프로젝트 규칙 파일 작성하기: AI 에이전트가 실제로 따를 수 있는 방법

범용 규칙 파일은 에이전트에게 '어떻게 행동해야 하는지'를 알려줍니다. 하지만 프로젝트가 어떻게 작동하는지(테스트를 실행하는 명령어, 공유 헬퍼가 어디에 있는지, 절대 건드려서는 안 되는 폴더 등)는 알려줄 수 없습니다.

프로젝트 규칙 파일이 바로 이런 역할을 합니다. UNIVERSAL-AGENTS.md에서는 이를 AGENTS.project.md라고 부르며, 이 게시물에서는 좋은 파일을 작성하는 방법을 보여줍니다.

두 파일의 연동 방식

범용 규칙의 섹션 23은 지침이 충돌할 때 우선순위를 설정합니다:

1. 현재 사용자 요청에 명시된 지침
2. 프로젝트별 규칙
3. 기존 프로젝트 컨벤션
4. 범용 AGENTS.md
5. 일반적인 구현 선호도

섹션 34.1은 AGENTS.project.md를 프로젝트 규칙의 홈으로 지정합니다. 따라서 분리가 깔끔합니다:

• AGENTS.md는 범용적으로 유지되어 프로젝트별로 편집할 필요가 없습니다.
• AGENTS.project.md에는 이 리포지토리에만 특화된 모든 것이 담깁니다.

한 가지 예외 사항은 안전 규칙(섹션 27, 28, 29 및 33)입니다. 이 규칙들은 프로젝트 규칙에 의해 완화될 수 없습니다. 오직 사용자로부터의 명시적인 지침만이 이를 재정의할 수 있습니다.

템플릿으로 시작하기

cp templates/AGENTS.project.template.md AGENTS.project.md

이 템플릿은 열 개의 섹션으로 구성되어 있습니다. 모든 섹션을 사용할 필요는 없습니다. 적용되지 않는 것은 삭제하고 파일을 간결하게 유지하세요. 에이전트는 이 파일을 컨텍스트 창에 로드하며, 매 줄마다 비용이 발생하기 때문입니다.

작성된 예시

여기 TypeScript로 작성된 청구서 API라는 가상의 프로젝트가 있습니다. 사용자의 스택에 맞게 조정하십시오.

# Project Rules (AGENTS.project.md)

## 1. Project overview
...

각 섹션이 자리를 차지하는 이유

명령어(Commands). 이 부분이 가장 가치가 높습니다. 이것이 없으면 에이전트는 pnpm 프로젝트에서 npm test를 추측하거나, 한 파일만 하면 되는 경우에도 전체 테스트 스위트를 실행합니다. 정확한 명령어는 또한 에이전트의 검증 보고서(섹션 21)를 신뢰할 수 있게 만듭니다.

아키텍처 및 계층화(Architecture and layering). 섹션 5는 이미 에이전트에게 새로운 코드를 작성하기 전에 기존 코드를 재사용하도록 지시합니다. src/lib를 지정하는 것은 에이전트가 어디를 봐야 하는지 알려주는 것이므로, 네 번째 날짜 형식 도우미(date-formatting helper)를 만들 필요가 없습니다.

보호 영역(Protected areas). 섹션 8은 에이전트가 요청 범위 외의 것을 건드려서는 안 된다고 명시합니다. migrations/와 생성된 파일들을 이름으로 지정하면 일반 원칙을 강력한 경계로 만듭니다.

승인 필요(Approval required). 의존성(Dependencies), 마이그레이션(Migrations), CI 변경 사항은 사람들이 검토하지 않은 것을 가장 후회하는 변화들입니다. 이를 나열한다는 것은 에이전트가 먼저 질문하도록 만든다는 의미입니다.

동기화해야 하는 문서화(Documentation to keep in sync). 섹션 9는 문서가 코드와 일치해야 한다고 요구합니다. "X가 변경될 때 Y를 업데이트하라"는 표는 에이전트가 이를 신뢰성 있게 수행하도록 합니다.

테스트 기대치(Testing expectations). 이는 테스트를 요청받았거나 프로젝트 규칙에서 필요할 때만 추가하라고 명시한 섹션 19를 구체화합니다. 만약 귀사의 규칙이 "버그 수정 시마다 회귀 테스트(regression test)가 필수"라면, 이를 여기에 명시하면 에이전트가 따르게 됩니다.

알려진 함정(Known pitfalls). 여기에 한두 줄만 추가해도 많은 낭비되는 실행을 막을 수 있습니다.

파일 에이전트가 따라야 할 팁

• 구체적이고 테스트 가능하게 작성하세요. "라우트는 데이터베이스를 직접 쿼리해서는 안 된다"는 지침이 "코드를 깨끗하게 유지하라"보다 효과적입니다.
• 설명이 아닌 정확한 명령어를 사용하세요.
• 보호 경로에 대해서는 몇 마디로 '왜' 그런지 설명하세요 ("적용된 마이그레이션은 절대 수정되어서는 안 된다"). 이유를 제시하는 것이 에이전트가 엣지 케이스(edge cases)에서 좋은 판단을 내리도록 돕습니다.
• 간결하게 유지하세요. 에이전트가 코드로부터 추론할 수 있는 것은 모두 잘라내세요.
• 보편적인 규칙을 반복하지 마세요. 프로젝트에 고유한 내용을 추가하세요.
• 현실이 바뀔 때 업데이트하세요. 오래된 규칙 파일은 아예 없는 것보다 더 나쁩니다.

모노레포(Monorepos)

섹션 34.2에서 이를 다룹니다: 변경되는 파일과 가장 가까운 AGENTS.md가 해당 서브트리(subtree)에 대한 우선권을 가지며, 이 파일에 언급되지 않은 규칙은 여전히 보편적인 파일의 규칙이 적용됩니다. 각 패키지에 자체 명령어와 레이아웃을 가진 작은 AGENTS.md를 배치하세요.

연결하기 (Wire it up)

만약 사용하려는 도구가 AGENTS.md 파일을 네이티브하게 읽지 못한다면, adapters/ 폴더에서 해당되는 파일(Claude Code, Gemini CLI, GitHub Copilot, Cursor)을 복사하세요. 어댑터들은 이미 도구에게 AGENTS.project.md를 읽도록 지시합니다. 사용하려는 도구의 문서를 확인하여 기대하는 파일 형식을 검토해 보세요.

👉 https://github.com/NTDevLops/UNIVERSAL-AGENTS.md (MIT 라이선스)

프로젝트에서 모든 새로운 기여자(인간이든 AI든)가 가장 먼저 읽었으면 하는 한 줄은 무엇인가요? 댓글로 공유해 주세요.