improve-architecture · daveebbelaar — Claude Code skill for Swift architecture
The improve-architecture Claude Code skill reviews a macOS Swift codebase and plans refactors that preserve existing behavior. It activates before a major feature, at a milestone, or when bugs keep returning in one area.
MIT 1,000 installs ★ 1,933 updated 2026-11-05
npx skills add daveebbelaar/bama --skill improve-architecture -a claude-codeWhat improve-architecture does
The skill finds parts of a codebase that have become difficult to change and proposes clearer module boundaries. It checks architecture documents and Git history, then writes a review with candidate problems, suggested interfaces, and a change plan. A Swift file over 600 lines is one trigger; at 1,000 lines, the skill says to act.
The review pauses for a choice. In an unattended loop, it proceeds only with the top recommendation if marked Strong. Refactoring is split into commits, with tests or other recorded checks used to compare behavior before and after. The project must build at each step. The process also updates ARCHITECTURE.md and records bugs found during refactoring in docs/FIXLOG.md.
What it helps with
- spot modules that make code harder to change
- trace recurring bugs to an area of the codebase
- plan architecture changes before a major feature
- break a refactor into commits with behavior checks
Example prompts for the agent
- Review the architecture before I add a major feature.
- Find Swift code that should be split into clearer modules.
- Plan a refactor for the area where bugs keep recurring.
How to install improve-architecture
1Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill improve-architecture -a claude-code2Manually: put the files in place
~/.claude/skills/improve-architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/improve-architecture/
1Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill improve-architecture -a codex2Manually: put the files in place
.agents/skills/improve-architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill improve-architecture -a cursor2Manually: put the files in place
.cursor/skills/improve-architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install daveebbelaar/bama skills/code/improve-architecture2Manually: put the files in place
.github/skills/improve-architecture/SKILL.md1Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill improve-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/daveebbelaar/bama --path skills/code/improve-architectureManually: put the files in place
.devin/skills/improve-architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add daveebbelaar/bama --skill improve-architecture -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about improve-architecture
How do I install improve-architecture in Claude Code?
Run npx skills add daveebbelaar/bama --skill improve-architecture -a claude-code. The skill file is installed at ~/.claude/skills/improve-architecture/SKILL.md.
What does improve-architecture do?
It reviews a macOS Swift app, identifies parts that may need clearer module boundaries, and lays out a refactor in small commits with checks for unchanged behavior.
What triggers an architecture review?
Triggers include reaching a milestone, preparing a major feature, a Swift file exceeding 600 lines, or recurring bugs in the same area.
Source text
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
Similar skills
All skills for Code review and refactoring →improve-architecture by other authors comes first.