TL;DR
- 人間が「審判（Approve）」、AI が「選手（Execution）」を担当する分離モデル
implementation_plan.mdによる事前合意なしに AI はコードを書かない- すべての変更はボトムアップ（Issue → Plan → PR）で管理される
ワークフローの 5 ステップ
- Input (Issue): 記事作成依頼 Issue を作成し、DoD（完了定義）を明記します。
- Planning: AI エージェントが依頼を分析し、修正内容をまとめた
implementation_plan.mdを作成。 - Approval: 人間がプランを読み、問題なければコメント欄で承認（または修正指示）を行います。
- Execution: エージェントが記事を執筆し、自動的に Pull Request を作成。
- Review & Merge: 人間が最終的な PR を確認し、マージボタンを押します。
ステータス遷移図
mermaid
graph LR
A[Issue] --> B[Planning]
B --> C{Human Review}
C -->|Approved| D[Execution]
C -->|Feedback| B
D --> E[Pull Request]
E --> F[Human Merge]
2 つの「安全弁（Safety Gates）」
私たちは AI の暴走を防ぎ、品質を維持するために 2 つのゲートを設けています。
- Plan Gate: プランの承認なしに、エージェントは 1 行のコードも書きません。変更の「理由」と「範囲」を事前に握ることが、不必要な修正を防ぎます。
- Merge Gate: エージェントは PR を自らマージすることはできません。最終的なデプロイ権限は常に人間にあります。
依頼のコツ：DoD を明確にする
Article Request (Auto) テンプレートを使用する際は、Acceptance Criteria セクションを具体的に書くのがポイントです。
markdown
- [ ] SDD の概念図を Mermaid で含めること
- [ ] 内部リンクを 4 つ以上設定すること
- [ ] TL;DR セクションを文頭に追加すること
承認ゲートの具体例：Plan Gate でのやりとり
抽象論ではなく、実際の Plan Gate がどう機能するかを 1 ケースで示します。
依頼 Issue:
markdown
## Article Request
- Title: "SDD 入門"
- Acceptance Criteria
- [ ] Mermaid 概念図を 1 つ含める
- [ ] 内部リンクを 4 つ以上
- [ ] TL;DR を文頭に
エージェントが提出した implementation_plan.md（抜粋）:
markdown
## Plan
1. TL;DR を 3 行で作成
2. 「なぜ仕様書か」→「3層管理」→「落とし穴」の構成で本文
3. Mermaid で Issue→Plan→PR の遷移図
4. 内部リンク: sdd-hub / managing-spec-files / human-in-the-loop-workflow / spec-driven-dev-pitfalls
人間のレビュー判断は次の 2 パターンに分岐します。
- Approved: コメントに
LGTM. Execute.と記載 → エージェントが Execution に進み PR を自動作成。 - Feedback: 「内部リンクが 3 本。受入基準は 4 本以上なので 1 本追加してから着手」→ プランが差し戻され、エージェントは修正版プランを再提出。コードはまだ 1 行も書かれていない点が重要です。
この「実装前に範囲を握る」往復があるため、手戻りが Execution 後ではなく Plan 段階で吸収されます。
参考・一次資料
承認ゲート付きワークフローは GitHub の Issue / PR / Actions の標準機能で組めます。一次情報で運用前提を確認してください。
- GitHub Docs: About pull request reviews — Approve/Request changes のレビュー仕様
- GitHub Docs: Required reviews（branch protection） — Merge Gate を強制する設定
- GitHub Actions: Events that trigger workflows — Execution 自動化のトリガー設計
