claude-md-generator

CLAUDE.md ジェネレーター

コードベースを読み込みます。Claude に必要な情報だけを過不足なく伝える CLAUDE.md を作成します。

---

重要なルール： 優れた CLAUDE.md は 100 行未満です。Claude がコードを読むだけでは把握できない情報だけを記載します。ファイルを自動で書き込んではいけません。必ず下書きを提示し、ユーザーの承認を待ってください。

コードスニペットのルール： CLAUDE.md にインラインのコード例を記載してはいけません。代わりに file.ts:42 の形式で参照してください。CLAUDE.md にコードを記載するとトークンを無駄にし、内容も古くなります。

---

Step 1: モードを判定する

次の 3 つのモードのいずれかを判定します。

create：CLAUDE.md が存在しません。新規作成します。 update：CLAUDE.md が存在します。独自の内容を削除せずに改善します。 audit：プロジェクト内のすべての CLAUDE.md ファイルを A-F で評価し、品質レポートを出力します。ユーザーが自分の CLAUDE.md について「audit」「check」「review」「grade」と言った場合は、audit モードを実行します。

# Discover ALL CLAUDE.md locations
find . -name "CLAUDE.md" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null
ls ~/.claude/CLAUDE.md 2>/dev/null && echo "Global CLAUDE.md found"
ls .claude.local.md 2>/dev/null && echo ".claude.local.md found"

複数の CLAUDE.md ファイルが見つかった場合は、一覧表示します。次のように尋ねます。「[locations] に CLAUDE.md が見つかりました。すべて更新しますか、それとも [root] だけを更新しますか？」

---

Step 2: audit モード（create/update の場合は Step 3 に進む）

見つかった CLAUDE.md ごとに、次の評価基準を使って A-F で採点します。

評価項目	確認内容
コマンド	ビルド／テスト／lint のコマンドが記載され、実行可能か？
アーキテクチャ	一見して分からない構成が説明されているか？
一見して分からないパターン	注意点、生成ファイル、環境変数の順序が記載されているか？
簡潔さ	100 行未満か？ 明らかな水増しがないか？
最新性	コマンドは現在の package.json/Makefile と一致しているか？
実用性	新しいコントリビューターが質問せずに作業を進められるか？

スコア：90-100 = A、70-89 = B、50-69 = C、30-49 = D、0-29 = F

次の形式で表を提示します。

## CLAUDE.md Audit Report

| File | Score | Grade | Top Issues |
|------|-------|-------|-----------|
| ./CLAUDE.md | 72 | B | Missing gotchas section, test command outdated |
| ./packages/api/CLAUDE.md | 45 | D | No commands, 340 lines (too long), stale arch notes |

**Overall: B (72/100)**

Issues found:
- ./packages/api/CLAUDE.md: 340 lines: well over the 100-line target
- ./packages/api/CLAUDE.md: Test command references `jest` but package.json uses `vitest`
- ./CLAUDE.md: No Gotchas section: most valuable section is missing

レポートの後に、次のように尋ねます。「修正しますか？（すべて／ルートだけ／指定）」

ユーザーが「はい」と答えた場合は、修正するファイルごとに Step 3 に進みます。

---

Step 3: プロジェクト構成をスキャンする

# Project type and package manager
ls package.json yarn.lock pnpm-lock.yaml bun.lockb requirements.txt pyproject.toml Cargo.toml go.mod 2>/dev/null

# Top-level directory structure
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

---

Step 4: ビルドおよびテストコマンドを抽出する

# npm/yarn/pnpm/bun scripts
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 Makefiles
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

次の正確なコマンドを特定します。ビルド、テスト（すべて）、テスト（単一のファイル／名前）、開発サーバー、lint／型チェック。実行に必要な環境変数があれば記録します。

---

Step 5: コードスタイルと注意点を確認する

# Import aliases (most commonly missed)
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

# Environment variables required
cat .env.example 2>/dev/null | grep -v "^#" | grep -v "^$" | head -20

# Auto-generated files (must not be edited)
find . -path "*/node_modules" -prune -o -name "*.ts" -print \
  | xargs grep -l "DO NOT EDIT\|@generated\|Generated by" 2>/dev/null | head -5

# Test setup requirements
cat jest.config.js jest.config.ts vitest.config.ts 2>/dev/null | head -30

# Database/migration setup
ls migrations/ prisma/ drizzle/ db/ 2>/dev/null

注意点に該当するもの（以下のみを含め、それ以外は省略します）：

• 自動生成されるファイル（編集してはいけないもの）
• テスト実行前に必要な環境変数
• デフォルト以外のインポートエイリアスマッピング
• 実行中のサービスが必要なテストコマンド
• 意図的な既知の癖（バグではなく回避策）

---

Step 6: Gemini で CLAUDE.md の下書きを生成する

調査結果をまとめ、下書きを生成します。

cat > /tmp/claude-md-request.json << 'ENDJSON'
{
  "system_instruction": {
    "parts": [{
      "text": "Write a CLAUDE.md file for a software project. Rules: (1) Under 100 lines total. (2) Only include what Claude cannot derive from reading the code. (3) No inline code examples: use file.ts:42 references instead. (4) Sections: Commands, Code Style (only non-defaults), Testing (only if setup needed), Gotchas (required: what trips people up). Skip any section that has nothing non-obvious to say. (5) All commands in code blocks. (6) Preferred order: short Project Overview (1-2 sentences, only if non-obvious), Commands, Architecture (only non-obvious structure), Code Style, Testing, Gotchas. (7) Do not use em dashes. (8) Output only the CLAUDE.md content, no commentary."
    }]
  },
  "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 を Step 3-5 の調査結果に置き換えます。

大規模なプロジェクト（ファイル数 50 以上）の場合： 詳細をインラインで記載する代わりに、CLAUDE.md の末尾に @path ポインターを追加します。

## Extended Reference
See @docs/ai-context/architecture.md for full module map.
See @docs/ai-context/testing.md for integration test setup details.

100 行に収まらない詳細を記載した参照ファイルを docs/ai-context/ に作成します。

---

Step 7: 自己 QA

下書きを提示する前に、次の点を確認します。

• 100 行未満である（行数を確認：echo "$CONTENT" | wc -l）
• インラインのコード例がない（file.ts:42 形式の参照またはシェルコマンドのみ）
• すべてのコマンドがコードブロック内にあり、そのまま実行できる
• 注意点のセクションがあり、実際の項目が 1 つ以上記載されている
• ファイルを見れば明らかなことだけを記載したセクションがない
• em dash を使用していない
• マーケティング用語や水増し表現（「このプロジェクトは React を使用しています」のような表現）がない
• インポートエイリアスが存在する場合は記載されている
• 自動生成ファイルが存在する場合は「編集禁止」と明記されている

確認項目に不備があれば、提示する前に修正します。

---

Step 8: 下書きを提示して承認を待つ

ユーザーの承認なしにファイルを書き込んではいけません。

下書きをコードブロックで提示します。

## Draft CLAUDE.md ([N] lines)

[full draft content here]

---
Write this to CLAUDE.md? (yes / edit first / cancel)

ユーザーが yes と答えた場合：ファイルを書き込み、次のように確認します。 「CLAUDE.md を書き込みました（[N] 行）。セクション：[## ヘッダーの一覧]」

ユーザーが edit first と答えた場合：編集内容を反映し、下書きを再提示します。

ユーザーが cancel と答えた場合：終了します。

含めないもの

• 言語やフレームワークのバージョン（「これは TypeScript プロジェクトです」など）
• フレームワークの仕組み（Claude は React、FastAPI などをすでに理解しています）
• すべての依存関係の一覧
• リンターがすでに適用しているスタイルルール（インデント幅、引用符のスタイルなど）
• README.md と重複する内容
• インラインコードの例や複数行のスニペット
• 同じスタックを使うどのプロジェクトにも当てはまる内容