Modern AI-Driven SDLC
A Practitioner's Guide to Stage Contracts, Agent Controls, and Evidence-Based Delivery
AI can speed up every stage of delivery, but the gain holds only when each stage has clear inputs, checks, and a person accountable for the outcome.
Contents
- Preface
- About This Guide
- Part I. Foundations
- Part II. The Six Stages
- Part III. Cross-Cutting Concerns
- Part IV. Putting It to Work
- Appendices
- Appendix A. Stage Contract Template
- Appendix B. Pull Request Template for AI-Assisted Changes
- Appendix C. Agent Permission Policy (Starter)
- Appendix D. Eval-Driven Development Checklist for AI Features
- Appendix E. Review Checklist for Reviewers of AI-Authored Changes
- Appendix F. Accountability Matrix and Maturity Self-Assessment
- Appendix G. Glossary
- Appendix H. Standards and Frameworks
- Closing
Preface
Every engineering organization that has adopted AI assistants has seen the same early result. Individual developers get faster. Pull requests get larger. Review queues grow. Incidents trace back to code nobody fully read. The speed is real, but it does not become delivery performance on its own.
This guide exists to close that gap. It does not argue for or against AI in engineering. It assumes you are already using it, or are about to, and asks a narrower and more useful question: what must be true at each stage of delivery for the speed to survive contact with production?
The answer is a small, repeatable structure called the stage contract. For each stage of the lifecycle, a stage contract names the inputs that must exist, what the AI may do, the automated checks on its output, the named human who decides, and the evidence kept. Everything else in this guide (autonomy tiers, agent profiles, quality gates, roles, metrics, and the adoption path) is an elaboration of that one idea.
The guide is deliberately conservative about claims. It describes controls that mature engineering organizations already know how to operate: least privilege, presubmit checks, code ownership, progressive delivery, error budgets, blameless postmortems. It shows where AI plugs into them, and where it changes the risk profile enough to need something new.
About This Guide
What it covers
The guide applies AI across the whole software delivery lifecycle (requirements, design, build, test, release, and operations) in a way that keeps the speed and keeps accountability.
| Stage | Question it answers | Core practice |
|---|---|---|
| Requirements | What are we building, and what did we assume? | Source-linked stories and an assumptions ledger signed off by the product owner |
| Design | Which option fits our architecture and constraints? | Machine-readable decision records and policy checks on design |
| Build | How do agents change code without losing control? | Scoped access, required tests, and reviewable, small changes |
| Test | Do the tests show the change works, or only that coverage went up? | Mutation scoring and criteria traceability |
| Release | Is this safe to roll out, and who approved it? | Provenance, progressive delivery, and error budget gating |
| Operate | What is happening in production, and what should we do? | AI-assisted triage with humans in command |
Note: All six stages connect to one blue AI core through two-way navy arrows, so context and decisions pass in both directions at every stage. Blue arrows run Requirements → Design → Build → Test → Release → Operate. A dashed cyan arrow carries Operate back into Requirements as the feedback loop. Cyan dots on the arrows mark the data and context flowing between each stage and the core.
Who this guide is for
The guide is written for engineering leaders, staff and principal engineers, architects, platform and developer-experience teams, and security and SRE leads. It assumes you already run a mature delivery practice with version control, code review, CI/CD, and on-call. It does not ask you to replace that practice. It shows where AI plugs into it.
Using this guide in a large engineering organization
Organizations that already run mature delivery systems do not need a parallel process for AI. The guide is designed to attach to what exists:
- Every practice is expressed as artifacts and checks that fit existing tooling: files in version control, checks in CI, policies as code, records in the review system.
- Chapter 13 maps each concept to the practices established teams already use (launch checklists, presubmit checks, code ownership, progressive delivery, error budgets, blameless postmortems) and shows how to connect them.
- Chapter 14 walks one realistic change through all six stages so you can see the contracts working together.
- Chapter 15 gives a phased adoption path, with a decision rule for raising autonomy only when measurement supports it.
- Chapter 12 describes governance and measurement, so standards scale across many teams without becoming a bottleneck.
How to read it
| If you want to... | Read |
|---|---|
| Get the model quickly | Chapters 1 and 2 |
| Fix the stage that hurts most | The matching chapter in Chapters 3 to 8 |
| Set policy for coding agents | Chapters 9 and 10, Appendices A and C |
| Plan the rollout | Chapters 13, 15, and Appendix F |
| Review AI-authored changes | Chapter 9 and Appendices B and E |
Each chapter in Part II follows the same shape: what AI is good at, where it is risky, the stage contract, a practical pattern, and metrics. Use the appendices as templates you can copy.
Conventions
- The guide is vendor-neutral. Where it mentions standards or frameworks (DORA, SLOs, SBOM, SLSA, OWASP, NIST AI RMF, OpenTelemetry, and the Model Context Protocol), it does so because they are useful integration points, not because the approach depends on them. Verify current versions and capabilities before adopting them.
- Code and configuration are illustrative. They show the shape of a solution, not a library to copy. Numeric thresholds (diff sizes, mutation scores, budgets, retention periods) are starting points to be set by your own risk policy.
- Autonomy tiers are named L0 to L4 (Chapter 2) and are used consistently throughout.
- Company practices are referred to by category (for example, "presubmit checks" or "launch review"), not by proprietary names, because internal names and details differ and change.
Part I. Foundations
Chapter 1. The Problem: Local Speed, Global Drag
In this chapter: why faster code generation does not automatically produce faster delivery, and the reframing that the rest of the guide builds on.
1.1 Where the time actually goes
Writing code was never the whole job. In most organizations, a change spends the majority of its life waiting: for a decision, for a review, for a test environment, for an approval, for a deploy window. AI that makes code generation ten times faster attacks one segment of that timeline.
When only one segment accelerates, three things tend to happen.
- Queue pressure moves downstream. More code arrives at review and test than those stages were sized for.
- Defects move downstream too. Generated code that looks plausible passes a quick read and fails later, where fixes cost more.
- Accountability blurs. When a change is largely machine-authored, "who owns this?" becomes harder to answer unless the process forces an answer.
Read it top to bottom, comparing the two bars.
-
Top bar, “Before AI.” This is a software delivery pipeline with four steps: Write, Review, Test, Ship. Each step takes a similar share of the total time, so no single step dominates.
-
The blue arrow. It points from the Write segment to the small blue “W” in the bottom bar. AI tools make writing code much faster, so that step shrinks sharply. The blue is the only strong color in the diagram because that shrinkage is the thing that changed.
-
Bottom bar, “After AI (naive).” “Naive” means the team adopted AI for writing code but changed nothing else. Code now arrives faster than people can review, test and ship it, so the work piles up in “Review / Test / Ship queues.” That segment is long because it is now where work waits.
-
The dashed cyan lines and the bracket. The dashed lines at both ends of the bars, and the navy bracket beneath, show that both bars are the same total length. Despite the faster Write step, the end-to-end time did not improve.
-
The caption. “One segment shrinks, the system does not” is the takeaway. Speeding up one stage doesn’t speed up the whole system, because the bottleneck moves to the next stage. This is the idea behind the theory of constraints.
In practice, to get real gains from AI, a team has to speed up the other stages too, such as automated testing, review and release.
1.2 The reframing
The question is not "how do we use AI to write code faster?" It is "how do we redesign each stage so that AI work arrives with evidence, and a named person decides?"
That reframing gives us a unit of design: the stage contract.
Key takeaways
- Local speed-ups create downstream queues unless the whole flow is redesigned.
- The goal is evidence-bearing AI work with a named human decision, not more generated code.
Chapter 2. The Core Model: The Stage Contract
In this chapter: the five parts of a stage contract, three design rules, and the autonomy tiers L0 to L4.
2.1 Definition
A stage contract defines how AI participates in one stage of delivery. It has five parts, including a named human role accountable for the decision at the human gate.
| Element | Question it answers |
|---|---|
| Inputs | What must exist before AI work starts? (approved artifacts, context, constraints) |
| AI action | What is the AI allowed to do, and with what access? |
| Checks | What automated verification runs on the output? |
| Human gate | Which named role decides whether the output proceeds? |
| Evidence | What record is kept so the decision can be audited and learned from? |
If any of the five is missing, the stage is running on hope.
2.2 The six stage contracts at a glance
The table below is the backbone of the guide. It expands the minimal view (AI action and human gate) into the full contract.
| Stage | AI does | Typical inputs | Automated checks | Human gate | Evidence kept |
|---|---|---|---|---|---|
| Requirements | Draft stories and acceptance criteria | Product brief, user research, domain glossary | Template completeness, ambiguity lint, traceability links | Product owner signs off | Approved story set with source links |
| Design | Propose options against architecture decisions | ADRs, reference architectures, NFRs | Policy-as-code on design constraints, cost estimate | Architect approves | Decision record with rejected options |
| Build | Coding agents work in scoped repos | Approved stories, design, repo context file | Compile, lint, unit tests, SAST, secrets scan | Engineer or code owner reviews the evidence and approves the change after blocking checks pass | Agent run log, diff, test results |
| Test | Generate and expand test suites | Acceptance criteria, code diff, prod traffic shapes | Mutation score, coverage delta, flake detection | Engineer reviews coverage | Coverage and mutation report |
| Release | Summarize changes, check policy | Merged diffs, risk signals, SLO state | Provenance, SBOM, vulnerability and license policy | Release owner or designated approver approves the rollout | Release notes, approval record |
| Operate | Triage incidents, suggest fixes | Telemetry, runbooks, recent changes | Read-only by default, change-risk scoring | On-call decides | Incident timeline with AI suggestions and outcomes |
2.3 Three design rules
Rule 1: AI proposes, people decide. An AI output is a candidate until a named human accepts it. This is not distrust. It is how you keep accountability intact when authorship is shared.
Rule 2: Gates verify, they do not re-do. A human gate works only if the reviewer is checking evidence (tests, diffs, policy results), not recreating the work. If the reviewer must redo the work to trust it, the gate has no leverage.
Rule 3: Least privilege for agents. Any AI that can act (edit files, run commands, call APIs) is granted only the access its task requires, for only as long as it needs it.
2.4 Autonomy is a dial, not a switch
Not every task deserves the same level of oversight. Define autonomy tiers and assign work to them deliberately.
| Tier | Name | AI behavior | Example |
|---|---|---|---|
| L0 | Assist | Suggests, human types | Inline completion, explain this function |
| L1 | Draft | Produces an artifact, human edits | First-draft story, test skeleton |
| L2 | Act with review | Executes in a sandbox, opens a change for review | Coding agent opens a PR |
| L3 | Act with guardrails | Executes and merges automatically for narrow, low-risk classes of change | Dependency bumps with passing tests, doc fixes |
| L4 | Operate autonomously | Takes production actions within a pre-approved envelope | Automated rollback on SLO breach |
Most organizations should spend most of their effort at L1 and L2, move specific low-risk classes to L3 after measuring them, and treat L4 as an exception earned through evidence.
Key takeaways
- A stage contract has five parts; a missing part is a gap, not a detail.
- Gates check evidence; they do not redo the work.
- Autonomy is assigned per class of work and raised only on evidence.
Part II. The Six Stages
Chapter 3. Requirements
In this chapter: how to use AI on requirements without letting unflagged assumptions ship.
3.1 What AI is good at here
Requirements work is language work, which is where models are strong. AI can:
- Turn a product brief or customer interview notes into candidate user stories.
- Draft acceptance criteria in a consistent form (for example Given/When/Then).
- Detect ambiguity, missing edge cases, conflicting statements, and undefined terms.
- Cross-check new stories against existing behavior to find overlaps.
- Produce a first-pass non-functional requirements list (latency, availability, privacy, accessibility).
3.2 Where it is risky
- Plausible invention. Models fill gaps with reasonable-sounding assumptions. In requirements, an unflagged assumption becomes a defect that ships.
- Loss of intent. Polished stories can drift from what the customer actually said.
- False completeness. A long list of acceptance criteria looks thorough even when key cases are missing.
3.3 The stage contract
Inputs. Source material the story is derived from (brief, research, tickets), a domain glossary, and the product's existing behavior descriptions.
AI action. Draft stories and criteria. Every statement must link to its source. Any statement without a source is labeled an assumption.
Checks.
- Template completeness (actor, goal, value, criteria, non-functionals present).
- Ambiguity lint (vague terms such as "fast," "easy," "appropriate" flagged).
- Traceability (every story links to a source and every criterion is testable).
Human gate. The product owner signs off. The sign-off covers the assumptions list explicitly: each assumption is confirmed, corrected, or deleted.
Evidence. Approved story set with source links and the resolved assumptions list.
3.4 Practical pattern: the assumptions ledger
Require every AI-drafted requirement set to end with a ledger:
ASSUMPTIONS (resolved by: <product owner>, date)
A1. Users are authenticated before reaching checkout. [confirmed]
A2. Refunds apply to digital goods. [corrected: physical only]
A3. Guest checkout is out of scope. [confirmed]
This turns the model's biggest weakness into a reviewable object.
3.5 Metrics
- Share of stories requiring rework after engineering review.
- Defects traced to requirement misunderstanding.
- Time from brief to approved backlog.
Key takeaways
- Every statement links to a source or is labeled an assumption.
- The product owner resolves each assumption explicitly.
Chapter 4. Design
In this chapter: using AI as a sparring partner for design, with decisions recorded in a form both people and tools can use.
4.1 What AI is good at here
Design is where AI is most useful as a sparring partner and least useful as an oracle. It can:
- Generate several candidate approaches for a stated problem.
- Compare options against stated constraints and tradeoffs.
- Draft design documents and sequence diagrams from notes.
- Check a proposal against existing architecture decision records (ADRs) and flag conflicts.
- Estimate rough cost and capacity implications.
4.2 Where it is risky
- Generic answers. Without organization-specific context, designs regress to textbook patterns that ignore your platform, your data gravity, and your operating model.
- Confident omission. The design may sound complete while skipping failure modes, migration paths, or data governance.
- Anchoring. A fluent first option can crowd out better ones.
4.3 The stage contract
Inputs. Approved requirements, the relevant ADRs, reference architectures, approved technology list, non-functional targets (latency, availability, cost), and data classification of the systems involved.
AI action. Propose at least three options against the architecture decisions already in force, with tradeoffs, risks, and a migration or rollback path for each. The AI must cite which ADRs and constraints each option satisfies or violates.
Checks.
- Policy-as-code on design constraints (approved services, data residency, encryption requirements).
- Cost and capacity estimate within a stated tolerance.
- Completeness checklist: failure modes, observability, security model, data lifecycle, rollout plan.
Human gate. The architect approves. The architect chooses an option, or rejects all and states why.
Evidence. A decision record that keeps the rejected options and reasons. Rejected options are valuable. They prevent the same debate from being re-run six months later.
4.4 Practical pattern: ADRs as machine-readable context
If your ADRs are prose scattered across wikis, the AI cannot honor them. Give each ADR a stable ID, a status, a scope, and a short normative statement. Then design prompts can reference them, and checks can verify that a proposal cites the relevant ones.
ADR-0042 Status: Accepted Scope: all services handling PII
Decision: Services handling PII use the managed secrets store and
field-level encryption. Direct database credentials in
config are prohibited.
4.5 Metrics
- Share of designs that cite applicable ADRs.
- Design rework rate after build starts.
- Time from approved requirements to approved design.
Key takeaways
- Ask for at least three options, each citing the ADRs it satisfies or violates.
- Keep rejected options and the reasons in the decision record.
Chapter 5. Build
In this chapter: how coding agents change code without losing control: scoped access, required tests, and reviewable changes.
5.1 The shift from completion to agents
Early AI coding tools completed lines. Current tools plan multi-step changes, edit many files, run commands, read test output, and iterate. This is a different risk class. A completion tool that is wrong wastes a keystroke. An agent that is wrong can modify the wrong module, exfiltrate a secret, or quietly weaken a test.
5.2 The stage contract
Inputs.
- An approved story with acceptance criteria.
- The relevant design or ADRs.
- A repository context file (see 5.4) that tells the agent how this codebase builds, tests, and is organized.
AI action. Coding agents work in scoped repos: a sandboxed checkout, a limited set of writable paths, a limited set of allowed commands, no production credentials, and network access restricted to an allowlist.
Checks. Compile, lint and format, unit tests, static analysis, secrets scanning, dependency policy, and a diff-size limit.
Human gate. An engineer or code owner reviews the evidence and approves the change. This review happens only after the blocking checks pass. A change whose tests fail, are missing, or were weakened does not proceed to human review.
Evidence. The agent's run log, the diff, the test results, and the identity of the person who assigned the task.
5.3 Scoping agents: the permission model
Treat an agent like a new contractor on their first day. Give it a desk, not the keys to the building.
| Control | Recommended default |
|---|---|
| Filesystem | Write access limited to the target repo or a declared subset of paths; read-only elsewhere |
| Commands | Allowlist of build and test commands; deny by default for network tools, package publishing, and deployment |
| Network | Egress allowlist (package mirrors, internal docs); no open internet unless required |
| Secrets | None by default. Task-specific, short-lived, least-privilege credentials only when needed |
| Production | No access. Staging only, read-only where possible |
| Time and budget | Maximum wall-clock time, step count, and token or cost budget per task |
| Identity | Agent acts under a distinct service identity so its actions are attributable |
5.4 The repository context file
Agents perform far better, and far more safely, when the repository tells them how it works. Maintain a short, version-controlled context file at the repo root (many tools read a file named AGENTS.md or a tool-specific equivalent). Keep it factual and brief.
# Repo context for coding agents
## Build and test
- Build: `make build`
- Unit tests: `make test` (must pass before opening a PR)
- Lint and format: `make lint`
## Layout
- `api/` public service handlers
- `core/` domain logic (no I/O)
- `infra/` deployment config (do NOT modify without owner approval)
## Rules
- Never edit files under `infra/` or `.github/`.
- Never weaken or delete existing tests. Add tests for new behavior.
- Public API changes require a note in `CHANGELOG.md`.
- Keep PRs under 400 changed lines. Split larger work.
## Where to look
- Design decisions: `docs/adr/`
- Ownership: `CODEOWNERS`
Treat this file as code. It is reviewed, versioned, and owned. Note that the context file guides the agent but does not enforce anything; the rules that matter (protected paths, test requirements) must also be enforced by the pipeline.
5.5 Required tests: three rules
- Behavior change needs test change. A pull request that changes behavior without adding or updating tests is rejected by an automated check.
- No silent weakening. Detect deleted assertions, newly skipped tests, loosened thresholds, and broadened mocks. These are the most common ways an agent "makes the build green" without making the code correct.
- Tests come from criteria, not only from code. When possible, generate tests from the acceptance criteria rather than from the implementation, so the tests are not simply a mirror of the code's own assumptions.
5.6 Keeping changes reviewable
Review quality collapses as diffs grow. Enforce:
- A diff-size budget (lines and files) per agent PR, with automatic splitting guidance.
- A structured PR description: intent, approach, risks, test evidence, areas the reviewer should look at hardest.
- Provenance labels on the PR indicating AI involvement and the autonomy tier used.
5.7 Common failure modes
| Failure mode | What it looks like | Counter |
|---|---|---|
| Test gaming | Tests edited to pass; assertions removed | Weakening detector; protected test directories |
| Hallucinated dependencies | Imports of packages that do not exist or are typo-squats | Dependency allowlist; registry verification |
| Scope creep | Unrelated refactors bundled into a feature PR | Path scoping; diff-size budget |
| Context poisoning | Instructions hidden in issues, comments, or fetched web content steer the agent | Treat all external text as untrusted; restrict tools after reading untrusted content |
| Secret exposure | Keys printed to logs or committed | No secrets by default; secrets scan on every diff |
| Convention drift | Code works but ignores house patterns | Repo context file; lint rules that encode conventions |
5.8 Metrics
- Agent PR acceptance rate and time-to-merge.
- Rework: share of agent PRs needing more than one review round.
- Escaped defects per agent-authored change versus human-authored.
- Share of PRs within the diff-size budget.
Key takeaways
- Green automated checks are a precondition for human review, not a substitute for it.
- Scope the agent by identity, paths, commands, network, secrets, and budget.
- The context file informs the agent; the pipeline enforces the rules.
Chapter 6. Test
In this chapter: using AI to expand testing while measuring whether tests actually detect faults.
6.1 What AI is good at here
Testing is a strong use case because tests are checkable. AI can:
- Generate unit tests for new and legacy code.
- Expand edge cases from acceptance criteria and boundary analysis.
- Generate property-based tests and fuzz inputs.
- Draft integration and end-to-end scenarios from user flows.
- Triage flaky tests and cluster failures by root cause.
- Maintain test suites as code evolves (update broken selectors, fix brittle fixtures).
6.2 The trap: coverage is not quality
AI can raise line coverage very quickly with tests that execute code but assert almost nothing. The number goes up. Confidence does not.
6.3 The stage contract
Inputs. Acceptance criteria, the code diff, existing test suite, and where available, production traffic shapes and past incident patterns.
AI action. Generate and expand test suites. Prefer tests derived from criteria and behavior over tests derived mechanically from implementation.
Checks.
- Mutation testing on changed code: do the tests fail when the code is deliberately broken? This measures whether tests assert anything.
- Coverage delta on changed lines, not only global coverage.
- Flake detection: new tests must pass repeatedly before joining the blocking suite.
- Determinism checks (no reliance on time, ordering, or network without control).
Human gate. An engineer reviews coverage. The review is specific: are the important behaviors tested, are the assertions meaningful, and are the highest-risk paths covered? The engineer uses the mutation report to guide where to look.
Evidence. Coverage and mutation report attached to the change.
6.4 Practical pattern: the test quality scorecard
| Signal | Meaning | Gate suggestion |
|---|---|---|
| Mutation score on changed code | Do tests detect faults? | Minimum threshold set per service tier |
| Assertion density | Are tests asserting outcomes? | Flag tests with zero or trivial assertions |
| Flake rate of new tests | Are tests stable? | Quarantine until stable |
| Criteria traceability | Does each acceptance criterion have a test? | Block if any criterion is untested |
6.5 Beyond functional tests
AI-enabled systems need additional testing categories:
- Evaluation suites for features that contain a model: golden datasets, regression sets, adversarial prompts, and rubric-based scoring. See Chapter 10 and Appendix D.
- Performance and cost tests to catch latency and token-cost regressions.
- Security tests including prompt injection and tool-abuse scenarios for agentic features.
6.6 Metrics
- Mutation score trend on changed code.
- Escaped defects by area.
- Share of acceptance criteria with linked tests.
- Flake rate and mean time to fix a flaky test.
Key takeaways
- Measure whether tests detect faults (mutation), not only whether code executes (coverage).
- Block changes with untested acceptance criteria.
Chapter 7. Release
In this chapter: using AI to summarize and check releases while the deployment pipeline, not the model, enforces safety.
7.1 What AI is good at here
Release work combines summarization and policy checking, both strong fits. AI can:
- Summarize what changed in a release in language suited to different audiences (engineers, support, customers).
- Highlight risky changes: touched critical paths, schema migrations, config flips, dependency upgrades.
- Check changes against release policy and flag exceptions.
- Draft rollout plans with suggested stages, canary criteria, and rollback triggers.
- Assemble compliance evidence automatically.
7.2 The stage contract
Inputs. Merged diffs, change risk signals, current SLO and error budget state, deployment history, and policy definitions.
AI action. Summarize changes, assess risk, check policy, and propose a rollout plan.
Checks.
- Provenance and integrity: build attestations and a software bill of materials (SBOM) for the artifact.
- Vulnerability and license policy on dependencies.
- Migration safety checks: backward compatibility, reversible schema changes.
- Error budget check: if the service has exhausted its budget, risky releases are blocked or require escalation.
Human gate. The release owner or designated approver approves the rollout. Code-merge approval remains part of the preceding build and review workflow. For higher-risk releases, approval should come from the service owner and, where the organization requires it, a second reviewer.
Evidence. Release notes, risk assessment, approval record, and attestations, stored with the release.
7.3 Practical pattern: progressive delivery with AI-informed risk
AI summarizes risk, but the deployment mechanism enforces safety.
- Deploy behind a feature flag, off by default.
- Canary to a small percentage of traffic.
- Compare canary against baseline on SLO indicators (error rate, latency, saturation, business metrics).
- Promote automatically only when thresholds hold; roll back automatically when they break.
- Record the decision and metrics as evidence.
The model may suggest thresholds and write the summary. The thresholds are defined and approved by the service owner, then enforced by the deployment pipeline, not chosen by the model at decision time.
7.4 Metrics
- Change failure rate and time to restore, split by AI involvement.
- Deployment frequency and lead time for changes.
- Share of releases with complete evidence.
- Rollbacks triggered automatically versus manually.
Key takeaways
- Separate the merge decision (Build) from the rollout decision (Release).
- Models may propose thresholds; owners approve them; the pipeline enforces them.
Chapter 8. Operate
In this chapter: AI-assisted incident triage with humans in command, and how to earn autonomy in operations.
8.1 What AI is good at here
Operations produces large volumes of noisy, time-sensitive data. AI can:
- Correlate alerts, logs, traces, and recent changes to form incident hypotheses.
- Summarize an incident timeline for responders and stakeholders.
- Retrieve relevant runbooks, past incidents, and ownership information.
- Suggest mitigations (rollback, flag flip, scale-out) with expected effects.
- Draft postmortems from the incident record.
- Reduce alert noise by clustering and deduplicating.
8.2 The stage contract
Inputs. Telemetry (metrics, logs, traces), runbooks, service ownership data, deployment and change history, and past incident records.
AI action. Triage incidents and suggest fixes. Read-only by default. The AI investigates and recommends. It does not change production unless a specific, pre-approved action is defined for it.
Checks.
- Change-risk scoring on any proposed remediation.
- Blast-radius limits on automated actions.
- Audit logging of every query and recommendation.
Human gate. On-call decides. The responder accepts, modifies, or rejects each suggestion. During high-severity incidents, the human retains command.
Evidence. Incident timeline that records which AI suggestions were offered, which were taken, and what happened. This record is gold for improving the system and for postmortems.
8.3 Earning autonomy in operations
Move specific remediations from "suggest" to "execute" only when all of these hold:
- The action is reversible and bounded (limited blast radius).
- It has been recommended and accepted correctly many times, with measured outcomes.
- A kill switch exists and is tested.
- The action is logged and alerts a human when it fires.
Typical candidates: restarting a stateless service, rolling back the most recent deploy when SLOs break, scaling within a fixed range. Typical non-candidates: data deletion, schema changes, anything touching security controls.
8.4 Feeding operations back into the lifecycle
Operate is not the end. It is the sensor for the whole system.
- Incidents become new test cases and new evaluation items.
- Recurring toil becomes a candidate for automation.
- Postmortem findings update ADRs, runbooks, and the repository context file.
- Production usage informs the next round of requirements.
8.5 Metrics
- Mean time to detect and mean time to restore.
- Share of incidents where AI triage surfaced the correct cause within a target time.
- Alert noise reduction and on-call load.
- Acceptance rate of AI suggestions.
Key takeaways
- Read-only by default; humans retain incident command.
- Autonomous remediation requires reversibility, a boundary, a tested kill switch, and a track record.
Part III. Cross-Cutting Concerns
Chapter 9. Coding Agents in Depth: Scoped Access, Required Tests, Review Before Merge
In this chapter: the three Build controls consolidated into an operating policy you can adopt directly.
9.1 Scoped access
Define agent profiles, each with a fixed permission set, and assign tasks to profiles rather than negotiating permissions case by case.
| Profile | Typical use | Write scope | Commands | Network |
|---|---|---|---|---|
| Reader | Code search, explanation, impact analysis | None | Read-only tools | Internal docs only |
| Contributor | Feature work, bug fixes | Target repo paths | Build, test, lint | Package mirror only |
| Maintainer | Dependency bumps, mechanical refactors | Repo, with protected paths excluded | Build, test, codemod tools | Package mirror only |
| Operator | Incident triage | None | Read-only telemetry queries | Internal observability only |
9.2 Required tests
Make test requirements machine-enforced:
- The pipeline blocks a PR from being merged or advanced when required tests fail.
- The pipeline refuses behavior changes lacking test changes.
- The pipeline flags weakened or removed tests for mandatory human attention.
- Protected paths (for example the test harness itself, CI configuration) cannot be edited by agents.
9.3 Review before merge
Human review is the last line of defense, so protect its quality.
- Every agent change has a human reviewer who did not author the task prompt where feasible, so the check is independent.
- Reviewers see evidence first: test results, mutation report, policy checks, then the diff.
- Review is time-boxed against a diff-size budget. If a change is too large to review well, it is split. It is not skimmed.
- Merge rights stay with people. The agent may prepare a merge. It does not complete one, except in L3 classes explicitly approved.
9.4 Prompt injection and untrusted content
Agents read issues, web pages, logs, documents, and tool outputs. Any of those can contain instructions written by someone other than your team. Defend in layers:
- Label all external content as untrusted data, never as instructions.
- After an agent ingests untrusted content, restrict its tools for the remainder of the task (for example, no network, no secret access).
- Require confirmation for sensitive actions that originate after untrusted input.
- Monitor for anomalous behavior: unexpected outbound requests, edits outside scope, repeated attempts at denied actions.
The OWASP guidance for LLM applications is a good starting checklist for these risks. Verify the current version.
9.5 Attribution and audit
Every agent action should be attributable: which agent, which version, which prompt or task, which human requested it, which tools it called. Without this, incident analysis and compliance become guesswork.
Key takeaways
- Assign tasks to fixed profiles; do not negotiate permissions per task.
- Untrusted content is data. After reading it, narrow the agent's tools.
- Every action is attributable to an agent, a task, and a requesting human.
Chapter 10. Quality, Security, and Cost Built Into the Pipeline
In this chapter: why controls must exist from the first pilot, and the gates, checks, and budgets that make up the pipeline.
The principle: these checks are part of the pipeline from day one. They are not added later.
10.1 Why "later" fails
Controls bolted on after adoption meet resistance because they slow people who have already built habits around speed. Controls built in from the start become part of what "working" means. They are also cheaper, since the cost of fixing a defect grows with every stage it passes through.
10.2 A pipeline of gates
Task ──► Agent work ──► Gate 1: Build & unit tests
Gate 2: Static analysis, secrets, dependency policy
Gate 3: Test-quality (mutation, criteria traceability)
Gate 4: Security (SAST/DAST, injection tests for AI features)
Gate 5: Eval suite (for features containing a model)
Gate 6: Cost and performance budget
Gate 7: Provenance, SBOM, release policy
──► Human review & approval ──► Progressive rollout
10.3 Quality checks
- Mutation score, assertion density, criteria traceability (Chapter 6).
- Maintainability: complexity, duplication, dependency direction rules.
- Eval-driven development for AI features. If the product contains a model, prompt, or agent, treat evaluations as tests. Maintain golden datasets, regression sets, and rubric scoring, and run them on every change to prompts, models, retrieval configuration, or tools. A prompt edit is a code change and needs a test.
10.4 Security checks
- Secrets scanning and static analysis on every diff.
- Dependency allowlists and verification against hallucinated or typo-squatted packages.
- Software supply chain integrity: build attestations and SBOMs. Frameworks such as SLSA describe levels of build integrity.
- Threat modeling updated for AI-specific risks: prompt injection, tool abuse, data leakage through context, insecure output handling, excessive agency.
- Alignment with a risk management framework such as the NIST AI RMF where your organization uses one.
10.5 Cost checks
AI changes the cost profile of both building and running software.
Cost of building. Token and compute spend for agents, test generation, and review assistance. Track cost per merged change and cost per accepted suggestion. Set per-task budgets.
Cost of running. For AI features, token usage per request, model choice per task, caching, and batching. Set budgets in CI and block release when measured regressions exceed the approved thresholds.
| Cost control | Mechanism |
|---|---|
| Per-task budget | Step and token caps on agents |
| Model routing | Smaller models for simple tasks, larger for hard ones, decided by measured quality |
| Caching | Reuse of repeated context and results |
| Regression gate | Fail if token or latency per request exceeds threshold versus baseline |
| Attribution | Tag spend by team, service, and use case for showback |
10.6 Making gates tolerable
Gates fail when they are slow, noisy, or opaque. Keep them fast (run cheap checks first), precise (tune out false positives), and explainable (every failure says what to fix). A gate that people route around is worse than no gate.
Key takeaways
- Build gates in from the first pilot; order them cheap-first.
- Treat prompts, models, and retrieval configuration as code that needs tests.
- Budget and attribute cost for both building and running AI.
Chapter 11. Roles and Skills for Changing Work
In this chapter: how roles shift, which skills to invest in, and how to protect learning paths.
AI changes what people spend their days doing more than it changes who is needed.
11.1 How roles shift
| Role | Shifts away from | Shifts toward |
|---|---|---|
| Product owner | Writing every story by hand | Curating intent, resolving assumptions, owning acceptance |
| Architect | Producing every diagram | Curating decisions, maintaining machine-readable ADRs, reviewing options |
| Software engineer | Typing implementation | Specifying tasks precisely, reviewing evidence, decomposing work, owning outcomes |
| Test / quality engineer | Writing every test | Designing test strategy, evaluating test quality, owning eval suites |
| Platform / DevEx engineer | Tooling maintenance | Agent platforms, sandboxes, policy-as-code, pipeline gates |
| SRE / on-call | Manual triage | Supervising AI triage, defining safe automations, error budget policy |
| Security engineer | Late-stage review | Built-in controls, AI threat modeling, agent permission design |
| Engineering manager | Throughput tracking | Quality and flow, capability building, risk posture |
11.2 Skills worth investing in
- Specification skill. Writing a task so precisely that an agent can do it and a reviewer can judge it. This is the new core craft.
- Evidence-based review. Reviewing tests, reports, and diffs efficiently, and knowing where models tend to be wrong.
- Decomposition. Breaking work into small, verifiable units.
- Evaluation design. Building datasets, rubrics, and metrics for AI behavior.
- Systems thinking. Seeing where speed in one stage becomes a queue in another.
- Security literacy for AI. Understanding injection, excessive agency, and data exposure.
11.3 A caution for early-career engineers
If juniors only review machine output, they may never build the intuition that makes review good. Protect learning paths: pair juniors with seniors, assign hand-written work on purpose, require them to explain agent-produced changes, and rotate them through on-call and incident review.
11.4 Accountability stays human
Write it down. For each stage, the accountable role is named in the stage contract. "The AI did it" is never an acceptable answer to "why did this ship?"
Key takeaways
- Specification and evidence-based review become core engineering skills.
- Preserve hands-on learning for early-career engineers deliberately.
Chapter 12. Governance and Measurement
In this chapter: a balanced measurement set, the vanity metrics to avoid, and a light governance structure.
12.1 What to measure
Use a balanced set so that speed cannot be bought with quality.
Flow (are we faster?)
- Lead time for changes, deployment frequency.
- Time in each stage and queue time between stages.
Stability (are we safe?)
- Change failure rate, time to restore.
- Escaped defects, incident count and severity.
Quality of AI contribution
- Agent PR acceptance and rework rate.
- Mutation score, eval pass rate.
- Share of AI suggestions accepted and later reverted.
Cost
- Cost per merged change, cost per accepted suggestion.
- Cost per request for AI features.
Human factors
- Reviewer load and review time.
- Developer satisfaction, cognitive load, trust calibration.
The widely used delivery metrics from the DORA research (deployment frequency, lead time, change failure rate, time to restore) remain the right outer frame. Add the AI-specific measures above, and always segment by AI involvement so you can see whether AI-assisted work is genuinely better or merely faster.
12.2 Beware vanity metrics
| Vanity metric | Why it misleads | Better alternative |
|---|---|---|
| Lines of AI-generated code | Rewards volume | Accepted changes that stayed in production |
| Suggestion acceptance rate alone | Can reflect over-trust | Acceptance combined with later revert rate |
| Coverage percentage alone | Easy to inflate | Mutation score on changed code |
| Hours saved (self-reported) | Unreliable | Lead time and queue time measured in the pipeline |
12.3 Governance structure
Keep governance light and close to the work.
- A policy owner (often platform engineering with security) defines agent profiles, gates, and autonomy tiers.
- A review forum meets regularly to examine metrics, incidents, and requests to raise autonomy.
- An exception path exists, is fast, and is logged.
- A change process for the guardrails themselves: changes to agent policy are reviewed like code.
12.4 Evidence retention
Decide what you keep and for how long: agent run logs, approvals, evaluation results, attestations. Align retention with your compliance requirements and privacy obligations, and avoid storing sensitive data in logs.
Key takeaways
- Segment every metric by AI involvement.
- Pair every speed metric with a stability or quality counterpart.
- Govern the guardrails with the same rigor as code.
Part IV. Putting It to Work
Chapter 13. Connecting to Practices You Already Have
In this chapter: a translation table from this guide's concepts to the delivery disciplines large engineering organizations already operate.
Large engineering organizations have spent years building strong delivery disciplines. The model in this guide is designed to attach to them. It does not replace them. The table maps each concept to a practice you likely already run. Names and details vary by company, so treat this as a translation aid, and adapt it to your own internal terminology.
| This guide | Typically connects to | How |
|---|---|---|
| Stage contract | Launch checklists, production readiness reviews, definition of done | Add AI-specific rows: autonomy tier, agent profile, evidence |
| Product owner sign-off on stories | Product requirement reviews, planning rituals | Add the assumptions ledger |
| Machine-readable ADRs | Design docs, architecture review boards, technical design reviews | Give decisions stable IDs and scope so tools can cite them |
| Repository context file | READMEs, contributing guides, onboarding docs | Keep one short, agent-readable file per repo |
| Scoped agent access | Least privilege, service identities, sandboxing, build isolation | Treat each agent as a service with its own identity |
| Required tests and weakening detection | Presubmit checks, test-required policies, protected branches | Extend existing presubmit rules to detect assertion removal |
| Diff-size budget | Small-change culture, stacked or incremental changes | Enforce the same norm for agent output |
| Evidence-first review | Code ownership files, readability or approver requirements, review tooling | Surface test and mutation results at the top of the review |
| Mutation and criteria traceability | Test certification, test pyramid and quality bars | Add mutation scoring for changed code |
| Provenance and SBOM | Supply chain security programs, hermetic and reproducible builds | Add AI involvement as a provenance field |
| Progressive delivery | Feature flags, canaries, staged rollouts | Keep model-written summaries advisory; enforce thresholds in the pipeline |
| Error budget gating | SLOs and error budgets, release gating | Block or escalate risky releases when budget is spent |
| On-call decides | Incident command, paging, escalation policy | AI assists triage; humans keep command |
| Incident timeline with AI suggestions | Blameless postmortems, incident reviews | Record AI suggestions and outcomes as postmortem inputs |
| Evals as tests | Experimentation, offline and online evaluation, launch review for ML features | Run eval suites in CI on prompt, model, and retrieval changes |
| Cost attribution | FinOps, showback and chargeback, capacity planning | Tag AI spend by team and service |
| AI risk review | Privacy review, security review, responsible AI review, trust and compliance programs | Add agent and prompt-injection threat modeling |
13.1 Fitting different organizational shapes
Organizations differ in how they structure code, ownership, and tooling. The same contracts apply; the enforcement points move.
| Organizational shape | Where enforcement usually lives | Adaptation |
|---|---|---|
| Single large monorepo with centralized build and presubmit | Path-level ownership and presubmit rules | Scope agents by path; route agent changes through the same owner-review machinery as human changes |
| Many repos (polyrepo) with per-team pipelines | Repo-level permissions and shared pipeline templates | Ship a standard context file and pipeline template; treat cross-repo dependency updates as natural L3 candidates |
| Platform-centric organization with an internal developer platform | Shared platform services | Put sandboxes, identity, policy, logging, model routing, and cost attribution on the platform |
| Highly regulated or trust-centric environment (customer data, audited controls) | Compliance evidence and change management | Map evidence retained per stage to existing audit controls; keep L3 and L4 narrow |
| Federated product lines with autonomous teams | Governance forum plus a published baseline | Publish a minimum baseline (Appendix C); let teams tighten but not loosen it |
13.2 A note on monorepos and polyrepos
In a large monorepo, agent scoping is mostly about path-level permissions and ownership. An agent assigned to one service should be unable to modify shared libraries without an owner's approval, and large-scale automated changes should go through the same owner-review machinery as human-authored ones.
In a polyrepo estate, scoping is mostly about repo-level permissions and cross-repo coordination. Context files per repo matter even more, and dependency updates across repos are a natural L3 candidate.
13.3 A note on build systems
Hermetic, reproducible builds make agent output far easier to verify, because a green build means the same thing everywhere. If your builds are not reproducible, fix that first. Agents amplify whatever build reliability you already have.
13.4 A note on internal platforms
Most large organizations run internal developer platforms. The agent platform belongs there: sandboxes, identity, policy, logging, model routing, and cost attribution as shared services, so that individual teams do not each rebuild them.
Key takeaways
- Extend existing presubmit, ownership, launch, and SRE practices rather than creating a parallel process.
- Put shared agent infrastructure on the internal platform.
Chapter 14. A Worked Example: One Change Through Six Stages
In this chapter: a single illustrative change followed through every stage contract. The scenario is fictional and simplified.
Scenario. A payments team wants to add partial refunds for physical goods to an existing checkout service (tier-1, handles PII).
14.1 Requirements (L1)
An AI assistant drafts three stories and acceptance criteria from the product brief and two support-ticket summaries. It flags four items as assumptions. The product owner confirms two, corrects one (refunds apply to physical goods only), and deletes one (guest checkout is out of scope).
Evidence: approved story set with source links; resolved assumptions ledger.
14.2 Design (L1)
The AI proposes three options: extend the existing refund endpoint, add a separate refund service, or use an asynchronous refund queue. It cites ADR-0042 (PII handling) and an ADR on idempotent payment operations. Option 2 violates the "no new services without platform review" ADR and is flagged by policy-as-code. The architect chooses Option 1 and records Options 2 and 3 as rejected, with reasons.
Evidence: decision record including rejected options.
14.3 Build (L2)
A contributor-profile agent works in services/payments/** with infra/**, .github/**, and test-harness paths denied. It has no secrets and a package-mirror-only network. It opens a PR of 310 changed lines with the structured description from Appendix B. Blocking checks run: build, unit tests, static analysis, secrets scan, dependency policy, behavior-change-needs-test-change, and weakening detection. One run fails weakening detection because the agent loosened an existing assertion; the agent is returned to rework.
After the checks pass, the code owner reviews evidence first, then the diff, and approves.
Evidence: agent run log, diff, test results, requester identity, approver identity.
14.4 Test (L1 and L2)
The AI generates tests from the acceptance criteria. Mutation testing on changed code reports 0.64 against a 0.70 threshold. The engineer inspects surviving mutants, finds an unasserted rounding path, and the AI adds a targeted test. Mutation score rises above threshold. Every acceptance criterion now has a linked test.
Evidence: coverage and mutation report attached to the change.
14.5 Release
The AI drafts release notes for engineering and support and flags one risk: a config flip that enables the feature. Provenance attestation and SBOM are generated; vulnerability and license policy pass; the error budget is healthy. The release owner approves rollout behind a flag, off by default, canary at 1 percent. Thresholds were defined by the service owner and are enforced by the pipeline. The canary holds, so promotion proceeds.
Evidence: release notes, risk assessment, approval record, attestations.
14.6 Operate
Two weeks later, a latency regression appears. The operator-profile agent, read-only, correlates the alert with the recent release and a downstream dependency change and suggests flipping the feature flag off. On-call accepts. The incident timeline records the suggestion, the decision, and the outcome. The postmortem adds a latency test case, updates the repository context file, and adds a design checklist item for downstream-dependency impact.
Evidence: incident timeline with AI suggestions and outcomes; follow-up actions linked back to Test, Design, and the context file.
14.7 What the example shows
- Every stage produced an artifact a named person could check.
- Automated checks caught a weakened assertion before a human spent time on it.
- Humans decided at each gate; AI never held the final say.
- Operations findings flowed back into earlier stages.
Chapter 15. Adoption Roadmap
In this chapter: a phased rollout in which measurement decides when to advance.
Move in phases, and let measurement decide when to advance. The week ranges are indicative; adjust them to your organization's size and risk appetite.
Phase 0: Foundations (weeks 0 to 4)
- Inventory current AI use, formal and informal.
- Baseline delivery metrics (lead time, change failure rate, time to restore, review time).
- Define autonomy tiers and agent profiles.
- Stand up sandboxing, agent identities, and audit logging.
- Write repo context files for pilot repositories.
Exit criteria: baseline recorded, sandbox and logging working, pilot repos ready.
Phase 1: Assist and draft (weeks 4 to 10)
- Roll out L0 and L1 use in requirements, design drafts, and test generation.
- Introduce the assumptions ledger and decision records with rejected options.
- Add mutation scoring to the pipeline for pilot services.
Exit criteria: measurable quality signals in place; no rise in change failure rate.
Phase 2: Agents with review (weeks 10 to 20)
- Enable L2 coding agents in pilot repos with required tests, weakening detection, diff-size budgets, and provenance labels.
- Add policy-as-code for dependencies, secrets, and protected paths.
- Add eval suites for any AI-containing features.
- Begin read-only AI triage for on-call.
Exit criteria: agent PR acceptance and rework within targets; escaped defects not worse than the human baseline.
Phase 3: Earn autonomy (weeks 20 and beyond)
- Promote specific low-risk, high-volume change classes to L3 (for example dependency bumps, documentation, mechanical refactors) using measured evidence.
- Introduce bounded L4 automations in operations (for example rollback on SLO breach), each with a tested kill switch.
- Expand to more teams using a published playbook.
Exit criteria: autonomy raised only where metrics justify it; governance forum running; cost per change tracked.
15.1 Decision rule for raising autonomy
Raise a class of work to the next tier only if, over a meaningful sample, it shows: low defect escape, low rework, stable cost, working rollback, and an accountable owner who agrees.
15.2 Rollback of autonomy
Autonomy can also be lowered. Define triggers (for example a rise in escaped defects or a security incident traced to an agent change) that automatically return a class of work to the previous tier pending review.
Chapter 16. Anti-Patterns
In this chapter: the failure patterns seen most often, with symptoms and remedies.
| Anti-pattern | Symptom | Remedy |
|---|---|---|
| Speed theater | Impressive code-volume numbers, flat lead time | Measure end-to-end flow, not generation |
| Rubber-stamp review | Large AI PRs approved in minutes | Diff budgets; evidence-first review; reviewer load tracking |
| Green at any cost | Tests weakened to pass | Weakening detection; protected test paths |
| God-mode agent | One agent with broad credentials | Profiles and least privilege |
| Prompt as folklore | Useful prompts live in individual heads | Version-controlled context files and shared task templates |
| Orphaned output | No one can say who owns an AI-written module | Named accountable role per stage; CODEOWNERS applied to agent work |
| Controls later | Security and cost reviews added after rollout | Build gates into the pipeline from the first pilot |
| Autonomy by enthusiasm | Promotion to L3 or L4 driven by excitement | Promotion by evidence only |
| Blind trust in summaries | Release or incident summaries treated as ground truth | Summaries are advisory; the pipeline enforces |
| Skill erosion | Juniors never write or debug unaided | Deliberate learning paths and pairing |
Appendices
Appendix A. Stage Contract Template
Copy and adapt for each stage and service tier.
stage: build
service_tier: tier-1 # criticality drives strictness
autonomy_tier: L2 # act with review
accountable_role: service-owner-engineer
inputs:
- approved_story: required
- design_reference: required # ADR ids or design doc link
- repo_context_file: required
ai_action:
agent_profile: contributor
write_scope: ["services/payments/**"]
denied_paths: ["infra/**", ".github/**", "**/test-harness/**"]
allowed_commands: ["make build", "make test", "make lint"]
network: package-mirror-only
secrets: none
budget:
max_steps: 60
max_cost_usd: 15 # illustrative; set by task risk and budget policy
max_wall_clock_min: 45
automated_checks:
- build_and_unit_tests: blocking
- static_analysis: blocking
- secrets_scan: blocking
- dependency_policy: blocking
- test_change_required_for_behavior_change: blocking
- test_weakening_detector: blocking
- mutation_score_changed_code: ">= 0.70" # illustrative; set per service tier
- diff_size: "<= 400 lines" # illustrative
human_gate:
role: code-owner-reviewer
precondition: all_blocking_checks_pass
must_review: ["evidence_summary", "diff", "risk_notes"]
evidence:
retain: ["agent_run_log", "diff", "test_results", "mutation_report", "approver_id"]
retention_days: 365 # illustrative; align with retention and privacy policy
Appendix B. Pull Request Template for AI-Assisted Changes
## Intent
<What problem does this change solve? Link to story and design/ADR.>
## AI involvement
- Autonomy tier: L2
- Agent profile: contributor
- Task requested by: <person>
## Approach
<Short description of the approach and alternatives considered.>
## Evidence
- Tests added/changed: <list>
- Test results: <link>
- Mutation score on changed code: <value>
- Policy checks: <pass/fail summary>
## Risk
- Areas needing closest review: <list>
- Rollback plan: <flag, revert, migration reversal>
## Assumptions made by the agent
<List. Reviewer confirms or corrects each.>
Appendix C. Agent Permission Policy (Starter)
- Agents run in isolated sandboxes under their own service identity.
- Agents have no production access and no long-lived credentials.
- Writes are limited to declared paths. CI configuration, infrastructure code, and test harnesses are protected.
- Commands are allowlisted. Network egress is allowlisted.
- Every task has step, time, and cost budgets.
- After reading untrusted content, agents lose access to sensitive tools for the remainder of the task.
- Every agent change is reviewed by a human before merge, except in classes explicitly approved at L3.
- All agent actions are logged and attributable.
- Policy changes are reviewed like code and owned by the platform and security teams.
Appendix D. Eval-Driven Development Checklist for AI Features
- Golden dataset covering core tasks, edge cases, and known failures.
- Adversarial set covering injection, jailbreak, and tool-abuse attempts.
- Rubric or automated scoring with calibration against human judgment.
- Evals run in CI on any change to prompts, models, retrieval, or tools.
- Thresholds defined and enforced as blocking gates.
- Latency and token-cost budgets enforced.
- Production samples feed back into the dataset.
- Incidents become new eval cases.
Appendix E. Review Checklist for Reviewers of AI-Authored Changes
- Does the change match the stated intent and linked story?
- Are tests meaningful? Check assertions, not only coverage.
- Did any test get weakened, skipped, or removed?
- Are all new dependencies real, necessary, and approved?
- Does the change stay within its declared scope?
- Are error handling, logging, and observability consistent with house patterns?
- Are there security concerns: input handling, secrets, authorization, data exposure?
- Is the rollback path clear?
- Did the agent record assumptions, and are they acceptable?
- Would I be comfortable being on call for this change?
Appendix F. Accountability Matrix and Maturity Self-Assessment
F.1 Accountability matrix
A = accountable (decides), R = responsible (does the work), C = consulted, I = informed. Adapt role names to your organization.
| Activity | Product owner | Architect | Engineer / code owner | Quality engineer | Platform | SRE / on-call | Security |
|---|---|---|---|---|---|---|---|
| Approve story set and assumptions | A | C | C | C | I | I | C |
| Approve design decision | C | A | R | I | C | C | C |
| Approve agent change (merge) | I | I | A | C | I | I | C |
| Review test quality | I | I | R | A | I | I | I |
| Approve rollout | C | I | R | I | I | C | C |
| Own agent profiles and gates | I | C | C | C | A | C | R |
| Decide incident actions | I | I | C | I | I | A | C |
| Approve autonomy promotion | C | C | C | C | R | C | A (policy owner) |
F.2 Maturity self-assessment
Score each row from 0 (absent) to 3 (enforced by the pipeline and measured).
| Capability | 0 | 1 | 2 | 3 |
|---|---|---|---|---|
| Stage contracts defined | None | Written for one stage | Written for all stages | Enforced and reviewed |
| Agent identity and scoping | Shared credentials | Informal limits | Profiles defined | Profiles enforced and audited |
| Test-weakening detection | None | Manual | Advisory check | Blocking check |
| Mutation scoring | None | Pilot | Per-service threshold | Blocking on changed code |
| Evidence retention | None | Partial | Defined per stage | Searchable and audited |
| Autonomy promotion rule | Ad hoc | Informal | Documented | Evidence-gated with rollback |
| Metrics segmented by AI involvement | None | Partial | Dashboard | Used in governance forum |
Appendix G. Glossary
| Term | Meaning |
|---|---|
| ADR | Architecture decision record: a short, versioned record of a design decision and its rationale |
| Agent | An AI system that plans and takes multi-step actions using tools, rather than only generating text |
| Autonomy tier | The level of independence granted to AI for a class of work, from assist (L0) to autonomous operation (L4) |
| Context file | A version-controlled file that tells agents how a repository builds, tests, and is organized |
| DORA metrics | Deployment frequency, lead time for changes, change failure rate, and time to restore service |
| Eval | A repeatable test of AI behavior using datasets, rubrics, and scoring |
| Human gate | A point where a named person must accept or reject output before work proceeds |
| Mutation testing | Deliberately introducing faults to check whether tests detect them |
| Policy as code | Rules expressed in machine-checkable form and enforced automatically |
| Provenance | A verifiable record of how and from what an artifact was built |
| SBOM | Software bill of materials: an inventory of components in a software artifact |
| SLO / error budget | A reliability target and the amount of unreliability allowed before action is required |
| Stage contract | The inputs, AI action, checks, human gate, and evidence defined for one lifecycle stage |
Appendix H. Standards and Frameworks
- DORA research program (delivery performance metrics).
- SLSA (supply chain integrity levels).
- OWASP guidance for LLM applications.
- NIST AI Risk Management Framework.
- OpenTelemetry (telemetry standards).
- Model Context Protocol (tool and context integration for agents).
Closing
The organizations that get durable value from AI in delivery will not be the ones that generate the most code. They will be the ones that redesign each stage so AI work arrives with evidence, checks are built into the pipeline, and a named person remains accountable for every outcome.
Start with one stage contract. Make it real in one team. Measure it honestly. Then extend it.
The gain holds when each stage has clear inputs, checks, and a person accountable for the outcome. Everything else in this guide is a way of making that true.