Подключить свой проект к заводу

Быстрый старт в четыре шага — init, /setup, /feature, /publish-recording — а затем что появилось в проекте, команды и как завод устроен внутри.

Быстрый старт

Нужны Node 22+, git и Claude Code или Codex CLI. Проект должен быть git-репозиторием (в пустой папке выполните git init): /feature требует чистой рабочей копии и делает коммиты.

Cyberzavod задуман независимым от агента. Поддержаны два адаптера: Claude Code (по умолчанию) и Codex CLI (init --agent codex); других агентов пока нет. Проектом управляет один агент. Ниже отличия Codex помечены: скиллы вызывают через $, а не через / ($setup, $feature, $publish-recording). Короткая версия этой страницы: Cyberzavod за 3 минуты.

npx cyberzavod init в корне проекта (для Codex — npx cyberzavod init --agent codex). Если npx спросит, скачать ли пакет, ответьте y. init покажет, что нашёл, и спросит Продолжить? [Y/n] (в английском выводе Continue? [Y/n]), затем запишет конфиг, AGENTS.md и файлы агента и напечатает, что закоммитить. Закоммитьте эти файлы.
Откройте агента в проекте после init (сессия, начатая раньше, запишется без начала) и запустите /setup (в Codex — $setup). Скилл заполнит AGENTS.md по вашему репозиторию, спросит только то, чего не узнать из кода, и один раз прогонит проверки (команды, которые должны проходить, чтобы агент мог закончить ход). Закоммитьте файлы, которые он изменил (он их перечислит).
/feature <задача> (в Codex — $feature <задача>). Задача проходит этапы: постановка, код, ревью, проверки, фиксация (этап — один шаг процесса; у большинства этапов свой агент). Вы одобряете план, в конце получаете коммиты.
/publish-recording (в Codex — $publish-recording) в той же сессии. Скилл превратит сессию в запись (очищенный слепок задачи: этапы, промпты, реплики, время, токены) и попросит вас её проверить. С вашего согласия он отправит запись в галерею (личную страницу на сайте; при первой отправке нужен вход через GitHub) и напечатает ссылку вида https://cyberzavod.com/r/?id=…. Цех, вид сверху на сайте, проиграет задачу по этой ссылке.

Готовые сборки, которые можно открыть и посмотреть, — в примерах ниже.

Что появилось в проекте

.cyberzavod/project.json: маркер и конфиг проекта: id проекта, процесс, агент на каждый этап, проверки и путь журнала. Журнал — каталог .cyberzavod/journal/, в нём сессии, решения и заметки отдельными JSON-файлами.
AGENTS.md: правила проекта для агентов и людей. Рукописный CLAUDE.md, если он был, становится AGENTS.md, иначе ложится заготовка, которую заполнит /setup.
Для Claude Code CLAUDE.md: тонкая точка входа. Он генерируется: руками его не правят.
Для Claude Code .claude/agents/: агенты этапов и редактор записи.
Для Claude Code .claude/skills/: скиллы /setup, /feature и /publish-recording.
Для Claude Code .claude/settings.json: хуки записи и остановки и запрет читать и править .env. Ваши собственные настройки и хуки в этом файле остаются как есть.
Для Codex CLI .codex/config.toml: рабочие правила для агента и поднятый предел размера AGENTS.md (Codex читает AGENTS.md сам, поэтому CLAUDE.md нет).
Для Codex CLI .codex/agents/: роль на каждый этап и редактор записи.
Для Codex CLI .agents/skills/: скиллы $setup, $feature и $publish-recording.
Для Codex CLI .codex/hooks.json: хуки записи и остановки и защита, которая отказывает на .env и сырые журналы сессий. Ваши собственные хуки в этом файле остаются как есть.
.cyberzavod/generated.json: список файлов, которые сгенерировал Cyberzavod, с контрольными суммами. По нему сгенерированный файл отличается от исправленного вами.
строка в .gitignore: capture/ журнала, где лежат сырые журналы сессий, в git не идёт.

--id, --check и --journal меняют то, что init распознал; --yes пропускает подтверждение. Подробности: npx cyberzavod init --help.

Cyberzavod не перезаписывает молча файлы, которые ему не принадлежат. Если на месте сгенерированного файла лежит ваш, init остановится, ничего не записав, и скажет, что делать. Повторный init в подключённом проекте ничего не меняет: он скажет, актуальны ли файлы или нужен npx cyberzavod sync.

Доверие Codex

Codex запускает хуки и роли проекта, только если вы доверяете проекту и одобрили хуки. Это хранится в вашем собственном конфиге Codex ($CODEX_HOME/config.toml, по умолчанию ~/.codex/config.toml), а не в проекте. После своего единственного подтверждения init --agent codex отмечает проект доверенным и одобряет записанные хуки; sync переносит одобрение на обновлённые хуки, а disconnect убирает только добавленное init и не трогает доверие, которое вы дали сами. Файл правится построчно, комментарии и порядок остаются. doctor проверяет доверие и подсказывает, как починить. Команды хуков — POSIX-оболочка: на Windows запускайте Codex в WSL, потому что хуки на родном Windows не проверены.

Команды

Каждую команду запускайте как npx cyberzavod <команда>.

Начало

init: подключить проект: конфиг, AGENTS.md, файлы агента. --agent claude|codex выбирает агента, по умолчанию claude.
status: проект, процесс, агенты этапов, проверки и журнал.

Журнал

decision: записать решение в журнал.
note: записать заметку в журнал.

Галерея

login: войти через GitHub, чтобы публиковать записи в галерею.
logout: забыть сохранённый токен GitHub.
share: отправить запись из журнала в вашу галерею.
unshare: убрать запись из вашей галереи.
gallery: ваша галерея: записи, лимит, ссылки; открыть или закрыть.

Обслуживание

sync: заново распознать стек и пересобрать файлы агента. sync --diff показывает, что команда добавит, обновит и удалит и чего не тронет, ничего не меняя. sync --check сообщает то же и завершается с кодом 1, если что-то устарело. sync --force перезапишет файл, который вы написали или исправили сами на месте сгенерированного.
doctor: проверить подключение и подсказать, как починить.
disconnect: убрать Cyberzavod из проекта, см. Как убрать Cyberzavod.

Для скриптов и CI status --json, doctor --json, sync --check --json и sync --diff --json печатают один JSON-документ без цвета, со schemaVersion и постоянными ключами.

npx cyberzavod <команда> --help покажет флаги команды. Язык выбирают --lang en|ru, CYBERZAVOD_LANG или локаль системы. Чтобы перейти на новый выпуск, выполните npx cyberzavod@latest sync: команда перепишет файлы агента и хуки под новую версию. draft, publish и hook вызывают скиллы и хуки, а не вы.

Если что-то не работает

Начните с команды:

npx cyberzavod doctor

Она печатает строку на каждый пункт: ✓ — в порядке, – — замечание, ✗ — проблема. Под каждым ✗ стоит строка «Как починить: …». Если есть ✗, код выхода 1. doctor не ходит в сеть. Команды проверок он только ищет; чтобы запустить и их, выполните npx cyberzavod doctor --run-checks.

Чего doctor не ловит:

Агент был открыт до init. В журнале нет начала сессии, поэтому у записи пусты проект, версия и процесс. Их можно заполнить на шаге редактуры, но проще начать новую сессию.
Codex игнорирует роли и хуки. Проекту или его хукам нет доверия в вашем конфиге Codex; doctor об этом скажет. Откройте Codex в проекте и доверьте его (или добавьте проекту trust_level = "trusted" в конфиг Codex) и одобрите хуки через /hooks.
Хук остановки не отпускает. Значит, красные проверки: исправьте то, что они печатают.
Нет сети и нет пакета в кэше npm. Хуки записи пропускаются, а стоп-хук отпускает агента с сообщением, что проверки пропущены.

Неожиданная ошибка печатается одной строкой. Чтобы увидеть стек для сообщения об ошибке, повторите команду с CYBERZAVOD_DEBUG=1.

Как убрать Cyberzavod

npx cyberzavod disconnect

Сначала команда покажет, что уберёт и что оставит, и спросит Продолжить? [Y/n]. Убирается только добавленное Cyberzavod: сгенерированные CLAUDE.md, агенты и скиллы в .claude/ (для Codex — .codex/ и .agents/skills/), его хуки и запреты в .claude/settings.json (для Codex — .codex/hooks.json и доверие, которое он добавил в конфиг Codex), .cyberzavod/generated.json и .cyberzavod/project.json. Остаются ваш код, AGENTS.md, журнал, строка в .gitignore, ваши настройки и хуки и сгенерированные файлы, которые вы исправили руками. Без терминала добавьте --yes. Claude Code читает CLAUDE.md, поэтому, если продолжаете с ним работать, создайте CLAUDE.md с одной строкой @AGENTS.md.

Живые примеры

Завод собрал с нуля три проекта-примера. Каждый начался с одного промпта человека на серию задач, и эту серию ведущий (сессия /feature) сам провёл по процессу: постановка, код, ревью, проверки, фиксация. У «Делим счёт» после серии были доработки по новым промптам человека. Каждая задача — отдельная запись; на странице проекта его сборки идут по порядку задач, там же итоги: время, токены, возвраты (работа, которую ревью или проверка отправили назад) и участие человека. Записи dupes и doc-diff — на русском, «Делим счёт» — на английском.

«Делим счёт» — веб-приложение на TypeScript, Astro и Solid, проект на английском: страница проекта. В записи «Astro + Solid migration and English project language» проект переходит на английский, а интерфейс — на Astro и Solid, по коммиту за шаг: ревью дважды возвращает работу, а 24 снимка экрана до и после переезда совпадают до пикселя.
dupes — программа для командной строки на Rust: страница проекта. В записи «Безопасная очистка в корзину, JSON и README» ревью дважды возвращает перенос в корзину, пока программа не перестаёт рисковать настоящими файлами.
doc-diff — сравнение версий договора на Python: страница проекта. Запись «Каркас doc-diff и извлечение текста из PDF и DOCX» открывает серию: в ней промпт человека сразу на пять задач.

Как это устроено

Киберзавод — harness: готовый набор процесса, ролей, принципов и проверок. Он не пишет код сам и не заменяет вашего агента. Из harness он собирает файлы, которые понимает агент. Ваш стек может меняться, и агент тоже. Процесс остаётся тем же. Cyberzavod работает локально: наружу ничего не уходит, пока вы сами не опубликуете запись. В сеть ходят только команды галереи (login, share, unshare, gallery): к GitHub для входа и на сервер cyberzavod.com; init, sync, status, doctor и хуки никуда ничего не отправляют; npx лишь скачивает пакет cyberzavod из npm, если его ещё нет в кэше.

Этапы и роли

Ведущий, то есть сама сессия /feature, код не пишет, а передаёт работу этапам. Каждый этап — агент из .claude/agents/ (для Codex — роль из .codex/agents/) со своей моделью; при model: "default" её выбирает адаптер. Список ниже — для Claude Code; у Codex свои модели: старшая для постановки и ревью и рабочая для кода и проверки, а этап ведущий зовёт через spawn_agent:

постановка: analyst, Opus: ошибка в постановке обходится дороже всего;
код: coder, Sonnet, а на второй доработке Opus;
ревью: reviewer, Opus;
проверка: tester, Sonnet.

Ход работы:

Постановка. analyst изучает код и пишет план с критериями готовности. Ведущий показывает его целиком вместе с вопросами и ждёт вашего одобрения.
Код. coder делает задачу по плану.
Ревью. reviewer читает изменения. «На доработку» — возврат.
Проверка. tester сверяет результат с критериями и запускает проверки проекта. Дефект — возврат.
Фиксация. Коммиты по правилам из AGENTS.md. Если AGENTS.md описывает публикацию и выкатку, ведущий делает и их. Решения, важные надолго, записываются в журнал командой decision, заметки — командой note.

Возвраты

Возвраты от ревью, от проверки и от фиксации считаются вместе:

первый: coder на своей модели;
второй: coder на более сильной модели;
третий: стоп. Ведущий показывает оставшиеся замечания и что уже пробовали, и зовёт вас.

Хук остановки

Пока проверки красные и агент менял код в этом ходе, хук остановки не даёт ему закончить ход. После трёх неудачных попыток подряд он останавливается и зовёт человека. Чужие незакоммиченные правки, сделанные до хода, агента не держат.

Проверки

Проверки — команды из verification.commands в .cyberzavod/project.json; verification.paths перечисляет каталоги кода (пустой список — весь репозиторий). Они идут по порядку на каждой остановке агента, который менял там код. Пока они красные, агент не может закончить ход. Не кладите сюда то, что требует недоступной агенту среды, например Docker: это оставляют CI.

Журнал и формат записи

Журнал — каталог из конфига (journal), по умолчанию .cyberzavod/journal. Он ваш и лежит в вашем репозитории; можно и вне его, например ../<проект>.cyberzavod. Каждая запись — отдельный JSON-файл:

sessions/: записи сессий агента;
decisions/: решения (npx cyberzavod decision "<решение>" --why "<почему>");
notes/: заметки (npx cyberzavod note "<текст>");
capture/: рабочие файлы адаптера, сырые журналы сессий и черновики записей. В них исходные тексты ваших промптов, поэтому init прячет capture/ от git.

У каждой записи один и тот же конверт: версия, тип, время, проект, сессия, источник (агент или человек) и данные. Этот формат — весь договор между инструментом и витриной: свой цех для визуализации можно построить на своём журнале.

В .cyberzavod/project.json лежат:

projectId, версия harness, процесс и путь журнала;
agents: для каждого этапа provider, agent и model;
verification: commands и paths, см. «Проверки» выше;
stack: что распознал init, только для справки.

Публикация записи подробно

/publish-recording проведёт по шагам:

Черновик. draft собирает его из самого свежего сырого журнала сессии. Черновик ложится в capture/<агент>/drafts/ журнала (capture/claude/drafts/ или capture/codex/drafts/).
Редактура. Сессия пишет заголовок записи и переписывает ваши промпты в чистовой вид: главное указание и уточнения. Агент recording-editor пишет реплики между этапами и к вам и вмешательства человека, то есть моменты, когда автоматика ждала вашего слова.
Проверка человеком. Скилл показывает таблицы промптов, реплик и вмешательств. Читайте их внимательно: в запись уйдёт то, что вы одобрите. Публикация ищет в тексте адреса и ключи, но это лишь страховка.
Публикация. publish проверяет формат и пишет sessions/<id>.json в журнал проекта.
Коммит. Если журнал лежит в репозитории проекта, скилл запускает проверки проекта и коммитит запись по правилам из AGENTS.md.
Галерея. С вашего согласия скилл отправляет запись в вашу галерею.

Если в одной сессии шло несколько задач, каждая публикуется отдельной записью: скилл разметит их в черновике сам. Чтобы сравнить прогоны одной задачи на разных моделях или агентах, назовите метку задачи, когда просите запись: скилл положит её в запись, а сайт покажет записи с одной меткой рядом. Команды галереи вы не набираете: их запускает скилл. Для ручного пути нужны login, share <id> и gallery --public.

Галерея

Войдите через GitHub:
```
npx cyberzavod login
```
Команда покажет код и адрес https://github.com/login/device: откройте его, введите код и подтвердите. Завод просит у GitHub только публичный профиль — чтобы узнать ваш логин. Токен хранится в каталоге настроек пользователя (~/.config/cyberzavod/credentials.json, на Windows — %APPDATA%\cyberzavod), вне проекта; logout его удаляет.
Отправьте запись по её id — имени файла в sessions/ журнала:
```
npx cyberzavod share <id>
```
Перед отправкой share проверяет запись так же, как сайт. В ответ он печатает ссылку вида https://cyberzavod.com/r/?id=<slug>. Повторная отправка того же id заменяет запись, ссылка остаётся прежней.
Галерея по умолчанию закрыта: запись видят только те, у кого есть ссылка. Чтобы галерея появилась на сайте, откройте её:
```
npx cyberzavod gallery --public
```
Открытая галерея получает свою страницу /gallery/?user=<login>, которую видит тот, у кого есть ссылка, например с бейджа; общего списка галерей и аналитики по ним нет. gallery --private снова закрывает её; ссылки на записи продолжают работать.

В галерее не больше 5 записей; замена записи новой не считается. Когда лимит исчерпан, share покажет список ваших записей: освободите место командой unshare <id>. gallery без флагов показывает записи со ссылками, открыта ли галерея и лимит. Для открытой галереи gallery печатает ещё и строку бейджа для README. Та же строка с кнопкой «копировать» есть на странице галереи.

[![Built at Cyberzavod](https://cyberzavod.com/api/badges/<login>.svg)](https://cyberzavod.com/gallery/?user=<login>)

То же можно сделать на сайте, без терминала: войдите через GitHub в меню (на телефоне — в панели «Записи») и откройте личный кабинет. Там галерею открывают и закрывают, видят записи со ссылками, удаляют лишние и копируют строку бейджа. Загружаются записи по-прежнему только из проекта, командой share.

Проект на главной сайта завода

Главная и страницы проектов сайта собираются из репозитория завода: записи — из его .cyberzavod/journal/sessions/, карточки проектов — из projects/. Чтобы ваш проект был там с карточкой, предложите pull request в репозиторий завода с двумя файлами:

запись .cyberzavod/journal/sessions/<id>.json из журнала вашего проекта;
карточка projects/<id>.json: id, name и description одной строкой на каждом языке сайта ({ "en": …, "ru": … }) и необязательные repo и website, только с https, и stack: до шести подписей вроде ["TypeScript", "Vite"].

Перед этим запустите в клоне pnpm install и make check-web: он собирает сайт и ловит битую карточку или запись.

Исходники harness, CLI и адаптеров Claude Code и Codex CLI лежат в репозитории завода: harness/, packages/cli, adapters/claude и adapters/codex. В npm они выходят одним пакетом cyberzavod.