NetShift — система AI-агентов (руководство оператора)

Это руководство для человека, который запускает AI-агентов на проекте NetShift. Описанная здесь система переносит профессиональные практики agent-разработки: специализированные агенты, шлюз код-ревью, накопление знаний в памяти и строгие правила архитектуры. Работает в двух инструментах: OpenCode и Claude Code — с единым источником правил.

Сами агенты, правила и команды написаны на английском (так точнее работает LLM). Это руководство — на русском.

TL;DR

Открываешь проект в OpenCode (или Claude Code).
Даёшь задачу через команду /task (или просто текстом оркестратору).
Оркестратор уточняет, проектирует, раскладывает задачу на подзадачи в docs/tasks/*.md, делегирует разработчикам, прогоняет шлюзы и код-ревью.
Когда всё прошло ревью — коммитишь сам, руками. Агенты никогда не коммитят.

Что где лежит

AGENTS.md                       # корневой контекст для OpenCode (composition root)
opencode.json                   # конфиг OpenCode: права + подключение правил
.opencode/
  agent/                        # 5 агентов (OpenCode-формат)
  command/                      # /task /review /describe
  skill/                        # shellcheck / smoke-tests / frontend-ci
.claude/
  CLAUDE.md                     # корневой контекст для Claude Code
  settings.json                 # права (allow/ask)
  agents/                       # те же 5 агентов (Claude-формат)
  commands/                     # /task /review /describe
  skills/                       # те же 3 скилла
docs/
  agent-rules/                  # ЕДИНЫЙ ИСТОЧНИК правил (оба инструмента ссылаются сюда)
    project-core.md             #   архитектура, runtime-контракт, шлюзы, gating
    backend-shell.md            #   правила backend (ash + jq)
    frontend-luci.md            #   правила frontend (TS + LuCI)
    packaging.md                #   правила packaging / CI / release
    memory/                     #   ПАМЯТЬ агентов (committed, общая для обоих инструментов)
      architect-orchestrator.md
      shell-backend-developer.md
      luci-frontend-developer.md
      packaging-ci-engineer.md
      code-reviewer.md
  tasks/                        # спеки задач и ревью-доки
    TEMPLATE-task.md            #   шаблон спеки
    TEMPLATE-review.md          #   шаблон ревью
  README-AGENTS.md              # этот файл

Команда агентов

                       ┌──────────────────────────┐
                       │   architect-orchestrator  │  (opus) — дирижёр
                       │  уточняет · проектирует · │
                       │  раскладывает · ревьюит   │
                       └────┬───────┬───────┬──────┘
            ┌───────────────┘       │       └───────────────┐
            ▼                       ▼                       ▼
 ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐
 │ shell-backend-     │ │ luci-frontend-     │ │ packaging-ci-      │
 │ developer (sonnet) │ │ developer (sonnet) │ │ engineer (sonnet)  │
 │ ash/jq, sing-box,  │ │ TS, LuCI, валид.,  │ │ Makefile, Docker,  │
 │ nft, dnsmasq, UCI  │ │ i18n, main.js      │ │ SDK, CI, install   │
 └─────────┬──────────┘ └─────────┬──────────┘ └─────────┬──────────┘
           └──────────────────────┼───────────────────────┘
                                  ▼
                       ┌────────────────────┐
                       │   code-reviewer     │  (haiku) — только чтение
                       │  вердикт: APPROVED /│
                       │  CONDITIONS / CHANGES│
                       └────────────────────┘

Агент	Что делает	Модель
`architect-orchestrator`	Уточняет → проектирует → раскладывает в `docs/tasks/*.md` → делегирует → гоняет цикл разработчик↔ревьюер	opus
`shell-backend-developer`	Backend: ash/jq, генерация конфига sing-box, nft, dnsmasq, UCI. Прогоняет shellcheck + smoke	sonnet
`luci-frontend-developer`	Frontend: TS-исходник, LuCI-вьюхи, валидаторы, i18n. Прогоняет `yarn ci`, пересобирает `main.js`	sonnet
`packaging-ci-engineer`	Makefile, Docker ipk/apk, SDK, workflows, тест-харнесс, install.sh	sonnet
`code-reviewer`	Read-only ревью диффа против правил, пишет вердикт	haiku

Как запускать

Вариант A — команда `/task` (рекомендуется)

В OpenCode или Claude Code введи:

/task добавить опцию X в секцию UCI и пробросить её в конфиг sing-box

Оркестратор пройдёт весь цикл: уточнит → спроектирует → разложит → делегирует → прогонит шлюзы → ревью → отдаст тебе на коммит.

Вариант B — спека файлом

Создай docs/tasks/task-010-моя-задача.md (по шаблону TEMPLATE-task.md), затем:

/task обработай docs/tasks/task-010-моя-задача.md

Вариант C — обработать ревью

/review docs/tasks/task-010-моя-задача-review-001.md

или передай URL Pull Request.

Вариант D — описать PR

/describe

Жизненный цикл задачи (7 шагов)

Уточнение. Оркестратор задаёт вопросы по неоднозначным решениям (порты/marks/пути/схема конфига/упаковка). Не додумывает.
Проектирование. Предлагает 1–3 варианта с trade-offs, ждёт твоего «ОК».
Декомпозиция. Пишет спеки в docs/tasks/task-NNN-*.md.
Реализация. Делегирует нужному разработчику (параллельно — если подзадачи не пересекаются по файлам).
Шлюзы. Разработчик прогоняет соответствующий gate:
- backend → скилл shellcheck + скилл smoke-tests;
- frontend → скилл frontend-ci (yarn ci) + пересборка main.js без git-диффа;
- packaging → smoke-tests, проверка ipk и apk.
Ревью. code-reviewer пишет ревью-док с вердиктом. При REQUIRES CHANGES разработчик переделывает до прохождения.
Готово. Ты коммитишь вручную. PR — только после согласования в Telegram с авторами (CODEOWNERS=@yandexru45).

Память агентов

Файлы docs/agent-rules/memory/<agent>.md — это долгая память агентов: грабли, неочевидные правила, уже принятые решения, повторяющиеся находки ревью. Каждый агент читает свою память перед работой и дописывает туда новое. Память коммитится в git — поэтому она общая для всей команды и для обоих инструментов (OpenCode и Claude Code ссылаются на одни и те же файлы, дублей нет). Держи каждый файл памяти короче ~200 строк.

Ключевые правила (действуют для всех агентов)

Тесты/шлюзы обязательны. Изменение не «готово», пока не прошёл нужный gate.
Агенты не коммитят. Коммит и push делает только человек (права настроены на подтверждение git commit/git push).
Без апрува архитектора нет реализации. Каждое изменение проходит ревью.
Слои не смешиваются. UI → backend (через два разрешённых бинарника) → sing-box/nft/dnsmasq.
Священный runtime-контракт (порты/marks/пути) не меняется без проверки всей цепочки. Всё — в constants.sh, без хардкода.
Сгенерированный main.js руками не править. Только правка TS-исходника + yarn build.
jq на OpenWRT — без regex (нет Oniguruma).

Требования инструментов

OpenCode: конфиг подхватывается из opencode.json и AGENTS.md автоматически. После изменения конфигурации перезапусти OpenCode (конфиг читается один раз при старте).
Claude Code: для оркестрации субагентами включи экспериментальный режим agent teams в глобальном ~/.claude/settings.json:
```
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
```
Без этого флага запуск нескольких агентов работать не будет.
Шлюзы локально: для smoke-tests нужен Docker; для frontend-ci — Node 22
- yarn в fe-app-netshift; для shellcheck — локальный shellcheck или Docker-образ koalaman/shellcheck.

Траблшутинг

Агенты не запускаются (Claude Code): проверь флаг CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
OpenCode не стартует после правки конфига: значит, opencode.json невалиден. Запусти из папки проекта с OPENCODE_DISABLE_PROJECT_CONFIG=1, поправь файл, перезапусти без флага.
Пустое/слабое ревью: убедись, что есть незакоммиченный дифф (ревьюер смотрит git diff).
Память распухла: подрежь файл docs/agent-rules/memory/<agent>.md до ~200 строк, оставив только durable-знания.

12 KiB Raw Permalink Blame History Unescape Escape