Turning research notes into a spec a coding agent can build

The short answer: convert findings into constraints. A coding agent does not need to know what you learned — it needs to know what to build, what is explicitly out of scope, which decisions are already settled, and which are still open. The practical artefact is a short project context file carrying the product goal, the target user, the feature list, the non-goals, and the risk rules. Research left in prose produces vague code; research compiled into constraints produces something you can run. As of July 2026 every mainstream coding agent reads a project context file of this kind, so the format is portable rather than tied to one vendor.

This is the step that quietly decides whether a research phase was worth doing. Plenty of well-researched projects stall here, holding a document full of genuine insight that cannot be handed to anything — human or agent — as instructions.

Findings are not requirements

A finding describes the world. A requirement constrains what you build. The translation is mechanical once you see it, and skipping it is why so many specs read like literature reviews.

Note the fourth row. Unresolved questions belong in the file explicitly, flagged as open. If you leave them out, the agent resolves them silently with whatever is most common in its training, and you discover the decision later as an implementation detail rather than a choice.

The shape of a context file that works

The structure that holds up in practice is boring and short. Six sections, each of which an agent can act on:

# Mission          - one paragraph: what this is and for whom
# Target user      - specific enough to exclude people
# MVP features     - the list, in build order
# Do not build yet - explicit non-goals, with the reason
# Risk rules       - things that must never happen in generated code
# Open questions   - decisions deliberately not yet made

Every section earns its place by changing what gets written. Mission prevents generic scaffolding. Target user rules out features. Risk rules catch the category of mistake that is expensive rather than annoying — the compliance disclaimer that must appear, the data that must never be stored, the claim the product must never make.

The full anatomy of that file, section by section with worked examples, is in how to write a CLAUDE.md that actually steers the model.

Why the non-goals section does the most work

Coding agents are helpful, and helpfulness is the problem. Given an under-specified brief, an agent adds the features it expects a product like this to have — auth flows nobody asked for, admin panels, settings pages for options that do not exist. Each addition is individually reasonable and collectively a different product.

An explicit non-goals list is the only reliable defence, and it works best when each entry carries its reason:

• No mobile app — responsive web covers the observed use case; nothing in the corpus described a mobile workflow
• No team accounts in v1 — every validated user in the research was working alone
• No custom model hosting — API tier is sufficient at this volume, and self-hosting is a project of its own

The reasons matter because you will revisit these decisions, and without them you cannot tell a considered exclusion from an oversight. Six weeks later a bare list of non-goals looks arbitrary and gets quietly overturned.

Keep provenance, but keep it separate

Every constraint in the file came from somewhere — a specific claim in a specific video, or a pattern across several. That provenance is valuable and does not belong in the instruction file, because it bloats what the agent reads without changing what it does.

Keep it alongside: the constraint list the agent consumes, and the sourced findings document a human consults when a decision comes back up for review. Losing the second one is how a team ends up re-litigating a settled question because nobody remembers why it was settled — the same attribution discipline argued for in the timestamps-and-citations test.

Doing this against an existing codebase

For an established project the same compilation applies with one change: the context file already exists and describes conventions, so the research output is layered on as a feature brief rather than a founding document.

That layering works better than a fresh spec, because the agent inherits the existing patterns — file layout, naming, testing approach — and receives only the new requirement as constraints. The most common mistake here is restating the whole product in the brief, which invites the agent to reconsider settled architecture.

Test the spec before you test the code

A spec is cheap to check and expensive to get wrong, so it is worth running two quick tests before any code is generated from it.

The substitution test. Replace your product name with a competitor's throughout the file. If it still reads as an accurate brief for them, the constraints are describing the category rather than your findings, and the agent will build the category average.

The disagreement test. Hand the file to someone who knows the space and ask which line they would argue with. A spec nobody can disagree with contains no decisions — it is a description. The lines that draw an objection are the ones actually doing work, and they are also the ones worth double-checking against your sources.

The loop that keeps it honest

A context file written once and never revised becomes misleading the moment the product moves, and a misleading file is worse than none — the agent follows it confidently. Three maintenance triggers worth adopting:

That third trigger is why research and building are better run as a loop than as phases. The reasoning-model side of producing the findings in the first place is covered in using Claude for product research, and the compressed end-to-end version — corpus to synthesis to a spec you can build against — in the seven-day playbook.

Closing thought

The reason this step gets skipped is that it feels like paperwork after the interesting part is done. It is not: it is the point where research either becomes constraints or evaporates into a document nobody opens again. An afternoon spent converting findings into a page of specific instructions — including the list of things you are refusing to build — is the difference between an agent that ships your product and one that ships the average of everything like it. The plans all include the exports, because the compiled artefact is the point of the research rather than a bonus on top of it.