feature-block-design

brainstorming で合意済みの「何を作るか / どう変更するか」を入力に、システムを疎結合な機能ブロックに分割し、分割仕様書を作成・更新するスキル。

いつ使うか

brainstorming スキルが完了した直後で、writing-plans に進む前。
ただし以下の適用要否判定に該当しなければ本スキルは適用せず、下記の終了手順（確定前レビューの提示を経て次手を確認する）に従う。

適用要否判定（しきい値）

以下のいずれかに該当する場合のみ後続フェーズへ進む:

• brainstorming 出力に「主要機能（ユーザー価値を直接提供する機能）」が 2 つ以上 含まれる
• 想定モジュール / コンポーネント / サービスが 3 つ以上 ある

該当しない場合は、判定理由をユーザーに提示して本スキルを終了する。このとき、直前に確定した brainstorming の設計文書（ファイル化されない場合は承認済みの設計）が spec 確定点にあたるため、pre-finalization-review の提示操作を呼んで確定前レビューを提示したうえで次手（writing-plans への直行を含む）を確認する。本スキルの側から writing-plans 直行を推奨側に固定しないこと。

brainstorming との責務境界

スキル	責務
brainstorming	何を作るか / なぜ作るか / どんな方針で作るかの合意
feature-block-design（本スキル）	その方針をどんな機能ブロックに分割し、各ブロックがどんな責務・インターフェース・データを持つかを確定し、分割仕様書として出力する
writing-plans	上記を入力に、実装をどんなタスクに分け、どの順で進めるかの plan を作る

重要な前提

• 初期設計の判断の分担は start-work の references/decision-delegation.md に従って分割後の仕様にも所在を保持する。本スキルの承認・次手確認も同じ分担へ照らし、既に承認された判断を再質問しない。分割で相談事項や限度が変わる場合は相談する。

• 仕様書は常に「現時点のシステム全容のスナップショット」として維持する

• 差分のみを記載した別ファイル（変更差分仕様書）を作ってはならない

• 「なぜ変更したか」は ADR に書き、仕様書には「今どうなっているか」のみを書く

• 機能ブロックは高凝集・疎結合・単一責任を満たすように切り出す。ただしプロジェクトのパラダイム・規模・制約に応じて適切な粒度を判断する。責務と依存関係を明確にできる粒度とし、独立して変更・検証する必要がない部分まで、将来の可能性だけを理由に分割しない。

出力ディレクトリ構造

docs/current/specs/YYYY-MM-DD-<topic>/
├── 00-overview.md       # 概要、機能一覧、ブロック関係、主要処理フロー、設計上の意思決定、スコープ外、完了基準
├── 01-<block-slug>.md   # ブロック1の詳細
├── 02-<block-slug>.md   # ブロック2の詳細
└── ...

• ブロック番号はゼロ埋め2桁の連番
• ブロックスラッグは英小文字とハイフン

手順

Phase 0: 適用要否判定

上記の「適用要否判定」を実施する。該当しなければ、上記のとおり確定前レビューの提示を経てスキル終了。

Phase 1: モード判定

該当 topic の仕様書ディレクトリ docs/current/specs/*-<topic>/ の有無で分岐:

• 存在しない → 新規モード
• 存在する → 修正モード（既存ディレクトリを入力に含める）

Phase 2: 機能ブロック抽出

粒度ガイドライン（1ブロックの基準）

• 単独で説明・テスト可能な責務単位
• 他ブロックとの依存はインターフェース（関数シグネチャ、API、メッセージ等）経由のみ
• 1ブロックの内部詳細を変更しても、他ブロックの実装に影響を与えない
• ブロック数の目安: 2〜7個。超過する場合は階層化を検討し、ユーザーに確認する

抽出時の自己問いかけ

• このブロックは「何をするか」を1文で説明できるか
• 他ブロックを知らずにこのブロックを実装・テストできるか
• ブロック間の依存方向は循環していないか

ブロック間の依存関係・接続点（置き場・誰が読む・何が検査する・起動順序・不変条件）を書く前に、接続先が既存の実体（コード・設定・構成定義）を持つ場合はそれを読み直す。文書の要約や記憶から書かない。新規要素どうしの接続はこの限りではない。

抽出結果（ブロック名、責務一行サマリ、依存関係）をユーザーに提示して承認を得る。
この承認は ADR 候補（アーキテクチャ決定）。節目の前後で行う共通処理経由で decision-log を呼ぶ。

Phase 3: 00-overview.md の作成 / 更新

ブロック間関係図・主要な処理フローを書く前に、Phase 2 と同様に接続先の実体を読み直す（文書の要約・記憶から書かない）。

以下の構成で書く:

1. このドキュメントの読み方（含まれるファイルの一覧）
2. 背景・動機
3. 全体アーキテクチャ（機能ブロック一覧表 + ブロック間関係図）
4. 主要な処理フロー
5. 設計上の主要な意思決定（ADR への参照）
6. スコープ外（YAGNI）
7. 完了基準

修正モードの厳守事項:

• 既存内容を全置換的に更新する。新セクション追記による継ぎ接ぎを禁止
• 「変更前」「変更後」「差分」のような節を作らない。常に最新スナップショットのみを書く
• 変更理由・経緯は ADR にのみ書く。仕様書からは ADR を参照リンクで指す

Phase 4: 各ブロック詳細の作成 / 更新

ブロック数だけ繰り返す。ファイル名は NN-<block-slug>.md。

「対象ファイル」「インターフェース」「このブロック固有の制約・前提」など接続点の記述では、Phase 2 と同様に接続先の実体を読み直してから書く。

各ファイルの構成:

1. 対象ファイル（実装が触る予定のファイル / モジュールパス）
2. 責務（1〜3 文）
3. インターフェース（公開関数 / API / 入出力データ形式）
4. サブ機能 / 内部構成
5. データモデル（必要な場合）
6. このブロック固有の制約・前提
7. 関連 ADR

修正モードでは Phase 3 同様、既存記述の整合性を保ちながら書き換えで更新する。

Phase 5: 整合性セルフレビュー

以下を機械的にチェックし、不整合があれば該当フェーズに戻る:

• 00-overview.md の機能ブロック一覧表のブロック数 = NN-<block>.md ファイル数
• 各 NN-<block>.md の「対象ファイル」が他ブロックと衝突していないか
• ブロック間インターフェースの呼出側と被呼出側の記述が一致するか
• 「変更前 / 変更後 / 差分」を示す節が混入していないか（スナップショット規約違反の検出）

Phase 6: 節目の前後で行う共通処理

本スキルの完了時点が spec 確定点にあたるため、まず pre-finalization-review の提示操作を呼んで確定前レビューを提示し、次手（writing-plans への遷移を含む）を確認する。

そのうえで start-work の節目の前後で行う共通処理が自動適用する:

• ADR 候補（機能ブロック構造の選択など）を decision-log 経由で記録
• handoff を update（マイルストーン到達）。確定前レビューの提示結果を review= として併記する

対応する原則

• 原則1（追跡可能性）: ブロック分割時の ADR 候補検出、handoff 更新
• 原則2（関心の分離）: 機能ブロックを独立した責務として切り出す。本スキル自身が原則2拡張版の体現
• 原則3（コンテキスト管理）: 分割仕様書により、AI が必要なファイルだけコンテキストに載せられる
• 原則4（人間の関与）: ブロック構造の承認ゲート、適用要否判定理由の提示
• 原則5（漸進的検証）: ブロック単位での詳細化により、後続の writing-plans / 実装が小さな単位で進められる