AGENTS.md는 잡동사니 서랍이 아닙니다

규칙 파일은 처음에는 한 페이지로 시작합니다. 6개월 후에는 14페이지가 되고 아무도 그 안에 무엇이 들어있는지 기억하지 못합니다. 팀은 무언가 짜증 나는 일이 생길 때마다 새로운 규칙을 추가하고, 그 무엇도 삭제하지 않습니다. 에이전트(Agent)는 매 세션마다 파일 전체를 컨텍스트 (Context)에 로드하지만, 그중 대부분을 무시합니다. 그럼에도 팀은 자신들이 직접 작성했다는 이유만으로 이 파일이 여전히 유용하다고 확신합니다.

이것이 규칙 파일이 맞이하게 되는 가장 흔한 종착역입니다. 규칙 파일이 잡동사니 서랍 (Junk drawer)이 된 상태입니다. 즉, 선의로 작성된 내용이 오래된 조언, 중복된 사실, 그리고 열망 섞인 원칙들과 공존하는 장소가 되며, 큐레이션 (Curation)이 전혀 이루어지지 않기 때문에 모든 항목의 가중치가 동일하게 취급되는 곳입니다.

잡동사니 서랍은 도구가 아닙니다. 그것은 도구를 가지고 있다는 '기분'일 뿐입니다.

규칙의 목적

AGENTS.md / CLAUDE.md 또는 그와 유사한 맥락에서 규칙 (Rule)은 정확히 한 가지 임무를 가집니다. 바로 에이전트 (Agent)가 수행하는 동작을 바꾸는 것입니다. 만약 파일의 특정 항목이 에이전트의 동작을 바꾸지 못한다면, 그것은 동작을 바꾸는 다른 항목들을 희생시키며 공간만 차지하고 있는 것입니다.

당연한 소리처럼 들릴 것입니다. 하지만 실제로 대부분의 규칙은 이 테스트를 통과하지 못합니다.

열망 (The aspiration): "우리는 깨끗하고 유지보수 가능한 코드를 작성한다." 에이전트는 이 문장에 따라 어떻게 행동해야 할지 모릅니다. 에이전트는 이미 학습을 통해 배운 어떤 의미에서든 깨끗한 코드를 작성하고 싶어 합니다. 이 항목은 컨텍스트 (Context) 비용만 발생시킬 뿐 아무런 신호 (Signal)를 제공하지 않습니다.

중복 (The redundancy): "TypeScript 엄격 모드 (Strict mode)를 사용하라." 엄격 모드는 이미 tsconfig.json에 설정되어 있습니다. 컴파일러 (Compiler)가 이를 강제합니다. 에이전트는 실행 시 이를 인지할 것입니다. 이 항목은 코드베이스 (Codebase)가 이미 드러내고 있는 사실에 불과합니다.

동사가 없는 원칙 (The principle-without-verb): "상속보다 합성을 선호하라." 설계 과정에서 인간에게는 유용합니다. 하지만 에이전트가 지금 편집 중인 파일 내에서 구체적인 결정으로 번역하기에는 어렵습니다.

모순 (The contradiction): 3페이지에는 "항상 async/await를 사용하라"고 되어 있고, 11페이지에는 "에러 처리를 위해 비동기 호출을 우리의 safeAsync 헬퍼 (Helper)로 감싸라"고 되어 있습니다. 둘 다 사실일 수 있습니다. 하지만 함께 있을 때, 에이전트는 우선순위에 대해 추측해야 하는 상황에 놓입니다.

산문 투척 (The prose dump): 팀이 왜 특정 ORM을 선택했는지에 대한 역사를 설명하는 세 개의 문단. 흥미롭긴 합니다. 하지만 실행 가능 (Actionable)하지 않습니다. 지탱하는 힘 (Load-bearing)도 없습니다.

이 항목들 중 나쁜 것은 하나도 없습니다. 단지 에이전트의 행동을 변화시키는 것이 유일한 목적인 파일 내에서, 그 자리를 차지할 만큼의 가치를 증명하지 못하고 있을 뿐입니다.

모든 규칙이 답해야 하는 두 가지 질문

항목을 추가하기 전에 다음을 질문하십시오:

이 규칙이 없다면 에이전트는 무엇을 할 것인가? 만약 대답이 "똑같은 행동을 할 것이다"라면, 해당 항목을 삭제하십시오. 그 규칙은 현실을 변화시키는 것이 아니라, 단순히 현실을 묘사하고 있을 뿐입니다.

에이전트가 취해야 할 구체적인 행동(Concrete action)은 무엇인가? 만약 이를 명시할 수 없다면, 그 항목은 규칙 (Rule)이 아니라 원칙 (Principle)입니다. 원칙은 설계 문서 (Design docs)에 있어야 하며, 규칙은 규칙 파일에 있어야 합니다.

두 가지 테스트를 모두 통과하는 규칙의 예시는 다음과 같습니다: "새로운 API 엔드포인트를 추가할 때, routes.ts에 등록하고 tests/api/에 상응하는 통합 테스트 (Integration test)를 추가하십시오. 다른 곳에 임시로 라우트를 등록하지 마십시오." 이는 구체적입니다. 에이전트가 직면하게 될 실제 결정에 작용합니다. 에이전트가 기본적으로 수행할 행동과 다릅니다.

실패하는 규칙의 예시: "기존 패턴과 일관성을 유지하십시오." 맞는 말입니다. 지향점은 맞습니다. 하지만 에이전트가 이미 하고 싶어 했던 것 외에 아무것도 알려주지 않습니다.

포함할 것과 제외할 것

이 파일은 높은 기준을 충족하는 규칙들을 포함해야 합니다. 즉, 규칙이 없다면 에이전트가 틀릴 내용, 에이전트가 이미 실행 중인 도구들로 강제할 수 없는 내용, 그리고 실행 가능할 만큼 충분히 구체적인 내용이어야 합니다.

포함되어야 할 항목의 예시: 타입 시스템 (Type system)이 표현할 수 없는 계층 구조 및 아키텍처 경계 (Architectural boundaries); 새로운 파일, 모듈 또는 테스트에 대한 명명 규칙 (Naming conventions); 의존성 (Dependencies) 중에 옵션이 여러 개 있을 때 어떤 라이브러리를 사용할 것인지; 서비스 코드에서 발생하는 에러를 구조화하는 방법; 새로운 테스트를 어느 파일의 어떤 이름으로 추가할 것인지 등입니다.

제외되어야 할 항목의 예시: 린터 (Linter), 포매터 (Formatter), 또는 타입 체커 (Type checker)가 이미 강제하고 있는 모든 것; 모든 코드베이스에 공통적으로 적용되는 사실 (테스트 작성하기, 비밀 정보 커밋하지 않기, 읽기 쉬운 코드 선호하기 등); 동사가 없는 원칙; 현재의 영향력이 없는 역사적 맥락; 아무도 세부 사항을 기억하지 못하는 2년 전의 좋지 않은 사건 하나 때문에 존재하는 규칙 등입니다.

기존 규칙 파일의 모든 줄에 대해 던질 수 있는 가장 유용한 단 하나의 질문은 이것입니다: "만약 내가 이 줄을 삭제한다면, 에이전트 (Agent)가 다르게 행동할 것인가?" 만약 솔직한 답변이 '아니오'라면, 그 줄은 공간만 차지하고 있는 것입니다.

가지치기 (Pruning)는 실천입니다

규칙을 추가하는 것은 쉽습니다. 하지만 규칙을 삭제하는 것은 절제 (Discipline)입니다.

리뷰 코멘트로부터 규칙을 추가하는 것과 동일한 플라이휠 (Flywheel)이 반대 방향으로도 돌아가야 합니다. 누군가가 정기적인 주기 (매주가 좋으며, 최대 한 달에 한 번)로 규칙 파일을 처음부터 끝까지 읽으며 각 항목에 대해 삭제 질문을 던져야 합니다. 잘못된 것으로 판명된 규칙은 삭제됩니다. 린터 (Linter)에 의해 대체된 규칙은 삭제됩니다. 아무도 그 기원을 기억하지 못하는 규칙은 누군가가 5초 안에 그 이유를 방어할 수 없다면 삭제됩니다. 새로운 규칙과 모순되는 규칙은 조정되거나, 둘 중 하나가 삭제됩니다.

만약 Bridle을 사용하고 있다면, 이 과정을 더 빠르게 만들기 위해 하네스 (Harness, 규칙 파일을 포함)의 문제를 감사 (Audit)하는 명령어가 있습니다.

건강한 규칙 파일은 작습니다. 파일이 작은 이유는 팀의 의견이 예전보다 줄어들어서가 아니라, 의견들이 자동으로 강제되는 곳 (린터 (Linter), 테스트 (Tests), 타입 (Types))으로 이동했고, 오직 진정으로 맥락에 의존적인 것들만이 파일에 남아 있기 때문입니다.

가지치기를 하는 팀은 실제로 에이전트의 행동을 변화시키는 수십 줄 정도의 규칙 파일을 갖게 됩니다. 가지치기를 하지 않는 팀은 대부분 아무런 영향도 주지 못하는 수백 줄의 규칙을 갖게 되며, 신호 (Signal)가 묻혀버리기 때문에 에이전트가 엉뚱한 것에 주의를 기울이게 됩니다.

시작하는 규칙 파일을 위한 시작 규칙

만약 현재 아무것도 없고 처음부터 시작해야 한다면, 한 번에 완전한 파일을 작성하려고 하지 마세요. 기본적으로 잡동사니 서랍을 만들게 될 것입니다. 파일에 다음 규칙 하나만 먼저 작성하며 시작하세요:

이 파일의 규칙은 에이전트가 수행하는 작업을 변경합니다. 규칙이 변경하는 구체적인 행동과, 그 규칙이 없을 때 에이전트가 기본적으로 수행할 대안 행동을 명시할 수 있는 경우에만 규칙을 추가하세요. 그 외의 모든 것은 디자인 문서 (Design doc)나 린터 설정 (Linter config)에 속합니다.

그 문장이, 비어 있는 파일의 맨 윗부분에 자리 잡음으로써 향후 1년 동안 이루어질 모든 추가 사항의 지침이 될 것입니다. 그 하나의 규칙이 강제하는 규율을 통해 다른 모든 규칙들도 더 나아질 것입니다.

잡동사니 서랍이 기본값입니다. **큐레이션 (Curation)**이 바로 우리가 해야 할 일입니다.