코덱스 툴 사용법 23: AGENTS.md는 저장소의 작업 계약서다 | DAKER 커뮤니티

코덱스 툴 사용법 23: AGENTS.md는 저장소의 작업 계약서다

Codex에게 매번 같은 말을 하고 있다면 프롬프트가 아니라 작업 계약이 없는 것입니다. “테스트는 이 명령으로 돌려”, “이 디렉토리는 건드리지 마”, “게시 전 공개 API까지 확인해” 같은 규칙은 대화창에 반복해서 붙여 넣을 내용이 아닙니다. 저장소 안에 남겨야 합니다.

OpenAI Codex 공식 문서 기준으로 AGENTS.md는 Codex가 작업 전에 읽는 프로젝트 지침 파일입니다. 전역 지침, 저장소 지침, 하위 디렉토리 지침을 계층으로 읽고, 더 가까운 디렉토리의 지침이 나중에 붙습니다. Best practices 문서도 AGENTS.md를 agent를 위한 open-format README로 설명하며, repo 구조, 실행 명령, 테스트와 린트, 리뷰 기대치, 금지 규칙, 완료 기준을 담으라고 권합니다.

그래서 실무 기준은 간단합니다. 한 번만 필요한 요청은 프롬프트에 두고, 반복되는 저장소 규칙은 AGENTS.md에 둡니다. 반복 절차와 보조 자료가 필요하면 Skill로 분리합니다.

한 줄 요약

AGENTS.md는 Codex에게 “이 저장소에서 일할 때 항상 지켜야 할 방식”을 알려주는 작업 계약서입니다.

Codex는 지침을 계층으로 읽는다

공식 AGENTS.md 가이드에 따르면 Codex는 시작할 때 지침 체인을 만듭니다. 먼저 CODEX_HOME 아래의 전역 파일을 보고, 그다음 프로젝트 루트에서 현재 작업 디렉토리까지 내려오며 각 디렉토리의 지침 파일을 확인합니다.

중요한 점은 두 가지입니다.

Codex는 전역 기본값과 프로젝트 규칙을 함께 읽을 수 있습니다.
현재 작업 위치에 더 가까운 파일이 나중에 붙으므로, 더 구체적인 규칙으로 취급됩니다.

예를 들어 백엔드 서비스 안에서 작업한다면 아래처럼 계층이 생깁니다.

~/.codex/AGENTS.md
repo/AGENTS.md
repo/services/api/AGENTS.md

전역 파일에는 개인 선호를 둡니다. 저장소 루트에는 팀 공통 규칙을 둡니다. 하위 디렉토리에는 특정 서비스나 패키지에만 맞는 빌드, 테스트, 배포 주의사항을 둡니다.

`AGENTS.override.md`는 임시 우선권이다

공식 문서는 AGENTS.override.md도 설명합니다. 전역 위치에서는 AGENTS.override.md가 있으면 기본 AGENTS.md 대신 읽고, 프로젝트 디렉토리에서도 AGENTS.override.md가 있으면 같은 디렉토리의 AGENTS.md보다 우선합니다.

이 기능은 강력하지만 남용하면 위험합니다. 이름 그대로 override입니다. 팀 표준을 잠깐 덮어야 하는 실험이나 로컬 전환에는 유용하지만, 장기 운영 규칙을 숨겨두는 장소로 쓰면 다음 사람이 이유를 알 수 없습니다.

실무에서는 이렇게 나눕니다.

위치	넣을 내용	주의할 점
`~/.codex/AGENTS.md`	개인 커뮤니케이션 방식, 기본 검증 습관	팀 규칙을 대신하지 않음
`repo/AGENTS.md`	저장소 공통 빌드, 테스트, 리뷰, 금지 규칙	너무 길게 만들지 않음
`repo/path/AGENTS.md`	특정 패키지나 서비스의 로컬 규칙	적용 범위를 좁게 유지
`AGENTS.override.md`	임시 우선 규칙	오래 남기지 않음

Mermaid로 보는 지침 위치 결정

아래는 초안에 남겨둔 Mermaid 의사결정 흐름입니다. 게시 본문에는 같은 흐름을 SVG로 렌더링해 넣습니다.

Mermaid 원본:
flowchart TD
  A[새 규칙이 생겼는가?] --> B{다음 작업에도 반복되는가?}
  B -->|아니오| C[프롬프트에 둔다]
  B -->|예| D{저장소 규칙인가?}
  D -->|예| E[가까운 AGENTS.md에 저장]
  D -->|아니오| F[반복 절차면 Skill로 분리]

이 흐름의 핵심은 “반복성”입니다. 한 번만 필요한 요청을 AGENTS.md에 넣으면 파일이 금방 지저분해집니다. 반대로 매번 반복되는 테스트 명령이나 외부 게시 확인 절차를 프롬프트에만 두면 언젠가 빠집니다.

좋은 AGENTS.md는 짧고 검증 가능하다

OpenAI customization 문서는 AGENTS.md를 작게 유지하라고 안내합니다. 반복 실수, 너무 많은 파일 읽기, 반복되는 PR 피드백이 생기면 그때 규칙을 추가하는 방식이 좋습니다.

좋은 문장은 Codex가 바로 행동할 수 있습니다.

JavaScript 파일을 수정한 뒤에는 `npm test`를 실행한다.
DAKER 게시물은 게시 전 `scripts/markdown-to-daker-html.mjs --directory codex`로 payload를 만든다.
외부 게시 후에는 공개 API status 200과 디렉토리 목록 포함을 확인한다.

나쁜 문장은 멋있지만 실행 기준이 없습니다.

항상 최고의 품질로 책임감 있게 작업한다.
가능한 한 꼼꼼하게 확인한다.
상황에 맞게 잘 판단한다.

Codex는 추상적인 태도보다 구체적인 완료 기준을 더 잘 따릅니다. 좋은 AGENTS.md는 문화 선언문이 아니라 체크리스트에 가깝습니다.

`/init`은 시작점이지 완성본이 아니다

Codex CLI slash command 문서에는 /init이 현재 디렉토리에 AGENTS.md scaffold를 생성하는 명령으로 정리되어 있습니다. Best practices 문서도 /init을 quick-start로 소개하지만, 팀이 실제로 빌드하고 테스트하고 리뷰하고 배포하는 방식에 맞게 수정하라고 말합니다.

따라서 /init을 실행했다면 그다음 작업이 더 중요합니다.

저장소의 실제 테스트 명령을 넣는다.
가장 자주 실패하는 작업 경로를 넣는다.
Codex가 먼저 읽어야 할 디렉토리와 피해야 할 디렉토리를 적는다.
외부 side effect가 있는 작업의 확인 기준을 적는다.
“완료”의 증거를 명령이나 API 확인으로 적는다.

scaffold는 빈 양식입니다. 운영 지식은 팀이 채워야 합니다.

config, memory, skill과 역할이 다르

다

AGENTS.md를 모든 지식의 저장소로 만들면 금방 무거워집니다. Codex customization 문서는 customization layer를 나눠 설명합니다. AGENTS.md는 지속 프로젝트 지침, memory는 이전 작업에서 배운 유용한 맥락, Skill은 반복 workflow, MCP는 외부 도구 연결, subagent는 전문 작업 위임에 가깝습니다.

실무에서는 이렇게 나눕니다.

필요	둘 위치
저장소에서 항상 지킬 규칙	`AGENTS.md`
모델, sandbox, approval, MCP 기본값	`~/.codex/config.toml` 또는 `.codex/config.toml`
쉘 단위 자동화 변수나 installer 변수	환경 변수
반복 절차와 참고 자료, 스크립트	Skill
이전 작업에서 이어받을 짧은 맥락	memory
오늘 한 번만 필요한 요청	현재 프롬프트

예를 들어 CODEX_HOME은 Codex 상태, 설정, 인증, 로그, 세션, skills 같은 루트를 바꾸는 환경 변수입니다. 이런 실행 환경 설정을 AGENTS.md에 장황하게 설명하기보다, “이 저장소는 어떤 검증 명령을 요구하는가”처럼 작업 규칙을 적는 편이 낫습니다.

하위 디렉토리 지침은 강력한 라우팅 장치다

큰 저장소에서는 루트 AGENTS.md 하나만으로 부족합니다. 프론트엔드, 백엔드, 인프라, 데이터 파이프라인이 서로 다른 명령과 위험을 갖기 때문입니다.

하위 디렉토리 지침은 아래처럼 씁니다.

# services/payments/AGENTS.md

## 결제 서비스 규칙

- 결제 금액 계산 로직을 바꾸면 `make test-payments`를 실행한다.
- 마이그레이션 파일은 새 파일만 추가하고 기존 적용 파일은 수정하지 않는다.
- API 키 회전, 환불 처리, 결제 상태 강제 변경은 사용자 확인 없이 실행하지 않는다.

이런 지침은 루트 파일에 모두 넣는 것보다 해당 디렉토리 가까이에 두는 편이 좋습니다. Codex가 그 영역에서 작업할 때 더 구체적인 규칙으로 읽기 때문입니다.

AGENTS.md에 넣지 말아야 할 것

AGENTS.md는 저장소에 남을 수 있고, 팀원이 볼 수 있으며, Codex가 매번 읽을 수 있습니다. 그래서 넣으면 안 되는 것도 분명합니다.

빼야 할 것	이유
비밀값, 쿠키, 개인 토큰	저장소와 세션에 노출될 수 있음
임시 이슈 대응 메모	금방 낡아서 잘못된 규칙이 됨
긴 배경 설명	핵심 지침을 묻어버림
서로 충돌하는 규칙	Codex가 우선순위를 추측해야 함
사람만 이해하는 은어	자동화가 행동으로 옮기기 어려움

특히 비밀값은 절대 넣지 마세요. 인증은 connector, MCP, 환경 변수, 비밀 관리 도구의 영역입니다. AGENTS.md는 “어떤 경우 확인이 필요한가”를 적는 곳이지 “토큰 값이 무엇인가”를 적는 곳이 아닙니다.

업데이트 기준은 “두 번 반복되었는가”다

모든 피드백을 즉시 AGENTS.md에 넣으면 파일이 부풀어 오릅니다. 반대로 아무것도 넣지 않으면 같은 실수를 계속 설명하게 됩니다.

내 기준은 이렇습니다.

같은 실수나 리뷰 피드백이 두 번 반복되면 추가 후보로 본다.
한 디렉토리에만 해당하면 그 디렉토리의 AGENTS.md에 둔다.
여러 저장소에서 반복되면 전역 지침이나 Skill 후보로 본다.
명령, 파일 경로, 완료 증거 없이 적을 수밖에 없다면 아직 지침으로 만들지 않는다.
오래된 지침은 지우거나 더 가까운 위치로 옮긴다.

좋은 운영 문서는 길어지는 문서가 아니라 정확해지는 문서입니다.

팀 가이드에 넣을 문장

Codex를 팀에서 쓴다면 아래 문장을 루트 AGENTS.md에 넣을 만합니다.

AGENTS.md에는 반복되는 저장소 규칙만 둔다.
한 번만 필요한 요청은 프롬프트에 쓰고, 반복 절차와 참고 자료가 필요한 workflow는 Skill로 분리한다.
새 규칙을 추가할 때는 적용 범위, 실행 명령, 완료 증거를 함께 적는다.
비밀값, 쿠키, 개인 토큰, 임시 우회 절차는 AGENTS.md에 넣지 않는다.

이 네 줄은 Codex뿐 아니라 팀원에게도 유용합니다. 어떤 규칙을 어디에 둘지 합의가 생기기 때문입니다.

시니어 엔지니어의 기준

좋은 Codex 작업은 프롬프트를 길게 쓰는 능력이 아니라, 반복되는 작업 조건을 올바른 표면에 저장하는 능력에서 나옵니다. AGENTS.md는 그중 가장 기본적인 표면입니다.

오늘 저장소에서 AGENTS.md를 열고 이 질문만 해보세요.

이 파일은 Codex가 바로 실행하고 검증할 수 있는 작업 계약인가?

그렇다면 좋은 출발입니다. 아니라면 줄이세요. 추상적인 설명은 빼고, 명령과 금지 범위와 완료 증거를 남기세요. Codex는 긴 당부보다 정확한 계약을 더 잘 지킵니다.

참고: OpenAI Codex의 Custom instructions with AGENTS.md, Best practices, Customization, CLI slash commands, Environment variables 문서를 20

26-06-15 Asia/Seoul 기준으로 확인했습니다.