AGENTS.md는 잡동사니 서랍이 아니다
Source: Dev.to
과도하게 늘어난 Rules 파일의 문제
Rules 파일은 보통 한 페이지로 시작합니다. 6개월 뒤면 열네 페이지가 되고, 안에 뭐가 들어있는지 아무도 기억하지 못합니다. 팀은 귀찮은 일이 생길 때마다 새로운 규칙을 추가하고, 절대 삭제하지 않습니다. 에이전트는 매 세션마다 전체 파일을 컨텍스트에 로드하지만 대부분을 무시하고, 팀은 자신들이 만든 것이니 아직도 유용하다고 스스로 설득합니다.
이것이 Rules 파일의 가장 흔한 최종 상태입니다: 정크 서랍—좋은 의도와 오래된 조언, 중복된 사실, 그리고 실현 가능한 원칙이 모두 동등하게 무게를 두고 섞여 있는 곳, 아무것도 정리되지 않기 때문입니다.
정크 서랍은 도구가 아닙니다. 도구가 있다는 느낌일 뿐입니다.
Rules의 목적
AGENTS.md, CLAUDE.md 혹은 동등한 파일에서의 규칙은 정확히 한 가지 일을 합니다: 에이전트가 하는 일을 바꾸는 것. 만약 어떤 항목이 에이전트의 행동을 바꾸지 못한다면, 그것은 행동을 바꾸는 항목들을 차지하는 공간일 뿐입니다.
대부분의 규칙이 실패하는 이유
| 문제 | 예시 | 왜 실패하는가 |
|---|---|---|
| 목표 지향적 진술 | “우리는 깨끗하고 유지보수 가능한 코드를 작성한다.” | 에이전트는 이미 깨끗한 코드를 쓰고 싶어합니다(훈련 데이터에서 학습). 이 항목은 컨텍스트를 차지하지만 실행 가능한 신호를 제공하지 않습니다. |
| 중복된 사실 | “TypeScript strict mode를 사용한다.” | tsconfig.json에서 이미 strict mode가 강제됩니다. 컴파일러가 위반을 잡아내므로 규칙이 추가적인 가치를 제공하지 않습니다. |
| 동사 없는 원칙 | “상속보다 컴포지션을 선호한다.” | 인간에게는 설계 단계에서 도움이 되지만, 에이전트가 코드를 편집하면서 구체적인 결정을 내리기엔 어렵습니다. |
| 모순되는 규칙 | - 3페이지: “항상 async/await를 사용한다.”- 11페이지: “비동기 호출은 오류 처리를 위해 safeAsync 헬퍼로 감싼다.” | 두 규칙 모두 사실일 수 있지만, 함께 있을 경우 에이전트는 어느 것이 우선인지 혼란스러워합니다. |
| 장문 설명 | 특정 ORM을 선택한 이유에 대한 3단락 짜리 설명 | 흥미로운 역사이지만 실행 가능하지도 않고 로드도 무겁습니다. |
이 항목들은 나쁜 것이 아니라, 에이전트의 행동을 바꾸는 파일에 들어갈 자격을 얻지 못했을 뿐입니다.
모든 규칙이 답해야 할 두 질문
항목을 추가하기 전에 스스로에게 물어보세요:
-
이 규칙이 없으면 에이전트는 무엇을 할까?
- 답이 “똑같은 일”이라면 삭제하세요. 규칙은 현실을 묘사할 뿐, 행동을 바꾸지 않습니다.
-
에이전트가 취해야 할 구체적인 행동은 무엇인가?
- 구체적인 행동을 명시할 수 없다면, 그것은 원칙이지 규칙이 아닙니다. 원칙은 설계 문서에, 규칙은 Rules 파일에 둡니다.
좋은 규칙 vs 나쁜 규칙 예시
-
좋은 규칙:
“새 API 엔드포인트를 추가할 때는
routes.ts에 등록하고,tests/api/에 해당 통합 테스트를 추가한다. 임시로 다른 곳에 라우트를 등록하지 않는다.”
구체적이고 실행 가능하며 기본 동작과 차별화됩니다. -
나쁜 규칙:
“기존 패턴과 일관성을 유지한다.”
목표 지향적이고 모호해서 에이전트에게 새로운 행동을 알려주지 못합니다.
무엇을 넣고 무엇을 뺄까
파일에는 높은 기준을 만족하는 규칙만 포함해야 합니다:
-
포함: 에이전트가 이 규칙 없이는 잘못 행동하고, 기존 도구(린터, 포매터, 타입 체커)로는 강제할 수 없으며, 구체적으로 실행할 수 있는 규칙.
유용한 규칙 예시
- 타입 시스템으로 표현할 수 없는 레이어링 및 아키텍처 경계.
- 새 파일, 모듈, 테스트의 네이밍 규칙.
- 의존성에 여러 옵션이 있을 때 어떤 라이브러리를 사용할지.
- 서비스 코드에서 발생하는 오류를 어떻게 구조화할지.
- 새로운 테스트를 어디에, 어떤 파일에, 어떤 네이밍 패턴으로 추가할지.
-
제외: 린터·포매터·타입 체커가 이미 다루는 내용, 보편적인 진리, 원칙만 있는 진술, 현재와 무관한 역사적 배경, 기억조차 안 나는 과거 사건에서 나온 규칙.
모든 라인에 적용되는 가장 유용한 질문:
“이 라인을 삭제하면 에이전트가 행동을 바꾸나요?”
정직하게 아니오라면, 그 라인은 단순히 공간을 차지하고 있는 겁니다.
가지치기(Pruning)란 실천
- 추가는 쉽습니다.
- 삭제는 규율이 필요합니다.
정기적인 주기(주간이면 충분, 최대 월간)를 정해 Rules 파일을 위에서 아래까지 읽으며 각 항목에 삭제 질문을 적용하세요. 삭제 대상:
- 잘못된 것으로 판명된 규칙.
- 린터·포매터에 의해 대체된 규칙.
- 출처를 아무도 기억하지 못하는 규칙(5초 안에 변호할 사람이 없으면).
- 모순되는 규칙—통합하거나 약한 쪽을 삭제.
**Bridle**를 사용한다면, 규칙 파일을 포함한 하네스를 감사하는 명령이 있어 이 과정을 빠르게 할 수 있습니다.
건강한 Rules 파일은 작습니다—팀 의견이 적어서가 아니라, 그 의견들이 자동으로 강제되는 곳(린터, 테스트, 타입)으로 옮겨갔기 때문입니다. 오직 실제 상황에 따라 달라지는 규칙만 남습니다.
- 가지치기 하는 팀: 실제로 에이전트 행동을 바꾸는 수십 줄의 규칙만 남깁니다.
- 가지치기 하지 않는 팀: 대부분 효과가 없는 수백 줄이 쌓이고, 에이전트는 잘못된 신호에 주목하게 됩니다.
새 Rules 파일을 위한 시작 규칙
처음부터 완전한 파일을 만들려고 하지 마세요—그럼 바로 정크 서랍이 됩니다. 다음 한 줄만으로 시작하세요:
“이 파일의 규칙은 에이전트가 하는 일을 바꾼다. 규칙을 추가하려면 바뀌는 구체적인 행동과 에이전트가 기본적으로 할 행동을 명시할 수 있어야 한다. 그 외는 설계 문서나 린터 설정에 둬라.”
이 문장을 파일 상단에 두고 앞으로의 모든 추가를 이 문장이 안내하도록 하세요.
비어 있는 파일의 최상단이 앞으로 1년 동안 모든 추가를 이끌어 줄 것입니다. 이후의 모든 규칙은 그 한 줄이 강제하는 규율 덕분에 더 나아질 것입니다.
정크 서랍은 기본값입니다. 큐레이션이 바로 작업입니다.