핵심 정리

# AGENTS.md

Repo layout
- app/: 사용자 화면
- lib/: 공용 로직

Run and test
- npm run build
- npm test

Conventions
- 새 파일은 kebab-case
- 테스트가 가능하면 같이 추가

Done when
- 관련 테스트 통과
- diff 검토 완료

핵심 항목

AGENTS.md는 모델이 스스로 컨텍스트를 구성하는 설계도다

Codex는 작업을 시작하기 전에 AGENTS.md를 읽고 저장소에서 어떻게 행동할지를 결정합니다. 이 파일이 없으면 매 세션마다 같은 규칙을 프롬프트로 반복 설명해야 하고, 그 사이 일관성이 흔들립니다. AGENTS.md는 "한 번만 적으면 모든 세션에 적용되는 지속형 지침"입니다. /init 명령은 현재 디렉터리를 분석해 초안을 만들어 주므로 처음 시작점을 잡기 좋습니다.

검증 루프를 표준화하면 결과 품질이 달라진다

실수 중 가장 자주 반복되는 유형은 잘못된 테스트 명령 실행, 팀이 쓰지 않는 스타일 적용, 완료 기준 없이 중간 결과 제출입니다. AGENTS.md의 Run and test 항목은 Codex가 어떤 명령으로 결과를 검증해야 하는지를 명확히 고정합니다. "테스트는 npm run test:unit", "import 정렬은 기존 파일 스타일 유지"처럼 구체적인 규칙이 막연한 지침보다 훨씬 효과적입니다.

반복해서 생기던 실수          AGENTS.md에 넣을 규칙
잘못된 테스트 명령 실행    →  검증은 npm run test:unit 사용
팀이 쓰지 않는 코드 스타일 →  import 정렬은 기존 파일 스타일 유지
완료 기준 없이 중간 결과   →  작업 종료 전 git diff와 빌드 결과를 함께 보고

파일을 짧게 유지해야 하는 이유는 읽기 상한 때문이다

전체 읽기 크기에 기본 상한이 있으므로 AGENTS.md가 길수록 뒤쪽 지침이 실질적으로 무시될 위험이 있습니다. 팀 위키를 복붙하거나 배경 설명을 장황하게 넣는 방식은 역효과를 냅니다. "어디를 먼저 읽어라", "어떤 명령으로 검증하라", "무엇이 완료 기준인가"처럼 Codex가 지금 당장 따라야 하는 실천 규칙만 남기는 편이 훨씬 잘 작동합니다.

좋은 항목
  -> 지금 따라야 하는 규칙

나쁜 항목
  -> 배경 설명
  -> 팀 위키 복사본
  -> 오래된 프로젝트 역사

Done when 항목이 중간 결과를 최종으로 착각하는 실수를 막는다

완료 조건이 명시되지 않으면 Codex는 테스트 실행 없이 코드 수정만 하고 작업을 끝낼 수 있습니다. Done when 항목에 "관련 테스트 통과", "diff 검토 완료", "빌드 성공"을 적어 두면, 에이전트가 스스로 종료 판단을 내릴 때 이 기준을 참조합니다. 이것이 AGENTS.md가 단순 문서가 아니라 에이전트 행동을 제어하는 설계도인 이유입니다.

무엇을 남길까

주의할 점

❌ "우리 팀은 2021년에 이 구조를 도입했고..."
❌ "백엔드 아키텍처 전반 설명 40줄"

이런 내용은 배경 이해에는 도움이 될 수 있어도, Codex가 당장 따라야 할 실행 규칙으로는 약합니다.