Claude Code CLAUDE.md 스타터 템플릿: 기존 코드베이스용 최소 규칙

CLAUDE.md는 매 세션의 반복 설명을 줄이는 파일이다

기존 코드베이스에서 Claude Code를 쓰면 처음 막히는 지점은 코드 생성 능력이 아니라 프로젝트 맥락입니다. 어떤 package manager를 쓰는지, 앱 디렉터리가 어디인지, 어떤 파일은 생성물인지, 어떤 명령은 위험한지, 완료 기준이 무엇인지 매번 설명하면 작업 품질이 흔들립니다.

CLAUDE.md는 이 반복을 줄이는 가장 작은 운영 파일입니다. 공식 Claude Code memory 문서는 CLAUDE.md가 세션 시작 시 로드되는 지속 지시라고 설명합니다. 다만 이것은 강제 설정이 아니라 context입니다. 명령 차단이나 파일 범위 제한이 필요하면 settings, permission, hook, CI와 함께 설계해야 합니다. 보안 경계는 security 문서도 같이 확인하는 편이 안전합니다.

여기서 harness는 agent가 안전하게 일하도록 잡아 주는 발판이라는 뜻으로 쓰겠습니다. 처음부터 회사 전체 규정을 만들 필요는 없습니다. 실제로 자주 반복되는 실수만 막는 작은 발판이 더 잘 지켜집니다. 더 넓은 패턴은 CLAUDE.md 템플릿 모음과 Claude Code 권한 가이드를 이어서 읽으면 됩니다.

바로 붙여 넣는 CLAUDE.md 템플릿

첫 파일은 짧아야 합니다. 프로젝트 개요, 명령, 작업 경계, 품질 기준, 완료 조건만 넣습니다. 규칙은 실제 실패가 반복될 때 추가합니다.

# CLAUDE.md

## Project snapshot
- Product: content site and paid template store
- Stack: Astro, TypeScript, MDX, npm
- Main app: site/
- Source articles: site/src/content/blog*/
- Owner voice: practical, evidence-based, no hype

## Commands
- Install dependencies: cd site && npm install
- Start local dev server: cd site && npm run dev
- Build check: cd site && npm run build
- Search fast: rg "keyword" site/src
- Inspect git state: git status --short

## Working rules
- Read existing files before editing.
- Keep changes scoped to the requested slug or feature.
- Do not edit .env, dist, generated reports, or unrelated locale files.
- Preserve pubDate, category, tags, author, lang, and heroImage unless they are broken.
- Ask before destructive git operations, production deploys, or secret rotation.

## Article quality
- Japanese canonical articles should be 4000-6000 characters excluding code.
- Include at least three real use cases.
- Include concrete pitfalls and how to avoid them.
- Include runnable code or config examples, not pseudocode.
- Check official docs when the topic may have changed.

## Definition of done
- The requested files are edited.
- Code fences and JSON/YAML examples are valid.
- Links to internal pages and official docs are present.
- Verification commands have run or skipped checks are explained.
- Remaining risks are stated in the final message.

저장 위치는 repository root의CLAUDE.md가 기본입니다. 개인용 메모는CLAUDE.local.md로 분리합니다. 이미AGENTS.md를 쓰는 저장소라면 중복 작성보다 작은CLAUDE.md에서 기존 파일을 import하고 Claude Code 전용 규칙만 덧붙이는 방식이 관리하기 쉽습니다.

강제 규칙은 settings에 둔다

CLAUDE.md에 “push하지 말 것”이라고 써도 그것만으로 차단되지는 않습니다. 위험 명령과 민감 경로는 settings로 관리해야 합니다. 아래 예시는 콘텐츠 저장소에서 개인 안전망으로 시작할 때의 최소 형태입니다.

{
  "permissions": {
    "allow": [
      "Read",
      "Edit(site/src/content/blog/**)",
      "Bash(rg:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(node:*)"
    ],
    "deny": [
      "Bash(git reset:*)",
      "Bash(git checkout --:*)",
      "Bash(git push:*)",
      "Bash(npm publish:*)",
      "Edit(.env*)",
      "Edit(reports/**)"
    ]
  }
}

개인 설정이면.claude/settings.local.json, 팀 기본값이면.claude/settings.json에 둡니다. 실제 적용 전에는 공식 settings 문서에서 최신 schema를 확인하세요. CLAUDE.md는 의도와 맥락, settings는 실행 경계, CI는 최종 검증이라는 역할로 나누면 혼란이 줄어듭니다.

실무 use case 3가지

Use case	CLAUDE.md에 적을 내용	좋아지는 점
다국어 기사 관리	대상 slug, locale 목록, 보존할 frontmatter, 본문 길이, CTA, 검증 순서	빠진 언어, 영어 잔재, 깨진 링크, 오래된 날짜를 줄임
기존 SaaS의 작은 버그 수정	수정 가능한 디렉터리, 테스트 명령, DB 변경 승인 조건, 로그 기준	불필요한 리팩터링과 위험한 migration을 줄임
팀 코드 리뷰	severity, file, line, 영향, 재현 절차, test gap 형식	리뷰가 추상적인 의견이 아니라 실행 가능한 항목이 됨

다국어 콘텐츠에서는 파일이 모두 있어도 본문이 같은 언어로 남는 실수가 많습니다. locale별 경로와 description 제한, internal link 규칙을 적어 두면 첫 탐색부터 그룹 단위로 진행됩니다.

SaaS 수정에서는 범위 제한이 핵심입니다. 작은 UI 버그인데 인증, 결제, migration까지 건드리면 review 비용이 커집니다. “먼저 관련 파일을 읽고, 요청 범위만 수정하고, 해당 테스트를 실행하고, DB 변경은 승인 전까지 하지 않는다”처럼 검증 가능한 문장이 좋습니다.

팀 리뷰에서는 출력 형식이 중요합니다. severity와 line reference가 없으면 결과를 PR comment로 옮기기 어렵습니다. 자동 실행이나 one-shot review를 검토한다면 공식 CLI reference를 함께 보세요.

피해야 할 함정

첫 번째 함정은 파일을 너무 크게 만드는 것입니다. 300줄짜리 정책 파일은 진지해 보이지만 context를 많이 쓰고 실제 준수율은 낮아집니다. 항상 쓰는 규칙만 남기고, 특정 폴더에만 필요한 내용은 path-scoped rule이나 별도 문서로 분리합니다.

두 번째 함정은 비밀 정보를 넣는 것입니다. API key, 고객명, 내부 dashboard URL, 공개 전 매출 수치는 쓰지 않습니다. 대신 “secret은 environment variable에 있으며 출력하지 않는다”처럼 처리 원칙만 적습니다.

세 번째 함정은 오래된 명령입니다. Yarn에서 npm으로, Jest에서 Vitest로, Next.js에서 Astro로 바뀌었는데 템플릿이 그대로면 Claude Code는 잘못된 명령을 자신 있게 실행합니다. 도구 변경 직후 첫 commit에CLAUDE.md수정을 포함하세요.

네 번째 함정은 검증을 말로만 끝내는 것입니다. 완료 보고에는 실행한 command, 결과, 수정 파일, 확인하지 못한 위험이 있어야 합니다. 이 습관이 배포 직전의 작은 누락을 가장 많이 잡아냅니다.

작게 도입하고 실제 실패로 키운다

도입 순서는 단순합니다. 먼저 이 글의 템플릿으로 30줄 정도의 파일을 만듭니다. 다음으로 기사 수정, 작은 UI 수정, 코드 리뷰처럼 위험이 낮은 세 작업에 사용합니다. 실제로 반복된 실수만 한 줄씩 추가합니다. 마지막으로 반드시 막아야 하는 경계는 settings, CI, branch protection, 배포 승인으로 옮깁니다.

운영 중에는 규칙의 이유도 짧게 남기세요. “reports를 수정하지 말 것”보다 “reports는 audit script output이므로 이 작업에서는 생성하지 않는다”가 더 오래 유지됩니다. 여러 worker가 동시에 다른 slug를 수정하는 상황에서는 edit scope를 좁게 쓰는 것도 중요합니다.

수익 경로가 있는 사이트라면 CTA도 완료 조건에 넣어야 합니다. 제품 카드, 구매 링크, training form, 상담 링크가 깨지면 페이지뷰는 유지되어도 전환이 줄어듭니다. 개인은 ClaudeCodeLab products의 템플릿과 체크리스트로 시작할 수 있습니다. 팀에서 권한, 리뷰 게이트, 교육 자료, 저장소별 규칙까지 설계해야 한다면 Claude Code training and consultation을 사용하는 편이 빠릅니다.