- Author
- Adam Lewis
- Published
- Updated 4 September 2026
- Kind
- Short personal blog post
- Original
- prickles.hashnode.dev/a-spec-the-agent-can-t-run-isnt-a-spec-yet
- Subject
- Checkable specs for coding agents
- Themes
- Checking the work, Handing over control
What it is
Adam Lewis argues that what matters in a spec is whether it can be executed. The format and length barely matter by comparison. The post belongs to a collection of software-craft tenets at prickles.org.
What it says
- A table of contents that should work is intent. A checkable heading position is not.
- A spec an agent invents mid-task sits inside the loop and grades itself generously.
- A spec written beforehand, which the agent cannot edit, sits outside the loop.
- One executable check that defines done can be enough.
- Large specs stop being verifiable without anyone noticing, so short per-step checks work better.
What evidence it gives
The post offers one small example and reasoning from experience. It reports no measurements.
Interests and limits
It is a short opinion post, and it promotes the author's wider collection of tenets. It does not discuss criteria that resist automation. It does admit that fuzzy tasks are hard.
Connections
These links are this wiki's own reading, not claims the sources make.
- Agents Don't Need Memory. They Need Documentation.. Liao has the working agent write its own documents. Lewis says anything an agent writes mid-task grades itself generously. Together they raise a question: which memory should an agent be unable to edit?
- Effective harnesses for long-running agents. Young's team chose JSON because models overwrite it less often than Markdown. It added strong wording against editing tests. Lewis says anything written mid-task grades itself generously. So file format has become a soft lock. How firm must the definition of done be?
- How much can you delegate to agents?. Yoon sets an agent's ceiling with two questions. Is the work easy to check, and cheap to undo? A spec the agent can run changes the first answer. So Lewis's check is also a way of buying autonomy.