A recent Hacker News question had a title I recognised straight away: "How do you keep up quality when you vibe-code?" The poster, nkcodes, described an app where the AI-written code had grown too complex, nothing central said how the product should behave, and each bug fix had turned into "a game of whack-a-mole". They added the detail I think matters most: the agent doesn't track how new code fits the rest of the product.

Here is my answer in one line: vibe-coding doesn't lower quality, unchecked code does, and code stays unchecked when nobody wrote down what done means. The fix is three things you can put in your repo today: a written plan, a short definition of done the agent has to meet, and a rule that you read whole files before you accept a change.

The AI typing isn't the problem

It's tempting to blame the model. I don't think that's where it goes wrong. Anthropic's own Claude Code best-practices page names two common ways a session fails. Claude says it's done when it isn't quite, usually because it had no way to check its own work. Or it builds something other than what you had in mind, because the missing information isn't in the repo for it to read.

Both are the same gap seen from two sides. The agent stops when the work looks done. Without something to run that says whether it really is done, "looks done" is all it has. The page's phrasing for what happens next is the line I'd pin above every desk: in practice, the human becomes the test suite.

That is the whack-a-mole. You are the only check, so every fix gets checked from memory, and memory doesn't grow with the codebase.

Before

Done means it looks done

  • The plan lives in a chat that scrolled away
  • The agent stops when the output seems right
  • "All tests pass" is the whole report
  • You find the regression later, by hand

After

Done is written down

  • The plan is a file in the repo
  • A command returns pass or fail
  • The agent shows the command it ran and the output
  • You read the files before you accept

A plan the agent can open

The poster's second complaint, that nothing centrally defines how the product behaves, is the one a file fixes. My plan lives in the repo. The agent proposes against it, and I review. It's an unglamorous setup, which is most of its charm. The docs lean the same way: for a run nobody is watching, their first question is whether the agent knows what done looks like, and a spec file is one of their examples.

The plan also gives review a target. The page shows a review prompt where a subagent checks the diff against SPEC.md: is every requirement implemented, do the listed edge cases have tests, which gaps affect correctness. It skips style on purpose. The same page warns that a reviewer asked to find problems will always find something. With a plan, the question becomes "does this match what we agreed?"

Keep CLAUDE.md short next to it. The docs say not to describe your architecture and file layout there, because Claude reads the repo itself. Write down only what isn't already in the code.

A definition of done that says pass or fail

This is the part that does the most work. The docs' advice is to give Claude a check that returns pass or fail: a test file, a build's exit code, a linter, a script that diffs output against a fixture, a browser screenshot next to the mockup. If your repo already has one, the page calls the command that runs it the single most useful line in CLAUDE.md.

Then ask for evidence: the command it ran and its output, or the screenshot. The page is blunt that "All tests pass" on its own tells you very little.

One distinction worth respecting: CLAUDE.md is guidance, and the model is allowed to decide a guideline doesn't apply. If a check must run every time, it belongs in a hook. The docs show a Stop hook that runs a typecheck whenever Claude tries to end its turn, and sends it back to work if the check fails:

A Stop hook from the Claude Code docs

There is a ceiling: if the hook blocks eight stops in a row with no tool call in between, Claude Code ends the turn anyway. You still look at what came back.

Read the files, not just the diff

This rule is mine, not the docs'. Before I accept a change, I read the whole files it touched. A diff shows the lines that moved. It doesn't show the function above that now does the same job twice, or the screen that still calls the old path. That is exactly the poster's agent that doesn't track how new code fits the rest of the product. The fit only shows up in context.

The docs back the spirit of it from another angle: a reviewer that hasn't watched the code being written is more useful. /code-review reviews the diff in a fresh subagent that never saw the conversation, so it isn't swayed by the reasoning that produced the code. That's a good second pair of eyes. I still want mine on the file.

Nobody, human or model, can meet a bar that was never written down.

The short version

What to put in your repo today

  1. 1A plan file. SPEC.md or similar: what the feature does, its requirements, the edge cases you care about. Review against it.
  2. 2A definition of done. One command that returns pass or fail, written in a short CLAUDE.md, and a hook for anything that must run every time. Ask for the output, not the summary.
  3. 3A reading rule. No change is accepted until you've read the whole files it touched.

The parts that stay with you are the ones the docs leave with the human even for unattended runs: starting the run, deciding what done means this time, and approving the merge at the end. Let the agent type the rest.

Free checklistThe Done Gate: 5 proofs before a ticket closesFor the moment an agent says it's finished, so you close the ticket on proof, not on how it looks.Get the checklist