Designing a Release Gate Claude Code Can Run — Pre-Deploy Verification You Can Actually Read

One Friday evening, just after I posted "shipping tomorrow morning" in Slack, tests that nobody had touched began failing. The cause traced back to a coworker's PR merged two weeks earlier and a tiny change I had merged that afternoon. A dependency bump in between had reshuffled the runtime, and the two changes happened to collide in a way that broke things only on main. CI had been green the whole time. So why was production about to burn?

For a long time I assumed "if CI is green, we are fine." But once we started letting Claude Code produce a steady stream of small improvement PRs, that assumption stopped holding. Tests miss what tests do not cover. Forgotten config updates and missing environment variables slip past unit tests entirely. Coverage reports do not flag what was never exercised.

So I built a thing I now refer to as a release gate: a check Claude Code runs right before any production deploy. The thing that separates it from a normal pre-deploy checklist is not the list itself — it is the requirement that Claude write down, in human-readable prose, why each item passed or failed. This article walks through how it works, why each piece is shaped the way it is, and the failures I had to live through to arrive at the current design.

Why "the reason it passed" needs to be readable

A gate that returns only pass/fail loses your team's trust over time. When green is the norm, nobody reads it. When red shows up, people dismiss it as "that flaky check again." At one point my team had thirty-plus check results pouring into Slack every day, and I could not name a single person who actually read them.

What changed things was treating the gate as a short review report, not a status badge. I instruct Claude Code to walk through seven checkpoints in order, and for each one to write three lines: (1) what it observed, (2) the verdict, (3) the reasoning behind that verdict.

claude review:release-gate --target=main --base=production

A successful run looks something like this:

[1/7] Database migration diff
  - Observed: 2 new files in prisma/migrations, 0 deleted
  - Verdict: PASS (reversible — no DROP statements; NOT NULL has DEFAULT)
  - Reasoning: migrations/20260428_add_user_locale.sql sets DEFAULT 'en'
    so existing rows are populated and rollback stays consistent

[2/7] Environment variables
  - Observed: .env.example diff +2 lines; production secrets unchanged
  - Verdict: BLOCK
  - Reasoning: GEMINI_API_KEY and STRIPE_WEBHOOK_SECRET were added to
    the example but not to the secrets manager. Deploy would 500.

When the gate is red, you can read the reason in one line. When it is green, the reasoning still tells you the gate actually looked. After running this for several months, I came to believe the persuasive force of a review lives in the visible chain of reasoning, not in the verdict itself.

The seven checkpoints I keep

These are the seven I have been running for a while. The exact set varies by project, but this skeleton has held up across very different services.

1. Database migration diff — Is it reversible? Any DROP / RENAME? If you added NOT NULL, did you also supply a default that populates existing rows?
2. Environment variables and secrets — Did every key added to .env.example actually land in the production secrets store?
3. API request/response compatibility — Will old clients still work against the new schema?
4. Dependency version changes — Any major bumps? Does the changelog mention breaking changes you did not address?
5. i18n key diff — If you added a Japanese key, did you also add the English one? (On my own sites, missing this triggers a 404 on language switch.)
6. Bundle size — Any chunk that grew dramatically?
7. Manual review of production-only paths — Stripe webhooks, email sending, third-party API calls — anything CI mocks out.

Each checkpoint is a small MCP tool or shell script. Claude Code calls them through Bash and converts the machine-readable JSON into prose. Splitting it that way made the tools individually testable, and it removed any room for Claude to "round numbers" while writing the report.

A small implementation per checkpoint — the env-var case

Early on I tried to cram everything into a single MCP tool. One release-gate tool, all seven checks inside, JSON out. Claude Code would just call it. Clean, beautiful — and useless within a week.

Two reasons. First, every check needs its own context. Migration safety wants schema history. The i18n diff wants to know how the article folders are organized. Second, what humans want from a review report is a story, not numbers. "Two reversible additive migrations" lands better than "DROP statements: 0."

The current setup is one independent tiny tool per checkpoint, plus Claude Code in the role of "call them in order, write one section of the report per result."

The env-var checker, for example, is just a shell script:

#!/usr/bin/env bash
# scripts/release-gate/env-diff.sh
set -euo pipefail
 
# Keys added to .env.example since the production branch
ADDED_KEYS=$(git diff "${BASE:-production}"...HEAD -- .env.example \
  | grep -E '^\+[A-Z_]+=' \
  | sed -E 's/^\+([A-Z_]+)=.*/\1/')
 
# Compare against Cloudflare Workers production secrets
EXISTING=$(npx wrangler secret list --env=production 2>/dev/null \
  | jq -r '.[].name')
 
MISSING=()
for key in $ADDED_KEYS; do
  echo "$EXISTING" | grep -qx "$key" || MISSING+=("$key")
done
 
if [ ${#MISSING[@]} -eq 0 ]; then
  echo '{"status":"PASS","added":'"$(jq -Rsc 'split("\n")|map(select(length>0))' <<< "$ADDED_KEYS")"'}'
else
  printf '{"status":"BLOCK","missing":%s}\n' \
    "$(printf '%s\n' "${MISSING[@]}" | jq -Rsc 'split("\n")|map(select(length>0))')"
fi

I hand the JSON output to Claude Code with prompt instructions like: "If PASS, say 'all N added variables exist in production.' If BLOCK, list the missing keys and ask the operator to add them before deploy." The output structure stays fixed and Claude only writes the prose. This split dramatically reduced drift between runs.

Migration safety, with the evidence quoted back at you

Migrations are one of the highest-risk surfaces. My implementation runs five regex patterns over the raw SQL and labels each finding with a severity, then hands the findings to Claude.

// scripts/release-gate/migration-safety.ts
import { readdir, readFile } from "node:fs/promises";
import { join } from "node:path";
 
interface Finding {
  file: string;
  pattern: string;
  severity: "block" | "warn" | "note";
  excerpt: string;
}
 
const PATTERNS: Array<[RegExp, string, Finding["severity"]]> = [
  [/\bDROP\s+TABLE\b/i, "DROP TABLE", "block"],
  [/\bDROP\s+COLUMN\b/i, "DROP COLUMN", "warn"],
  [/\bRENAME\s+(TO|COLUMN)\b/i, "RENAME", "warn"],
  [/\bNOT\s+NULL\b(?![^;]*DEFAULT)/i, "NOT NULL without DEFAULT", "block"],
  [/\bALTER\s+COLUMN\s+\S+\s+TYPE\b/i, "TYPE change", "warn"],
];
 
export async function inspect(dir: string): Promise<Finding[]> {
  const files = (await readdir(dir)).filter((f) => f.endsWith(".sql"));
  const findings: Finding[] = [];
  for (const file of files) {
    const sql = await readFile(join(dir, file), "utf8");
    for (const [re, name, severity] of PATTERNS) {
      const match = sql.match(re);
      if (match) {
        findings.push({
          file,
          pattern: name,
          severity,
          excerpt: sql.slice(Math.max(0, match.index! - 30), match.index! + 80),
        });
      }
    }
  }
  return findings;
}

Claude Code receives the array and applies the rule "any block → BLOCK, only warns → WARN, empty → PASS." For each finding, it must quote the excerpt and then say what could happen because of that line. Forcing a quote of the matched line is the trick that prevents Claude from inventing concerns that are not in the SQL — every claim has to point at evidence the regex actually surfaced.

Wiring it together: the slash command

With the per-checkpoint scripts in place, I expose the whole sequence as a Claude Code slash command.

// .claude/commands/release-gate.json
{
  "description": "Run pre-deploy verification and write a readable report",
  "system": "You are the engineer responsible for pre-deploy verification. Do not just transcribe tool output; write a human-readable report. Follow each tool's BLOCK/WARN/NOTE verdict, and when in doubt, downgrade by one level.",
  "steps": [
    { "tool": "git_diff_summary", "args": { "base": "production" } },
    { "tool": "migration_safety_check", "args": { "path": "prisma/migrations" } },
    { "tool": "env_var_diff", "args": { "example": ".env.example" } },
    { "tool": "api_compat_check" },
    { "tool": "deps_changelog_summary" },
    { "tool": "i18n_key_diff" },
    { "tool": "bundle_size_diff" }
  ],
  "output": "report.md"
}

After all seven sections are written, Claude Code reads report.md back and appends an overall verdict (GO / NO-GO / WAIT). The decision rules are written into the prompt: "If migrations is red, NO-GO. If env vars is red, request the missing values and WAIT. Anything else red is WAIT pending human review."

Designing the way you go red — to avoid alert fatigue

A subtle thing I learned the hard way: you have to design how the gate goes red. Make everything red and your team stops reading the gate within a fortnight. The three tiers I settled on are:

• BLOCK (red) — Will cause an incident if shipped. Data loss in migrations, missing secrets, etc.
• WARN (yellow) — Will work, but is unhealthy. Sudden chunk size growth, dependency major bump, unread changelog.
• NOTE (blue) — Worth recording. New i18n keys added, additive API changes, etc.

A single BLOCK in our setup automatically halts the deploy. WARN only notifies a human. NOTE just goes into the report for posterity. I tell Claude Code to "downgrade by one level if you are not sure," because an agent that throws BLOCKs around quickly stops being trusted.

The unexpected benefit of this split was the explicit permission to ignore WARN. Some releases are full of WARNs. Others are zero-zero. Aiming exclusively for the latter pushes PRs to grow until review burden eclipses the safety the gate provides — a paradox I did not see until the team had been on the gate for a couple of months.

Tying the report back into release notes

Once the gate had been running for a while, I noticed an unexpected side benefit: report.md is basically a draft of the release notes. Pull each "reasoning" line out, polish it, and you have most of what users need to know.

claude release-notes --from=report.md --audience=end-user

The command extracts user-facing changes from the report and rewrites them in plain Japanese and English. I now spend almost no time writing release notes — I just review what Claude produced. Telling Claude "write for end users; do not use internal jargon" keeps internal implementation language out of the public-facing copy.

Bake rollback steps into the gate

Another addition that came later: rollback steps generated alongside each verdict. For every checkpoint, Claude Code writes one sentence about how to undo the change.

[1/7] Database migration diff
  - Verdict: PASS
  - Rollback: run `prisma migrate resolve --rolled-back 20260428_add_user_locale`,
    then `git revert` on the production branch is safe

This single addition changed how the team handles incidents. "The rollback steps are in report.md" became the on-call mantra. When something goes wrong at 2 AM, the first action is to open the report — not to flail in the dashboard. The release gate stops being only about "going forward safely" and becomes "knowing how to step back."

A pitfall: do not let the gate be the final authority

One last lesson, from a failure I caused. A few weeks into running the gate, Claude Code returned an unconditional GO on a PR. I merged it, and production started miscalculating rate limits. The cause: my API compatibility check looked at request and response schemas only — not semantic compatibility, where the same shape carries new meaning.

After that I rewrote the gate's role in my head. It is not a replacement for human review. It is a tool that catches the routine things humans miss. The very first instruction Claude Code receives is: "Even if you say GO, a human's NO-GO wins." Agent collaboration becomes brittle the moment ultimate responsibility stops resting with a person.

A related habit followed: the gate's own code goes through the gate. Every PR that updates the release-gate scripts is reviewed by the very scripts being updated. It looks self-referential, but it is the cheapest way to discover holes in the gate from the PR review — instead of from the next production incident.

One thing to start with this week

This has been a long article. Let me leave you with exactly one place to start. Building the whole release gate is weeks of work, but the environment variable diff alone takes about half an hour. Run git diff on .env.example, compare against your production secrets store (or wrangler.toml), and let Claude Code report what is missing. That single check eliminated half of our deploy incidents.

You do not need a perfect gate from day one. Automate the place that hurts most often, one checkpoint at a time. What does your team's most common release incident look like? Build that one check first, and ask Claude Code to write you the reasoning. The rest of the gate can follow as the pain demands.