English summary: A reusable
.github/framework that powers an 11-agent AI development workflow using GitHub Copilot CLI. Enforces a V-model process — requirements development and acceptance validation are first-class concerns, not afterthoughts. Agents collaborate through a shared Board, enabling parallel execution of read-only agents and enforcing context isolation between implementers, test designers, and verifiers. Drop-in ready — copy.github/to your project and runinitialize-project.
GitHub Copilot CLI でマルチエージェント開発ワークフローを実現する .github 構成フレームワーク。
11 体のエージェントが Board を介して協調し、要求開発 → 要求分析 → 設計 → 実装 → テスト設計 → 独立検証（Verification） → 妥当性確認（Validation） → レビュー → ドキュメント → PR の一連のフローを自動化します。V字モデルに基づく品質保証とコンテキスト分離が特徴です。
本フレームワークは V字モデル（V-model）の考え方を採用しています。
要求開発 ────────────────────────── 妥当性確認（Validation）
要求分析 ────────────────── 設計整合性チェック
テスト設計 ────────── テスト検証（Verification）
実 装
- 左辺（開発プロセス）: 要求開発 → 要求分析 → テスト設計 → 実装
- 右辺（検証プロセス）: テスト検証（Verification）→ 妥当性確認（Validation）
| Verification（検証） | Validation（妥当性確認） | |
|---|---|---|
| 問い | 正しく作っているか？ | 正しいものを作っているか？ |
| 対象 | 仕様・テスト・形式的期待への適合 | 目的・要求・運用文脈への適合 |
| 完了条件 | テスト全 pass、ビルド成功 | 受け入れ基準（AC）全充足 |
| 担当 | test-verifier（Phase 7） | test-verifier（Phase 8） |
核心原則: テスト pass ≠ 要求充足。テストが全て通っても、受け入れ基準の半分しかカバーしていないかもしれない。
ユーザーの曖昧な「要望」を、検証可能な「要求」に変換するプロセス（requirements-engineer）を開発フローの起点に据えています。
- 目的の再構成: 表面的依頼の背後にある本来目的を引き出す
- 仮定の明示: 暗黙の前提を仮定として識別し、事実と区別する
- 反例の検討: 要求が不適切となるシナリオを事前に検討する
- スコープ定義: スコープ内/外/将来対応を明確に分離する
.github/ は Instructions・Rules・Skills・Agents・Docs の 5 層 + Board（ランタイム） で構成されています。
| 層 | 適用方式 | 役割 |
|---|---|---|
| Instructions | ファイルパターンで自動適用 | 言語別・テスト用のコーディングガイドライン |
| Rules | 各エージェントが view で手動参照 |
ブランチ命名・コミット形式・ワークフロー規則 |
| Skills | タスクに応じて自動ロード（16 個） | ワークフロー手順の定義（Issue 作成、PR 提出 等） |
| Agents | task ツールで呼び出し（11 体） |
専門的な役割を持つカスタムエージェント |
| Docs | フレームワーク同梱ドキュメント | 設計思想・ADR テンプレート（他プロジェクトへ移植可能） |
| Board | ランタイム（.copilot/boards/） |
Feature 単位の状態管理・エージェント間連携の媒体 |
.github/
├── copilot-instructions.md # トップレベル Copilot 設定
├── settings.json # プロジェクト固有設定
├── settings.schema.json # settings.json のスキーマ
├── board.schema.json # Board JSON スキーマ（コア構造）
├── board-artifacts.schema.json # Board artifact 定義（成果物スキーマ）
├── gate-profiles.schema.json # Gate Profile スキーマ
│
├── agents/ # カスタムエージェント（11 体）
│ ├── analyst.agent.md # 要求分析・受け入れ基準策定
│ ├── architect.agent.md # 構造設計・設計判断
│ ├── assessor.agent.md # プロジェクト全体評価
│ ├── developer.agent.md # 実装・デバッグ
│ ├── impact-analyst.agent.md # 影響分析・依存グラフ・リスク評価
│ ├── planner.agent.md # タスク分解・計画策定
│ ├── requirements-engineer.agent.md # 要求開発・対話的要求引き出し
│ ├── reviewer.agent.md # コードレビュー・品質・セキュリティ検証
│ ├── test-designer.agent.md # テストケース設計
│ ├── test-verifier.agent.md # テスト検証・品質判定
│ └── writer.agent.md # ドキュメント・リリース管理
│
├── instructions/ # ファイルパターン別ガイドライン（自動適用）
│ ├── common.instructions.md
│ ├── javascript.instructions.md
│ ├── typescript.instructions.md
│ ├── python.instructions.md
│ ├── test.instructions.md
│ ├── verification.instructions.md # Verification（検証）ルール
│ └── validation.instructions.md # Validation（妥当性確認）ルール
│
├── rules/ # 開発ルール（手動参照）
│ ├── development-workflow.md
│ ├── workflow-state.md
│ ├── gate-profiles.json
│ ├── branch-naming.md
│ ├── commit-message.md
│ ├── merge-policy.md
│ ├── worktree-layout.md
│ ├── issue-tracker-workflow.md
│ ├── error-handling.md
│ ├── adr-management.md # ADR テンプレート・ステータス管理・不変原則
│ ├── protected-files.md # 保護ファイル一覧・変更手順
│ ├── verification-procedures.md # Verification 詳細手順リファレンス
│ └── validation-procedures.md # Validation 詳細手順リファレンス
│
├── skills/ # ワークフロースキル（16 個）
│ ├── analyze-and-plan/
│ ├── assess-project/
│ ├── cleanup-worktree/
│ ├── configure-model/
│ ├── develop-requirements/
│ ├── execute-plan/
│ ├── generate-gitignore/
│ ├── initialize-project/
│ ├── manage-board/
│ ├── merge-nested-branch/
│ ├── orchestrate-workflow/
│ ├── requirements-to-merge/
│ ├── resolve-conflict/
│ ├── review-code/
│ ├── start-feature/
│ └── submit-pull-request/
│
├── docs/ # フレームワーク同梱ドキュメント
│ ├── design-philosophy.md # 設計思想（Pace Layering, NFR as Structure）
│ └── adr-template.md # ADR 標準テンプレート
│
└── workflows/
└── ci.yml # CI ワークフロー
docs/
├── quickstart.md # クイックスタートガイド
└── architecture/ # 構造ドキュメント（architect/writer が維持）
├── module-map.md # ディレクトリごとの責務・層の対応・依存方向
├── data-flow.md # 主要データの流れ・Source of Truth
├── glossary.md # ドメイン固有の用語定義
└── adr/ # 設計判断記録（ADR-000-template, ADR-001, ...）
tools/
├── skill-creator/ # スキル作成ガイド
├── validate-architecture/ # 構造テスト（ポインタ腐敗検出・サイズガード）
├── validate-commit-msg.py # コミットメッセージ検証
├── validate-framework/ # フレームワーク全体検証
├── validate-github-config/ # .github 設定のバリデーション
└── validate-schemas/ # スキーマ整合性バリデーション
pyproject.toml # Python lint/format 設定（Ruff）
.editorconfig # エディタ共通設定
.markdownlint-cli2.jsonc # Markdown lint 設定
lefthook.yml # プリコミットフック設定（Lefthook）
トップレベルの Copilot CLI がオーケストレーターとして機能し、Board を管理しながら task ツールで各エージェントを呼び出します。
| エージェント | 役割 | 並列安全 | 備考 |
|---|---|---|---|
requirements-engineer |
要求開発・対話的要求引き出し | — | 対話型。analyst の前工程として機能 |
analyst |
要求分析・受け入れ基準策定 | ✅ | 読み取り専用。impact-analyst と並列実行可能 |
impact-analyst |
影響分析・依存グラフ・リスク評価 | ✅ | 読み取り専用。analyst と並列実行可能 |
architect |
構造設計・設計判断 | — | エスカレーション時のみ呼び出し |
planner |
タスク分解・計画策定 | — | analyst + impact-analyst の結果を入力として受け取る |
developer |
実装・デバッグ | — | 書き込み系。test-designer と並列実行可能 |
test-designer |
テストケース設計 | ✅ | 読み取り専用。要求ベースで設計（実装に依存しない） |
test-verifier |
テスト検証（Verification）・妥当性確認（Validation） | ✅ | 実装者と独立した立場で V&V を実施 |
reviewer |
コードレビュー・品質・セキュリティ検証 | ✅ | セキュリティ観点を常時チェック |
writer |
ドキュメント・リリース管理 | — | 技術文書・リリースノート・バージョニング |
assessor |
プロジェクト全体評価 | — | 移植直後の包括評価。コード変更は行わない |
並列安全（✅）: 読み取り専用のためファイル競合なく同時実行可能。CLI の
taskツールで並列呼び出しできます。
スキルはワークフローの手順を定義するもので、ユーザーの指示やコンテキストに応じて自動的にロードされます。
| スキル | 用途 |
|---|---|
start-feature |
Issue 作成・ブランチ・worktree 準備で新規作業を開始 |
develop-requirements |
requirements-engineer を単独で呼び出し、要求開発を実行 |
analyze-and-plan |
要求分析（analyst）・影響分析（impact-analyst）・計画策定（planner）を連携実行 |
orchestrate-workflow |
Feature 開発フロー全体のオーケストレーション手順 |
execute-plan |
plan.md のタスク一覧を依存関係に基づき並列実行 |
requirements-to-merge |
要求開発→計画→実装→検証→妥当性確認→PR の6フェーズ一括フロー |
manage-board |
Board の CRUD・状態遷移・Gate 評価・アーカイブ |
review-code |
コードレビュー実行・修正委任 |
submit-pull-request |
変更のコミット・PR 作成・マージ |
cleanup-worktree |
マージ後の worktree・ブランチ・Issue 整理 |
assess-project |
プロジェクト全体の包括的評価 |
configure-model |
エージェントの LLM モデル変更 |
initialize-project |
新規プロジェクトの .github/ 初期設定 |
generate-gitignore |
gitignore.io API を使った .gitignore 生成 |
resolve-conflict |
PR マージ時のコンフリクト解消 |
merge-nested-branch |
入れ子ブランチ構造の順序マージ（サブ → 親 → main） |
orchestrate-workflow スキルが定義する 12 フェーズの開発フローです。Phase 7（Verification）と Phase 8（Validation）で V字モデルに基づく品質保証を実施します。
flowchart TD
P1["Phase 1: start-feature<br/>Issue 作成 → ブランチ → worktree 準備"]
P2["Phase 2: requirements-engineer<br/>要求開発・対話的引き出し"]
P3A["analyst<br/>要求分析・受け入れ基準"]
P3B["impact-analyst<br/>影響分析・リスク評価"]
P4["Phase 4: architect<br/>構造変更エスカレーション<br/>（必要時のみ）"]
P5["Phase 5: planner<br/>タスク分解・実行計画"]
P6A["developer<br/>実装・デバッグ"]
P6B["test-designer<br/>テストケース設計<br/>+ 妥当性確認計画"]
P7["Phase 7: test-verifier<br/>独立検証<br/>（実装者 ≠ 検証者）"]
P8["Phase 8: test-verifier<br/>妥当性確認（Validation）<br/>AC 充足判定"]
P9{"Phase 9: reviewer<br/>コードレビュー<br/>セキュリティ検証"}
P10["Phase 10: writer<br/>ドキュメント更新<br/>（必要時のみ）"]
P11["Phase 11: submit-pull-request<br/>PR 作成 → マージ"]
P12["Phase 12: cleanup-worktree<br/>worktree・ブランチ整理"]
P1 --> P2
P2 --> P3A & P3B
P3A & P3B --> P4
P4 --> P5
P5 --> P6A & P6B
P6A & P6B --> P7
P7 --> P8
P8 -->|NG| P6A
P8 -->|OK| P9
P9 -->|NG| P6A
P9 -->|OK| P10
P10 --> P11
P11 --> P12
style P2 fill:#cce5ff,stroke:#0366d6
style P3A fill:#d4edda,stroke:#28a745
style P3B fill:#d4edda,stroke:#28a745
style P6B fill:#d4edda,stroke:#28a745
style P7 fill:#d4edda,stroke:#28a745
style P8 fill:#f8d7da,stroke:#dc3545
style P4 fill:#fff3cd,stroke:#ffc107
style P10 fill:#fff3cd,stroke:#ffc107
🔵 対話型（ユーザーとの対話が必要） 🟢 並列実行可能（読み取り専用） 🟡 必要時のみ呼び出し 🔴 V字モデル対応（AC 充足を判定）
エージェント間の状態共有は Board（.copilot/boards/<feature-id>/board.json）を通じて行われます。
- JSON が永続的正本 — Feature 単位で作成され、状態・成果物・Gate 評価結果を保持
- SQL ミラー — CLI の
sqlツールで Board JSON のセッション内コピーを維持し、高速クエリを実現 - Gate 評価 — フェーズ遷移時に品質基準を自動チェック（
gate-profiles.jsonで定義）
詳細は rules/development-workflow.md および rules/workflow-state.md を参照。
開発フロー（12フェーズ）が「何をするか」を定義し、オーケストレーションが「どう駆動するか」を担う。両者は両輪の関係です。
orchestrate-workflow スキルはオーケストレーターとして以下を管理します:
- Board の読み書き — Feature ごとの状態・成果物・履歴を JSON に永続化
- Flow State の遷移 —
initialized → eliciting → analyzing → ... → completedの状態機械を制御 - Gate 評価 — フェーズ遷移前に品質基準を自動チェック（
gate-profiles.json定義） - エージェント呼び出し —
taskツールで各エージェントを独立コンテキストで起動 - SQL ミラー同期 — Board JSON と同時に SQL テーブルを更新し、高速クエリを維持
flowchart LR
subgraph Orchestrator["オーケストレーター（Copilot CLI）"]
direction TB
SK["orchestrate-workflow<br/>スキル"]
SQL["SQL ミラー<br/>（セッション内クエリ層）"]
SK <-->|同期| SQL
end
subgraph Board["Board（永続的正本）"]
direction TB
FS["flow_state<br/>状態機械"]
ART["artifacts<br/>成果物"]
GT["gates<br/>評価結果"]
HIST["history<br/>変更履歴"]
end
subgraph Agents["専門エージェント（task ツール経由）"]
direction LR
A0["requirements-engineer"]
A1["analyst"]
A2["impact-analyst"]
A3["developer"]
A4["test-designer"]
A5["test-verifier"]
A6["reviewer"]
end
SK <-->|読み書き| Board
SK -->|spawn| Agents
Agents -->|artifacts 書き込み| ART
GT -->|Gate 通過| FS
Feature の Maturity（成熟度）によって Gate の厳格さが変わります。
| Maturity | Gate の厳格さ | 用途 |
|---|---|---|
experimental |
最小限（実装→PR の最短パス） | プロトタイプ・PoC |
development |
標準（分析・実装・テスト・レビュー必須） | 通常の機能開発 |
stable |
厳格（全フェーズ + ドキュメント必須） | 安定版への変更 |
release-ready |
最厳格（外部レビュー・リリースノート必須） | リリース候補 |
Gate 条件の詳細は .github/rules/gate-profiles.json を参照してください。
stateDiagram-v2
[*] --> initialized: start-feature
initialized --> eliciting: requirements_gate
initialized --> analyzing: analysis_gate (skip requirements)
eliciting --> analyzing: analysis_gate
analyzing --> designing: design_gate
analyzing --> planned: plan_gate (skip design)
designing --> planned: plan_gate
planned --> implementing: implementation_gate
implementing --> testing: test_gate
testing --> validating: validation_gate
validating --> reviewing: review_gate
validating --> implementing: not_validated (loop back)
reviewing --> approved: review_approved
reviewing --> implementing: review_rejected (loop back)
approved --> documenting: documentation_gate
approved --> submitting: submit_gate (skip docs)
documenting --> submitting: submit_gate
submitting --> completed: pr_merged
completed --> [*]
決定論的な品質チェックは LLM に任せず、ツールで自動化します。
| ツール | 用途 | 設定ファイル |
|---|---|---|
| Ruff | Python lint + format | pyproject.toml |
| markdownlint-cli2 | Markdown lint | .markdownlint-cli2.jsonc |
| EditorConfig | エディタ共通設定（インデント・改行コード等） | .editorconfig |
| Lefthook | プリコミットフック（Ruff・markdownlint・JSON validation・commit-msg） | lefthook.yml |
| validate-architecture | 構造テスト（ポインタ腐敗検出・ファイルサイズガード・ADR ステータス検証） | tools/validate-architecture/ |
.github/workflows/ci.yml に以下のジョブを追加済み:
| ジョブ | 内容 |
|---|---|
lint-python |
Ruff でコードスタイルとフォーマット検証 |
lint-markdown |
markdownlint-cli2 で Markdown 整合性確認 |
validate-schemas |
JSON スキーマ整合性バリデーション |
validate-config |
GitHub 設定ファイルのバリデーション |
test |
Python ユニットテスト（pytest） |
validate-architecture |
ポインタ腐敗・サイズ超過・ADR ステータス異常を検出 |
# .github/ をプロジェクトにコピー
cp -r path/to/copilot-cli-workflow-framework/.github your-project/.github# プロジェクトディレクトリで Copilot CLI を起動
cd your-project
copilotinitialize-project スキルが対話的に設定をガイドします。手動で settings.json を編集することも可能です。
# 新しい Feature を始める（自然言語で指示）
> ログイン機能を追加したい
# start-feature → analyze-and-plan → orchestrate-workflow が連携して動作| やりたいこと | 指示例 |
|---|---|
| 新機能の開発開始 | ユーザー認証機能を追加して |
| プロジェクト評価 | このプロジェクトの状態を評価して |
| コードレビュー | 変更をレビューして |
| PR 提出 | PR を作成してマージして |
| worktree 整理 | マージ済みの worktree を片付けて |
初めての方へ: 詳細なウォークスルーは docs/quickstart.md を参照してください。
| ツール | 必須度 | 備考 |
|---|---|---|
| Git | 必須 | すべての変更は Git で管理 |
| GitHub | 推奨 | PR・マージ・コードレビューに使用 |
| Issue トラッカー | オプション | Linear / GitHub Issues に対応。settings.json で provider: "none" に設定すると無効化 |
| Lefthook | 推奨 | プリコミットフックで即時フィードバック |
ドキュメントには2種類あります:
| 種別 | 例 | 腐敗リスク |
|---|---|---|
| 実行可能アーティファクト | テスト・スキーマ・リンター | 低い（実行すれば整合性が確認できる） |
| 説明的ドキュメント | docs/architecture/ |
高い（コードと乖離しやすい） |
docs/architecture/ の4ファイルには doc-freshness メタデータブロックが埋め込まれており、
validate_architecture.py が更新日と対応コミットを定期チェックします。
ADR は不変原則により一度承認されると変更不可のため、腐敗に強い構造になっています。
Verification（検証）は「仕様通りに正しく作っているか？」を確認するプロセスです（テスト pass、ビルド成功）。Validation（妥当性確認）は「要求を本当に満たしているか？」を確認するプロセスです（受け入れ基準の充足判定）。テストが全て通っても、受け入れ基準の半分しかカバーしていないケースがあるため、両方が必要です。
CLI の仕様上、rules/ ディレクトリは自動ロードされません。各エージェントの定義ファイル内で必要なルールを view で参照する設計になっています。これは CLI 版の制約ですが、「必要なルールだけを読み込む」ことでコンテキストウィンドウを効率的に使うメリットもあります。
廃止されました。 CLI ではプロンプトファイルが使えないため、すべてのプロンプトを Skills に移行済みです。自然言語で指示すれば、対応するスキルが自動的にロードされます。
Feature 単位の状態管理ファイル（.copilot/boards/<feature-id>/board.json）です。エージェント間で作業状態・成果物・Gate 評価結果を共有するために使われます。JSON が永続的な正本で、セッション中は SQL ミラーで高速にクエリできます。
docs/architecture/ の各ファイルには doc-freshness メタデータが埋め込まれており、
tools/validate-architecture/validate_architecture.py が鮮度を自動チェックします。
ADR は不変原則により腐敗に強い構造です。詳細は ドキュメント鮮度 セクションを参照してください。
.github/ をコピーした後、initialize-project スキルを使って対話的に settings.json を設定してください。その後、assess-project スキルでプロジェクトの現状を評価するのがおすすめです。
MIT