はじめに
前回までの記事で、cc-sddとAgent Teamsの組み合わせ方と、ウォーターフォールの罠を避けるアジャイルSDDの考え方を整理しました。
本記事では、このワークフローをGitHub Issue起点のパイプラインとして具体的に構築する方法を解説します。環境はClaude Code Maxプラン、GitHub Issueによるタスク管理を前提としています。
シリーズ記事:
- 第1回: ツール編 — cc-sdd、takt、Agent Teams、Code Reviewは何が違うのか
- 第2回: 設計編 — 企画書から実装までのワークフローをどう設計するか
- 第3回（本記事）: 実践編 — GitHub Issue起点のアジャイルSDDパイプラインを構築する
全体像
パイプライン全体は、3つのフェーズからなるイテレーティブループです。
┌─────────────────────────────────────────────────┐
│ │
│ Planning ──→ Build ──→ Review & Learn ──→ 次へ │
│ (Agent Teams) (cc-sdd + 実装) (Agent Teams) │
│ │
└─────────────────────────────────────────────────┘
1サイクルで2〜3個のIssueを処理します。企画書全体を最初に分解するのではなく、サイクルごとに次にやるべきIssueだけを決めていきます。
前提環境の準備
cc-sddのインストール
cd your-project
npx cc-sdd@latest --claude --lang ja
Agent Teamsの有効化
~/.claude/settings.json に以下を追加します。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
プロジェクト構造
your-project/
├── .kiro/
│ ├── specs/ # cc-sddが生成する仕様書（機能単位のサブディレクトリ）
│ ├── steering/ # プロジェクト全体の方針（cc-sdd steering）
│ └── settings/ # テンプレートとルール
├── docs/
│ ├── plan.md # 企画書
│ ├── architecture.md # 共通アーキテクチャ（Phase 1で生成、随時更新）
│ ├── issues.md # 機能一覧（Phase 1で生成）
│ └── adr/ # Architecture Decision Records
│ ├── 0001-auth-jwt.md
│ └── 0002-db-postgresql.md
├── CLAUDE.md # AIへの指示
└── ...
CLAUDE.mdの設定
CLAUDE.mdに以下を追記しておくと、全フェーズでADRとsteeringの活用が自動化されます。
## プロジェクトルール
- 設計判断が発生したら、docs/adr/ にADRファイルを作成すること
- ADRのフォーマット: 状態、背景、検討した選択肢、決定、影響
- 仕様生成時は .kiro/steering/ と docs/architecture.md を必ず参照すること
- 実装時は該当Issueの仕様書（.kiro/specs/{feature}/）に従うこと
Phase 1: Planning（Agent Teamsで実施）
初回サイクル: 企画書からの起動
企画書 docs/plan.md を用意した状態で、Claude Codeで以下のプロンプトを実行します。
企画書 docs/plan.md を読み、以下の3人のチームで分析してください。
## チーム構成
- Architect: 共通基盤の抽出を担当。データモデル、API設計方針、
技術スタック、認証方式、ディレクトリ構造など、全機能が依存する
共通要素を特定し、docs/architecture.md に出力する。
設計判断があれば docs/adr/ にADRも作成すること。
- PM: 機能分割と優先順位付けを担当。企画書を独立した機能単位に
分割し、全体像を docs/issues.md に整理する。
ただし、今回のサイクルで実装するのは最も優先度が高い
2〜3機能のみ。残りは概要レベルで記録するだけでよい。
1機能あたりrequirements 15〜20件以内に収まる粒度を目安とする。
- QA: 分割の検証を担当。ArchitectとPMの成果物に対して、
漏れ・矛盾・粒度の問題を指摘する。
特に「この2〜3機能を先に作ることで、後続機能に悪影響はないか」
を重点的に検証すること。
## 成果物
1. docs/architecture.md - 共通アーキテクチャ定義
2. docs/issues.md - 機能一覧（各機能のタイトル、概要、依存関係、
優先順位。今サイクル対象の2〜3機能は詳細に、残りは概要のみ）
3. docs/adr/ - 技術選定に関する判断記録
4. QAレビュー結果の報告
全員の作業が完了したら、私に報告してください。
issues.md の内容を確認して、承認後にGitHub Issueとして起票します。
2回目以降のサイクル: 学びからの再計画
前サイクルの実装結果を踏まえて、次のサイクルの計画を立ててください。
## 参照すべき情報
- docs/architecture.md（現在のアーキテクチャ）
- docs/issues.md（機能一覧と進捗）
- .kiro/steering/（プロジェクト方針）
- docs/adr/（過去の設計判断）
- 前サイクルのReview & Learnの結果
## チーム構成（初回と同じ3名）
- Architect: architecture.mdの更新が必要か判断し、必要なら更新
- PM: 次に実装すべき2〜3機能を選定。前サイクルの学びを反映
- QA: 選定の妥当性と、既存実装との整合性を検証
## 特に注意すべき点
- 前サイクルで発見された技術的課題への対処が計画に含まれているか
- 新しいIssueの仕様が既存の実装と矛盾しないか
承認とIssue起票
Agent Teamsの成果物を確認し、問題がなければGitHub CLIでIssueを起票します。
# issues.mdの内容を元にIssue起票
gh issue create --title "ユーザー認証機能" \
--body "$(cat docs/issues/auth.md)" \
--label "size:L,priority:high,cycle:1"
ラベルの設計がポイントです。
| ラベル | 用途 |
|---|---|
size:S / size:M / size:L | 実装時のAgent Teams構成を切り替える |
priority:high / priority:medium | 同一サイクル内での実装順序 |
cycle:N | どのサイクルで計画されたIssueか |
architecture.mdからsteeringへの接続
Agent Teamsが生成したarchitecture.mdを、cc-sddのsteeringとして読み込ませるため、steeringコマンドを実行します。
/kiro:steering
これにより、architecture.mdの内容が.kiro/steering/に反映され、後続のcc-sdd実行時に自動的にコンテキストとして使われます。
Phase 2: Build（Issue単位ループ）
Phase 2a: 仕様生成（cc-sdd、単体実行）
起票されたIssueごとに、cc-sddで仕様を生成します。
/kiro:spec-init ユーザー認証機能（JWT + リフレッシュトークン）
続けて、各フェーズを順番に実行し、人間が承認します。
/kiro:spec-requirements user-auth
# → requirements.md を確認・承認
/kiro:spec-design user-auth -y
# → design.md を確認・承認
/kiro:spec-tasks user-auth -y
# → tasks.md を確認・承認（特にタスク順序を注意深く確認）
tasks.mdの順序確認は必ず行ってください。 依存関係が不正確なケースがあるため、「タスクBはタスクAの成果物に依存しているのに、タスクBが先に来ている」といった問題がないかチェックします。
Phase 2b: 実装（Agent Teamsまたは単体）
Issueのサイズラベルに応じて、実装方法を切り替えます。
size:S（バグ修正、小さな機能追加）— 単体実装
/kiro:spec-impl user-auth
cc-sddの通常のTDD実装フローで十分です。
size:M〜L（中〜大規模機能）— Agent Teams実装
.kiro/specs/user-auth/ の仕様書に基づいて実装してください。
## チーム構成
- Implementer: tasks.mdのタスクを順番に実装。
各タスクでファイルを作成・変更したら、Testerに通知すること。
- Tester: Implementerが作成したコードに対してテストを書き、
実行する。テストが失敗したらImplementerにフィードバックする。
テスト戦略は .kiro/steering/ に従うこと。
- Reviewer: ImplementerとTesterの成果物をレビューする。
以下の観点でチェック:
- design.mdとの整合性
- docs/architecture.md に定義された規約への準拠
- セキュリティ上の問題
- パフォーマンス上の懸念
問題があれば該当エージェントにフィードバックすること。
## 完了条件
- 全タスクが実装済み
- 全テストがパス
- Reviewerが承認
ループ処理スクリプトとの統合
既存のGitHub Issue起点のループ処理スクリプトに、以下のロジックを追加します。
#!/bin/bash
# 疑似コード: Issue単位のループ処理
CYCLE_SIZE=3 # 1サイクルあたりのIssue数
COMPLETED=0
# 現在のサイクルのIssueを取得（優先順位順）
ISSUES=$(gh issue list --label "cycle:$(cat .current-cycle)" \
--state open --json number,title,labels \
--jq 'sort_by(.labels[] | select(.name | startswith("priority:")))')
for ISSUE in $ISSUES; do
ISSUE_NUM=$(echo $ISSUE | jq -r '.number')
SIZE=$(echo $ISSUE | jq -r '.labels[] | select(.name | startswith("size:")) | .name')
echo "Processing Issue #$ISSUE_NUM (${SIZE})"
# Phase 2a: 仕様生成（常に単体）
claude --headless "Issue #${ISSUE_NUM} の内容を読み、
/kiro:spec-init で仕様を生成してください"
# Phase 2b: 実装（サイズに応じて切り替え）
if [ "$SIZE" = "size:S" ]; then
claude --headless "/kiro:spec-impl ${FEATURE_NAME}"
else
claude --headless "Agent Teamsで実装してください（Implementer/Tester/Reviewer構成）"
fi
COMPLETED=$((COMPLETED + 1))
# サイクル分のIssueを処理したらReview & Learnへ
if [ $COMPLETED -ge $CYCLE_SIZE ]; then
echo "Cycle complete. Starting Review & Learn..."
# Phase 3へ
break
fi
done
注意: 上記は概念的な疑似コードです。実際にはheadlessモードでのAgent Teams起動方法、承認フローの挟み方、エラーハンドリングなどを環境に合わせて調整する必要があります。
Phase 3: Review & Learn（Agent Teamsで実施）
2〜3 Issueの実装が完了したら、振り返りを行います。
今サイクルで実装した以下のIssueについて、振り返りを行ってください。
## 実装済みIssue
- #12 ユーザー認証機能
- #13 プロフィール管理機能
- #14 ファイルアップロード機能
## チーム構成
- Integration Tester: 上記3機能の結合テストを実施。
特に機能間のデータ受け渡し、認証状態の引き継ぎ、
エラーハンドリングの一貫性を検証すること。
- Consistency Checker: 以下の整合性を検証。
1. 各Issueの仕様書（.kiro/specs/）間の矛盾
2. docs/architecture.md と実装の乖離
3. .kiro/steering/ の方針と実装の乖離
問題があれば、次サイクルで対処すべき項目としてリスト化すること。
## 成果物
1. 結合テスト結果レポート
2. 整合性チェック結果
3. docs/architecture.md の更新（必要な場合）
4. .kiro/steering/ の更新（必要な場合）
5. docs/adr/ への追記（新たな設計判断があった場合）
6. 次サイクルへの引き継ぎ事項（発見された課題、推奨する改善）
validate-gapの活用
cc-sddの検証コマンドも併用します。
/kiro:validate-gap user-auth
/kiro:validate-gap profile-management
/kiro:validate-gap file-upload
乖離が検出された場合は、次サイクルのPlanningで対処方針を決定します。
ADRの蓄積フロー
ADRは各フェーズで自然に蓄積されます。
| タイミング | ADRの内容 |
|---|---|
| Phase 1 Planning | 技術選定（DB、認証方式、フレームワーク等） |
| Phase 2b Build中 | 設計変更（「〇〇を試したがXXの理由でYYに変更」） |
| Phase 3 Review & Learn | 振り返りで得た知見（「この構成だとZZが辛い」） |
半年後の保守時には、AIにsteering + ADR群を読み込ませることで「何がどうなっていて、なぜそうなったか」を把握した状態で作業に入れます。
ハマりどころと対策
実際にこのパイプラインを回す上で、注意すべき点を列挙します。
1. Agent Teamsのセッション管理
Agent Teamsは現在experimental機能であり、セッション再開やネストされたチームには未対応です。Phase 1のAgent Teamsセッションが途中で切れた場合、最初からやり直しになるリスクがあります。
対策: Agent Teamsへの指示は「中間成果物をファイルに書き出す」ことを明示する。こうすれば、セッションが切れても途中のファイルから再開できます。
2. steeringの肥大化
サイクルを重ねるとsteeringの内容が肥大化し、AIのコンテキストウインドウを圧迫します。
対策: Review & Learnフェーズで「steeringの整理」もタスクに含める。古くなった情報を削除し、最新の状態だけを残す。
3. cc-sddのtasks.md信頼性
前述の通り、タスク順序が不正確なケースがあります。
対策: Phase 2aの仕様承認時に、tasks.mdの順序を人間が確認する習慣をつける。特に「このタスクの入力は何か、その入力はどのタスクで作られるか」を確認する。
4. Agent Teamsのトークンコスト
Maxプランではトークンコスト自体は問題になりませんが、Agent Teamsはチームメイトの数に比例してトークンを消費するため、上限に達する速度が上がります。
対策: Phase 2bで全Issueに3名構成のAgent Teamsを使うのではなく、size:Sのissueは単体実装にする。これだけで全体のトークン消費を大幅に抑えられます。
5. 機能間の暗黙的依存
明示的な依存関係はPlanningで整理されますが、暗黙的な依存（共有テーブル、共通コンポーネント、CSS名前空間の衝突等）は見落としやすい。
対策: Phase 3のConsistency Checkerに「暗黙的な依存の検出」を明示的に指示する。「同じテーブルを参照している機能はあるか」「同じファイルを変更している機能はあるか」といった観点でチェックさせる。
まとめ
本記事で構築したパイプラインの全体像を整理します。
企画書
│
▼
┌─────────────────────────────────────────────┐
│ Planning（Agent Teams: Architect/PM/QA） │
│ → architecture.md + 次の2〜3 Issue + ADR │
│ → 人間が承認 → GitHub Issue起票 │
│ → steering更新 │
└──────────────────┬──────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ Build（Issue単位ループ × 2〜3回） │
│ → cc-sdd仕様生成（単体）→ 人間承認 │
│ → 実装（size:S→単体 / size:M〜L→Agent Teams）│
└──────────────────┬──────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ Review & Learn（Agent Teams） │
│ → 結合テスト + 整合性チェック │
│ → validate-gap │
│ → steering/architecture.md/ADR更新 │
│ → 次サイクルへの引き継ぎ事項 │
└──────────────────┬──────────────────────────┘
│
▼ 次のサイクルへ
このパイプラインのポイントは3つです。
- 最初に全部決めない: 2〜3 Issueずつ探索的に進める
- 学びをフィードバックする: Review & Learnの結果が次のPlanningに反映される
- 人間は「分割」「承認」「方向転換」に集中する: 仕様生成・実装・レビュー・検証はAIが担当
AI駆動開発のツール群は急速に進化しています。Agent Teamsが正式版になれば制約も緩和されるでしょうし、cc-sddも機能間の整合性チェック機能が追加されるかもしれません。しかし、「小さく回して学びを反映する」というアジャイルSDDの基本思想は、ツールが変わっても有効であり続けるはずです。
シリーズ記事:
- 第1回: ツール編 — cc-sdd、takt、Agent Teams、Code Reviewは何が違うのか
- 第2回: 設計編 — 企画書から実装までのワークフローをどう設計するか
- 第3回（本記事）: 実践編 — GitHub Issue起点のアジャイルSDDパイプラインを構築する