코딩 에이전트(coding agent)가 당신의 저장소(repository)를 열고 다음과 같이 간단해 보이는 작업을 받습니다:

계정 설정 엔드포인트(endpoint)에 유효성 검사(validation)를 추가하세요.

해당 저장소에는 이미 유효성 검사 라이브러리, 공유 에러 형식, 테스트 헬퍼(test helper), 그리고 생성된 API 클라이언트는 절대 수동으로 편집해서는 안 된다는 규칙이 존재합니다.

이 프로젝트에서 작업해 온 개발자라면 이 모든 것을 알고 있습니다. 하지만 코딩 에이전트는 정보를 빠르게 찾아낼 수 없다면 이를 알지 못합니다.

에이전트는 저장소를 조사하여 모든 것을 스스로 파악할 수도 있습니다. 하지만 가장 빠른 길처럼 보이는 방식을 택하느라 두 번째 유효성 검사 라이브러리를 설치하거나, 새로운 형식으로 에러를 반환하거나, 기존 헬퍼를 중복 생성하거나, 생성된 파일을 직접 수정해 버릴 수도 있습니다.

문제는 반드시 모델(model)이나 프롬프트(prompt) 때문만은 아닙니다. 저장소에 운영 가이드(operating guide)가 없기 때문입니다.

그것이 바로 AGENTS.md의 역할입니다.

요약하자면: README는 프로젝트를 설명합니다. AGENTS.md는 프로젝트를 안전하게 변경하는 방법을 설명합니다.

목차

• AGENTS.md란 무엇인가?
• README와 AGENTS.md는 서로 다른 문제를 해결한다
• 유용한 첫 번째 버전 만들기
• 검증 가능한 지침 작성하기
• 명령어, 경계(boundaries), 그리고 완료 정의(definition of done) 추가하기
• 모노레포(monorepos)에서 중첩된 파일 사용하기
• 흔한 실수 피하기
• 스타터 템플릿 복사하기
• 실제 작업으로 파일 테스트하기

AGENTS.md란 무엇인가?

AGENTS.md는 코딩 에이전트에게 프로젝트 특화 지침을 제공하는 일반 마크다운(Markdown) 파일입니다. 오픈 포맷(open format)에서는 이를 에이전트를 위한 README라고 설명합니다. 즉, 설정 명령어, 테스트 지침, 컨벤션(conventions), 그리고 에이전트가 저장소 내에서 작업하는 데 도움이 되는 기타 컨텍스트(context)를 담는 예측 가능한 장소입니다.

이 형식은 의도적으로 단순하게 설계되었습니다. 필수적인 스키마(schema)나 특별한 설정 언어(configuration language)가 없습니다. 프로젝트 루트에 파일 하나를 배치할 수 있으며, 저장소의 서로 다른 부분에 서로 다른 지침이 필요한 경우 하위 디렉터리에 더 구체적인 파일들을 추가할 수 있습니다.

이러한 변화가 유용해지고 있는 이유는 코딩 에이전트 (coding agents)가 자동 완성 (autocomplete) 수준을 넘어서고 있기 때문입니다. 에이전트는 저장소를 조사하고, 여러 파일을 수정하며, 명령어를 실행하고, 테스트를 수행하며, 풀 리퀘스트 (pull requests)를 준비할 수 있습니다. GitHub는 2025년 8월, 프로젝트의 특정 영역을 위한 중첩된 파일들을 포함하여 자신의 Copilot 코딩 에이전트에 AGENTS.md 지원을 추가했습니다. OpenAI Codex 또한 저장소 루트에서 현재 작업 디렉터리로 향하며 프로젝트 지침을 발견하는 계층 구조를 문서화하고 있습니다.

다시 말해, 저장소 지침 (repository instructions)이 개발 환경의 일부가 되고 있습니다.

README.md와 AGENTS.md는 서로 다른 문제를 해결합니다

좋은 README는 사람이 프로젝트가 자신과 관련이 있는지, 그리고 어떻게 사용을 시작할지를 결정하는 데 도움을 줍니다. 일반적으로 다음과 같은 내용을 포함합니다:

• 프로젝트의 목적,
• 설치 지침 (installation instructions),
• 짧은 사용 예시,
• 문서 (documentation) 링크,
• 기여 (contribution) 정보.

에이전트도 이러한 정보 중 일부가 필요하지만, README를 복잡하게 만들 수 있는 운영 세부 사항 (operational detail)도 필요로 합니다:

• 특정 테스트를 위한 정확한 명령어,
• 생성된 코드 (generated code)가 포함된 디렉터리,
• 아키텍처 경계 (architectural boundaries),
• 선호되는 패키지 매니저 (package manager),
• 특별한 검토가 필요한 파일,
• 절대로 자동으로 실행되어서는 안 되는 작업,
• 완료된 변경 사항의 정의.

AGENTS.md는 README를 대체하는 것이 아니라 보완합니다.

간단한 구분법이 효과적입니다:

README는 프로젝트를 설명합니다. AGENTS.md는 프로젝트를 안전하게 변경하는 방법을 설명합니다.

첫 번째 버전은 작아야 합니다

유용한 경험칙 (rule of thumb)

에이전트가 틀릴 가능성이 가장 높은 지침부터 시작하세요. 실제 작업 중에 누락된 컨텍스트 (context)가 드러날 때만 더 추가하십시오.

지침 파일을 두 번째 문서 사이트로 만들기 쉽습니다. 이는 대개 유용성을 떨어뜨립니다.

에이전트가 틀릴 가능성이 가장 높은 사실부터 시작하십시오.

다음은 TypeScript 서비스에 대한 간결한 예시입니다:

전체 최소 AGENTS.md 예시 열기

# AGENTS.md

## Repository map
...

이 파일은 짧지만, 그렇지 않으면 저장소 탐색이나 추측이 필요한 여러 질문에 답을 제공합니다.

이 파일은 에이전트에게 코드가 어디에 속해야 하는지, 어떤 명령어를 사용해야 하는지, 어떤 패턴이 이미 존재하는지, 무엇을 수정하면 안 되는지, 그리고 결과를 어떻게 검증하는지를 알려줍니다.

검증 가능한 지침 작성하기

취약한 지침은 증거를 정의하지 않은 채 선호도만을 표현합니다:

# 너무 모호함
클린 코드 (clean code)를 작성하세요.
베스트 프랙티스 (best practices)를 따르세요.
...

이러한 문구들은 합리적으로 들리지만, 두 명의 개발자가 이를 서로 다르게 해석할 수 있습니다. 에이전트는 추측할 여지가 훨씬 더 많습니다.

저장소 상태나 실행 가능한 검증(executable checks)과 연결된 지침을 선호하세요:

# 구체적이고 검증 가능함
라우트 핸들러 (route handlers)를 요청 파싱 (request parsing) 및 응답 매핑 (response mapping)으로 제한하세요.
비즈니스 규칙 (business rules)을 src/domain에 배치하세요.
...

유용한 지침은 적어도 다음 질문 중 하나에 답해야 합니다:

• 작업 (Action): 무엇을 해야 하는가?
• 범위 (Scope): 규칙이 어디에 적용되는가?
• 증거 (Evidence): 준수 여부를 어떻게 검증할 수 있는가?

"출력을 보기 좋게 포맷팅하세요"보다는 "기존 포맷터 (formatter)를 사용하세요"가 더 낫습니다. "파싱이 여전히 작동하는지 확인하세요"보다는 "파서 테스트 (parser tests)를 실행하세요"가 더 낫습니다.

설명보다 명령어를 먼저 배치하기

에이전트가 작은 변경 사항을 검증해야 할 때, 테스트 철학에 대한 긴 문단보다 정확한 명령어가 더 유용합니다.

명확하게 명시된 디렉토리에서 작동하는 것으로 알려진 명령어를 포함하세요:

## 명령어 (Commands)

이 명령어들을 저장소 루트 (repository root)에서 실행하세요.
...

package.json의 모든 스크립트를 복사하는 것은 피하세요. 일반적인 워크플로우 (workflow)를 정의하는 명령어와 특이한 순서 요구 사항이 있는 명령어를 강조하세요.

테스트에 서비스나 환경 변수 (environment variable)가 필요한 경우, 이를 명시하세요:

- 통합 테스트 (Integration tests)에는 `compose.yaml`의 PostgreSQL이 필요합니다.
- `docker compose up -d postgres`로 시작하세요.
- `.env.example`을 `.env.test`로 복사하세요. `.env.production`은 절대 읽거나 수정하지 마세요.

목표는 에이전트에게 더 넓은 권한을 주는 것이 아닙니다. 에이전트가 이미 가지고 있는 권한에서 모호함을 제거하는 것입니다.

모든 구현 세부 사항이 아닌 경계(boundaries)를 설명하세요

아키텍처 가이드는 그럴듯한 실수(plausible mistakes)를 방지할 수 있을 때 가치가 있습니다.

어떤 프로젝트에 다음과 같이 세 개의 레이어가 있다고 가정해 봅시다:

API -> application -> data

에이전트는 API 핸들러(handler)에서 데이터베이스를 직접 호출함으로써 기능을 완성할 수도 있습니다. 그 결과물은 작동할 수는 있겠지만, 아키텍처를 위반하게 됩니다.

짧은 경계 설정만으로도 충분합니다:

## 아키텍처 경계 (Architecture boundaries)

- API 핸들러는 리포지토리(repositories)가 아닌 애플리케이션 서비스(application services)를 호출해야 합니다.
...

모든 클래스(class)와 함수(function)를 설명하려고 시도하지 마세요. 설명이 이미 존재한다면 아키텍처 문서로 링크를 연결하세요.

AGENTS.md는 코드베이스의 복제본이 아니라, 지도(map)이자 가드레일(guardrails) 역할을 해야 합니다.

에이전트가 작업하지 말아야 할 곳을 알려주세요

제한 사항(Restrictions)은 종종 스타일 선호도보다 더 가치 있습니다.

유용한 예시는 다음과 같습니다:

## 제한 구역 (Restricted areas)

- `src/generated` 하위의 생성된 파일(generated files)은 편집하지 마세요.
...

이러한 경계는 실제 프로젝트 정책을 반영해야 합니다. 리포지토리에 필요하지 않은 과도한 제한 사항을 추가하면 중요한 규칙을 찾기가 더 어려워집니다.

또한, 지침 파일(instruction file)은 가이드일 뿐 보안 경계(security boundary)가 아니라는 점을 기억하세요. 액세스 제어(Access controls), 격리된 실행(isolated execution), 브랜치 보호(branch protection), 필수 리뷰(required reviews), 그리고 비밀 관리(secret management)가 여전히 중요한 규칙들을 강제해야 합니다.

리포지토리가 정말로 서로 다른 영역을 가지고 있다면 중첩된 파일(nested files)을 사용하세요

모노레포(monorepo)에는 프론트엔드(frontend), API, 인프라 코드(infrastructure code), 그리고 모바일 애플리케이션이 포함될 수 있습니다. 하나의 루트(root) 파일은 공유된 기대 사항을 설명할 수 있고, 중첩된 파일들은 로컬 세부 사항을 제공할 수 있습니다.

repository/
├── AGENTS.md
├── apps/
...

루트 파일은 공유 규칙을 정의할 수 있습니다:

# 리포지토리 전역 지침 (Repository-wide instructions)

- 모든 JavaScript 워크스페이스(workspaces)에는 `pnpm`을 사용하세요.
...

그다음 웹 애플리케이션은 로컬 지침을 추가할 수 있습니다:

# 웹 애플리케이션 지침 (Web application instructions)

- 새로운 컴포넌트를 만들기 전에 `packages/design-system`에 있는 기존 컴포넌트를 사용하세요.
...

API는 다른 워크플로(workflow)를 정의할 수 있습니다:

# API 지침 (API instructions)

- 컨트롤러(controllers)는 전송 관련 관심사(transport concerns)로만 제한하세요.
...

지침(instructions)이 진정으로 다를 때만 중첩된 파일(Nested files)이 유용합니다. 모든 디렉토리에 파일을 생성하면 유지보수가 더 어려워지고 모순이 발생할 수 있습니다.

완료 정의(Definition of done)를 포함하세요

에이전트(Agents)는 패치(patch)를 생성하고 완료를 알리는 데 능숙합니다. 여러분의 저장소(repository)는 완료가 무엇을 의미하는지 정의해야 합니다.

예시:

## 완료 정의 (Definition of done)

작업을 완료된 것으로 보고하기 전에:
...

필수 체크(check)가 실행되지 않았다면 해당 작업은 완전히 검증된 것이 아닙니다. 완료 보고서(completion report)는 이를 명확히 보여주어야 합니다.

명령어를 사용할 수 없었거나, 시간 초과(timed out)되었거나, 실행 중이지 않은 서비스가 필요했던 경우, 에이전트는 체크가 통과되었다고 암시해서는 안 됩니다. 유용한 완료 보고서는 완료된 작업, 성공적인 검증, 그리고 남아있는 불확실성을 분리하여 보여줍니다.

보안 가이드를 구체적으로 유지하세요

"보안을 준수하라"와 같은 일반적인 지침은 행동을 변화시키기에 너무 광범위합니다.

민감한 영역과 필수 체크 항목을 명시하세요:

## 보안 민감 변경 사항 (Security-sensitive changes)

- 인증(Authentication) 및 인가(authorization) 변경은 사람의 검토가 필요합니다.
...

지침 파일은 영향력이 큰 작업(high-impact actions) 또한 명시적으로 작성해야 합니다:

## 승인이 필요한 작업 (Actions requiring approval)

다음 사항에 대해 먼저 문의하세요:
...

코딩 에이전트가 셸(shells), 외부 도구(external tools), 비동기 워크플로(asynchronous workflows)에 대한 접근 권한을 얻게 됨에 따라 이는 특히 중요합니다.

흔한 실수들

⚠️ README 전체를 복사하는 것

중복은 서로 내용이 달라지는 두 개의 문서를 만듭니다. 기존 문서에 링크를 걸고, 에이전트의 행동에 영향을 미치는 지침만 유지하세요.

⚠️ 에세이를 쓰는 것

긴 배경 설명 섹션은 의사결정을 유도하지 못한 채 주의력(attention)만 소모합니다. 필수 명령어, 경계(boundaries), 검증 단계(validation steps)를 상단에 배치하세요.

⚠️ 모호한 규칙을 사용하는 것

컨벤션(conventions)이 명시되거나 링크되지 않았다면 "우리의 컨벤션을 따르세요"라는 말은 유용하지 않습니다.

⚠️ 아무도 실행하지 않는 명령어를 나열하는 것

잘못된 명령어는 명령어가 없는 것보다 더 나쁩니다. 잘못된 자신감(false confidence)을 심어주기 때문입니다. 깨끗한 체크아웃(clean checkout) 상태에서 지침을 테스트하세요.

⚠️ 선호도(preferences)와 필수 요구 사항(hard requirements)을 혼합하는 것

그 차이를 명확히 하세요. “기존 헬퍼(helpers)를 선호할 것”과 “생성된 파일은 절대 수정하지 말 것”은 동일한 비중을 갖지 않습니다.

⚠️ 지침이 권한을 강제한다고 가정하는 것

그렇지 않습니다. 비밀 정보(secrets), 보호된 브랜치(protected branches), 배포 권한(deployment access), 그리고 파괴적인 작업(destructive operations)에는 기술적 제어(technical controls)를 사용하세요.

⚠️ 파일을 업데이트하는 것을 잊는 것

CI 명령, 디렉토리 구조, 또는 아키텍처가 변경되면, 동일한 풀 리퀘스트(pull request)에서 AGENTS.md를 업데이트하세요.

실용적인 시작 템플릿

다음 템플릿은 의도적으로 간결하게 작성되었습니다. 적용되지 않는 섹션은 삭제하고, 모든 플레이스홀더(placeholder)를 저장소(repository)별 정보로 교체하세요.

AGENTS.md 시작 템플릿 전체 복사

# AGENTS.md

## 프로젝트 개요 (Project overview)
...

플레이스홀더를 변경하지 않은 채로 게시하지 마세요. 추측이 담긴 포괄적인 템플릿보다는 실제 명령어가 포함된 짧은 파일이 더 낫습니다.

실제 작업을 통해 지침을 테스트하세요

AGENTS.md를 한 번 읽고 완료되었다고 선언함으로써 평가하지 마세요.

에이전트에게 작고 대표적인 작업을 부여하고 어떤 일이 일어나는지 관찰하세요:

• 올바른 패키지 매니저(package manager)를 사용했는가?
• 집중된 테스트 명령어를 찾아냈는가?
• 아키텍처 경계(architectural boundaries)를 준수했는가?
• 생성된 파일(generated files)을 피했는가?
• 의존성(dependency)을 추가하기 전에 물어보았는가?
• 실패했거나 사용할 수 없는 체크를 정직하게 보고했는가?

에이전트가 합리적이지만 잘못된 선택을 했을 때, 저장소에 유용한 컨텍스트(context)가 누락되었는지 결정하세요. 만약 그렇다면, 하나의 정확한 지침을 추가하세요.

이 방식은 발생 가능한 모든 실수를 미리 예측하려고 시도하는 것보다 더 나은 파일을 만들어냅니다.

이것이 지금 중요한 이유

GitHub의 2025 Octoverse 보고서는 생성형 AI(generative AI)를 개발의 표준 구성 요소로 설명했으며, AI 관련 저장소와 에이전트 보조 워크플로우(agent-assisted workflows)의 강력한 성장을 보고했습니다. 동시에, 도구들은 단계별 감독을 덜 받으면서도 더 큰 작업을 처리할 수 있는 능력을 갖추고 있습니다.

그것은 저장소 컨텍스트(repository context)를 덜 중요하게 만드는 것이 아니라, 오히려 더 중요하게 만듭니다.

더 나은 모델은 코드로부터 더 많은 것을 추론할 수 있지만, 기록되지 않은 팀의 결정 사항까지 알 수는 없습니다. 모델은 우연히 발생한 패턴과 의도된 컨벤션 (convention)을 확실하게 구분할 수 없습니다. 저장소(repository)가 해당 정보를 발견 가능하게(discoverable) 만들지 않는 한, 모델은 마이그레이션 (migration)이 중단되었는지, 특정 헬퍼 (helper) 사용이 권장되는지, 혹은 특정 명령어가 금지되어 있는지 알 수 없습니다.

AGENTS.md는 마법 같은 프롬프트 (prompt)가 아니며, 생성된 모든 패치 (patch)를 올바르게 만들어주지도 않습니다.

이것은 저장소와 그 안에서 작업하는 에이전트 (agents) 사이의 작고 유지보수 가능한 계약 (contract)입니다.

실제로 작동하는 명령어부터 시작하세요. 실제로 중요한 경계 (boundaries)를 추가하세요. "완료 (done)"가 무엇을 의미하는지 정의하세요. 그런 다음 실제 작업 중에 누락된 컨텍스트 (context)가 드러나면 파일을 개선해 나가면 됩니다.

요점 (The takeaway)

여러분의 다음 코딩 에이전트 (coding agent)에게 프로젝트의 전체 히스토리가 필요한 것은 아닙니다.