経費精算 SaaS（expense-saas）の開発で実践した、Claude Code（AI コーディングエージェント）を 役割別エージェント × ワークフロー × テンプレート で統制するための内部運用フレームワーク。
AI コーディングエージェントに「設計判断・実装・テスト・レビュー」をやらせるとき、何の指示もなしに使うと出力品質がブレる。本フレームワークは以下を組み合わせて、AI 出力を計画駆動型プロセスに乗せる仕組みを提供する。
- 役割別エージェント: 1 タスクに 1 エージェント、責務を分けて並列起動
- ワークフロー: 設計成果物フロー / PR フローの 2 種を指揮役が選択
- テンプレート: ADR / issue / ticket / work-breakdown 等の成果物形式を統一
- レビュー手順書: 内部レビュー（reviewer）と外部レビュー（codex）の手順を明文化
適用事例として、要件定義 → 設計 → 実装 → テスト → デプロイ → UAT までを完走した。
本リポジトリは ルール・手順書・テンプレートの正本 を集約する。Claude Code が直接読み込む実行要素（エージェント定義 / スキル / hooks）は、Claude Code の規約に従って root-project/.claude/ 配下（agents/ / skills/ / hooks/）に配置されている。
| ディレクトリ | 役割 |
|---|---|
agents/ |
レビュー手順書（issue-review / pr-review / review / ticket-review） |
guide/ |
指揮役のワークフロー（workflow.md）+ Step 別の作業分解（work-breakdown/） |
operations/ |
運用設計（ブランチ戦略 / hooks / サブエージェント設計） |
templates/ |
各種テンプレート（ADR / issue / ticket / work-breakdown / README / task / review-finding） |
Claude Code のサブエージェント定義の実体は、Claude Code の規約に従い root-project/.claude/agents/ に置く。本フレームワークは「指揮役がどのエージェントをいつ起動するか」のルールを提供する。
| エージェント | 主な責務 |
|---|---|
architect |
タスク分解、依存関係整理、実装順序策定、受け入れ基準定義 |
designer |
画面設計 / API 設計 / DB 設計 / セキュリティ設計 / 監視設計 / テスト設計 |
backend-developer |
Go バックエンド実装（Clean Architecture、テナント分離 + RBAC） |
frontend-developer |
React / TypeScript 実装（画面・カスタムフック・API クライアント） |
test-implementer |
Go テスト・Vitest コンポーネントテスト・Playwright E2E |
platform-builder |
共通基盤・起動環境（ディレクトリ構造・Docker Compose・CI/CD） |
ops-writer |
運用資料・プロセス文書（progress / session-log / 日報 / issue 移動） |
reviewer |
設計・実装・テストの品質検証 |
詳細は operations/subagent-design.md を参照。
編集対象のリポジトリでフローを判定する。
| 編集対象 | フロー |
|---|---|
dev-journal/ |
設計成果物フロー（チケット起票 → チケットレビュー → 成果物作成 → 内部レビュー → コミット → codex レビュー → 指摘対応） |
expense-saas/ |
PR フロー（チケット起票 → チケットレビュー → /implement → ローカルテスト → 内部レビュー → codex レビュー → マージ前最新化 → スカッシュマージ） |
詳細・各ステップの責務分担は guide/workflow.md を参照。
| 関心 | 参照先 |
|---|---|
| 全体プロセスの完走記録 | dev-journal/progress-management/progress.md |
| 設計判断（ADR） | dev-journal/deliverables/docs/30_arch/adr/ |
| テスト戦略 | dev-journal/deliverables/docs/60_test/ |
| Step 別作業分解 | guide/work-breakdown/ |