CLAUDE.md / AGENTS.md / .cursorrules — AI 시대의 영구 지시어
1. 요약
CLAUDE.md·AGENTS.md·.cursorrules는 AI 코딩 도구의 프로젝트 헌법 이다. 매 세션마다 같은 지시를 반복하지 않도록, 프로젝트 루트에 영구 지시어 파일을 기록하는 패턴이다.
- CLAUDE.md — Anthropic Claude Code의 표준 (2024)
- AGENTS.md — OpenAI Codex·Cursor 등 다중 도구의 합의 표준 (2024)
- .cursorrules — Cursor 전용 (2023~)
- .windsurfrules — Windsurf 전용
2. 배경 — 매 세션 같은 지시 반복의 비용
LLM 코딩 도구가 보편화되면서 새 문제가 기록되었다. 매 세션마다 "한국어로 답해라·CLAUDE.md를 따라라·테스트 먼저 짜라·로깅은 이렇게 해라" 같은 프로젝트별 규칙 을 반복해야 했다.
이는 컨텍스트 부패(Context Rotting) 와도 직결된다. 토큰이 길어지면 모델 성능이 감소하고, 같은 지시를 반복하면 프로젝트 본연의 작업에 쓸 토큰이 줄어든다.
해결책은 단순했다. "프로젝트 루트에 영구 지시어 파일을 두고, 매 세션 시작 시 자동 로드" — 이것이 CLAUDE.md의 출발이다.
3. 핵심 특징
CLAUDE.md
- Anthropic 공식 지원 — Claude Code가 자동으로 읽음
- 계층 구조 — 글로벌(
~/.claude/CLAUDE.md) · 프로젝트(./CLAUDE.md) · 하위 폴더 가능 - 마크다운 자유 형식 — 프로젝트 규칙·코딩 컨벤션·도구 사용법·도메인 지식
- MCP·Skills·Slash Commands 와 통합
AGENTS.md
- 다중 도구 합의 표준 (2024) — Cursor·Copilot·Claude·OpenAI Codex가 공통 인식
- CLAUDE.md의 agentic 측면 을 박은 형식
- 반복적 작업 지시·도구 사용·테스트 정책 명시
.cursorrules
- Cursor 전용 (2023~)
- 단순 텍스트 파일 — 자유 형식
- 현재는 .cursor/rules/ 디렉토리 구조로 진화*
4. 주 용도 — 영구 지시어가 기록하는 자리
| 자리 | 기록하는 내용 |
|---|---|
| 소통 규칙 | "한국어로 답해라" / "코드 주석은 영문" |
| 코딩 컨벤션 | 들여쓰기·네이밍·import 순서 |
| 테스트 정책 | TDD 강제·커버리지 임계 |
| 도메인 지식 | 비즈니스 용어·약어 사전 |
| 금지 사항 | "절대 production DB를 건드리지 마라" |
| 도구 우선순위 | "Bash 대신 Glob·Grep을 써라" |
| 에이전트 라우팅 | "보안 검토는 reviewer 에이전트가" |
5. 시대 설계 도구 매핑
CLAUDE.md는 "프로젝트 규칙을 코드 외부에 기록한다" 는 패턴의 LLM 시대 박음이다. 같은 패턴은 30년 전부터 기록되어 있었다.
- Makefile(1976) — 빌드 규칙을 외부 파일에
- .gitignore(2005) — Git 규칙을 외부 파일에
- .editorconfig(2011) — 편집기 규칙을 외부 파일에
- package.json·pyproject.toml — 의존성 규칙을 외부 파일에
- CLAUDE.md(2024) — AI 협업 규칙을 외부 파일에
이 흐름이 "설계 결정을 문서화 해서 재사용·검증·진화 가능하게 기록한다" 는 일관된 원리다.
6. 강의 활용
CLAUDE.md는 강의의 "AI 시대의 설계 도구" 의 결정적 사례다. 70년 전 어셈블리 시대 "머릿속 설계" 에서, C 시대 "주석 + 헤더 파일 설계", OOP 시대 "UML 다이어그램 설계", 마이크로서비스 시대 "API 명세 + ADR 설계" 를 거쳐, 지금은 "CLAUDE.md + Spec Kit 설계" 가 기록된다.
핵심 메시지 세 가지를 기록한다.
1. 영구 지시어 = 매 세션 다시 박지 않아도 되는 설계
일회성 프롬프트는 매번 박아야 한다. CLAUDE.md는 한 번 박으면 영원히 적용 된다. 이는 함수·클래스·라이브러리 의 본질과 같다 — 재사용 가능한 단위 다.
2. 프로젝트 헌법이 곧 팀 합의
사람과 AI 협업, 사람과 사람 협업 모두에 같다. CLAUDE.md는 팀의 설계 결정을 명시적으로 박아서 모두가 같은 규칙을 따르게 한다. 이는 Coding Standards·Style Guide 의 LLM 시대 박음이다.
3. 컨텍스트 위생(Context Hygiene)이 새 학문
CLAUDE.md를 어떻게 박을 것인가 가 새 설계 분야로 박히고 있다 — 본 위키의 Context Engineering 트랙이 이를 다룬다. 너무 길면 부패하고, 너무 짧으면 부족하다. 명확함·구조화·우선순위 가 새 설계 원리다.
본 위키 자체가 CLAUDE.md 시대의 산물이라는 점을 강조한다. 학생들이 "매일 30개 파일을 만들고 또 만드는 일 을 CLAUDE.md 한 번 박음으로 해결한 사례를 보면서, 이 도구의 위력을 체감하게 한다.
출처
- Claude Code 공식 문서 - Anthropic
- GitHub Spec Kit - speckit.org
- Spec-Driven Development with Claude Code in Action - alexop.dev
- Chapter 16: Spec-Driven Development with Claude Code
그룹 시리즈
→ synthesis/group-g7 (시대 그룹 종합 카드)