claude-md-starter

Claude.md スターター — プロジェクトコンテキスト生成ツール

リポジトリをスキャンして技術スタックと規約を推測し、最大 3 つの的を絞った質問をしたうえで、初回セッションから Claude がプロジェクト全体のコンテキストを把握できる、内容が入力済みの CLAUDE.md を作成します。

起動トリガー

明示的なトリガー：

• 「CLAUDE.md を作成して」
• 「CLAUDE.md が空です」
• 「プロジェクトコンテキストを生成して」
• 「CLAUDE.md を初期化して」
• 「このリポジトリ用に Claude のコンテキストを設定して」
• 「CLAUDE.md を埋めて」
• 「claude-md-starter スキルを実行して」

暗黙的なトリガー：

• ユーザーがほぼ空の CLAUDE.md を貼り付け、内容を入力するよう Claude に依頼した場合
• ユーザーがセッションの開始時に、同じプロジェクトコンテキストを何度も説明している場合

トリガーされたらすぐに実行します。スキャン前に質問してはいけません。

ワークフロー（6 ノード）

ノード	役割
1 — 検出	CLAUDE.md の有無を確認し、内容の長さを測定します
2 — スキャン	プロジェクトルートから手掛かりとなるファイルを読み取ります（references/scan-signals.md を参照）
3 — 推測	スキャンした手掛かりから導き出せるすべてのセクションの草案を作成します
4 — 質問	推測できない内容について、最大 3 つの質問をします
5 — 生成	references/claude-md-template.md のテンプレートを使って、完全な CLAUDE.md を作成します
6 — 検証	必須セクションが存在し、プレースホルダーではないことを確認します

ノード 1 — 検出

プロジェクトルートに CLAUDE.md があるか確認します。

見つからない場合： そのままノード 2 に進みます。

見つかり、文字数が 200 以下の場合： 空として扱い、ノード 2 に進みます。

見つかり、文字数が 200 を超える場合： 書き込み前に差分確認・マージの手順を実行します。

1. 既存のファイルを読み取ります

2. ノード 2〜4 を完了し、生成版を作成します

3. セクションごとに比較し、必須 8 セクションそれぞれを次のように分類します：

   • 新規 — 生成版には存在するが、既存版には存在しない、または空である
   • 拡張 — 両方のバージョンに内容があり、生成版のほうが情報を追加している
   • 同一 — 両方のバージョンの内容が同等である
   • 競合 — 両方のバージョンに、異なる空でない内容がある

4. 差分の概要表を提示します。

Section              | Existing | Generated | Action
---------------------|----------|-----------|-------
Project Overview     | present  | enhanced  | +additions available
Tech Stack           | absent   | new       | will add
Commands             | present  | enhanced  | +2 commands found
Architecture         | absent   | new       | will add
Code Conventions     | present  | same      | no change
Testing              | absent   | new       | will add
What NOT To Do       | absent   | new       | will add
Environment Setup    | absent   | new       | will add

5. 次の 3 つの選択肢を提示します：

   • A（推奨） — 既存の内容を維持し、新規および拡張されたセクションのみ追加します（安全な追加方式）
   • B — 生成版で全面的に置き換えます
   • C — 書き込む前に、競合するセクションを個別に確認します

6. 選択された方法でマージした内容を書き込みます。

ノード 2 — スキャン

references/scan-signals.md の一覧を使って、手掛かりとなるファイルを読み取ります。見つかった各ファイルから、判明する項目を抽出します。見つからないファイルは何も通知せずにスキップします。

可能な場合は、すべての読み取りを並行して実行します。

1. package.json — フレームワーク、スクリプト、パッケージマネージャー、依存関係
2. pyproject.toml / requirements.txt / setup.py — Python スタック
3. Cargo.toml / go.mod / pom.xml / build.gradle — 言語
4. Makefile / justfile — 名前付きコマンド
5. .github/workflows/*.yml — CI/CD の手順、デプロイ先
6. Dockerfile / docker-compose.yml — 実行環境、サービス
7. .eslintrc.* / .prettierrc.* / eslint.config.* — JS/TS のコードスタイル
8. ruff.toml / .flake8 / mypy.ini — Python の lint／型設定
9. jest.config.* / vitest.config.* / pytest.ini / conftest.py — テストフレームワーク
10. tsconfig.json — TypeScript の設定
11. .env.example / .env.sample — 必須の環境変数
12. README.md（先頭 40 行のみ）— プロジェクトの説明
13. トップレベルのディレクトリ一覧 — アーキテクチャパターン
14. .gitignore — ビルド成果物と生成ファイル

ノード 3 — 推論

スキャンしたデータを使って、質問する前にできるだけ多くのセクションを埋めます。

• プロジェクト概要 → README.md の最初の段落から取得します。見つからない場合は、package.json の description フィールドを使います。
• 技術スタック → 言語ファイルとフレームワークの依存関係から取得します。
• コマンド → package.json のスクリプト、Makefile のターゲット、ワークフローの実行ステップから取得します。
• アーキテクチャ → プロジェクトのトップレベルのディレクトリ構成から取得します。
• コード規約 → eslint/prettier/ruff の設定値から取得します。
• テスト → テスト設定ファイルとテストディレクトリの場所から取得します。
• してはいけないこと → .gitignore のビルド成果物、ワークフローのブランチ保護、ロックファイルから取得します。
• 環境設定 → .env.example の変数名と docker-compose のサービスから取得します。

ノード 4 — ヒアリング

推論できないことだけを質問します。質問は最大 3 つです。スキャンしたファイルから回答が明らかな質問は省略します。

該当する質問をすべてまとめて 1 つのメッセージで提示します。複数回に分けて質問してはいけません。

CLAUDE.md を完成させるための簡単な質問（該当するものにお答えください）：

1. このプロジェクトは何をするものですか？1 文で教えてください。（README が見つかった場合は省略）
2. Claude に触れさせたり、自動変更させたりしてはいけないファイル、ディレクトリ、システムはありますか？
3. lint 設定に含まれていないチームの規約はありますか？（命名パターン、PR の規模、コミット形式、レビュープロセスなど）

ノード 5 — 生成

references/claude-md-template.md のセクション構成を厳密に守って CLAUDE.md を作成します。

重要なルール：

• 内容を記載するすべてのセクションには、実際の内容を入れてください。[TODO: add your X here] のようなプレースホルダーを使ってはいけません。
• セクションをまったく記入できない場合は、プレースホルダーを書くのではなく、そのセクション全体を省略してください。
• コマンドは正確で、実行可能なものにしてください（「開発サーバーを起動する」ではなく npm run dev）。
• 「してはいけないこと」には、少なくとも 2 項目を記載してください。
• 命令形で簡潔に書いてください（「テストを実行するには……」「……のファイルは編集しないでください」）。
• セクション内で H2 より深い見出しレベルを使ってはいけません。

ノード 6 — 検証

書き込む前に、references/validation-checklist.md に照らして確認します。

• 内容を記載したすべてのセクションに実際の内容があり、プレースホルダーがない
• コマンドのセクションに、実行可能なコマンドが 2 つ以上ある
• 「してはいけないこと」に 2 項目以上ある
• 置換されていないプレースホルダーのテキストが残っていない
• 既存の CLAUDE.md が 200 文字を超える場合、差分確認と統合の手順が完了している

「コマンド」または「してはいけないこと」の要件を満たせない場合は、書き込む前に最後の確認として、要点を絞った質問を 1 つしてください。

出力

プロジェクトのルートにある CLAUDE.md にファイルを書き込みます。書き込み後、次の 1 行の確認メッセージを出力します。

✓ CLAUDE.md written — X sections populated from repo scan, Y from your answers.

差分確認と統合のモードの場合は、追加したセクションと変更せずに残したセクションも出力します。

拒否すべきアンチパターン

• 最初にスキャンを実行せずに CLAUDE.md を生成する
• ヒアリングで 3 つを超える質問をする
• プレースホルダーのセクションを書く（「ここにコマンドを追加」など）
• 差分確認と統合の手順を実行せずに、既存の内容が記載された CLAUDE.md を上書きする
• スキャンしたプロジェクトに即していない、汎用的なひな形を含める
• シグナルファイルで見つからず、ユーザーにも確認していないコマンドを含める

参考資料

• references/scan-signals.md — シグナルファイルの一覧と、それぞれから取得できる情報
• references/claude-md-template.md — CLAUDE.md の標準セクション構成とスタイルルール
• references/validation-checklist.md — 書き込む前に必要な項目と品質確認項目

---

バージョン： 1.0.0