CLAUDE.md 생성기은(는) 무엇을 하나요?
코드베이스를 읽고 Claude가 정확히 필요한 정보만 담은 CLAUDE.md를 작성합니다. 더도 말고, 덜도 말고.
핵심 규칙: 좋은 CLAUDE.md는 100줄 미만입니다. Claude가 코드 자체를 읽어서 알 수 없는 정보만 포함해야 합니다. 파일을 자동으로 쓰지 마십시오. 항상 드래프트를 먼저 보여주고 사용자 승인을 기다리십시오.
코드 스니펫 규칙: CLAUDE.md에 인라인 코드 예제를 절대 포함하지 마십시오. 대신 file.ts:42와 같은 참조를 사용하십시오. CLAUDE.md의 코드는 토큰을 낭비하고 금세 구식이 됩니다.
1단계: 모드 감지
다음 세 가지 모드 중 하나를 결정합니다:
create: CLAUDE.md가 없습니다. 처음부터 새로 작성합니다. update: CLAUDE.md가 이미 있습니다. 사용자 지정 내용을 버리지 않고 개선합니다. audit: 프로젝트의 모든 CLAUDE.md 파일에 A-F 등급을 매기고 품질 보고서를 출력합니다. 사용자가 "감사", "확인", "검토", 또는 "등급"을 요청하면 감사 모드를 실행합니다.
# 모든 CLAUDE.md 위치 찾기
find . -name "CLAUDE.md" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null
ls ~/.claude/CLAUDE.md 2>/dev/null && echo "전역 CLAUDE.md 발견"
ls .claude.local.md 2>/dev/null && echo ".claude.local.md 발견"
여러 개의 CLAUDE.md 파일이 발견되면 목록을 보여주고 "다음 위치에서 CLAUDE.md 발견: [위치]. 모두 업데이트할까요, 아니면 [루트]만 업데이트할까요?"라고 질문하십시오.
2단계: 감사 모드 (create/update인 경우 3단계로 이동)
발견된 각 CLAUDE.md에 대해 다음 기준표를 사용하여 A-F 등급을 매깁니다:
| 기준 | 확인 사항 |
|---|---|
| 명령어 | 빌드/테스트/린트 명령어가 존재하고 실행 가능한가? |
| 아키텍처 | 비명시적인 구조가 설명되어 있는가? |
| 비명시적 패턴 | 주의사항, 생성된 파일, env 변수 순서 등이 문서화되어 있는가? |
| 간결성 | 100줄 미만인가? 명백한 잡담이 없는가? |
| 최신성 | 명령어가 현재 package.json/Makefile과 일치하는가? |
| 실행 가능성 | 새로운 기여자가 질문 없이 따라할 수 있는가? |
점수: 90-100 = A, 70-89 = B, 50-69 = C, 30-49 = D, 0-29 = F
표 형식으로 제시합니다:
## CLAUDE.md 감사 보고서
| 파일 | 점수 | 등급 | 주요 문제 |
|------|-------|-------|-----------|
| ./CLAUDE.md | 72 | B | 주의사항 섹션 누락, 테스트 명령어 구식 |
| ./packages/api/CLAUDE.md | 45 | D | 명령어 없음, 340줄 (너무 김), 오래된 아키텍처 노트 |
**전체: B (72/100)**
발견된 문제:
- ./packages/api/CLAUDE.md: 340줄: 100줄 목표를 크게 초과
- ./packages/api/CLAUDE.md: 테스트 명령어가 `jest`를 참조하지만 package.json은 `vitest`를 사용함
- ./CLAUDE.md: 주의사항 섹션 없음: 가장 중요한 섹션이 누락됨
보고서가 끝나면 "이 중에서 수정할 항목이 있나요? (모두 / 루트만 / 지정)"라고 질문하십시오.
사용자가 예라고 답하면 수정하려는 각 파일에 대해 3단계를 계속 진행합니다.
3단계: 프로젝트 구조 스캔
# 프로젝트 유형 및 패키지 매니저
ls package.json yarn.lock pnpm-lock.yaml bun.lockb requirements.txt pyproject.toml Cargo.toml go.mod 2>/dev/null
# 최상위 디렉토리 구조
find . -maxdepth 2 -type d \
| grep -v node_modules | grep -v .git | grep -v __pycache__ \
| grep -v ".next" | grep -v dist | grep -v build | sort
4단계: 빌드 및 테스트 명령어 추출
# npm/yarn/pnpm/bun 스크립트
cat package.json 2>/dev/null \
| python3 -c "
import sys, json
d = json.load(sys.stdin)
for name, cmd in d.get('scripts', {}).items():
print(f'{name}: {cmd}')
"
# Python, Go, Rust Makefile
cat Makefile 2>/dev/null | grep -E "^[a-z].*:" | head -20
# Go
cat go.mod 2>/dev/null | head -5
# Rust
cat Cargo.toml 2>/dev/null | grep -E "^\[" | head -10
다음에 대한 정확한 명령어를 식별합니다: 빌드, 테스트 (전체), 테스트 (단일 파일/이름), 개발 서버, 린트/타입체크. 실행에 필요한 모든 env 변수를 기록합니다.
5단계: 코드 스타일 및 주의사항 찾기
# 임포트 별칭 (가장 흔히 놓치는 것)
python3 -c "
import json, sys
try:
d = json.load(open('tsconfig.json'))
paths = d.get('compilerOptions', {}).get('paths', {})
if paths: print('Import aliases:', json.dumps(paths, indent=2))
except: pass
" 2>/dev/null
# 필요한 환경 변수
cat .env.example 2>/dev/null | grep -v "^#" | grep -v "^$" | head -20
# 자동 생성 파일 (편집 금지)
find . -path \"*/node_modules\" -prune -o -name \"*.ts\" -print \
| xargs grep -l \"DO NOT EDIT\\|@generated\\|Generated by\" 2>/dev/null | head -5
# 테스트 설정 요구 사항
cat jest.config.js jest.config.ts vitest.config.ts 2>/dev/null | head -30
# 데이터베이스/마이그레이션 설정
ls migrations/ prisma/ drizzle/ db/ 2>/dev/null
주의사항으로 간주되는 것 (이것들만 포함하고 나머지는 건너뜁니다):
- 자동 생성된 파일 (편집 금지)
- 테스트 실행 전에 필요한 env 변수
- 기본값이 아닌 임포트 별칭 매핑
- 실행 중인 서비스가 필요한 테스트 명령어
- 알려진 의도적인 특이사항 (해결 방법, 버그 아님)
6단계: Gemini로 CLAUDE.md 드래프트 생성
모든 조사 결과를 컴파일하고 드래프트를 생성합니다:
cat > /tmp/claude-md-request.json << 'ENDJSON'
{
"system_instruction": {
"parts": [{
"text": "소프트웨어 프로젝트를 위한 CLAUDE.md 파일을 작성하세요. 규칙: (1) 총 100줄 미만. (2) Claude가 코드를 읽어서 알 수 없는 것만 포함하세요. (3) 인라인 코드 예제 금지: 대신 file.ts:42 참조를 사용하세요. (4) 섹션: 명령어, 코드 스타일(기본값이 아닌 것만), 테스트(설정이 필요한 경우만), 주의사항(필수: 사람들이 실수하는 부분). 말할 것이 없으면 해당 섹션을 건너뛰세요. (5) 모든 명령어는 코드 블록 안에 넣으세요. (6) 선호 순서: 짧은 프로젝트 개요(1-2문장, 비명시적인 경우만), 명령어, 아키텍처(비명시적 구조만), 코드 스타일, 테스트, 주의사항. (7) Em dash 사용 금지. (8) CLAUDE.md 내용만 출력하고 설명은 덧붙이지 마세요."
}]
},
"contents": [{
"parts": [{
"text": "PROJECT_ANALYSIS_HERE"
}]
}],
"generationConfig": {
"temperature": 0.3,
"maxOutputTokens": 2048
}
}
ENDJSON
curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d @/tmp/claude-md-request.json \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(d['candidates'][0]['content']['parts'][0]['text'])"
PROJECT_ANALYSIS_HERE를 3-5단계의 조사 결과로 바꾸십시오.
대규모 프로젝트(파일 50개 이상)의 경우: 인라인 세부 정보 대신 CLAUDE.md 하단에 @path 포인터를 추가하십시오:
## 확장 참조
전체 모듈 맵은 @docs/ai-context/architecture.md를 참조하세요.
통합 테스트 설정 세부 정보는 @docs/ai-context/testing.md를 참조하세요.
100줄 안에 들어가지 않는 세부 정보는 docs/ai-context/ 디렉토리에 참조 파일을 작성하십시오.
7단계: 자체 QA
드래프트를 제시하기 전에 다음을 확인하십시오:
- 100줄 미만 (줄 수 확인:
echo "$CONTENT" | wc -l) - 인라인 코드 예제 없음 (
file.ts:42참조 또는 셸 명령어만) - 모든 명령어가 코드 블록 안에 있고 그대로 실행 가능
- 주의사항 섹션이 존재하고 최소 하나의 실제 항목 포함
- 파일에서 명백히 알 수 있는 내용만 말하는 섹션 없음
- Em dash 사용 금지
- 마케팅 단어나 채우기 문구 없음 ("이 프로젝트는 React를 사용하여...")
- 임포트 별칭이 존재하면 문서화됨
- 자동 생성 파일이 존재하면 "편집 금지" 표시됨
하나라도 실패하면 제시하기 전에 수정하십시오.
8단계: 드래프트 제시 및 승인 대기
사용자 승인 없이 파일을 절대 쓰지 마십시오.
코드 블록에 드래프트를 제시하십시오:
## 드래프트 CLAUDE.md ([N]줄)
[전체 드래프트 내용]
---
이 내용을 CLAUDE.md에 쓸까요? (예 / 먼저 수정 / 취소)
사용자가 예라고 답하면: 파일을 쓰고 "CLAUDE.md 작성 완료 ([N]줄). 섹션: [## 헤더 목록]."이라고 확인하십시오.
사용자가 먼저 수정이라고 답하면: 사용자의 수정을 적용하고 드래프트를 다시 보여주십시오.
사용자가 취소라고 답하면: 중단하십시오.
포함하지 말아야 할 것
- 언어/프레임워크 버전 ("이것은 TypeScript 프로젝트입니다")
- 프레임워크 작동 방식 (Claude는 이미 React, FastAPI 등을 알고 있습니다)
- 모든 의존성 목록
- 린터가 이미 적용하는 스타일 규칙 (들여쓰기 크기, 따옴표 스타일)
- README.md를 복제하는 내용
- 인라인 코드 예제 또는 여러 줄 스니펫
- 동일한 스택을 사용하는 모든 프로젝트에서 동일할 내용