agent.md, 코딩 에이전트 품질의 새 계약서

프롬프트에서 저장소 계약으로

Fabien Sanglard가 쓴 My agent.md to improve LLM-assisted code quality는 코딩 에이전트가 성숙하는 방향을 잘 보여준다. 더 긴 프롬프트를 매번 채팅창에 붙여 넣는 방식이 아니라, 저장소 안에 에이전트가 읽어야 할 규칙을 두고 품질을 반복적으로 끌어올리는 방식이다. 이름은 agent.md이지만 핵심은 문서 하나가 아니다. 팀이 AI에게 맡길 수 있는 일, 반드시 검증해야 하는 명령, 건드리면 안 되는 영역을 코드와 같은 버전 관리 대상으로 만드는 변화다.

이미 AGENTS.md는 여러 에이전트가 읽을 수 있는 저장소 지침 파일을 표준처럼 제안한다. GitHub도 Copilot repository custom instructions을 통해 저장소별 지시를 문서화하도록 한다. Anthropic은 Claude Code memory에서 프로젝트 지침과 반복 학습의 중요성을 다룬다. Cursor 역시 Rules로 코드베이스별 맥락을 관리한다. 서로 이름은 달라도 방향은 같다. 코딩 AI는 대화 상대가 아니라 팀 도구가 되고 있다.

좋은 agent.md는 스타일 가이드가 아니다

초기 AI 코딩 지침은 "간결하게 작성하라", "테스트를 추가하라" 같은 일반론에 머무는 경우가 많았다. 하지만 실무에서 필요한 것은 구체성이다. 어떤 패키지 매니저를 쓰는지, 어떤 테스트가 빠른 검증인지, DB 마이그레이션을 언제 금지하는지, 기존 디자인 시스템을 어떻게 따라야 하는지, 어떤 파일은 생성물이므로 수정하면 안 되는지까지 적혀야 한다.

Claude Code 세션 메시징, 에이전트 협업의 작지만 큰 변화는 코딩 에이전트가 단일 채팅을 넘어 협업 단위가 된다고 봤다. Ante, 단일 바이너리 코딩 에이전트가 겨냥한 틈는 로컬 실행과 단순 배포의 장점을 짚었다. Databricks, AI 코딩 비용을 운영 지표로 만들다는 AI 코딩을 비용과 품질 지표로 관리해야 한다고 분석했다. agent.md는 이 세 흐름을 현장 문서로 묶는다.

경쟁은 모델 성능에서 팀 규칙 적응력으로 간다

코딩 에이전트 시장은 OpenAI Codex, Claude Code, GitHub Copilot, Cursor, Windsurf 계열이 서로 다른 UX로 경쟁한다. 성능 차이는 여전히 중요하지만, 기업 구매에서는 "우리 저장소 규칙을 얼마나 안정적으로 따르는가"가 더 큰 기준이 된다. 모델이 한 번 좋은 코드를 쓰는 것보다, 매일 같은 검증 루프를 지키고 팀의 금지선을 넘지 않는 것이 더 가치 있다.

한국 개발팀에도 이 변화는 실용적이다. 많은 팀이 레거시와 신규 앱, 외주 코드, 빠른 배포 문화를 동시에 안고 있다. 이 환경에서 코딩 에이전트에게 자유도를 크게 주면 생산성보다 리뷰 부담이 먼저 늘어난다. agent.md 같은 문서는 에이전트에게 일을 덜 시키는 장치가 아니라, 더 좁고 정확하게 시키는 장치다. 특히 금융, 헬스케어, 공공 프로젝트처럼 감사와 재현성이 필요한 영역에서는 작업 지침 파일이 내부 통제 문서의 일부가 될 수 있다.

작성 원칙은 짧고 검증 가능해야 한다

agent.md가 길어질수록 좋아지는 것은 아니다. 에이전트가 매번 읽고 행동으로 옮길 수 있어야 한다. 가장 중요한 원칙은 세 가지다. 첫째, 추상적 선호보다 실행 가능한 명령을 둔다. 둘째, 파일 소유권과 금지 구역을 명확히 한다. 셋째, 최종 보고 형식을 정한다. 이 세 가지가 있으면 모델이 바뀌어도 팀의 기본 품질선은 유지된다.

또 하나 중요한 점은 문서를 코드 리뷰 대상으로 삼는 것이다. 에이전트가 반복해서 같은 실수를 하면 프롬프트를 탓하기 전에 agent.md를 수정해야 한다. 반대로 문서가 특정 모델의 습관에만 맞춰져 있으면 다른 도구로 전환할 때 비용이 커진다. 따라서 공급자별 요령보다 저장소의 사실, 팀의 검증 절차, 제품의 위험 경계를 중심으로 써야 한다.

자주 묻는 질문

Q1: agent.md와 AGENTS.md는 같은 것인가요?

A: 목적은 비슷하지만 이름과 관례는 도구마다 다를 수 있다. 중요한 것은 저장소 안에 에이전트가 따를 규칙을 버전 관리한다는 점이다.

Q2: README에 쓰면 충분하지 않나요?

A: README는 사람 중심 설명이 많다. 에이전트 지침은 검증 명령, 금지 파일, 작업 순서처럼 실행에 필요한 정보를 더 직접적으로 담는 편이 좋다.

Q3: 너무 많은 규칙이 모델 성능을 낮추지 않나요?

A: 장황한 규칙은 방해가 된다. 그러나 짧고 구체적인 규칙은 탐색 비용을 줄이고 리뷰 가능한 결과를 늘린다.

Q4: 한국 스타트업도 바로 도입할 가치가 있나요?

A: 있다. 작은 팀일수록 암묵지를 문서화하면 새 도구와 새 팀원이 들어와도 작업 방식이 흔들리지 않는다.

Q5: 가장 먼저 넣을 내용은 무엇인가요?

A: 설치 명령, 빠른 테스트 명령, 빌드 명령, 수정 금지 파일, 커밋 전 확인 사항, 최종 응답 형식을 먼저 넣는 것이 좋다.