claude-factory

音声対話で駆動する、個人用「ループエンジニアリング」システム。

Claude アプリのボイスモードで話しかけると、裏の Claude Code がリポジトリで作業し、 判断が必要になると質問を返してくる。それに音声か画面で答えると作業が続く。 企画は docs/01_企画書.md、実装方針は docs/02_制作指示書.md、 セッション管理は docs/03_セッション管理.md。

あなた（音声）
  └ Claude アプリ／ボイスモード（秘書）
      └ カスタムコネクタ = MCP Bridge Server（Bearer 認証）
          ├ Orchestrator ── Claude Code（claude-agent-sdk）── 各リポジトリ
          └ SQLite ── Dashboard（FastAPI + React）

中核は 計画 → 承認 → 実行 のゲート。書き込みが起きる作業は必ず一度計画として返り、 あなたが承認するまで実行されない。

1. セットアップ

Python 3.12 以上、Node.js 18 以上、Claude Code CLI（Max アカウントでログイン済み）。

# Mac / Linux
uv sync --extra dev              # または: pip install -r requirements.txt
cp .env.example .env
python -c "import secrets; print(secrets.token_urlsafe(32))"   # → .env の CF_MCP_TOKEN
python -c "import secrets; print(secrets.token_urlsafe(16))"   # → .env の CF_DASHBOARD_PASSWORD

# Windows
python -m venv .venv; .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env    # 中身のトークンを実値に置き換える

Claude Code の認証は SDK が引き継ぐので、実行ホストで一度 claude を起動して Max アカウントでログインしておく。

config.yaml を自分の環境に合わせる

最低限、触ってよいディレクトリを書き換える。ここに無いパスは全て拒否される。

security:
  repo_allowlist:
    - ~/Private_Project           # Mac
    # - C:\Users\<you>\repos      # Windows

Related MCP server: MCP-Claude Code Bridge

2. 起動

./scripts/run_mcp.sh          # MCP サーバー（秘書の窓口 + ジョブのワーカー）
./scripts/run_dashboard.sh    # ダッシュボード（初回はフロントも自動ビルド）

.\scripts\run_mcp.ps1
.\scripts\run_dashboard.ps1

• MCP: http://127.0.0.1:8010/mcp

• ダッシュボード: http://127.0.0.1:8787

ジョブを実際に走らせるのは MCP サーバープロセス。ダッシュボードだけ起動していても キューは進まない。常時動かすのは run_mcp のほう。

疎通確認:

curl -i http://127.0.0.1:8010/mcp                    # 401 = 認証が効いている
curl -s -X POST http://127.0.0.1:8010/mcp \
  -H "Authorization: Bearer $CF_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

3. コネクタとして登録

./scripts/tunnel.sh quick     # 使い捨て（URL は起動ごとに変わる）

表示された https://<ランダム>.trycloudflare.com の末尾に /mcp を付けて、 Claude アプリの「＋」→ コネクタ → カスタムコネクタを追加、に貼る。

トークンの渡し方が 2 通りある:

パス方式はトークンが URL に載るぶん漏れやすい（ログに残る）。ヘッダが使えるなら config.yaml の mcp.allow_path_token を false にして塞ぐこと。

4. 使い方

秘書（音声）に対して、たとえばこう話しかける:

状況を知る

• 「今どうなってる？」 → get_org_status（組織全体を 1 回で。まずこれ）

• 「あの仕事は？」 → get_job（detail で summary / report / log を切り替え）

• 「調査の結果を読んで」 → read_board（部署が出した成果は全部ここに載る）

組織を動かす（重い順）

• 「新しいタスクを『請求書パーサ』で始めて」 → create_task（ディレクトリ作成 + git init + 登録を一手で。config.yaml の編集も再起動も不要）

• 「保存方式をどうするか、設計班にかけて」 → start_council（ファイルは変更されないので気軽に使える）

• 「会議の結論は？」 → get_council（結論・争点ごとの議論・残った反対意見）

• 「demo に、テストの失敗を直すよう依頼して」 → dispatch_to_code（計画だけ作られる）

• 「承認して」 → answer_question（ここで初めて実行される）

• 「この目標で任せる」 → grant_mandate（自走が始まる。revoke_mandate で止まる）

セッション

• 「今のセッションを分岐して、別のアプローチを試して」 → fork_session（git worktree で隔離）

組織のかたち（設計書 docs/04_組織化設計書.md）

子会社 = プロジェクト（互いに不干渉）
  部署 = 役割        調査 / 設計班 / 実装 / デザイン / 統合管理
    成果ボード       部署はここだけを介して成果を見せ合う

設計班の会議は司会主導の 4 段階で進む。

1. 下読み — 司会が自明な点を自分で決着させ（resolved_by_chair に記録）、争点だけを抽出

2. 付議 — 争点ごとに社員名簿から人を指名（理由つき）

3. 検討 — 指名された人が意見と、先行意見への批評を述べる

4. 結論 — 司会が争点ごとの結論・残った反対意見・人間への論点を出す

名簿は config/personas.yaml（司会 1 名 + メンバー 10 名）。自由に編集でき、起動時に反映される。

部署ごとの権限（最小権限）

「調査は Web を見られるがファイルは書けない」「実装はファイルを書けるが Web は見られない」と 分離してある。変更は config.yaml の roles: で行い、人だけが変えられる （統合管理エージェントが自分の権限を広げる経路を作らない）。

自走（委任状）

grant_mandate で目標ごと承認すると、統合管理が各部署に仕事を振り、個別の承認なしに進む。 承認を減らすかわりに、いつでも捨てられる形で走らせている。

• 専用の作業ブランチを切る（main は触らせない）

• 予算（ジョブ数・コスト）と期限を付け、使い切ると自動で止まる

• 削除・git push・履歴の改変・依存の追加は委任の外。必ず止まって確認する

• ダッシュボードの「停止」ボタン（revoke_mandate）で実行中ごと取り消せる

ダッシュボードでは、保留質問キュー・進捗タイムライン・ライブログ・レポート・ セッションのフォークツリー・監査ログが見える。回答は音声でも画面でも同じ経路を通る。

秘書のスキル（skills/）

毎朝あたらしいチャットを立ち上げる運用のため、秘書には前日の記憶がない。 立ち上げ手順はスキルとして skills/factory-startup/ に置いてある （状況収集 → 読み上げ順序 → 今日の提案、読み上げ台本つき）。 Claude アプリの設定からアップロードし、チャットの冒頭に /factory-startup（短縮形 /cf） と打って呼び出す。自然文のトリガー語は置いていない（誤爆と起動漏れを避けるため）。 アプリの / サジェストはスキルの name から出るので、名前がそのまま合図になる。 詳細は skills/README.md。

コネクタ側の SECRETARY_GUIDE（毎回のリクエストに載る＝短く保つ）と、 スキル（必要なときだけ読まれる＝手順や台本を置く）で役割を分けている。

秘書に効く指示（企画 §検証4）

会話の途中で勝手に依頼を飛ばさないよう、秘書側にこう言っておくとよい:

私が「これで依頼して」と言うまで dispatch_to_code は呼ばないで。 それまでは相談に付き合って、指示文を一緒に整えて。

5. セキュリティ（制作指示書 §8）

実装済みの防御:

実 Claude Code で試して分かった要注意点が 2 つあり、対策済み:

• can_use_tool は CLI が自動承認するツールには呼ばれない。 認可コールバックだけを 頼りにすると、計画モードでもリポジトリ外に書き込みが起きる。disallowed_tools による CLI レベルの禁止と、OS サンドボックス（orchestrator.sandbox）を重ねてある。

• cd によるディレクトリ脱出はパス検査では止まらない。 Bash コマンド中の絶対パスと .. を _bash_escapes_workspace で見ている。

• 対象リポジトリの .claude/settings.json は読み込まない（setting_sources=[]）。 読み込むとリポジトリが自分の権限を自己承認できてしまう。

6. 固定公開（M5）

使い捨てトンネルは起動ごとに URL が変わるので、常用するなら名前付きに移す。

cloudflared tunnel login
cloudflared tunnel create claude-factory
cloudflared tunnel route dns claude-factory mcp.<domain>
cloudflared tunnel route dns claude-factory dash.<domain>

~/.cloudflared/config.yml:

tunnel: claude-factory
credentials-file: /path/to/<tunnel-id>.json
ingress:
  - hostname: mcp.<domain>
    service: http://localhost:8010
  - hostname: dash.<domain>
    service: http://localhost:8787
  - service: http_status:404

常時公開は systemd の cloudflared.service が担当する（/etc/cloudflared/config.yml を読む）。

systemctl status cloudflared          # 状態確認
sudo systemctl restart cloudflared    # 設定変更の反映
journalctl -u cloudflared -f          # ログ

./scripts/tunnel.sh named claude-factory でも起動できるが、常駐サービスと 同じトンネルにコネクタが二重に張られるため通常は使わない。手動運転に切り替える 場合は先に sudo systemctl stop cloudflared すること。スクリプト側でも常駐を 検知したら警告し、確認を求める。

Route 53 側は cloudflared tunnel route dns が CNAME（<tunnel-id>.cfargotunnel.com）を 作る。コネクタ登録 URL は https://mcp.<domain>/mcp。 ダッシュボードは Cloudflare Access を前段に置き、その場合のみ dashboard.auth: none にする。

7. 開発

.venv/bin/python -m pytest -q                                  # テスト
cd src/claude_factory/dashboard/web && npm run dev             # フロントの開発サーバー

構成は制作指示書 §2 に対応（src/ 直下ではなく src/claude_factory/ パッケージにしてある）:

src/claude_factory/
├─ config.py        設定（config.yaml + .env）
├─ models.py        型・出力規約・その解析
├─ store.py         SQLite DAO
├─ security.py      トークン・allowlist・レート制限
├─ runner.py        claude-agent-sdk ラッパと承認ゲート（役割別の権限）
├─ orchestrator.py  ジョブキュー、計画→承認→実行、自走ループ
├─ sessions.py      セッション一覧/閲覧/分岐（git worktree 隔離）
├─ personas.py      社員名簿と組閣
├─ council.py       設計班の合議エンジン
├─ integrate.py     統合管理（作業計画を出すだけ。実行はしない）
├─ org.py           組織全体の状況
├─ mcp_server.py    秘書向け MCP
└─ dashboard/       FastAPI + React(Vite)

ドキュメント: docs/01_企画書.md（構想）→ 02_制作指示書.md（基盤）→ 03_セッション管理.md（追補）→ 04_組織化設計書.md（組織化）。

8. 残っていること

• M6 音声 E2E: 実プロジェクト 1 本を音声だけで回す（コネクタ登録後に手動で確認）。

• 判断待ちのプッシュ通知（v2）。

• 分岐 worktree の後片付けルール（マージ後に消すか残すか）。

• 統合管理が同じ仕事を振り続けた場合の検知（いまは予算と期限が唯一の歯止め）。

• 部署間で意見が食い違ったときの調停者を統合管理にするか、人に上げるか。