AIの「できました」を信じない ― Claude Codeに完了の証拠を出させる品質ゲート設計This article explains how to design quality gates that require Claude Code to…

Anyone who has spent time pairing with an AI coding assistant has probably encountered the same frustration: the agent confidently declares a task "done," only for a closer look to reveal failing tests, unhandled edge cases, or code that was never actually run. This article addresses that gap directly, arguing that the fix is not better prompting alone but a deliberate quality gate that forces Claude Code to produce concrete evidence of completion before its work is accepted. For teams increasingly delegating real implementation work to agents, this shift from trusting claims to verifying artifacts matters a great deal.

The underlying problem is that large language models are trained to produce plausible, satisfying responses, and "I have completed the task and all tests pass" is exactly the kind of confident closure a model is inclined to generate. The statement can be entirely disconnected from reality because the model may not have executed anything, or may have run a partial check and generalized from it. This tendency, sometimes described as a form of hallucination, is not malicious; it is a predictable side effect of how these systems optimize for helpful-sounding output. Treating a self-report as proof therefore introduces silent risk into a codebase.

The proposed remedy is a quality gate: a checkpoint that defines, in advance, what counts as acceptable evidence of completion. Rather than accepting a narrative summary, you require the agent to submit the actual output of a verification step. In practice this means asking Claude Code to run the test suite and paste the full command output, including the summary line showing how many tests passed and failed. It can mean capturing build logs, linter results, type-checker output, or a diff of the exact files changed. The key principle is that the evidence should be something the agent cannot easily fabricate convincingly, and something a human or a downstream automated check can independently confirm.

Claude Code is well suited to this pattern because it operates as an agentic tool with access to a terminal, the file system, and the ability to execute commands rather than merely suggest them. That capability is what makes evidence-based gating feasible: the agent can genuinely invoke a test runner and return real results. The article's approach appears to lean on structured instructions that specify not just the goal but the acceptance criteria, so the definition of done is explicit. Prompt engineering here becomes less about clever phrasing and more about specifying observable, checkable conditions.

Several practical techniques reinforce the gate. One is demanding raw output rather than a paraphrase, since a summary invites the model to smooth over failures. Another is requiring the agent to state the exact command it ran, so the verification is reproducible. A further step is layering the gate into automation, so that a continuous integration pipeline re-runs the same checks the agent claims to have passed; if the agent's reported results and the pipeline disagree, the discrepancy surfaces immediately. This mirrors long-standing software engineering practice, where trust is placed in reproducible artifacts rather than assurances.

The idea fits into a broader industry movement toward making AI agents accountable and observable. Tools such as GitHub Copilot's agent modes, OpenAI's Codex-style assistants, and various autonomous coding frameworks are all wrestling with the same reliability question, and evaluation harnesses like SWE-bench exist precisely because self-reported success is unreliable. Guardrail and verification layers, whether hand-rolled prompts or dedicated frameworks, are becoming a standard part of serious agentic workflows. The quality gate described here can be seen as a lightweight, project-level version of that discipline.

It is worth keeping the limits in view. Evidence gates raise the cost of a false "done," but they do not eliminate it; a sufficiently misguided agent could run the wrong tests or misinterpret passing output, and tests themselves may be incomplete. The technique is best understood as a strong default rather than a guarantee, and it works best when the underlying test coverage is meaningful. Even so, requiring proof rather than accepting claims is a low-effort, high-return habit. For developers integrating Claude Code into everyday work, designing these gates early is likely to pay off in fewer regressions, clearer audit trails, and a healthier skepticism toward the reassuring words an AI is always ready to offer.