기본 패턴
md
# AGENTS.md
## Repo layout
- app/: 사용자 화면
- lib/: 공용 로직
## Run and test
- npm run build
- npm test
## Conventions
- 새 파일은 kebab-case
- 테스트가 가능하면 같이 추가
## Done when
- 관련 테스트 통과
- diff 검토 완료설명
- AGENTS.md는 Codex가 작업을 시작하기 전에 읽는 지속형 지침 파일입니다.
- 공식 가이드는 여기에 저장소 구조, 실행/테스트 명령, 코드 규칙, 리뷰 기대치, 완료 조건을 작게 적으라고 권합니다.
- 한 번만 설명하고 끝낼 일보다, 세션마다 반복해서 고쳐 주게 되는 실수를 줄이는 규칙을 넣는 데 특히 효과적입니다.
/init명령은 현재 디렉터리에 맞는 AGENTS.md 초안을 만들어 주므로 첫 시작점을 잡기 좋습니다.- 너무 긴 배경 설명보다 "어디를 먼저 읽어라", "어떤 명령으로 검증하라", "무엇을 끝의 기준으로 볼 것인가" 같은 عملی적인 문장이 훨씬 유용합니다.
짧은 예제
text
반복해서 생기던 실수
- 잘못된 테스트 명령 실행
- 팀이 쓰지 않는 코드 스타일 사용
- 완료 기준 없이 중간 결과만 제출
AGENTS.md에 넣을 규칙
- 검증은 npm run test:unit 사용
- import 정렬은 기존 파일 스타일 유지
- 작업 종료 전 git diff와 빌드 결과를 함께 보고빠른 정리
| 넣기 좋은 내용 | 이유 |
|---|---|
| 저장소 구조 | 먼저 볼 파일과 디렉터리를 줄여 줍니다. |
| 실행과 테스트 명령 | 검증 루프를 표준화합니다. |
| 팀 규칙 | 반복 실수를 줄입니다. |
| 리뷰 기대치 | 결과물 품질 기준을 맞춥니다. |
| 완료 조건 | 중간 결과를 최종 결과로 착각하지 않게 합니다. |
주의할 점
AGENTS.md는 팀 위키를 복붙하는 곳이 아닙니다. 길고 포괄적인 설명보다, Codex가 지금 저장소에서 당장 따라야 할 규칙만 남겨 두는 편이 훨씬 잘 작동합니다.
참고 링크
3 sources