ADR-0029: Spec Pipeline B1-B6 / Impl Pipeline C1-C6 詳細ワークフローの正式採用

• Status: Accepted
• Mode: Critical
• Kruchten Type: Property/Executive
• Scope: platform
• Implementation Status: In Progress (Step 7 進行中、PR #661 〜 #668)
• 起案者: [email protected]
• 起案日時 (JST): 2026-05-13 16:46
• 承認日時 (JST): 2026-05-13 17:30
• Deciders: [email protected] (単独)

Kruchten Type は ADR-0031 (2026-05-13) で遡及追加。分類根拠は ADR-0031 §決定セクションおよび docs/adr/README.md の Kruchten 3 分類ガイドを参照。 Status / Mode / Scope は 2026-06-11 に遡及追加 (ADR-0031 corrigendum パターン)。出典: Status = 旧形式「## ステータス」節の機械転記 / Mode = 旧 README §既存 ADR 一覧の推定値 (git 履歴) / Scope = ADR-0049 4 層分類の遡及付与 (PR レビューで確定)。

コンテキスト

1.1 背景 (Background)

ADR-0028 で全体 6 段フレームワークを採用した際、段 4 (Spec Pipeline) と段 5 (Impl Pipeline) の内部ワークフローは「詳細は ADR-0029 で規定」として委譲された。本 ADR はその委譲分を確定させるために起案する。

1.2 現状 (Current State / As-Is)

Spec Pipeline / Impl Pipeline は ADR-0028 で外形のみ採用され、内部の段構成・担当ツール・完了条件は明文化されていない。既存スクリプトは scripts/1_generate_prompts_gemini.js / scripts/2_run_writers.sh / scripts/4_review_specs_by_gemini.js が存在し、Walking Skeleton 4 要素 (認証 / DDL / 監査ログ / Feature Flag) は ADR-0021 で定義済、slice_id は ADR-0025、自動同期は ADR-0026、計測基盤は ADR-0027 で整備済である。

訂正 (Corrigendum 2026-05-13): 「Walking Skeleton 4 要素 (認証 / DDL / 監査ログ / Feature Flag) は ADR-0021 で定義済」は誤参照。正しくは ADR-0028 §採用方針 line 73 が初定義 (4 要素を束ねて「Customer Validation 合否基準ではなく横断的先行実装制約」と位置づけたのは ADR-0028)。ADR-0021 §3 DoD line 192 では「監査ログ + 認証 + DDL 整合性」の 3 アサーションまで定義、Feature Flag は §2.1 line 104 で「共通技術運用」として並列言及されているのみで未束ね状態であった。本訂正は本文の事実誤認に対する corrigendum (注記行追加、本文改変なし) で、イミュータブル原則を尊重しつつ事実を訂正する学術論文 errata 方式に準拠。詳細経緯は memory project_walking_skeleton_4_elements.md 参照。

2026-06-20 corrigendum (ADR-0152 umbrella 化 + ADR-0161 受理): 本 ADR が定義する Spec Pipeline (B1-B6) / Impl Pipeline (C1-C6) は ADR-0028 6 段ワークフローの Stage 4-5 内部詳細を規定する。ADR-0152 (Accepted 2026-06-15) で ADR-0028 が umbrella 化され、ADR-0161 (Accepted 2026-06-20 PR #2343 / MAS GAS-MVP Build / Verify ライフサイクル) が Stage 5-6 全体を引き継いだ後も、本 ADR の B1-B6 / C1-C6 内部詳細は不変。同期義務 (盲点 #1 対応): ADR-0161 は §1.4 入力契約として本 ADR の Stage 4 (Spec Pipeline) 出力スキーマを参照するため、Stage 4 出力スキーマを本 ADR で変更する場合は ADR-0161 §1.4 を同期更新する義務を本注記で宣言する。本訂正は注記行追加のみで本文改変なし (ADR-0031 corrigendum パターン)。

2026-06-22 corrigendum (refines 張替・ADR-0152 KPI 3): frontmatter refines を ADR-0028 (umbrella) から ADR-0161 (MAS GAS-MVP Build/Verify Stage 5-6) に張り替え。Spec/Impl Pipeline は Stage 4-5 内部詳細を担うため MAS 検証ライフサイクル寄りに再配置。ADR-0028 は本日 PR #2514 で umbrella 化済 (本文編集は adr-lint --check-umbrella-readonly で拒否) のため、ADR-0028 側 refined_by からの相互削除を本同 PR で完了。本訂正は frontmatter 1 行張替 + 注記追加のみで本文改変なし (ADR-0031 corrigendum パターン)。

1.3 課題 (Problem)

委譲状態のまま放置すると以下の具体的痛みが発生する:

• scripts/1/2/4 と新規 scripts/2.5 の使用順序・完了条件が口頭運用になる
• Walking Skeleton 4 要素 (認証 / DDL / 監査ログ / Feature Flag) の貫通検証タイミングが人によって異なる
• C4 (Codex CLI MCP による命名規約チェック) や C6 (Gemini MCP 監査 QA) といった独立レビューが属人的判断で省略される

1.4 制約・要件 (Constraints & Requirements)

• ADR-0001〜0028 の本文は不変 (イミュータブル原則)
• scripts/2_run_writers.sh / scripts/5_generate_rq_prompt.js のシェルロジックは改変しない
• 新規スクリプトは scripts/2.5_inject_walking_skeleton.js のみ (Node、LLM 呼出なし、テンプレ挿入)
• ADR-0021 (Walking Skeleton 4 要素) / ADR-0025 (slice_id) / ADR-0026 (自動同期) / ADR-0027 (計測基盤) / ADR-0028 (6 段フレームワーク) との整合性必須
• 既存 testT{N}_* 命名のリネームは禁止 (新規分のみ移行)

1.5 目標 (Goals / To-Be)

Spec Pipeline 内部を B1-B6、Impl Pipeline 内部を C1-C6 として各段の担当ツール・完了条件を明文化し、Jr 入社後に各段の作業を自己確認できる状態にする。Non-Goals: Codex CLI / Gemini MCP の障害時フォールバック詳細、既存 testT{N}_* テストの一括リネーム、Decision Pipeline 各段の Gate 自動チェック実装。

決定

Spec Pipeline 内部を B1-B6、Impl Pipeline 内部を C1-C6 として正式採用する。各段の担当ツール・完了条件を以下のマトリクスで規定し、Walking Skeleton 4 要素 (ADR-0021) / slice_id (ADR-0025) / 自動同期 (ADR-0026) / 計測基盤 (ADR-0027) を各段に組み込む。新規スクリプトは scripts/2.5_inject_walking_skeleton.js のみとし、既存 scripts/1/2/4 はプロンプト追記ベースで改修する。

Spec Pipeline 内部 6 段 (B1-B6)

Impl Pipeline 内部 6 段 (C1-C6)

判断基準

1. 属人化リスク低減 (最重要) — Jr 入社後に各段の担当ツール・完了条件を自己確認できる
2. 既存スクリプト資産の活用 (高) — scripts/1/2/4 は改修ベース、新規は scripts/2.5 のみ
3. ADR-0021〜0028 との整合性 (高) — Walking Skeleton 4 要素 (ADR-0021) / slice_id (ADR-0025) / 自動同期 (ADR-0026) / 計測基盤 (ADR-0027) を各段に組み込む

影響範囲

ADR-0029 Accepted 後に sub workspace の通常 PR で実装

• scripts/2.5_inject_walking_skeleton.js: 新規 (Node、LLM 呼出なし、Walking Skeleton 4 要素のテンプレ挿入)
• scripts/1_generate_prompts_gemini.js: 「Walking Skeleton 4 要素を Step 2-3a で必ず列挙」「test_{slice_id}_{condition} 命名を Step 3 で必須」をプロンプトに追加
• scripts/4_review_specs_by_gemini.js: レビュー観点に「Walking Skeleton 4 要素」「Feature Flag rollback 計画」「6 分制限の見積もり」追加
• docs/_internal/trunk_based_workflow.md: 新規 (短命ブランチ ≤ 2 日 / 1 PR = 1 UC スライス / slice_id PR 必須欄)
• docs/_internal/failure_patterns.md: #28 (監査ログ書込握りつぶし検知不能) / #29 (Feature Flag 9KB 制限超過) / #30 (6 分制限を貫通する UC スライス粒度) 追加
• docs/internal/dev_spec_prompt_template.md: v1.10「Walking Skeleton 4 要素」+ test{slice_id}_{condition} 命名規約 + 変更履歴追記
• docs/_config.json: trunk_based_workflow.md の nav 登録

ADR-0029 範囲外 (main workspace で別 PR)

• usecase_dev_mapping.md / todo_master_tables.md に 3 列 (slice_id / walking_skeleton_status / now_next_later) 追加
• 900_test/901_test_runner.js: 新規分のみ test_{slice_id}{condition}() 命名移行

MCP 障害時の暫定フォールバック (即時運用、フォールバック詳細 ADR は将来規定)

• C1 (Codex CLI MCP + Gemini MCP) 障害時: 代表取締役本人が git grep / find で類似関数を手動サーベイし PR 説明欄に列挙、fallback-c1-manual ラベルを付与
• C4 (Codex CLI MCP) 障害時: scripts/adr-lint.mjs + 手動 grep (APL_xxx / 列ヘッダー名違反 / add_rows 使用) で代替、fallback-c4-manual ラベル付与
• C6 (Gemini MCP) 障害時: 6 項目チェックリストを PR 説明欄に手動記入して self-attestation、fallback-c6-manual ラベル付与
• 上記いずれの fallback-*-manual ラベル付き PR が月 3 件超になった場合は MCP フォールバック詳細 ADR を即時起案

不変対象

• ADR-0001〜0028 の本文 (イミュータブル原則)
• scripts/2_run_writers.sh / scripts/5_generate_rq_prompt.js のシェルロジック

コスト試算

機会費用換算: 8.25 時間 × Jr エンジニア想定時給 [MASKED:AMOUNT]/h = [MASKED:AMOUNT] 相当。ただし Jr 入社前の代表取締役 1 人作業のため実支出ゼロ。LLM API 実費 $8-13 (≒ [MASKED:AMOUNT]-2,000) のみ。

完了条件 (定量メトリクス)

1. ADR-0029 Accepted 化: grep -E "^\- \*\*Status\*\*: Accepted" docs/adr/0029-*.md → exit 0
2. scripts/2.5_inject_walking_skeleton.js 存在: test -f scripts/2.5_inject_walking_skeleton.js → exit 0
3. scripts/2.5 が Walking Skeleton 4 要素を出力: node scripts/2.5_inject_walking_skeleton.js --dry-run | grep -cE "(認証|DDL|監査ログ|Feature Flag)" → 4
4. scripts/1 にプロンプト追記済: grep -c "Walking Skeleton 4 要素" scripts/1_generate_prompts_gemini.js → >= 1
5. scripts/1 に命名規約追記済: grep -c "test_{slice_id}_{condition}" scripts/1_generate_prompts_gemini.js → >= 1
6. scripts/4 にレビュー 3 観点追加済: grep -cE "(Walking Skeleton 4 要素|Feature Flag rollback|6 分制限)" scripts/4_review_specs_by_gemini.js → >= 3
7. trunk_based_workflow.md 存在: test -f docs/_internal/trunk_based_workflow.md → exit 0
8. failure_patterns.md に #28-#30 追加済: grep -cE "^### #(28|29|30) " docs/_internal/failure_patterns.md → 3
9. dev_spec_prompt_template.md v1.10 化: grep -c "v1.10" docs/_internal/dev_spec_prompt_template.md → >= 1
10. docs/_config.json に trunk_based_workflow 登録済: grep -c "trunk_based_workflow" docs/_config.json → >= 1
11. CI markdown-link-check PASS: gh pr checks <実装 PR> → SUCCESS
12. 既存 ADR への遡及改変なし: git diff main..HEAD -- 'docs/adr/00[0-2][0-9]-*' → 0 byte
13. Jr 受け入れ前提: 入社 1 ヶ月前 (2026-09 末) までに 12 段チートシート整備済 — test -f docs/_internal/uc_slice_workflow_cheatsheet.md && grep -cE "^### (B[1-6]|C[1-6])\b" docs/_internal/uc_slice_workflow_cheatsheet.md → 12 (B1-B6 / C1-C6 各段が見出しとして網羅)

検討した代替案 (Alternatives Considered)

• 案 A【採用】B1-B6 と C1-C6 を ADR-0029 として一括採用: B6 ↔ C1 の引き継ぎ点が同一 ADR 内で明示され境界が明確。Spec と Impl を独立採用すると「Spec だけ先行して Impl が未定義」の期間が生まれる。— トレードオフ: ADR が Standard サイズの上限に近い。
• 案 B【不採用】B1-B6 のみ ADR-0029、C1-C6 は後日 ADR-0030: 各 ADR がより小さく焦点が絞れる。— 不採用理由: Impl Pipeline (C1-C6) は Walking Skeleton 第 1 号 (UC-4-S01) で即使うため後日 ADR が間に合わない。B6 (整合性チェック) と C1 (既存実装サーベイ) の引き継ぎが ADR をまたいで曖昧になる。
• 案 C【不採用】ADR-0028 に B1-B6 / C1-C6 を含めて一本化: Pipeline 投入が 1 回で済む。— 不採用理由: ADR が Critical サイズ (200-400 行) になり全体フレームワークと内部詳細が結合する。将来どちらか一方だけ改訂する際に全体 ADR を Supersede する必要が生じる。

影響 (Consequences)

5.1 正の影響 (Good)

• Spec Pipeline / Impl Pipeline の各段の担当ツール・完了条件がマトリクス化され、Jr 入社後の属人化リスクが大幅に低減する
• Walking Skeleton 4 要素 (認証 / DDL / 監査ログ / Feature Flag) の貫通検証タイミングが B3 / C6 で明示され、人によるばらつきが消える
• C4 (Codex CLI MCP) / C6 (Gemini MCP) の独立レビューが完了条件として明文化され、属人的省略が防げる
• ADR-0021/0025/0026/0027/0028 の既存基盤を各段に組み込むことで、既存資産の活用度が最大化される
• scripts/2.5_inject_walking_skeleton.js は LLM 呼出なしのテンプレ挿入のため、API コストゼロで Walking Skeleton 4 要素を強制できる

5.2 負の影響 (Bad)

• B1 / C1-C2 は人間判断段として残り、LLM 自動化を捨てた (UC スライス選定・既存実装サーベイ・設計判断)
• 既存 testT{N}_* と新規 test_{slice_id}_{condition}_ の二重メンテが新規分移行期間中 (半年以上想定) 継続する
• Codex CLI / Gemini MCP の障害時フォールバックは本 ADR では未定義 (将来 ADR で対応)
• B1-B6 / C1-C6 = 12 段の暗記がオンボーディング負担となり、簡易チートシート整備が別途必要になる
• Critical Mode の工数上限 (約 8.25 時間) に達しており、追加改訂の余地が小さい

5.3 中立・トレードオフ (Neutral / Trade-offs)

運用上の罠 (Operational Pitfalls)

長期的影響 (6 ヶ月後の負債化リスク)

1. ワークフロー肥大化: B1-B6 / C1-C6 のいずれかに「形式的にスキップされるが ADR 上は残る」段が発生 → 縮退 ADR が必須化
2. Codex MCP / Gemini MCP 依存度の上昇: C1 / C4 / C6 が外部 MCP に依存しすぎてベンダー仕様変更時のフォールバック未定義リスクが顕在化 → フォールバック ADR 起案が必要
3. Jr 学習コストの固定化: 6 段 + 6 段 = 12 段の暗記がオンボーディング負担になり「最低限の経路だけ覚える」運用に分裂 → 簡易チートシート + ハッピーパス図の整備が必須
4. 命名規約混在の長期化: 既存 testT{N}_* と新規 test_{slice_id}_{condition}_ の二重メンテが半年以上続く → 段階移行完了 ADR を起案
5. C5 計測データの腐敗: ADR-0027 _RUNTIME_METRICS シートが UC スライス削除と非同期で残骸データを抱える → クリーンアップ運用 ADR が必要

観測指標 (月次 Health Metrics)

撤退条件 (Rollback Plan)

Review After (定期見直し計画)

各タイミングで Review After 結果を docs/_internal/changelog.md に追記する。指標が閾値超過した場合は ADR-0029 を Supersede した縮退版 ADR を起案する。

Confirmation (準拠確認 / Fitness Function)

本セクションは ADR-0036 (Accepted 2026-05-14) で遡及追加された。ADR-0031 パターン (業界標準準拠メタデータ後付け = 誤字修正範疇) に準拠する遡及で本文の意思決定内容は不変。

• 検証手段: Pipeline Gate 2 (consistency) + LiteLLM ログ集計
• 実行頻度: PR ごと
• 違反時の対応: 自動 fail

参照 (References)

• 関連 ADR:
  • ADR-0021 (Walking Skeleton 4 要素: 認証 / DDL / 監査ログ / Feature Flag) — 準拠
  • ADR-0025 (slice_id) — 準拠
  • ADR-0026 (自動同期ワークフロー) — 準拠
  • ADR-0027 (計測基盤 Utils.measureRuntime_ / _RUNTIME_METRICS) — 準拠
  • ADR-0028 (全体 6 段フレームワーク) — 本 ADR は段 4 / 段 5 の内部詳細を規定
  • ADR-0001〜0028 — 不変対象 (イミュータブル原則)
• 関連 PR/Issue: （要追記）
• 外部資料: （要追記）