본문 바로가기
C.W.K.
Stream
Lesson 03 of 13 · published

CLAUDE.md — 프로젝트가 기억할 규칙

~18 min · claude-md, memory, context, init

Level 0🌱 입문자
0 XP0/70 lessons0/11 achievements
0/120 XP to next level120 XP to go0% complete

CLAUDE.md는 에이전트가 일을 시작하기 전에 읽는 집 안내서야

CLAUDE.md에는 매번 첫 메시지로 설명하기 아까운 장기 진실을 적어. 기술 구성, 자주 쓰는 명령, 아키텍처 원칙, 절대 어기면 안 되는 제약이 여기에 들어가. 대화가 아니라 저장소와 함께 버전 관리되기 때문에 새 세션도 같은 규칙을 물려받아.

전역 ~/.claude/CLAUDE.md에는 개인 습관을, 저장소 루트에는 팀 공통 규칙을, 더 깊은 디렉터리에는 그 영역만의 추가 규칙을 둬. 적용되는 문서는 모두 합쳐지고 작업 위치에 가까운 규칙이 더 구체적인 사정을 덧붙여. 결제 코드만 특별히 엄격하게 다루는 식의 구성이 복사 없이 가능하지.

처음부터 빈 문서를 붙잡고 쓸 필요도 없어. /init이 저장소를 훑어 초안을 만들면 틀린 부분을 덜어내고 빠진 원칙을 보태. 세션 도중 새로 배운 사실은 메시지 앞에 #를 붙여 적절한 CLAUDE.md에 남길 수도 있어.

직접 확인할 항목: package.json, pyproject.toml, src/.../CLAUDE.md.

Code

제값을 하는 CLAUDE.md 예시·markdown
# myproject — CLAUDE.md

## What this is
TypeScript REST API on Node 22 + Postgres 16, deployed via Fly.io.
Frontend lives in ../myapp-frontend (separate repo).

## Standard commands
npm run dev          # localhost:3000, hot reload
npm test             # vitest
npm run db:migrate   # prisma migrate dev
npm run lint         # eslint + prettier

## Architecture
- src/routes/        Express handlers (one per resource)
- src/services/      business logic (no DB calls here)
- src/repositories/  Prisma queries (the only place DB is touched)
- src/middleware/    auth, validation, error envelope

## Conventions
- TS strict, no `any` (use `unknown` and narrow)
- async/await only, never callbacks
- Validate all inputs with Zod before processing
- Response envelope: { data, error, meta }

## Do not
- Modify schema.prisma without a migration
- Commit .env (use direnv)
- Use console.log in app code (use src/lib/logger.ts)
상위 규칙에 하위 디렉터리 규칙 덧씌우기·markdown
# src/payments/CLAUDE.md

## Payments — additional rules
This service handles PCI-DSS regulated data. Treat everything here
as SENSITIVE.

- NEVER log card numbers, CVVs, or full PANs (debug code included)
- All encryption goes through src/lib/crypto.ts (AES-256-GCM)
- All Stripe calls go through src/clients/stripe.ts
- Rate limiting is MANDATORY on every public payment endpoint

## Verify before committing
npm run pci-check

External links

Exercise

사용 중인 저장소에서 /init을 실행해 CLAUDE.md 초안을 만들어. 내용을 비판적으로 읽고 틀린 것은 덜어 낸 뒤, 실제로 겪고 배운 “하지 마” 규칙 2개를 추가해. 파일을 커밋하고 새 Claude Code 세션을 연 다음, 따로 입력하지 않아도 된 지시가 몇 개인지 세어 봐.

Progress

Progress is local-only — sign in to sync across devices.
이 페이지에서 버그를 발견하셨거나 피드백이 있으세요?문제 신고

댓글 0

🔔 답글 알림 (로그인 필요)
로그인댓글을 남기려면 로그인해 주세요.

아직 댓글이 없어요. 첫 댓글을 남겨보세요.