AGENTS.md 파일은 코딩 에이전트에게 저장소에서 작업하는 방법을 알려 줍니다.
이 파일은 세션마다 컨텍스트에 로드됩니다. 따라서 추가하는 모든 줄은 매 작업마다
비용을 발생시키며, 실제 요청과 에이전트의 주의를 두고 경쟁합니다.
이 한 가지 사실만으로도 아래 조언의 대부분을 설명할 수 있습니다.
살펴봐도 알 수 없는 내용만 작성하기
에이전트가 저장소를 살펴보고 알아낼 수 있는 내용은 적지 마세요. 디렉터리 구조, 사용 중인 프레임워크, 테스트 파일 명명 규칙은 모두 저장소에서 확인할 수 있으므로 다시 설명할 필요가 없습니다.
직접 살펴봐도 알 수 없는 것은 의도와 제약 조건입니다.
- 테스트를 실행하는 명령어, 특히 명령어가 명확하지 않은 경우
- 아직 코드 전반에서 일관되게 지켜지지 않는 규칙
- 버그처럼 보이지만 의도적으로 설계된 동작
- 수정하면 안 되는 디렉터리와 그 이유
끝까지 읽을 수 있을 만큼 짧게 유지하기
파일이 대략 백 줄을 넘으면 아무도 읽지 않는 문서처럼 변하기 시작합니다. 180번째 줄에 묻힌 지침은 파일의 나머지 내용 전체와 주의를 두고 경쟁하므로 행동을 안정적으로 바꾸지 못합니다.
파일이 이미 길어졌다면 “에이전트가 이 내용을 따르게 하려면 어떻게 해야 할까?” 보다 “이 중 실제로 결과를 바꾼 줄은 무엇일까?”라고 묻는 편이 더 유용합니다.
명령어를 구체적으로 작성하기
모호한 지침은 모호한 행동을 낳습니다. 다음 두 예를 비교해 보세요.
Run the tests before committing.그리고:
Run `pnpm test -- --run` before committing. It takes about 40 seconds.
Do not run `pnpm test` without `--run`; it starts watch mode and hangs.두 번째 문장은 구체적이고 반복되는 실패를 막아 줍니다. 첫 번째 문장은 태도를 표현할 뿐입니다.
규칙뿐 아니라 이유도 설명하기
이유가 있는 규칙은 낯선 상황에서도 적용할 수 있지만, 단순한 금지 사항은 그렇지
못합니다. “src/generated/를 수정하지 마세요”라고만 하면 직접 수정하는 편이
편리해 보이는 순간 예외를 만들기 쉽습니다. “src/generated/를 수정하지 마세요.
pnpm codegen이 덮어쓰기 때문에 변경 내용이 사라집니다”라고 하면 그렇지
않습니다.
효과가 없어지면 다시 검토하기
이 파일도 시간이 지나며 낡는 것으로 생각하세요. 에이전트가 원하지 않는 행동을 반복한다면 이는 모델뿐 아니라 파일에도 문제가 있다는 증거입니다. 필요한 지침이 빠졌거나, 기존 지침이 더 이상 중요하지 않은 삼백 줄에 묻혀 있는 것입니다.