AGENTS.md 작성법과 AI 코딩 에이전트 활용 가이드

AGENTS.md란 무엇인가

AGENTS.md는 저장소 루트에 위치한 일반 마크다운 파일로, 코딩 에이전트가 해당 프로젝트에서 작업하는 방법을 안내합니다. 공식 사이트에서는 이를 "에이전트를 위한 README: AI 코딩 에이전트가 프로젝트에서 작업할 수 있도록 맥락과 지침을 제공하는 전용의 예측 가능한 공간"이라고 설명합니다. 이 형식은 Linux Foundation 산하의 Agentic AI Foundation에서 관리하며, 2026년 7월 기준으로 Codex, Cursor, Jules, Devin, GitHub Copilot 등 20개 이상의 에이전트가 이 파일을 읽습니다.

이 관례가 존재하는 이유는 실용적입니다. 팀에 새로 합류한 사람은 README를 읽고 빌드 명령어를 추측하며, 추측이 틀리면 동료에게 질문합니다. 하지만 에이전트는 질문할 수 없습니다. 에이전트는 추측하여 npm test를 pnpm test을 사용하는 프로젝트에서 실행하고, 실패를 읽은 뒤 다른 방법을 시도합니다. 사용자는 그 모든 토큰에 대해 비용을 지불해야 합니다. 올바른 명령어를 한 번 기록해 두는 것만으로도 이러한 유형의 모든 실패를 제거할 수 있습니다.

필수 항목은 없습니다. 사이트에서는 "AGENTS.md는 표준 마크다운일 뿐입니다. 원하는 제목을 사용하십시오. 에이전트는 제공된 텍스트를 파싱할 뿐입니다."라고 명확히 밝히고 있습니다. 이것이 사양의 전부입니다. 이 파일의 가치는 형식에 있는 것이 아니라, 모든 도구가 이미 확인하고 있는 경로에 파일이 존재한다는 점에 있습니다.

파일 위치와 우선순위 결정 방식

첫 번째 파일은 저장소 루트에 배치합니다. 모노레포 환경이라면 각 하위 프로젝트 내부에 파일을 추가할 수 있으며, 규칙은 간단합니다. "에이전트는 디렉터리 트리에서 가장 가까운 파일을 자동으로 읽으므로, 가장 근접한 파일이 우선권을 갖습니다." 두 파일 간에 충돌이 발생하면 편집 중인 파일이 우선하며, 채팅창에 직접 입력한 내용은 두 파일 모두의 설정보다 우선합니다.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

중첩 구조를 사용하는 것이 좋습니다. 특정 폴더에서는 참이지만 다른 폴더에서는 거짓인 규칙을 정의할 수 있는 유일한 방법이기 때문입니다. "모든 엔드포인트는 입력을 검증한다"와 같은 규칙은 엔드포인트 옆에 위치해야 합니다. 루트 파일에 두면 관련 없는 모든 작업에서 로드되므로 아무런 이점이 없습니다. 루트 파일이 이미 서비스별 섹션으로 비대해졌다면, 중첩 구조로 분할하는 것이 해결책입니다. 이 과정에서 어떤 규칙을 하위로 이동시키고 어떤 규칙을 상단에 유지할지 결정하게 됩니다.

AGENTS.md에 포함해야 할 내용

코드를 읽는 것만으로는 에이전트가 파악할 수 없는 정보를 기록하십시오. 터미널에 그대로 붙여넣을 수 있는 형태의 정확한 빌드, 테스트, 린트 명령어를 가장 먼저 작성하십시오. 전체 테스트 스위트를 실행하는 방법만 아는 에이전트는 매번 전체를 40번씩 실행할 것이므로, 단일 테스트를 실행하는 명령어도 추가하십시오. 도구의 기본값과 다른 관례가 있다면 명시하십시오. 에이전트는 이미 기본값을 알고 있으므로, 여러분이 설정한 예외 사항만 알면 됩니다. 커밋 메시지 형식과 풀 리퀘스트 규칙이 있다면 이 또한 추가하십시오.

주장이 검증 가능할 정도로 구체적으로 작성하십시오. "2칸 들여쓰기를 사용하십시오"는 적용 여부를 확인할 수 있으므로 유용한 지침입니다. 반면 "코드를 적절하게 포맷하십시오"는 검증할 수 있는 기준이 없으므로 부적절합니다. 파일 위치도 마찬가지입니다. "API 핸들러는 src/api/handlers/에 위치합니다"가 "파일을 체계적으로 유지하십시오"보다 훨씬 효과적입니다.

부정적인 규칙도 명시할 가치가 있습니다. "dist/ 하위의 파일은 npm run build에 의해 생성되므로 절대 수정하지 마십시오"와 같은 규칙은 특정 실수를 방지합니다. 또한 원인을 명시함으로써, 여러분이 직접 적지 않은 유사한 상황에서도 에이전트가 스스로 판단할 수 있게 합니다. 범위에 관한 규칙도 여기에 포함해야 합니다. 에이전트에게 판단을 맡기면 요청한 것보다 더 많은 부분을 수정하려 하기 때문입니다. 널리 복제된 한 가지 기술은 작동하는 최소한의 변경만을 고집하는 것입니다.

포함해서는 안 되는 내용

이러한 파일에 비밀 정보를 절대 넣지 마십시오. 해당 파일은 git에 커밋되고, 모든 세션 시작 시 컨텍스트로 로드되며, 요청마다 모델 제공자에게 전송됩니다. AGENTS.md에 포함된 API key는 저장소 기록과 제3자의 로그에 그대로 남게 됩니다. 비밀 정보를 직접 붙여넣는 대신 참조하십시오. 예: "데이터베이스 비밀번호는 gitignore 처리된 .env에 있습니다. 읽기 전에 먼저 확인하십시오." 이와 관련된 더 넓은 범위의 원칙은 자격 증명을 에이전트의 접근 범위 밖으로 유지하기에서 다룹니다.

에이전트가 직접 확인하여 유추할 수 있는 내용은 생략하십시오. 붙여넣은 디렉터리 목록, 의존성 목록 사본, 폴더 이름을 나열한 아키텍처 개요 등은 작성한 지 일주일만 지나도 구식이 되며, 그동안 모든 세션에서 컨텍스트 비용을 소모합니다. 주의 사항과 그 이유는 유지하되, 단순 목록은 제거하십시오. 이유를 별도로 분리하는 것은 중요합니다. 왜 특이한 구조가 존재하는지 알지 못하는 에이전트는 이를 조용히 리팩터링하여 없애버릴 수 있기 때문이며, 이것이 바로 이 파일 옆에 DESIGN.md를 두는 것이 필요한 이유입니다.

CLAUDE.md는 동일한 개념의 Claude Code 인스턴스입니다.

Claude Code는 CLAUDE.md를 읽으며 AGENTS.md은 스스로 읽지 않습니다. 프로젝트 파일은 ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 위치하며, 모든 프로젝트에 적용되는 개인 설정은 ~/.claude/CLAUDE.md에 저장합니다. 조직 차원에서는 Linux의 /etc/claude-code/CLAUDE.md에 시스템 전체 적용 파일을 배포할 수 있습니다. 발견된 파일들은 파일 시스템 루트에서 작업 디렉터리까지 순차적으로 결합되므로, 세션을 시작한 위치와 가장 가까운 파일이 마지막에 읽힙니다. 해당 디렉터리에서 시작하는 모든 세션은 동일한 스택을 로드하며, 이 덕분에 한 대의 머신에서 두 개의 세션을 나란히 실행하는 것이 가능하고 실행 중인 세션끼리 작업을 주고받을 수 있습니다.

저장소에 이미 AGENTS.md가 있다면 두 번째 복사본을 유지하지 마십시오. 이를 가져온 뒤 Claude 전용 내용만 추가하십시오.

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

추가할 내용이 없다면 심볼릭 링크를 사용하십시오.

ln -s AGENTS.md CLAUDE.md

명령이 성공하면 아무것도 출력되지 않습니다. 다음 세션에서 /context을 실행하고 Memory files 아래에 CLAUDE.md가 나타나는지 확인하십시오. 해당 목록에 없다면 파일이 로드되지 않은 것이며, 따라서 내부 설정도 적용되지 않습니다. 초안을 직접 작성하는 대신 생성하려면 /init을 실행하십시오. 이 명령은 코드베이스를 읽어 시작 파일을 생성하며, 이미 CLAUDE.md가 존재할 경우 덮어쓰는 대신 개선 사항을 제안합니다.

각 파일은 약 200줄 미만으로 유지하십시오. 파일이 길어지면 컨텍스트 윈도우를 더 많이 차지하게 되어 준수율이 떨어집니다. 해당 공간을 차지하는 다른 요소가 궁금하다면 에이전트의 컨텍스트 윈도우를 실제로 채우는 요소를 참조하여 세부 내용을 확인하십시오.

한 가지 강조할 점이 있습니다. AGENTS.md는 지침일 뿐 권한 시스템이 아닙니다. 내용은 일반적인 컨텍스트로 전달되므로 모델이 이를 읽고 보통은 따르지만, 지침에 반하는 동작을 기술적으로 막지는 못합니다. 작성한 규칙이 조용히 무시되고 이유를 알 수 없다면, 문구를 세 번째로 다시 쓰기 전에 지침이 누락되는 이유를 먼저 검토하십시오. "절대로 main 브랜치에 푸시하지 마라"와 같이 매번 반드시 지켜져야 하는 규칙은 훅(hook)이나 권한 설정을 사용하십시오. 이는 코드로 실행되므로 모델의 판단에 의존하지 않기 때문입니다.

이러한 파일을 자동으로 생성하는 도구

2026년 7월 30일 GitHub 트렌딩 목록에 오른 두 프로젝트는 현재 관례가 어떤 방향으로 나아가고 있는지 보여줍니다.

agent0ai/dox(2026년 7월 기준 별 1,368개)은 AGENTS.md 파일 트리를 최신 상태로 유지하기 위한 프레임워크입니다. 이 프로젝트는 별도의 패키지나 런타임을 제공하지 않습니다. 사용자가 해당 프로젝트의 AGENTS.md 내용을 자신의 루트 AGENTS.md에 복사하는 것이 설치의 전부입니다. 이미 존재하는 프로젝트의 경우, 에이전트에게 다음과 같이 지시합니다.

Initialize DOX tree for this project now.

그러면 에이전트가 하위 AGENTS.md 파일과 인덱스를 생성하고, 편집을 수행하기 전에 해당 트리를 탐색하며, 변경 사항이 적용된 후 관련 문서를 업데이트합니다. 이 방식의 핵심은 에이전트가 작업의 부수 효과로 유지 관리하는 문서는 정확하게 유지되는 반면, 사람이 직접 수정하는 문서는 그렇지 못할 가능성이 높다는 점에 있습니다.

HUMAN.md, 당신을 대상으로 하는 동일한 기법

Intuition-Lab/personal-model(2026년 7월 기준 1,260개의 별)는 이 패턴을 저장소가 아닌 사람에게 적용합니다. 이 프로젝트는 HUMAN.md를 직접 작성하는 파일이 아니라 시스템의 출력물로 정의합니다. 즉, "현재 무엇이 중요한지, 어떻게 의사결정을 내리는 경향이 있는지, 어디에 주의를 기울이고 있는지에 대한 살아있는 모델"입니다. 이 도구는 macOS 13 이상에서 로컬로 실행되며, macOS 권한을 부여받은 후 활동을 캡처하여 MCP(Model Context Protocol)를 통해 에이전트에 결과를 노출합니다. 짧은 설치 경로는 다음과 같습니다.

uv tool install personal-model
persome onboard
persome model open --after 30

대부분의 이점을 누리기 위해 이러한 도구가 반드시 필요한 것은 아닙니다. 직접 작성한 HUMAN.md는 약 20줄 정도로 구성됩니다. 여기에는 본인의 역할, 시간대, 실제로 사용하는 스택, 이미 내려진 결정으로서 다시 논의하고 싶지 않은 사항, 그리고 답변 시 원하는 설명의 수준 등이 포함됩니다. 이는 프로젝트 파일이 절약해 주는 반복적인 설명을 한 단계 더 높은 수준에서 동일하게 절약해 줍니다.

한 가지 주의할 점이 있습니다. HUMAN.md는 개인의 프로필이므로 정의상 민감한 정보를 담고 있습니다. 공개 저장소에는 올리지 마십시오. ~/.claude/CLAUDE.md에 보관하거나, 프로젝트 루트의 gitignore 처리된 CLAUDE.local.md에 두십시오. 이렇게 하면 커밋된 파일과 함께 로드되며 동일한 방식으로 처리됩니다.

복사하여 사용할 수 있는 시작 템플릿

이 내용은 의도적으로 짧게 작성되었습니다. 적용되지 않는 섹션은 삭제하고, 최신 상태로 유지할 수 없는 섹션은 추가하지 마십시오.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

내용을 작성한 뒤, 그 자리에서 수정하십시오. 동일한 수정 사항을 채팅창에 두 번 입력했다면, 그것이 바로 줄을 추가해야 한다는 신호입니다. 이 규칙 하나만으로도 파일의 유용성이 유지되며, 기계와 사람 모두 읽지 않는 문서로 비대해지는 것을 방지할 수 있습니다. 파일이 안정화되면 저장소와 함께 이동합니다. 이는 에이전트가 본인의 노트북이 아닌 다른 곳에서 실행될 때 가장 중요합니다. 자체 서버에서 코딩 에이전트 실행하기에서 해당 설정을 다룹니다.

FAQ

AGENTS.md와 CLAUDE.md는 같은 파일입니까?

두 파일은 이름만 다를 뿐 같은 개념입니다. Claude Code는 CLAUDE.md를 읽으며, 연결하지 않는 한 AGENTS.md은 무시합니다. 한 파일을 단일 진실 공급원(source of truth)으로 유지하고 다른 파일을 연결하십시오. CLAUDE.md 상단에 @AGENTS.md이라고 적거나 ln -s AGENTS.md CLAUDE.md을 사용하여 연결할 수 있습니다. 두 개의 전체 복사본을 별도로 관리하면 한 달 안에 내용이 서로 달라지게 됩니다.

AGENTS.md를 작성하면 에이전트가 이를 반드시 따릅니까?

아닙니다. 내용은 컨텍스트로 전달되므로 모델이 이를 읽고 대체로 준수하지만, 이에 반하는 동작을 강제로 막을 수는 없습니다. 모호한 지침은 가장 신뢰도가 낮게 이행되며, 두 파일이 상반된 지침을 제공하면 에이전트는 임의로 하나를 선택하게 됩니다. 매번 반드시 지켜야 하는 규칙이라면 훅(hook)이나 권한 규칙을 사용하십시오. 이는 모델의 판단과 관계없이 클라이언트가 강제로 적용합니다.

AGENTS.md를 git에 커밋해야 합니까?

네, 빌드 명령어, 레이아웃, 관례 등 프로젝트에 관한 사실이라면 커밋해야 합니다. 이것이 이 파일의 존재 이유이며, 그래야 팀원들의 에이전트도 본인의 에이전트와 동일한 컨텍스트로 시작할 수 있습니다. 개인적이거나 특정 장비에 종속된 내용은 gitignore 처리된 별도의 파일에 보관하고, 자격 증명(credentials)은 어느 파일에도 포함해서는 안 됩니다.

HUMAN.md는 무엇이며 꼭 필요한가요?

HUMAN.md는 프로젝트가 아닌 사람에 대한 기계 판독 가능한 프로필입니다. 여기에는 사용자의 역할, 제약 사항, 이미 결정된 사항이 포함되어 매 세션마다 같은 논의를 반복하지 않게 해줍니다. 시작하기 위해 별도의 도구는 필요하지 않습니다. 사용자 수준의 지침 파일에 20줄 정도 직접 작성하는 것만으로도 대부분의 가치를 얻을 수 있습니다. 이를 개인 데이터로 취급하고, 푸시하는 어떤 저장소에도 포함하지 마십시오.