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 앱의 "＋" → 커넥터 → 사용자 지정 커넥터 추가에 붙여 넣는다.

토큰 전달 방식은 두 가지가 있다:

경로 방식은 토큰이 URL에 실리는 만큼 유출되기 쉽다(로그에 남는다). 헤더를 쓸 수 있다면 config.yaml의 mcp.allow_path_token을 false로 막아 둘 것.

4. 사용법

비서(음성)에게 예를 들어 이렇게 말을 건다:

상황 파악

• "지금 어떻게 되고 있어?" → get_org_status(조직 전체를 한 번에. 우선 이것)

• "그 일은?" → 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의 뒷정리 규칙(머지 후 삭제할지 남길지).

• 통합 관리가 같은 일을 계속 나눠 줄 경우의 감지(지금은 예산과 기한이 유일한 제동).

• 부서 간 의견이 어긋났을 때 조정자를 통합 관리로 할지, 사람에게 올릴지.