Скилл для агента
Связанность считается до того, как написан код
arch-balance — скилл для Claude Code, Codex, Qwen Code и Cursor. Когда агент собирается пересечь границу модуля или сервиса, он размечает каждую зависимость по трём осям, считает вердикт и оставляет в репозитории документ решения — с таблицей, схемой и триггерами пересмотра.
v0.1.0 · MIT · 30 КБ · инструкции по-английски, отчёт — на языке диалога
Три оси
Не вкус, а процедура
Обычное архитектурное ревью — это мнение, с которым можно спорить только в целом. Здесь у каждого ребра есть три числа, и спорить можно с конкретным. Модель — Влад Хононов, «Balancing Coupling in Software Design».
Сила
Что именно потребитель теперь обязан знать о поставщике
- 1 — контракт, спроектированный от нужд потребителя
- 3 — наружу торчит внутренняя модель
- 8 — переплетённая бизнес-логика: порядок, транзакция, инвариант
- 9 — одно правило, реализованное дважды
- 10 — приватные внутренности: чужие таблицы, внутренняя шина
Дистанция
Сколько стоит провести изменение через обе стороны
- 1 — методы одного объекта
- 3–7 — модули одного развёртываемого куска
- 9 — сервисы распределённой системы
- 10 — системы разных вендоров
- поправки: чужая команда — дальше, синхронный вызов — ближе
Волатильность
Как часто меняется именно разделяемое знание
- 1 — заморожено: легаси, которое не развивают
- 3 — поддерживающий или generic-поддомен
- 10 — ядро: там, где бизнес конкурирует
- оценка по git-истории тех файлов, где живёт знание
- плюс наведённая: стабильный модуль на сильной связи с ядром — тоже ядро
баланс =
max(|сила − дистанция|, 10 − волатильность) + 1
8–10 — оставить как есть · 4–7 — записать триггер · 1–3 — менять сейчас
Что получается
«Доставке нужна итоговая сумма заказа со скидкой»
Одна фраза в чате. Агент находит два ребра, которых нет ни в одном импорте: Доставка читает таблицу Заказов, а правило скидки живёт сразу в двух сервисах и обязано меняться одновременно. Ни то ни другое не найдёт ни один анализатор зависимостей.
Оба ребра пунктирные: ни одно из них не видно ни в импортах, ни в графе зависимостей.
| Ребро | Сила | Дист. | Волат. | Баланс |
|---|---|---|---|---|
| Доставка → Заказы, чтение таблицыглобальная сложность | 10 · интрузивная | 9 · сервисы | 10 · ядро | ○ 2 |
| Доставка ↔ Цены, дубль правилаглобальная сложность | 9 · симметричная | 10 · разные команды | 10 · ядро | ○ 2 |
| Доставка ← Заказы, контрактсбалансировано | 1 · контрактная | 9 · сервисы | 10 · ядро | ● 9 |
Работа архитектора — превращать пунктир в сплошные линии.
Дальше скилл пишет docs/decisions/0007-….md — с этой таблицей, схемами, отвергнутыми альтернативами и триггерами пересмотра: наблюдаемыми событиями, при которых решение надо пересчитать. Решение без триггеров тихо протухает.
Установка
Распаковать и положить
Никакого сервера и рантайма: это папка с инструкциями. В архиве — сам скилл, слэш-команда и метаданные плагина, полная инструкция внутри в INSTALL.md.
Claude Code — плагином
Даёт и скилл, и команду /arch-design для явного вызова.
/plugin marketplace add ./arch-balance
/plugin install arch-balance@clearnClaude Code — просто скиллом
Если плагины ни к чему. Для одного проекта — в .claude/skills внутри репозитория.
cp -r arch-balance/skills/arch-balance ~/.claude/skills/Codex, Qwen Code, Gemini CLI
Положить папку в репозиторий и описать в AGENTS.md, когда её читать. Условие важнее пути: без явного «когда» агент либо не откроет файл никогда, либо будет открывать на каждый рефакторинг переменной.
# AGENTS.md
Прежде чем писать код для изменения, которое
пересекает границу модуля или сервиса, прочитай
.agents/skills/arch-balance/SKILL.md и выполни
описанную там процедуру целиком.Cursor
Содержимое SKILL.md с frontmatter, references — рядом.
cp -r arch-balance/skills/arch-balance/. .cursor/rules/arch-balance/Проверить, что работает
Дайте агенту задачу, которая пересекает границу, не называя скилл: «нужно, чтобы доставка знала итоговую сумму заказа со скидкой». Скилл должен сработать сам и оставить документ решения. Обратная проверка: на «переименуй переменную в этом файле» он срабатывать не должен.
Откуда модель
Дистиллят двух книг, а не их пересказ
Ядро — «Balancing Coupling in Software Design» Влада Хононова: сила интеграции, дистанция, волатильность и уравнение баланса. Слой про данные — «Designing Data-Intensive Applications, 2nd ed.» Клеппмана и Риккомини: нефункциональные требования, модель, эволюция схемы, sync против async. Эволюция схемы — это шов между двумя книгами: совместимость вперёд и назад есть та же связанность, только во времени.
Этому же учит курс «Архитектор поневоле» — модель связанности разбирается в модулях 11–13 на живой системе, с решениями и последствиями. Бесплатно и без регистрации.