Project Scaffolding

プロジェクトのスキャフォールディング

目的

任意のプロジェクトに対して、完全な CLAUDE.md と .claude/ ディレクトリ構造を生成します。これにより、AI エージェントは最初のセッションから効果的に作業するために必要なコンテキスト（ビルドコマンド、規約、品質ゲート、セッションのトラッキング）を得られます。

スタックの検出

スキャフォールディングの前に、マニフェストファイルをスキャンしてプロジェクトの技術スタックを検出します。

検出されたファイル	検出されるスタック	ビルドツール
tsconfig.json	TypeScript	tsc、npm/yarn/pnpm
package.json (tsconfig なし)	JavaScript	npm/yarn/pnpm
pyproject.toml	Python	pip/poetry/uv
setup.py または requirements.txt	Python (レガシー)	pip
Cargo.toml	Rust	cargo
go.mod	Go	go
Makefile	内容を確認	さまざま
Dockerfile	コンテナ	docker

検出の手順

1. プロジェクトルートのファイルを一覧表示し、上記のマニフェストファイルを確認します
2. package.json が存在する場合は、scripts を読み取ってビルド／テスト／リントのコマンドを見つけます
3. pyproject.toml が存在する場合は、[tool] セクションを読み取って設定済みのツールを確認します
4. 複数のスタックが検出された場合は、それらすべてを記録します（モノレポパターン）

CLAUDE.md の生成

references/claude-md-template.md のテンプレートを使用し、検出した情報を埋め込みます。目標: 200 行未満。 Claude Code はシステムプロンプト内で CLAUDE.md を約 200 行で切り捨てるため、簡潔に保ってください。

1. プロジェクト概要 — README.md または package.json の description を読み取ります
2. ビルドと実行のコマンド — マニフェストの scripts セクションから検出します（最もよく使われる 8〜10 件を残し、「完全なリストは [マニフェスト] を参照」と追記します）
3. トリガー — ファイルパターンをドキュメントやスキルにマッピングし、オンデマンドで深いコンテキストを提供します
4. 命名規則 — スタックに基づいて references/naming-conventions.md から選択します。表が大きい場合は docs/CONVENTIONS.md に移し、トリガーから参照します
5. テストコマンド — 検出するか、ユーザーに確認します
6. リントコマンド — 検出するか、ユーザーに確認します

あらかじめ埋め込まれるもの

• コアとなる振る舞い（自己改善および並列セッションのルールを含む）
• トリガーセクション（検出したプロジェクト構造から生成）
• テストファースト開発のルール
• Git コミットのルール（conventional commits）
• 禁止ファイル（.env、認証情報、node_modules など）
• 環境変数のルール

検出またはユーザー入力が必要なもの

• プロジェクト名と説明
• ビルド、テスト、リント、開発の各コマンド
• スタック固有の命名規則
• ユーザーが希望する任意のカスタム規約

トリガーの生成

トリガーセクションはファイルパターンをより詳細なドキュメントにマッピングし、CLAUDE.md を肥大化させることなくオンデマンドでコンテキストを読み込めるようにします。

トリガーの生成方法

1. プロジェクト構造をスキャンして、特徴的なディレクトリ（例: src/、lib/、tests/、docs/）を探します
2. 既存のドキュメントファイル（docs/*.md、ARCHITECTURE.md、CONTRIBUTING.md）を特定します
3. 各ソースディレクトリを、最も関連するドキュメントまたはスキルにマッピングします
4. 標準的なパターンを含めます: Dockerfile → デプロイのドキュメント、tests/ → テストのドキュメント、新規ファイル → 規約

生成されるトリガーの例

| File Pattern | Load |
|---|---|
| src/api/* | Read: docs/API.md |
| src/components/* | Read: docs/COMPONENTS.md |
| tests/* | Read: docs/TESTING.md |
| Dockerfile, docker-compose* | Read: docs/DEPLOYMENT.md |
| New .ts files | Read: docs/CONVENTIONS.md |

まだドキュメントが存在しない場合は、スキャフォールディング中に TODO プレースホルダーを含むスタブのドキュメントファイルを生成します。

MEMORY.md の初期化

検出したスタックから得られた最初の教訓で、プロジェクトの MEMORY.md を初期化します。MEMORY.md はすべての Claude Code のシステムプロンプトに自動的に読み込まれ、自己改善ループを形成します。

場所

~/.claude/projects/<project-path-with-dashes>/memory/MEMORY.md

ここで <project-path-with-dashes> は、/ を - に置き換えたプロジェクトの絶対パスです（例: -Users-dev-myproject）。

何をシードするか

1. スタックの詳細 — 言語バージョン、ビルドツール、パッケージマネージャー
2. アーキテクチャパターン — 検出中に判明したモジュール構造
3. 検出されたスタックの一般的な落とし穴:
   • TypeScript: ESM のインポート拡張子、tsconfig の厳格さ、型のみのインポート
   • Python: 仮想環境のアクティベーション、__init__.py の要件、mypy による型チェック
   • Rust: 借用チェッカーでよくある間違い、フィーチャーフラグ、ワークスペースパターン
   • Go: モジュールパス、エクスポートされるものとされないもの、エラーのラップ
4. テストパターン — フレームワーク、モック戦略、テストファイルの配置場所
5. オーナーの設定 — /init 中にユーザーが指定した規約

サイズの目安

最初は 55 行未満に抑えてください — エージェントがセッション中に学習して成長する余地を残します。200 行のシステムプロンプトの制限は MEMORY.md にも適用されます。

ディレクトリ構造の作成

以下の構造を作成します:

.claude/
├── commands/
│   └── parallel.md            ← multi-session coordination guide
├── reports/
│   ├── _registry.md          ← from session-management references
│   ├── _tech-debt.md         ← from session-management references
│   ├── architecture/
│   ├── bugs/
│   ├── code-review/
│   ├── config/
│   ├── dependencies/
│   ├── docs/
│   ├── features/
│   ├── integration/
│   ├── performance/
│   ├── refactor/
│   ├── security/
│   ├── testing/
│   ├── ci/
│   ├── tech-debt/
│   └── release/
└── scripts/
    └── post-edit-check.sh     ← from quality-gates hook

手順

1. .claude/reports/ の下に 15 個のカテゴリディレクトリをすべて作成します
2. registry-template.md の内容を .claude/reports/_registry.md にコピーします (空の状態で、すぐに使えます)
3. tech-debt-template.md の内容を .claude/reports/_tech-debt.md にコピーします (空の状態で、すぐに使えます)
4. Bash 経由で cp を使って post-edit-check.sh を .claude/scripts/ にコピーします (Write ツールは使わないでください — Write は改行コードを壊してスクリプトを動かなくする可能性があります):

   mkdir -p .claude/scripts && cp "$CLAUDE_PLUGIN_DIR/scripts/post-edit-check.sh" .claude/scripts/post-edit-check.sh && chmod +x .claude/scripts/post-edit-check.sh
   

   $CLAUDE_PLUGIN_DIR が利用できない場合は、find ~/.claude -name "post-edit-check.sh" | head -1 でプラグインを探し、そこから cp してください。
5. プロジェクト固有のファイル所有権の境界を記述した .claude/commands/parallel.md を作成します
6. 自動メモリのパスに MEMORY.md をシードします (上記の「MEMORY.md のシード」セクションを参照してください)

フックのセットアップ

検出されたスタックに基づいて、PostToolUse フックを設定します:

1. .claude/settings.json を 正確に 以下の内容で作成または更新します (追加の引数や変更は加えません):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/scripts/post-edit-check.sh"
          }
        ]
      }
    ]
  }
}

重要: コマンドは正確に bash .claude/scripts/post-edit-check.sh でなければなりません — $CLAUDE_TOOL_INPUT_FILE_PATH のような引数を追加しないでください。スクリプトは環境から $CLAUDE_TOOL_INPUT を自動的に読み取ります。

2. スクリプトを変更しないでください — ファイル拡張子の検出によって、すべてのスタック (TypeScript、Python、Rust、Go) をすでに処理しています。そのままコピーしてください。

インタラクティブな流れ

スキャフォールディングを実行する際は、決定のためにユーザーと対話します:

ステップ 1: 検出と確認

Detected stack: TypeScript (package.json + tsconfig.json)
Build: npm run build
Test: npm test
Lint: npm run lint

Does this look correct? Any changes?

ステップ 2: カスタム規約

Any project-specific conventions I should add to CLAUDE.md?
For example:
- Specific directory structure rules
- Required code patterns
- Forbidden patterns or anti-patterns

ステップ 3: 生成とレビュー

1. 検出された情報とユーザー提供の情報をすべて含めて CLAUDE.md を生成します
2. .claude/ ディレクトリ構造を作成します
3. フックをセットアップします
4. 作成された内容の概要を表示します

ステップ 4: 確認

Created:
- CLAUDE.md (project configuration with Triggers, under 200 lines)
- .claude/reports/ (15 category dirs + registry + tech debt tracker)
- .claude/commands/parallel.md (multi-session coordination)
- .claude/scripts/post-edit-check.sh (auto-validation hook)
- .claude/settings.json (PostToolUse hook wired up)
- MEMORY.md (seeded at ~/.claude/projects/.../memory/MEMORY.md)

Ready to start developing with session tracking, auto-validation,
and self-improvement across sessions.

相互参照

• references/claude-md-template.md — プレースホルダーセクション付きの完全な CLAUDE.md テンプレート
• references/naming-conventions.md — 言語別の命名規則表 (TS、Py、Rust、Go)
• references/git-workflow.md — Conventional Commits、ブランチ運用、PR パターン