매뉴얼 대 규칙서: 값비싼 오해
많은 팀이 AGENTS.md 파일의 역할을 오해하여 값비싼 운영상의 사각지대를 만들고 있습니다. Coldtea 엔지니어들의 최근 연구는 냉혹한 현실을 보여줍니다. 상위 1,000개의 GitHub 저장소 중 AGENTS.md 파일을 보유한 곳은 27%에 불과하며, 그중 대다수가 잘못 활용되고 있습니다. 이러한 광범위한 간과로 인해 AI 기여를 관리하는 데 중요한 공백이 발생합니다.
핵심 문제는 '운영 매뉴얼'과 '규칙서'를 혼동하는 데 있습니다. 대부분의 기존 AGENTS.md 파일은 프로젝트 아키텍처 설명이나 빌드 및 테스트를 위한 정확한 명령어를 나열하는 매뉴얼 역할을 합니다. 이들은 AI에게 '어떻게' 작동해야 하는지는 알려주지만, 결정적으로 '무엇을' 해야 하고 '무엇을 하지 말아야' 하는지는 제한하지 못합니다.
진정한 AGENTS.md는 규칙서로서, AI 에이전트를 위한 엄격한 가드레일과 명시적인 부정적 제약을 설정합니다. 이 규칙서가 없으면 에이전트는 경계 없이 작동하여 일관성 없는 기여, 예상치 못한 동작, 잠재적인 버그 유입을 초래합니다. 예를 들어, 대규모 저장소는 '하지 마라'는 규칙에 거의 두 배의 공간을 할애하는데, 이는 그들이 이러한 필요성을 명확히 이해하고 있음을 보여줍니다. 명확한 '해야 한다', '항상', '절대 하지 마라'는 지침이 없으면 잠재적으로 강력한 도구가 예측 불가능한 부채로 변합니다.
'하지 마라'의 힘: Vercel과 Bun에서 배우는 교훈
Coldtea의 연구는 선도적인 저장소들 사이의 중요한 패턴을 밝혀냈습니다. 가장 효과적인 AGENTS.md 파일은 명시적인 부정적 제약을 우선시합니다. 상위 100개 저장소는 소규모 프로젝트에 비해 무엇을 하지 말아야 하는지에 대한 규칙에 거의 두 배의 공간을 할애하며, 암시적인 '하지 마라' 문장이 784건 발견되었습니다.
이 고성능 파일들의 90%가 AI 에이전트를 안내하기 위해 '해야 한다', '항상', 또는 '절대 하지 마라'와 같은 단정적인 용어를 사용한다는 점은 놀랍습니다. 이는 우연이 아니며, 의도치 않은 행동을 방지하고 코드 무결성을 유지하기 위한 의도적인 전략으로, 강력한 시스템의 특징입니다.
구체적인 사례들이 이러한 정밀함을 뒷받침합니다. 예를 들어, Vercel의 Next.js 저장소는 커밋에서 'generated with Claude code'라는 문구를 명시적으로 금지합니다. 이러한 세부 수준은 AI의 기여가 프로젝트 표준 및 인간의 기대치와 완벽하게 일치하도록 보장합니다.
Bun의 저장소는 'NEVER run bun test directly - it won't include your changes(bun test를 직접 실행하지 마십시오. 변경 사항이 포함되지 않습니다)'라는 대문자 경고로 또 다른 강력한 예시를 제공합니다. 이러한 직접적인 금지는 모호함을 제거하여 에이전트가 빌드나 테스트 환경을 손상시킬 수 있는 해로운 명령을 실행하지 못하도록 방지합니다.
AI 에이전트는 인간의 맥락이나 직관 없이 작동하기 때문에 명확한 경계가 필수적입니다. 그들은 프로젝트 기록, 팀 규범 또는 잠재적인 부작용에 대한 암묵적인 이해가 부족합니다. 따라서 디지털 가드레일 역할을 하여 어떤 파일, 함수 또는 패턴을 철저히 피해야 하는지 정확히 알려주어야 합니다. 이러한 선제적 접근 방식은 미묘한 오류를 방지하고 코드베이스를 보호합니다.
33단어에서 14,000단어까지: 파일의 적절한 크기 찾기
AGENTS.md 파일 길이의 엄청난 변동성은 이제 막 생겨난 모범 사례를 보여줍니다. 극단적인 사례를 고려해 보십시오. VS Code의 전체 파일은 33단어에 불과하며 단순한 리다이렉트 역할을 합니다. Neovim은 35단어로 거의 비슷하며 AI가 생성한 커밋에 대한 단일 공개 규칙에 집중합니다. 반면, OpenHands 저장소는 14,000단어에 달하는 방대한 지침 세트를 제공합니다. 이러한 광범위한 스펙트럼은 최적의 청사진을 정의하는 것이 얼마나 어려운 과제인지 잘 보여줍니다.
하지만 Coldtea의 연구는 실용적인 북극성을 제시합니다. 바로 약 1,200단어의 중간 길이(median length)입니다. 이 수치는 대부분의 프로젝트에 있어 실용적인 최적의 지점으로, AI 기여자를 위한 충분한 세부 정보와 인간의 감독 및 빠른 반복에 필요한 명확성 사이의 균형을 맞춰줍니다. 이는 장황함에 빠지지 않으면서 효과적인 에이전트 경계를 설정하기 위한 현실적인 벤치마크입니다.
궁극적으로 AGENTS.md 파일의 복잡성은 프로젝트의 규모와 AI 지원을 통해 완화하려는 특정 위험에 직접적으로 맞춰져야 합니다. 작고 집중적인 유틸리티는 최소한의 가이드라인만 필요할 수 있지만, 복잡한 다중 기여자 시스템은 강력한 규칙집을 요구합니다. 컨텍스트 파일이 코딩 에이전트에게 어떻게 실질적인 도움을 주는지에 대한 더 깊은 통찰력을 얻으려면 Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?와 같은 연구를 살펴보세요.
이 글이 마음에 드셨나요? 매일 아침 이런 글을 메일로 받아보세요.
하루 한 통 · 두 번의 클릭으로 구독 취소 · 제3자 추적 없음
에이전트로부터 안전한 저장소를 위한 3단계 체크리스트
상위 1,000개의 GitHub 저장소를 분석한 후, Coldtea의 엔지니어들은 효과적인 AGENTS.md 파일의 핵심을 세 가지 체크리스트로 요약했습니다. 이는 단순한 제안이 아니라 AI 에이전트에게 정확한 명령을 제공하여 파일을 강력한 규칙집(rulebook)으로 변환하는 것에 관한 것입니다.
에이전트로부터 안전한 저장소를 위해 AGENTS.md에 다음 사항을 포함하세요:
- 최소한 하나 이상의 명시적인 '하지 마세요(don't)' 규칙. 효과적인 파일의 86%에 포함된 이 중요한 지침은 에이전트 행동에 대한 명확한 경계를 설정합니다. 이러한 부정적 제약이 없으면 에이전트는 종종 가정을 기반으로 행동하게 되며, Vercel의 Next.js에서 볼 수 있듯이 원치 않는 변경 사항이나 "생성된" 바닥글을 도입할 수 있습니다. 여기에는 에이전트가 절대로 건드려서는 안 되는 부분을 명확하게 정의하는 것이 포함됩니다.
- 커밋 및 풀 리퀘스트(pull requests) 형식을 어떻게 지정해야 하는지 꼼꼼하게 명시하세요. 성공적인 파일의 79%에서 발견되는 이 규칙은 인간이든 AI 에이전트든 누가 코드를 제출하든 관계없이 프로젝트 기록과 표준이 일관되게 유지되도록 합니다. 규정된 형식은 버전 관리 시스템의 혼란을 방지합니다.
- 테스트 실행 및 코드 린트(lint) 방법을 정확히 명시하세요. 효과적인 파일의 약 4분의 3(75%)이 이러한 정확한 지침을 제공합니다. 이는 선택 사항이 아니라 에이전트가 실행해야 할 직접적인 명령이며, 모든 기여가 통합되기 전에 품질 관문을 통과하도록 보장합니다.
자주 묻는 질문
프로젝트가 AGENTS.md 파일과 관련하여 저지르는 가장 큰 실수는 무엇인가요?
가장 흔한 실수는 AGENTS.md를 (명령어를 나열하는) 운영 매뉴얼로 취급하는 것입니다. 대신 AI 에이전트에게 무엇을 해야 하는지, 그리고 더 중요하게는 무엇을 하지 말아야 하는지를 알려주는 엄격한 규칙집으로 다루어야 합니다.
좋은 AGENTS.md 파일의 핵심 요소는 무엇인가요?
효과적인 파일에는 명시적인 부정적 제약('하지 마세요' 규칙), 커밋 및 PR 형식 지정에 대한 명확한 지침, 테스트 실행 및 코드 린트 방법에 대한 정확한 가이드라인이 포함됩니다.
대규모 프로젝트는 소규모 프로젝트와 다른 AGENTS.md 파일이 필요한가요?
네. 연구에 따르면 더 크고 복잡한 프로젝트일수록 훨씬 더 엄격한 AGENTS.md 파일을 가지고 있으며, 코드베이스를 보호하기 위해 부정적 제약('하지 마세요' 규칙)에 거의 두 배의 공간을 할애합니다.
상위 GitHub 저장소에서 AGENTS.md 파일은 얼마나 흔한가요?
아직은 비교적 드뭅니다. 상위 1,000개 GitHub 저장소를 조사한 결과, 27%만이 AGENTS.md 파일을 가지고 있었으며, 이는 AI 에이전트를 안내하는 측면에서 개선의 여지가 많음을 시사합니다.