code-design

Files (3)

• SKILL.md
• design-moves.md · references/
• principles.md · references/

SKILL.md (first lines)

# code-design

Write new code in a shape that a reader can follow and a maintainer can change — by deciding
*where* each piece of behaviour lives before writing it, and tightening the result after it works.

## Contract

- **Input:** a change to production code — a feature, an extension, a behaviour change — plus the
  codebase it lands in. Also works as a rule set loaded by another workflow (see
  [Inside another workflow](#inside-another-workflow)).
- **Output:** the code change with its tests, and a **Design notes** block in the final reply (or
  in the calling workflow's report).
- **Not in scope:** restructuring code the change does not touch (that is the `refactor` skill),
  bug fixes that ride along, performance tuning, style-only reformatting.
- **Never commits.** The user reviews the diff and decides what enters history.

**Explicit invocation.** This skill starts only when it was named — `/code-design`,
`/cc-ai-dev:code-design`, "code-design" in the prompt, or a load by name from another skill or a
skill selection the user confirmed. "Write clean code" or "follow SOLID" in a request is not an
invocation; such a request is handled as an ordinary request without this skill.

## Why this skill exists

An agent extending a codebase feels a strong pull toward the nearest existing class: it is already
imported, already registered, already tested, and adding a method there produces the smallest diff.
Each single step looks harmless. Repeated over twenty changes, it produces the service with 1,500
lines and twelve dependencies that nobody dares to touch.

The smallest diff is not the smallest design. The cost of "just add it here" is paid later, by
every reader of the class and by every test that has to construct all of its dependencies to check
one of its behaviours. This skill moves the decision to the moment it is cheapest: before the first
line is written.

The opposite failure is just as real. An agent told "use SOLID" tends to put an interface in front
of every class, a factory in front of every constructor, and a strategy in front of every `if`.
Indirection that does not pay for itself is also complexity. So the principles here come in pairs
that pull against each other, and the workflow ends with a check against the brakes.

## The principles, and how they pull

Operational definitions — signals, actions, counter-indications — are in
[`references/principles.md`](references/principles.md). The short version:

| Decompose when … | … but stop when |
|---|---|
| **Single Responsibility** — a unit changes for one reason | **KISS** — a split that forces the reader through more files than it saves in understanding |
| **Separation of Concerns** — domain rules, I/O, orchestration, and presentation live apart | **YAGNI** — an abstraction exists for a variation nobody has asked for |
| **DRY** — one piece of *knowledge* has one home | **Coincidental similarity** — two blocks look alike but change for different reasons |
| **Extract Interface / Dependency Inversion** — at a real seam (external system, test double for I/O, plug-in point) | **Speculative Generality** — one implementation and no second caller |
| **Extract Method / Class** — a unit does several things at several levels of abstraction | **Middle Man** — the extracted unit only forwards |

A decision cites a principle from the left column *and* has checked the right one.

## Workflow

```
Step 1  Read the neighbourhood     — the units the change would touch, their size, responsibilities, seams
Step 2  Design pass                — per new responsibility: extend, reuse, or new unit; state the sketch
Step 3  Build it                   — tests first where the project has tests; the shape from Step 2
Step 4  Refactor pass              — after green, on touched code only; one move at a time, tests after each
Step 5  Counter-check              — every abstraction pays rent, or it goes
Step 6  Design notes               — decisions, rejected alternatives, what was left alone
```

### Step 1 — Read the neighbourhood

Before designing, look at the code the change would naturally land in, and at its surroundings:

- **The candidate host(s):** the class, module, or file you would extend by default. Its size, its
  public members grouped by what they do, its dependencies (constructor parameters, imports, module
  globals). A host whose members fall into several unrelated groups already has several
  responsibilities — adding one more makes the eventual split harder, not easier.
- **The project's architecture pattern:** layering, vertical slices, handlers, services and
  repositories, feature folders. Read two or three sibling features. The pattern decides *where*
  things go; the principles decide *how finely* to cut inside it.
- **Existing units that already do part of the job:** helpers, value objects, validators,
  formatters, clients. Search by the nouns and verbs of the requirement. Re-implementing an
  existing helper is the most common DRY violation an agent produces.
- **Seams:** where external systems are called (HTTP, database, file system, clock, randomness,
  message bus) and whether they are already behind an abstraction the tests replace.
- **Test coverage of the host:** which paths of the code you will change or move have tests —
  quote the test per path, and list the paths without one. Step 2 closes those gaps before
  anything is moved.

Keep this short — enough to make the Step-2 decisions with evidence (`file:line`), no more.

### Step 2 — Design pass

**List the responsibilities the change adds**, one line each, before thinking about files. "Add
discount codes" is not one responsibility; it is *parse and validate a code*, *look up a code*,
*compute the discount*, *apply it to an order*, *record the redemption*. The list is what makes
placement decidable.

**Place each responsibility** by asking in order, and stop at the first yes:

1. **Does a unit already exist whose job this is?** Reuse it, extend it inside its responsibility,
   or generalise it if the new use is the same knowledge. (DRY)
2. **Does it share the host's reason to change?** All three must hold: the same requirement or
   stakeholder would change both; it needs no dependency the host does not already have; the host's
   name still describes the host truthfully afterwards. Then extend the host.
3. **Otherwise it gets its own unit**, named after its responsibility, in the layer its concern
   belongs to (domain rule, I/O adapter, orchestration, presentation). The host delegates to it.
   (SRP, SoC)

**A rule stays a rule when it needs data.** A check that decides whether something is allowed —
*this code may be redeemed*, *this order may be cancelled* — is domain logic, even when the facts
it decides on come from storage. The usual slip is a private method on the host that fetches those
facts and decides on them in the same breath, which leaves the new rule inside the class the
change was supposed to keep from growing. Split the two: the host (orchestration) fetches the
facts and passes them in — plain values, not the repository — and the rule unit decides. Passing
values also keeps the dependency pointing from orchestration to rules, which is what removes the
circular import that otherwise argues for keeping the check in the host.

**Heuristics that say a host is already full** — any one of them is reason enough to prefer a new
unit for new behaviour, not a verdict on the existing code:

| Signal | Rough threshold (heuristic, not law) |
|---|---|
| lines in the unit | a few hundred |

From CreativeCodersTeam/ai-store, Apache-2.0.

More from CreativeCodersTeam/ai-store