AGENT.md는 코딩 하네스가 작업 시작 시 읽는 프로젝트 지침 파일이다. 리뷰에서 계속 반복하는 “매직 넘버를 상수로 추출하라”, “버그는 먼저 재현 테스트를 작성하라” 같은 요구를 짧고 구체적인 규칙으로 옮기면, 매 세션마다 같은 피드백을 재입력하는 비용을 줄일 수 있다. 다만 지침 파일은 코드 리뷰와 테스트를 대체하지 않는다.
무엇을 넣을지 고르는 기준
| 넣기 좋은 규칙 | 피해야 할 규칙 |
|---|---|
| 실제로 여러 번 발생한 실패를 막는 행동 | 취향만 담긴 추상적 찬사·금지어 |
| 테스트, 공개 API, 레이어 경계처럼 검증 가능한 조건 | 특정 기능에만 필요한 일회성 구현 지시 |
| 변경 범위와 사람 승인 지점을 정하는 규칙 | 오래된 배경 설명과 방대한 API 문서 |
예를 들어 “버그 수정 전에는 실패하는 테스트를 추가하고, 수정 뒤 통과 결과를 확인한다”는 실행과 검증이 모두 명확하다. 반면 “깔끔한 코드를 작성한다”는 에이전트마다 해석이 달라 회귀 테스트가 어렵다.
작게 시작하는 예시
# 작업 규칙
- 버그를 수정할 때는 먼저 실패하는 테스트를 만든다.
- 수정한 기능과 무관한 코드의 리팩터링은 포함하지 않는다.
- public API 변경은 구현 전에 승인받는다.
- 완료 보고에는 실행한 검증 명령과 결과를 적는다.규칙이 반복해서 무시된다면 프롬프트를 길게 하기보다, 포매터·린터·테스트·pre-commit 훅처럼 기계적으로 검증할 수 있는 레이어로 옮긴다. agent-harness의 래칫 원칙처럼 실제 실패에서만 규칙을 추가하고, 효과가 없는 문장은 삭제해 파일을 짧게 유지한다.
관련 문서
- agent-harness — 지침, 훅, 검증을 나눠 설계하는 하네스
- claude-code-patterns — 지침 파일을 라우터로 유지하는 운영 패턴
- prompt-lexical-sensitivity — 구체적인 행동 지시가 출력을 안정화하는 이유
참고 자료
- My agent.md to improve LLM-assisted code quality — Fabien Sanglard (2026-08-21)
- agentsmd/agent — GitHub 공식 저장소