Since January 2026 I’ve been building Agent Smith, an open source agent that turns tickets into pull requests. It’s now about 500k lines of code and 10k tests. The challenge I started with was not to write a single line of code myself, and that’s still true. Unfortunately it works pretty well, which proves something I didn’t want to know: coding is more or less solved. To make that happen, I built a spec-first development plugin for Claude Code. The short version: Every spec is a YAML file in the repo with a fixed schema: a goal, steps and a definition of done. Specs move from planned to active to done. The reasoning goes into a separate decisions file, so when an agent picks up the next spec, it can read what was built before, why it was built that way, and why things changed later. Before any code gets written, a second agent reviews the spec. A script first checks that every file and line the spec cites actually exists. Then the reviewer answers BUILD, BUILD WITH CUTS or REFUSE. It refuses a lot, and most of the time it’s right. Each spec gets its own git worktree, so several agents can run overnight without getting in each other’s way. A commit hook runs the full test suite on every spec commit and blocks the commit if anything is red. That hook is why I can skip reading most of the code. What I learned along the way: My first specs were Markdown. At 100 specs they added up to 250k tokens, just the specs. Claude tends to write a lot that’s unnecessary and sometimes even misleading. Moving to YAML brought that down to 15k tokens. The workflow has to be good enough that all I discuss is features, changes, design and architecture. Coding principles have to be enforced by quality gates. Without them, files grow past 500 lines and the code gets buggier. Without a fixed procedure (create, review, apply, deliver) I kept doing the same things over and over: testing every change and finally checking the result of every spec myself. Without a review step that brings evidence for whether a spec can be built at all, I wasted a lot of time. I put procedure into tickets (“first do X, then Y”). The agent turned that into acceptance criteria and failed a run that was actually correct. I let learned memories act as rules. One wrong memory and every later run followed it. Now they’re hints, and whether a memory holds up depends on how the runs that used it turned out. Specs don’t need to be as precise as the code they produce. They need to be short, verified, and ideally something several agents can execute in parallel. They pin down intent and architecture. The tests and the commit gate supply the precision. My job now is mostly deciding what to build and how it should be structured: design and architecture. Programming was more romantic last year, but this works pretty well. Plugin and method: spec-first.dev , github.com/holgerleichsenring/specification-first-agentic-development Agent Smith (MIT): agent-smith.org , github.com/holgerleichsenring/agent-smith How do you handle this? Do you keep specs in the repo, or do they disappear with the chat? submitted by /u/holgerleichsenring
Originally posted by u/holgerleichsenring on r/ClaudeCode