improve-architecture · daveebbelaar — скилл для Claude Code: архитектура Swift
Скилл improve-architecture для Claude Code разбирает архитектуру macOS-приложения на Swift и планирует безопасный рефакторинг. Срабатывает перед крупной функцией, в конце этапа или при повторяющихся проблемах в одной области.
MIT 1 000 установок ★ 1 933 обновлён 2026-11-05
npx skills add daveebbelaar/bama --skill improve-architecture -a claude-codeЧто делает improve-architecture
Скилл ищет места, где код становится труднее менять, и предлагает разделить их на модули с понятными интерфейсами. Сначала он изучает архитектурные документы и историю Git, затем формирует обзор с проблемами, предложениями и планом изменений. Для Swift-файла сигналом служат 600 строк; при 1 000 строках нужно действовать.
После обзора скилл останавливается и просит выбрать вариант. В автономном цикле он берёт только верхнюю рекомендацию с оценкой Strong. Рефакторинг идёт отдельными коммитами: тесты и другие проверки фиксируют прежнее поведение, а проект должен собираться после каждого шага. Изменения фиксируются в ARCHITECTURE.md, а найденные при рефакторинге баги — в docs/FIXLOG.md.
Какие задачи решает
- найти модули, которые мешают менять код
- разобрать причины повторяющихся багов в одной области
- спланировать рефакторинг перед крупной функцией
- разделить изменения на коммиты с проверкой прежнего поведения
Примеры запросов агенту
- Проведи архитектурный разбор перед добавлением крупной функции.
- Проверь, какие части Swift-кода пора разделить на модули.
- Спланируй рефакторинг после повторяющихся багов в одной области.
Как установить improve-architecture
1Через Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill improve-architecture -a claude-code2Вручную: положить файлы
~/.claude/skills/improve-architecture/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/improve-architecture/
1Через Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill improve-architecture -a codex2Вручную: положить файлы
.agents/skills/improve-architecture/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill improve-architecture -a cursor2Вручную: положить файлы
.cursor/skills/improve-architecture/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install daveebbelaar/bama skills/code/improve-architecture2Вручную: положить файлы
.github/skills/improve-architecture/SKILL.md1Через Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill improve-architecture -a gemini-cli2Командой платформы
gemini skills install https://github.com/daveebbelaar/bama --path skills/code/improve-architectureВручную: положить файлы
.devin/skills/improve-architecture/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill improve-architecture -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы об improve-architecture
Как установить improve-architecture в Claude Code?
Выполни npx skills add daveebbelaar/bama --skill improve-architecture -a claude-code. Файл скилла устанавливается по пути ~/.claude/skills/improve-architecture/SKILL.md.
Что делает improve-architecture?
Он анализирует структуру macOS-приложения на Swift, предлагает кандидатов на разделение и помогает проводить рефакторинг небольшими коммитами с проверкой поведения.
Когда скилл предлагает проверить архитектуру?
Среди сигналов — конец этапа, подготовка крупной функции, Swift-файл длиннее 600 строк и повторяющиеся баги в одной области.
Исходный текст
SKILL.md · MIT
---
name: improve-architecture
description: Architecture check-in for a growing macOS Swift codebase. Finds hot spots, proposes deeper modules, and refactors one step per commit with behavior proven unchanged. Use at the end of a milestone, before a big feature, when a file passes 600 lines, when one feature touches many files, when bugs repeat in one area, or when the user asks to refactor or clean up the code.
---
# Improve architecture
Features pile up, and an app that was easy to change gets hard to change.
A **check-in** catches that early: survey, propose, let the user pick, then
refactor in small steps that keep behavior the same. The target shape for
apps that grow is in [architecture.md](architecture.md).
## When to run
Any one signal is enough:
- The end of a milestone (the `improve-loop` skill calls this skill there).
- Before a big feature. Ask: "What change to the code would make this
feature easy?"
- A Swift file over 600 lines (act at 1,000), a type over 400 lines, or
"unable to type-check this expression".
- One feature touched more than 6 files or more than 2 targets.
- The same area shows up in 3 fix-log entries, or the same kind of bug
happens twice.
- State that changes more than 10 times a second sits on a model that many
views observe.
- A dependency cannot be replaced in a test.
## Vocabulary
Use these words exactly, so proposals stay comparable:
- **Module**: anything with an interface and an implementation (a type, a
file group, a target).
- **Interface**: everything a caller must know: signatures, ordering,
error modes, threading, performance.
- **Depth**: how much a module does per unit of interface. Deep modules hide
a lot behind a small interface. Shallow modules are pass-throughs.
- **Seam**: a place where you can swap behavior without editing callers.
- **Adapter**: one implementation behind a seam. One adapter is a
hypothetical seam. Two (production and test) make it real.
- **Locality**: a change touches one place. **Leverage**: callers get a lot
for little.
## 1. Survey
Change no code in this step.
1. Read `CLAUDE.md`, `ARCHITECTURE.md`, `docs/adr/`, and `docs/FIXLOG.md`
where they exist.
2. Find hot spots:
```bash
git log --since=30.days --name-only --format= | sort | uniq -c | sort -rn | head -20
find Sources -name '*.swift' | xargs wc -l | sort -n | tail -20
```
3. Map the structure: targets and their dependencies, protocols and their
conformers, `@MainActor` types that do I/O, and what runs on which
queue.
4. Look for Swift friction:
- A view model that owns everything (a god model).
- Wrappers that only forward calls.
- App code that reaches into a library's internals.
- Test hooks in the app target.
- Fast-changing state published to every view.
- Slow work on the main thread or a real-time queue.
- Protocols with one conformer and no test adapter.
- Drifted copies: the same `private struct <Name>` defined in two files
(`grep -rn 'private struct' Sources/ | awk '{print $3}' | sort | uniq -d`).
- A settings or detail page that lives far from its feature. Pages live
in the feature's folder.
- Pure logic inside a `@MainActor` store, which tests cannot compile
alone. Move it into a plain type that takes plain values.
5. **Deletion test** for each candidate: if you deleted this module, would
its complexity concentrate in one place (keep it) or spread to every
caller (it earns its place)? Pass-throughs fail the test.
## 2. Propose
Write `docs/architecture-review-<YYYY-MM-DD>.md`, one card per candidate:
```markdown
## <Title in domain nouns> [Strong | Worth exploring | Speculative]
Files: Sources/App/EditorModel.swift (1,750 lines), ...
Signal: <which trigger above>
Problem: <what is hard to change today, with one example>
Proposal: <the new module and its interface, 15 lines of Swift at most>
Benefits: <locality and leverage; which tests get simpler>
Proof of same behavior: <tests, golden files, snapshots, perf baseline>
Plan: <one commit per step>
```
End with a **top recommendation** and a short "considered, not
recommended" list. Saying "the code is fine" is a valid result: then
every card is `Speculative` or there are none.
Stop and ask the user which candidate to do. In an unattended loop, do the
top recommendation only if it is `Strong`. Leave the rest in the file.
## 3. Refactor
- **Before:** record the proof: tests at the interface, golden outputs
(file bytes or hashes, snapshot PNGs, old files that must still load),
and a performance baseline where speed matters.
- One refactor per commit. Behavior stays the same. No features mixed in.
- New types go in new files that compile first. Then move callers over.
The project builds after every step.
- Replacing an engine: keep the old path behind a flag for one milestone,
then delete it.
- Replace tests, do not layer them: delete the old shallow tests that the
new interface tests cover.
- If a diff passes about 10 files, split it.
- If the interface is open, design it twice: sketch two or three
interfaces under different constraints (fewest entry points, simplest
common caller, ports and adapters) and pick one with a reason.
## 4. Record
- Update `ARCHITECTURE.md`: targets, layers, dependency direction, seams.
- Add an ADR in `docs/adr/` only when the decision is hard to reverse,
surprising without context, and a real trade-off.
- Add a `docs/FIXLOG.md` entry for any bug the refactor found. Every entry
ends with a `Rule:` line.
Done when the review file exists, the chosen refactor is committed in
steps, the proof gives the same results before and after, and
`ARCHITECTURE.md` matches the code.
© daveebbelaar · MIT · daveebbelaar/bama
Похожие скиллы
Все скиллы по теме «Код-ревью и рефакторинг» →Сначала — improve-architecture от других авторов.