Один сервис,
пять агентов

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

Восемь месяцев назад этого слоя не было вовсе — только код. Сейчас в репозитории больше пятидесяти операционных документов: три корневых гида для агентов, четыре файла правил, около двух десятков навыков под четыре разных инструмента и двадцать два плана задач. Ниже — разбор этого слоя по частям: как он устроен в папках, как устроен в гите, и почему без ручного ухода за ним агенты перестают помогать. Не хроника «как дошли», а анатомия того, что получилось, с числами и реальной структурой.

Из чего состоит операционный слой

Вот что физически лежит в корне репозитория поверх кода:

CLAUDE.md            гид для Claude Code (31 КБ)
AGENTS.md            гид для остальных агентов (33 КБ)
GEMINI.md            симлинк на AGENTS.md (9 байт)
.claude/
  rules/             4 файла правил (привязаны к путям)
  skills/            7 навыков (срабатывают по смыслу задачи)
  memory/plans/      22 плана задач
  hooks/             перехватчики команд
.codex-skills/       6 навыков под Codex
.kimi/skills/        6 навыков под Kimi
.agent/rules/        5 файлов правил под Gemini (4 из них генерируются)

Начиналось всё с одного файла. Первый CLAUDE.md появился на второй месяц жизни проекта — сто двадцать одна строка, меньше пяти килобайт: стек, список сервисов, таблицы цен, дерево файлов. Сейчас он в шесть с половиной раз больше. И это только один документ из пятидесяти.

Важно понимать, что ни один файл этого слоя — не код. Это инструкции о том, как код трогать: где источник правды, какие инварианты нельзя ломать, как деплоить, куда писать план. Слой растёт не от лени и не от любви к бюрократии, а потому что каждая новая способность в работе с агентами требует места, где она записана. Второй агент — второй гид. Path-scoped конвенция — файл правил. Повторяемая процедура — навык. Сложная задача — папка плана. Слой — это материализованный ответ на вопрос «откуда агент узнаёт, как здесь принято».

Правило и навык — разные механизмы

Первое, что путают, заводя этот слой: считают «инструкцию для агента» одной сущностью. На деле их минимум две, и различаются они не текстом, а тем, когда срабатывают.

Правило привязано к путям. Файл в .claude/rules/ начинается с указания, к каким файлам он относится:

---
paths:
  - "backend/**/*.py"
  - "frontend/**/*.ts"
---
# Code Style Rules
- snake_case для функций, PascalCase для классов
- каждый эндпоинт обязан иметь response_model

Агент, редактирующий питон-файл в бэкенде, получает это правило автоматически — оно цепляется по совпадению пути. Правило не имеет срока годности: «snake_case для функций» верно и через год.

Навык привязан к смыслу задачи. Навык в .claude/skills/ срабатывает не по пути, а по описанию-триггеру, которое агент сопоставляет с тем, что собирается делать:

---
name: billing-edit-check
description: Use BEFORE editing any file that writes to
  users.balance, chat_token_charges, or lives under
  services/billing*.py. Enforces invariants before edits
  ship to prod.
---
# Billing Edit Pre-Flight
Money-path код. Любая правка критична: тихая регрессия
стоит реальных денег.
## Инварианты, которые нельзя ломать
1. FOR UPDATE row lock на каждом чтении баланса перед записью...

Это не справка, а процедура: чек-лист инвариантов, который агент обязан пройти до правки денежного кода. Срабатывает он потому, что агент собрался тронуть биллинг, а не потому, что открыл конкретный файл.

Разница не косметическая. Правило — это «в этом типе файлов так принято всегда». Навык — это «перед таким типом задачи сделай вот это». Если свалить их в одну кучу, получается третий, ядовитый жанр: снимок текущего состояния, который лёг в папку правил и притворяется вечной конвенцией. В разобранном проекте таким оказался файл video-generation.md: список актуальных на январь видео-моделей, положенный в rules/. За пять месяцев в проект добавили новые модели, а файл никто не открыл — он всё это время тихо отдаёт агенту устаревший список как «правило». Снимок состояния в папке конвенций опаснее отсутствующего файла: отсутствующий заставит агента переспросить, а этот отвечает уверенно и неверно.

Один канон, много копий

Как только в проекте появляется второй инструмент, появляется вторая проблема: одно и то же знание про один и тот же код теперь нужно каждому инструменту в его формате. В разобранном проекте параллельно живут четыре набора: .claude/skills, .codex-skills, .kimi/skills, .agent/rules. И дублирование видно прямо в именах файлов — навык проверки биллинга лежит и в .claude/skills/billing-edit-check, и в .codex-skills/ под тем же смыслом. Процедура деплоя чат-модуля расписана отдельно в шести местах, и только одна из шести копий знает про новый скрипт деплоя — остальные пять описывают устаревшую ручную последовательность.

Из всего слоя есть ровно одно место, где рост управляется правильно. Файлы правил под Gemini не пишутся руками — они генерируются из канона:

---
trigger: model_decision
---
<!-- ГЕНЕРИРУЕТСЯ из .claude/rules/api-design.md
     скриптом scripts/gen-agy-rules.ts.
     НЕ редактировать здесь: правь канон
     и запусти npm run gen:agy-rules -->

Один источник (.claude/rules/), автоматическая копия под каждый инструмент, баннер поверх копии, запрещающий её править вручную. Всё, что сделано так, не расходится по определению — копия пересобирается из канона одной командой. Всё, что скопировано руками, разошлось: четыре версии правила про биллинг разными словами, шесть версий процедуры деплоя разной свежести.

Гит: ветки как карта

Структура веток в проекте, который строят несколькими агентами, — это не свалка, а неймспейсы. Конвенция имени: <агент>/<тип>-<слаг>.

gemini/feat-chat-references     gemini/fix-image-download
claude/plan-dr-writable-failover
kimi/fix-model-params           deepseek/eval-run
fix/sentry-7592001386           worktree-agent-a0314b72...

По одному git branch видно, кто над чем работал. Реальное распределение за восемь месяцев (ветки, local плюс remote, по префиксам):

gemini/    56      claude/     5
feature/   35      deepseek/   4
fix/       34      kimi/       2
worktree-*  6      docs/       1

Отсюда читается сразу несколько фактов, которые интуиция подсказала бы неверно. Основной объём рутинной разработки нёс не тот инструмент, который поставили первым и вокруг которого написана вся документация: веток gemini/ — пятьдесят шесть, claude/ — пять. Отдельный класс fix/sentry-* (четырнадцать веток) — это не человек, а автоматический поток починок по алертам мониторинга: присутствие автоматизации видно прямо в списке веток. Префикс worktree-agent-* с хеш-суффиксами — это изолированные рабочие копии для параллельных агентов, чтобы они не топтались в одном дереве.

И здесь же — первая статья счёта за этот слой. Всего веток накопилось сто пятьдесят две. Из локальных сто двадцать три уже вмёржены в основную и при этом не удалены — просто висят. Пока веток десяток, git branch — карта. Когда их полторы сотни, это шум, в котором уже не видно, что в работе, что брошено, а что давно влито и подлежит удалению. Конвенция имён спасает от хаоса ровно до тех пор, пока кто-то регулярно чистит вмёрженное; без чистки неймспейсы просто аккуратно сортируют мусор.

Планы: скелет для больших задач

Когда изменение не влезает в один промпт — многофазное, с рисками, затрагивающее деньги, — его нельзя просто «попросить у агента»: агент сделает ровно то, что недоспецифицировано, и сделает уверенно. Для таких задач в проекте есть отдельная подсистема — папка .claude/memory/plans/, и у неё виден градиент зрелости.

Лёгкий план — один файл:

sites-telegram-notifications/
  plan.md

Полный план — папка на два десятка файлов, каждый со своей ролью:

dr-writable-failover/
  intent.md              что и зачем, до всякого кода
  plan.md                фазы
  decisions.md           пронумерованные арх-решения
  constraints.md         живые ограничения (по ходу)
  glossary.md            термины
  graph.json             граф зависимостей
  RISK-REGISTER.md       реестр рисков
  MONEY-PATH-GATE.md     гейт для фаз, трогающих деньги
  EXECUTION-ORDER-DAG.md порядок выполнения как граф
  verification.md        как проверить, что готово
  reviews/               артефакты независимого ревью
  BRIEF-00..08           бриф на каждую фазу

Каждый файл здесь — ответ на конкретный провал, который случается, если файла нет. intent.md фиксирует «зачем» до кода, иначе агент оптимизирует не ту цель. decisions.md держит пронумерованные решения, чтобы через месяц было видно, почему выбран этот путь, а не другой. MONEY-PATH-GATE.md — отдельный проверочный барьер для фаз, которые списывают деньги: не общая осторожность, а конкретный чек-лист, без которого фаза не закрывается. reviews/ хранит вердикты независимого ревьюера — в этом проекте роль ревьюера планов какое-то время играл отдельный агент (Kimi), проверяя план на несуществующие вызовы функций и неверные числа до того, как за него взялся кодер.

Этот скелет — не украшение. Именно сюда переехали распределение задач и ревью, которых нет в другом месте: за два самых плотных по коду месяца в проекте не завели ни одного GitHub Pull Request, а Issues не использовались вообще ни разу за восемь месяцев. Контроль качества шёл не через классический PR, а через папку плана с явными гейтами. И он работает предметно: в плане резервного переключения инфраструктуры была фаза слияния денежных балансов — самая рискованная во всём плане. После того как реализовали более раннюю фазу, стало видно, что рискованное слияние не нужно вовсе, и фазу вычеркнули целиком. Хорошее ревью не одобряет опасный шаг аккуратно — оно находит способ его не делать.

Что гниёт без ухода

Слой, ради которого агенты вообще окупаются, растёт и портится быстрее, чем код, и убирает за ним по-прежнему только человек. Три конкретных вида гнили из разобранного проекта:

ВЕТКИ    152 всего, 123 вмёрженных-неудалённых.
         git branch перестал быть картой.
КОПИИ    1 правило про биллинг в 4 экземплярах разными
         словами; процедура деплоя в 6 версиях свежести.
БАЗА     AGENTS.md через недели после вывода Codex и Kimi
         всё ещё описывает их в настоящем времени:
         маршрутизацию задач, ветки, доступ к сервисам.

Последняя строка — самая показательная. Часть инструментов из проекта вывели: личные папки их навыков честно замерли сами собой, раз их больше не запускают. А общий координационный документ AGENTS.md, который любой подключённый агент читает автоматически на старте сессии, сам не замирает — он получил живую правку уже после вывода инструментов, но правка добавила новое правило и не тронула устаревшие разделы. Решение «этот инструмент выведен» существует в голове владельца, но не исполнено в файле, который прочитает следующий агент. Отказ от инструмента — это не только «перестать его звать», это отдельный шаг чистки документа, который его звал.

Скорость письма растёт, способность видеть проект целиком падает, и в какой-то момент вторая обнуляет первую. Не потому что агенты пишут плохой код — код чаще как раз хороший. А потому что слой над кодом гниёт молча, и заметно это становится только тогда, когда на него уже нельзя опереться.

Четыре промпта для ревизии слоя

Это не про баги, а про инвентаризацию операционного слоя. Забираются целиком и отдаются своему агенту.

Промпт 1 · что реально используется

Пройди по логам моих последних сессий с агентами: истории вызовов навыков и под-агентов. Для каждого зарегистрированного в проекте навыка и под-агента посчитай, сколько раз он реально был вызван за всё время. Отдельно выведи список тех, у кого счётчик ноль. Ничего не удаляй сам, только покажи список с обоснованием по каждому пункту.

Промпт 2 · разделить инструкции по типу

Прочитай все мои файлы правил и инструкций для агентов. Раздели каждый на один из трёх типов: правило, привязанное к путям (не имеет срока годности), снимок состояния (список версий, моделей, цен, устаревает), навык-процедура (исполняется по шагам). Для каждого файла, отнесённого к снимку состояния, но лежащего в папке правил, проверь по коду: не устарел ли он уже сейчас. Покажи расхождения построчно, ничего не исправляя.

Промпт 3 · ревизия по всем инструментам сразу

Прочитай все мои файлы инструкций для агентов во всех форматах, а не только под один инструмент: корневые гиды (CLAUDE.md, AGENTS.md, GEMINI.md и аналоги), папки правил, все наборы навыков под разные CLI-инструменты. По каждому файлу оцени три вещи. Первое: не раздут ли он, нет ли разнородных тем, которые правильнее вынести в отдельные файлы, читаемые по требованию, а не грузящиеся в каждый контекст. Второе: какие фрагменты повторяются в нескольких файлах слово в слово или по смыслу, и можно ли свести их к одному источнику с автоматической генерацией копий вместо ручного дублирования. Третье: где остались упоминания инструментов, веток или процедур, которых в проекте больше нет. Выведи по каждому пункту список файл-строка и план: что вынести, что объединить, что сократить, что удалить. Сам ничего не меняй.

Промпт 4 · гит-гигиена по агентам

Покажи все ветки репозитория, сгруппированные по приставке (по инструменту или типу задачи). Для каждой группы отметь: сколько уже вмёржено в основную и может быть удалено, сколько висит без коммитов дольше месяца, сколько в реальной работе. Составь план подчистки: что удалить сразу как вмёрженное, что проверить вручную, что оставить. Сами ветки не трогай, только план.

Что из этого следует

Операционный слой проекта, который строят агентами, — это реальный артефакт с реальной анатомией: корневые гиды, правила двух типов, навыки под каждый инструмент, ветки-неймспейсы, папки планов с гейтами. Его нельзя спроектировать за столом заранее, потому что за столом не видно, какой инструмент возьмёт на себя объём, какой навык не запустится ни разу и какой документ переживёт свои инструменты мёртвым грузом. Его можно только вырастить и вести — глядя в собственные папки, ветки и планы, а не в чужие лучшие практики.

Агент пишет код быстро. Держать этот слой правдивым, единым и чистым — по-прежнему человеческая работа, и именно она теперь решает, ускоряют агенты проект или закапывают.