# Claude Code Setup for a Research to Delivery Pipeline A concrete setup for one workflow: research a field, build a dashboard or an AI agent from it, design it, then produce the client deliverable. Companion to the [Agentic Coding Playbook](/playbooks/agentic-coding-playbook.md). That one covers principles. This one is the actual configuration. **Provenance.** My working notes, published as-is. Client names and commercial details have been removed and the examples replaced with neutral placeholders. Every external claim was re-verified before publishing. **Last verified: 28 July 2026.** --- ## The one rule that makes this work **Every stage must be able to run in a brand new session, reading only files.** If a stage needs you to re-explain something from the previous conversation, the handoff is broken. That is a testable property. Use it as your gate. The consequence is that each stage's real output is a file, not a conversation. Research that lives in a chat log does not exist. Anthropic's long-running harness work found the same thing: structured artifacts handing off context between sessions is what keeps multi-hour builds coherent. ## Where this pipeline actually breaks Not in the build. In the **research to spec handoff**. Research produces prose. Prose is a terrible spec. If you hand a 20-page research doc to a build session, the agent reads it, extracts whatever it happens to latch onto, and builds something loosely inspired by it. Then the wrong assumption is baked in three stages deep and shows up in the client proposal. Two fixes, both cheap: **1. Split what is true from what we should do.** Every research file has two sections. Findings, with a source per claim. Implications, which converts findings into constraints on the build. You review the implications section. That is a five minute job and it is where your domain expertise enters the system, which is the highest-return moment in the whole pipeline. **2. Mark unverified claims.** Anything the agent could not source gets `[unverified]`. The spec stage is instructed to flag rather than build on those. Without this you get confident invention that nobody catches until a client does. --- ## The stages | Stage | Session | Reads | Writes | Your gate | |---|---|---|---|---| | 0. Brief | You, 5 min | Nothing | `docs/00-brief.md` | You write it | | 1. Research | Fresh, subagents | Web, sources | `docs/research/*.md` | Edit the Implications section | | 2. Spec | Fresh | brief + research | `docs/specs/.md` | Edit the file directly, `Ctrl+G` | | 3. Design | Fresh | spec | `docs/design.md` + one built screen | Look at the screen | | 4. Build | Fresh per slice | spec + design + plan | code + tests/evals | Read the evidence, not the claim | | 5. Deliverable | Fresh | everything above | `deliverables/*` | Normal client review | Six sessions minimum, not one. `/clear` or a new session between each. The cost of a fresh session is one file read. The cost of a polluted context is a wrong build. --- ## Stage 0. Brief You write this. Ten lines, no agent involved. It is the only artifact where your intent is unfiltered. ```markdown # Brief **For:** [client], [role of the person who will actually use it] **What:** Dashboard showing [the metric that matters] across [the sources] **Why now:** [the commercial reason this exists] **Success:** They can see [the specific thing] without asking us **Out of scope:** [the two things a reasonable person would assume are included] **Constraints:** Must run on the existing stack. No new vendor spend. ``` The "out of scope" line does more work than everything above it. Write it before you know if you need it. --- ## Stage 1. Research Run research in a **separate session using subagents**. Research reads a lot. Every source the main agent reads sits in your context for the rest of the session, and you want that context clean for the spec. The skill below enforces the structure. Save it once at user level and it works in every project. **`~/.claude/skills/research/SKILL.md`** ```markdown --- name: research description: Research a domain and produce a sourced brief with implications for the build disable-model-invocation: true --- Research this topic: $ARGUMENTS ## How to work Use subagents to do the reading. Each subagent investigates one angle and reports back a summary. Do not read sources into this conversation directly. Cover at minimum: how the field actually works, who the serious players are, what the current standard practice is, what changed in the last 12 months, and where practitioners disagree. ## Rules - Every factual claim gets a source link inline. - Anything you could not source gets tagged `[unverified]`. Do not drop it, do not assert it. Tag it. - Prefer primary sources. Official docs, filings, papers, vendor changelogs. Skip content farms and listicles. - State the date of anything time-sensitive. - When sources disagree, say so. Do not silently pick one. - Do not pad. If the honest answer is three paragraphs, write three paragraphs. ## Output Write to `docs/research/.md` using exactly this structure: # Researched . Sources: . ## Findings What is true. Sourced. No recommendations here. ## Open questions What you could not resolve and what it would take to resolve it. ## Implications for the build Convert findings into constraints. Each one in the form: "Because , the build must/must not ." This section is short and blunt. It is the only section that touches the spec. Then append one line to `docs/research/index.md`. Stop after writing. Do not propose a solution. ``` That last line matters. Left alone, the agent will slide from research into design into implementation in one breath, and you lose the gate. ### Your five minutes Open the Implications section. Cut the ones that are generic. Correct the ones that are wrong. Add the two you know from running the business that no amount of web reading would surface. That edit is the highest-value thing you do all day. --- ## Stage 2. Spec Fresh session. This is where the planner earns its keep. Anthropic tested removing it from their harness and the generator consistently under-scoped, producing a thinner product from the same starting prompt. **`~/.claude/skills/spec/SKILL.md`** ```markdown --- name: spec description: Turn a brief and research into a build spec with explicit non-goals disable-model-invocation: true --- Read `docs/00-brief.md` and everything in `docs/research/`. ## First, check If any research claim you need is tagged `[unverified]`, list those and ask me before building on them. ## Then, interview me Use the AskUserQuestion tool. Ask about the hard parts I probably have not thought through: edge cases, failure modes, what happens with bad or missing data, who else touches this, what breaks if usage is 10x expected. Do not ask obvious questions. Do not ask things the brief already answers. Keep going until the gaps are closed. ## Then, write the spec Write `docs/specs/.md`: # ## What it does User stories. Concrete. "As X I can Y so that Z." ## Data model Tables, key fields, relationships. Where the data comes from. ## Interfaces The contracts between parts. Function signatures or endpoint shapes. ## Not building Explicit list. Things a reasonable person might assume are included. ## How we verify it works The end to end check that proves this is done. Name the exact command, test, or user journey. If this section is vague the spec is not finished. ## Rules - Stay at the level of deliverables and contracts. Do not specify internal implementation. Errors in an over-specified plan cascade into the build. - No phases, no timelines, no effort estimates. Sequence only where one step genuinely blocks another. - Ambitious on scope, conservative on technical prescription. ``` Then open the file with `Ctrl+G` and cut things. Editing a spec costs minutes. Editing the code it produced costs hours. --- ## Stage 3. Design Do this before the build, not during. And produce **tokens plus one reference screen**, not a design system. Why one screen: "follow the pattern in ``" is the single strongest prompt shape that exists. One well-built screen becomes the pattern every other screen copies, and consistency stops being something you police. Left alone, models default to safe, bland, technically-fine layouts. Explicit grading criteria move this a lot, and weighting matters. Models are already competent at craft and functionality by default. What they need pushing on is coherence and originality. Prompt: ``` Read docs/specs/.md. Design the visual language for this, then build exactly one screen as the reference implementation. Grade your work against these, in this order of weight: 1. Coherence. Does colour, type, layout, and spacing combine into one deliberate mood, or does it read as assembled parts? 2. Originality. Would a designer see deliberate choices? Stock components, library defaults, and purple-gradient-on-white-card patterns fail this. 3. Craft. Type hierarchy, spacing rhythm, contrast ratios. 4. Functionality. Can a user find the primary action without guessing? Write the tokens to docs/design.md: colour, type scale, spacing scale, radius, motion. Build the reference screen. Take a screenshot and tell me what you would change on a second pass. ``` Then either accept it or say "pivot, try a completely different direction" once. Iterating in the same direction converges. Pivoting is what produces something you would actually put in front of a client. --- ## Stage 4. Build Fresh session per meaningful slice. Read the spec, the design tokens, and the reference screen. ``` Implement from docs/specs/.md. Follow the pattern in . Use the tokens in docs/design.md. Write tests as you go. Run the verification from the spec and show me the output before you tell me it works. Change only what this slice requires. If you spot something adjacent that needs fixing, list it at the end instead of doing it. ``` ### The part that determines reliability Your verification loop depends on what you are building, and this is where most people go wrong. **Building a dashboard or app.** Tests plus something driving the running UI. Playwright, or a browser-driving integration. The agent clicks through the app the way a user would, checks the states, and files what is broken. This catches the class of bug where the code compiles, the tests pass, and the feature does not actually work when you click it. Anthropic's harness runs found exactly this: apps that looked impressive and had real bugs the moment you used them. **Building an AI agent.** Tests are not enough and you cannot skip this. An agent's output is not deterministic, so "it ran without error" tells you nothing. You need an eval set. Minimum viable version, roughly an hour of setup: ``` evals/ ├── golden.jsonl # 20-50 cases: input + what correct behaviour looks like ├── rubric.md # How to score. 3-5 criteria, each with a pass threshold. └── run.ts # Runs each case, scores with a SEPARATE model call ``` Three things make this work: 1. **Score behaviour, not exact output.** "Correctly refused and offered the escalation path" not a string match. 2. **A different model instance does the scoring.** Agents grading their own work confidently praise it. Separating the generator from the evaluator is the strong lever, and tuning a sceptical standalone evaluator is far easier than making a generator self-critical. 3. **Hard thresholds per criterion.** If any one falls below, the change fails. No aggregate score to hide behind. Then in CLAUDE.md: `YOU MUST run pnpm eval and show me the score table before claiming an agent change works.` The eval set is also one of the most sellable artifacts you produce. A scored regression suite is a concrete thing you can hand a client, and most agent work ships without one. --- ## Stage 5. Deliverable Fresh session. Reads research, spec, and the built thing. Writes into `deliverables/`. The reason the proposal comes last and reads the built artifact is that it can then reference what actually exists rather than what was planned. Those diverge more than you would like. ``` Read docs/00-brief.md, docs/research/, docs/specs/, and the current state of the app. Draft the client proposal in deliverables/proposal.md. Ground every claim about capability in something that actually exists in the repo. If a claim is aspirational, mark it as roadmap, not delivered. No superlatives. The reader is a marketing lead, not an engineer. ``` That grounding instruction is not decoration. Without it you get a proposal describing the spec rather than the software, and you find out in the meeting. --- ## Where each piece lives The distinction that keeps this clean: - **Workflow goes user level.** `~/.claude/skills/` for `/research`, `/spec`, `/ship`. Same pipeline for every client, set up once. - **Project knowledge goes repo level.** `CLAUDE.md`, `.claude/rules/`, stack conventions. Different per engagement. - **Reusable pipeline goes in a template repo.** Clone it per client instead of rebuilding. ``` / ├── CLAUDE.md ├── docs/ │ ├── 00-brief.md │ ├── research/{index.md, *.md} │ ├── specs/*.md │ ├── decisions/*.md │ ├── design.md │ └── plans/{active,done}/ ├── evals/ # only for agent builds ├── deliverables/ # proposal, deck, handover ├── .claude/ │ ├── settings.json │ ├── rules/ │ └── agents/reviewer.md └── src/ ``` ### Project CLAUDE.md Keep it short. This one carries the pipeline rules on top of the usual stack rules. ```markdown # Stack: <...> ## Commands - Dev: `pnpm dev` - Test: `pnpm test` - Typecheck: `pnpm typecheck` - Eval: `pnpm eval` # agent builds only ## How work moves here Stages hand off through files, never conversation. If you cannot do your stage from files alone, stop and tell me the handoff is broken. - Research lives in `docs/research/`. Claims tagged `[unverified]` are not facts. Flag them, do not build on them. - The spec in `docs/specs/` is the source of truth for scope. `## Not building` is binding. - Multi-file work gets a plan in `docs/plans/active/` before any edits. - Non-obvious choices get an ADR in `docs/decisions/`. Never edit an old one, supersede it. ## Rules - Change only what the task requires. List adjacent issues, do not fix them. - No abstraction, generalisation, or optimisation for a problem we do not have yet. Duplication beats the wrong abstraction. - No phases, timelines, or effort estimates in plans. Sequence only. - YOU MUST run the verification from the spec and show me the output. Do not assert that it passed. - Validate all external data at the boundary. Never trust an API shape. ## Gotchas ``` ### settings.json ```json { "permissions": { "deny": [ "Read(./**/dist/**)", "Read(./**/node_modules/**)", "Edit(./.env*)", "Edit(./**/migrations/**)" ] }, "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "pnpm typecheck 2>&1 | tail -20" }] } ] } } ``` Rules that must hold go here, not in CLAUDE.md. A CLAUDE.md line is a request. A hook is enforcement. If you catch yourself writing "NEVER edit X" in prose, that is the signal to move it. ### The reviewer subagent **`.claude/agents/reviewer.md`** ```markdown --- name: reviewer description: Reviews a diff against the spec in a fresh context tools: Read, Grep, Glob, Bash --- You review changes against a stated spec. You did not write this code and you have no attachment to it. Check three things: 1. Every requirement in the spec is implemented. 2. The listed edge cases have tests or evals. 3. Nothing outside the task's stated scope changed. Report only gaps that affect correctness or the stated requirements. Style preferences are not findings. Suggestions for future work are not findings. If the work is sound, say so plainly. ``` That last paragraph is load-bearing. Anthropic's own docs make the same point: a reviewer prompted to find gaps will usually report some even when the work is sound, because that is what it was asked to do, and chasing every finding leads to extra abstraction layers, defensive code, and tests for cases that cannot happen. --- ## What to actually set up **This week, about 90 minutes.** 1. `~/.claude/skills/research/SKILL.md` and `~/.claude/skills/spec/SKILL.md`. Copy from above. 2. A template repo with the `docs/` tree and the CLAUDE.md skeleton. 3. The typecheck hook in settings.json. 4. Run the whole pipeline once on a small real project. Do not experiment on your most important client. Use something with low stakes. **After the first run.** 5. Whatever annoyed you becomes a line in the skill. That is the whole maintenance model. 6. If you are building agents, set up `evals/` on the next one. Do not retrofit it. **Not yet.** Agent teams, parallel worktrees, custom plugins, MCP servers you have not needed. Each of those is scaffolding that encodes an assumption about what the model cannot do alone. Add them when a specific failure forces you to, and revisit them when a new model lands, because half of them will have gone stale. --- ## Sources - [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) - [Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps), Anthropic, 24 March 2026