agent.md로 LLM 코딩 품질을 끌어올리는 법 — 반복하는 코딩 지시를 파일로 저장한다

핵심 요약

• LLM 코딩 어시스턴트를 쓰면 속도는 빨라지지만 코드 품질이 나빠진다 — 스파게티 코드, 주석 없음, 구조 없음. 속도 이득이 코드 정리에 잠식되는 문제입니다.
• 게임 개발자 Fabien Sanglard는 이 문제를 agent.md로 해결했습니다. 에이전트 세션이 시작될 때 자동 로드되는 지침 파일에 자신의 코딩 스타일을 명시한 것입니다.
• 핵심 통찰: LLM을 개인 코딩 스타일에 맞추는 방법은 "무한한 인내심을 가진 주니어 개발자를 반복적으로 교정하듯 지시" 하는 것인데, 이 지시를 매번 반복하는 대신 파일에 저장합니다.
• 효과: 코드 품질이 손으로 쓴 수준에 근접. 그리고 "스타일 교정"이라는 반복 노동에서 벗어나, 아키텍처·설계에 집중할 수 있게 됩니다.
• 다만 마법은 아닙니다. 저자가 강조하듯 LLM은 여전히 환각하고, 사람이 코드를 읽고 검증해야 합니다. agent.md는 "스타일"을 잡아주지 "정확성"을 보장하지 않습니다.

agent.md: 반복하는 코딩 지시를 파일로 저장

agent.md는 에이전트 코딩 하네스가 세션 시작 시 자동으로 프롬프트에 주입하는 지침 파일 도구입니다. LLM 코딩의 현실을 겪어본 사람은 같습니다. 첫 시도는 실패했고, 조금 나아졌지만, 코드 품질이 기준 이하입니다. Fabien Sanglard의 경험도 비슷합니다.

• 2025년 중반, 첫 LLM 코딩 시도 — 코드가 컴파일도 안 됨
• 2026년 1월, 재시도 — 인덱스드 바이너리 힙을 쓰고, OS 버그까지 잡아냄. 하지만 코드가 스파게티
• 2026년 3월, 에이전틱 IDE 사용 — 코드 품질이 극적으로 개선, 하지만 매 세션 같은 지시를 반복해야 함

여기서 핵심 전환이 옵니다. 에이전트 하네스(Claude Code, Antigravity 등)는 세션 시작 시 agent.md 파일을 자동으로 프롬프트에 주입합니다. 이 파일이 바로 "반복되는 코딩 스타일 지시"를 넣을 완벽한 위치입니다.

저자가 반복했던 지시를 모아둔 파일이 공개돼 있습니다 (agent.md).

agent.md가 담는 것

이 파일은 구체적인 코딩 규칙 모음입니다. 몇 가지 핵심을 보면:

• 주석/커밋 메시지는 최소한의 단어로. 칭찬·수사 빼고 핵심만.
• 매직 넘버/문자열 지양. 상수·enum으로 추출. 단, 사양에서 온 값(HTTP 200)은 항상 상수로.
• 들여쓰기 줄이기. Arrow Anti-Pattern 피하고 early return 활용.
• 함수명 30자 이내. boolean 대신 enum을 파라미터로.
• 논리 블록 사이 빈 줄. 독자가 숨 쉬게.
• 접근 제어는 설계적 결정. private 유지, 변경 시 명시적 승인 요구.
• 레이어 경계 엄수. 컨트롤러/UI가 DB·하드웨어에 직접 접근 금지, 항상 서비스 계층 경유.
• 커밋 메시지 7규칙 — 50자 제목, 명령형, what/why 분리 등.
• 버그 수정 시 TDD — 수정 전에 실패하는 테스트 먼저.

이 규칙들은 대부분 "이미 알고 있지만 반복해서 말하기 귀찮은" 것들입니다. agent.md는 그 반복을 없앱니다.

주목할 부분: "관련 없는 코드를 건드리지 마라"

이 파일에서 가장 통찰적인 규칙이 있습니다.

"구현하는 기능과 무관한 코드 블록을 건드리지 마라. 만든 적도 수정한 적도 없는 코드에 주석을 달지 마라. 기능을 구현할 때 변경하는 라인 수를 최소화하라."

이것은 LLM 코딩의 특유 문제를 겨냥합니다. LLM은 관련 없는 코드까지 "정리"하면서 diff를 부풀리고, 리뷰 비용을 키웁니다. 변경 최소화는 LLM 에이전트가 존중하지 못하는 원칙이라, 명시적으로 지시해야 합니다.

주목할 부분: "칭찬하지 마라"

또 하나 흥미로운 규칙:

"칭찬과 수사를 피하라. 내가 완전히 맞다고 말하지 마라. 냉정한 사실을 말해라."

이건 우리가 Claude의 BuzzFeed 말투에서 다룬 "AI 슬롭"과 정확히 연결됩니다. 에이전트가 "훌륭합니다!"라고 칭찬하는 건 신호 대 잡음비를 떨어뜨리는 노이즈입니다. 코드 리뷰에서 칭찬은 정보가 아니므로, 금지 지시로 제거합니다.

한계: context dilution과 환각

저자는 agent.md가 만능이 아님을 분명히 합니다.

첫째, 컨텍스트 희석(context dilution) — Lost in the Middle 논문이 지적하듯, 컨텍스트가 길어질수록 모델은 중간의 지시에 덜 주의를 기울입니다. 두 가지 완화책이 있습니다.

1. 컨텍스트를 짧게 — 기능마다 새 세션 시작
2. 명시적으로 agent.md 재로드 — 코드 품질이 떨어질 때 "reload agent.md"

둘째, 환각 — "LLM은 끊임없이 환각하고 신뢰할 수 없다. 여전히 코드를 읽고 검증해야 한다."

즉, agent.md는 스타일 문제를 해결하고, 사용자를 아키텍처 검토에 집중하게 만들지만, "코드가 정확하다"는 보장은 하지 않습니다. 사람의 검증은 여전히 필수입니다.

자동 업데이트: 에이전트가 자신의 규칙을 갱신

마지막으로 저자는 agent.md를 수동으로 편집하지 않는다고 합니다. 반복되는 새 지시가 보이면, 에이전트에게 "agent.md에 이 규칙을 추가해줘"라고 시킵니다. 이렇게 하면 규칙 파일이 점진적으로 발전합니다.

이 부분은 우리가 쓴 자가개선와 연결됩니다. agent.md 자동 갱신은 하네스 하나로 순간적으로 되는 게 아니라, 사용자가 계속 지시를 관찰하고 규칙을 축적하는 점진적 과정입니다.

판단 — agent.md의 실용 가치

agent.md를 코딩 워크플로에 적용하는 판단 기준입니다.

• "반복해서 말하는 것"을 나열하라. 자주 내는 코딩 지시(주석, 매직넘버, 함수명, 레이어 경계)를 모아 agent.md에 넣습니다.
• 변경 최소화를 명시하라. "관련 없는 코드를 건드리지 마라"는 LLM이 자연스럽게 어기는 규칙이라, 꼭 넣어야 합니다.
• 칭찬을 금지하라. "훌륭합니다" 같은 수사는 신호 대 잡음비를 떨어뜨립니다.
• 레이어 경계를 강제하라. LLM은 아키텍처 규칙을 잘 어기므로, 서비스 계층 경유를 명시합니다.
• agent.md를 자동 갱신하라. 새 지시가 반복되면 에이전트에게 규칙 추가를 시킵니다.
• 그래도 검증은 사람이. agent.md는 스타일을 잡아줄 뿐, 환각은 막지 못합니다. 아키텍처 검토에 집중하되 코드는 읽어야 합니다.

결론은 이렇습니다. agent.md는 LLM 코딩의 "스타일 난제"를 실용적으로 해결하는 도구입니다. 반복되는 코딩 지시를 파일로 저장해, 에이전트를 개인 코딩 스타일에 맞추고, 사용자가 아키텍처에 집중하게 합니다. 다만 스타일과 정확성은 별개라는 점을 잊으면 안 됩니다. agent.md는 코드 품질을 끌어올리는 기반이지만, 그 위에서 사람의 검증이 여전히 필요합니다.

참고 링크

• My agent.md to improve LLM-assisted code quality — Fabien Sanglard
• FAB's agent.md (전문)
• Lost in the Middle — arXiv 2307.03172