アーキテクチャ概要

claude-forge はソフトウェア開発を隔離されたフェーズに分解し、各フェーズを専門のサブエージェントが実行します。メインエージェントは薄いオーケストレーターとして機能し — 作業のルーティング、サマリーの提示、状態の管理を行い — サブエージェントがすべてのコード読み書きを担当します。

コンポーネント図

コンポーネントの接続

SKILL.md (オーケストレーター)
  ├── mcp__forge-state__* MCPツールで状態遷移を呼び出し
  ├── Agent ツールでエージェントを名前で起動
  └── hooks/ が自動的に制約を強制
       ├── pre-tool-hook.sh  → Phase 1-2で書き込みブロック、
       │                        並列Phase 5でgit commitブロック、
       │                        main/masterへのcheckoutブロック
       ├── post-agent-hook.sh → 不正なエージェント出力を警告
       ├── post-bash-hook.sh  → summary.md + state.jsonの自動コミット（v1レガシー; v2はEngine execアクションを使用）
       └── stop-hook.sh       → 途中終了を防止

責任マトリクス

責任	オーナー
フェーズの順序制御とフロー	SKILL.md（オーケストレーター）
状態遷移	Go MCPサーバー（mcp__forge-state__* ツール）
制約の強制	フックスクリプト（自動）
ドメイン専門知識（分析、設計、コード）	Agent .md ファイル
ランタイムパラメータ	オーケストレーター → エージェントプロンプト

ディレクトリ構造

claude-forge/
├── CLAUDE.md              ← AIエージェントガイド（Claude Code が自動読み込み）
├── ARCHITECTURE.md        ← インデックス（詳細は docs/architecture/ を参照）
├── BACKLOG.md             ← 既知の問題・改善候補
├── README.md              ← プロジェクト概要とクイックスタート
├── .claude-plugin/
│   └── plugin.json        ← プラグインメタデータ（名前、バージョン）
├── .claude/
│   └── rules/             ← git.md、shell-script.md、docs.md
├── agents/                ← 10 の専門エージェント定義（.md ファイル）
├── docs/
│   ├── _partials/         ← SSOT コンテンツ断片（docs/ ファイルが組み込む）
│   └── architecture/      ← アーキテクチャドキュメント（13 ファイル）
├── hooks/
│   └── hooks.json         ← フック定義（Setup、SessionStart、PreToolUse、PostToolUse、Stop）
├── mcp-server/            ← Go MCPサーバーソース（forge-state バイナリ）
├── scripts/               ← フックスクリプト + テストスイート
│   ├── session-start-hook.sh ← セッション開始時にダッシュボードURLを表示
│   ├── pre-tool-hook.sh   ← 読み取り専用ガード、コミットブロック、チェックアウトブロック
│   ├── post-agent-hook.sh ← エージェント出力品質バリデーション
│   ├── stop-hook.sh       ← パイプライン完了ガード
│   └── test-hooks.sh      ← 自動フックテストスイート（62テスト）
└── skills/forge/SKILL.md  ← オーケストレーター命令（メインスキル）