코딩 AI에게 줄 팀 규칙을 한 파일로 정리하는 6단계

이런 상황이라면

팀에서 코딩 에이전트를 쓰기 시작했는데, 사람마다 다른 도구를 쓰고 결과물의 스타일도 제각각입니다. 패키지 매니저를 npm으로 통일했는데 에이전트는 yarn 명령을 내놓고, 테스트를 돌리라고 했는데 엉뚱한 명령을 씨니다. 이 워크플로우는 그 규칙을 AGENTS.md 파일 하나로 모아 어느 에이전트를 써도 같은 절차를 따르게 만드는 순서입니다. 대상은 코딩 에이전트를 도입했거나 도입을 준비하는 개발팀입니다.

도입 전과 후

• 도입 전 — 도구마다 지침 파일이 따로 놀았습니다. 같은 내용을 여러 파일에 중복으로 적고, 하나를 고치면 나머지가 낡았습니다
• 도입 후 — 저장소 최상위의 AGENTS.md 한 장을 서로 다른 에이전트가 같이 읽습니다 ^[1]
• 공식 사이트 기준 6만 개 이상의 오픈소스 프로젝트가 이 형식을 쓰고 있습니다 ^[1]
• 지원 도구는 25종 이상입니다. 도구를 바꿔도 지침은 그대로 가져갑니다 ^[1]
• 2025년 OpenAI 코덱스, 구글 줄스, 커서, 팩토리, 앰프가 공동 제정했고 이후 리눅스재단 산하 재단이 관리합니다 ^[1][3]

한 가지 주의가 필요합니다. 파일을 만든다고 품질이 자동으로 오르지는 않습니다. 깃허브가 2,500개 이상 저장소를 분석해 내놓은 결론도 구체성이 전부라는 것이었습니다 ^[2].

전체 흐름

현재 규칙 모으기 → 초안 작성 → 명령어 검증 → 실제 작업으로 테스트 → 범위 분리 → 갱신 규율화 순서입니다. 핵심은 문서를 예쁘게 쓰는 것이 아니라, 에이전트가 그대로 실행할 수 있는 명령과 예시를 넣는 것입니다.

단계별 설계

1. 현재 규칙 모으기 — 사내 위키, README, 코드 리뷰에서 반복된 지적을 한데 모읍니다. 사람에게 가장 자주 설명했던 내용이 에이전트에게도 가장 필요한 내용입니다.
2. 초안 작성 — 저장소 최상위에 AGENTS.md를 만들고 설치·빌드·테스트 명령 세 가지부터 적습니다 ^[1]. 정해진 항목은 없으니 필요한 섹션만 두면 됩니다. 아래 템플릿을 그대로 복사해 빈칸을 채우세요.

# AGENTS.md

## 프로젝트 개요
- 무엇을 하는 서비스인지 2줄로
- 주요 기술 스택: (예: Next.js 15, TypeScript, PostgreSQL)

## 설치와 실행
\`\`\`bash
pnpm install
pnpm dev
\`\`\`

## 테스트
- 전체 테스트: \`pnpm test\`
- 단일 파일: \`pnpm test <파일경로>\`
- PR 전에 반드시 전체 테스트를 통과시킬 것

## 코드 규칙
- 패키지 매니저는 pnpm만 사용(npm·yarn 금지)
- 함수형 스타일 선호, 클래스 상속 지양
- 예시)
  - 좋음: \`const getUser = (id: string) => ...\`
  - 지양: \`function GetUser(id) { ... }\`

## 하지 말 것
- \`src/legacy/\` 아래 파일은 수정하지 말 것
- 의존성을 임의로 추가하지 말 것. 필요하면 PR 설명에 이유를 적을 것

## PR 규칙
- 제목 형식: [영역] 요약 (예: [auth] 로그인 만료 처리 수정)
- 변경 이유를 본문 첫 줄에 한 문장으로

1. 명령어 검증 — 적어 둔 명령을 터미널에 그대로 붙여 넣어 실행해 봅니다. 하나라도 안 돌아가면 에이전트도 똑같이 실패합니다. 깃허브 가이드가 명령어를 복사 가능한 코드블록으로 쓰라고 강조하는 이유입니다 ^[2].
2. 실제 작업으로 테스트 — 작은 이슈 하나를 에이전트에게 맡기고 규칙을 어기는 지점을 기록합니다. 어긴 부분이 곳 문서가 비어 있거나 모호한 부분입니다. 아래 프롬프트로 점검을 맡겨도 됩니다.

이 저장소의 AGENTS.md를 읽고, 코딩 에이전트 입장에서 부족한 점을 짚어 주세요.

다음 기준으로 점검해 주세요.
1. 복사해 바로 실행할 수 없는 명령이 있는가
2. "깔끔하게", "적절히" 처럼 판단이 갈리는 표현이 있는가
3. 금지 사항이 구체적으로 적혀 있는가
4. 코드 예시가 없어 해석이 갈리는 규칙이 있는가

문제마다 고쳐 쓸 문장을 그대로 제안해 주세요.

1. 범위 분리 — 모노레포라면 하위 패키지별로 AGENTS.md를 따로 둡니다 ^[2]. 최상위에는 공통 규칙만 남기고 패키지 고유 규칙은 그 폴더로 내립니다.
2. 갱신 규율화 — 빌드·테스트 명령이나 폴더 구조를 바꿀 때 AGENTS.md도 같이 고치도록 코드 리뷰 체크리스트에 넣습니다. 낡은 안내문은 없는 것보다 위험합니다.

주의점

• 길이가 공짜가 아닙니다 — 파일이 길어질수록 그 자체가 컨텍스트를 차지해 정작 코드를 읽을 여유가 줄어듭니다. 자세한 배경 설명은 별도 문서로 빼고 링크만 남기세요. 컨텍스트 롯 항목을 함께 보면 좋습니다 ^[6].
• 모호한 형용사는 지우기 — "깔끔한 코드를 쓰세요" 같은 문장은 사람에게도 에이전트에게도 아무 기준이 되지 못합니다. 규칙은 예시 코드와 쌍으로 쓰세요 ^[2].
• 비밀값은 절대 금지 — API 키나 내부 서버 주소는 적지 않습니다. 공개 저장소라면 그대로 노출됩니다.
• 도구별 파일과의 관계 — 이미 CLAUDE.md 같은 파일을 쓰고 있다면 내용을 AGENTS.md로 옮기고 기존 파일은 참조만 하게 줄이는 방식이 흔합니다 ^[5].

확장

• 여러 저장소를 운영한다면 공통 섹션을 사내 표준 템플릿으로 만들어 새 저장소 생성 시 자동으로 복사되게 합니다
• 온보딩 문서와 합치면 사람 신입과 에이전트가 같은 문서로 출발하게 됩니다
• 클로드 코드, 커서 등 팀에서 쓰는 도구가 같은 파일을 읽는지 도구 목록에서 확인해 둡니다 ^[1]

바로 열어볼 자료

• AGENTS.md 공식 사이트 — 형식 설명과 예시 파일, 지원 도구 목록 ^[1]
• 깃허브 작성 가이드 — 2,500개 저장소에서 뽑은 작성 원칙 ^[2]