feature-build

Feature Build（新機能の設計から並列実装まで）

新しい機能を「いきなり書き始めず、まず設計し」、その設計を基準に実装を衝突しないタスク(wave)へ分割して 並列実装＋段階検証するスキル。ゴールは 速さ(並列)と安全(設計先行＋既存整合＋検証)の両立。

review/fix が「既存コードを直す」のに対し、本スキルは「新しい振る舞いをゼロから足す」開発フェーズを担う。 ただし基本思想は共通: 構造化して理解し、衝突しない単位に分け、並列で進め、段階的に検証する。

いつ使うか

• 「この機能を追加して / 〜を実装して / 〜を作って / 〜できるようにして」と言われたとき。
• 新しいエンドポイント・画面・CLI コマンド・ジョブ・モジュールなど、複数ファイルにまたがる機能開発。
• 既存の設計に新しい部品を整合的に足したいとき（既存パターン踏襲が要るとき）。

単一ファイル・数行で明白な追加だけなら本スキルは不要(普通に書く)。既存コードの構造改善が主目的なら architecture-review / architecture-fix を使う。

進め方（5フェーズ）

Phase 0 — 要件とスコープの確定

• 何を作るかを1〜3文で言語化する（ユーザーストーリー / 入力→出力 / 受け入れ条件）。曖昧なら作り始める前に聞く。
• スコープ境界を決める: 含むもの / 含まないもの（YAGNI: 今要らない汎用化は足さない）。
• 受け入れ条件(Acceptance Criteria) を箇条書きにする。これが後段の検証(verify)の基準になる。
• 適用前ゲート(壊れた状態で始めない):
  • git 作業ツリーがクリーンか確認。未コミット変更があれば退避/コミットを促す。
  • main 等の保護ブランチ上なら作業ブランチを切る(feat/<name>)。
  • ベースラインのビルド/テストが通ることを確認(references/verify.md)。最初から赤なら先に切り分け。

Phase 1 — 全体を理解し、変更箇所を漏れなく特定してから設計する（本スキルの核心その1）

最重要の原則: コードベース全体を理解し「どこを変えればいいか」を漏れなく把握してから、初めて実装に入る。 1ファイルだけ見て書き始めない。新機能は既存設計の上に乗るので、関係する経路・配線・規約を先に押さえる。 詳細手順は references/design.md を読む。Phase 1 は次の 1A→1B→1C の順で進める。

1A. 関連範囲を全体として理解する（理解ゲート — ここを飛ばさない）

新機能が触れる「機能の道筋」を端から端まで追って、頭の中に地図を作る。最低限これを押さえる:

• 既存の同種機能を1つ丸ごと読む: 似た機能(同種のエンドポイント/画面/コマンド/ジョブ)を入口から出口まで 追跡する。入口(ルート/エントリ)→検証→処理→永続化/出力→テスト、までを通しで読む。これが踏襲テンプレートになる。
• レイヤと依存方向: どの層に何が置かれ、誰が誰を import するか。新コードが乗る層と守るべき依存方向を確認。
• 横断的関心事の作法: 設定・DI・ロギング・エラー処理・認可・トランザクションが既存でどう引き回されているか。
• 接続点(seam): 新機能が既存とつながる箇所(呼ばれる場所・呼ぶ場所・イベント/フック登録点)。
• 規約: 命名・ディレクトリ配置・テストの置き方/スタイル。新規発明より一貫性を優先する。

大きい機能では理解を並列探索でファンアウトしてよい(既存パターン/データモデル/I/O境界/配線箇所を別エージェントで 調べ、構造化要約を集約)。推測で断定しない——「ここを変えれば足りる」は grep / 参照追跡 / 型・ビルドで裏を取る。

1B. 変更箇所を漏れなく洗い出す（チェンジマップ）

理解した道筋をもとに、手が入る場所を1つ残らずリスト化する。新規作成だけでなく既存編集を取りこぼさない (配線漏れは「動かない」の最大要因)。各項目は パス + 新規/編集 + 何のため で書く。最低限この観点を当てる:

• 機能本体(新規ファイル) / 既存ロジックへの追記
• 配線: ルーティング/エントリ登録・DI/コンテナ登録・export/index 追記・イベント/フック登録
• データ: スキーマ/型/マイグレーション/シード
• 設定: 環境変数・設定ファイル・フィーチャーフラグ
• テスト: 新規テスト・既存テストへの影響・フィクスチャ
• ドキュメント: README・API ドキュメント・使い方

このチェンジマップ(影響を受ける全ファイル)が Phase 2 の wave 分割の入力になる。漏れていると配線 wave が 不完全になり機能が繋がらないので、ここの網羅性を最優先する。確信が持てない接続点は「(要確認)」と明示する。

1C. 設計する（契約を先に固める）

理解とチェンジマップを基準に設計を確定する:

• 配置とレイヤ: 新コードを置くパッケージ/層。依存方向(基盤→ドメイン→アプリ→UI)を守る。
• 公開インターフェース: 関数/型/API シグネチャ・データ形・エラー型を先に決める(実装より先に契約を固める)。
• データ/制御フロー: 入力→処理→出力の経路を1本通す。
• 複数案がありトレードオフが大きいときは、案を併記して推奨を1つ示し、必要なら確認を取る。
• YAGNI: 今の受け入れ条件に要らない汎用化・拡張点は足さない。

Phase 2 — 実装計画を立て、タスクを wave に分割する（本スキルの核心その2）

設計を実装タスクの DAG に落とす。アルゴリズムは fix の発想を流用、詳細は references/planning.md を読む。要点:

1. 機能を小さな実装単位(task) に割る。各 task は「触れるファイル集合」「依存(先に要る task)」「検証」を持つ。
2. 基盤先行: 型/スキーマ/インターフェースなど他 task が依存する土台は先頭 wave に置く(deps の源)。
3. ファイルが重ならない task を貪欲に同一 wave へ詰める(wave 内はファイル素集合＝並列編集が衝突しない)。
4. 配線(routing/DI/export/設定)は最終 wave で中央集約するのが安全(複数 task が同じ配線ファイルに触れがちなため)。
5. 結果は [wave0, wave1, ...]。wave 内は並列、wave 間は逐次(前段の検証 PASS 後に次段)。

テスト同伴: 各 task は実装と一緒にテストを書く(受け入れ条件→テストケース)。重要パスは**テスト先行(TDD)**を明記。

Phase 3 — Workflow で並列実装

Workflow ツールで wave 列を実行する。スクリプト雛形は references/workflow-template.md を読んで埋める。 構造(wave 単位の barrier: 次 wave は前 wave 統合後に開始):

• 各 PARALLEL wave は parallel(wave.map(t => () => agent(buildPrompt(t), {schema: RESULT})))。
  • 各 subagent には task の title / 設計仕様(契約) / 触れてよいファイル / 依存先で確定した型・IF / 受け入れ条件 / verify を渡す。
  • 「指定ファイルだけを作成/編集し、既存パターンに倣い、テストも書き、task.verify を実行して結果を構造化で返せ。 他 task のファイルには触れない(wave 設計の前提)」と明示する。
  • subagent は {id, status: done|failed|blocked, files_changed[], tests_added[], verify_passed, verify_output, notes} を返す。
• 配線 wave(SERIAL)は中央で1つずつ繋ぎ込み、その都度検証する。
• wave 完了ごとに 全体検証(references/verify.md: ビルド/型/リンタ/テスト/起動スモーク)を main 側で実行し、 PASS したら その wave をグループコミットする。

Phase 4 — 統合・検証・受け入れ確認・レポート

• グループ毎コミット: 各 wave の検証 PASS 直後にその範囲をコミット。メッセージは feat: <要約> (task: a,b,…) 形式。
• 受け入れ条件の確認: Phase 0 の Acceptance Criteria を1つずつ満たしているか検証(可能なら実際に動かす/テストで担保)。
• どこかで検証が赤くなったら そこで停止(次 wave に進まない)。当該 wave を切り分け、原因 task を特定して報告。
• 最後に集計レポート: 実装済/失敗/保留の task、追加/変更ファイル、各コミットハッシュ、未実装の残作業、 フォローアップ(later 等)。必要なら README / ドキュメントの更新も行う(機能を足したら使い方も足す)。

原則（なぜそうするか）

• 全体を理解してから着手する(最重要): 1ファイルだけ見て書き始めない。新機能が乗る道筋・配線・規約を端から端まで 把握し、「どこを変えるか」を漏れなく特定してから実装に入る。理解不足のまま書くと配線漏れ・規約違反・手戻りを生む。
• 設計を先にする: 書き始める前に契約(型/IF/フロー/配置)を固める。手戻りの最大要因は設計の後付け。
• 既存に馴染ませる: 新機能は既存パターンの踏襲が第一。一貫性 > 新規発明。我流の別レイヤを生やさない。
• 衝突をデータで消す: 並列の唯一の危険は同一ファイル同時編集。wave をファイル素集合にすれば worktree もマージも不要。
• 基盤先行・配線は最後: 共有される型/IF は先頭 wave、複数 task が触れる配線ファイルは最終 wave で中央集約。
• テスト同伴: 受け入れ条件をテストに落とし実装と一緒に入れる。重要パスはテスト先行。緑を確認してから次へ。
• YAGNI: 今の要件に要らない汎用化・拡張点を先回りで足さない。スコープ境界を守る。
• 壊れた状態で先に進まない: 各 wave 後に検証して緑を確認してからコミット・次段へ。赤なら停止して切り分け。

参考ファイル

• references/design.md — 既存パターン調査・配置/レイヤ判断・インターフェース設計・影響範囲洗い出しの手順。Phase 1 で読む。
• references/planning.md — 実装タスク分割、wave 化(ファイル集合・依存順・基盤先行・配線集約)、テスト計画。Phase 2 で読む。
• references/workflow-template.md — Workflow スクリプト雛形(wave barrier・実装プロンプト・RESULT スキーマ)。Phase 3 で読む。
• references/verify.md — 言語別の検証コマンドと成功条件(ビルド/型/リンタ/テスト/起動スモーク)。Phase 0/各 wave 後で読む。