[Home]

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
New findings from stage 03 become the next change, and the loop starts again at Plan. Output style, all three stages: every agent reports in ASD-STE100 Simplified Technical English.

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.

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.

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.

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

PieceWhoseWhat it does
claude-dev-pipelineMineDevelopment workflow with gates
codequalityexplorerMineCode quality checks
ponytailDietrich Gebert’sChecks for duplication and dead code
mattpocock/skillsMatt Pocock’sInterviews 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.