Архитектурный отчёт

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

Цель углубления — тестируемость и проходимость кода для агента: чтобы следующая сессия понимала кусок за один Read, а тест цеплялся за один интерфейс.

Основано на improve-codebase-architecture Мэтта Покока (mattpocock/skills, MIT). Отличия под этот стек: русский язык, ноль внешних CDN, продолжение через oprosi-menya вместо grilling.

Словарь

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

• Модуль — единица, у которой есть внутренность и то, чем она наружу торчит.
• Интерфейс — то, что модуль показывает наружу. Он же поверхность тестирования: тест цепляется за интерфейс, не за внутренности.
• Глубина — отношение сложности внутренности к сложности интерфейса. Глубокий модуль прячет много за простым входом. Мелкий — интерфейс почти такой же сложный, как то, что он прячет; такой модуль не платит за своё существование.
• Шов — место, где кодовую базу можно разрезать и подставить другое: тест, заглушку, второй источник данных. Чем меньше швов, тем лучше; идеал — один.
• Адаптер — то, что стоит на шве и переводит наружное во внутреннее. Один адаптер — шов гипотетический, два — настоящий.
• Рычаг — сколько будущих правок облегчает эта переделка.
• Локальность — держится ли поведение в одном месте. Чистая функция, выделенная ради тестируемости, локальность обычно ломает: баги переезжают в то, как её зовут, и тест их больше не видит.
• Тест удалением — удалить модуль: сложность соберётся в одном месте или просто расползётся по вызывающим? «Соберётся» — это кандидат.

Шаг 1. Область

Углубление окупается там, где код продолжает меняться, — поэтому область выбирается до сканирования.

• Пользователь назвал направление (модуль, подсистему, боль) — берёшь его и пропускаешь остальное.
• Не назвал — git log --oneline -200 и git log --name-only --since="3 months ago" | sort | uniq -c | sort -rn | head -30: горячие точки притягивают внимание первыми. Правки разбросаны без горячих точек — расширяй сеть.
• Входной файл проекта (CLAUDE.md в корне) и его раздел граблей читаются до кода: там лежит то, что из кода не выводится.

Готово, когда: выписан список путей — до 15 файлов и папок, у каждого причина попадания.

Шаг 2. Разведка

Читаешь код и отмечаешь трение. Жёсткого чек-листа нет, ищешь органически:

• Понимание одного понятия требует прыжков между десятком мелких модулей.
• Интерфейс модуля почти такой же сложный, как его реализация.
• Чистые функции выделены ради тестируемости, а настоящие баги живут в том, как их вызывают.
• Тесно связанные модули протекают через шов: один знает про внутренности другого.
• Кусок не покрыт тестами или не тестируется через нынешний интерфейс.

Каждое подозрение проходит тест удалением — без него кандидат в отчёт не идёт.

Готово, когда: 3–7 кандидатов, и у каждого есть все пять полей — файлы, трение, что меняется, выигрыш, сила рекомендации (Уверенно / Стоит обсудить / Догадка).

Шаг 3. Отчёт

Пишешь один HTML-файл в scratchpad-папку сессии (не в репозиторий проекта — там ему не место), именем arch-report-<проект>-<ГГГГММДД-ЧЧММ>.html. Открываешь через start <путь> и называешь пользователю абсолютный путь.

Скаффолд, карточка кандидата, паттерны диаграмм и стиль — REPORT.md рядом с этим файлом. Читать перед тем, как писать HTML.

Готово, когда: файл открылся в браузере, каждый кандидат несёт собственную диаграмму «было / стало», и в конце стоит раздел «С чего начать» с одним кандидатом и обоснованием.

Шаг 4. Что дальше

Интерфейсы в отчёте не проектируются — отчёт показывает, что углублять, а не как. Файл открыт → спроси, какого кандидата разбираем, и веди разбор по ~/.claude/skills/oprosi-menya/SKILL.md: ограничения, зависимости, форма углублённого модуля, что остаётся за швом, какие тесты выживают.

Пользователь отклонил кандидата с весомой причиной — запиши причину в CLAUDE.md проекта, чтобы следующий прогон не предложил то же самое. Причины на сегодня («сейчас не до этого») не записываются.

Грабли

• Интернета у отчёта нет. Ни Tailwind, ни Mermaid, ни шрифтов с CDN: стили инлайном, диаграммы — руками написанный SVG, шрифты системные. Файл должен открываться без интернета — и на ноутбуке, и на сервере.
• Диаграмма несёт вес, а не проза. Нужен абзац, чтобы понять картинку, — перерисовывай картинку.
• Отчёт по-русски, включая подписи на диаграммах. Имена файлов, функций и модулей — как в коде.
• Проект на Python, Node, Astro или чистом HTML — словарь один и тот же. Слова «класс» и «сервис» не тянуть из чужого языка.