How I Use Claude Code to Take a Feature from Discovery to Production

Most descriptions of coding-agent workflows start at the prompt. Mine starts two steps earlier, because the two steps before the prompt — understanding the operational problem and understanding the repository — are where features succeed or fail, with or without an agent. This is the workflow I use to ship real features with Claude Code, including on this site and on production systems at Playmaker. It's the same forward-deployed discipline I apply to AI deployments for customer operations: inspect, plan, execute inside boundaries, validate with evidence, and keep deploy authority human.

Before any session, I write one paragraph a stakeholder would recognize: what changes for the user or the operation, and how we'd know. "Recruiters can't tell what I do within ten seconds of landing" is an operational problem. "Redesign the homepage" is not — it's a solution wearing a problem's clothes. This paragraph becomes the first block of the prompt, and it does real work there: when the agent hits an ambiguous decision mid-task, the stated outcome is what disambiguates it.

The first session on any codebase is read-only. I ask Claude Code to trace the architecture and current behavior before proposing anything — either informally ("inspect and summarize before making recommendations") or by starting in plan mode, which restricts the session to reading and exploration until a plan is approved. From the CLI that's claude --permission-mode plan; interactively, Shift+Tab cycles modes. Two things come out of this stage: a map (routes, data flow, where the change actually lives — which is rarely where the ticket says it lives) and corrections to my own assumptions. On an unfamiliar repository I also run /init so the findings persist into a CLAUDE.md instead of evaporating with the session.

Agents are eager. Left unscoped, a "fix the hero copy" task becomes a typography refactor. So scope gets written down with equal weight on both halves: what we're doing, and what we're explicitly not doing this pass. Non-goals are the cheapest control surface in the whole workflow — one line ("do not touch the case-study renderer") prevents an hour of unwanted diff.

For anything beyond a trivial edit, implementation starts only after an explicit plan: the files to be changed, the approach, the risks, and — the part most people skip — acceptance criteria that are checkable, not aspirational. The difference:

ACCEPTANCE CRITERIA
1. Built HTML for / contains the new H1 text (grep the out/ directory)
2. yarn build and yarn lint pass with zero errors/warnings
3. Every route returns 200 when the static export is served locally
4. No route renders a placeholder image or "in progress" badge
5. Lighthouse-relevant: hero image ≤ 200KB, no layout shift on load
6. The diff contains no changes outside src/ and public/

Plan mode is the natural home for this stage: the agent explores and proposes; nothing is edited until I approve. The plan-approval step is also where I harden scope — cutting steps the plan invented, and adding stop conditions for the risky parts.

Claude Code's permission system is layered — allow/ask/deny rules in .claude/settings.json (project, committed), .claude/settings.local.json (personal), and ~/.claude/settings.json (user-wide), plus per-session permission modes. My defaults per task type: read-only investigation runs in plan mode; normal feature work runs with edits allowed and commands like the test runner and build allowlisted (rules like Bash(yarn build), Bash(yarn lint)); anything touching production config stays behind prompts. The full risk-tiering system is its own article — how I give Claude Code autonomy without losing control — but the principle here is simple: decide the boundary before the session, not per-prompt in the middle of one.

Execution happens on a dedicated branch, always — git checkout -b feat/... as the first action of the implementation session. The branch is the coarse rollback boundary: nothing the agent does on a feature branch requires undoing anything on main. For parallel sessions, Claude Code has first-class git-worktree support (claude -w feature-name creates an isolated worktree under .claude/worktrees/), which is the documented way to run more than one session against one repository without write collisions. Within the session, I let the agent run autonomously against the approved plan — the point of the earlier stages is precisely that autonomy here is safe and bounded.

The instruction I give is: build early, build often, and treat validation as part of implementation rather than a phase after it. Concretely, on a web project: run the linter and production build after each meaningful unit of work; serve the built output and check the routes; when the change is visual, capture screenshots and actually look at them. On this site's redesign, screenshot review caught two defects the build never would have — an invisible diagram caused by animation-gated opacity, and a punctuation bug in a text-splitting component. An agent that says "done" has made a claim. The build passing, the routes returning 200, and the screenshots looking right are evidence.

Before anything merges, I read the full diff — not the agent's summary of the diff. The summary is the agent grading its own work; the diff is what will actually run. I'm reading for four things: changes outside the agreed scope, deleted code that wasn't part of the plan, invented content (the cardinal sin in anything user-facing), and quiet weakening of checks — a skipped test, a loosened type. Alongside the diff, the session ends with an implementation report:

IMPLEMENTATION REPORT
What changed:        files + one line each
What was verified:   commands run, with results (not "tests pass" — which tests)
What was NOT done:   explicit deferrals and why
Claims needing me:   anything the agent could not verify itself
Risks:               where this could break, and what to watch
Suggested commits:   logical grouping if splitting the change

The "claims needing me" field is the one I'd keep if I could keep only one. A well-run agent session knows what it couldn't verify — unverified metrics in copy, an external service it couldn't test against — and says so instead of burying it.

The agent's authority ends at the branch push and the pull request. On this site, merging to main triggers the production deploy — so the merge is the deploy authorization, and it's mine. The agent prepares everything that makes that decision easy: green build, validated routes, screenshots, the report, a PR description with a review checklist of exactly the claims that need human confirmation. After deploy, verification is a checklist, not a vibe: the routes that changed, the metadata in a link-preview validator, the analytics events firing. When the deploy has operational stakes, this stage mirrors what I do for voice-agent deployments — defined success metrics, checked after ship, on a schedule.

The last step of a feature is a two-minute edit to the repository's CLAUDE.md: anything the agent had to discover the hard way — the static-export constraint that forbids server features, the pre-push lint hook, the fixture file where all copy lives — becomes a standing instruction. This is the compounding step. Session one on a repository is exploration; session ten should start with ten sessions' worth of institutional knowledge already loaded. Repository instructions are how agent workflows accumulate skill instead of re-learning it.

OPERATIONAL PROBLEM
<one paragraph: what changes for the user/operation, how we'll know>

CONTEXT
<what I already know: relevant files, prior decisions, constraints>

SCOPE
In:  <the work>
Out: <explicit non-goals — things you must not touch this pass>

ACCEPTANCE CRITERIA
<numbered, individually checkable — commands or inspectable artifacts>

BOUNDARIES
- Work on branch <name>; never commit to main
- Permissions: <mode / allowlisted commands for this task>
- STOP and ask if: <task-specific stop conditions — e.g. "a migration
  seems necessary", "any acceptance criterion appears unachievable",
  "you need a credential or external account">

PROCESS
1. Inspect before changing; summarize what you find
2. Plan with exact files; wait for approval    [omit for small tasks]
3. Implement; validate continuously (lint, build, routes, screenshots)
4. End with the implementation report (format below)

REPORT FORMAT
What changed / What was verified / What was NOT done /
Claims needing me / Risks / Suggested commits

Nothing in this workflow is exotic — it's the same discipline good teams already apply to human contributors: understand the problem, agree on a plan, work on a branch, prove it with checks, review the diff, gate the deploy. The agent changes the economics of each step, not the steps. What it removes is grunt work; what it cannot remove is judgment about scope, risk, and doneness. The engineers getting the most out of Claude Code aren't the ones writing cleverer prompts — they're the ones who already knew how to run a change through a production process, and taught the process to the tool.