LLM 코드 품질을 끌어올리는 Fabien Sanglard의 agent.md

TL;DR Highlight

반복하던 코드 리뷰 지적을 agent.md에 넣어 LLM 코드 품질을 높였다

Who Should Read

AI 코딩 에이전트가 짠 스파게티 코드를 세션마다 같은 지적으로 고치고 있는 개발자

Core Mechanics

반복 지적은 agent.md로 옮겼다
- 세션이 시작되면 하네스(코딩 도구)가 agent.md를 읽어 프롬프트에 넣는다.
- 같은 지적을 또 하게 될 때마다 규칙을 한 줄씩 추가했다.
- 프로젝트 루트에 두면 되고, gemini.md나 claude.md는 심볼릭 링크로 연결할 수 있다.
코드 스타일 규칙을 구체적으로 적었다
- 매직 넘버는 상수나 enum으로 빼고, 들여쓰기는 early return과 continue로 줄이라고 적었다.
- 함수 이름은 30자 미만, boolean 파라미터 대신 enum, if는 한 줄이어도 {}를 쓰게 했다.
- 기능과 무관한 코드는 건드리지 말고 바뀐 줄을 최소화하라는 규칙도 넣었다.
구조와 소통 규칙도 넣었다
- 멤버는 기본 private, 접근자를 바꾸기 전에는 사용자 승인을 받게 했다.
- 레이어는 바로 아래 이웃만 호출하고, 컨트롤러가 DB나 하드웨어 드라이버를 직접 부르지 못하게 했다.
- 칭찬은 빼고 최소한의 단어로 냉정하게 답하라고 했다.
버그 수정은 테스트부터 시키게 했다
- 테스트를 먼저 쓰고 실패를 확인한 뒤 수정하고, 통과를 확인하게 했다.
- 저자는 이 방식으로 생성 코드가 상당히 좋아졌다고 썼다.
- 그래도 코드를 읽지 않아도 되는 마법은 아니고, LLM은 계속 환각을 낸다고 했다.

Community Reactions

린터로 강제하자는 의견
- {} 강제나 함수 이름 길이는 린터로 걸면 직접 코딩하는 사람도 같은 피드백을 받는다는 의견이 있었다.
- 'what은 코드 자체'라서 블록마다 설명 주석을 달게 하면 노이즈가 늘어난다는 지적도 있었다.
규칙 상당수가 불필요하다는 경험
- Claude를 1년 가까이 써도 Arrow Anti-Pattern 코드를 본 적이 없다는 경험이 있었다.
- 8~9개 규칙은 기본 CS라 시킬 필요가 없고, '숨 쉬게 하라' 같은 모호한 지시는 효과가 약하다는 의견도 있었다.
- 규칙 적용 시 특정 문자열을 출력하게 해 효과를 측정해 보라는 제안도 있었다.
컨텍스트 부담과 구조 분리
- AGENTS.md가 비대할수록 컨텍스트 소모가 커지고, 에이전트가 먼저 적용할 규칙을 고르게 했더니 일관성이 100%였다는 경험이 있었다.
- 코딩 규칙은 CODING_STANDARDS.md로 빼고 스킬이 필요할 때만 찾게 한다는 경험도 있었다.
- /tdd를 항상 쓰는데 가끔 어색한 테스트가 나와도 결함이 훨씬 줄었다는 경험이 있었다.
금지형보다 긍정형 문장이 낫다는 의견
- 'X 하지 마'는 모델에게 X를 먼저 심는 셈이라, 'Y를 하라, 이유는 이렇다'로 쓰는 편이 낫다는 의견이 있었다.
- 함수 이름 30자 제한은 이상한 약어를 만들 수 있어 오히려 해롭다는 반론이 있었다.

How to Apply

지금 쓰는 지적 3개를 agent.md에 넣기
- 오늘 코드 리뷰에서 에이전트에게 반복한 지적을 3개만 골라 프로젝트 루트의 agent.md에 한 줄씩 적어라.
- 새 세션에서 같은 작업을 시켜 지적이 사라지는지 확인하라.
버그 수정에 테스트 선행 규칙 추가하기
- 'Fix 요청이면 실패하는 테스트를 먼저 쓰고, 실패를 확인한 뒤 수정하라'를 agent.md에 넣어라.
- 다음 버그 티켓에 적용해 생성된 diff를 비교하라.
기능마다 새 세션을 열고 재로드 명령 쓰기
- 기능 하나가 끝나면 세션을 새로 시작하라.
- 품질이 떨어지면 'Reload agent.md'를 입력하라.
린터로 잡을 규칙은 린터로 옮기기
- {} 강제나 이름 길이처럼 기계가 검사할 수 있는 규칙은 린터 설정으로 옮겨라.
- agent.md에는 린터로 못 잡는 설계 규칙만 남겨라.

Try It

복사해서 바로 해보기

# Claude Code나 Cursor 같은 에이전트 IDE의 agent.md(또는 CLAUDE.md)에 붙여넣기. 원문 agent.md의 간이 버전

- 사람이 읽는 글(주석, 커밋 메시지, 답변)은 최소한의 단어로 쓴다. 칭찬과 최상급은 빼고 냉정하게 말한다.
- 매직 넘버와 문자열은 설명적인 상수나 enum으로 뺀다. 한 번 쓰는 자명한 값은 그대로 둔다.
- 들여쓰기를 줄인다. early return과 continue를 쓴다.
- 함수 이름은 30자 미만으로 짧게 쓴다.
- boolean 파라미터 대신 enum을 쓴다.
- if는 한 줄이어도 항상 {}를 쓴다.
- 구현하는 기능과 무관한 코드는 건드리지 않는다. 바뀐 줄을 최소화한다.
- 멤버는 기본 private. 접근 제어자를 넓히기 전에 승인을 요청한다.
- 버그 수정 요청이면 수정 전에 테스트를 먼저 쓰고, 실패를 확인한 뒤 수정하고, 통과를 확인한다.

# 이어서 해 볼 것: 에이전트에게 "이 규칙을 적용할 때마다 [RULE:규칙이름]을 출력해"라고 시켜 어떤 규칙이 실제로 지켜지는지 세어 보세요.

Terminology

agent.md세션이 시작될 때 코딩 도구가 프롬프트에 자동으로 넣는 설정 파일이다. 팀 코딩 컨벤션 문서를 AI에게 미리 읽혀 두는 것과 비슷하다.

하네스(harness)LLM을 감싸 파일 읽기와 프롬프트 구성 등을 맡는 코딩 도구다. Claude Code나 Antigravity 같은 도구가 해당한다.

Context dilution컨텍스트가 길어질수록 모델이 중간에 있는 지시를 덜 반영하는 현상이다. 긴 회의록에서 중간 발언만 기억이 흐려지는 것과 비슷하다.

Arrow Anti-Patternif가 깊게 중첩되어 코드가 화살표처럼 오른쪽으로 밀리는 패턴이다. early return으로 펴는 것이 해법이다.