AI에게 규칙을 한 번만 가르치는 법

AI 페어 프로그래밍

AI에게 규칙을 한 번만 가르치는 법

CLAUDE.md · AGENTS.md · 파일별 자동 로드 규칙 실전

핵심 요약

• 요즘 AI 코딩 도구 대부분은 "매 세션 자동으로 읽는 지침 파일"을 지원한다. 여기에 컨벤션·함정·빌드 명령을 적어두면 같은 설명을 반복하지 않아도 된다.
• 가장 기본은 루트에 파일 하나 — Claude Code는 CLAUDE.md, 여러 도구 공통 표준은 AGENTS.md.
• 규칙이 커지면 쪼개서 파일 패턴별로 조건부 로드한다 — Claude Code .claude/rules/*.md의 paths:, Cursor .cursor/rules/*.mdc의 globs:. 둘 다 네이티브 기능이다.
• 함정은 learnings 파일에 한 줄씩 모으고, "해결 즉시 기록"을 지침 파일에 규칙으로 박는다.

1.지침 파일 = 매 세션 자동으로 읽히는 메모

AI 코딩 도구(Claude Code, OpenAI Codex, Cursor 등) 대부분은 프로젝트에 둔 마크다운 파일을 매 세션 시작 때 자동으로 읽어 컨텍스트에 넣는 기능이 있다. 여기에 빌드 명령·코드 컨벤션·자주 빠지는 함정을 적어두면, 새 대화를 열 때마다 같은 설명을 다시 하지 않아도 된다.

핵심은 단순하다 — "기억"을 휘발성인 모델이 아니라 저장소(파일)에 두는 것. 아래는 도구별로 그 파일을 어떻게 만들고 키우는지에 대한 실전 설정이다. (도구 기능은 자주 바뀌니, 세부는 각 공식 문서를 함께 확인하자.)

2.가장 기본 — 루트에 지침 파일 하나

시작은 프로젝트 루트에 파일 하나면 된다. Claude Code는 CLAUDE.md(루트 또는 .claude/CLAUDE.md)를 매 세션 자동으로 읽는다. 개인 전역 설정은 ~/.claude/CLAUDE.md, 공유하기 싫은 개인 메모는 CLAUDE.local.md(gitignore)에 둔다.

CLAUDE.md (또는 AGENTS.md) — 루트Markdown

# 프로젝트 지침

## 빌드 · 테스트
- 설치: pnpm install
- 테스트: pnpm test

## 컨벤션
- 커밋은 Conventional Commits
- 새 파일은 kebab-case

## 규칙 유지
- 비자명한 에러를 해결하면 "즉시" learnings.md에 한 줄 남긴다

여러 도구를 같이 쓴다면 AGENTS.md가 더 낫다. Google·OpenAI·Cursor 등이 함께 미는 cross-tool 공개 표준이라, Codex·Cursor·Aider 등 수십 개 도구가 같은 파일을 읽는다. 형식은 그냥 마크다운(특별한 문법 없음), 위치는 루트다.

⚠ Claude Code는 AGENTS.md를 자동으로 안 읽는다

AGENTS.md를 쓰면서 Claude Code도 같이 쓴다면, CLAUDE.md 맨 위에서 @AGENTS.md로 import하거나 심볼릭 링크를 건다(ln -s AGENTS.md CLAUDE.md). 안 그러면 Claude Code만 그 지침을 못 본다.

3.도구마다 파일 이름이 다르다

"도구마다 다르다"를 구체적으로 펼치면 이렇다.

도구	지침 파일	비고
Claude Code	CLAUDE.md (+ 전역 ~/.claude/CLAUDE.md, 개인 CLAUDE.local.md)	매 세션 자동 · @import · .claude/rules
OpenAI Codex · 공통	AGENTS.md (루트, 일반 마크다운)	cross-tool 표준(30+ 도구)
Cursor	.cursor/rules/*.mdc	globs: 패턴별 자동 첨부
GitHub Copilot	.github/copilot-instructions.md	리포 전체 단일 파일(패턴 없음)

4.규칙이 커지면 — "파일 패턴별로" 조건부 로드

규칙이 수백 줄로 불면 한 파일에 다 넣는 게 오히려 노이즈가 된다(중요한 게 묻힌다). 그래서 지금 만지는 파일에 해당하는 규칙만 불러오게 쪼갠다. 이건 관습이 아니라 도구의 네이티브 기능이다.

Claude Code는 .claude/rules/에 규칙을 파일별로 두고, frontmatter paths:에 글롭 패턴을 단다. paths가 없으면 항상 로드, 있으면 그 패턴에 맞는 파일을 읽을 때만 로드된다(토큰 절약).

.claude/rules/python.mdMarkdown · frontmatter

---
paths:
  - "apps/**/*.py"
---

# 파이썬 규칙 (apps/**/*.py 를 읽을 때만 로드)
- async 세션 안에서 ORM add 후 execute는 autoflush 주의
- 마이그레이션 revision id는 32자 이내

Cursor도 같은 개념이다 — .cursor/rules/*.mdc의 frontmatter globs:에 패턴을 적으면, 매칭 파일을 편집할 때 자동 첨부된다. alwaysApply: true면 항상.

.cursor/rules/react.mdcMDC · frontmatter

---
description: "React 컴포넌트 규칙"
globs: ["src/components/**/*.{tsx,ts}"]
alwaysApply: false
---

- 함수형 컴포넌트만
- props는 TypeScript로 타입 지정

"항상 로드"와 "조건부 로드"를 나눈다

핵심 함정·전역 컨벤션은 항상(루트 지침 / paths 없는 규칙), 영역별 세부 규칙은 패턴별 조건부(paths / globs)로 둔다. 이렇게 해야 매 세션 컨텍스트가 "지금 일과 무관한 규칙"으로 부풀지 않는다.

디렉터리마다 CLAUDE.md를 두는 것과 뭐가 다른가

사실 비슷한 효과를 다른 방법으로도 낼 수 있다 — 디렉터리마다 CLAUDE.md(또는 AGENTS.md)를 두면, Claude Code가 그 디렉터리의 파일을 읽을 때 그 파일을 자동으로 불러온다(중첩 로드). 그럼 .claude/rules의 paths:와 뭐가 다를까?

	디렉터리별 CLAUDE.md	.claude/rules + paths:
위치	규칙이 그 디렉터리 안에 흩어져 산다	.claude/rules/ 한 곳에 모인다
타깃	그 디렉터리 하위 전체만	임의 글롭 — **/*.test.ts·**/*.{env,key}처럼 디렉터리를 가로지르는 패턴도 가능
관리	"어떤 규칙이 언제 켜지나"가 트리 곳곳에 흩어져 한눈에 안 보임	한 폴더만 보면 전부 파악
공유	위치에 묶임	symlink로 프로젝트 간 공유

그래서 기본은 rules가 깔끔하다 — 한 폴더에 모여 관리가 쉽고, "모든 테스트 파일", "모든 마이그레이션", "보안 민감 파일"처럼 디렉터리를 가로지르는 규칙은 디렉터리별 파일로는 아예 표현이 안 된다(글롭만 가능). 다만 모노레포의 한 서비스처럼 디렉터리 단위로 맥락이 또렷하게 묶이는 큰 덩어리는 그 안에 CLAUDE.md를 두는 게 직관적이다("규칙이 코드 옆에"). 둘을 섞어 써도 된다.

5.@import로 조립하기 (Claude Code)

CLAUDE.md가 길어지면 @경로 import로 다른 파일을 끌어와 조립할 수 있다(상대경로 기준, 최대 4단계 중첩). 큰 지침을 여러 파일로 나누거나, 앞서 말한 AGENTS.md를 끌어쓸 때 쓴다.

CLAUDE.md — import로 조립Markdown

빌드 절차: @docs/build.md
코드 컨벤션: @docs/conventions.md
@AGENTS.md          # 공통 표준 파일을 그대로 끌어옴

6.함정 기록(learnings) 파일

지침 파일(컨벤션)과 별개로, 코드만 봐선 모르는 비자명한 함정을 모으는 파일을 하나 둔다(항상 로드). 그리고 가장 중요한 한 가지 — "해결 즉시 기록"을 규칙으로 박는다. "나중에 정리"는 오지 않는다.

learnings.md — 함정 한 줄씩Markdown

- 그 로깅 라이브러리 로그는 테스트 캡처에 안 잡힘 → 전용 캡처 API로 검증
- CSS 프레임워크 vN + 특정 색공간에서 흔한 색상 표기 무효 → 변수 직접 사용
- 이벤트 봉투 키는 "data"가 표준("payload" 아님) — 틀리면 메시지가 조용히 사라짐

쌓이면 관리도 필요하다 — 비자명한 것만, 한 줄로 적고, 낡거나 해결된 항목은 주기적으로 아카이브로 덜어낸다. 안 그러면 그 파일 자체가 노이즈가 된다.

7.정리

한 번 세팅해두면, 새 세션이 매번 0에서 시작하지 않는다. 정리하면 단계는 셋이다.

1. 루트에 지침 파일 하나 — CLAUDE.md / AGENTS.md(매 세션 자동 로드).
2. 커지면 패턴별로 쪼갠다 — .claude/rules의 paths: / Cursor globs:로 조건부 로드.
3. 함정은 learnings에 즉시 한 줄 — "해결 즉시 기록"을 규칙으로.

도구는 달라도 원리는 하나다 — 기억을 모델이 아니라 저장소에 두고, 필요한 만큼만 자동으로 불러온다.

참고 — Claude Code Memory · AGENTS.md · Cursor Rules

바이브코딩 · AI와 더 잘 일하는 법