К основному содержанию
скилл CX Codex

improve-architecture · daveebbelaar — скилл для Claude Code: архитектура Swift

Скилл improve-architecture для Claude Code разбирает архитектуру macOS-приложения на Swift и планирует безопасный рефакторинг. Срабатывает перед крупной функцией, в конце этапа или при повторяющихся проблемах в одной области.

MIT 1 000 установок ★ 1 933 обновлён 2026-11-05

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add daveebbelaar/bama --skill improve-architecture -a claude-code
Открыть на GitHub

Что делает 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-code

2Вручную: положить файлы

~/.claude/skills/improve-architecture/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/improve-architecture/

По шагам, с командами для каждой платформы: Как установить скилл в 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 от других авторов.

improve-architecture Rohit Ghumare Скилл improve-architecture диагностирует проблемы архитектуры кода — запутанные границы, дублирование, неправильные швы — и предлагает приоритизированный план минимальных изменений без переписи. CX Codex +1 ★ 2 966звёзд репо cmux-architecture manaflow-ai Скилл cmux-architecture задаёт правила разделения кода cmux на пакеты Swift, инверсии зависимостей и многопоточности Swift 6. Помогает переносить модули без циклических связей. CX Codex +1 5 100установок swift-architecture-skill efremidze Скилл swift-architecture-skill для Claude Code помогает выбрать и применить архитектуру для SwiftUI- или UIKit-кода. Он включается при проектировании, рефакторинге и ревью функций и модулей. CX Codex +1 2 100установок codebase-architecture mblode Скилл codebase-architecture проектирует структуру TypeScript-кода, укрупняет мелкие модули и ставит проверки, которые держат репозиторий в форме. CX Codex +1 593установок guarding-architecture riekelt Скилл guarding-architecture защищает архитектурные границы проекта и превращает правила в автоматические тесты сборки. Пригодится при сквозных правках модулей или случайных импортах. CX Codex +1 25 600установок code-architecture-review omer-metin Скилл code-architecture-review проверяет структуру кодовой базы на зависимости и связность модулей. Помогает поймать проблемы до того, как они станут техдолгом. CX Codex +1 270установок go-architecture-review eduardo-sl Скилл go-architecture-review для Claude Code проверяет структуру пакетов, направление зависимостей и границы модулей в Go-проекте. Проводит ревью архитектуры или составляет план рефакторинга. CX Codex +1 ★ 90звёзд репо

Из того же набора21

Весь набор →
improve-loop Скилл improve-loop для Claude Code ведёт разработку macOS-приложения по историям из docs/STORIES.md. Он собирает приложение, сравнивает снимки экранов с образцами и фиксирует готовые истории в Git. CX Codex +1 1 000установок agent-cli Скилл agent-cli для Claude Code, Codex и Cursor добавляет командную строку и MCP-сервер к macOS-приложению, чтобы ИИ управлял им через локальный сокет. CX Codex +1 1 000установок build-and-verify Скилл build-and-verify для Claude Code собирает SwiftUI-приложение для macOS и проверяет снимки страниц в двух темах. Агент запускает его после изменений интерфейса, ошибок сборки или просьбы проверить приложение. CX Codex +1 1 000установок performance Скилл performance для Claude Code, который измеряет нагрузку на CPU, память и энергию в macOS-приложениях. Помогает находить причины зависаний и переносить вычисления с основного потока на GPU. CX Codex +1 1 000установок app-brief Скилл app-brief для Claude Code и Cursor создаёт одностраничный файл docs/BRIEF.md для нового приложения под macOS до написания кода. CX Codex +1 1 000установок design-from-app Скилл design-from-app для Claude Code воссоздает дизайн любого приложения в виде нативной дизайн-системы SwiftUI по скриншотам. CX Codex +1 1 000установок os-integrations Скилл os-integrations для Claude Code помогает выбрать API macOS и нужные разрешения для системных функций приложения. Включается при добавлении глобальных горячих клавиш, захвата экрана или управления окнами других приложений. CX Codex +1 1 000установок layout-grid Скилл layout-grid для Claude Code проверяет сетку и выравнивание в приложениях macOS SwiftUI. Запускается при создании кастомных экранов, карточек, форм и после изменения вёрстки. CX Codex +1 1 000установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой