CLAUDE.md 실전 템플릿

Q: `/init`으로 자동 생성하면 되지 않나요?

초안으로는 좋습니다. 다만 /init은 코드에서 보이는 것(폴더, 명령)을 잘 적고, 코드에 없는 것(왜 이 게이트가 있는지, 운영 DB를 왜 못 건드리는지)은 모릅니다. 초안을 받은 뒤 이 템플릿의 "규칙"과 "주의"를 채워 넣는 순서가 맞습니다.

Q: 길이는 어느 정도가 적당한가요?

공식 권장은 200줄 이하이고, 우리 템플릿은 30줄 안팎입니다. 그 이상 길어지면 파일별 규칙은 .claude/rules/로, 절차는 Skill로 뺍니다.

Q: 지침을 썼는데 지켜지지 않습니다.

/context의 Memory files 목록으로 로드 여부를 확인한 뒤 문장을 검증 가능하게 바꿉니다. 그래도 안 되면 그 규칙은 CLAUDE.md의 몫이 아니라 훅이나 퍼미션의 몫입니다.

「CLAUDE.md 작성법」에서 원칙을 봤다면 이 글은 복사해서 시작할 수 있는 뼈대를 줍니다. 초급 과정 4주차 실습 2 "CLAUDE.md 기본 템플릿 작성"을 프로젝트 유형별로 넓힌 것입니다. 템플릿은 출발점일 뿐이며, 붙여넣은 채로 두면 오히려 방해가 됩니다. 마지막 절의 "반드시 손볼 것"까지 읽어야 완성입니다.

다음 글 「퍼미션 설정 최적화」에서는 템플릿의 "주의" 항목을 CLAUDE.md 밖으로 꺼내 강제하는 방법을 봅니다.

핵심 요약

구조는 목적 → 실행 명령 → 규칙 → 주의 네 블록이면 충분합니다.
어떤 템플릿이든 200줄을 넘기지 않고, 비밀값과 폴더 트리는 넣지 않습니다.
붙여넣은 뒤 프로젝트 이름, 명령, 포트, 건드리면 안 되는 파일을 실제 값으로 바꿉니다.

어떤 구조로 쓰는가

목적: 한두 문장. 무엇을 만드는 프로젝트인지.
실행: 개발 서버·빌드·테스트 명령과 포트.
규칙: 번호를 붙인 지침. 검증 가능한 문장만.
주의: 건드리면 안 되는 파일, 우회하면 안 되는 게이트와 그 이유.

헤더와 불릿을 쓰고, 이유가 있는 규칙은 이유를 한 줄 붙입니다. "왜"가 있어야 Claude가 비슷한 상황에 일반화합니다.

기본 템플릿

# <프로젝트명> 작업 규칙

## 목적
<한 문장>

## 실행
- 실행: `<명령>` (포트 <번호>)
- 검증: `<빌드/테스트 명령>`

## 규칙
1. 민감 정보는 코드에 쓰지 않는다. 키는 `.env`에 두고 `.gitignore`로 제외한다.
2. 수정 전에 기존 구조를 읽는다. 큰 변경은 요약을 남긴다.
3. main 브랜치에 직접 작업하지 않는다.

## 주의
- `<원본 데이터 파일>`은 읽기 전용이다.

웹 프론트엔드 템플릿

# <서비스명> 프론트엔드

## 실행
- `pnpm dev` (포트 4400) / 검증 `pnpm build`

## 규칙
1. 가격·환불 문구의 단일 소스는 `lib/courses.ts`다. 화면에 숫자를 직접 쓰지 않는다.
2. 브랜드명은 `NEXT_PUBLIC_BRAND_NAME`으로만 읽는다. 하드코딩 금지.
3. UI를 바꾸면 390px·360px 뷰포트에서 가로 스크롤(scrollWidth)이 없는지 실측한다.
4. 발행 문구에 수익 보장 표현을 쓰지 않는다.

## 주의
- `app/(legacy)/`는 리스타일 대상이다. 새 페이지는 `app/(site)/`에 만든다.

우리 사이트 레포 CLAUDE.md에서 뽑은 항목입니다. 3번처럼 "확인 방법"까지 적으면 Claude가 검증을 스스로 수행합니다.

백엔드·API 템플릿

# <서비스명> API

## 실행
- 로컬: `pnpm dev` / 테스트 `pnpm test`
- DB 스키마 정본: `supabase/schema.sql`

## 규칙
1. 결제 금액은 서버가 정한다. 클라이언트가 보낸 금액을 신뢰하는 코드는 쓰지 않는다.
2. 스키마 변경은 `add column if not exists`로 누적해 재실행이 안전하게 한다.
3. service_role 키를 쓰는 모듈은 클라이언트 컴포넌트에서 import하지 않는다.
4. 결제 코드를 수정하면 별도 리뷰 절차를 거친다.

## 주의
- 운영 DB는 성역이다. 마이그레이션은 dev에서 검증한 뒤에만 적용한다.

초급 6주차 "서버 3단계, 운영 DB는 성역" 원칙을 그대로 옮긴 형태입니다.

비개발 프로젝트 템플릿

# 정책자금 상담 기록 정리

## 목적
상담 녹음 전사본을 보고서로 정리하고 고객 DB를 갱신한다.

## 규칙
1. 모든 문서는 존댓말로 쓴다.
2. 고객 실명은 홍OO 형태로만 쓴다.
3. 확실하지 않은 수치는 지어내지 않고 "확인 필요"로 표시한다.
4. 고객 DB 항목은 다음 10개로 고정한다: 고객명, 연락처, 유입경로, 관심상품, 상담내용, 진행상태, 마지막 상담일, 다음 액션, 담당자, 중요도.

## 주의
- `data/원본/` 아래 파일은 수정하지 않는다. 결과는 `output/`에 쓴다.

2주차의 3줄 지침서가 4주차 고객 DB 표준 10항목과 합쳐진 모습입니다.

붙여넣은 뒤 반드시 손볼 것

<꺾쇠> 자리를 전부 실제 값으로 바꿉니다. 하나라도 남으면 Claude가 그 자리를 추측합니다.
실행 명령을 터미널에서 직접 한 번 돌려 봅니다. 틀린 명령이 적힌 CLAUDE.md는 없는 것보다 나쁩니다.
우리 프로젝트에 없는 규칙을 지웁니다. 프론트엔드가 없는데 뷰포트 규칙이 남아 있으면 소음입니다.
"주의"에는 이유를 붙입니다. "운영 DB는 성역이다"보다 "운영 DB는 성역이다. 되돌릴 수 없기 때문"이 오래 갑니다.
/context의 Memory files 목록으로 로드됐는지 확인하고 한 세션 써 본 뒤 안 지켜진 줄을 고칩니다.

계층별로 무엇을 두나

위치	여기에 둘 것
`~/.claude/CLAUDE.md`	한국어 응답, 존댓말, 개인 도구 습관
`./CLAUDE.md`	위 템플릿 본문(팀 공유)
`./CLAUDE.local.md`	내 로컬 포트, 테스트 계정, 개인 경로. `.gitignore`에 추가
`frontend/CLAUDE.md`, `backend/CLAUDE.md`	그 폴더에서만 필요한 규칙. 그 폴더 파일을 읽을 때 로드
`.claude/rules/*.md`	파일 종류별 규칙(`paths` 조건부)

정리

목적, 실행, 규칙, 주의 네 블록이면 충분합니다. 30줄 안팎에서 시작합니다.
꺾쇠 자리를 실제 값으로 바꾸고 명령을 직접 돌려 본 뒤에야 템플릿은 완성입니다.
팀 규칙은 루트, 개인 값은 CLAUDE.local.md, 파일별 규칙은 .claude/rules/입니다.

자주 묻는 질문

`/init`으로 자동 생성하면 되지 않나요?

초안으로는 좋습니다. 다만 /init은 코드에서 보이는 것(폴더, 명령)을 잘 적고, 코드에 없는 것(왜 이 게이트가 있는지, 운영 DB를 왜 못 건드리는지)은 모릅니다. 초안을 받은 뒤 이 템플릿의 "규칙"과 "주의"를 채워 넣는 순서가 맞습니다.

길이는 어느 정도가 적당한가요?

공식 권장은 200줄 이하이고, 우리 템플릿은 30줄 안팎입니다. 그 이상 길어지면 파일별 규칙은 .claude/rules/로, 절차는 Skill로 뺍니다.

지침을 썼는데 지켜지지 않습니다.

/context의 Memory files 목록으로 로드 여부를 확인한 뒤 문장을 검증 가능하게 바꿉니다. 그래도 안 되면 그 규칙은 CLAUDE.md의 몫이 아니라 훅이나 퍼미션의 몫입니다.

여러 폴더에 두면 어느 쪽이 이기나요?

이기는 쪽은 없습니다. 상위부터 하위 순으로 전부 이어 붙고, 작업 폴더에 가까운 것이 마지막에 읽힙니다. 충돌하면 Claude가 임의로 고르므로 충돌 자체를 없애야 합니다.

언제 갱신하나요?

같은 실수가 반복된 날, 기능 하나가 끝난 시점, 그리고 월 1회 점검입니다. 우리 팀은 프로젝트에 의미 있는 변경이 있으면 CLAUDE.md도 같은 작업 안에서 갱신하는 것을 규칙으로 둡니다.