AGENTS.md와 HUMAN.md 차이와 작성법

AGENTS.md란

AGENTS.md는 저장소 루트에 있는 일반 Markdown 파일입니다. 이 파일은 코딩 에이전트에게 해당 프로젝트에서 작업하는 방법을 설명합니다. 공식 사이트에서는 AGENTS.md를 "에이전트를 위한 README: AI 코딩 에이전트가 프로젝트에서 작업하는 데 필요한 컨텍스트와 지침을 제공하는 전용의 예측 가능한 위치"라고 설명합니다. 이 형식은 Linux Foundation 산하 Agentic AI Foundation에서 관리하며, 2026년 7월 기준으로 Codex, Cursor, Jules, Devin, GitHub Copilot을 비롯한 20개 이상의 에이전트가 이를 읽습니다.

이 규칙이 필요한 이유는 실용적입니다. 팀에 새로 합류한 사람은 README를 읽고 빌드 명령을 추측합니다. 추측이 틀리면 다른 사람에게 질문합니다. 에이전트는 질문할 수 없습니다. 에이전트는 pnpm test을 사용하는 프로젝트에서 npm test을 실행하고, 실패를 확인한 뒤 다른 방법을 시도합니다. 이러한 토큰마다 비용이 발생합니다. 실제 명령을 한 번 기록해 두면 이런 유형의 실패를 모두 방지할 수 있습니다.

필수 필드는 없습니다. 사이트에도 다음과 같이 명시되어 있습니다. "AGENTS.md는 일반 Markdown일 뿐입니다. 원하는 제목을 사용하면 됩니다. 에이전트는 제공된 텍스트를 그대로 구문 분석합니다." 이것이 전체 사양입니다. 중요한 것은 형식이 아닙니다. 모든 도구가 이미 확인하는 경로에 파일이 있다는 점이 중요합니다.

파일 위치와 우선 적용되는 파일

첫 번째 파일은 repository root에 배치합니다. monorepo에서는 각 subproject 안에 파일을 더 추가할 수 있습니다. 규칙은 간단합니다. "agents는 directory tree에서 가장 가까운 파일을 자동으로 읽으므로 가장 가까운 파일이 우선 적용됩니다." 두 파일의 내용이 충돌하면 편집 중인 파일에 더 가까운 파일이 적용됩니다. chat에 입력한 내용은 두 파일보다 우선합니다.

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

이 중첩 구조를 사용하는 것이 좋습니다. 한 폴더에서는 참이고 다음 폴더에서는 거짓인 내용을 지정하는 유일한 방법이기 때문입니다. "모든 endpoint는 입력을 검증합니다"와 같은 규칙은 endpoint 옆에 배치해야 합니다. root 파일에 배치하면 관련 없는 모든 task에서 로드되며 아무런 이점이 없습니다.

AGENTS.md에 포함할 내용

코드를 읽어도 에이전트가 알아낼 수 없는 내용을 기록합니다. 먼저 터미널에 붙여 넣을 수 있는 형식으로 정확한 빌드, 테스트 및 lint 명령을 제시합니다. 단일 테스트를 실행하는 명령도 추가합니다. 전체 테스트 모음만 실행할 줄 아는 에이전트는 전체 테스트를 40번 실행할 수 있습니다. 도구 기본값과 다른 규칙을 명시합니다. 에이전트는 기본값을 이미 알고 있으므로, 변경한 내용만 알리면 됩니다. 사용 중인 경우 commit message 형식과 pull request 규칙도 추가합니다.

주장을 확인할 수 있을 정도로 구체적으로 작성합니다. "2-space 들여쓰기를 사용합니다"는 실제로 지켜졌는지 확인할 수 있으므로 유효한 지침입니다. 반면 "코드를 적절히 포맷합니다"는 확인할 수 있는 내용이 없으므로 유효하지 않습니다. 위치도 마찬가지입니다. "API handler는 src/api/handlers/에 있습니다"는 "파일을 체계적으로 관리합니다"보다 유용합니다.

금지 규칙도 포함할 가치가 있습니다. "dist/ 아래의 파일은 편집하지 않습니다. npm run build이 해당 파일을 생성합니다"라고 하면 특정 실수를 방지할 수 있습니다. 원인을 함께 제시하므로, 에이전트는 문서에 명시되지 않은 동등한 경우에도 같은 규칙을 적용할 수 있습니다.

포함해서는 안 되는 내용

이러한 파일에는 비밀 정보를 절대 저장하지 않습니다. 파일은 git에 커밋되고, 모든 세션 시작 시 컨텍스트에 로드되며, 모든 요청마다 모델 제공업체로 전송됩니다. AGENTS.md에 API key를 저장하면 해당 API key가 저장소의 이력과 제3자의 로그에 남습니다. 비밀 정보를 직접 붙여 넣지 말고 위치만 지정합니다. "database password는 .env에 있으며 git에서 무시됩니다. 읽기 전에 요청하세요."라고 작성합니다. 이 원칙에 대한 자세한 내용은 에이전트가 자격 증명에 접근하지 못하게 하기에서 설명합니다.

에이전트가 확인만으로 파악할 수 있는 내용은 포함하지 않습니다. 디렉터리 목록을 붙여 넣거나, dependency 목록을 복사하거나, 폴더 이름을 다시 나열하는 architecture 개요를 작성하는 경우가 이에 해당합니다. 이러한 내용은 작성한 다음 주부터 오래된 정보가 되며, 그동안 모든 세션에서 컨텍스트를 차지합니다. 주의할 사항과 그 이유는 유지합니다. 목록은 삭제합니다.

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가 있다면 두 번째 사본을 유지하지 마십시오. AGENTS.md를 가져온 다음 Claude에만 해당하는 내용을 추가합니다.

@AGENTS.md

## Claude Code

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

추가할 내용이 없다면 symlink를 사용하면 됩니다.

ln -s AGENTS.md CLAUDE.md

성공하면 명령이 아무것도 출력하지 않습니다. 다음 세션에서 /context을 실행하고 Memory files 아래에 CLAUDE.md이 표시되는지 확인합니다. 목록에 없다면 파일이 로드되지 않은 것이므로 파일의 내용이 적용되지 않았습니다. 파일을 직접 작성하지 않고 초안을 생성하려면 /init을 실행합니다. 이 명령은 코드베이스를 읽고 시작 파일을 생성합니다. CLAUDE.md가 이미 있으면 덮어쓰지 않고 개선 사항을 제안합니다.

각 파일은 약 200줄 이하로 유지합니다. 파일이 길수록 window를 더 많이 사용하고 지침 준수율이 낮아집니다. 해당 공간을 차지하는 다른 요소를 확인하려면 에이전트의 context window를 실제로 채우는 요소에서 자세히 설명합니다.

한 가지는 강조할 필요가 있습니다. AGENTS.md는 지침일 뿐이며 권한 시스템이 아닙니다. 내용은 일반 context로 전달되므로 모델이 이를 읽고 대체로 따르지만, 지침에 위배되는 작업을 차단하지는 않습니다. "main에 절대 push하지 않음"처럼 매번 반드시 지켜야 하는 규칙에는 hook 또는 permission 설정을 사용합니다. 이러한 기능은 코드로 실행되며 모델이 따를지 여부에 의존하지 않기 때문입니다.

이러한 파일을 대신 작성하는 도구

2026년 7월 30일 GitHub trending 목록에 오른 2개의 프로젝트는 이러한 관례가 어떤 방향으로 나아가고 있는지 보여줍니다.

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개)는 이 패턴을 repository 대신 사람에게 적용합니다. 이 프로젝트는 HUMAN.md를 사용자가 직접 작성하는 파일이 아니라 시스템의 출력으로 설명합니다. 즉, “현재 중요한 사항, 결정을 내리는 일반적인 방식, 관심이 향하는 방향을 보여 주는 살아 있는 모델”입니다. 이 도구는 macOS 13 이상에서 로컬로 실행되며, macOS 권한을 부여하면 활동을 수집하고, MCP(model context protocol)를 통해 그 결과를 agent에 제공합니다. 간단한 설치 방법은 다음과 같습니다.

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

대부분의 이점을 얻기 위해 이 모든 기능이 필요한 것은 아닙니다. 직접 작성하는 HUMAN.md는 약 20줄이면 충분합니다. 역할, timezone, 실제로 사용하는 stack, 이미 내렸으며 다시 논의하고 싶지 않은 결정, 그리고 어느 정도의 설명을 원하는지를 적습니다. 프로젝트 파일이 반복적인 설명을 줄이는 것처럼, 이 파일은 한 단계 상위에서 같은 설명을 반복하는 일을 줄입니다.

한 가지 주의할 점이 있습니다. HUMAN.md는 사람의 profile이므로 본질적으로 민감한 정보입니다. public repository에 포함하지 마십시오. ~/.claude/CLAUDE.md에 저장하거나, 프로젝트 root의 gitignored CLAUDE.local.md에 저장하십시오. 후자의 파일은 commit된 파일과 함께 로드되며 동일한 방식으로 처리됩니다.

복사해서 사용할 수 있는 시작 템플릿

일부러 짧게 작성했습니다. 적용되지 않는 섹션은 삭제하고, 현재 상태로 유지할 수 없는 섹션은 추가하지 않습니다.

# 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.

작성한 후 제자리에서 수정합니다. 같은 수정 내용을 채팅에 두 번 입력했다면 해당 내용을 한 줄로 추가합니다. 이 규칙 하나만으로도 파일을 유용하게 유지할 수 있으며, 컴퓨터가 읽지 못하는 문서로 파일이 커지는 것도 막을 수 있습니다. 파일이 안정되면 저장소와 함께 이동합니다. 에이전트가 노트북이 아닌 다른 위치에서 실행될 때 특히 중요합니다. 자체 서버에서 coding agent 실행에서 해당 설정을 설명합니다.

FAQ

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

두 파일명으로 표현된 같은 개념입니다. Claude Code는 CLAUDE.md를 읽고, 연결하지 않는 한 AGENTS.md은 무시합니다. 하나의 파일을 기준 파일로 유지하고, CLAUDE.md 상단에 @AGENTS.md이라는 줄을 추가하거나 ln -s AGENTS.md CLAUDE.md을 사용하여 다른 파일을 연결합니다. 두 개의 전체 사본을 별도로 관리하면 한 달 안에 내용이 달라집니다.

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

아닙니다. 내용은 컨텍스트로 전달되므로 모델이 읽고 일반적으로 따르지만, 해당 내용에 위배되는 작업을 차단하지는 않습니다. 모호한 지침은 가장 안정적으로 따르지 않으며, 서로 반대되는 지침을 제공하는 두 파일이 있으면 에이전트가 임의로 하나를 선택합니다. 매번 반드시 적용해야 하는 규칙에는 hook 또는 permission rule을 사용합니다. 이러한 규칙은 모델의 결정과 관계없이 클라이언트가 강제합니다.

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

그렇습니다. 빌드 명령, 디렉터리 구조, 규칙 등 프로젝트에 대해 항상 유효한 내용이라면 커밋해야 합니다. 이 파일의 목적은 팀원의 에이전트도 사용자의 에이전트와 동일한 컨텍스트로 시작하도록 하는 것입니다. 개인적이거나 특정 시스템에만 해당하는 내용은 별도의 gitignored 파일에 저장하고, 자격 증명은 어느 파일에도 저장하지 않습니다.

HUMAN.md란 무엇이며, 반드시 필요합니까?

HUMAN.md는 프로젝트가 아니라 사람의 정보를 기계가 읽을 수 있는 형식으로 기록하는 프로필입니다. 여기에는 사용자의 역할, 제약 조건, 이미 결정한 사항을 기록하여 매 세션마다 다시 논의하지 않도록 합니다. 시작하는 데 별도의 도구는 필요하지 않습니다. 사용자 수준 지침 파일에 직접 작성한 20줄만으로도 대부분의 이점을 얻을 수 있습니다. 이를 개인 데이터로 취급하고 push하는 어떤 repository에도 포함하지 않습니다.