Claude Code in Production: Build Apps Without Vibe Coding

I have seen a publishing sheet say “Published” while the corresponding article was missing from the live blog. I cannot pin that incident on one edit or one tool. It exposed a simpler problem: a successful build and a completed task list had been treated as proof that the user-facing workflow worked. They were not.

That is the line between using Claude Code to build a real app and vibe coding one. Start with a short product contract, cut it into end-to-end slices, and require evidence at each boundary. Claude can explore the repository, edit files, and run checks. The founder or engineer still owns the behavior the app must deliver. The same handoff problem appears in my marketing system build: each downstream artifact needs to inherit the decision above it.

What belongs in a PRD before Claude Code touches the app?

A useful PRD is a decision document, not a giant feature wish list. It should name the user, the job they need done, the current failure, the smallest successful workflow, the important constraints, and what will deliberately wait. If the team cannot agree on those points, letting an agent code faster only moves the disagreement into the repository.

For a publishing app, I would write the first page like this:

PRD field	Working answer
User and job	An editor needs to publish an approved article and confirm it appears on the live site.
Successful path	Valid article data becomes a detail page and an entry in the blog index.
Failure behavior	Invalid metadata blocks publication with a specific error; a failed deploy does not mark the article live.
Constraints	Preserve existing URLs, image references, and unrelated pages.
Out of scope	Redesigning the work page, rebuilding the CMS, or changing every old article.
Acceptance	The deployed index and detail URL both return the intended article and image.

This is an illustrative contract, not a claim that my current site was built from this exact PRD. The distinction matters. I know the missing-blog symptom; I would not invent a root cause to make a cleaner story. In a client build, I would also add who can approve release, where sensitive data lives, and what rollback means.

Anthropic’s Claude Code best-practices guide recommends exploring the codebase before planning a multi-file change and giving Claude specific files, constraints, and a verifiable finish line. I would keep the PRD in the repo so each task can point to the same approved source.

How small should a Claude Code task be?

Slice by a user-visible outcome, not by technical layer. “Build the database, then the API, then the UI” can leave three apparently finished components that have never worked together. A better slice lets one user complete one narrow path through the system, with its own tests and reviewable diff.

For the publishing example, I would sequence the work this way:

1. Accept and validate one article record. Reject a missing slug or duplicate slug with a clear error.
2. Render that article at its detail URL. Verify title, body, metadata, and image.
3. Add it to the blog index, ordered correctly, without removing existing posts.
4. Make publication status depend on a successful deployment check, not on a spreadsheet label alone.

Each slice has a definition of done. It changes only the files needed for that path, carries a targeted test, and leaves the app runnable. The slice is too large when Claude must decide product behavior, architecture, and release policy in the same pass. The slice is too small when it is merely “create a component” with no user outcome.

I would ask Claude to map dependencies and unknowns in plan mode before editing. Anthropic recommends that for uncertain, multi-file work, while noting that small, obvious changes do not need ceremony. The plan gets reviewed, then implementation starts. A plan is not an acceptance test.

What should you put in CLAUDE.md, and what stays in the task?

Put stable repository facts in CLAUDE.md: the stack, build and test commands, architectural boundaries, and non-obvious rules. Put temporary feature requirements in the PRD and task. Mixing them makes the always-loaded file grow until nobody, human or model, can see the few rules that matter.

Anthropic’s guidance on CLAUDE.md says to keep it concise and include instructions the model cannot simply infer by reading code. For an app, that might be: use the existing router, run the targeted test before the full suite, never edit a migration without review, and do not commit secrets. I would not paste the whole product roadmap into it. My Claude Code for small business analysis makes the same resource point: a small team cannot afford to make a large harness the product.

Here is the task shape I would send after approving one slice:

Read PRD.md and the existing article publishing path.
Implement only slice 2: render one validated article at its detail URL.
Preserve existing slugs and unrelated pages.
Before editing, list the files you expect to touch and the test you will run.
Add or update the targeted test, implement the slice, then run the test and build.
Show the diff, test output, and any behavior you could not verify.
Stop before deployment.

The important line is “only slice 2.” It gives Claude enough autonomy to solve the engineering problem without silently expanding the product decision.

Which tests prove the app works rather than merely compiles?

Use a test ladder that matches the risk: unit tests for rules, integration tests for boundaries, browser checks for user journeys, and a post-deploy smoke test for the live route. A green build proves the application can build. It does not prove that the editor can publish or that visitors can find the result.

For the publishing path, I would require:

• Rule test: an empty or duplicate slug is rejected; a valid record is accepted.
• Integration test: the content record maps to the expected route and metadata.
• Browser test: the index links to the article, the page loads, and the cover renders.
• Release smoke test: after deployment, fetch the index and detail URL and verify the expected title. If this fails, do not mark the article “Published.”

That last check is the one my missing-blog incident makes impossible to ignore. It is not a claim that a browser test alone would have prevented the original issue. The cause remains unverified. It is a gate that would catch the visible failure before declaring success.

Anthropic says to give Claude a check it can run, such as tests, a build, or a screenshot, and ask for the output rather than a success claim. GitHub’s status-check documentation explains how CI checks can be required before merging. Use those gates for repeatable failures. Keep human review for behavior, security, data handling, and changes the tests do not understand.

When is the pull request ready to merge and deploy?

A pull request is ready when it satisfies the approved slice, has a comprehensible diff, passes the required checks on the current commit, and states what remains unverified. “Claude says done” is not a release criterion. Neither is a wall of green tests if the tests never exercised the real user path.

My review checklist is short:

1. Does the diff stay inside the agreed scope? Inspect deleted and renamed files, not just additions.
2. Do the tests cover the failure mode from the PRD, including at least one negative case?
3. Did someone use the feature in a running app or preview?
4. Are secrets, permissions, external calls, and data migrations reviewed separately?
5. Is rollback clear if the deployed behavior differs from the preview?

For a small change, that can be one human and a few minutes. For payments, authentication, or migrations, it should be stricter. I would not replace judgment with a huge harness of agents and hooks just to make the process look mature. Use deterministic CI for deterministic checks; add automation only where a recurring mistake justifies it. Anthropic notes that hooks run automatically, while CLAUDE.md instructions are advisory. That is a useful distinction, but a hook does not make a weak acceptance test strong.

FAQ

Do I need a long PRD to use Claude Code?

No. A one-page contract covering the user, successful path, failure behavior, constraints, out-of-scope work, and acceptance criteria is enough for many app features. Expand it only when the risk or number of decision-makers demands more detail.

Should Claude Code write the tests or should I write them first?

Either can work. The acceptance behavior must be agreed before the implementation. Claude can draft tests, but a human should check that they test the right behavior and do not merely bless the code it just wrote.

Can I let Claude Code build the whole app in one session?

It can work across a large codebase, but one unreviewed session is a poor release unit. Break the app into user-visible slices, verify each one, and preserve a working state between them. Large autonomous runs need stronger checks, not less supervision.

Is plan mode enough to stop vibe coding?

No. Plan mode helps expose assumptions and scope before edits. It cannot prove the result works. Tests, a running-app review, a diff review, and a post-deploy check close the loop.

The release rule

The expensive mistake is not letting AI write code. It is declaring the work complete from artifacts that are one step removed from the user’s experience. Give Claude Code a narrow contract, let it execute, and demand evidence from the actual path a person will use. This workflow will not eliminate every production bug or replace an experienced reviewer. It makes the gap between “code generated” and “user outcome verified” visible before that gap reaches a customer. On your next feature, write the acceptance check before the first implementation prompt.