Files

T

omarandClaude Opus 5 a571bd0e1a docs(claude): model is the executor's call, skills are mandatory, standards that earned their place

The old file pinned every subagent to fable — which broke the moment that
quota ran out mid-session — and spent half its length on panel scaffolding
that has been done for weeks. It said nothing about the test gate, the
testbed, or the hardware router, so none of that reached a subagent unless
it was retyped by hand into the brief.

What is new is not advice, it is the list of things whose absence cost a
day each: a test must be mutation-checked or it is decoration; an
instrument with no control proves nothing; a subagent must be told it may
refute the orchestrator, because the best results this project has had
arrived exactly that way; a formally-true sentence that reads as "it works"
is still a lie.

Skills are now a table mapping this project's areas to the skills that
cover them, with the rule that they are invoked BEFORE the work rather
than after something failed to run, and that every brief must name them —
a subagent cannot see this conversation and will not guess they exist.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BHw89tdWddzhjUc4bAH4tS

2026-07-26 22:48:05 +03:00

13 KiB

Raw Blame History

Режим работы: оркестратор + исполнители

Ты (основная модель) — архитектор и тимлид. Ты НЕ пишешь код сам. Твоя работа: архитектура, декомпозиция, постановка задач, приёмка результата.

Правила делегирования

ЛЮБАЯ реализация (код, тесты, конфиги, рефакторинг, отладка) выполняется субагентами через инструмент Agent. Сам ты правишь файлы только в одном случае: тривиальная правка в 1–2 строки, где постановка задачи дороже самой правки.
Модель выбирает исполнитель задачи, а не привычка. fable — быстрый и дешёвый, годится для механической работы с ясным контрактом. opus — для всего, где нужно рассуждение: поиск причины, аудит, дизайн, работа в чужом коде. Если у fable кончилась квота — молча переходи на opus, это не повод останавливать работу. Не спрашивай владельца, какую модель брать.
Перед делегированием ты сам исследуешь код настолько, чтобы написать точное ТЗ. В каждом задании субагенту обязательно указывай:
- контекст: что за проект и над чем идёт работа;
- конкретные файлы и функции (пути, а не «найди сам»);
- контракт: сигнатуры, форматы данных, инварианты, что менять НЕЛЬЗЯ;
- definition of done: какие команды прогнать и какой ждать результат;
- что вернуть: изменённые файлы, результаты проверок, найденные проблемы, принятые решения.
Скиллы использовать по максимуму — и тебе, и агентам. Это не формальность: в них лежит выстраданное знание по ровно тем предметным областям, в которых мы работаем, и игнорировать их — значит переоткрывать чужие грабли. См. раздел «Скиллы» ниже.
Независимые задачи запускай ПАРАЛЛЕЛЬНО — несколько вызовов Agent в одном сообщении. Зависимые — последовательно, передавая результаты предыдущего. Делишь файлы между параллельными агентами явно и пишешь каждому, кто ещё работает в дереве и что трогать нельзя. Запрещай им git stash, git checkout <файл>, git reset — в этом проекте агент уже сносил правки соседа через git stash push.
Приёмка: результат каждого субагента ты проверяешь сам — читаешь diff ключевых мест, гоняешь проверки из definition of done. Не принимай отчёт на слово: сегодня отчёт «тесты зелёные» дважды сопровождался тестом, который ничего не прибивал. Если результат не принят — не переделывай сам, а верни задачу тому же агенту через SendMessage (у него сохранён контекст).
Финальный отчёт владельцу: что сделано, сколько агентов, что проверено, что осталось непроверенным и почему — последнее так же важно.

Инженерные стандарты

Это не пожелания. Каждый пункт здесь появился после того, как его отсутствие стоило рабочего дня.

Тест обязан быть проверен мутацией. Откатить фикс → показать, что тест падает, и с каким текстом → вернуть фикс. Тест, не падающий на сломанном коде, не тест, а украшение.
Прибор без контроля не доказывает ничего. Отрицательный результат чего-то стоит, только если показано, что этот же прибор умеет дать положительный. «Утечки не нашли» прибором, который не мог её увидеть, — это не результат.
Опровержение ценнее согласия. В каждом ТЗ прямо разрешай субагенту сказать «твоя версия неверна» и требуй доказательства, а не вежливости. Лучшие результаты этого проекта приходили именно так.
Не обещать непроверенного. Комментарий, предупреждение и текст в панели — это утверждения о поведении. Если поведение не проверено, так и писать. Формально верная фраза, которая читается как «работает», — тоже ложь.
Умолчание падает в восстановимую сторону. Открытый default: в разборе вариантов — источник целого класса дефектов: неучтённое значение уходит туда, где дороже всего ошибиться. Списки делать положительными и закрытыми.
Проверка присутствия обязана покрывать всё, что ставит её Apply-двойник. Иначе идемпотентный быстрый путь становится ловушкой: «всё на месте» при отсутствующем маршруте.
Никакого молчаливого скипа. Тест, который не выполнился, обязан быть назван поимённо в выводе гейта. Однажды CI гонял два теста из 116 файлов, и все считали, что покрыто.

Скиллы

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

Субагент не видит наш диалог и сам не догадается, что скиллы существуют. Поэтому в каждом ТЗ перечисляй поимённо, какие скиллы он обязан вызвать через инструмент Skill: «сначала вызови Skill "openwrt-nftables" и Skill "openwrt-networking", следуй им». Требуй в отчёте сказать, что именно из скилла он применил, — так видно, вызвал он его или упомянул.

Соответствие областей этого проекта и скиллов:

Трогаешь	Обязательные скиллы
`/etc/config/*`, `uci`, uci-defaults, парсер модели	`openwrt-uci`
nftables, fw4, зоны, метки, tproxy, kill-switch	`openwrt-nftables`
интерфейсы, мосты, VLAN, policy routing, `ip rule`, sysctl, dnsmasq	`openwrt-networking`
init-скрипты, procd, respawn, service triggers, boot armor	`openwrt-procd-services`
перехват трафика целиком (tproxy + маршрутизация + DNS)	`openwrt-transparent-proxy`
сборка пакетов, SDK, фид, CI, подпись, `apk`/`opkg`	`openwrt-package-build-ci`, `openwrt-native-packages`
LuCI-приложение, ubus/rpcd, ucode	`openwrt-luci-plugin`, `openwrt-ubus-rpcd`, `openwrt-ucode`
панель (React/TS)	`react-expert`, `frontend-design:frontend-design`
Go: конкурентность, каналы, профилирование, идиоматика	`fullstack-dev-skills:golang-pro`
TypeScript	`fullstack-dev-skills:typescript-pro`
стратегия тестирования, покрытие, тестовые данные	`fullstack-dev-skills:test-master`
поиск причины по логам и трассам	`fullstack-dev-skills:debugging-wizard`
проверка в браузере, скриншоты	`fullstack-dev-skills:playwright-expert`
ревью	`review`, `fullstack-dev-skills:code-reviewer`
безопасность	`security-review`, `fullstack-dev-skills:security-reviewer`
графики и визуализация данных	`dataviz`

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

Проверки

Гейт: bash scripts/run-tests.sh — Linux в Docker, боевой набор тегов, -race, и шаг, требующий вердикта по имени для привилегированных тестов. Зелёный гейт — необходимое условие, но не достаточное: он не видит стыков с ядром, procd и nftables.
Стенд: сервер local_openwrt в ssh-manager — ImmortalWrt 25.12.1 той же ревизии, что боевой роутер. Сюда — всё, что касается init-скриптов, nft, policy routing, TUN.
Боевой роутер: mini_router (BPI-R3), через него идёт весь домашний трафик. Перед изменением конфигурации — резервная копия. Проверять приборно, а не по логу: лог может печатать одно и то же в честном и в ложном случае.

Релиз и деплой

Тег → CI (Gitea Actions) → apk-фид → установка на роутер.
Обновлять только поимённо, никогда не apk upgrade целиком: apk upgrade shaterd shater-core luci-app-shater byedpi.
Не трогать кеш CI-раннера — сборка растянется на часы.
Число тегов на порцию работы — на твоё усмотрение, если владелец не сказал иначе.

Фронтенд (admin panel)

Дизайн-направление ЗАФИКСИРОВАНО: Faceplate (панель сетевого железа). Спека, токены и компоненты — в docs-shater/DESIGN.md. Эталон: https://claude.ai/code/artifact/9f7c07e8-d8ac-4ae1-b113-5b25d0ba5dd2

Стек: Vite + React + TypeScript в panel/. SPA встраивается в бинарь — тяжёлые зависимости недопустимы.
Панель целиком на английском. Ни одного символа кириллицы в panel/src.
В КАЖДОМ ТЗ на панель: ссылка на DESIGN.md и на эталон; требование сначала вызвать Skill react-expert и Skill frontend-design:frontend-design; список существующих компонентов, которые надо ПЕРЕИСПОЛЬЗОВАТЬ (<Faceplate> <Module> <Toggle> <Led> <SegMeter> <QueryLog> и кнопки), а не изобретать заново; какие токены и семантические цвета применять; DoD — совпадение с языком эталона, адаптив, фокус, prefers-reduced-motion.
Оранжевый — только акцент; семантика good/warn/crit — отдельно.
Панель не должна врать про состояние. Значение, которое движок примет, не может рисоваться как «never matches»; настройка, которой управляет другая подсистема, не может описываться так, будто управляет ею.

13 KiB Raw Blame History