Claude Code용 CLAUDE.md 시작 템플릿

약한 CLAUDE.md는 매번 세션을 차갑게 시작하게 만듭니다

Claude Code에게 같은 프로젝트 규칙을 반복해서 설명하고 있다면 문제는 프롬프트만이 아닙니다. 명령, 가드레일, 위험한 경로, 완료 기준을 담은 작은 운영 파일이 필요합니다.

이 템플릿은 기존 코드베이스에 바로 넣기 위한 시작점입니다. First Task Runbook과 함께 쓰면 첫 세션이 훨씬 안정적입니다.

시작 템플릿에 들어갈 내용

거대한 정책 문서가 필요하지 않습니다. stack, 주요 명령, 위험한 경로, 출력 방식, 완료 기준부터 적으면 충분합니다.

# CLAUDE.md

## Project snapshot
- stack: Astro + TypeScript
- package manager: npm
- main app: site/

## Commands
- dev: cd site && npm.cmd run dev
- build: cd site && npm.cmd run build

## Guardrails
- do not touch: .env, dist, generated exports
- ask before: destructive git commands, production deploys, secret rotation

## Definition of done
- code change is applied
- verification command has run
- remaining risks are stated

이 정도만 있어도 Claude Code가 다음 세션에서 덜 헤맵니다.

콘텐츠 사이트 예시

Astro 다국어 사이트라면 모든 언어가 같은 slug를 쓰는지, pubDate와 updatedDate가 맞는지, heroImage가 있는지, 공개 URL에서 h1, canonical, 본문 언어, CTA 링크가 맞는지 확인하는 규칙을 추가합니다.

가장 위험한 실패는 파일은 모든 언어에 있는데 비영어 페이지의 본문이 영어로 남는 상태입니다. frontmatter만 맞아서는 완료가 아닙니다.

규칙을 늘리는 시점

CLAUDE.md는 길수록 좋은 파일이 아닙니다. 같은 문제가 반복될 때만 한 줄을 추가하세요. build 혼란이 있으면 명령을, 번역 누락이 있으면 다국어 검증을, 리뷰가 얕으면 리뷰 기준을 추가합니다.

다음 단계

명령 기억이 문제라면 무료 cheatsheet부터 시작하세요. 권한, hooks, MCP, CLAUDE.md 품질이 문제라면 Setup Guide가 맞습니다. 팀 규칙 설계는 상담 페이지를 보세요.