Улучшение архитектуры кодовой базы

Ищет мелкие модули, которые стоит углубить, начиная с чаще всего меняющегося кода, показывает кандидатов в HTML-отчёте со схемами «до и после» и разбирает выбранный вместе с вами. Для случаев, когда код стало трудно тестировать и понимать.

РазработкаПак: Скиллы Мэтта Покока71 строкаimprove-codebase-architecture
Автор
Источник
mattpocock/skills/skills/engineering/improve-codebase-architecture @ abeeaf9
Лицензия
MIT · Copyright (c) 2026 Matt Pocock

Об этом скилле

Что делает

Скилл ищет, где код можно «углубить»: какие рефакторинги сведут мелкие модули в глубокие, чтобы код было легче тестировать, а агенту — в нём ориентироваться. Сначала он решает, где искать: в той части, которую назвали вы, а без подсказки — там, где код чаще всего менялся по git log. Затем читает GLOSSARY.md и ADR этой области. После этого субагент со свежим контекстом проходит по коду и отмечает места трения: одно понятие размазано по множеству мелких модулей, интерфейс почти так же сложен, как реализация, чистые функции вынесены ради тестов, а баги живут в том, как их вызывают, модули протекают через швы, код трудно тестировать. Подозрительное проверяется тестом на удаление.

Кандидаты попадают в самостоятельный HTML-отчёт во временной папке ОС — в репозиторий ничего не пишется, — и агент открывает его для вас. На карточке каждого: файлы, проблема, решение, выигрыш в терминах locality и leverage, схема «до и после» и метка Strong, Worth exploring или Speculative. Кандидат, который противоречит ADR, попадает в отчёт, только если решение стоит пересмотреть. После главной рекомендации агент спрашивает, что из этого разбирать; интерфейсы до этого он не предлагает.

Выбранный вариант агент разбирает с вами через скилл grilling, по ходу обновляет GLOSSARY.md через domain-modeling, предлагает ADR, если вы отклонили кандидата по причине, которая пригодится будущим ревью, а для альтернативных интерфейсов берёт design-it-twice из codebase-design.

HTML-REPORT.md описывает отчёт: каркас, раскладку карточки, пять видов схем и тон текста. agents/openai.yaml к тому же отключает неявный вызов в Codex.

Когда включать и когда не надо

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

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

Как поставить и вызвать

Команда установки ниже кладёт всю папку. Во frontmatter указано disable-model-invocation: true, поэтому сам агент его не запустит — только вы.

  • Claude Code: только командой /improve-codebase-architecture — если просто назвать скилл в сообщении, агент его не запустит.
  • Codex: $improve-codebase-architecture.
  • Cursor: наберите / в чате Agent и выберите improve-codebase-architecture.

Пример: /improve-codebase-architecture Начни с оформления заказа — оттуда пришла большая часть багов за квартал.

Поставьте вместе с ним codebase-design, grilling и domain-modeling: он вызывает все три. Отчёту нужен интернет: Tailwind и Mermaid он грузит из CDN.

Чем отличается от похожих

Безопасный рефакторинг из нашего каталога проводит уже выбранный рефакторинг мелкими шагами под тестами; этот скилл выбирает рефакторинг и останавливается. Упрощение кода делает работающий код понятнее, не меняя поведения, и по умолчанию только в недавно изменённом коде; здесь речь о том, как код нарезан на модули. Карта незнакомого репозитория описывает устройство репозитория и ничего не предлагает.

Установка

Выполните одну команду — она сохранит SKILL.md и файлы, которые он использует, в папку скиллов агента. Claude Code и Codex подхватывают новый скилл без перезапуска; если скилл не появился, перезапустите агента.

Скилл написан на английском — агент поймёт его и ответит вам по-русски.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/improve-codebase-architecture/SKILL.md https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/SKILL.md -o ~/.claude/skills/improve-codebase-architecture/HTML-REPORT.md https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/HTML-REPORT.md -o ~/.claude/skills/improve-codebase-architecture/LICENSE https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/LICENSE -o ~/.claude/skills/improve-codebase-architecture/agents/openai.yaml https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/agents/openai.yaml
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/improve-codebase-architecture/SKILL.md https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/SKILL.md -o ~/.agents/skills/improve-codebase-architecture/HTML-REPORT.md https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/HTML-REPORT.md -o ~/.agents/skills/improve-codebase-architecture/LICENSE https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/LICENSE -o ~/.agents/skills/improve-codebase-architecture/agents/openai.yaml https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/agents/openai.yaml
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','HTML-REPORT.md','LICENSE','agents/openai.yaml') { $p = Join-Path "$HOME\.claude\skills\improve-codebase-architecture" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','HTML-REPORT.md','LICENSE','agents/openai.yaml') { $p = Join-Path "$HOME\.agents\skills\improve-codebase-architecture" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/$f" -UseBasicParsing -OutFile $p }

Другой агент: сохраните файл в его папку скиллов или дайте ему ссылку на файл: https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/SKILL.md

SKILL.md

Исходник

Improve Codebase Architecture

Surface architectural friction and propose deepening opportunities: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

This command is informed by the project's domain model and built on a shared design vocabulary:

  • Call the Skill tool with "codebase-design" for the architecture vocabulary (module, interface, depth, seam, adapter, leverage, locality) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary."
  • The domain language in GLOSSARY.md gives names to good seams; ADRs in docs/adr/ record decisions this command should not re-litigate.

Process

1. Explore

Scope before you scan: YAGNI. Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide where to look before you look:

  • If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
  • Otherwise, walk back a good stretch of the commit history (git log --oneline) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.

Read the project's domain glossary (GLOSSARY.md) and any ADRs in the area you're touching first.

Then spawn a sub-agent with a fresh context window to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:

  • Where does understanding one concept require bouncing between many small modules?
  • Where are modules shallow, with an interface nearly as complex as the implementation?
  • Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no locality)?
  • Where do tightly-coupled modules leak across their seams?
  • Which parts of the codebase are untested, or hard to test through their current interface?

Apply the deletion test to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.

2. Present candidates as an HTML report

Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from $TMPDIR, falling back to /tmp (or %TEMP% on Windows), and write to <tmpdir>/architecture-review-<timestamp>.html so each run gets a fresh file. Open it for the user (xdg-open <path> on Linux, open <path> on macOS, start <path> on Windows) and tell them the absolute path.

The report uses Tailwind via CDN for layout and styling, and Mermaid via CDN for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals: use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a before/after visualisation. Be visual.

For each candidate, render a card with:

  • Files: which files/modules are involved
  • Problem: why the current architecture is causing friction
  • Solution: plain English description of what would change
  • Benefits: explained in terms of locality and leverage, and how tests would improve
  • Before / After diagram: side-by-side, custom-drawn, illustrating the shallowness and the deepening
  • Recommendation strength: one of Strong, Worth exploring, Speculative, rendered as a badge

End the report with a Top recommendation section: which candidate you'd tackle first and why.

Use GLOSSARY.md vocabulary for the domain, and the /codebase-design vocabulary for the architecture. If GLOSSARY.md defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."

ADR conflicts: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: "contradicts ADR-0007, but worth reopening because…"). Don't list every theoretical refactor an ADR forbids.

See HTML-REPORT.md for the full HTML scaffold, diagram patterns, and styling guidance.

Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"

3. Grilling loop

Once the user picks a candidate, call the Skill tool with "grilling" to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.

Side effects happen inline as decisions crystallize; call the Skill tool with "domain-modeling" to keep the domain model current as you go:

  • Naming a deepened module after a concept not in GLOSSARY.md? Add the term to GLOSSARY.md. Create the file lazily if it doesn't exist.
  • Sharpening a fuzzy term during the conversation? Update GLOSSARY.md right there.
  • User rejects the candidate with a load-bearing reason? Offer an ADR, framed as: "Want me to record this as an ADR so future architecture reviews don't re-suggest it?" Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing; skip ephemeral reasons ("not worth it right now") and self-evident ones.
  • Want to explore alternative interfaces for the deepened module? Call the Skill tool with "codebase-design" and use its design-it-twice parallel sub-agent pattern.

Подключить через AnyModel API

Скилл работает на той модели, которую использует агент. Подключите Claude Code, Codex или Cursor к AnyModel и запускайте его на Claude, GPT, Gemini и других моделях по одному ключу — оплата за токены, без подписки.

Ещё из пака Скиллы Мэтта Покока

Ревью по стандартам и спецификации

Проверяет дифф от коммита, ветки или тега по двум осям в параллельных субагентах: записанные стандарты репозитория с базовым набором запахов кода по Фаулеру и исходная спецификация. Для случаев, когда ветку или PR надо сверить с задачей.

Проектирование глубоких модулей

Задаёт общий словарь для глубоких модулей — интерфейс, шов, адаптер, глубина — с тестом на удаление, видами зависимостей и проектированием в нескольких вариантах через субагентов. Для случаев, когда нужно придумать интерфейс модуля или место шва.

Диагностика сложных багов

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

Модель предметной области

Уточняет язык предметной области по ходу проектирования: оспаривает размытые и противоречивые термины, сразу пишет согласованные в GLOSSARY.md и предлагает короткий ADR лишь для трудно обратимых решений. Для случаев, когда обсуждают термины или пишут ADR.

Реализация спецификации по тикетам

Реализует спецификацию и её тикеты на одной интеграционной ветке: по свежему субагенту-исполнителю на тикет в своём worktree, параллельно по графу блокировок, затем ревью и один проход исправлений. Для случаев, когда тикеты из to-tickets уже готовы.

Прототип на выброс

Пишет прототип на выброс под один вопрос о дизайне: кликабельное HTML-демо модели состояний в одном файле или несколько разных вариантов интерфейса на одном маршруте с переключением через URL. Для случаев, когда нужно проверить логику или облик страницы.

Ретро сессии с агентом

Разбирает прошедшую сессию агента по логам и предлагает, что поменять в окружении: указатели в CLAUDE.md, правила линтера, pre-commit и CI, стандарты для ревью, вызовы инструментов. Для случаев, когда агент долго искал нужное или ошибался.

TDD с интеграционными тестами

Ведёт разработку через тесты на публичных интерфейсах: согласует с пользователем швы для тестов, делает по одному циклу red-green на тест, мокает только границы системы, рефакторинг оставляет ревью. Для случаев, когда фичу или баг делают тестами вперёд.

Спецификация из разговора

Собирает из текущего разговора и кода спецификацию с пользовательскими историями, решениями по реализации и тестам и публикует её в трекер с меткой ready-for-agent, без расспросов. Для случаев, когда фичу уже обсудили и её пора записать.

Разбивка спецификации на тикеты

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

Триаж задач и PR

Разбирает входящие задачи и внешние PR в трекере: ставит категорию и состояние, ищет готовый код и прошлые отказы, воспроизводит баги и пишет бриф для агента. Для случаев, когда мейнтейнер разгребает поток задач и PR.

Карта для большой работы

Раскладывает работу, которая не влезает в одну сессию агента, в карту в трекере с дочерними тикетами-решениями и закрывает по тикету за сессию, пока путь к цели не прояснится. Для случаев, когда большая задача упирается в нерешённые вопросы.

Bash-мастер для ручных шагов

Пишет интерактивный bash-скрипт, который ведёт человека по ручным шагам: открывает нужные страницы, принимает ключи и пишет их в .env и секреты GitHub. Для случаев, когда настройка сервисов или миграция требует действий, которые агент сам не сделает.

Защита от опасных git-команд в Claude Code

Ставит в Claude Code хук PreToolUse, который останавливает типовые формы git push, reset --hard, clean -f, branch -D и отката всего дерева, для одного проекта или для всех, и проверяет его. Для случаев, когда нужна страховка от того, что агент сам запушит или сотрёт работу.

Перевод тестов на shoehorn

Заменяет as и as unknown as в тестах на TypeScript на fromPartial и fromAny из @total-typescript/shoehorn, добавляет импорты и запускает проверку типов. Для случаев, когда тесты собирают объекты целиком или обманывают компилятор приведениями.

Настройка pre-commit хуков

Ставит Husky и lint-staged в Node-репозиторий: каждый коммит прогоняет Prettier по staged-файлам, проверку типов и тесты; учитывает менеджер пакетов и делает первый коммит через хук. Для случаев, когда в репозитории нет проверок при коммите.

Допрос плана

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

Обучение новой теме

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

Опросник для решения

Составляет Markdown-опросник для человека, у которого есть нужные знания, спросив только, кому он и какие ответы нужны; важные вопросы идут первыми. Для случаев, когда решение упирается в факты от другого человека.

Тексты для агентов: скиллы и AGENTS.md

Даёт правила для текстов, которые читает агент: описание скилла как указатель, что держать в файле и что выносить, критерии готовности, опорные слова и чистка. Для случаев, когда пишете или правите скилл, AGENTS.md или CLAUDE.md.