Partner with AI to Write Quality Code
How I build software with Claude: a pipeline of narrow agents, a pass that deletes what should never have existed, and a ranked report that helps humans clean up AI slop.
A large language model can write two thousand plausible lines of code per minute. That is simultaneously a grand technological achievement and a way to automate yourself into a huge mess.
Nobody reviews two thousand lines carefully. Anyone who says they do is either skimming or lying. Now try it with 100,000 lines. A colleague recently dropped 160,000 lines on me. I’m just not going to review that.
We know development can be done quickly, even amazingly quickly. That’s the realm of AI. What you want and how you want it to look when it is done are still the domain of people. AI influencers will tell you all about those things, as has Anthropic.
There is another, and arguably more important, place for people in our use of strong AI to create software: It is up to us to tell the technology how to create good code.
What do I mean by good code? I mean that it complies with a specification, that it has low cyclometric complexity, that I can read it if I need to, that it reuses functions instead of reimplementing near copies, that it is, in short, maintainable by whatever we will use in the future.
The workflow
flowchart TB
subgraph S1["STAGE 01 — Build under gates · claude-dev-pipeline"]
direction LR
P["Plan<br/>human-approved"] --> D["Developer<br/>writes code"]
D --> CR["Code review<br/>gate"]
CR --> SR["Security review<br/>gate · OWASP"]
SR --> T["Test + commit<br/>only committer"]
T --> DOC["Document<br/>on what shipped"]
CR -. "fail" .-> D
SR -. "fail" .-> D
end
subgraph S2["STAGE 02 — Delete what should not exist · ponytail"]
direction LR
PR["/ponytail-review<br/>the diff"] --> CUT["Cut<br/>dead code · duplication<br/>near-twin abstractions"]
PA["/ponytail-audit<br/>the whole repo"] --> CUT
CUT --> PD["/ponytail-debt<br/>ledger of shortcuts taken on purpose"]
end
subgraph S3["STAGE 03 — Measure, then let a human read · codequalityexplorer"]
direction LR
QR["/quality-report<br/>measures · never edits"] --> MD["CODE_QUALITY.md<br/>ranked worst-first"]
MD --> QI["/quality-improve<br/>one finding · test · stop"]
QI --> HR["Human review<br/>read the top of the list"]
end
S1 --> S2
S2 --> S3
I build in three stages:
Stage 01 — Build with gates
My Claude development pipeline runs six agents with one job each. A project manager, developer, code reviewer, security reviewer, tester, and documenter. The constraints matter more than the roles.
- The project manager orchestrates and never writes code.
- The developer writes code and never commits.
- Code review and security review (OWASP framing) are gates, not opinions. A FAIL routes the change straight back to the developer with findings, and it goes round again.
- The tester is the only agent allowed to commit, and only once both gates pass and the suite is green.
- The documenter runs last, against what actually shipped.
I work the change out with Claude in plan mode, approve it, and only then hand it to the project manager.
Running alongside Matt Pocock’s skills
Matt Pocock’s skills sit underneath and supply the engineering habits: test-driven development (TDD), domain modelling and deep-module design.
I have come to especially appreciate the benefits of Matt’s grillme skill. Grillme ensures that the LLM and I understand the task the same way before it starts coding.
Stage 02 — Delete what should never have existed
Models are generous in their output. If you ask for a function, you probably will get an interface, a factory and three helpers that are never called twice. None of that is helpful.
Dietrich Gebert’s ponytail is the cure for this behaviour. Does a piece of code need to exist at all? Is it already in the codebase? Does the standard library do it? Is there a native platform feature? Can it be one line? New code is only allowed as a last resort.
/ponytail-reviewon the diff, before human review, to catch what this change just added./ponytail-auditacross the whole repo, periodically, for what has accumulated: dead code, duplicated blocks, and the one I care about most — near-twin abstractions, two utilities doing one job under different names, drifting slowly apart./ponytail-debtcollects the shortcuts the pipeline took on purpose, so “we’ll do that later” is a list rather than a feeling.
It also runs as a live mode during implementation, which is a great deal cheaper than deleting fluff afterward.
Stage 03 — Measure it, then let a human read the top of the list
My codequalityexplorer ranks every finding worst-first into a CODE_QUALITY.md report, then fixes exactly one at a time. I cannot review everything the pipeline produced. I can review the worst things in it, and I know they are the worst because something measured them instead of sampling them.
/quality-report measures the codebase using old-fashioned software engineering concepts including cyclomatic complexity, function length, nesting depth, argument counts, duplicated blocks, dead code, error-handling smells (bare except, Rust unwrap, swallowed catches), oversized files, documentation and reusability — and writes CODE_QUALITY.md: every finding, ranked worst-first. It never edits code.
Currently, Python, Rust, JavaScript and TypeScript are supported languages.
/quality-improve takes exactly one finding, the top open one, fixes it, runs the tests, and stops. That constraint is deliberate. Nobody wants a tool that promises to fix everything but hands me back an unreviewable diff, which is the problem I started with.
The skill will ask you if you want to start a new branch for the improvements. Say yes.
You run this command again to tackle the next finding.
Clean up Claude’s English
A pipeline this size produces a lot of reports. Six agents, two gate verdicts, an over-engineering pass and a ranked quality file — all of it lands on me at the end of a long day. LLM prose makes that worse, especially with the newer Claude models.
The easy solution is to set an output style and hold every agent to it. Mine is ELI5 crossed with ASD-STE100 Simplified Technical English a limited vocabulary for technical reporting. It has a fixed approved vocabulary, one meaning per word, active voice, and one instruction or idea per sentence.
- Plain words only. If a technical term is unavoidable, it gets explained straight after.
- Active voice, short sentences, short paragraphs. No throat-clearing.
- Report the outcome: what was done, whether it worked, what I do next.
- Decisions come as two options, not five — with just enough context to choose, and a recommendation.
- Paths and commands stay exact. Simplification applies to the prose, never to an identifier.
These are not cosmetic preferences. Ambiguous review findings are how a real problem gets waved through, and the discipline that keeps a maintenance manual unambiguous does the same job for a code review. It also makes the gates faster to read, which means I actually read them.
Let Claude clean itself
Every Claude upgrade changes what the model does well unaided, and scaffolding that helped last quarter can actively get in the way this quarter. You have probably seen Anthropic’s guidance to delete your CLAUDE.md every quarter.
I run /doctor once per month. Anthropic has improved that tool immensely so it is worth doing. It will guide you through the process of complying with their best practices.
Credits
| Piece | Whose | What it does |
|---|---|---|
claude-dev-pipeline | Mine | Development workflow with gates |
codequalityexplorer | Mine | Code quality checks |
ponytail | Dietrich Gebert’s | Checks for duplication and dead code |
mattpocock/skills | Matt Pocock’s | Interviews and related process tooling |
The shape matters more than the parts. The process is generate under constraint, delete aggressively, measure honestly, report in plain English, and give the human a short ranked list instead of a long diff.