Most of us start a session the same way. We type what we want in a sentence or two and press enter. Sometimes that's exactly right. Often it isn't, and we find out forty minutes later when the result is tidy, working, and not what we meant.
That gap is older than coding agents. Requirements engineering, the part of software work that decides what to build, has been studying it for decades. We think its findings travel well.
An old problem with a survey behind it
The Naming the Pain in Requirements Engineering initiative surveys practitioners about the problems they hit in practice. One published analysis draws on data from 228 companies in 10 countries, covering 21 requirements problems and a cause-effect analysis of the most critical ones.1 The authors describe the aim as grounding the field in observation, because decisions about practice had been driven mostly by conventional wisdom.1
We won't quote percentages here, because we couldn't open the full paper to check them. What we can say is the point of the exercise: requirements trouble is common enough, across enough companies, that people built a multi-country survey to name it. If that's true for teams with analysts and review meetings, it's true for a one-line prompt.
What the agent's docs ask of you
Anthropic's best practices guide for Claude Code is vendor documentation, so it speaks only for that tool. Still, its advice reads like a requirements checklist. It warns that letting Claude jump straight to coding can produce code that solves the wrong problem.2 Its remedy is to separate exploring and planning from implementing.2
For larger features it goes further and suggests you have Claude interview you first, asking about things you might not have considered yet, including edge cases and tradeoffs, and then write the result to a spec file.2 Notice who's doing the work there. The agent asks, but you answer. The spec only gets better if you actually decide.
What goes in a small spec
The same guide says the most useful specs are self-contained, name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step.2 That's a short list, and it's worth taking one item at a time.
- Where it touches. Name the files and interfaces. This is the part you'd have to explain to a new teammate anyway.
- What's out of scope. This is the line people skip. Writing it forces you to notice the neighbouring work you were half expecting.
- How you'll know it works. One check you can run or look at. If you can't name one, you haven't finished deciding what you want.
The guide's own summary is blunt: time spent making the spec precise pays off more than time spent watching the implementation.2 We'd add that a spec is also a record. When the build drifts, you have something to hold it against.
When to skip it
A spec isn't free, and the docs say so. Planning adds overhead, and for small fixes the advice is to ask directly: if you could describe the diff in one sentence, skip the plan.2 A typo doesn't need a document.
So here's the rule we use. If the change touches several files, or we're unsure of the approach, we write the spec first. If we can say it in one sentence, we just say it.
Where session history fits
Cartographer reads the session history your agent already keeps and turns it into a map of how a project was built, as how it works explains. If you wrote a spec, the map gives you a way to read the build against it afterwards. If you didn't, it shows where the requirements were being decided anyway, one prompt at a time.
A small test
Before your next prompt that touches more than one file, write three lines: where it touches, what's out of scope, and how you'll check it. Paste them in with the request. It takes a couple of minutes, and you may find the decision you'd been putting off.
Sources
- Daniel Méndez Fernández, Stefan Wagner, et al. Naming the Pain in Requirements Engineering: Contemporary Problems, Causes, and Effects in Practice. Empirical Software Engineering, 2017 (arXiv preprint 1611.10288).
- Anthropic. Best practices for Claude Code. Claude Code documentation, code.claude.com.