claude-factory

Персональная система «циклической разработки» (loop engineering), управляемая голосовым диалогом.

Когда вы говорите в голосовом режиме приложения 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 и потому легче утекает (остаётся в логах). Если можно использовать заголовок, закройте эту возможность, установив mcp.allow_path_token в false в config.yaml.

4. Использование

Обращайтесь к секретарю (голосом), например так:

Узнать статус

• «Что сейчас происходит?» → get_org_status (вся организация за один раз. Сначала это)

• «А та задача?» → get_job (переключайте summary / report / log через detail)

• «Прочитай результаты исследования» → 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». Изменения вносятся через roles: в config.yaml, и изменить их может только человек (чтобы не создавать путь, по которому агент интеграционного управления смог бы расширить собственные права).

Автономная работа (доверенность)

Когда цель утверждается через 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 обнаружились два важных момента, меры приняты:

• can_use_tool не вызывается для инструментов, которые CLI одобряет автоматически. Если полагаться только на колбэк авторизации, запись за пределы репозитория возможна даже в режиме планирования. Поэтому применяются совместно запрет на уровне CLI через disallowed_tools и песочница ОС (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/claude_factory/, а не непосредственно в 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)

Документы: docs/01_企画書.md (замысел) → 02_制作指示書.md (основа) → 03_セッション管理.md (дополнение) → 04_組織化設計書.md (организация).

8. Что осталось

• M6 голосовой E2E: прогнать один реальный проект только голосом (ручная проверка после регистрации коннектора).

• Push-уведомления об ожидающих решения вопросах (v2).

• Правила уборки разветвлённых worktree (удалять или оставлять после слияния).

• Обнаружение случаев, когда интеграционное управление продолжает раздавать одну и ту же работу (сейчас единственный ограничитель — бюджет и срок).

• Кто должен быть арбитром при расхождении мнений между отделами — интеграционное управление или вынесение вопроса человеку.