Learning Log 2: Guidance through Harness and Specs

In my last post I wrote about my learnings about TDD in the age of AI and promised to dig into two topics: what a harness is, and how people work with spec files today. This post will cover what I learned so far.

All about Harnesses

It must have been around mid May in 2026 when I heard of Pi through hackernews. They advertise themselves as: "... a minimal terminal coding harness". Since then I was wondering what exactly is meant by that. Birgitta Böckeler again comes to the rescue. In her blog post about harness engineering she explain what the tooling does and why it is needed in the first place. Let me summarize her post in my own words:

Why the word "Harness": Harness is borrowed from horses and climbing gear: the equipment that lets you direct a powerful thing without being the thing. The model is the strong, unpredictable part. The harness is everything around it that keeps it pointed in a useful direction.

The Definition: Tools like Claude Code already ship with a built-in harness. You add an outer harness for your own codebase, made of two kinds of controls:

• Guides (feedforward) steer the agent before it acts. Examples are AGENTS.md, skills, code mods and language servers.
• Sensors (feedback) check after it acts, so the agent can self-correct. Examples are linters, tests, structural tests and AI review agents.

Each of these can be computational (deterministic and fast, like linters and type checkers) or inferential (LLM-based and more expensive, like review agents).

Agent = Model + Harness

Claude Code, Codex and Copilot are often just called coding agents. Strictly speaking, what you install is the harness. It runs the loop, gives the model its tools and decides what it is allowed to do. Only together with a model does it become an agent. Pi makes this very visible. You pick the model yourself, and you can adapt the harness to your needs. I plan to try out Pi and OpenCode and write about them in a future learning log. OpenCode was even featured in the most recent Technology Radar Vol 35, so it seems to be worth the time.

Now that I understand what a harness is, it's time to tackle the next bigger open question: What is spec-driven development?

Specs as context files

At DNAstack I had a co-worker who built an SQL driver from a spec over the course of several days. Back then I was not convinced. Adding features that way seemed time consuming to me. You would have to be unambiguous to get everything right and how would you even make sure the code quality was right? Regenerating code from spec files did not seem plausible to me either. So how has the technique evolved since "specify → plan → tasks"? Quite a bit, as it turns out.

Birgitta Böckeler wrote about this in October 2025. She looked at Kiro, Spec Kit and Tessl and identified three levels of spec-driven development (SDD):

• Spec-first: A spec is written first and used for the task at hand. Kiro and Spec Kit worked like this.
• Spec-anchored: The spec is kept after the task is done and evolves with the feature.
• Spec-as-source: The spec is the main artifact. Humans only edit the spec, never the code.

A spec file is a Markdown file in which you describe a feature in as much detail as possible. The acceptance criteria in it guide the agent towards a sufficient outcome. In harness terms, a spec is feedforward. Whether the result is complete depends on the context window and the quality of the model. Böckeler saw this herself. Even with all the files, templates and checklists, the agent often did not follow all the instructions.

Since then the tools have changed a lot.

Tessl left specs behind. It moved from specs to skills, so from one kind of guide to another. The company now sells a platform to manage, version and secure skills, just like dependencies. Today no well-known tool offers spec-as-source anymore. The most radical idea did not survive as a product.

Spec Kit added skills. It reached 1.0 in August 2026. Originally it generated a separate set of command files for each agent, because Copilot, Claude Code, Cursor and Gemini each had their own format. Agent Skills is now an open format most of them read, so one package works everywhere. That is why Spec Kit added a skills mode with support for 30+ agents.

OpenSpec answers my old doubt. Looking back, the SQL driver was a perfect fit for a spec. The protocol and interface were clearly defined. Adding a feature to an existing codebase is a different problem. OpenSpec seems to be built for exactly that. A change only describes what is added, modified or removed. The spec grows with the code instead of describing everything up front. That makes it spec-anchored. It also ships skills for agent tools.

Kiro got lighter and started checking. Böckeler called Kiro a sledgehammer to crack a nut when she used it for a small bug. Kiro now has bugfix specs, a quick spec without approval gates and a step that checks requirements for ambiguities and gaps before design. And it turns requirements into property-based tests. That makes it the first spec tool I came across that not only guides the agent but also checks the result.

On top of that, most coding agents now have a plan mode that writes a plan before coding. It is the lightweight version of the same idea, without the extra hours a full spec workflow costs.

So spec files are still everywhere. Kiro is the only major tool that builds them into the product itself. Spec Kit and OpenSpec bring them to almost any other coding agent. Strictly speaking you don't need any of these tools. Every coding agent can work with specs today. A skill that describes your spec workflow is enough to make the agent follow it. I haven't had the time yet to try any of these tools, but I plan to after I have learned more about token economics. Before that, I will share what I learned about Acceptance Test Driven Development, which Dave Farley calls the future of programming with AI.

Stay tuned, people.