Skip to content
Topic hub

Claude Code Production Engineering

Shipping safely with Claude Code: checks that can actually fail, security, accessibility, Core Web Vitals, CI, environment config and release discipline.

15 guides in this hub, including a 8-step learning path.

There is a gap between "the feature works" and "this is safe to leave running", and agentic coding tools make that gap wider rather than narrower. They are fast at producing working code and indifferent to the operational questions nobody asked them: what happens when this fails, who can see this, what breaks if the third-party service is down, and how would anyone find out.

This hub is about closing that gap deliberately — security, accessibility, performance, CI, code review, and the release discipline that makes deploys boring.

Who this is for

Developers shipping to production, and small teams where the person writing the code is also the person on call. If you have a platform team enforcing this for you, most of it is already handled. If you do not, it is handled by whoever remembers, which is a bad plan that works right up until it does not.

For client work, verification has a commercial twin: the definition of done the client agreed to, the QA report before every review, and the readiness check before launch. The Agency & Client Delivery System makes those the gates of the engagement; the guides here are what the gates test.

The one idea everything here depends on

A check that has never failed is not a check. It is a line in a log file that says "PASS" for reasons nobody has established.

This sounds obvious and is routinely skipped, because a passing test feels like evidence. It is not, until you have seen it go red. Before trusting any automated check — a link crawler, a schema validator, a secret scanner, an accessibility pass — break the thing it is checking and confirm it notices, then restore and confirm it goes quiet again. Both directions matter: a check that fires on everything is as useless as one that fires on nothing, because both get ignored.

Every automated check behind this site was built that way, and doing so caught real defects that a green run would have hidden. An SEO crawler that stripped query strings never followed ?page=2, so a duplicate title on paginated pages was invisible to the very audit meant to find it. A diagram generator silently clipped subtitles that overflowed their box; adding a guard that raised on overflow immediately surfaced three diagrams that had been shipping clipped since publication.

Neither of those was found by review. Both were found by making a check capable of failing.

Security: the parts that actually bite

Web application security has a current reference point — the OWASP Top 10:2025 — and it is worth reading rather than half-remembering, because the categories moved. Software Supply Chain Failures is now its own entry, Security Logging and Alerting Failures was renamed, and Mishandling of Exceptional Conditions is new.

For a website built with an agentic tool, four risks dominate in practice.

Secrets reaching places they should not. Not just committed keys — a credential in a log line, in a generated document, in a screenshot, in a template, or copied into a downloadable artefact. The defence is structural: read credentials from a path outside the repository, run every diagnostic output through a redaction filter, and scan the whole tree for credential patterns as part of the test suite rather than at review time.

Client-side trust. Anything in front-end JavaScript is public. An API key in a bundle is disclosed, whatever the file is called.

Dependencies. Every package is code you are choosing to run. Every MCP server is a trust boundary you are choosing to open. The question is not whether they are malicious but whether you would notice if one became so.

Failing loudly enough. An error swallowed by a catch block is a security event nobody investigated. Logging that nobody reads is the same thing with extra steps.

Worth stating plainly: a defensive security review of code you own is not penetration testing, and conflating the two produces reports that are both alarming and useless.

Accessibility as a production concern

WCAG 2.2 is the current W3C Recommendation. AA is the level nearly every legal framework references, and the practical work divides cleanly in two.

What a machine can answer: missing alt attributes, colour contrast ratios, form controls without labels, heading order, duplicate or missing landmarks, focus visibility, and target size — with the caveat that success criterion 2.5.8 has five exceptions, and a checker that does not implement the inline one will flag every link inside a paragraph and destroy its own credibility.

What needs a person: whether alt text is useful, whether the reading order makes sense, whether an error message tells you how to fix the problem, and whether the whole flow can be completed with a keyboard. No tool answers these, and a report that implies otherwise is overstating what it found.

Keep the two categories separate in any audit you produce. Merging them is how "47 issues found" comes to mean nothing.

Performance, measured honestly

Core Web Vitals thresholds: LCP at or under 2.5 seconds, INP at or under 200 milliseconds, CLS at or under 0.1 — at the 75th percentile, segmented across mobile and desktop. INP replaced FID and has been the stable responsiveness metric since 2024.

Two consequences people skip. Lab tools cannot meaningfully measure INP, because it depends on what real users actually click — you need field data. And a good median can sit on a failing 75th percentile, so an average is not an answer.

The regressions that matter in practice are structural rather than incremental: an embed that arrives late and shifts the layout, an image without dimensions, a font swap that reflows a paragraph, a script that blocks rendering. Reserve space, set dimensions, defer what can be deferred, and treat a new third-party script as the significant decision it is.

CI, code review, and what to automate

The useful division is between things that must always be true and things that need judgement.

Automate the invariants. No secrets in the tree. Configuration files parse. Structured data is valid JSON. Internal links resolve. The declared page size matches the constant the layout uses to decide what to noindex — the kind of drift that silently drops a real page out of the index, and exactly the kind a human reviewer will never catch.

Review the judgement. Whether the abstraction is right, whether the error handling is meaningful, whether the change is scoped to what was asked. An agent reviewing a pull request is genuinely useful here, provided its findings are treated as a hypothesis to verify rather than a verdict.

Two failure modes to design against. Tooling so fragile that ordinary content changes break the build teaches everyone to bypass it. And a check that reads the paid or private half of a repository will fail on a public clone — skip it explicitly rather than letting it fail, so a green run stays meaningful in both places.

Environment configuration

Most production incidents in small projects are configuration, not code. Three rules cover most of it.

Configuration comes from the environment, secrets come from outside the repository. Those are different statements. A feature flag in a committed config file is fine. A token is not, even in a file you have gitignored — gitignore protects against one specific accident and nothing else.

Make the dangerous target require an explicit act. If the same command can deploy to staging or production depending on an argument you might forget, it will eventually deploy to production. Default to the safe target and require an environment variable to override. One line of code, one entire class of accident removed.

Assert the environment rather than assuming it. A script that needs a credential should fail immediately with a clear message when it is absent, not halfway through a multi-step operation with a stack trace. This matters more with an agent in the loop, because a partial failure is much harder to reason about than a refusal at the start.

What to test on a content-heavy site

Unit tests are not the interesting part here. The checks that repeatedly earn their keep on a website are the boring structural ones, and most of them are a few lines:

  • Every internal link and in-page anchor resolves.
  • Every JSON and configuration file parses.
  • No credential pattern appears anywhere in the tracked tree.
  • Structured data contains the types you expect and none you have forbidden.
  • Constants that must agree actually agree — the page size in a paginator and the page size the layout uses to decide what to noindex being the canonical example.
  • Claims made on the site still match the thing they describe. If a page says "100 prompts", something should count them.

That last one is the category people never automate and always regret. Marketing copy drifts from reality quietly, and the drift is only ever noticed by a customer.

Release discipline

Small, reversible, verified. Deploy something you can undo, then check the live URL rather than the preview — after DNS and caches have settled, because the interesting differences between local and production are exactly the ones that only appear there: canonical URLs, robots directives, redirect behaviour, and anything that depends on a response header.

Then check again the next day. Some failures are only visible once a crawler, a CDN, or a scheduled job has had a turn.

Where to go next

The path below runs from the general audit through security, accessibility, and CI. The full hub list underneath adds performance and the production CLAUDE.md guide, which is where most of this gets written down so it survives you not being in the room.

Learning path

Follow it in order

Each guide assumes the one before it. You can read them in any order, but this is the sequence that does not double back.

  1. Claude Code Website Audit: Complete Production Checklist

    An audit asks what is wrong with what already shipped, and which of it matters. Four passes in a deliberate order, prompts that produce evidence in...

    Intermediate12 min read

  2. Claude Code Website Security Audit: Complete Workflow

    An agent reads code, configuration and dependencies in full, reaches a deployed site only through its own requests, and must not attempt exploitati...

    Advanced12 min read

  3. Claude Code Accessibility Audit: Complete WCAG Workflow

    W3C is explicit that tools cannot do it all. This is the division of labour: what a scanner answers, what reading components adds, and the manual p...

    Intermediate13 min read

  4. Claude Code and GitHub: Actions, PR Review, and CI

    Mention @claude and it implements changes. Give it a prompt and it runs on every pull request without anyone asking. The second is where the value is.

    Advanced15 min read

  5. Deploy a Claude Code Website With GitHub Actions and Cloudflare: Complete CI/CD Workflow

    Continuous deployment is usually sold on speed, which is the least interesting thing about it. The reason to build one is that it is the only place...

    Advanced20 min read

  6. Playwright Testing With Claude Code: Forms, Links, and Regression Checks

    A dozen browser tests that catch what breaks silently on a marketing site, written with Claude Code, run, broken on purpose so you see the failure,...

    Intermediate14 min read

  7. Claude Code for Teams and Enterprise

    The question that matters is narrow: where does inference run, and who is billed. Everything else — policy, standards, rollout — is the same either...

    Advanced10 min read

  8. Claude Code Website Maintenance: A Safe Weekly Checklist

    Maintenance is inspection on a schedule that changes nothing, followed by small reversible fixes. The weekly checklist, the two prompts kept apart,...

    Intermediate14 min read

Start with Claude Code Website Audit: Complete Product...

Every guide in this hub

Including the reference pieces that do not belong in a sequence.

Browse the full guide library

Free resources for this topic

  • Claude Code Security Checklist

    A free website security checklist: secrets, headers, input handling, authentication, sessions, authorisation, webhooks, dependencies and CI/CD.

  • Claude Code Website Audit Checklist

    A free website audit checklist for sites that already exist: UX, conversion, broken links, technical SEO, accessibility, performance and security.

  • Claude Code Web Development Failure Library

    Twenty ways a website built with an AI coding assistant breaks quietly, with how to detect, fix and prove each one. Sixteen observed on this site.

  • Website Launch Readiness Score

    Twenty questions across SEO, performance, accessibility, security, analytics and deployment. A score out of 100 and a prioritised list of what to fix.

Related learning

  • Claude Code for Web Development

    The operational layer for building real websites with Claude Code: CLAUDE.md, prompting, skills, hooks, subagents and MCP, in the order they become useful.

  • Claude Code SEO

    Technical SEO with Claude Code, in dependency order: crawling, canonicals, indexing, structured data, Core Web Vitals, Search Console and internal linking.

  • Claude Code Shopify Development

    Building and running a Shopify store with Claude Code: themes, Liquid, the platform's silent failures, Shopify SEO, performance, accessibility and deployment.

  • Claude Code WordPress Development

    Using Claude Code on WordPress: reconnaissance, child themes, plugins, escaping, the database rule, and the audits that catch what review does not.

  • Claude Code Astro Development

    Building production Astro sites with Claude Code: content collections, islands, TypeScript as a check, SEO, and deploying to Cloudflare Workers.