CLAUDE.md · AGENTS.md · 규칙 파일 패턴

AI 코딩 보조 도구가 늘어나면서 "프로젝트 규칙·맥락을 한 파일에 적어 두자" 는 관습이 자리 잡았습니다. 도구마다 이름과 위치가 조금씩 다르지만 의도는 비슷합니다.

1. 규칙 파일에 대한 이야기

파일	도구·생태계
CLAUDE.md	Anthropic Claude Code.
AGENTS.md	OpenAI Codex 등 다수 도구가 채택.
.cursorrules / .cursor/rules/*.mdc	Cursor (구·신 형식 공존).
.github/copilot-instructions.md	GitHub Copilot.
.windsurf/rules/*	Windsurf.
CONVENTIONS.md	aider 등에서 명시 결합.
.continue/*.md	Continue.
.zed/*	Zed.

같은 자리 (프로젝트 규칙·맥락) 를 다루지만 도구별 로딩 규칙·우선순위가 다릅니다.

AGENTS.md 의 등장 — OpenAI Codex 류 도구가 채택한 모양이 시작이라 거론되며, 도구 중립적 이름이 매력으로 작용해 다른 도구도 함께 읽거나 별칭으로 지원하는 흐름. 단일 표준은 아닙니다.

2. 위치별 우선순위

계층	위치	의미
글로벌	~/.claude/CLAUDE.md	모든 프로젝트 공통.
프로젝트	<repo>/CLAUDE.md	팀 공유 가능.
디렉터리	<repo>/<subdir>/CLAUDE.md	모노레포 한 모듈.
사용자 로컬	<repo>/CLAUDE.local.md	git 무시, 개인.

서브디렉터리에서 작업할 때 그 디렉터리의 규칙 파일이 추가로 합쳐지는 모양이 흔합니다. 우선순위·합치기 방식은 도구 문서를 따릅니다.

3. 다중 도구 환경

같은 저장소를 Claude Code · Cursor · Copilot 가 동시에 쓰는 환경:

• 단일 진실원 한 파일 — AGENTS.md 또는 CLAUDE.md 한 곳에 적고, 다른 도구의 규칙 파일은 그 파일을 참조하는 짧은 포인터만.
• 별칭 (symlink) — 한 파일을 만들고 다른 이름으로 심볼릭 링크.
• 각각 따로 적기 — 도구별로 독립 작성. 표류 위험.

자주 보이는 모양은 한 곳에 모으고 나머지는 짧게 두는 방식.

4. 합치기 메커니즘

도구는 보통 다음 방식 중 하나로 규칙을 모델 컨텍스트에 넣습니다:

• 모든 일치 파일을 단순 연결.
• 일치 파일을 시스템 프롬프트의 정해진 자리에 끼워 넣기.
• 사용자 입력에 보이지 않는 형태로 첨부.

긴 파일은 그 자체로 토큰을 쓰고 모델 추론에 영향을 줍니다.

5. 다른 길들

규칙·맥락을 모델에 전달하는 자리에서 규칙 파일 외 가닥:

• 시스템 프롬프트 직접 작성 — API 레벨에서 매번 보냄.
• Skills · Custom Modes — 작업별로 규칙·도구 묶기.
• MCP Prompts — 도구 중립적 표준 프롬프트.
• README 의 일부 — 사람용·모델용 문서를 한 자리.
• 외부 문서 + 인덱스 — docs/ 디렉터리에 규칙을 두고 규칙 파일은 짧은 라우터.

6. 좋은 규칙 파일의 결

• 짧다 — 모델이 끝까지 읽도록.
• 명확한 단위 — "절대 규칙" 과 "권장 사항" 을 시각적으로 분리.
• 예시 — 추상 표현보다 짧은 코드·명령 예시.
• 링크 — 자세한 자리는 외부 문서로.
• 버전·일자 — 변경된 시점이 보이도록.

흔히 들어가는 항목:

• 프로젝트 개요 한 문단.
• 폴더 구조 요점.
• 빌드·테스트·실행 명령.
• 코드 스타일·네이밍 규칙.
• 자주 쓰는 의존성·도구.
• 보안·시크릿 정책.
• 문서 작성 규칙 (언어·톤).
• 도구·모델에게 하지 말 것의 명시.

7. 모노레포 패턴

루트의 짧은 라우터 + 각 서비스 디렉터리의 세부 규칙으로 나누는 모양:

/CLAUDE.md            ← 서비스 맵·전역 규칙·작업 시작 절차
/services/web/CLAUDE.md
/services/api/CLAUDE.md

루트 파일이 너무 길어지면 핵심을 흘려버리는 위험이 있어 라우팅 중심으로.

글로벌 규칙 — ~/.claude/CLAUDE.md 에는 도구 사용 자체의 일반 규칙 (언어 선호 · 답변 톤 · 파일 작성 정책). 프로젝트 파일은 도메인 규칙. 두 자리를 섞으면 충돌·누락.

8. 안티패턴

너무 길어서 읽지 않음 — 수백 줄의 규칙은 모델이 일부를 무시하고, 사람도 갱신을 놓칩니다. 핵심 10~30 줄로 시작해 필요할 때 외부 문서로 분기.

같은 규칙을 여러 곳에 중복 — README.md · CONTRIBUTING.md · CLAUDE.md 에 같은 규칙이 따로 적혀 있으면 표류. 한 곳을 SSOT 로 두고 다른 곳은 참조.

모순되는 규칙 — "한국어로 답한다" + "기술 용어는 영어로" 같은 상충. 우선순위·예외를 명시.

도구 명령을 그대로 복붙 — 도구 버전이 바뀌면 깨집니다. 명령은 가능한 한 스크립트로 추상화.

시크릿·민감 정보 포함 — 규칙 파일은 git 에 커밋되는 자리. 자격증명·내부 URL 이 새는 사례.

모델에게 자기 자랑 강요 — "항상 자신만만하게 답한다" 같은 자기 강화 지시. 모델이 잘못된 답을 자신감 있게 내는 행동을 부추김. 절제·정직 쪽이 안전.

9. 짧은 템플릿

# 프로젝트 X

> 한 줄 요약. 모노레포라면 서비스 맵.

## 작업 시작 시

1. 이 파일을 읽는다.
2. 변경 대상 디렉터리의 `CLAUDE.md` 를 읽는다.
3. 필요한 경우 `docs/RULES.md` 의 §1~§N 을 본다.

## 절대 규칙

- 한국어로 답한다.
- `.env*` · 키 파일은 커밋 후보로 제안하지 않는다.
- 비가역 명령 (`rm -rf` · `DROP TABLE`) 은 사용자 확인 후에만.

## 명령

- 빌드: `pnpm build`
- 테스트: `pnpm test`
- 개발 서버: `pnpm dev`

## 디렉터리

- `apps/`: 앱.
- `packages/`: 공용.
- `docs/`: 문서.

위 결을 시작점으로 점진 확장.

10. 자주 걸리는 자리

여러 도구의 규칙 표류 — 도구별 파일이 따로 자라며 다른 답을 만듭니다. SSOT 와 라우터.

언어 혼합 — 한국어·영어를 같은 단락에서 섞으면 모델이 톤을 흔듭니다. 기준 명시.

모델별 행동 차이 — 같은 파일에 다른 모델이 다르게 반응. 추상화·예시 위주.

CLAUDE.md 만 보고 모든 답을 기대 — 문서·테스트·코드 베이스가 진짜 출처. 규칙 파일은 라우팅·요약.

변경 이력 부재 — 정책이 바뀌어도 적힌 그대로 유지. 일자·변경 기록.

서브디렉터리 누락 — 모노레포에서 모듈별 규칙이 빠져 있으면 일반 규칙으로 처리되며 도메인 특이점이 무시.

권한 모델과의 분리 — 규칙 파일은 권고이고 권한 게이트는 settings. 둘을 섞지 않습니다.

하고픈 말

규칙 파일은 짧고 라우팅 중심으로 둘 때 가장 잘 동작합니다. 길어지면 모델도 사람도 일부를 흘려보냅니다. SSOT 한 곳 + 서비스별 분리 + 서로 참조 — 이 세 자리가 운영 표준이 됩니다.

Next

• ai-coding-ides
• ai-cli-tools

Claude Code Memory · Cursor Rules · Copilot Custom Instructions · aider CONVENTIONS · OpenAI Codex · Awesome Cursor Rules 를 참고합니다.