Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add daveebbelaar/bama --skill improve-architecture -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

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

Copy the whole skill folder; for one project use .claude/skills/improve-architecture/

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.

improve-architecture Rohit Ghumare improve-architecture audits code structure, identifies tangles in boundaries and dependencies, and proposes a ranked list of minimal moves that relieve the strain—no rewrite, only a plan you approve first. CX Codex +1 ★ 2,966repo stars cmux-architecture manaflow-ai cmux-architecture guides modular Swift package architecture, strict 5-layer dependency inversion, and Swift 6 concurrency rules in the cmux codebase. CX Codex +1 5,100installs swift-architecture-skill efremidze swift-architecture-skill is a Claude Code skill that guides architecture choices for SwiftUI and UIKit code. It activates for feature design, implementation, refactoring, and reviews. CX Codex +1 2,100installs codebase-architecture mblode codebase-architecture designs TypeScript module structure, deepens shallow modules, and wires repository checks that keep the shape from decaying. CX Codex +1 593installs guarding-architecture riekelt guarding-architecture enforces system boundaries by turning structural invariants into breaking build tests. Useful when code crosses module limits or adds unwanted cross-package imports. CX Codex +1 25,600installs code-architecture-review omer-metin code-architecture-review evaluates codebase structure for module dependencies and coupling. Catches architectural problems before they turn into debt. CX Codex +1 270installs go-architecture-review eduardo-sl The go-architecture-review skill reviews Go package structure, dependency direction, and module boundaries. Use it to assess an existing codebase or plan a refactor. CX Codex +1 ★ 90repo stars

From the same set21

The whole set →
improve-loop improve-loop — a Claude Code skill that works through a macOS app’s stories in docs/STORIES.md. It builds the app, checks screen snapshots against references, and commits completed work. CX Codex +1 1,000installs agent-cli agent-cli — a skill for Claude Code, Codex and Cursor that adds a command line and MCP server to a macOS app so agents can control it via a local socket. CX Codex +1 1,000installs build-and-verify build-and-verify — a Claude Code skill that builds SwiftUI macOS apps and checks page snapshots in light and dark appearance. The agent invokes it after UI changes, failed builds, or requests to run or inspect the app. CX Codex +1 1,000installs performance performance — a skill for Claude Code that measures CPU, memory, and energy usage in macOS apps. It identifies causes of freezes and helps offload tasks from the main thread to the GPU. CX Codex +1 1,000installs app-brief The app-brief skill for Claude Code and Cursor generates a one-page docs/BRIEF.md file for a new macOS app before writing code. CX Codex +1 1,000installs design-from-app design-from-app — a Claude Code skill that rebuilds any app interface as a native SwiftUI design kit using reference screenshots. CX Codex +1 1,000installs os-integrations The os-integrations Claude Code skill maps macOS APIs to system-level features and their required permissions. It applies when adding global shortcuts, screen capture, or controls for other apps’ windows. CX Codex +1 1,000installs layout-grid layout-grid is a Claude Code skill that enforces grid and alignment rules in macOS SwiftUI apps. It runs when building custom UI components or after layout changes. CX Codex +1 1,000installs

Project sponsors

Companies that keep this analytics open