コードが変わるたびにドキュメントも自動更新される仕組みを Claude Code で作る

pip install anthropic==0.50.0

# CLAUDE.md
 
## ドキュメント生成方針
- README.md はユーザー向け。インストール手順と基本的な使い方に集中する
- docs/api.md は開発者向け。型定義と副作用に重点を置く
- CHANGELOG は Conventional Commits 形式のコミットメッセージから生成する
- コード例は TypeScript で統一する
- 日本語と英語の両方で出力する（日本語が主、英語が副）

# scripts/generate_readme.py
import anthropic
import sys
from pathlib import Path
 
client = anthropic.Anthropic()
 
def get_code_structure(repo_path: str, max_files: int = 8) -> str:
    """リポジトリのソースコードを収集する"""
    repo = Path(repo_path)
 
    # 対象拡張子（node_modules・dist などを除外）
    patterns = ['*.ts', '*.tsx', '*.py', '*.js', '*.go']
    exclude_dirs = {'node_modules', 'dist', '.next', '__pycache__', '.git', 'coverage'}
 
    files = []
    for pattern in patterns:
        for path in repo.rglob(pattern):
            if not any(excl in path.parts for excl in exclude_dirs):
                files.append(path)
 
    # 更新日時が新しい順に並び替え（最近変更されたファイルが現状を反映）
    files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
 
    samples = []
    for filepath in files[:max_files]:
        try:
            content = filepath.read_text(errors='ignore')[:2500]
            relative = filepath.relative_to(repo)
            samples.append(f"### {relative}\n```\n{content}\n```")
        except (OSError, ValueError) as e:
            print(f"警告: {filepath} を読み込めませんでした: {e}", file=sys.stderr)
            continue
 
    if not samples:
        raise ValueError("対象となるソースファイルが見つかりませんでした")
 
    return '\n\n'.join(samples)
 
def generate_readme(repo_path: str, project_name: str) -> str:
    """Sonnet 4.6 を使って README を生成する"""
    code_structure = get_code_structure(repo_path)
 
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=4096,
        system="""あなたは GitHub README の専門家です。
コードを読んで、開発者が最初に必要とする情報を的確に書きます。
冗長な説明は避け、実用的な内容に集中してください。""",
        messages=[{
            "role": "user",
            "content": f"""プロジェクト名: {project_name}
 
以下のソースコードを分析して README.md を生成してください。
 
{code_structure}
 
含めるべきセクション:
1. プロジェクト概要（3文以内）
2. 主な機能（箇条書き、5項目以内）
3. インストール手順
4. 基本的な使い方（コード例付き）
5. 設定オプション（存在する場合のみ）
 
マークダウン形式で出力してください。"""
        }]
    )
 
    return response.content[0].text
 
if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("使用方法: python generate_readme.py <repo_path> <project_name>", file=sys.stderr)
        sys.exit(1)
 
    try:
        readme = generate_readme(sys.argv[1], sys.argv[2])
        print(readme)
    except ValueError as e:
        print(f"エラー: {e}", file=sys.stderr)
        sys.exit(1)
    except anthropic.APIConnectionError:
        print("エラー: Anthropic API に接続できませんでした。ネットワーク接続を確認してください", file=sys.stderr)
        sys.exit(1)
    except anthropic.AuthenticationError:
        print("エラー: API キーが無効です。ANTHROPIC_API_KEY 環境変数を確認してください", file=sys.stderr)
        sys.exit(1)

# ローカルでプレビュー
python scripts/generate_readme.py . "my-project"
 
# 問題なければ README.md に上書き
python scripts/generate_readme.py . "my-project" > README.md

# scripts/generate_changelog.py
import anthropic
import subprocess
import json
import sys
from datetime import datetime
from typing import Optional
 
client = anthropic.Anthropic()
 
def get_recent_commits(since_tag: Optional[str] = None, limit: int = 30) -> list[dict]:
    """直近のコミット履歴を取得する"""
    if since_tag:
        cmd = ['git', 'log', f'{since_tag}..HEAD',
               '--pretty=format:%H|%s|%an|%ad', '--date=short']
    else:
        cmd = ['git', 'log', f'-{limit}',
               '--pretty=format:%H|%s|%an|%ad', '--date=short']
 
    result = subprocess.run(cmd, capture_output=True, text=True)
    if result.returncode != 0:
        raise RuntimeError(f"git log に失敗しました: {result.stderr.strip()}")
 
    commits = []
    for line in result.stdout.strip().split('\n'):
        if not line:
            continue
        parts = line.split('|', 3)
        if len(parts) >= 4:
            commits.append({
                'hash': parts[0][:8],
                'message': parts[1],
                'author': parts[2],
                'date': parts[3]
            })
    return commits
 
def classify_commits_with_haiku(commits: list[dict]) -> dict:
    """Haiku 4.5 でコミットを分類する（コスト効率重視の単純タスク）"""
    commit_text = '\n'.join([f"- {c['message']}" for c in commits])
 
    # Haiku 4.5 はシンプルな分類タスクに最適
    # 入力1Mトークンあたりの料金は Sonnet 4.6 の約1/5
    response = client.messages.create(
        model="claude-haiku-4-5-20251001",
        max_tokens=1024,
        messages=[{
            "role": "user",
            "content": f"""以下のコミットメッセージをカテゴリに分類してください。
 
{commit_text}
 
JSON形式のみで返してください（説明文不要）:
{{"features": [], "fixes": [], "improvements": [], "docs": [], "other": []}}
 
分類基準:
- features: feat: で始まる、または新機能追加
- fixes: fix: で始まる、またはバグ修正
- improvements: refactor: / perf: で始まる、または改善
- docs: docs: で始まる、またはドキュメント更新
- other: 上記以外"""
        }]
    )
 
    text = response.content[0].text
    # JSON 部分を抽出（マークダウンブロックが含まれる場合に対応）
    if '```' in text:
        parts = text.split('```')
        text = parts[1] if len(parts) > 1 else text
        if text.startswith('json'):
            text = text[4:]
 
    try:
        return json.loads(text.strip())
    except json.JSONDecodeError:
        # パースに失敗した場合は全コミットを other に分類
        return {"features": [], "fixes": [], "improvements": [],
                "docs": [], "other": [c['message'] for c in commits]}
 
def format_changelog_with_sonnet(version: str, date: str, classified: dict) -> str:
    """Sonnet 4.6 で読みやすい CHANGELOG エントリを整形する"""
    # features / fixes が空の場合はスキップ
    has_changes = any(classified.get(k) for k in ['features', 'fixes', 'improvements'])
    if not has_changes:
        return ""
 
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        messages=[{
            "role": "user",
            "content": f"""以下の変更内容を CHANGELOG エントリとして整形してください。
 
バージョン: {version}
日付: {date}
変更内容:
{json.dumps(classified, ensure_ascii=False, indent=2)}
 
フォーマット（該当するセクションのみ出力）:
## [{version}] - {date}
 
### 新機能
- 変更内容（features が空の場合は省略）
 
### バグ修正
- 変更内容（fixes が空の場合は省略）
 
### 改善
- 変更内容（improvements が空の場合は省略）
 
技術的な用語をそのまま使い、開発者が読んで内容がわかる表現にしてください。"""
        }]
    )
 
    return response.content[0].text
 
if __name__ == "__main__":
    since_tag = sys.argv[1] if len(sys.argv) > 1 else None
 
    try:
        commits = get_recent_commits(since_tag=since_tag)
        if not commits:
            print("新しいコミットが見つかりませんでした")
            sys.exit(0)
 
        # Step 1: Haiku 4.5 で分類（入力1Mトークンあたり $0.08 — 安価）
        classified = classify_commits_with_haiku(commits)
 
        # Step 2: Sonnet 4.6 で整形（入力1Mトークンあたり $3.00 — 品質重視）
        today = datetime.now().strftime("%Y-%m-%d")
        entry = format_changelog_with_sonnet("unreleased", today, classified)
 
        if entry:
            print(entry)
        else:
            print("記録すべき変更がありませんでした")
 
    except RuntimeError as e:
        print(f"エラー: {e}", file=sys.stderr)
        sys.exit(1)
    except anthropic.RateLimitError:
        print("エラー: API レート制限に達しました。しばらく待ってから再試行してください", file=sys.stderr)
        sys.exit(1)

# scripts/generate_api_docs.py
import anthropic
import sys
from pathlib import Path
 
client = anthropic.Anthropic()
 
def extract_typescript_signatures(source_dir: str) -> str:
    """TypeScript ファイルからエクスポートされた定義を抽出する"""
    src = Path(source_dir)
 
    if not src.exists():
        raise FileNotFoundError(f"ディレクトリが見つかりません: {source_dir}")
 
    ts_files = list(src.rglob('*.ts')) + list(src.rglob('*.tsx'))
    # node_modules・型定義ファイル・テストファイルを除外
    ts_files = [
        f for f in ts_files
        if 'node_modules' not in f.parts
        and not f.name.endswith('.d.ts')
        and not f.name.endswith('.test.ts')
        and not f.name.endswith('.spec.ts')
    ]
 
    signatures = []
    for filepath in ts_files[:20]:
        try:
            content = filepath.read_text(errors='replace')
            lines = content.split('\n')
            relevant_lines = []
            in_jsdoc = False
 
            for line in lines:
                stripped = line.strip()
                # JSDoc ブロック開始
                if stripped.startswith('/**'):
                    in_jsdoc = True
                # export または JSDoc ブロック内の行を収集
                if in_jsdoc or stripped.startswith('export'):
                    relevant_lines.append(line)
                # JSDoc ブロック終了
                if '*/' in line:
                    in_jsdoc = False
 
            if relevant_lines:
                relative = filepath.relative_to(src.parent)
                extracted = '\n'.join(relevant_lines[:80])
                signatures.append(f"### {relative}\n```typescript\n{extracted}\n```")
        except (OSError, ValueError) as e:
            print(f"警告: {filepath} の処理中にエラー: {e}", file=sys.stderr)
            continue
 
    if not signatures:
        raise ValueError("TypeScript のエクスポートが見つかりませんでした")
 
    return '\n\n'.join(signatures)
 
def generate_api_docs(source_dir: str, project_name: str) -> str:
    """Sonnet 4.6 で API 仕様書を生成する"""
    signatures = extract_typescript_signatures(source_dir)
 
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=8192,
        system="""あなたは技術ドキュメントの専門家です。
TypeScript のコードを読んで、開発者が実際に使うためのリファレンスドキュメントを生成します。
- 各関数の引数と返り値の型を明示する
- 使用例は必ず実行可能なコードで示す
- エラーが発生しうる条件を明記する""",
        messages=[{
            "role": "user",
            "content": f"""プロジェクト: {project_name}
 
以下の TypeScript コードから API リファレンスドキュメントを生成してください。
 
{signatures}
 
各エクスポートについて:
1. 機能の簡潔な説明（1-2文）
2. 引数の説明（型・必須/任意・デフォルト値）
3. 返り値の説明
4. 使用例（コード付き）
5. 注意事項（あれば）
 
マークダウン形式で出力してください。"""
        }]
    )
 
    return response.content[0].text
 
if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("使用方法: python generate_api_docs.py <source_dir> <project_name>", file=sys.stderr)
        sys.exit(1)
 
    try:
        docs = generate_api_docs(sys.argv[1], sys.argv[2])
        print(docs)
    except FileNotFoundError as e:
        print(f"エラー: {e}", file=sys.stderr)
        sys.exit(1)
    except ValueError as e:
        print(f"エラー: {e}", file=sys.stderr)
        sys.exit(1)

# .github/workflows/auto-docs.yml
name: Auto Documentation Update
 
on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'lib/**'
      - 'api/**'
      - '!**/*.test.ts'
      - '!**/*.spec.ts'
 
jobs:
  update-docs:
    runs-on: ubuntu-latest
    permissions:
      contents: write
 
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}
 
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
 
      - name: Install dependencies
        run: pip install anthropic==0.50.0
 
      - name: Detect changed file types
        id: changes
        run: |
          CHANGED=$(git diff --name-only HEAD~1 HEAD 2>/dev/null || echo "")
          if echo "$CHANGED" | grep -qE '\.(ts|tsx|py|js|go)$'; then
            echo "source_changed=true" >> $GITHUB_OUTPUT
          else
            echo "source_changed=false" >> $GITHUB_OUTPUT
          fi
 
      - name: Generate README
        if: steps.changes.outputs.source_changed == 'true'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          python scripts/generate_readme.py . "${{ github.repository }}" > /tmp/readme_new.md
          EXIT_CODE=$?
 
          if [ $EXIT_CODE -ne 0 ]; then
            echo "::warning::README生成に失敗しました（コード $EXIT_CODE）"
            exit 0  # 失敗しても他のステップは続行する
          fi
 
          # 差分が30行以上の場合のみ更新（小さな変化でのコミット増加を防ぐ）
          DIFF_LINES=$(diff -u README.md /tmp/readme_new.md 2>/dev/null | wc -l || echo "0")
          if [ "$DIFF_LINES" -gt 30 ]; then
            mv /tmp/readme_new.md README.md
            echo "README_UPDATED=true" >> $GITHUB_ENV
          fi
 
      - name: Update CHANGELOG
        if: steps.changes.outputs.source_changed == 'true'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
 
          if [ -n "$LATEST_TAG" ]; then
            python scripts/generate_changelog.py "$LATEST_TAG" > /tmp/changelog_entry.md
          else
            python scripts/generate_changelog.py > /tmp/changelog_entry.md
          fi
 
          EXIT_CODE=$?
          if [ $EXIT_CODE -ne 0 ]; then
            echo "::warning::CHANGELOG生成に失敗しました"
            exit 0
          fi
 
          # 既存 CHANGELOG の先頭に新エントリを挿入
          if [ -f CHANGELOG.md ]; then
            cat /tmp/changelog_entry.md CHANGELOG.md > /tmp/changelog_merged.md
            mv /tmp/changelog_merged.md CHANGELOG.md
          else
            mv /tmp/changelog_entry.md CHANGELOG.md
          fi
 
      - name: Generate API docs
        if: steps.changes.outputs.source_changed == 'true'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          mkdir -p docs
          python scripts/generate_api_docs.py src/ "${{ github.repository }}" > docs/api.md
          EXIT_CODE=$?
 
          if [ $EXIT_CODE -ne 0 ]; then
            echo "::warning::API仕様書生成に失敗しました"
            exit 0
          fi
 
      - name: Commit documentation updates
        run: |
          if git diff --quiet README.md CHANGELOG.md docs/ 2>/dev/null; then
            echo "ドキュメントに変更はありませんでした"
            exit 0
          fi
 
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add README.md CHANGELOG.md docs/
          git commit -m "docs: auto-update documentation [skip ci]"
          git push

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    temperature=0.3,  # 低めに設定して一貫性を上げる
    # ... 以下略
)

# GitHub Actions 内で変更ファイルのみ取得
CHANGED_TS=$(git diff --name-only HEAD~1 HEAD | grep -E '\.tsx?$' | head -10)