project-blueprint

プロジェクトブループリント

コードベースを調査し、スライスを見つけます。スライスとは、開発者が同じ種類の作業を新たに追加するときに繰り返し現れる構造パターンです。プロジェクトが実際に何をしているかを捉えた、文書によるリファレンスを作成します。あるべき姿ではなく、実態を記録します。

このスキルは記述的なものであり、規範を示すものではありません。現状を記録します。

---

基本原則

1. 理論より発見を重視します。DDD／ヘキサゴナル／クリーンアーキテクチャのチェックリストを当てはめるのではなく、構造を読み取ってパターンを見つけます。
2. 人間が判断に関与します。判断が必要なときは立ち止まって尋ねます。名前をでっち上げず、曖昧なものを分類しません。
3. 永続的な成果物はブループリントのみです。監査や PR レビューは、コードにブループリントを適用した際の一時的な出力であり、コミットしません。
4. 主張より証拠を重視します。すべての主張に、実在するパス／ファイル／行を示します。証拠を示せない場合は、⚠️を付けるか、未解決の質問に移します。
5. 意図的な決定を尊重します。CLAUDE.md または決定仕様書に記録された選択は、アンチパターンではありません。文書化されていない相違点のみを対象とします。

---

このスキルが生成するもの

状況	出力ファイル
単一プロジェクト	docs/architecture/BLUEPRINT.md
N 個のプロジェクトを含むモノレポ	docs/architecture/SYSTEM_MAP.md ＋各プロジェクトの docs/architecture/<project>/BLUEPRINT.md

横断的な調査結果（UNIVERSAL_NOTES.md）は任意であり、デフォルトでは生成されません。ユーザーが横断的な調査を明示的に依頼した場合に限り、チャットに出力します。

---

ワークフロー

ステップ 1 — モノレポか単一プロジェクトかを判定する

トップレベルから深さ 3 までにある、すべてのマニフェストファイルを探します。

find . -maxdepth 3 -type f \( \
  -name '*.csproj' -o -name '*.sln' \
  -o -name 'package.json' \
  -o -name 'pyproject.toml' -o -name 'requirements.txt' -o -name 'setup.py' -o -name 'Pipfile' \
  -o -name 'go.mod' \
  -o -name 'Cargo.toml' \
  -o -name 'pom.xml' -o -name 'build.gradle' -o -name 'build.gradle.kts' \
  -o -name 'composer.json' -o -name 'Gemfile' -o -name 'mix.exs' \
\) -not -path '*/node_modules/*' -not -path '*/.venv/*'

マニフェストをディレクトリごとにまとめます。マニフェストを含むトップレベルまたは深さ 2 までの各ディレクトリを、サブプロジェクト候補とします。依存関係、ビルド、キャッシュ、生成物、ベンダーの各フォルダーは除外します。

⏸ 確認ポイント 1：立ち止まって質問する:

「次の N 個のプロジェクトを検出しました：[リスト]。これは正しいですか？不足しているものや、誤って含まれているものはありますか？」

確認を待ちます。不確かな場合は先に進みません。

ステップ 2 — プロジェクトごとに、フェーズ A：スタックとレイヤーを調べる

確認済みの各プロジェクトについて、次を読みます。

• マニフェストファイル → 言語、フレームワークのバージョン、主要な依存関係
• README.md、CLAUDE.md、docs/architecture* → 宣言された規約、禁止されているライブラリ、移行に関するメモ
• .csproj の参照／package.json のワークスペース／go.mod のモジュール → モジュール間の依存関係グラフ

確認できる場合は、レイヤー構造をマッピングします。

• .NET の場合：Api → Application → Domain ← Infrastructure / Persistence
• Node／Python／Go の場合：相当する構造があれば記録し、なければ「フラット構造」と記します。

ステップ 3 — プロジェクトごとに、フェーズ B：用語を検出する

ディレクトリツリーを走査します（深さ 3～4。bin/obj/node_modules/.venv/dist/target/__pycache__ を除外）。

各構成要素について、インスタンスがあるかを確認します。

構成要素	検出方法
エンティティ／集約	ID と不変条件を持つクラスが含まれる Domain フォルダー
値オブジェクト	値による等価性を持つ、小規模で不変な型
リポジトリ	I*Repository ポートと実装
ドメインサービス	Domain 内のサービスクラス
アプリケーションサービス／ユースケース	オーケストレータークラス（サービス、ユースケース、コマンドハンドラー）
ドメインイベント	イベント型と公開箇所
ドライバーアダプター	HTTP コントローラー、CLI ハンドラー、WebSocket、キューコンシューマー
被駆動アダプター	DB、HTTP クライアント、メッセージプロデューサー
ポート（インターフェース）	Domain（または Application — その場合は非対称性として記録）の I*
Options／設定クラス	IConfiguration／設定からバインドされる、型付きの設定

見つけたものにラベルを付ける必要がある場合は、アーキテクチャパターンの特徴（DDD、ヘキサゴナル、クリーンアーキテクチャ、レイヤード、CQRS など）を確認するため、references/patterns.md を参照します。

ステップ 4 — プロジェクトごと、フェーズ C：スライスの検出

スライスとは、繰り返し現れるフォルダー／ファイルの構成、つまり、同種の新しい作業を追加するときに開発者が従う構造上のテンプレートです。

検出方法：

1. プロジェクトのルートから深さ 2～3 のディレクトリーを一覧表示します
2. 各ディレクトリーについて、子ファイルの名前を記録します
3. 子ファイルの名前が同じ正規表現／パターンに一致するディレクトリーをグループ化します
4. インスタンスが N ≥ 2 のグループ → スライス候補
5. インスタンスが N = 1 のグループ → 単独候補（人による分類が必要）

N ≥ 2 のスライス候補ごとに：

• 構成：メンバーシップを定義するファイル名の正規表現
• インスタンス：パスの完全な一覧。該当する場合は、次元でタグ付けします（ステップ 5 を参照）
• 正規リファレンス：以下のヒューリスティックを使って選択します
• 同時に作成されるファイル：同じコミットで追加されるほかのもの（DI 登録、テストのミラー、コントローラーのエンドポイント、オプションクラス）
• 制約：インポートの許可／禁止、命名、正規リファレンスで確認されたフレームワークの選択
• バリエーション：正規リファレンスの構成から外れるインスタンス。どのように異なるかを記述します
• ステータス：active（新しい作業に推奨）／frozen（レガシー。拡張しない）／deprecated（削除予定）

正規リファレンス選択のヒューリスティック（優先順）：

1. 構成全体を実質的に網羅している（空のファイルがない）
2. 対応するテストがある
3. 最近変更されている（≤ 6 か月）
4. 監査履歴で指摘されていない
5. 説明的な名前である
6. 実質的な Response／出力がある

ヒューリスティックで 2 つのインスタンスが同点の場合は、2 段階の正規リファレンスを使用します。Primary（ここから始める、よりシンプルな例）＋ Advanced（より充実した例）。

⏸ 停止して質問するチェックポイント 2（必要な場合）：

「スライス X には、同程度に有力な正規リファレンスが 2 つあります：A と B です。どちらを Primary、どちらを Advanced にしますか？ それとも両方を正規リファレンスとしますか？」

ステップ 5 — 次元の検出（単一プロジェクト内）

内部の縦割り領域を分けるフォルダー／名前空間のパターンを探します。

• チャネルベース：複数の入力チャネルを持つプロジェクト内で、Voice* と Whatsapp* のマーカーなど
• テナントベース：Internal* と External* のマーカーなど
• モジュールベース：明示的に名前が付けられた境界づけられたコンテキスト

見つかった場合は、すべてのスライスインスタンスに次元（voice | text | channel-agnostic など）のタグを付けます。

⏸ 停止して質問するチェックポイント 3：

「マーカー [...] を持つ次元 X を検出しました。次元ラベルを確認するか、修正してください。」

ステップ 6 — N=1 の候補を分類する

N=1 で見つかったものをすべて一覧に集めます。それぞれについて質問を 1 つします。

⏸ 停止して質問するチェックポイント 4（N=1 の候補をすべてまとめて確認）：

「N=1 の候補が N 個見つかりました。それぞれを分類してください：」 • [パス／名前]：singleton（固有の役割があり、複製されない） | template（この種の最初の例で、今後増える） | smell（複数に分割すべきだったもの）？

続行する前に、まとめて回答を待ちます。

ステップ 7 — 横断的な規約と非対称性

プロジェクト全体に適用されるものの、スライスには該当しないルールを記録します。

• マッパー — 境界ごとの配置場所
• シリアライゼーション — JSON の大文字・小文字の扱い、BSON など
• バリデーション — フレームワークと登録方法
• エラーモデル — エンベロープの構造、コードの規約
• 依存関係の方向 — マニフェストグラフで確認済みのもの
• ロギング／トレース — 単一の情報源、規約

既知の非対称性を明示的に記録します。過去の配置、命名上の例外、進行中の移行などが該当します。読み手が「これは意図的だが、少し変だ」と把握できるようにし、修正しようとしないためです。

ステップ 8 — （モノレポのみ）SYSTEM_MAP を構築する

プロジェクトごとのブループリントができたら、以下を網羅するシステムマップを構築します。

• プロジェクト一覧と各プロジェクトの役割
• プロジェクト間の呼び出し（呼び出し元 → 呼び出し先 → プロトコル → コントラクト）
• 言語をまたぐ境界をルールとともに明示
• 同じ言語内の境界（存在する場合）
• 共有する外部依存関係（データベース、SaaS、キュー）

プロジェクト間の境界ごとに、以下を記録します。

• 誰がコントラクトを所有するか
• どのような変更で調整が必要になるか
• 導入済みの緩和策

ステップ 9 — 書き込み前の概要

ファイルを書き込む前に、次の内容を提示してください。

Summary
- Projects: [list]
- Slices per project: [count]
- N=1 classified as: [singletons | templates | smells]
- Dimensions: [if any]
- Files to be written: [list of paths]

⏸ 停止して確認するチェックポイント 5：

「上記のファイルを書き込んでもよいですか？ それとも先に調整しますか？」

ステップ 10 — ファイルを書き込む

確認を得てから実行してください。構成には assets/blueprint-template.md と assets/system-map-template.md を使用してください。

書き込み後、各ファイルのパスを提示し、「これらをコミットしますか？ それとも先にレビューしますか？」と確認してください。明示的な許可なしにコミットしないでください。

---

停止して確認するチェックポイントの概要

#	チェックポイント	タイミング
1	プロジェクト一覧	ステップ 1 の後（常に）
2	正式な候補の優先順位	ステップ 4 の実行中（曖昧な場合のみ）
3	次元のラベル	ステップ 5 の後（次元が検出された場合のみ）
4	N=1 の分類	ステップ 6 の後（常に、一括で確認）
5	書き込み前	ステップ 10 の前（常に）

実行中に本当に曖昧な点が見つかった場合は、任意で確認してください。

• 形状は明らかでも、名前がはっきりしない場合のスライス名
• バリアントの分類（意図的なバリアントか、意図しない乖離か）
• CLAUDE.md に記載がない場合のスライスのステータス（アクティブ／凍結／非推奨）

---

エージェントが観察することと、人間が判断すること

エージェントが観察すること（事実に基づき、質問しない）：

• フォルダーの構造とその反復数
• モジュール間のインポート
• ファイルサイズ、メソッド数
• ソースコード内のデフォルト値
• テスト／DI 登録の有無
• アーキテクチャパターンの特徴との一致

人間が判断すること（必ず確認する）：

• N=1 がシングルトン、テンプレート、設計上の問題のどれに該当するか
• 明らかでない場合のスライス名
• 候補が同等の場合、プライマリとアドバンスのどちらを正式な候補とするか
• バリアントが意図的なものかどうか
• ドキュメントに記載がない場合のステータス（アクティブ／凍結／非推奨）

この分離は重要です。エージェントが人間の判断を推測すると、ブループリントに主観が入り込みます。人間が判断を示せば、ブループリントは根拠に基づいたものになります。

---

このスキルで行わないこと

• アンチパターン監査を永続ファイルとして生成すること（差分には pr-antipattern-review を使用してください。依頼があれば、ユニバーサルな網羅調査を一時的に実行することもできます）
• リファクタリングを推奨すること
• PR をブループリントと照合すること（pr-antipattern-review を使用してください）
• チームに代わってアーキテクチャ上の決定を行うこと

---

関連項目

• references/slice-discovery.md — スライスを見つけるための詳細なヒューリスティック
• references/patterns.md — アーキテクチャパターンの特徴（DDD、ヘキサゴナル、クリーンなど）
• references/universal-checks.md — プロジェクトに依存しない観察事項（要求時のみ出力）
• assets/blueprint-template.md — プロジェクトごとの出力テンプレート
• assets/system-map-template.md — モノレポ向けの出力テンプレート