AI 요약
코딩 에이전트를 사용할 때 프로젝트의 빌드, 테스트, 규칙 등을 정의하는 CLAUDE.md 혹은 AGENTS.md 파일은 필수적이지만, 수동으로 관리하면 프로젝트 변화에 따라 내용이 노후화되어 에이전트에게 잘못된 컨텍스트를 제공하는 문제가 발생합니다. 개발자 역세가와는 이를 해결하기 위해 agents-md-generator를 구축하여 프로젝트 초기 단계부터 에이전트용 설정 파일을 자동으로 생성하고 유지보수할 수 있는 체계를 제안했습니다. 핵심은 AI 모델이 처리할 수 있는 지시 사항의 총량이 제한되어 있다는 점을 인식하고, 코드에서 유추할 수 없는 고유한 판단 기준만을 남기는 '린(Lean)한' 관리입니다. 이 시스템은 단순한 설정 파일을 넘어 프로젝트와 함께 진화하는 생생한 문서를 지향하며, 에이전트가 최적의 성능을 낼 수 있도록 불필요한 가이드를 과감히 삭제하고 핵심 원칙(Core Principles) 위주로 구성합니다.
핵심 인사이트
- 표준 포맷 채택:
AGENTS.md는 Linux Foundation 산하 Agentic AI Foundation이 관리하며, 현재 GitHub에서 60,000개 이상의 리포지토리가 사용 중인 사실상의 표준입니다. - 지시 사항 버젯 제한: 프론티어 LLM이 확실히 따를 수 있는 지시 수는 150~200개이며, 에이전트의 시스템 프롬프트가 이를 상당수 점유하므로
AGENTS.md는 20~30행 이내로 작성해야 합니다. - 범용 호환성: Claude Code, Cursor, Zed, GitHub Copilot 등 주요 에이전트에 대응하기 위해
CLAUDE.md와AGENTS.md를 심볼릭 링크로 연결하여 단일 파일로 관리합니다. - 내용의 적시성: 6개월 전의 아키텍처 설명 등 낡은 정보는 에이전트의 판단을 흐리게 하므로, 에이전트가 코드에서 직접 유추할 수 있는 정보는 즉시 삭제해야 합니다.
주요 디테일
- 지원 도구: OpenAI Codex, Google Jules, Cursor, Zed, GitHub Copilot, Gemini CLI, Claude Code 등 광범위한 코딩 에이전트를 지원합니다.
- Core Principles 섹션: 에이전트가 구조적으로 명확히 인식할 수 있도록 섹션화하며, '20-30행 규칙 준수'와 '명시적 요청이 없는 한 하위 호환성 무시' 등의 강력한 원칙을 포함합니다.
- 작성 지침: 코드 스타일(린터가 해결 가능)이나 디렉토리 구조(수시로 변경됨) 대신, 비자명한 빌드/테스트 명령이나 도메인 특화 용어 등 AI가 추측할 수 없는 정보만 기록합니다.
- Maintenance Notes: 템플릿 내에서 유일하게 삭제하지 않도록 명시된 섹션으로, 사용자가 플레이스홀더를 제거하고 파일을 간결하게 유지하도록 유도합니다.
- 캐치올 섹션 배제: 'Important Context'와 같은 모호한 섹션은 정보의 쓰레기통이 되어 지시 버젯을 낭비하므로 생성을 지양합니다.
향후 전망
- 자동화된 문서 관리: 수동으로 업데이트하던 설정 파일이
agents-md-generator와 같은 도구를 통해 프로젝트의 코드 변화와 동기화되는 AI 네이티브 개발 문화가 확산될 것입니다. - 에이전트 최적화 경쟁: 에이전트 성능 극대화를 위해 컨텍스트 윈도우를 효율적으로 사용하는 '컨텍스트 엔지니어링'의 중요성이 더욱 커질 것으로 예상됩니다.