02.15Concept
The temperature of specification
AR Labs' principle for planning AI coding agent work: start in design-level language and grow specific stage by stage, leaving code detail to later steps.
On this page
The temperature of specification is AR Labs' principle for writing planning documents that AI coding agents (AI agents that write code, such as Claude Code or Codex) will act on. Early documents should be "hot": broad, written in design-level language, stating intent, approach and observable outcomes. Each later stage cools the description, adding specificity only once the stage has the knowledge to justify it, so that file names and code-level choices are made by the step that has actually read the codebase. Jumping to code-level detail too early locks the work into a solution chosen before anyone looked.
Where the metaphor comes from
Simulated annealing is an optimisation technique that starts with broad, exploratory search and gradually narrows to a specific solution. Start too cold and the search settles into a local minimum: a solution that satisfies the immediate constraints but misses a better one nearby. A planning document that prescribes exact files, method signatures and database statements before the codebase has been consulted is a search that started cold.
The principle also mirrors how people take in complex material. Progressive disclosure, loading the most general and constraining information first and detail only as it becomes relevant, is how attention and expertise work in the cognitive science we draw on (cognitive ecology).
How we arrived at it
Our coding pipeline once used a planning template, a product requirement prompt (PRP: a plan agents build from, in Rasmus Widing's format, adapted), that produced code-level output: class definitions, exact table schemas, and lists of files to create and modify. Agents could follow it, but the person making product decisions could not easily read it, and implementations were brittle. When conditions in the code differed from what the planner had assumed, the implementing agent followed the specification into a wall instead of finding the door.
We rewrote the template to require design-level language: paragraphs of intent instead of file operations, gotchas stated in plain words instead of code comments, and success criteria a product owner could review. Rewritten this way, the plan for a version of our Salesbot voice agent exposed gaps the code-level version had hidden. A review of the readable scenarios surfaced a missing distinction between ending a conversation and disconnecting, prompted a new requirement to log transcripts for improving the bot, and caught an ambiguous criterion that could have meant either backend durability or resuming a session later, two different versions' worth of work.
The gradient
The figure shows the three documents cooling from left to right. The plan holds only prose, the specification names the file for each layer from the real codebase, and the implementation opens with a failing test.
Planning, high temperature. State what is being built and why, which design approaches will be used, and what a person will be able to observe when it works. Natural language, no code blocks. The rule of thumb: code in a planning document is a design smell. If the code was written from assumptions about the codebase rather than knowledge of it, the optimisation is premature.
Specification, medium temperature. Ground the plan against the actual codebase: the specific files, the existing patterns to extend, the concrete wiring. Code-level detail belongs here, informed by what is really there.
Implementation, low temperature. The implementing agent works test-first, holding the design constraints from the plan and the grounding from the specification, and writes code that satisfies both.
Supporting practices
Three levels of verification. We separate three things that are often written as one list. Success criteria are outcomes a person can check. Gherkin scenarios, the Given-When-Then format of behaviour-driven development, are testable behavioural contracts. Per-slice evaluations are observable checks that a piece of the work is done. Each serves a different reader, and merging them produces a list too detailed for product review and too vague for testing.
The depth charge. Instead of listing architectural layers separately from the files that change, each layer entry names its file, says whether it is new or modified, and states its responsibility. The result is a single scannable proof that a slice of work runs vertically through every layer it needs.
How it is used now
The principle is built into our coding pipeline: a plan states intent and outcomes, a per-task specification is written against the current state of the code, and implementation follows the specification with tests first. The same idea applies to any multi-stage workflow where one AI step hands work to the next: constrain the design space early, and let each later step make the decisions it is best placed to make.