Claude Code는 코드베이스 전체의 문서를 자동으로 생성하고 유지할 수 있습니다. README 파일, JSDoc/docstring 주석, API 레퍼런스, 변경 로그를 슬래시 커맨드 하나 또는 git 훅으로 처리할 수 있습니다. 2025년 AI 보조 문서화를 도입한 오픈소스 프로젝트 벤치마크에 따르면, Claude Code는 문서 작성 시간을 70~85% 단축합니다. 이 가이드는 처음부터 끝까지 문서 자동화를 위한 정확한 프롬프트, 훅 설정, CI 패턴을 다룹니다.
왜 Claude Code로 문서를 자동화해야 할까?
수동 문서화에는 세 가지 근본적인 문제가 있습니다.
- 지연: 코드가 바뀌어도 문서는 뒤늦게 업데이트됩니다
- 일관성 부족: 팀원마다 문서 스타일이 달라집니다
- 우선순위 밀림: 마감 압박 속에서 문서화는 항상 뒤로 밀립니다
Claude Code는 pre-commit 훅으로 커밋 전 문서를 자동 생성하고, CLAUDE.md로 팀 전체 문서 스타일을 통일하며, 몇 초 안에 완성하므로 개발자가 건너뛸 이유가 없습니다.
README 자동 생성
새 프로젝트나 README가 없는 리포지토리에서:
claude "이 리포지토리 전체를 분석해서 포괄적인 README.md를 작성해줘. 프로젝트 설명, 설치 방법, 실제 코드 예시, 설정 레퍼런스, 기여 가이드를 포함해줘. 기존 코드 주석의 톤을 유지해줘."
특정 부분만 업데이트할 때:
claude "src/auth/에 새로 추가된 인증 모듈을 반영해서 README.md를 업데이트해줘. 기존 섹션은 그대로 유지해줘."
Claude Code는 전체 파일 트리와 코드를 읽으므로, 생성된 README에는 실제 함수 시그니처, 실제 설정 키, 동작하는 예제가 포함됩니다.
문서화 프롬프트 템플릿 50개+: Claude Power Prompts (P1, $29) — README 생성기, JSDoc 템플릿, 변경 로그 프롬프트, CLAUDE.md 스타터 포함.
인라인 주석 및 Docstring 자동 생성
Python docstring의 경우:
claude "src/ 안에서 docstring이 없는 모든 public 함수와 클래스에 Google 스타일 docstring을 추가해줘. 기존 docstring은 수정하지 마."
JavaScript JSDoc의 경우:
claude "src/api/의 모든 export 함수에 JSDoc 주석을 추가해줘. @param, @returns, @throws를 포함하고, TypeScript 타입을 최대한 활용해줘."
벤치마크: 5,000줄짜리 Python 코드베이스에서 Claude Code는 4분 만에 147개의 docstring을 생성했습니다. 개발자가 직접 하면 3~4시간이 걸리는 작업입니다.
API 레퍼런스 문서 생성
REST API의 경우, 라우트 파일에서 마크다운을 생성하도록 프롬프트:
claude "src/routes/의 모든 Express 라우트 파일을 읽고 docs/api-reference.md에 포괄적인 API 레퍼런스를 생성해줘. 각 엔드포인트에 메서드, 경로, 요청 바디 스키마, 응답 스키마, curl 예제를 포함해줘."
OpenAPI/Swagger 스펙 생성:
claude "src/routes/의 라우트 정의에서 openapi.yaml 스펙을 생성해줘. OpenAPI 3.1 형식을 사용하고, src/types/의 TypeScript 타입에서 요청/응답 스키마를 추론해줘."
변경 로그 자동 생성
git 히스토리에서 변경 로그를 자동 작성:
claude "마지막 태그 이후의 git 로그를 읽고 Keep a Changelog 형식으로 CHANGELOG.md 항목을 생성해줘. Added, Changed, Fixed, Removed로 분류하고, PR 제목과 커밋 메시지를 소스로 사용해줘."
릴리즈 워크플로우에 추가하는 스크립트:
VERSION=$(cat package.json | jq -r '.version')
git log $(git describe --tags --abbrev=0)..HEAD --oneline > /tmp/commits.txt
claude "이 커밋들을 기반으로 버전 $VERSION의 변경 로그를 생성해줘: $(cat /tmp/commits.txt). Keep a Changelog 형식. CHANGELOG.md 맨 앞에 추가해줘."
Git 훅: 커밋 시 문서 자동 업데이트
가장 강력한 패턴: pre-commit 훅이 모든 커밋 전에 문서를 최신 상태로 유지합니다.
.git/hooks/pre-commit 파일 생성:
#!/bin/bash
# 수정된 소스 파일의 문서 자동 업데이트
MODIFIED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(py|ts|js|go)$')
if [ -n "$MODIFIED" ]; then
echo "수정된 파일의 문서를 업데이트하는 중..."
claude "다음 파일들이 수정되었습니다: $MODIFIED. 현재 코드에 맞게 docstring과 인라인 주석을 업데이트해줘. 로직은 변경하지 마."
git add -u # 업데이트된 문서 파일 재스테이징
fi
실행 권한 부여:
chmod +x .git/hooks/pre-commit
Claude Code의 훅 시스템을 활용한 더 세밀한 훅:
// .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [{
"type": "command",
"command": "claude '방금 편집한 파일의 public API가 변경된 경우 JSDoc을 업데이트해줘'"
}]
}
]
}
}
커스텀 슬래시 커맨드
.claude/commands/document.md에 재사용 가능한 슬래시 커맨드 생성:
# 문서 생성
대상 파일 또는 디렉토리의 문서를 생성합니다:
1. $ARGUMENTS의 모든 소스 파일 읽기
2. 모든 public 함수, 클래스, 메서드에 docstring/JSDoc 추가 또는 업데이트
3. 같은 디렉토리에 README.md 생성 또는 업데이트
4. 모든 @param과 @returns 타입이 현재 TypeScript 타입과 일치하는지 확인
스타일: Python은 Google 스타일, JavaScript/TypeScript는 JSDoc.
어떤 로직이나 문서가 아닌 코드도 수정하지 마세요.
사용법:
claude /문서생성 src/api/
claude /문서생성 lib/auth.ts
CI 통합: 문서 품질 게이트
GitHub Actions에 문서화되지 않은 public API를 감지하는 단계 추가:
# .github/workflows/docs-check.yml
name: Documentation Check
on: [pull_request]
jobs:
check-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: 문서 커버리지 확인
run: |
claude "src/의 모든 public 함수를 감사하고 docstring이나 JSDoc 주석이 없는 것들을 JSON으로 출력해줘: [{file, function, line}]. 발견되면 exit code 1로 종료해줘."
CLAUDE.md 문서 표준 설정
문서 표준을 CLAUDE.md에 정의해서 모든 세션이 같은 규칙을 따르도록:
## 문서화 표준
- Python: 모든 public 함수와 클래스에 Google 스타일 docstring
- TypeScript: @param, @returns, @throws 포함 JSDoc
- README: 설치, 사용법, 설정, 기여 섹션 필수
- 변경 로그: Keep a Changelog 형식 (https://keepachangelog.com)
- 플레이스홀더 텍스트 금지 — 항상 코드베이스의 실제 예제 사용
더 자세한 CLAUDE.md 설정은 Claude Code 완전 가이드를 참조하세요.
리팩토링 후 문서 유지보수
대규모 리팩토링 후 기존 문서가 구식이 될 수 있습니다:
claude "src/의 현재 구현과 docs/와 README.md의 문서를 비교해줘. 오래된 섹션을 모두 나열한 다음, 현재 코드에 맞게 업데이트해줘."
에이전트 기반 자동화 패턴은 Claude Agent SDK 가이드를 참조하세요.
문서화 프롬프트 50개+: Claude Power Prompts (P1, $29) — 이 가이드의 모든 템플릿과 테스트, 리뷰, 아키텍처 문서용 40개 추가 포함.
자주 묻는 질문 (FAQ)
Claude Code가 기존 코드베이스 전체를 한 번에 문서화할 수 있나요?
가능하지만, 대용량 코드베이스(50K+ 줄)는 디렉토리별로 나눠서 처리하세요. claude "src/api/의 모든 public 함수를 문서화해줘" 형식으로 모듈별 실행이 컨텍스트 창 안에 맞고 더 정확한 결과를 냅니다.
Claude가 문서화 중 코드를 바꾸지 못하게 하려면?
프롬프트에 "어떤 로직도 수정하지 말고, 문서 주석만 추가하거나 업데이트해줘"를 포함하세요. 더 확실하게 하려면 CLAUDE.md에 전역 규칙으로 추가하면 모든 세션에 적용됩니다.
Claude Code가 지원하는 문서 형식은?
텍스트 기반 형식은 모두 지원합니다: Markdown, JSDoc, Google/NumPy 스타일 Python docstring, RST(Sphinx), OpenAPI YAML, AsciiDoc, 일반 텍스트. 프롬프트나 CLAUDE.md에 원하는 형식을 명시하세요.
한국어로 문서를 생성할 수 있나요?
네. 프롬프트 또는 CLAUDE.md에 "모든 문서를 한국어로 작성해줘"를 추가하면 됩니다. 코드 식별자(변수명, 함수명)는 영어로 유지되고 주석과 설명만 한국어로 생성됩니다.
PR에서 문서화를 강제하는 방법은?
GitHub Actions 단계에서 변경된 파일을 대상으로 Claude를 실행하고, 문서화되지 않은 public API가 발견되면 exit code 1로 종료하도록 설정하세요. 이것이 모든 PR에서 문서 품질 게이트 역할을 합니다.
자동 생성된 문서는 사람이 검토해야 하나요?
공개 문서나 컴플라이언스 관련 문서는 검토가 필요합니다. 내부 인라인 주석과 README 초안은 대부분의 팀이 10~20%를 spot-check하고 나머지는 Claude를 신뢰합니다. 잘 구조화된 코드에서 품질은 보통 90% 이상 정확합니다.
변경 로그를 git 커밋에서 자동 생성하는 방법은?
git log [이전-태그]..HEAD --oneline으로 커밋을 추출하고, Keep a Changelog 형식 프롬프트와 함께 Claude에게 전달한 뒤 출력을 CHANGELOG.md에 추가하세요. 릴리즈 워크플로우 스크립트에 통합할 수 있습니다.
관련 가이드
- Claude Code 완전 가이드 — 훅, CLAUDE.md, 슬래시 커맨드 레퍼런스
- Claude Agent SDK 가이드 — 에이전트로 문서화 파이프라인 자동화
- Claude Code 자동 테스트 생성 — 문서화와 함께하는 테스트 커버리지 자동화