| Stage | Traditional SDLC | AI-native SDLC |
| Plan | Requirements gathered by committee, distilled through workshops and sign-offs, written up by hand | Claude synthesizes pain points straight from the sources and captures them within intent.md which is human readable and machine actionable |
| Design | Spec written by analysts, parsed by designers | Requirements and design compressed into one working session with an agent, guided by standards encoded as skills, versioned in git |
| Build | Tests and code are handwritten and documentation is written after the main development happens | Tests and code are generated by AI and institutional knowledge is maintained as versioned machine-readable CLAUDE.md files and skills |
| Test | QA gates at stage boundaries | Continuous evals woven through implementation |
| Deploy | Humans review every line of code and governance occurs in review cycles, often inconsistently | Layers of agentic review with human review reserved for regulated and critical code. Governance is enforced as the AI acts, with hooks as approval gates |
| Maintain | Humans watch production for bugs | Agents monitor live deployments. Any breached control band is diagnosed and written back into the loop as a new intent.md |
intent.md, spec.md, plan.md, the diff and its tests, the PR with its review findings, and the incident record) and the next stage begins by reading it. For the early stages, .md files are the predominant artifact because a product owner and an agent can both read and act on the same file. From Build onward, the artifact is code and its records. The chain of commits is also the audit trail: who asked for what, what the agent produced, and who approved it."
},
{
"type": "paragraph",
"text": "Humans remain accountable for every decision that requires judgment. In the agentic SDLC world, the human attention shifts along with the artifacts that must be reviewed.",
"html": "Humans remain accountable for every decision that requires judgment. In the agentic SDLC world, the human attention shifts along with the artifacts that must be reviewed."
},
{
"type": "paragraph",
"text": "Every stage commits an artifact the next stage can read. Together, the intent, the spec, the plan, the diff and the review findings are the audit trail.",
"html": "Every stage commits an artifact the next stage can read. Together, the intent, the spec, the plan, the diff and the review findings are the audit trail."
},
{
"type": "heading",
"level": 2,
"text": "Plays",
"html": "Plays"
},
{
"type": "paragraph",
"text": "The plays are the core of the playbook and are grouped into six non-linear stages (Plan, Design, Build, Test, Deploy, Maintain), which together cover the complete lifecycle.",
"html": "The plays are the core of the playbook and are grouped into six non-linear stages (Plan, Design, Build, Test, Deploy, Maintain), which together cover the complete lifecycle."
},
{
"type": "paragraph",
"text": "Each play covers:",
"html": "Each play covers:"
},
{
"type": "list",
"ordered": false,
"items": [
{
"text": "What changes;",
"html": "What changes;"
},
{
"text": "Getting started;",
"html": "Getting started;"
},
{
"text": "Concrete steps for implementation;",
"html": "Concrete steps for implementation;"
},
{
"text": "Governance considerations; and",
"html": "Governance considerations; and"
},
{
"text": "How you measure whether it worked.",
"html": "How you measure whether it worked."
}
]
},
{
"type": "paragraph",
"text": "These steps are modular and organizations may choose to prioritize transforming different stages at different times based on their unique needs. Each play names its dependencies under \"Prerequisites,\" which the dependency graph further illustrates.",
"html": "These steps are modular and organizations may choose to prioritize transforming different stages at different times based on their unique needs. Each play names its dependencies under "Prerequisites," which the dependency graph further illustrates."
},
{
"type": "paragraph",
"text": "A stage ends by committing an artifact with the commit initiating the next stage. An accepted intent.md triggers the requirements and design pass, an approved spec.md triggers plan mode, a merged PR triggers the pipeline, and a breached control band in production writes the next intent.md and so the loop continues.",
"html": "A stage ends by committing an artifact with the commit initiating the next stage. An accepted intent.md triggers the requirements and design pass, an approved spec.md triggers plan mode, a merged PR triggers the pipeline, and a breached control band in production writes the next intent.md and so the loop continues."
},
{
"type": "paragraph",
"text": "First, you prompt each step by hand with the end state being a loop in which each accepted artifact fires the next gate. Human attention concentrates at the gates, reviewing what the agent flagged rather than starting each stage from scratch.",
"html": "First, you prompt each step by hand with the end state being a loop in which each accepted artifact fires the next gate. Human attention concentrates at the gates, reviewing what the agent flagged rather than starting each stage from scratch."
},
{
"type": "image",
"src": "https://cdn.prod.website-files.com/68a44d4040f98a4adf2207b6/6a8855c75344623fc81efcb8_5d5a3c05.png",
"alt": "",
"caption": "The plays are listed with stage; the arrows give the order to adopt them in. The two are not the same. Start with any clay play — nothing points into it, so it needs nothing first. For any other play, the arrows pointing into it are the plays to adopt before it.",
"local": "img/03.png"
},
{
"type": "paragraph",
"text": "01",
"html": "01"
},
{
"type": "heading",
"level": 2,
"text": "Plan",
"html": "Plan"
},
{
"type": "paragraph",
"text": "Ideas stop waiting for someone to write them up. Intent is captured once, in the originator's own words, as a version-controlled artifact the next stage can act on.",
"html": "Ideas stop waiting for someone to write them up. Intent is captured once, in the originator's own words, as a version-controlled artifact the next stage can act on."
},
{
"type": "heading",
"level": 3,
"text": "Capture as intent.md",
"html": "Capture as intent.md"
},
{
"type": "paragraph",
"text": "The intent.md , which kicks off the software development process can enter through different routes. A person has an idea, a ticket is filed, or an incident is surfaced via an alert (see Stage 6: Maintenance).",
"html": "The intent.md, which kicks off the software development process can enter through different routes. A person has an idea, a ticket is filed, or an incident is surfaced via an alert (see Stage 6: Maintenance)."
},
{
"type": "paragraph",
"text": "When a person has an idea, they brainstorm with Claude and produce a markdown proto-spec. In the traditional SDLC, the same person must then convince a member of the product team to write the idea up with them or on their behalf.",
"html": "When a person has an idea, they brainstorm with Claude and produce a markdown proto-spec. In the traditional SDLC, the same person must then convince a member of the product team to write the idea up with them or on their behalf."
},
{
"type": "paragraph",
"text": "The proto-spec generated by Claude is human readable, version-controlled, and immediately consumable by the next stage. The proto-spec is saved as an intent.md .",
"html": "The proto-spec generated by Claude is human readable, version-controlled, and immediately consumable by the next stage. The proto-spec is saved as an intent.md."
},
{
"type": "paragraph",
"text": "Regardless of whether the intent originates from an event trigger or an agent, the same steps apply: the product owner reviews and corrects the agent-written intent.md before it is committed.",
"html": "Regardless of whether the intent originates from an event trigger or an agent, the same steps apply: the product owner reviews and corrects the agent-written intent.md before it is committed."
},
{
"type": "paragraph",
"text": "TraditionalAn idea passes through backlog entries, user stories, story points, and refinement meetings before anyone can act on it. Ownership transfers at each handoff, so what reaches engineering is several steps removed from what the originator meant.AI-nativeThe originator brainstorms with Claude and writes the result down as intent.md , a proto-spec in the originator's own terms. The artifact contains what is wanted, why, and under which constraints. Repeat processes are encoded via skills.",
"html": "TraditionalAn idea passes through backlog entries, user stories, story points, and refinement meetings before anyone can act on it. Ownership transfers at each handoff, so what reaches engineering is several steps removed from what the originator meant.AI-nativeThe originator brainstorms with Claude and writes the result down as intent.md, a proto-spec in the originator's own terms. The artifact contains what is wanted, why, and under which constraints. Repeat processes are encoded via skills."
},
{
"type": "paragraph",
"text": "Getting started Prerequisites None. Infrastructure Claude access for people who are not engineers (claude.ai or Cowork ); an agreed intent.md template; a shared, version-controlled home for intent that the product owner watches. For a single product the simplest home is an intent/ folder in the product repo. This setup keeps the artifact chain next to the code derived from it. A dedicated intent repo is only worth the overhead when intent spans many repositories, and in a monorepo it is a directory. The Stage 3: Build sidebar covers how this home relates to a Jira or requirements tool that already holds the record.",
"html": "Getting startedPrerequisitesNone.InfrastructureClaude access for people who are not engineers (claude.ai or Cowork); an agreed intent.md template; a shared, version-controlled home for intent that the product owner watches. For a single product the simplest home is an intent/ folder in the product repo. This setup keeps the artifact chain next to the code derived from it. A dedicated intent repo is only worth the overhead when intent spans many repositories, and in a monorepo it is a directory. The Stage 3: Build sidebar covers how this home relates to a Jira or requirements tool that already holds the record."
},
{
"type": "paragraph",
"text": "Setting this up is a one-time task for the platform or engineering team. A technical team member needs to stand up the intent home and decide who can write to it, since many contributors will come from across the organization.",
"html": "Setting this up is a one-time task for the platform or engineering team. A technical team member needs to stand up the intent home and decide who can write to it, since many contributors will come from across the organization."
},
{
"type": "paragraph",
"text": "Once the repository exists, contributors without git experience don't need to use git directly. Instead a connector to the version-control system (e.g. GitHub) lets Claude commit markdown files on their behalf from claude.ai or Cowork.",
"html": "Once the repository exists, contributors without git experience don't need to use git directly. Instead a connector to the version-control system (e.g. GitHub) lets Claude commit markdown files on their behalf from claude.ai or Cowork."
},
{
"type": "heading",
"level": 4,
"text": "How to execute it",
"html": "How to execute it"
},
{
"type": "list",
"ordered": true,
"items": [
{
"text": "The originator describes the problem to Claude in their own words. The originator may describe what they cannot do today, who is affected by the idea, what better looks like, or what is out of scope. No formal language is required.",
"html": "The originator describes the problem to Claude in their own words. The originator may describe what they cannot do today, who is affected by the idea, what better looks like, or what is out of scope. No formal language is required."
},
{
"text": "Brainstorm until the idea is concrete. Claude asks the questions an analyst would ask: scope, users, constraints, and what success looks like.",
"html": "Brainstorm until the idea is concrete. Claude asks the questions an analyst would ask: scope, users, constraints, and what success looks like."
},
{
"text": "Ask Claude to write the result as intent.md using the organization's template, which can be encoded as a skill set up by a technical team member and signed off by a lead. This can cover the problem, proposed outcome, affected users and systems, constraints, and open questions.",
"html": "Ask Claude to write the result as intent.md using the organization's template, which can be encoded as a skill set up by a technical team member and signed off by a lead. This can cover the problem, proposed outcome, affected users and systems, constraints, and open questions."
},
{
"text": "The originator corrects anything Claude misunderstood.",
"html": "The originator corrects anything Claude misunderstood."
},
{
"text": "Commit intent.md to the shared home. Author and timestamp join the record, and the product owner picks the idea up from there.",
"html": "Commit intent.md to the shared home. Author and timestamp join the record, and the product owner picks the idea up from there."
}
]
},
{
"type": "code",
"text": "# Intent: claims status self-service\n\n\nAuthor: J. Ortiz (claims operations). Status: draft.\n\n\n\n## Problem\n\n\nCustomers phone the contact center to ask where their claim is.\n\nHandlers spend roughly a third of call time on status-only queries.\n\n\n\n## Proposed outcome\n\n\nCustomers see claim status, next step and expected date in the portal.\n\n\n\n## Affected users and systems\n\n\nClaims handlers, portal team, claims-core API.\n\n\n\n## Constraints\n\n\nNo new PII in the portal session. Existing authentication only.\n\n\n\n## Open questions\n\n\nDo third-party loss adjusters need access too?",
"lang": "markdown"
},
{
"type": "heading",
"level": 4,
"text": "Governance considerations",
"html": "Governance considerations"
},
{
"type": "paragraph",
"text": "The evidence is the committed intent.md , which lists the author, the timestamp and the full revision history. It's logged in the git history of the intent home. The product owner approves, and the accept or reject decision that sends the intent into Stage 2: Design is recorded as the merge or the closing review.",
"html": "The evidence is the committed intent.md, which lists the author, the timestamp and the full revision history. It's logged in the git history of the intent home. The product owner approves, and the accept or reject decision that sends the intent into Stage 2: Design is recorded as the merge or the closing review."
},
{
"type": "paragraph",
"text": "How to measure it Leading indicator Time from first conversation to a committed intent.md , read from git history on the intent home, which records author and time stamp. The expectation is to fall from a multi-week elicitation and refinement cycle to hours. Lagging indicator The survival rate, or the share of intent.md files that the product owner accepts into Stage 2: Design rather than closes. The accept or reject decision is recorded as the merge of the artifact or the closed review. Additionally, the number of changes made to the intent.md that are made after the first spec.md commit for the same change.",
"html": "How to measure itLeading indicatorTime from first conversation to a committed intent.md, read from git history on the intent home, which records author and time stamp. The expectation is to fall from a multi-week elicitation and refinement cycle to hours.Lagging indicatorThe survival rate, or the share of intent.md files that the product owner accepts into Stage 2: Design rather than closes. The accept or reject decision is recorded as the merge of the artifact or the closed review. Additionally, the number of changes made to the intent.md that are made after the first spec.md commit for the same change."
},
{
"type": "paragraph",
"text": "02",
"html": "02"
},
{
"type": "heading",
"level": 2,
"text": "Design",
"html": "Design"
},
{
"type": "paragraph",
"text": "Requirements and design collapse into one session. Policy is applied while the spec is written, not discovered in a review weeks later.",
"html": "Requirements and design collapse into one session. Policy is applied while the spec is written, not discovered in a review weeks later."
},
{
"type": "heading",
"level": 3,
"text": "Requirements and design",
"html": "Requirements and design"
},
{
"type": "paragraph",
"text": "Once approved by the product owner, Claude takes the accepted intent.md and produces a requirements and design spec. This is guided by the organization's skills for brand, security, compliance, and UX.",
"html": "Once approved by the product owner, Claude takes the accepted intent.md and produces a requirements and design spec. This is guided by the organization's skills for brand, security, compliance, and UX."
},
{
"type": "paragraph",
"text": "The product owner reviews that spec, but doesn't write it. The goal of this process is to create a spec the engineering team can plan against, with flagged areas of concern.",
"html": "The product owner reviews that spec, but doesn't write it. The goal of this process is to create a spec the engineering team can plan against, with flagged areas of concern."
},
{
"type": "paragraph",
"text": "Front-end work is the clearest example. Once the intent.md is accepted, the product owner mocks the design up in Claude Design (beta) from the intent.md , iterates on the mock, and then exports it to Claude Code to build.",
"html": "Front-end work is the clearest example. Once the intent.md is accepted, the product owner mocks the design up in Claude Design (beta) from the intent.md, iterates on the mock, and then exports it to Claude Code to build."
},
{
"type": "paragraph",
"text": "TraditionalRequirements and design are separate phases run by separate teams. Analysts formalize the idea into requirements and designers then parse those back into a design. The separation exists for accountability, but it is slow and lossy.AI-nativeBoth phases happen in a single prompted session. Claude takes intent.md and produces a requirements and design spec, constrained by the organization's skills, with areas of concern flagged.",
"html": "TraditionalRequirements and design are separate phases run by separate teams. Analysts formalize the idea into requirements and designers then parse those back into a design. The separation exists for accountability, but it is slow and lossy.AI-nativeBoth phases happen in a single prompted session. Claude takes intent.md and produces a requirements and design spec, constrained by the organization's skills, with areas of concern flagged."
},
{
"type": "paragraph",
"text": "Getting started Prerequisites Write an intent.md file, with brand, security, compliance, and UX policies written as skills. Infrastructure A product owner with Claude access. No engineering skill is required.",
"html": "Getting startedPrerequisitesWrite an intent.md file, with brand, security, compliance, and UX policies written as skills.InfrastructureA product owner with Claude access. No engineering skill is required."
},
{
"type": "heading",
"level": 4,
"text": "How to execute it",
"html": "How to execute it"
},
{
"type": "list",
"ordered": true,
"items": [
{
"text": "The product owner opens a session with the organization's skills available and attaches the intent.md .",
"html": "The product owner opens a session with the organization's skills available and attaches the intent.md."
},
{
"text": "The product owners prompt points at the intent.md , names the constraints, and demands flagged concerns. Run it by hand at first, then codify it as an organization-level slash command. From there make the acceptance of intent.md in the intent home the trigger, with a non-interactive job that fires on the merge, run the pass with the organization's skills loaded, and commit spec.md as a pull request (the CI/CD play in Stage 5: Deploy covers the plumbing). From that point the product owner's first involvement is the review.",
"html": "The product owners prompt points at the intent.md, names the constraints, and demands flagged concerns. Run it by hand at first, then codify it as an organization-level slash command. From there make the acceptance of intent.md in the intent home the trigger, with a non-interactive job that fires on the merge, run the pass with the organization's skills loaded, and commit spec.md as a pull request (the CI/CD play in Stage 5: Deploy covers the plumbing). From that point the product owner's first involvement is the review."
},
{
"text": "The same product owner reviews the spec against the idea. Does the spec solve the stated problem, and are the open questions from intent.md answered or carried forward?",
"html": "The same product owner reviews the spec against the idea. Does the spec solve the stated problem, and are the open questions from intent.md answered or carried forward?"
},
{
"text": "Work through the flagged concerns first as they are the points an analyst would have escalated. The product owner resolves each one with its policy owner before engineering sees the spec.",
"html": "Work through the flagged concerns first as they are the points an analyst would have escalated. The product owner resolves each one with its policy owner before engineering sees the spec."
},
{
"text": "Commit spec.md alongside intent.md . The file pair records what was asked for and what was decided.",
"html": "Commit spec.md alongside intent.md. The file pair records what was asked for and what was decided."
},
{
"text": "The product owner decides whether the spec and intent progress to build, consulting a technical lead for anything the organization classes as higher risk. A human team mate always makes this call, and accepting the spec is what starts the plan mode play in Stage 3: Build.",
"html": "The product owner decides whether the spec and intent progress to build, consulting a technical lead for anything the organization classes as higher risk. A human team mate always makes this call, and accepting the spec is what starts the plan mode play in Stage 3: Build."
}
]
},
{
"type": "heading",
"level": 4,
"text": "What it looks like (the prompt)",
"html": "What it looks like (the prompt)"
},
{
"type": "code",
"text": "Read the attached intent.md and produce a requirements and design spec for integrating it into our existing codebase. Apply the skills available to you so the plan conforms to our brand guidelines, security policies and UX standards. Document the spec fully as spec.md, ready to hand to the engineering team. Describe clearly any areas of concern, especially where you cannot satisfy contradicting policies.",
"lang": "markdown"
},
{
"type": "heading",
"level": 4,
"text": "Governance considerations",
"html": "Governance considerations"
},
{
"type": "paragraph",
"text": "Instead of being discovered in a review weeks later, the live policy is read and applied while the spec is written. The organization's skills are applied as constraints on the spec. The spec, the prompt that produced it, and the skill versions in force are all logged in version control. The product owner signs off the spec, and routes flagged concerns to the named policy owners.",
"html": "Instead of being discovered in a review weeks later, the live policy is read and applied while the spec is written. The organization's skills are applied as constraints on the spec. The spec, the prompt that produced it, and the skill versions in force are all logged in version control. The product owner signs off the spec, and routes flagged concerns to the named policy owners."
},
{
"type": "paragraph",
"text": "How to measure it Leading indicator Elapsed time between the intent.md commit and the spec.md commit for the same change (two git timestamps), compared with the old requirements-plus-design cycle. Lagging indicator Requirements rework after build starts. Count spec.md commits dated after the first plan.md commit for the same change. Git log will give this directly.",
"html": "How to measure itLeading indicatorElapsed time between the intent.md commit and the spec.md commit for the same change (two git timestamps), compared with the old requirements-plus-design cycle.Lagging indicatorRequirements rework after build starts. Count spec.md commits dated after the first plan.md commit for the same change. Git log will give this directly."
},
{
"type": "paragraph",
"text": "03",
"html": "03"
},
{
"type": "heading",
"level": 2,
"text": "Build",
"html": "Build"
},
{
"type": "paragraph",
"text": "Nothing is implemented without an accepted plan. Institutional knowledge becomes files the agent reads, and the guardrails run as code rather than as habits.",
"html": "Nothing is implemented without an accepted plan. Institutional knowledge becomes files the agent reads, and the guardrails run as code rather than as habits."
},
{
"type": "heading",
"level": 3,
"text": "Claude Code plan mode as the default starting point",
"html": "Claude Code plan mode as the default starting point"
},
{
"type": "paragraph",
"text": "Engineers start Claude Code sessions in plan mode , give Claude the approved spec.md from Stage 2: Design, and let it interview them, iterating on the plan until the engineer is happy with it.",
"html": "Engineers start Claude Code sessions in plan mode, give Claude the approved spec.md from Stage 2: Design, and let it interview them, iterating on the plan until the engineer is happy with it."
},
{
"type": "paragraph",
"text": "TraditionalAn engineer reads the design and starts writing code. How the change will be made, down to which files and which tests, stays in the engineer's head or at best a ticket comment. Nobody else can review it. The first thing a reviewer sees is the finished diff, and by then rework is slow.AI-nativeWork starts with a written plan that Claude produces in plan mode, where it can read the codebase without changing anything. The engineer corrects the plan before code is written, and the approved version is committed as plan.md for later stages to check against.",
"html": "TraditionalAn engineer reads the design and starts writing code. How the change will be made, down to which files and which tests, stays in the engineer's head or at best a ticket comment. Nobody else can review it. The first thing a reviewer sees is the finished diff, and by then rework is slow.AI-nativeWork starts with a written plan that Claude produces in plan mode, where it can read the codebase without changing anything. The engineer corrects the plan before code is written, and the approved version is committed as plan.md for later stages to check against."
},
{
"type": "paragraph",
"text": "Getting started Prerequisites The intent artifact ( intent.md or spec.md ) if one exists, and the CLAUDE.md file helps. Infrastructure Claude Code with access to the repository.",
"html": "Getting startedPrerequisitesThe intent artifact (intent.md or spec.md) if one exists, and the CLAUDE.md file helps.InfrastructureClaude Code with access to the repository."
},
{
"type": "heading",
"level": 4,
"text": "How to execute it",
"html": "How to execute it"
},
{
"type": "list",
"ordered": true,
"items": [
{
"text": "The engineer starts the session in plan mode with Claude.",
"html": "The engineer starts the session in plan mode with Claude."
},
{
"text": "The engineer gives Claude the intent.md and the spec.md and asks for an implementation plan that names the files that change, the order of the work, and the tests that prove it.",
"html": "The engineer gives Claude the intent.md and the spec.md and asks for an implementation plan that names the files that change, the order of the work, and the tests that prove it."
},
{
"text": "Interrogate the plan by asking what the change could break, which step is most risky, and what other options Claude chose not to do.",
"html": "Interrogate the plan by asking what the change could break, which step is most risky, and what other options Claude chose not to do."
},
{
"text": "Iterate until an engineer who has never seen the conversation could implement the change from the plan alone.",
"html": "Iterate until an engineer who has never seen the conversation could implement the change from the plan alone."
},
{
"text": "Commit the approved plan as plan.md . The plan joins the audit trail, and the PR review play (Stage 5: Deploy) checks the eventual diff against it.",
"html": "Commit the approved plan as plan.md. The plan joins the audit trail, and the PR review play (Stage 5: Deploy) checks the eventual diff against it."
},
{
"text": "Accept the plan and let Claude implement. With a solid plan, the implementation is often a single pass.",
"html": "Accept the plan and let Claude implement. With a solid plan, the implementation is often a single pass."
},
{
"text": "When implementation departs from the plan, update plan.md in the same commit. Consider using a hook to enforce synchronization between the two.",
"html": "When implementation departs from the plan, update plan.md in the same commit. Consider using a hook to enforce synchronization between the two."
}
]
},
{
"type": "heading",
"level": 4,
"text": "What it looks like (plan.md)",
"html": "What it looks like (plan.md)"
},
{
"type": "code",
"text": "# Plan: claims status self-service (from intent.md 2026-06-02)\n\n\n\n\n## Files that change\n\n\nportal/src/claims/StatusPanel.tsx (new), claims-api/routes/status.py,\n\nclaims-api/tests/test\n_status.py\n\n\n\n## Order of work\n\n1. Add the status endpoint behind existing auth.\n\n2. Panel against the endpoint.\n\n3. Wire into the portal nav.\n\n\n\n## Risks\n\nThe claims-core API rate-limits at 50 rps; the panel must cache.\n\n\n\n## Proof\n\ntest_\nstatus.py covers the four claim states; screenshot matches the\n\napproved mock.",
"lang": "markdown"
},
{
"type": "heading",
"level": 4,
"text": "Governance considerations",
"html": "Governance considerations"
},
{
"type": "paragraph",
"text": "Design review happens before any code is generated, when changing course is still a matter of editing a document. Plan mode enforces this itself, since Claude cannot edit files until the engineer accepts the plan. The plan and its revisions are logged along with who accepted it. Routine changes are approved by the engineer, and anything the organization classes as higher risk goes to a tech lead or architect.",
"html": "Design review happens before any code is generated, when changing course is still a matter of editing a document. Plan mode enforces this itself, since Claude cannot edit files until the engineer accepts the plan. The plan and its revisions are logged along with who accepted it. Routine changes are approved by the engineer, and anything the organization classes as higher risk goes to a tech lead or architect."
},
{
"type": "paragraph",
"text": "How to measure it Leading indicator Share of changes that merge from the first implementation pass, and time from plan approval to merged PR with the required data within the PR metadata. Lagging indicator Rework cycles per change, again from the PR metadata, and how often the merged diff still matches the committed plan.md .",
"html": "How to measure itLeading indicatorShare of changes that merge from the first implementation pass, and time from plan approval to merged PR with the required data within the PR metadata.Lagging indicatorRework cycles per change, again from the PR metadata, and how often the merged diff still matches the committed plan.md."
},
{
"type": "heading",
"level": 3,
"text": "Claude Code on auto mode",
"html": "Claude Code on auto mode"
},
{
"type": "paragraph",
"text": "Claude Code can also run in auto mode, where the engineer approves the plan and, once happy and iterated upon, Claude applies each change without a per-edit prompt. As the guardrails from the later plays mature (a tuned CLAUDE.md , skills that encode policy, hooks that block unsafe actions, and a test suite Claude can run), auto-accept becomes the default for routine work: a tight spec.md , a small blast radius, and code the tests already cover.",
"html": "Claude Code can also run in auto mode, where the engineer approves the plan and, once happy and iterated upon, Claude applies each change without a per-edit prompt. As the guardrails from the later plays mature (a tuned CLAUDE.md, skills that encode policy, hooks that block unsafe actions, and a test suite Claude can run), auto-accept becomes the default for routine work: a tight spec.md, a small blast radius, and code the tests already cover."
},
{
"type": "paragraph",
"text": "The shift is now away from the user watching the agent make the edits and reviewing actions, towards the review of artifacts after longer autonomous sessions. Auto-accept mode further enables parallelism across individuals and the team when used with worktrees and is fundamental to running the SDLC autonomously and closing the loop as described in Stage 6: Maintenance.",
"html": "The shift is now away from the user watching the agent make the edits and reviewing actions, towards the review of artifacts after longer autonomous sessions. Auto-accept mode further enables parallelism across individuals and the team when used with worktrees and is fundamental to running the SDLC autonomously and closing the loop as described in Stage 6: Maintenance."
},
{
"type": "paragraph",
"text": "Sidebar",
"html": "Sidebar"
},
{
"type": "heading",
"level": 3,
"text": "Legacy systems and the source of truth",
"html": "Legacy systems and the source of truth"
},
{
"type": "paragraph",
"text": "Applies to every artifact the process produces.",
"html": "Applies to every artifact the process produces."
},
{
"type": "paragraph",
"text": "Existing SDLC processes likely already track artifacts, just not in markdown files. Work items may be in Jira, requirements in a tool with regulatory traceability built in, designs in Figma, and change approvals with a change board. Those systems are hard to displace because auditors and regulators already accept them and other teams depend on them, so the AI-native SDLC has to fit around what exists.When transitioning to the AI-native SDLC, for every artifact the process produces, name one system as the source of truth, with everything else holding a copy or a link to the original. The configurations below can be set up to have one source of truth, with the choice differing per artifact: The repo as the source of truth. The markdown artifacts are the authoritative record and the legacy system references files within commits. This can be one of the cleanest configurations for engineering-led organizations, as all records live in one tool with one timestamp authority. The legacy system as the source of truth. Jira, ServiceNow, or the requirements tool holds the authoritative record and the markdown artifacts are working copies. Claude reads the record at the start of the session and writes the outcome back through an MCP connector in the same session that produced the spec or the plan. Linkage as the minimum bar. All artifacts note the record ID and all legacy records contain the commit SHA of the markdown file. Linkage is a good place to start when transitioning to the AI-native SDLC, accepting that there are two sources of truth.Both the legacy system and the markdown-first system can coexist, so long as there is a link between the two or one is declared the source of truth.",
"html": "Existing SDLC processes likely already track artifacts, just not in markdown files. Work items may be in Jira, requirements in a tool with regulatory traceability built in, designs in Figma, and change approvals with a change board. Those systems are hard to displace because auditors and regulators already accept them and other teams depend on them, so the AI-native SDLC has to fit around what exists.When transitioning to the AI-native SDLC, for every artifact the process produces, name one system as the source of truth, with everything else holding a copy or a link to the original. The configurations below can be set up to have one source of truth, with the choice differing per artifact:The repo as the source of truth. The markdown artifacts are the authoritative record and the legacy system references files within commits. This can be one of the cleanest configurations for engineering-led organizations, as all records live in one tool with one timestamp authority.The legacy system as the source of truth. Jira, ServiceNow, or the requirements tool holds the authoritative record and the markdown artifacts are working copies. Claude reads the record at the start of the session and writes the outcome back through an MCP connector in the same session that produced the spec or the plan.Linkage as the minimum bar. All artifacts note the record ID and all legacy records contain the commit SHA of the markdown file. Linkage is a good place to start when transitioning to the AI-native SDLC, accepting that there are two sources of truth.Both the legacy system and the markdown-first system can coexist, so long as there is a link between the two or one is declared the source of truth."
},
{
"type": "heading",
"level": 3,
"text": "The CLAUDE.md",
"html": "The CLAUDE.md"
},
{
"type": "paragraph",
"text": "CLAUDE.md gives Claude the context a new joiner would need, covering conventions, commands, architecture, and the mistakes the team sees most often. Knowledge that used to sit in people's heads and on wikis becomes a file the agent reads at the start of every session, maintained by the whole team and iterated on whenever a mistake is made.",
"html": "CLAUDE.md gives Claude the context a new joiner would need, covering conventions, commands, architecture, and the mistakes the team sees most often. Knowledge that used to sit in people's heads and on wikis becomes a file the agent reads at the start of every session, maintained by the whole team and iterated on whenever a mistake is made."
},
{
"type": "paragraph",
"text": "Getting started Prerequisites None. Infrastructure A repo, Claude Code installed, and one engineer who knows the codebase well.",
"html": "Getting startedPrerequisitesNone.InfrastructureA repo, Claude Code installed, and one engineer who knows the codebase well."
},
{
"type": "heading",
"level": 4,
"text": "How to execute it",
"html": "How to execute it"
},
{
"type": "list",
"ordered": true,
"items": [
{
"text": "Run /init in the repo. Claude generates a starting CLAUDE.md from what it finds.",
"html": "Run /init in the repo. Claude generates a starting CLAUDE.md from what it finds."
},
{
"text": "Cut the generated file down to what a new joiner would need on day one. Keep the build, test and lint commands, the conventions that matter, and the things Claude keeps getting wrong.",
"html": "Cut the generated file down to what a new joiner would need on day one. Keep the build, test and lint commands, the conventions that matter, and the things Claude keeps getting wrong."
},
{
"text": "Check CLAUDE.md into git at the repo root so the whole team shares one version and changes are reviewed like code.",
"html": "Check CLAUDE.md into git at the repo root so the whole team shares one version and changes are reviewed like code."
},
{
"text": "A working rule helps here. When Claude makes a mistake twice, the correction goes into CLAUDE.md .",
"html": "A working rule helps here. When Claude makes a mistake twice, the correction goes into CLAUDE.md."
},
{
"text": "Keep it under a page, because Claude reads all of it at the start of a session and anything stale is taking up context for no benefit.",
"html": "Keep it under a page, because Claude reads all of it at the start of a session and anything stale is taking up context for no benefit."
}
]
},
{
"type": "heading",
"level": 4,
"text": "What it looks like (CLAUDE.md)",
"html": "What it looks like (CLAUDE.md)"
},
{
"type": "code",
"text": "# Payments service\n\n\n\n## Commands\n\n- Build: make build\n\n- Test: make test (unit), make itest (integration, needs docker)\n\n- Lint: make lint (runs \nin\n CI; fix before pushing)\n\n\n\n## Conventions\n\n- Java \n21\n, Spring Boot \n3.\n No \nnew\n Lombok.\n\n- Money is always BigDecimal, never double.\n\n- Every endpoint needs an integration test \nin\n src/itest.\n\n\n\n## Architecture\n\n- api/ holds REST controllers, core/ holds domain logic,\n\n adapters/ talks to external systems.\n\n- Kafka events are defined \nin\n schemas/; never edit generated classes.\n\n\n\n## Things Claude gets wrong\n\n- Do not bump dependency versions; the platform team owns them.\n\n- The legacy v1/ package is frozen; changes go \nin\n v2/.",
"lang": "javascript"
},
{
"type": "heading",
"level": 4,
"text": "Governance considerations",
"html": "Governance considerations"
},
{
"type": "paragraph",
"text": "CLAUDE.md is version controlled, so the instructions the agent works to are reviewable and auditable. Team conventions are applied through the file, changes to it are logged in git history, and code owners approve those changes in PR review.",
"html": "CLAUDE.md is version controlled, so the instructions the agent works to are reviewable and auditable. Team conventions are applied through the file, changes to it are logged in git history, and code owners approve those changes in PR review."
},
{
"type": "paragraph",
"text": "How to measure it Leading indicator How often Claude repeats a mistake CLAUDE.md should have caught. The corrections or changes to the CLAUDE.md should be tracked within the git history. Lagging indicator Time to first merged PR for a new member of the team from PR history.",
"html": "How to measure itLeading indicatorHow often Claude repeats a mistake CLAUDE.md should have caught. The corrections or changes to the CLAUDE.md should be tracked within the git history.Lagging indicatorTime to first merged PR for a new member of the team from PR history."
},
{
"type": "heading",
"level": 3,
"text": "Skills as institutional knowledge",
"html": "Skills as institutional knowledge"
},
{
"type": "paragraph",
"text": "Skills are how an organization makes its institutional knowledge operational. The instructions are explicit, version-controlled, applied broadly, and updated centrally when policy changes. The rule of thumb: write a skill for institutional knowledge that must be applied consistently; don't write a skill for components that belong in CLAUDE.md or a prompt.",
"html": "Skills are how an organization makes its institutional knowledge operational. The instructions are explicit, version-controlled, applied broadly, and updated centrally when policy changes. The rule of thumb: write a skill for institutional knowledge that must be applied consistently; don't write a skill for components that belong in CLAUDE.md or a prompt."
},
{
"type": "paragraph",
"text": "Getting started Prerequisites None required. Having a CLAUDE.md helps, because it keeps the agent's working knowledge in the repo, but a skill does not depend on it. Infrastructure One policy with a named owner and a written source of truth.",
"html": "Getting startedPrerequisitesNone required. Having a CLAUDE.md helps, because it keeps the agent's working knowledge in the repo, but a skill does not depend on it.InfrastructureOne policy with a named owner and a written source of truth."
},
{
"type": "heading",
"level": 4,
"text": "How to execute it",
"html": "How to execute it"
},
{
"type": "list",
"ordered": true,
"items": [
{
"text": "Pick one piece of knowledge that is enforced inconsistently today. This could be a security standard, an API design convention, or a brand rule.",
"html": "Pick one piece of knowledge that is enforced inconsistently today. This could be a security standard, an API design convention, or a brand rule."
},
{
"text": "Write it as a skill, a folder containing a SKILL.md whose frontmatter says when it triggers and whose body says what to do. An engineer writes it from the policy owner's source of truth, using Claude to help.",
"html": "Write it as a skill, a folder containing a SKILL.md whose frontmatter says when it triggers and whose body says what to do. An engineer writes it from the policy owner's source of truth, using Claude to help."
},
{
"text": "Put the skill in the repo at .claude/skills/.claude/skills/<name>/ so it ships with the code, or distribute it organization-wide through a plugin."
},
{
"text": "Test that the skill triggers. Ask Claude to do the relevant task in different ways and confirm the skill loads each time.",
"html": "Test that the skill triggers. Ask Claude to do the relevant task in different ways and confirm the skill loads each time."
},
{
"text": "When the policy changes, change the skill and have the policy owner sign off the change.",
"html": "When the policy changes, change the skill and have the policy owner sign off the change."
},
{
"text": "Engineers pick up the new version automatically in their next session.",
"html": "Engineers pick up the new version automatically in their next session."
}
]
},
{
"type": "heading",
"level": 4,
"text": "What it looks like (.claude/skills/secure-api-review/SKILL.md)",
"html": "What it looks like (.claude/skills/secure-api-review/SKILL.md)"
},
{
"type": "code",
"text": "---\n\nname: secure-api-review\n\ndescription: Apply the API security standard. Use whenever creating or\n\n modifying an external-facing endpoint, reviewing API code, or\n\n generating an OpenAPI spec.\n\n---\n\n\n# Secure API review\n\n\n\n\nWhen you create or change an API endpoint:\n\n1.\n Authentication: every endpoint requires the gateway JWT;\n\n no anonymous routes outside /health.\n\n2.\n Input validation: validate request bodies against the OpenAPI\n\n schema and reject unknown fields.\n\n3.\n Audit: every state-changing endpoint emits an audit event with\n\n actor, action, entity and timestamp.\n\n4.\n Data classification: fields tagged pii in the schema must never\n\n appear in logs or error messages.\n\n\n\nRun scripts/check-endpoints.sh and include its output in your summary.",
"lang": "markdown"
},
{
"type": "heading",
"level": 4,
"text": "Governance considerations",
"html": "Governance considerations"
},
{
"type": "paragraph",
"text": "A skill is a control, though an advisory one. It makes Claude likely to apply the policy while the code is written, and nothing forces a session to comply with it. A policy that must always hold needs something deterministic behind the skill, such as a hook that blocks the action or a review pass that re-checks the policy at the PR. The skill makes violations rare and the hook makes them close to impossible. Skill invocations are logged in session traces, and the policy owner reviews skill changes like code.",
"html": "A skill is a control, though an advisory one. It makes Claude likely to apply the policy while the code is written, and nothing forces a session to comply with it. A policy that must always hold needs something deterministic behind the skill, such as a hook that blocks the action or a review pass that re-checks the policy at the PR. The skill makes violations rare and the hook makes them close to impossible. Skill invocations are logged in session traces, and the policy owner reviews skill changes like code."
},
{
"type": "paragraph",
"text": "How to measure it Leading indicator Time from the policy owner approving a policy change to the updated skill merging, taken from the PR on the skill folder. Lagging indicator PR reviews findings that cite the policy, which should fall towards zero once the skill is applying the policy while the code is written. Where the findings don't fall towards zero, either the skill isn't triggering or its text has drifted from the official policy.",
"html": "How to measure itLeading indicatorTime from the policy owner approving a policy change to the updated skill merging, taken from the PR on the skill folder.Lagging indicatorPR reviews findings that cite the policy, which should fall towards zero once the skill is applying the policy while the code is written. Where the findings don't fall towards zero, either the skill isn't triggering or its text has drifted from the official policy."
},
{
"type": "heading",
"level": 3,
"text": "Hooks as build-time guardrails",
"html": "Hooks as build-time guardrails"
},
{
"type": "paragraph",
"text": "A skill is an advisory control while a hook is the deterministic layer behind it. Most of Claude's actions are file edits and shell commands during implementation, so the build phase is where hooks can end up firing most often.",
"html": "A skill is an advisory control while a hook is the deterministic layer behind it. Most of Claude's actions are file edits and shell commands during implementation, so the build phase is where hooks can end up firing most often."
},
{
"type": "paragraph",
"text": "Build-phase hooks can:",
"html": "Build-phase hooks can:"
},
{
"type": "list",
"ordered": false,
"items": [
{
"text": "Block edits to protected paths such as generated classes or a frozen package;",
"html": "Block edits to protected paths such as generated classes or a frozen package;"
},
{
"text": "Run the formatter and linter after file edits so drift never accumulates;",
"html": "Run the formatter and linter after file edits so drift never accumulates;"
},
{
"text": "Keep credentials out of the diff.",
"html": "Keep credentials out of the diff."
}
]
},
{
"type": "paragraph",
"text": "Back any skill whose policy has to hold without exception. A hook runs on each action that matches it, so build-phase hooks should be fast and scoped to the file that changed. Heavier checks such as the full test suite belong at the commit or the PR.",
"html": "Back any skill whose policy has to hold without exception. A hook runs on each action that matches it, so build-phase hooks should be fast and scoped to the file that changed. Heavier checks such as the full test suite belong at the commit or the PR."
},
{
"type": "paragraph",
"text": "A hook that asks a human for approval belongs with the gates in Stage 5: Deploy, because an approval prompt during the build puts a person back on the critical path of all the sessions running in parallel.",
"html": "A hook that asks a human for approval belongs with the gates in Stage 5: Deploy, because an approval prompt during the build puts a person back on the critical path of all the sessions running in parallel."
},
{
"type": "heading",
"level": 3,
"text": "Parallel sessions and subagents",
"html": "Parallel sessions and subagents"
},
{
"type": "paragraph",
"text": "One engineer can drive several streams of work at once.",
"html": "One engineer can drive several streams of work at once."
},
{
"type": "paragraph",
"text": "A parallel session is another full Claude Code instance, working a separate task in its own git worktree . Each independent session knows nothing about the others, and the engineer steering them is the only thing they share.",
"html": "A parallel session is another full Claude Code instance, working a separate task in its own git worktree. Each independent session knows nothing about the others, and the engineer steering them is the only thing they share."
},
{
"type": "paragraph",
"text": "A subagent runs inside a single session as a scoped helper with its own context window and tool limits and suits jobs that recur in multiple tasks such as verifying the app runs as expected.",
"html": "A subagent runs inside a single session as a scoped helper with its own context window and tool limits and suits jobs that recur in multiple tasks such as verifying the app runs as expected."
},
{
"type": "paragraph",
"text": "Parallel sessions raise the number of tasks an engineer can have in flight, while subagents keep each session focused on its own task. The engineer's job is steering and reviewing all of them.",
"html": "Parallel sessions raise the number of tasks an engineer can have in flight, while subagents keep each session focused on its own task. The engineer's job is steering and reviewing all of them."
},
{
"type": "paragraph",
"text": "TraditionalOne engineer works one task at a time and spends a significant portion of their day or week on builds, tests and reviewers. Switching between tasks while waiting is possible, but the context switch is tiring enough that few people choose to.AI-nativeOne engineer runs several Claude sessions at once, each in its own worktree on its own task. Repeated jobs become subagents with their own context and tool limits. The engineer's job shifts to orchestrating, and eventually, to building and monitoring loops.",
"html": "TraditionalOne engineer works one task at a time and spends a significant portion of their day or week on builds, tests and reviewers. Switching between tasks while waiting is possible, but the context switch is tiring enough that few people choose to.AI-nativeOne engineer runs several Claude sessions at once, each in its own worktree on its own task. Repeated jobs become subagents with their own context and tool limits. The engineer's job shifts to orchestrating, and eventually, to building and monitoring loops."
},
{
"type": "paragraph",
"text": "Getting started Prerequisites The CLAUDE.md , since all sessions read the file. The feedback loop (Stage 4: Test) also helps here, because less supervision from the engineer is needed when a session can verify its own work. Infrastructure A git repository, since isolation comes from worktrees and permission settings tuned so sessions are not waiting on approval prompts for commands the organization considers safe.",
"html": "Getting startedPrerequisitesThe CLAUDE.md, since all sessions read the file. The feedback loop (Stage 4: Test) also helps here, because less supervision from the engineer is needed when a session can verify its own work.InfrastructureA git repository, since isolation comes from worktrees and permission settings tuned so sessions are not waiting on approval prompts for commands the organization considers safe."
},
{
"type": "heading",
"level": 4,
"text": "How to execute it",
"html": "How to execute it"
},
{
"type": "list",
"ordered": true,
"items": [
{
"text": "The engineer splits the work into tasks that touch different files, using the plan from the plan mode play (Stage 3: Build) to see where the work is independent. Tasks that share files run in a single session, one after another.",
"html": "The engineer splits the work into tasks that touch different files, using the plan from the plan mode play (Stage 3: Build) to see where the work is independent. Tasks that share files run in a single session, one after another."
},
{
"text": "Each parallel task gets its own worktree, for example claude --worktree feature-auth in one terminal and claude --worktree fix-rate-limit in another. A worktree is a separate checkout on its own branch, which stops sessions colliding on files.",
"html": "Each parallel task gets its own worktree, for example claude --worktree feature-auth in one terminal and claude --worktree fix-rate-limit in another. A worktree is a separate checkout on its own branch, which stops sessions colliding on files."
},
{
"text": "Two or three sessions is a sensible starting point. The practical ceiling is how many streams one person can review properly, so add sessions only while review is keeping up.",
"html": "Two or three sessions is a sensible starting point. The practical ceiling is how many streams one person can review properly, so add sessions only while review is keeping up."
},
{
"text": "Turn repeated jobs into subagents, as defined in markdown files in .claude/agents/ , each with a name, a description of when to use it, and the tools it may touch. Examples include a code simplifier that strips needless complexity after the main agent finishes, a verifier that runs the app and checks behavior, a researcher that explores the codebase and reports back without flooding the main context. Check the definitions into git so the whole team shares them.",
"html": "Turn repeated jobs into subagents, as defined in markdown files in .claude/agents/, each with a name, a description of when to use it, and the tools it may touch. Examples include a code simplifier that strips needless complexity after the main agent finishes, a verifier that runs the app and checks behavior, a researcher that explores the codebase and reports back without flooding the main context. Check the definitions into git so the whole team shares them."
}
]
},
{
"type": "heading",
"level": 4,
"text": "What it looks like (.claude/agents/verifier.md)",
"html": "What it looks like (.claude/agents/verifier.md)"
},
{
"type": "code",
"text": "---\n\nname: verifier\n\ndescription\n: Runs the app and checks the change works before the session\n\n reports done\n\ntools\n: Bash, Read\n\n---\n\nStart the app \nwith\n make run. Exercise the changed behavior and the two\n\nnearest neighboring flows. Report what you ran, what you saw, and any\n\nbehavior that does not match plan.md. Do not fix anything; report only.",
"lang": "javascript"
},
{
"type": "heading",
"level": 4,
"text": "Governance considerations",
"html": "Governance considerations"
},
{
"type": "paragraph",
"text": "More sessions means more output, so the controls have to come from configuration in the repo. Hooks and permission settings there apply to all sessions, and what a session does is logged and attributed to the engineer who ran it.",
"html": "More sessions means more output, so the controls have to come from configuration in the repo. Hooks and permission settings there apply to all sessions, and what a session does is logged and attributed to the engineer who ran it."
},
{
"type": "paragraph",
"text": "How to measure it Leading indicator Concurrent sessions per engineer while review quality holds, counted from the OpenTelemetry export, and the share of the day spent steering rather than waiting. Lagging indicator Changes merged per engineer per week read alongside the rework rate as determined per the PR history.",
"html": "How to measure itLeading indicatorConcurrent sessions per engineer while review quality holds, counted from the OpenTelemetry export, and the share of the day spent steering rather than waiting.Lagging indicatorChanges merged per engineer per week read alongside the rework rate as determined per the PR history."
},
{
"type": "heading",
"level": 3,
"text": "Give Claude a feedback loop",
"html": "Give Claude a feedback loop"
},
{
"type": "paragraph",
"text": "Always give Claude a way to verify its own work, whether tests, a build, or a screenshot diff. A session checks its own work and fixes its own mistakes before an engineer sees them.",
"html": "Always give Claude a way to verify its own work, whether tests, a build, or a screenshot diff. A session checks its own work and fixes its own mistakes before an engineer sees them."
},
{
"type": "paragraph",
"text": "The feedback loop should not be confused with a verifier subagent (Stage 3: Build). The feedback loop runs through the whole task as many times as the work. The verifier subagent, on the other hand, is one way to package the final check by running a fresh context window once the session believes the work is done. This way the verdict is not colored by the assumptions that produced the code.",
"html": "The feedback loop should not be confused with a verifier subagent (Stage 3: Build). The feedback loop runs through the whole task as many times as the work. The verifier subagent, on the other hand, is one way to package the final check by running a fresh context window once the session believes the work is done. This way the verdict is not colored by the assumptions that produced the code."
},
{
"type": "paragraph",
"text": "TraditionalThe signal that code works arrives late. CI minutes later, a tester days later, production weeks later. With an agent producing the code, a late signal means a person has to check all of its output, and that person becomes the bottleneck.AI-nativeThe session is given a way to check its own work before a person sees it. Run the tests, run the build, take the screenshot. Claude iterates until the check passes, so what reaches the engineer has already passed it. Setting the loop up falls to the engineer running the session, and the steps below are written for them.",
"html": "TraditionalThe signal that code works arrives late. CI minutes later, a tester days later, production weeks later. With an agent producing the code, a late signal means a person has to check all of its output, and that person becomes the bottleneck.AI-nativeThe session is given a way to check its own work before a person sees it. Run the tests, run the build, take the screenshot. Claude iterates until the check passes, so what reaches the engineer has already passed it. Setting the loop up falls to the engineer running the session, and the steps below are written for them."
},
{
"type": "paragraph",
"text": "Getting started Prerequisites None. Infrastructure A test suite and a build that run locally with one command each. For the UI work, a way for Claude to see the result is crucial, either a browser tool or a screenshot utility wired in via MCP.",
"html": "Getting startedPrerequisitesNone.InfrastructureA test suite and a build that run locally with one command each. For the UI work, a way for Claude to see the result is crucial, either a browser tool or a screenshot utility wired in via MCP."
},
{
"type": "heading",
"level": 4,
"text": "How to execute it",
"html": "How to execute it"
},
{
"type": "list",
"ordered": true,
"items": [
{
"text": "If checking the work today takes a sequence of commands and some environment knowledge, wrap it in a single target such as \"make test\" or \"npm test\" that exits non-zero on failure.",
"html": "If checking the work today takes a sequence of commands and some environment knowledge, wrap it in a single target such as "make test" or "npm test" that exits non-zero on failure."
},
{
"text": "In the CLAUDE.md 's Commands section, list each command with an example of a healthy output.",
"html": "In the CLAUDE.md's Commands section, list each command with an example of a healthy output."
},
{
"text": "State a target and make it quantifiable so Claude can check the work without asking you, for example: \"All tests in test_status.py pass,\" \"the screenshot matches the attached mock,\" or \"the endpoint returns 200 with the new field\".",
"html": "State a target and make it quantifiable so Claude can check the work without asking you, for example: "All tests in test_status.py pass," "the screenshot matches the attached mock," or "the endpoint returns 200 with the new field"."
},
{
"text": "For bug fixes, write the failing test first. Ask Claude to reproduce the bug as a test, run it, and confirm it fails for the reason you expect. Commit that test. Only then ask Claude to make it pass without editing the test, with the test-file hook from the final step enforcing the restriction. A test that existed before the fix, and that the agent couldn't rewrite, is proof the bug is gone.",
"html": "For bug fixes, write the failing test first. Ask Claude to reproduce the bug as a test, run it, and confirm it fails for the reason you expect. Commit that test. Only then ask Claude to make it pass without editing the test, with the test-file hook from the final step enforcing the restriction. A test that existed before the fix, and that the agent couldn't rewrite, is proof the bug is gone."
},
{
"text": "For UI work, close the loop with a visual check. Give Claude a browser or screenshot tool, give it the mock, and let it iterate. Implement, screenshot, compare, and adjust. Two or three rounds is normal, and the result should improve with each one.",
"html": "For UI work, close the loop with a visual check. Give Claude a browser or screenshot tool, give it the mock, and let it iterate. Implement, screenshot, compare, and adjust. Two or three rounds is normal, and the result should improve with each one."
},
{
"text": "Make verification part of \"done.\" Instruction lives in CLAUDE.md . Run the tests before reporting a task complete, and show the output.",
"html": "Make verification part of "done." Instruction lives in CLAUDE.md. Run the tests before reporting a task complete, and show the output."
},
{
"text": "Finally, the loop itself needs protecting, because an agent fixing code must not be able to weaken the check on that code. A hook that blocks edits to test files during a fix task does this. The alternative is to check the diff in review and reject any change that touches a test.",
"html": "Finally, the loop itself needs protecting, because an agent fixing code must not be able to weaken the check on that code. A hook that blocks edits to test files during a fix task does this. The alternative is to check the diff in review and reject any change that touches a test."
}
]
},
{
"type": "heading",
"level": 4,
"text": "What it looks like (CLAUDE.md verification block)",
"html": "What it looks like (CLAUDE.md verification block)"
},
{
"type": "code",
"text": "## Verifying your work\n\n\n\n- Build: make build (must finish \nwith\n \n\"Build succeeded\"\n)\n\n- Test: make test (all green; never skip or \ndelete\n a failing test)\n\n- Lint: make lint (zero warnings)\n\n\n\nRun all three before reporting any task complete, and paste the output.\n\nIf a test fails, fix the code, not the test.",
"lang": "javascript"
},
{
"type": "paragraph",
"text": "Governance considerations What is enforced Verification before a task is reported done, and the block on the agent editing test files during a fix, both implemented as hooks where the organization wants them guaranteed. What the evidence is The literal output of \"make test,\" the build log, or the screenshot diff that Claude ran and pasted, so the evidence comes from the toolchain. Where it is logged In the session transcript, which the OpenTelemetry export forwards to the organization's observability stack, and in the PR's check run, where the reviewer and any later auditor can both see it. Who approves The code owner reviewing the PR, who can concentrate on intent and risk because the mechanical evidence is already attached.",
"html": "Governance considerationsWhat is enforcedVerification before a task is reported done, and the block on the agent editing test files during a fix, both implemented as hooks where the organization wants them guaranteed.What the evidence isThe literal output of "make test," the build log, or the screenshot diff that Claude ran and pasted, so the evidence comes from the toolchain.Where it is loggedIn the session transcript, which the OpenTelemetry export forwards to the organization's observability stack, and in the PR's check run, where the reviewer and any later auditor can both see it.Who approvesThe code owner reviewing the PR, who can concentrate on intent and risk because the mechanical evidence is already attached."
},
{
"type": "paragraph",
"text": "How to measure it Leading indicator First-pass CI success rate for agent-written changes, which the CI system already supports. Lagging indicator Review time per PR (from the PR metadata), which should fall once the tests catch what reviewers used to catch, and the change failure rate from an incident tracker.",
"html": "How to measure itLeading indicatorFirst-pass CI success rate for agent-written changes, which the CI system already supports.Lagging indicatorReview time per PR (from the PR metadata), which should fall once the tests catch what reviewers used to catch, and the change failure rate from an incident tracker."
},
{
"type": "heading",
"level": 3,
"text": "Continuous evals in CI",
"html": "Continuous evals in CI"
},
{
"type": "paragraph",
"text": "Evals are the AI-native equivalent of stage-gate QA. In practice that means a suite that runs whenever the agent's configuration changes. When a new model is swapped in or a prompt is rewritten, the eval suite says whether the agent still does the work to the same standard.",
"html": "Evals are the AI-native equivalent of stage-gate QA. In practice that means a suite that runs whenever the agent's configuration changes. When a new model is swapped in or a prompt is rewritten, the eval suite says whether the agent still does the work to the same standard."
},
{
"type": "paragraph",
"text": "The evals should be seen as a live suite. As models improve, cases that once discriminated stop doing so and new ones must be added that arise from ongoing monitoring.",
"html": "The evals should be seen as a live suite. As models improve, cases that once discriminated stop doing so and new ones must be added that arise from ongoing monitoring."
},
{
"type": "paragraph",
"text": "Depending on the use case, some teams may prefer to run these evals offline on a set cadence rather than on every change. The steps below are for continuous evaluations.",
"html": "Depending on the use case, some teams may prefer to run these evals offline on a set cadence rather than on every change. The steps below are for continuous evaluations."
},
{
"type": "paragraph",
"text": "Getting started Prerequisites The CLAUDE.md and feedback loop (Stage 4: Test). Infrastructure CI that can run Claude Code non-interactively, and an API key with budget for eval runs.",
"html": "Getting startedPrerequisitesThe CLAUDE.md and feedback loop (Stage 4: Test).InfrastructureCI that can run Claude Code non-interactively, and an API key with budget for eval runs."
},
{
"type": "heading",
"level": 4,
"text": "How to execute it",
"html": "How to execute it"
},
{
"type": "list",
"ordered": true,
"items": [
{
"text": "The platform engineer collects 20 to 50 real tasks from recent work with its expected/accepted outcome.",
"html": "The platform engineer collects 20 to 50 real tasks from recent work with its expected/accepted outcome."
},
{
"text": "Write each task as an eval, meaning the prompt plus the checks that define acceptable (tests pass, lint clean, behavior unchanged, policy followed).",
"html": "Write each task as an eval, meaning the prompt plus the checks that define acceptable (tests pass, lint clean, behavior unchanged, policy followed)."
},
{
"text": "The suite runs non-interactively in CI on a schedule and on any change to CLAUDE.md , skills or hooks, since that configuration steers the agent and deserves the regression testing that code gets.",
"html": "The suite runs non-interactively in CI on a schedule and on any change to CLAUDE.md, skills or hooks, since that configuration steers the agent and deserves the regression testing that code gets."
},
{
"text": "Gate configuration changes on the results. A skill change that drops the pass rate gets reviewed before it merges.",
"html": "Gate configuration changes on the results. A skill change that drops the pass rate gets reviewed before it merges."
},
{
"text": "Each production incident gets an eval, written by the team that owned the incident, and stays in the suite as a regression test.",
"html": "Each production incident gets an eval, written by the team that owned the incident, and stays in the suite as a regression test."
}
]
},
{
"type": "heading",
"level": 4,
"text": "What it looks like (.github/workflows/agent-evals.yml)",
"html": "What it looks like (.github/workflows/agent-evals.yml)"
},
{
"type": "code",
"text": "name:\n \nAgent\n \nevals\n\n\non:\n\n\n \npull_request:\n\n\n \npaths:\n [\n'CLAUDE.md'\n, \n'.claude/**'\n]\n\n \nschedule:\n\n\n \n-\n \ncron:\n \n'0 2 * * *'\n\n\njobs:\n\n\n \nevals:\n\n\n \nruns-on:\n \nubuntu-latest\n\n\n \nsteps:\n\n\n \n-\n \nuses:\n \nactions/checkout@v4\n\n\n \n-\n \nrun:\n \nnpm\n \ninstall\n \n-g\n \n@anthropic-ai/claude-code\n\n\n \n-\n \nname:\n \nRun\n \neval\n \nsuite\n\n\n \nenv:\n\n\n \nANTHROPIC_API_KEY:\n \n${{\n \nsecrets.ANTHROPIC_API_KEY\n \n}}\n\n\n \nrun:\n \n|\n\n for eval in evals/*.json; do\n\n claude -p \"$(jq -r '.prompt' $eval)\" \\\n\n --allowedTools \"Read,Edit,Bash(make test)\" \\\n\n --output-format json > result.json\n\n ./evals/check.sh \"$eval\" result.json\n\n done",
"lang": "yaml"
},
{
"type": "heading",
"level": 4,
"text": "Governance considerations",
"html": "Governance considerations"
},
{
"type": "paragraph",
"text": "Evals give QA a gate that keeps up with agent output. The pass-rate threshold is enforced as a merge check, runs are logged so results can be compared over time, and the team that owns the configuration change approves it.",
"html": "Evals give QA a gate that keeps up with agent output. The pass-rate threshold is enforced as a merge check, runs are logged so results can be compared over time, and the team that owns the configuration change approves it."
},
{
"type": "paragraph",
"text": "How to measure it Leading indicator The eval pass rate over time, reported by the suite on every run, and how long a production incident takes to become a permanent eval. Lagging indicator Regressions caught in CI compared with regressions found in production derived from the incident tracker.",
"html": "How to measure itLeading indicatorThe eval pass rate over time, reported by the suite on every run, and how long a production incident takes to become a permanent eval.Lagging indicatorRegressions caught in CI compared with regressions found in production derived from the incident tracker."
},
{
"type": "paragraph",
"text": "05",
"html": "05"
},
{
"type": "heading",
"level": 2,
"text": "Deploy",
"html": "Deploy"
},
{
"type": "paragraph",
"text": "Review runs in both directions, and governance is enforced as the agent acts. The agent does everything up to the production gate and nothing past it.",
"html": "Review runs in both directions, and governance is enforced as the agent acts. The agent does everything up to the production gate and nothing past it."
},
{
"type": "heading",
"level": 3,
"text": "AI in the PR review loop",
"html": "AI in the PR review loop"
},
{
"type": "paragraph",
"text": "Claude both gives and receives reviews. It reviews incoming PRs against the organization's policies and addresses review comments on its own PRs. This allows engineers to focus on behavior in their PR review, which boils down to judging intent and risk.",
"html": "Claude both gives and receives reviews. It reviews incoming PRs against the organization's policies and addresses review comments on its own PRs. This allows engineers to focus on behavior in their PR review, which boils down to judging intent and risk."
},
{
"type": "paragraph",
"text": "TraditionalReview capacity was planned around human output. A PR waits for a reviewer to read all of it, review quality varies with the reviewer's load, and the author chases while the backlog grows.AI-nativeAll PRs get an identical set of review passes, with findings ranked by severity. Human attention moves up a level, to whether the change does what the plan intended and whether the risk is acceptable.",
"html": "TraditionalReview capacity was planned around human output. A PR waits for a reviewer to read all of it, review quality varies with the reviewer's load, and the author chases while the backlog grows.AI-nativeAll PRs get an identical set of review passes, with findings ranked by severity. Human attention moves up a level, to whether the change does what the plan intended and whether the risk is acceptable."
},
{
"type": "paragraph",
"text": "Getting started Prerequisites An updated CLAUDE.md file from Stage 3: Build; skills if the review passes enforce written policies, defined subagents. Infrastructure A repo with the Claude integration installed, either the managed Code Review (research preview) service enabled by an admin or the claude-code-action running in your own CI, with model calls through AWS Bedrock, Google Vertex or Microsoft Foundry where needed (the CI/CD play covers the deployment options). Branch protection policies that require a code owner's approval are also worthwhile.",
"html": "Getting startedPrerequisitesAn updated CLAUDE.md file from Stage 3: Build; skills if the review passes enforce written policies, defined subagents.InfrastructureA repo with the Claude integration installed, either the managed Code Review (research preview) service enabled by an admin or the claude-code-action running in your own CI, with model calls through AWS Bedrock, Google Vertex or Microsoft Foundry where needed (the CI/CD play covers the deployment options). Branch protection policies that require a code owner's approval are also worthwhile."
},
{
"type": "heading",
"level": 4,
"text": "How to execute it",
"html": "How to execute it"
},
{
"type": "list",
"ordered": true,
"items": [
{
"text": "The managed Code Review service is the fastest start. An admin enables it and selects repositories. Run the review in your own CI with the claude-code-action when you need control of the pipeline or want API calls routed through your own cloud agreement (the CI/CD play covers that plumbing).",
"html": "The managed Code Review service is the fastest start. An admin enables it and selects repositories. Run the review in your own CI with the claude-code-action when you need control of the pipeline or want API calls routed through your own cloud agreement (the CI/CD play covers that plumbing)."
},
{
"text": "The tech lead writes the review policy as REVIEW.md at the repo root, divided into the passes the organization cares about: bugs and logical errors; security and vulnerabilities; compliance against the spec ( spec.md from the requirements play), the implementation plan ( plan.md from the plan mode play) and design principles. REVIEW.md also defines what counts as Important as opposed to a Nit, and what to skip.",
"html": "The tech lead writes the review policy as REVIEW.md at the repo root, divided into the passes the organization cares about: bugs and logical errors; security and vulnerabilities; compliance against the spec (spec.md from the requirements play), the implementation plan (plan.md from the plan mode play) and design principles. REVIEW.md also defines what counts as Important as opposed to a Nit, and what to skip."
},
{
"text": "The tech lead sets the human threshold. Findings do not approve or block a PR on their own, and branch protection still requires approval from a code owner. A platform engineer who wants to gate merges on findings can read the severity counts that the check run publishes as a machine-readable tally.",
"html": "The tech lead sets the human threshold. Findings do not approve or block a PR on their own, and branch protection still requires approval from a code owner. A platform engineer who wants to gate merges on findings can read the severity counts that the check run publishes as a machine-readable tally."
},
{
"text": "When a reviewer or the author tags @claude on a review comment, Claude addresses the comment and pushes the fix. The PR thread records both the request and the change. This fix loop runs through the claude-code-action. In the managed service, commenting @claude review requests a fresh review instead. For PRs Claude opened, go further and let Claude babysit the PR to merge. Teams wrap the loop in a custom slash command that sweeps the unresolved review comments and failing checks on the PR, addresses them and pushes the fixes, until the PR is green and waiting only on code owner approval.",
"html": "When a reviewer or the author tags @claude on a review comment, Claude addresses the comment and pushes the fix. The PR thread records both the request and the change. This fix loop runs through the claude-code-action. In the managed service, commenting @claude review requests a fresh review instead. For PRs Claude opened, go further and let Claude babysit the PR to merge. Teams wrap the loop in a custom slash command that sweeps the unresolved review comments and failing checks on the PR, addresses them and pushes the fixes, until the PR is green and waiting only on code owner approval."
},
{
"text": "Review findings feed back into CLAUDE.md . When a review flags a mistake for the second time, the correction goes into CLAUDE.md as part of that review, and because review reads CLAUDE.md the mistake is caught from the next PR onwards. Review also flags when a change has made CLAUDE.md outdated.",
"html": "Review findings feed back into CLAUDE.md. When a review flags a mistake for the second time, the correction goes into CLAUDE.md as part of that review, and because review reads CLAUDE.md the mistake is caught from the next PR onwards. Review also flags when a change has made CLAUDE.md outdated."
},
{
"text": "Once a month the tech lead tunes the setup by rating findings so the reviewer improves and by capping Nit volume in REVIEW.md . Generated paths and anything CI already enforces are excluded.",
"html": "Once a month the tech lead tunes the setup by rating findings so the reviewer improves and by capping Nit volume in REVIEW.md. Generated paths and anything CI already enforces are excluded."
}
]
},
{
"type": "heading",
"level": 4,
"text": "What it looks like (REVIEW.md)",
"html": "What it looks like (REVIEW.md)"
},
{
"type": "code",
"text": "# Review instructions\n\n\n\n\n## Passes\n\n\nRun three passes and tag each finding with its pass:\n\n-\n Bugs: logic errors, broken edge cases, subtle regressions\n\n-\n Security: injection risks, authentication gaps, PII in logs\n\n-\n Compliance: the change matches spec.md, plan.md and our design principles\n\n\n\n## What Important means here\n\n\nReserve Important for findings that would break behavior, leak data\n\nor breach a policy. Style and naming are nits.\n\n\n\n## Cap the nits\n\n\nReport at most five nits per review; summarize the rest as a count.\n\n\n\n## Do not report\n\n\nGenerated files under src/gen/ and anything CI already enforces.",
"lang": "markdown"
},
{
"type": "heading",
"level": 4,
"text": "Governance considerations",
"html": "Governance considerations"
},
{
"type": "paragraph",
"text": "Separation of duties is preserved, because the agent that wrote the code has no way to approve it. The review policy in REVIEW.md is applied to all PRs, and findings, fixes, ratings and approvals are logged in the PR history, so the PR is the audit record. Approval comes from a human through branch protection, informed by the findings.",
"html": "Separation of duties is preserved, because the agent that wrote the code has no way to approve it. The review policy in REVIEW.md is applied to all PRs, and findings, fixes, ratings and approvals are logged in the PR history, so the PR is the audit record. Approval comes from a human through branch protection, informed by the findings."
},
{
"type": "paragraph",
"text": "How to measure it Leading indicator Time to first review, which should fall to minutes, and the share of review comments resolved without a human touching the branch with data stored directly on Git. Lagging indicator Defects and vulnerabilities caught before merge set against those escaping to production, from the PR history and the incident tracker.",
"html": "How to measure itLeading indicatorTime to first review, which should fall to minutes, and the share of review comments resolved without a human touching the branch with data stored directly on Git.Lagging indicatorDefects and vulnerabilities caught before merge set against those escaping to production, from the PR history and the incident tracker."
},
{
"type": "heading",
"level": 3,
"text": "Hooks as approval gates",
"html": "Hooks as approval gates"
},
{
"type": "paragraph",
"text": "The build phase used hooks as guardrails, allowing or blocking actions with no human involved (Stage 3: Build). A hook can also ask, pausing the action until a specific person approves, which is what release gating needs.",
"html": "The build phase used hooks as guardrails, allowing or blocking actions with no human involved (Stage 3: Build). A hook can also ask, pausing the action until a specific person approves, which is what release gating needs."
},
{
"type": "paragraph",
"text": "The play sits in Stage 5: Deploy because the release gate is the clearest case, but hooks are not deploy-specific: they run wherever Claude acts. For example, hooks can block edits to migrations and infra without a change ticket during Stage 3: Build, and stop the agent editing test files during a fix task in Stage 4: Test.",
"html": "The play sits in Stage 5: Deploy because the release gate is the clearest case, but hooks are not deploy-specific: they run wherever Claude acts. For example, hooks can block edits to migrations and infra without a change ticket during Stage 3: Build, and stop the agent editing test files during a fix task in Stage 4: Test."
},
{
"type": "paragraph",
"text": "Getting started Prerequisites None. Infrastructure A written list of the approvals the change process requires.",
"html": "Getting startedPrerequisitesNone.InfrastructureA written list of the approvals the change process requires."
},
{
"type": "heading",
"level": 4,
"text": "How to execute it",
"html": "How to execute it"
},
{
"type": "list",
"ordered": true,
"items": [
{
"text": "Engineering leadership, with change management and compliance, lists the human approval gates that must survive, such as change management sign-off, release authorization, and edits to protected paths.",
"html": "Engineering leadership, with change management and compliance, lists the human approval gates that must survive, such as change management sign-off, release authorization, and edits to protected paths."
},
{
"text": "The platform engineer expresses each gate as a hook, a script that runs before Claude acts that can allow, ask, or block.",
"html": "The platform engineer expresses each gate as a hook, a script that runs before Claude acts that can allow, ask, or block."
},
{
"text": "Team hooks go in .claude/settings.json in git, and non-negotiable hooks go in managed settings owned by the platform or IT admin, where individual engineers cannot switch them off.",
"html": "Team hooks go in .claude/settings.json in git, and non-negotiable hooks go in managed settings owned by the platform or IT admin, where individual engineers cannot switch them off."
},
{
"text": "A block should explain itself, so when a hook stops an action the reason and the route to approval appear in Claude's output.",
"html": "A block should explain itself, so when a hook stops an action the reason and the route to approval appear in Claude's output."
}
]
},
{
"type": "heading",
"level": 4,
"text": "What it looks like (.claude/settings.json)",
"html": "What it looks like (.claude/settings.json)"
},
{
"type": "code",
"text": "{\n\n \n\"hooks\"\n: {\n\n \n\"PreToolUse\"\n: [\n\n {\n\n \n\"matcher\"\n: \n\"Bash\"\n,\n\n \n\"hooks\"\n: [\n\n { \n\"type\"\n: \n\"command\"\n,\n\n \n\"command\"\n: \n\"${CLAUDE_PROJECT_DIR}/.claude/hooks/production-gate.sh\"\n }\n\n ]\n\n }\n\n ]\n\n }\n\n}",
"lang": "json"
},
{
"type": "heading",
"level": 4,
"text": "And the gate itself (.claude/hooks/production-gate.sh)",
"html": "And the gate itself (.claude/hooks/production-gate.sh)"
},
{
"type": "code",
"text": "#!/bin/bash\n\n\n# Production deploys require a named release authorization\n\n\ncmd=$(jq -r \n'.tool_input.command'\n < /dev/stdin)\n\nif\n [[ \n\"\n$cmd\n\"\n == *\n\"deploy\"\n* && \n\"\n$cmd\n\"\n == *\n\"production\"\n* ]]; \nthen\n\n\n \nif\n [ -z \n\"\n$RELEASE_APPROVAL\n\"\n ]; \nthen\n\n\n \necho\n \n\"Production deploys need a release authorization.\"\n >&2\n\n \nexit\n 2 \n# exit 2 blocks the action; the message goes to Claude\n\n\n \nfi\n\n\nfi\n\n\nexit\n 0",
"lang": "bash"
},
{
"type": "heading",
"level": 4,
"text": "Governance considerations",
"html": "Governance considerations"
},
{
"type": "paragraph",
"text": "Hooks are the approval gates. The gate condition is enforced every time, for everyone. Allow and block decisions are logged with a timestamp. The gate also defines what counts as approval, whether that's an approved change ticket or the release manager's sign-off.",
"html": "Hooks are the approval gates. The gate condition is enforced every time, for everyone. Allow and block decisions are logged with a timestamp. The gate also defines what counts as approval, whether that's an approved change ticket or the release manager's sign-off."
},
{
"type": "paragraph",
"text": "Worked example",
"html": "Worked example"
},
{
"type": "heading",
"level": 3,
"text": "Managed settings for a regulated enterprise",
"html": "Managed settings for a regulated enterprise"
},
{
"type": "paragraph",
"text": "Deployed by the platform team via MDM or the admin console; engineers cannot edit or override any of it.",
"html": "Deployed by the platform team via MDM or the admin console; engineers cannot edit or override any of it."
},
{
"type": "paragraph",
"text": "{ \"permissions\": { \"deny\": [ \"Read(.env*)\", \"Read(./secrets/**)\", \"WebFetch\", \"Bash(curl *)\", \"Bash(wget *)\" ], \"allow\": [ \"Bash(git *)\", \"Bash(make build)\", \"Bash(make test)\", \"Bash(make lint)\" ], \"disableBypassPermissionsMode\": \"disable\" }, \"allowManagedPermissionRulesOnly\": true, \"sandbox\": { \"enabled\": true, \"failIfUnavailable\": true, \"allowUnsandboxedCommands\": false, \"network\": { \"allowedDomains\": [\"git.internal.example.com\", \"registry.npmjs.org\"] }, \"credentials\": { \"files\": [ { \"path\": \"~/.ssh\", \"mode\": \"deny\" }, { \"path\": \"~/.aws/credentials\", \"mode\": \"deny\" } ], \"envVars\": [ { \"name\": \"GITHUB_TOKEN\", \"mode\": \"deny\" } ] } }, \"allowManagedHooksOnly\": true, \"disableSideloadFlags\": true, \"allowManagedMcpServersOnly\": true, \"strictKnownMarketplaces\": [ { \"source\": \"github\", \"repo\": \"example-corp/approved-plugins\" } ], \"requiredMinimumVersion\": \"2.1.193\" }What each line buys, in control terms permissions.deny keeps secrets out of the agent's context and blocks arbitrary network egress through tools; permissions.allow pre-approves the safe inner loop so the deny list doesn't turn into prompt fatigue. disableBypassPermissionsMode plus allowManagedPermissionRulesOnly means no engineer, project file or command-line flag can widen the rules. sandbox closes the gap permissions cannot. A tool-level deny on WebFetch doesn't stop a shell command reaching the network; the OS-level domain allowlist blocks egress outright. failIfUnavailable and allowUnsandboxedCommands make the sandbox a gate: Claude Code refuses to start when the sandbox cannot initialize, and a command that fails inside the sandbox cannot be retried outside it. credentials closes the gap the deny rules leave open. permissions.deny governs Claude's file tools, but a sandboxed shell command could still read ~/.ssh or ~/.aws/credentials by default; this block denies those reads and strips the named secrets from the environment of every sandboxed command. allowManagedHooksOnly means the approval gates from this play are the only hooks that run; nothing local can add to or replace them. disableSideloadFlags and strictKnownMarketplaces mean every skill, agent, hook and MCP server on an engineer's machine arrived through the organization's approved plugin marketplace, never from a home directory. allowManagedMcpServersOnly makes the agent's tool surface an allowlist owned by the platform team. requiredMinimumVersion refuses to start on a version below the approved floor, so the controls are enforced by a build the organization has actually assessed.Consider the above a starting point to tailor, rather than a recommendation to copy. Every deny trades against capability, and the right balance depends on the data classification of the repo. The settings reference documents every key, including the managed-only ones: code.claude.com/docs/en/settings",
"html": "{\n "permissions": {\n "deny": [\n "Read(.env*)", "Read(./secrets/**)",\n "WebFetch", "Bash(curl *)", "Bash(wget *)"\n ],\n "allow": [\n "Bash(git *)", "Bash(make build)",\n "Bash(make test)", "Bash(make lint)"\n ],\n "disableBypassPermissionsMode": "disable"\n },\n "allowManagedPermissionRulesOnly": true,\n "sandbox": {\n "enabled": true,\n "failIfUnavailable": true,\n "allowUnsandboxedCommands": false,\n "network": { "allowedDomains": ["git.internal.example.com",\n"registry.npmjs.org"] },\n "credentials": {\n "files": [\n { "path": "~/.ssh", "mode": "deny" },\n { "path": "~/.aws/credentials", "mode": "deny" }\n ],\n "envVars": [ { "name": "GITHUB_TOKEN", "mode": "deny" } ]\n }\n },\n "allowManagedHooksOnly": true,\n "disableSideloadFlags": true,\n "allowManagedMcpServersOnly": true,\n "strictKnownMarketplaces": [\n { "source": "github", "repo": "example-corp/approved-plugins" }\n ],\n "requiredMinimumVersion": "2.1.193"\n}What each line buys, in control termspermissions.deny keeps secrets out of the agent's context and blocks arbitrary network egress through tools; permissions.allow pre-approves the safe inner loop so the deny list doesn't turn into prompt fatigue.disableBypassPermissionsMode plus allowManagedPermissionRulesOnly means no engineer, project file or command-line flag can widen the rules.sandbox closes the gap permissions cannot. A tool-level deny on WebFetch doesn't stop a shell command reaching the network; the OS-level domain allowlist blocks egress outright.failIfUnavailable and allowUnsandboxedCommands make the sandbox a gate: Claude Code refuses to start when the sandbox cannot initialize, and a command that fails inside the sandbox cannot be retried outside it.credentials closes the gap the deny rules leave open. permissions.deny governs Claude's file tools, but a sandboxed shell command could still read ~/.ssh or ~/.aws/credentials by default; this block denies those reads and strips the named secrets from the environment of every sandboxed command.allowManagedHooksOnly means the approval gates from this play are the only hooks that run; nothing local can add to or replace them.disableSideloadFlags and strictKnownMarketplaces mean every skill, agent, hook and MCP server on an engineer's machine arrived through the organization's approved plugin marketplace, never from a home directory.allowManagedMcpServersOnly makes the agent's tool surface an allowlist owned by the platform team.requiredMinimumVersion refuses to start on a version below the approved floor, so the controls are enforced by a build the organization has actually assessed.Consider the above a starting point to tailor, rather than a recommendation to copy. Every deny trades against capability, and the right balance depends on the data classification of the repo. The settings reference documents every key, including the managed-only ones: code.claude.com/docs/en/settings"
},
{
"type": "paragraph",
"text": "How to measure it (for the hooks themselves) Leading indicator Time spent waiting on each approval gate. Every hook decision is written to the OpenTelemetry export with a timestamp and an allow or block verdict, so the wait is visible per gate. Lagging indicator Gate violations reaching production before and after hooks from the incident tracker.",
"html": "How to measure it (for the hooks themselves)Leading indicatorTime spent waiting on each approval gate. Every hook decision is written to the OpenTelemetry export with a timestamp and an allow or block verdict, so the wait is visible per gate.Lagging indicatorGate violations reaching production before and after hooks from the incident tracker."
},
{
"type": "heading",
"level": 3,
"text": "CI/CD integration and deployment",
"html": "CI/CD integration and deployment"
},
{
"type": "paragraph",
"text": "Run Claude Code non-interactively inside the CI/CD pipeline, sandbox the execution so long-running agents run safely, expose deployment through MCP integrations, and rehearse the rollback paths before the agent ever needs them.",
"html": "Run Claude Code non-interactively inside the CI/CD pipeline, sandbox the execution so long-running agents run safely, expose deployment through MCP integrations, and rehearse the rollback paths before the agent ever needs them."
},
{
"type": "paragraph",
"text": "TraditionalPipelines run deterministic scripts, and anything that needs judgment waits for a human. For example, triaging the flaky test, writing the changelog, or working out why the build broke. Deployment and rollback are runbooks a human follows under pressure.AI-nativeClaude runs non-interactively inside the pipeline for the judgment steps, in a sandbox with scoped credentials. Deployment tooling is exposed to the agent through MCP, so the workflow that wrote and tested the change can also ship it and roll it back, inside gates the organization defines per environment.",
"html": "TraditionalPipelines run deterministic scripts, and anything that needs judgment waits for a human. For example, triaging the flaky test, writing the changelog, or working out why the build broke. Deployment and rollback are runbooks a human follows under pressure.AI-nativeClaude runs non-interactively inside the pipeline for the judgment steps, in a sandbox with scoped credentials. Deployment tooling is exposed to the agent through MCP, so the workflow that wrote and tested the change can also ship it and roll it back, inside gates the organization defines per environment."
},
{
"type": "paragraph",
"text": "Getting started Prerequisites Claude in the PR review loop and hooks as approval gates, because the gates must exist before automation accelerates anything through them. Infrastructure A CI platform with the claude-code-action installed, or any runner that can call claude -p ; model access through the API, or Bedrock, Foundry, or Vertex where traffic must stay on the organization's cloud agreement; MCP servers for the deployment targets; a sandbox profile for agent jobs with no standing production credentials.",
"html": "Getting startedPrerequisitesClaude in the PR review loop and hooks as approval gates, because the gates must exist before automation accelerates anything through them.InfrastructureA CI platform with the claude-code-action installed, or any runner that can call claude -p; model access through the API, or Bedrock, Foundry, or Vertex where traffic must stay on the organization's cloud agreement; MCP servers for the deployment targets; a sandbox profile for agent jobs with no standing production credentials."
},
{
"type": "heading",
"level": 4,
"text": "How to execute it",
"html": "How to execute it"
},
{
"type": "list",
"ordered": true,
"items": [
{
"text": "The platform engineer starts with read-only judgment steps. Use claude -p in a pipeline job to triage a failed build, summarize a flaky test, or draft the changelog.",
"html": "The platform engineer starts with read-only judgment steps. Use claude -p in a pipeline job to triage a failed build, summarize a flaky test, or draft the changelog."
},
{
"text": "Add write steps behind the existing gates for jobs like fixing lint, updating generated docs, or addressing review comments via the @claude mentions. Anything the agent writes arrives as a PR through branch protection, and the agent has no route to push to main.",
"html": "Add write steps behind the existing gates for jobs like fixing lint, updating generated docs, or addressing review comments via the @claude mentions. Anything the agent writes arrives as a PR through branch protection, and the agent has no route to push to main."
},
{
"text": "Execution is sandboxed. Agent jobs run in containers under a network policy with short-lived scoped tokens, and hold no production credentials by default.",
"html": "Execution is sandboxed. Agent jobs run in containers under a network policy with short-lived scoped tokens, and hold no production credentials by default."
},
{
"text": "Expose deployment through MCP. Deploy, status, and rollback become tools, scoped per environment, so the agent's deployment powers are an allowlist rather than a shell script with credentials.",
"html": "Expose deployment through MCP. Deploy, status, and rollback become tools, scoped per environment, so the agent's deployment powers are an allowlist rather than a shell script with credentials."
},
{
"text": "Tier the autonomy by environment. In development, the agent deploys freely. In production, the agent prepares the release and the release manager authorizes it, and a hook enforces the production gate. Staging sits somewhere in the middle.",
"html": "Tier the autonomy by environment. In development, the agent deploys freely. In production, the agent prepares the release and the release manager authorizes it, and a hook enforces the production gate. Staging sits somewhere in the middle."
},
{
"text": "Rollback should be the most rehearsed path in the pipeline, a single command that the agent can run and that is exercised regularly in staging. The closing the loop play (Stage 6: Maintenance) calls this rollback when a control band is breached, so it has to be proven in advance.",
"html": "Rollback should be the most rehearsed path in the pipeline, a single command that the agent can run and that is exercised regularly in staging. The closing the loop play (Stage 6: Maintenance) calls this rollback when a control band is breached, so it has to be proven in advance."
}
]
},
{
"type": "heading",
"level": 4,
"text": "What it looks like (pipeline step)",
"html": "What it looks like (pipeline step)"
},
{
"type": "code",
"text": "-\n name: Triage failed build\n\n if: failure()\n\n run: >\n\n claude -p \"Read the build log at out/build.log. Identify the most\n\n likely cause, say whether the failure looks flaky or real, and write a\n\n three-line summary for the PR thread.\" >> triage.md",
"lang": "markdown"
},
{
"type": "heading",
"level": 4,
"text": "Governance considerations",
"html": "Governance considerations"
},
{
"type": "paragraph",
"text": "The governing principle is that the agent may act up to the production gate and cannot pass it. The controls below enforce this principle.",
"html": "The governing principle is that the agent may act up to the production gate and cannot pass it. The controls below enforce this principle."
},
{
"type": "list",
"ordered": false,
"items": [
{
"text": "Branch protection turns anything the agent writes into a PR, with no direct path to main.",
"html": "Branch protection turns anything the agent writes into a PR, with no direct path to main."
},
{
"text": "The production deploy hook blocks the release until a named release manager authorizes it. Each non-interactive run acts under the agent's own identity, so the pipeline log separates what the agent did from what the engineer who triggered it did.",
"html": "The production deploy hook blocks the release until a named release manager authorizes it. Each non-interactive run acts under the agent's own identity, so the pipeline log separates what the agent did from what the engineer who triggered it did."
},
{
"text": "Per-environment permission tiers set how much the agent may do on the way to the gate.",
"html": "Per-environment permission tiers set how much the agent may do on the way to the gate."
}
]
},
{
"type": "paragraph",
"text": "How to measure it Leading indicator The share of pipeline failures triaged without paging a human taken from the CI/CD pipeline logs. Lagging indicator DevOps Research and Assessment (DORA) measures, which the CI system and deployment tooling already emit.",
"html": "How to measure itLeading indicatorThe share of pipeline failures triaged without paging a human taken from the CI/CD pipeline logs.Lagging indicatorDevOps Research and Assessment (DORA) measures, which the CI system and deployment tooling already emit."
},
{
"type": "paragraph",
"text": "06",
"html": "06"
},
{
"type": "heading",
"level": 2,
"text": "Maintain",
"html": "Maintain"
},
{
"type": "paragraph",
"text": "The loop closes. A trigger invokes Claude with no person in the invocation path, and what it finds re-enters the pipeline as intent.md .",
"html": "The loop closes. A trigger invokes Claude with no person in the invocation path, and what it finds re-enters the pipeline as intent.md."
},
{
"type": "heading",
"level": 3,
"text": "Maintenance and closing the loop",
"html": "Maintenance and closing the loop"
},
{
"type": "paragraph",
"text": "So far, we've discussed how to add Claude to each stage of the SDLC process, with each stage requiring a human to launch the initial steps. This stage, however, shifts the focus to autonomous running of Claude to close the loop.",
"html": "So far, we've discussed how to add Claude to each stage of the SDLC process, with each stage requiring a human to launch the initial steps. This stage, however, shifts the focus to autonomous running of Claude to close the loop."
},
{
"type": "paragraph",
"text": "For example, a continuously running monitoring agent could, off the back of a bug ticket being raised, create an intent.md , and flow through the requirements, plan, build test and review phases. Stage 6: Maintenance runs headless, with an independent confidence gate between stages, a deterministic check or an adversarial reviewing agent, deciding whether the previous stage's output continues or is escalated to a human.",
"html": "For example, a continuously running monitoring agent could, off the back of a bug ticket being raised, create an intent.md, and flow through the requirements, plan, build test and review phases. Stage 6: Maintenance runs headless, with an independent confidence gate between stages, a deterministic check or an adversarial reviewing agent, deciding whether the previous stage's output continues or is escalated to a human."
},
{
"type": "paragraph",
"text": "TraditionalMaintenance is a reactive phase. All tickets or incidents wait on a person to act on it and restart the process. An alert fires at 3 a.m. and can be missed, a ticket can sit in the backlog until someone picks it up, and post-mortem actions may not reach the codebase at all if another fire starts first.AI-nativeA trigger such as a control-band breach, a ticket, a channel message or a schedule invokes Claude without a person in the path. Claude diagnoses, acts only through gated routes, and writes what it finds as intent.md , which then goes through the stages described above. People triage and review that work, and no longer have to start it.",
"html": "TraditionalMaintenance is a reactive phase. All tickets or incidents wait on a person to act on it and restart the process. An alert fires at 3 a.m. and can be missed, a ticket can sit in the backlog until someone picks it up, and post-mortem actions may not reach the codebase at all if another fire starts first.AI-nativeA trigger such as a control-band breach, a ticket, a channel message or a schedule invokes Claude without a person in the path. Claude diagnoses, acts only through gated routes, and writes what it finds as intent.md, which then goes through the stages described above. People triage and review that work, and no longer have to start it."
},
{
"type": "heading",
"level": 3,
"text": "Closing the loop",
"html": "Closing the loop"
},
{
"type": "paragraph",
"text": "A deterministic script watches production and invokes Claude when a control band is breached. Monitoring of a breach is a helpful example of the pattern for the loop running autonomously, while the Claude Tag (public beta) section at the end of the stage covers work arriving through different channels.",
"html": "A deterministic script watches production and invokes Claude when a control band is breached. Monitoring of a breach is a helpful example of the pattern for the loop running autonomously, while the Claude Tag (public beta) section at the end of the stage covers work arriving through different channels."
},
{
"type": "paragraph",
"text": "Getting started Prerequisites Intent.md which gives the loop a structured output to restart. Claude accelerated PR reviews, hooks as an action boundary, and a rollback path for CI/CD (which the highest autonomy tier invokes). Infrastructure A metrics store the detection script can query (Prometheus, the CI system's API, or equivalents), read access to the repository, a way to run Claude Code non-interactively in CI, or the Agent SDK for a service that receives webhooks.",
"html": "Getting startedPrerequisitesIntent.md which gives the loop a structured output to restart. Claude accelerated PR reviews, hooks as an action boundary, and a rollback path for CI/CD (which the highest autonomy tier invokes).InfrastructureA metrics store the detection script can query (Prometheus, the CI system's API, or equivalents), read access to the repository, a way to run Claude Code non-interactively in CI, or the Agent SDK for a service that receives webhooks."
},
{
"type": "heading",
"level": 4,
"text": "How to execute it",
"html": "How to execute it"
},
{
"type": "list",
"ordered": true,
"items": [
{
"text": "The service owner or platform engineer picks one metric with a stable rolling baseline, such as CI test failure rate, post-deploy 5xx rate, or PR cycle time.",
"html": "The service owner or platform engineer picks one metric with a stable rolling baseline, such as CI test failure rate, post-deploy 5xx rate, or PR cycle time."
},
{
"text": "They write the detection script, typically mean and standard deviation over a rolling window with rules (Western Electric or similar) so the bands catch slow drift as well as spikes. The script is version controlled and unit tested, and detection stays entirely deterministic, with no model involved.",
"html": "They write the detection script, typically mean and standard deviation over a rolling window with rules (Western Electric or similar) so the bands catch slow drift as well as spikes. The script is version controlled and unit tested, and detection stays entirely deterministic, with no model involved."
},
{
"text": "Response tiers are defined in version-controlled config ( bands.yaml below). At 1σ the script only logs, at 2σ it invokes Claude read-only to diagnose, and at 3σ Claude may act, though only by opening a PR into the review gate or triggering a pre-approved runbook.",
"html": "Response tiers are defined in version-controlled config (bands.yaml below). At 1σ the script only logs, at 2σ it invokes Claude read-only to diagnose, and at 3σ Claude may act, though only by opening a PR into the review gate or triggering a pre-approved runbook."
},
{
"text": "The trigger layer can be a scheduled workflow in GitHub or GitLab, a webhook from the existing monitoring stack, or a Cron Job inside the network. Claude runs stateless, either as a non-interactive step on a CI runner or as an Agent SDK service in a sandboxed container, and the CI/CD play covers the deployment and model-access options. Because the run is stateless and non-interactive, a loop can begin and end without anyone starting it.",
"html": "The trigger layer can be a scheduled workflow in GitHub or GitLab, a webhook from the existing monitoring stack, or a Cron Job inside the network. Claude runs stateless, either as a non-interactive step on a CI runner or as an Agent SDK service in a sandboxed container, and the CI/CD play covers the deployment and model-access options. Because the run is stateless and non-interactive, a loop can begin and end without anyone starting it."
},
{
"text": "The agent writes its diagnosis as intent.md in the Stage 1: Plan format, covering the anomaly and its evidence, a proposed outcome, the affected systems and any open questions. From there the finding goes through the pipeline like anything else.",
"html": "The agent writes its diagnosis as intent.md in the Stage 1: Plan format, covering the anomaly and its evidence, a proposed outcome, the affected systems and any open questions. From there the finding goes through the pipeline like anything else."
},
{
"text": "The service owner or on-call engineer triages the queue, routing product-facing findings to the product owner. Fix now, schedule, or dismiss. Dismissals tune the bands and help to reduce noise.",
"html": "The service owner or on-call engineer triages the queue, routing product-facing findings to the product owner. Fix now, schedule, or dismiss. Dismissals tune the bands and help to reduce noise."
},
{
"text": "When a fix ships, add an eval for the incident (the continuous evals play) to ensure that such issues are protected against going forwards.",
"html": "When a fix ships, add an eval for the incident (the continuous evals play) to ensure that such issues are protected against going forwards."
}
]
},
{
"type": "heading",
"level": 4,
"text": "What it looks like (for example, a bands.yaml monitoring CI test failure rate)",
"html": "What it looks like (for example, a bands.yaml monitoring CI test failure rate)"
},
{
"type": "code",
"text": "metric:\n \nci_test_failure_rate\n\n\nbaseline:\n \nrolling_30d\n\n\nrules:\n \nwestern_electric\n\n\ntiers:\n\n\n \n1sigma:\n { \naction:\n \nlog\n }\n\n \n2sigma:\n { \naction:\n \ndiagnose\n,\n\n \ntools:\n \n\"Read,Grep,Bash(gh run view *)\"\n }\n\n \n3sigma:\n { \naction:\n \npropose\n,\n\n \nroutes:\n [\npull_request\n, \nrunbook:rollback-deploy\n] }",
"lang": "yaml"
},
{
"type": "heading",
"level": 4,
"text": "Governance considerations",
"html": "Governance considerations"
},
{
"type": "paragraph",
"text": "The tier boundaries are enforced from version-controlled config, with permissions and managed settings denying production access. Invocations, findings and triage decisions are logged with a timestamp. A service owner triages and approves findings, resulting changes go through the normal PR review gate, and the runbooks the agent may trigger were approved in advance.",
"html": "The tier boundaries are enforced from version-controlled config, with permissions and managed settings denying production access. Invocations, findings and triage decisions are logged with a timestamp. A service owner triages and approves findings, resulting changes go through the normal PR review gate, and the runbooks the agent may trigger were approved in advance."
},
{
"type": "paragraph",
"text": "How to measure it Leading indicator Time from band breach to an intent.md in the triage queue, against the old time from incident to post-mortem action. The detection script's log has the breach timestamp and tier of incident. Lagging indicator The share of findings that become merged fixes (triage queue against actual PR history), and repeat incidents of the same class, which should fall as the fixes add cases to the eval suite.",
"html": "How to measure itLeading indicatorTime from band breach to an intent.md in the triage queue, against the old time from incident to post-mortem action. The detection script's log has the breach timestamp and tier of incident.Lagging indicatorThe share of findings that become merged fixes (triage queue against actual PR history), and repeat incidents of the same class, which should fall as the fixes add cases to the eval suite."
},
{
"type": "heading",
"level": 4,
"text": "Examples",
"html": "Examples"
},
{
"type": "list",
"ordered": false,
"items": [
{
"text": "When the CI test failure rate breaches 3σ, the agent quarantines the flaky test or opens a revert PR, and the review gate decides.",
"html": "When the CI test failure rate breaches 3σ, the agent quarantines the flaky test or opens a revert PR, and the review gate decides."
},
{
"text": "When the post-deploy 5xx rate breaches 3σ with a deployment in the window, the agent triggers the existing rollback pipeline.",
"html": "When the post-deploy 5xx rate breaches 3σ with a deployment in the window, the agent triggers the existing rollback pipeline."
},
{
"text": "When PR cycle time trips a drift rule, the agent writes a report for engineering leadership, which shows the harness works for process metrics as well as production ones.",
"html": "When PR cycle time trips a drift rule, the agent writes a report for engineering leadership, which shows the harness works for process metrics as well as production ones."
}
]
},
{
"type": "paragraph",
"text": "Detection stays deterministic. Claude is invoked once a band is breached, and the tier sets what it may do.",
"html": "Detection stays deterministic. Claude is invoked once a band is breached, and the tier sets what it may do."
},
{
"type": "heading",
"level": 3,
"text": "Claude on call with Claude Tag",
"html": "Claude on call with Claude Tag"
},
{
"type": "paragraph",
"text": "Incidents can also arrive via other means such as workplace communication apps, like Slack or Teams. Incidents can look like a 10pm Slack message for an urgent fix on an incident channel and can now be actioned immediately. Claude Tag (public beta currently available in Slack) makes Claude a member of those channels under its own identity, so each new incident gets a first responder and the response itself becomes part of the loop and memory for future incidents.",
"html": "Incidents can also arrive via other means such as workplace communication apps, like Slack or Teams. Incidents can look like a 10pm Slack message for an urgent fix on an incident channel and can now be actioned immediately. Claude Tag (public beta currently available in Slack) makes Claude a member of those channels under its own identity, so each new incident gets a first responder and the response itself becomes part of the loop and memory for future incidents."
},
{
"type": "paragraph",
"text": "The conversation and institutional knowledge stay in the channel, with anyone in the channel able to guide and action the response. Any team member can test hypotheses, explore new options and investigate in real time with the channel history adding to the auditability. Through access to MCP Claude verifies the metric is back at baseline and confirms it in the thread, writes the post-mortem to a version-controlled lessons file that future investigations can read.",
"html": "The conversation and institutional knowledge stay in the channel, with anyone in the channel able to guide and action the response. Any team member can test hypotheses, explore new options and investigate in real time with the channel history adding to the auditability. Through access to MCP Claude verifies the metric is back at baseline and confirms it in the thread, writes the post-mortem to a version-controlled lessons file that future investigations can read."
},
{
"type": "paragraph",
"text": "Incidents are not the only work Claude Tag picks up. Tagged on a ticket over MCP or asked in the channel, Claude triages the work the same way. A small, well-bounded fix arrives as a PR through the review gate, and anything larger is written up as intent.md for Stage 1: Plan, at which point the loop starts feeding itself.",
"html": "Incidents are not the only work Claude Tag picks up. Tagged on a ticket over MCP or asked in the channel, Claude triages the work the same way. A small, well-bounded fix arrives as a PR through the review gate, and anything larger is written up as intent.md for Stage 1: Plan, at which point the loop starts feeding itself."
},
{
"type": "image",
"src": "https://cdn.prod.website-files.com/68a44d4040f98a4adf2207b6/6a8760aded54a2a8319cd5b9_fe6d780d.png",
"alt": "",
"caption": "The channel is the audit trail: request, diagnosis, human authorization and fix all stay where the incident was handled.",
"local": "img/04.png"
},
{
"type": "heading",
"level": 2,
"text": "Closing thoughts",
"html": "Closing thoughts"
},
{
"type": "paragraph",
"text": "Models and harnesses have become more advanced, allowing organizations to not just transform how they produce code, but the entire software development lifecycle.",
"html": "Models and harnesses have become more advanced, allowing organizations to not just transform how they produce code, but the entire software development lifecycle."
},
{
"type": "paragraph",
"text": "This transformation keeps human judgement central to the process and considers the governance and regulation requirements of large enterprise organizations.",
"html": "This transformation keeps human judgement central to the process and considers the governance and regulation requirements of large enterprise organizations."
},
{
"type": "paragraph",
"text": "This guide consolidated many of the real best practices our Applied AI team executes on a daily basis for our customers, and we hope you found it a practical and actionable resource.",
"html": "This guide consolidated many of the real best practices our Applied AI team executes on a daily basis for our customers, and we hope you found it a practical and actionable resource."
},
{
"type": "paragraph",
"text": "The loop keeps running. Human judgement stays above it.",
"html": "The loop keeps running. Human judgement stays above it."
},
{
"type": "heading",
"level": 3,
"text": "Resources and acknowledgments",
"html": "Resources and acknowledgments"
},
{
"type": "paragraph",
"text": "The documentation below is what a platform team needs to set those controls up, in roughly the order you would roll them out.",
"html": "The documentation below is what a platform team needs to set those controls up, in roughly the order you would roll them out."
},
{
"type": "paragraph",
"text": "Set up Claude Code for your organization — the admin decision map; start herecode.claude.com/docs/en/admin-setup Settings reference and precedence, including every managed-only keycode.claude.com/docs/en/settings Server-managed settings from the Claude admin consolecode.claude.com/docs/en/server-managed-settings Permissionscode.claude.com/docs/en/permissions Sandboxing — OS-level filesystem and network isolationcode.claude.com/docs/en/sandboxing Hooks — guidecode.claude.com/docs/en/hooks-guide Hooks — referencecode.claude.com/docs/en/hooks Skillscode.claude.com/docs/en/skills Plugins and private marketplaces — how skills and hooks are distributed organization-widecode.claude.com/docs/en/plugin-marketplaces Managed MCP — central control of the agent's tool surfacecode.claude.com/docs/en/managed-mcp Enterprise deployment overview — Bedrock, Vertex, Foundrycode.claude.com/docs/en/third-party-integrations Enterprise network configurationcode.claude.com/docs/en/network-config Monitoring (OpenTelemetry)code.claude.com/docs/en/monitoring-usage The analytics dashboardcode.claude.com/docs/en/analytics Compliance API — Enterprise activity feed, chat retrieval and deletionplatform.claude.com/docs/en/manage-claude/compliance-api Security modelcode.claude.com/docs/en/security",
"html": "Set up Claude Code for your organization — the admin decision map; start herecode.claude.com/docs/en/admin-setupSettings reference and precedence, including every managed-only keycode.claude.com/docs/en/settingsServer-managed settings from the Claude admin consolecode.claude.com/docs/en/server-managed-settingsPermissionscode.claude.com/docs/en/permissionsSandboxing — OS-level filesystem and network isolationcode.claude.com/docs/en/sandboxingHooks — guidecode.claude.com/docs/en/hooks-guideHooks — referencecode.claude.com/docs/en/hooksSkillscode.claude.com/docs/en/skillsPlugins and private marketplaces — how skills and hooks are distributed organization-widecode.claude.com/docs/en/plugin-marketplacesManaged MCP — central control of the agent's tool surfacecode.claude.com/docs/en/managed-mcpEnterprise deployment overview — Bedrock, Vertex, Foundrycode.claude.com/docs/en/third-party-integrationsEnterprise network configurationcode.claude.com/docs/en/network-configMonitoring (OpenTelemetry)code.claude.com/docs/en/monitoring-usageThe analytics dashboardcode.claude.com/docs/en/analyticsCompliance API — Enterprise activity feed, chat retrieval and deletionplatform.claude.com/docs/en/manage-claude/compliance-apiSecurity modelcode.claude.com/docs/en/security"
},
{
"type": "paragraph",
"text": "Thanks to Jim Blackhurst, Will Steuk, and Jamal Arif for their contributions to this guide, which was inspired by and built on much of their previous work.",
"html": "Thanks to Jim Blackhurst, Will Steuk, and Jamal Arif for their contributions to this guide, which was inspired by and built on much of their previous work."
}
],
"links": [
{
"text": "Claude Code",
"href": "https://claude.com/product/claude-code"
},
{
"text": "Cowork",
"href": "https://claude.com/product/cowork"
},
{
"text": "skills",
"href": "https://code.claude.com/docs/en/skills"
},
{
"text": "Claude Design",
"href": "https://claude.com/product/design"
},
{
"text": "plan mode",
"href": "https://code.claude.com/docs/en/permission-modes"
},
{
"text": "MCP",
"href": "https://code.claude.com/docs/en/mcp"
},
{
"text": "CLAUDE.md",
"href": "https://code.claude.com/docs/en/memory"
},
{
"text": "plugin",
"href": "https://code.claude.com/docs/en/plugin-marketplaces"
},
{
"text": "hook",
"href": "https://code.claude.com/docs/en/hooks"
},
{
"text": "git worktree",
"href": "https://code.claude.com/docs/en/worktrees"
},
{
"text": "subagent",
"href": "https://code.claude.com/docs/en/sub-agents"
},
{
"text": "Code Review",
"href": "https://code.claude.com/docs/en/code-review"
},
{
"text": "claude-code-action",
"href": "https://code.claude.com/docs/en/github-actions"
},
{
"text": "code.claude.com/docs/en/settings",
"href": "https://code.claude.com/docs/en/settings"
},
{
"text": "Claude Tag",
"href": "https://claude.com/product/tag"
},
{
"text": "Agent SDK",
"href": "https://platform.claude.com/docs/en/agent-sdk/overview"
},
{
"text": "Set up Claude Code for your organization — the admin decision map; start here code.claude.com/docs/en/admin-setup",
"href": "https://code.claude.com/docs/en/admin-setup"
},
{
"text": "Server-managed settings from the Claude admin console code.claude.com/docs/en/server-managed-settings",
"href": "https://code.claude.com/docs/en/server-managed-settings"
},
{
"text": "Permissions code.claude.com/docs/en/permissions",
"href": "https://code.claude.com/docs/en/permissions"
},
{
"text": "Sandboxing — OS-level filesystem and network isolation code.claude.com/docs/en/sandboxing",
"href": "https://code.claude.com/docs/en/sandboxing"
},
{
"text": "Hooks — guide code.claude.com/docs/en/hooks-guide",
"href": "https://code.claude.com/docs/en/hooks-guide"
},
{
"text": "Managed MCP — central control of the agent's tool surface code.claude.com/docs/en/managed-mcp",
"href": "https://code.claude.com/docs/en/managed-mcp"
},
{
"text": "Enterprise deployment overview — Bedrock, Vertex, Foundry code.claude.com/docs/en/third-party-integrations",
"href": "https://code.claude.com/docs/en/third-party-integrations"
},
{
"text": "Enterprise network configuration code.claude.com/docs/en/network-config",
"href": "https://code.claude.com/docs/en/network-config"
},
{
"text": "Monitoring (OpenTelemetry) code.claude.com/docs/en/monitoring-usage",
"href": "https://code.claude.com/docs/en/monitoring-usage"
},
{
"text": "The analytics dashboard code.claude.com/docs/en/analytics",
"href": "https://code.claude.com/docs/en/analytics"
},
{
"text": "Compliance API — Enterprise activity feed, chat retrieval and deletion platform.claude.com/docs/en/manage-claude/compliance-api",
"href": "https://platform.claude.com/docs/en/manage-claude/compliance-api"
},
{
"text": "Security model code.claude.com/docs/en/security",
"href": "https://code.claude.com/docs/en/security"
}
],
"word_count": 9873,
"fetched_at": "2026-08-21T15:44:21+00:00"
}