claude-factory

Sistema personal de «ingeniería en bucle» impulsado por diálogo de voz.

Al hablar con el modo de voz de la aplicación Claude, el Claude Code subyacente trabaja en el repositorio y, cuando necesita una decisión, te devuelve una pregunta. Si respondes por voz o por pantalla, el trabajo continúa. El plan está en docs/01_企画書.md, la política de implementación en docs/02_制作指示書.md, y la gestión de sesiones en docs/03_セッション管理.md.

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

El núcleo es la compuerta plan → aprobación → ejecución. Todo trabajo que implique escritura regresa siempre primero como plan y no se ejecuta hasta que tú lo apruebas.

1. Configuración

Python 3.12 o superior, Node.js 18 o superior y la CLI de Claude Code (con sesión iniciada en una cuenta 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    # 中身のトークンを実値に置き換える

La autenticación de Claude Code la hereda el SDK, así que inicia claude una vez en el host de ejecución e inicia sesión con la cuenta Max.

Ajusta config.yaml a tu entorno

Como mínimo, cambia el directorio permitido. Todas las rutas que no estén aquí serán rechazadas.

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

Related MCP server: MCP-Claude Code Bridge

2. Inicio

./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

• Panel: http://127.0.0.1:8787

Quien ejecuta realmente los trabajos es el proceso del servidor MCP. Si solo se inicia el panel, la cola no avanza. Lo que debe estar siempre en marcha es run_mcp.

Comprobación de conectividad:

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. Registrar como conector

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

Añade /mcp al final de la https://<ランダム>.trycloudflare.com mostrada y pégala en la aplicación Claude en «＋» → Conectores → Añadir conector personalizado.

Hay dos formas de pasar el token:

El método de ruta es más propenso a fugas porque el token va en la URL (queda en los registros). Si puedes usar cabecera, cierra esa vía poniendo mcp.allow_path_token a false en config.yaml.

4. Uso

Por ejemplo, habla así con la secretaria (por voz):

Conocer el estado

• «¿Cómo vamos?» → get_org_status (toda la organización de una vez. Empieza por esto)

• «¿Y ese trabajo?» → get_job (detail cambia entre summary / report / log)

• «Lee los resultados de la investigación» → read_board (todo lo que producen los departamentos aparece aquí)

Mover la organización (de mayor a menor impacto)

• «Inicia una nueva tarea con "parser de facturas"» → create_task (crea el directorio + git init + registro en un solo paso. No hace falta editar config.yaml ni reiniciar)

• «Pasa al equipo de diseño la decisión sobre el método de almacenamiento» → start_council (se puede usar con tranquilidad porque no modifica archivos)

• «¿Cuál es la conclusión de la reunión?» → get_council (conclusión, discusión por punto en disputa y objeciones restantes)

• «Pide a demo que arregle el fallo del test» → dispatch_to_code (solo se crea el plan)

• «Apruebo» → answer_question (aquí es cuando se ejecuta por primera vez)

• «Te lo encargo con este objetivo» → grant_mandate (empieza la autonomía; se detiene con revoke_mandate)

Sesiones

• «Divide la sesión actual y prueba otro enfoque» → fork_session (aislado con git worktree)

Forma de la organización (documento de diseño docs/04_組織化設計書.md)

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

La reunión del equipo de diseño avanza en 4 fases dirigidas por el moderador.

1. Lectura previa — el moderador resuelve por sí mismo los puntos obvios (lo registra en resolved_by_chair) y extrae solo los puntos en disputa

2. Deliberación — por cada punto en disputa, nombra a personas de la lista de miembros (con motivo)

3. Examen — los nombrados dan su opinión y critican las opiniones anteriores

4. Conclusión — el moderador presenta la conclusión de cada punto, las objeciones restantes y los temas para el humano

La lista está en config/personas.yaml (1 moderador + 10 miembros). Puedes editarla libremente y se aplica al iniciar.

Permisos por departamento (privilegio mínimo)

«Investigación puede ver la Web pero no escribir archivos»; «Implementación puede escribir archivos pero no ver la Web». Están separados. Los cambios se hacen en roles: de config.yaml y solo las personas pueden cambiarlos (sin crear una vía para que el agente de gestión integrada amplíe sus propios permisos).

Autonomía (mandato)

Al aprobar un objetivo con grant_mandate, la gestión integrada reparte trabajo a los departamentos y avanza sin aprobaciones individuales. A cambio de reducir las aprobaciones, se hace funcionar de forma que se pueda desechar en cualquier momento.

• Se crea una rama de trabajo dedicada (no se toca main)

• Se fija un presupuesto (número de trabajos, coste) y una fecha límite; al agotarse se detiene automáticamente

• Eliminar, git push, modificar el historial y añadir dependencias quedan fuera del mandato. Siempre se detiene a confirmar

• Se puede cancelar todo, incluso en ejecución, con el botón «Detener» del panel (revoke_mandate)

En el panel se ven la cola de preguntas pendientes, la línea de tiempo de progreso, el registro en vivo, los informes, el árbol de bifurcaciones de sesiones y el registro de auditoría. Las respuestas pasan por el mismo camino tanto por voz como por pantalla.

Habilidades de la secretaria (skills/)

Como la operación consiste en abrir un chat nuevo cada mañana, la secretaria no tiene memoria del día anterior. El procedimiento de arranque está en la habilidad skills/factory-startup/ (recopilación de estado → orden de lectura → propuesta del día, con guion de lectura incluido). Se sube desde la configuración de la aplicación Claude y se invoca escribiendo /factory-startup (abreviado /cf) al inicio del chat. No hay palabras de activación en lenguaje natural (para evitar falsos positivos y activaciones omitidas). La sugerencia / de la aplicación sale del name de la habilidad, así que el nombre es en sí mismo la señal. Más detalles en skills/README.md.

El rol se divide entre SECRETARY_GUIDE en el lado del conector (va en cada petición = mantenerlo corto) y la habilidad (se lee solo cuando hace falta = poner aquí procedimientos y guiones).

Instrucciones que funcionan con la secretaria (plan §verificación 4)

Para que no lance solicitudes por su cuenta a mitad de la conversación, conviene decirle algo así:

No llames a dispatch_to_code hasta que yo diga «encárgalo con esto». Hasta entonces, acompáñame en la consulta y ajustemos juntos el texto de la instrucción.

5. Seguridad (instrucciones de producción §8)

Defensas implementadas:

Hay 2 puntos de atención descubiertos al probarlo con Claude Code real, ya mitigados:

• can_use_tool no se invoca para las herramientas que la CLI autoaprueba. Si confías solo en la callback de autorización, se pueden producir escrituras fuera del repositorio incluso en modo plan. Se ha reforzado con la prohibición a nivel de CLI mediante disallowed_tools y con el sandbox del SO (orchestrator.sandbox).

• La salida del directorio mediante cd no se detiene con la comprobación de rutas. Se vigilan las rutas absolutas y .. en los comandos Bash con _bash_escapes_workspace.

• No se carga el .claude/settings.json del repositorio de destino (setting_sources=[]). Si se cargara, el repositorio podría autoaprobar sus propios permisos.

6. Publicación fija (M5)

El túnel desechable cambia de URL en cada inicio, así que para uso habitual conviene pasar a uno con nombre.

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

La publicación permanente la gestiona el servicio systemd cloudflared.service (lee /etc/cloudflared/config.yml).

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

También se puede iniciar con ./scripts/tunnel.sh named claude-factory, pero normalmente no se usa porque el conector quedaría duplicado en el mismo túnel que el servicio residente. Si cambias a funcionamiento manual, detén antes sudo systemctl stop cloudflared. El script también detecta el servicio residente y avisa pidiendo confirmación.

En Route 53, cloudflared tunnel route dns crea el CNAME (<tunnel-id>.cfargotunnel.com). La URL de registro del conector es https://mcp.<domain>/mcp. El panel se coloca detrás de Cloudflare Access y solo en ese caso se usa dashboard.auth: none.

7. Desarrollo

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

La estructura corresponde a la sección §2 de las instrucciones de producción (está empaquetada en src/claude_factory/ en lugar de directamente en src/):

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)

Documentos: docs/01_企画書.md (concepto) → 02_制作指示書.md (base) → 03_セッション管理.md (complemento) → 04_組織化設計書.md (organización).

8. Lo que queda pendiente

• M6 E2E por voz: ejecutar un proyecto real solo con voz (comprobación manual después de registrar el conector).

• Notificaciones push para decisiones pendientes (v2).

• Reglas de limpieza de los worktrees bifurcados (eliminar o conservar tras el merge).

• Detección de que la gestión integrada sigue asignando el mismo trabajo (por ahora el presupuesto y la fecha límite son el único freno).

• Decidir si el mediador cuando los departamentos discrepan es la gestión integrada o si se eleva a un humano.