지시 파일은 많은 것을 말하는 문서가 아니다. 지금 어디에 서 있는지, 어느 방향으로 가야 하는지, 무엇을 넘으면 안 되는지를 알려주는 작은 지도에 가깝다. 좋은 지시는 모든 걸 대신 판단하지 않는다. 판단이 길을 잃지 않게 만든다.
CLAUDE.md, AGENTS.md, .cursor/rules/가
이름은 달라도 같은 문제를 푼다고 본다.
차이는 파일명이 아니라 얼마나 얇고, 얼마나 가까운 맥락을 불러오며,
얼마나 실제 실패를 기억하는가에 있다.
Claude Code의 지시 시스템은 전역·프로젝트·하위 디렉터리의 세 층으로 상속된다. 로딩은 넓은 곳에서 좁은 곳으로 진행되고, 뒤에 불린 더 가까운 규칙이 더 높은 우선순위를 갖는다. 형식은 일반 Markdown이며 저장소에 함께 커밋해 팀이 공유할 수 있다.
~/.claude/CLAUDE.md
모든 프로젝트에 적용할 일반 선호
./CLAUDE.md
프로젝트 고유의 구조와 제약
module/CLAUDE.md
모듈별 규칙 · 상위 규칙을 더 구체적으로 덮음
원문의 저자는 여러 종류의 일을 한 저장소에서 다루며
Root CLAUDE.md를 구체 규칙이 거의 없는 라우터로 사용한다.
먼저 현재 작업이 어느 workspace에 속하는지 판정하고,
해당 하위 디렉터리의 규칙만 읽게 한다.
/01-公众号写作/CLAUDE.md로 연결
/02-小红书写作/CLAUDE.md로 연결
/03-视频创作/CLAUDE.md로 연결
/09-实验项目/의 로컬 규칙을 읽음
원문이 소개하는 OpenAI Codex 팀의 방식은 더 얇다.
AGENTS.md는 상세한 모든 지식을 품는 문서가 아니라
프로젝트 개요, 핵심 명령, 아키텍처 지도와 전문 문서의 위치를 알려주는 포인터다.
무엇을 만드는 저장소인지, React + FastAPI + PostgreSQL 같은 기술 스택을 짧게 알린다.
pnpm dev, pnpm test, pnpm type-check처럼 Agent가 추측하기 어려운 실행 명령을 둔다.
상세 설명을 모두 넣는 대신 약 200줄의 docs/ARCHITECTURE.md로 연결한다.
설계 결정, 실행 계획, 제품 사양, 참고 자료, ADR을 각각 다른 디렉터리에서 관리한다.
코드는 고정 방향으로만 의존하며 위반은 CI가 차단한다.
AGENTS.md # ~100줄 · 목차 + 포인터 ARCHITECTURE.md # ~200줄 · 코드베이스 지도 docs/ ├── design-docs/ # 핵심 설계 결정 ├── exec-plans/ # 활성 작업 · 기술 부채 ├── product-specs/ # 기능 명세 ├── references/ # 디자인 시스템 등 참고 문서 └── decisions/ # Architecture Decision Records
Cursor의 두드러진 특징은 glob scoping이다. 모든 규칙을 매번 읽히는 대신 현재 편집하는 파일이 어느 경로에 있는지에 따라 해당 규칙만 활성화할 수 있다.
--- description: API 계층 코딩 규범 globs: src/api/**/*.ts alwaysApply: false --- # API 계층 - 모든 API 함수는 반환 타입을 명시 - 오류는 공통 AppError 사용 - 요청·응답 타입은 파일 상단에 정의 - API 계층에서 비즈니스 로직 판단 금지
--- description: React 컴포넌트 규범 globs: src/components/**/*.tsx alwaysApply: false --- # 컴포넌트 - 함수형 컴포넌트 + hooks - Props는 interface - 한 파일 200줄 이하 - Tailwind 사용, CSS Modules 미사용
| 활성화 방식 | 언제 로드되는가 | 어울리는 규칙 |
|---|---|---|
alwaysApply: true |
매 세션 자동 활성화 | 공통 규범, 프로젝트 구조 |
| glob match | 관련 파일이 컨텍스트에 들어왔을 때 | 모듈·경로별 특화 규칙 |
| 수동 @mention | 사용자가 명시적으로 불렀을 때 | 가끔만 필요한 특수 규칙 |
| AI 판단 | description을 바탕으로 Agent가 결정 |
상황 의존적 지침 |
원문은 여러 AI 개발 도구의 지시 파일이 본질적으로 “Markdown으로 프로젝트 규칙을 전달하는 인터페이스”로 수렴하고 있다고 본다. 제품별 이름보다 내용의 이식 가능성이 중요해지고 있다는 주장이다.
원문은 2026년 3월 AGENTS.md가 Linux Foundation 산하 Agentic AI Foundation의 관리로 들어갔고,
Sourcegraph·OpenAI·Google·Cursor·Factory 등이 이를 추진했다고 서술한다.
또한 Windsurf의 AGENTS.md 자동 인식, Copilot 지시 형식의 유사화, Gemini의 GEMINI.md 등장도 함께 언급한다.
| 차원 | Claude Code | Codex CLI | Cursor |
|---|---|---|---|
| 파일 형식 | 순수 Markdown | 순수 Markdown | MDC · Markdown + YAML |
| 계층 수 | 3 · 전역 / 프로젝트 / 하위 디렉터리 | 4 · override / agents / team_guide / .agents | 2 · 전역 / 프로젝트 |
| Glob Scoping | 없음 · 하위 디렉터리로 해결 | 없음 | 있음 · frontmatter의 globs |
| 팀 공유 | 가능 · Git 커밋 | 가능 · Git 커밋 | 가능 · Git 커밋 |
| Import | @path/to/file |
없음 | 없음 |
| 원문 기준 cross-tool 호환 | 없음 | Windsurf 자동 호환 | 없음 |
이 장의 후반은 도구 비교에서 다시 글쓰기의 원칙으로 돌아온다. 방향감을 주되 모든 단계를 고정하지 않고, 해야 할 일을 늘어놓기보다 넘으면 안 되는 경계를 선명하게 하며, 실제 실수를 팀의 제도 지식으로 축적한다.
“컴포넌트를 만들 때 폴더 생성 → index.tsx → types.ts → CSS 파일 → import → default export”처럼 모든 동작을 순서대로 적으면 예외 상황에서 Agent가 경직된다. 대신 어디에 두고, 무엇을 사용하며, 어떤 크기를 넘지 않는지 알려준다.
상황이 달라도 같은 6단계를 강제한다. 절차가 규칙을 대신한다.
공유 컴포넌트 위치, Tailwind 사용, 200줄 제한, Props의 interface 사용만 명시한다.
원문은 OpenAI의 architectural invariants를 반직관적이지만 효과적인 방식으로 소개한다. 사용할 수 있는 모든 선택지를 설명하는 대신 프로젝트에 존재하지 않는 선택지를 먼저 제거한다. 해 공간이 줄어들수록 Agent가 헤맬 수 있는 방향도 줄어든다.
원문은 Boris Cherny의 약 100줄짜리 CLAUDE.md를 예로 든다.
500~1000줄짜리 파일보다 짧은 이유는 실제로 Agent가 잘못한 것만 기록하고
필요가 사라진 문장은 다시 삭제하기 때문이다.
팀은 PR에서 @.claude 태그를 사용해 수정 경험을 지시 파일로 되돌린다고 서술된다.
마지막 표는 지시 파일의 경계를 실용적으로 정리한다. Agent가 코드만 보고 알아낼 수 없는 것, 기본값과 다른 것, 프로젝트에서 실제로 자주 틀리는 것을 쓴다. 나머지는 코드와 문서와 도구에게 맡긴다.
pnpm vitest run좋은 지시 파일은 교육 교재보다 첫 출근 날 선배가 건네는 생존 메모에 가깝다. 무엇이 중요한지, 어디에서 자주 넘어지는지, 무엇이 누구의 책임인지 알려준다. 모든 것을 가르치려 하지 않는다.
지도는 땅보다 클 수 없다.
모든 골목을 종이 위에 옮기면
오히려 길을 찾기 어려워진다.
지시 파일도 그렇다.
어디로 가야 하는지,
어디를 넘지 말아야 하는지,
어디에서 자주 길을 잃는지만 남긴다.
나머지는 Agent가 보고 판단하게 한다.
좋은 Harness는 지능을 대신하지 않는다.
지능이 길을 잃지 않을 만큼만 세계를 정리한다.