User-Guide-Driven Development With Agents

User-guide-driven development with coding agents is a workflow experiment described by a Hacker News poster on September 5, 2026. The author is asking a very practical question: if agents now write most of the code, what durable artifact should the human own and review? The useful takeaway is simple: write the user guide and mockups first, then judge the agent’s work by whether a fresh reader can complete the guide without hidden context.

User-guide-driven development is the practice of treating the user guide as the primary executable product spec for an agent-built feature. It sits near the practical edge of agentic coding governance, but it is not policy theater. It is a way to keep human intent visible when the code itself is increasingly produced by a coding agent.

Start with the thing a user can follow

The Hacker News post was not announcing a framework or a library. It was describing a small workflow: write the guide first, add mockups, let coding agents build toward it, then run a “user-experience” pass before calling the work done.

The author said they had been using this mostly for small utilities. That matters. A small utility has a narrow path: install it, run it, recover from the obvious error, and get the expected output. A guide can cover that path better than a pile of vague acceptance notes.

Here is the shape in a real repo:

docs/guide.md        # what the user should be able to do
mockups/export.png   # expected screen or CLI output
src/                 # agent-written implementation
test-fixtures/       # sample files used in the guide

The trap is pretending a public-facing guide contains every requirement. It does not. Good user docs hide internals on purpose. They may omit rate limits, migration behavior, security boundaries, weird browser states, or data retention rules.

So the guide should own the visible journey. It should not be forced to carry every invisible constraint.

Let one agent build and another read literally

The clever part of the experiment is the second agent. The author described using a context-less agent to walk through the guide literally before considering the work done. That is the move worth stealing.

A builder agent has too much memory. It has seen the prompts, the repo, the failed attempts, and the intended behavior. A fresh evaluator catches the missing sentence, the broken setup step, and the command that only works because the builder already knew where the fixture lived.

In Claude Code, Anthropic’s coding agent, the pattern can be this simple:

# human writes the guide first
mkdir -p docs mockups
$EDITOR docs/guide.md

# builder pass
claude "Implement the feature described in docs/guide.md. Use mockups/export.png as the behavior target. Keep changes small."

# clean reader pass in a fresh session
claude "You have no prior context. Follow docs/guide.md literally. Report the first step that fails, the exact command or UI action, and the smallest doc or code change needed."

The important bit is not the exact command. It is the context boundary. The evaluator should not inherit the builder’s chat, assumptions, or todo list.

The trap is letting the reader agent “be helpful” too early. If it silently fixes the guide while testing it, you lose the signal. First ask it to fail loudly. Then ask for a patch.

Keep the hidden contract somewhere else

The strongest objection in the Hacker News discussion was old and fair: user guides make bad complete specs because they hide complexity. Plenty of teams learned this long before coding agents existed.

That objection does not kill the workflow. It just defines its boundary.

Use the guide for user-visible behavior. Keep hidden contracts in a short companion note. For example:

docs/guide.md              # visible task flow
spec/internal-contract.md   # permissions, storage, failure modes, non-goals

For a file export utility, the guide might say: “Choose a folder and click Export.” The internal contract should say: “Never overwrite existing files without confirmation. Preserve original timestamps. Do not send filenames to external services.”

That second file is not user documentation. It is the part the user guide is supposed to hide.

Claude Code users can keep durable repo conventions in a concise project memory file, but this workflow should not depend on memory alone. The reviewable source of truth should be committed files that a human can diff: the guide, the mockup, and the hidden contract.

Use docs as tests, not replacements for tests

The author said they had “almost stopped using unit tests” for small utilities and started creating user-experience checks instead. I get the instinct. When an agent can generate brittle tests as easily as brittle code, tests stop feeling like a reliable human-owned artifact.

Still, the safer framing is: use the guide as the top-level acceptance test, not as the only test forever.

A user-guide pass is great at catching broken onboarding, missing setup, wrong defaults, and confusing success states. It is weak at catching edge cases that users should never need to understand: concurrency, data corruption, permission escalation, timezone math, retry behavior, and irreversible operations.

For small tools, the split can be modest:

The trap is turning the guide into a giant requirements novel. Once it becomes unreadable, it stops working as a user guide and as an agent target.

Try it safely with one slash command

The smallest useful version is one feature, one guide, one fresh-reader pass. Do not start by rewriting your whole development process. Pick a feature that can be completed in an hour and judged from the outside.

Here is a copyable Claude Code slash-command artifact. Save it as .claude/commands/ux-pass.md:

Run a literal user-guide pass for this repo.

Inputs:
- Guide: $ARGUMENTS

Rules:
- Start with no assumptions beyond the repository and the guide.
- Follow the guide exactly, step by step.
- Do not fix anything during the first pass.
- Stop at the first failure or ambiguity.
- Report:
  1. the step that failed,
  2. the command, screen, or file involved,
  3. what you expected,
  4. what actually happened,
  5. the smallest code or doc change that would unblock a new user.

After reporting, ask before making changes.

Then run:

claude "/ux-pass docs/guide.md"

A good first experiment looks like this:

• Write a 20-line guide for one narrow task.
• Add one mockup or terminal transcript.
• Ask the builder agent to implement only that guide.
• Start a fresh session and run the UX pass.
• Accept the work only when the fresh session can complete the guide literally.
• Add one small unit test only for invisible risk.

The trap is asking the same long-running agent to grade itself. It knows too much.

This is also where related memory work becomes useful. If you are comparing committed guides with committed agent memory, okf-agent-memory Adds Git-Native Agent Memory is a helpful adjacent example.

Common questions

• Is user-guide-driven development just documentation-driven development with agents?

  Mostly yes, but the evaluator changes the weight of the document. The guide is not only written for future users; it becomes the artifact a fresh coding agent must execute literally. The practical difference is the second pass: a context-less reader reports where the product or the guide fails.

• Can this replace unit tests for agentic coding?

  No, not across the board. It can replace some low-value tests for small, user-facing flows, but it should not replace tests for invisible risk. Keep targeted tests for security boundaries, data loss, permissions, concurrency, and deterministic business rules.

• What belongs in the user guide versus the internal contract?

  The user guide should contain what a real user needs to complete a task. The internal contract should contain what the system must guarantee but the user should not have to think about. If a requirement is security-sensitive, irreversible, or operationally expensive, put it outside the guide and review it directly.

• Does this work better for CLI tools or UI products?

  It works best when the user path can be followed literally. CLI tools, small internal utilities, onboarding flows, and admin screens are good candidates. Large collaborative products are harder because the guide hides roles, permissions, background jobs, and multi-user timing.

• How should Claude Code users review the final result?

  Review the guide diff, the implementation diff, and the UX-pass report together. A clean result should show that a fresh session completed the guide without private context. If the agent needed hidden instructions from chat history, the repo artifact is incomplete.

Best ways to use this research

• Best for: small utilities, setup flows, admin tools, and narrow product slices where the visible user journey matters more than internal architecture elegance.
• Best first artifact: a committed docs/guide.md plus one mockup or terminal transcript. Keep it short enough that a new engineer can read it in five minutes.
• Best comparison angle: compare the guide-first pass against a normal agent prompt. The useful metric is not lines of code; it is how many missing assumptions the fresh-reader pass finds.
• Best guardrail: keep a separate internal contract for behavior the guide intentionally hides. That is where code review guardrails belong.

Further reading

• Claude Code, Anthropic’s coding agent — getting started
• Claude Code — hooks
• Claude, Anysphere’s AI code editor — Agent
• Model Context Protocol — specification

Next step

Pick one small feature and write the guide before the prompt. Then make a fresh agent follow it literally, and treat the first failure as the real spec gap.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.