Building AIDLC Into an AI Engine
AIDLC is a process, but it does not have to live in a slide deck. If your organization runs an AI engine - an agent platform, an orchestration service, or an internal tool that drives coding agents - the five phases can become states it tracks, the artifacts can become records it stores, and the exit criteria can become gates it enforces. This page lays out a reference architecture, maps each phase onto it, and shows the data and configuration that make it concrete.
Which AI Engine Do You Mean?
"Integrate AIDLC into our AI engine" means different work depending on what the engine is. Find your situation first; the rest of the page is written for the first one, and links out for the other two.
The engine that does the work
An internal agent platform or orchestration service that runs coding agents for your teams. AIDLC becomes its workflow model: states, records, gates, and policy. This page covers that case end to end.
The engine your teams use
An off-the-shelf coding agent such as Claude Code, Codex, Copilot or Cursor, plus your CI. The method lives in instruction files, saved prompts, hooks and workflow checks. See Implementation Examples 1 and 2.
The engine you are building
A product with a model inside it. AIDLC still runs the delivery, and evals, pinning and drift monitoring join it. See When the AI Engine Is the Product below.
The Method Becomes Data and Gates
Integrating a methodology into an engine means translating every part of it into something the engine can store, check, or refuse. A rule that lives only in a prompt is a request the model can ignore. A rule that lives in the engine is a constraint it cannot.
Five translations do most of the work. Each one replaces a convention people have to remember with a mechanism the engine applies to every piece of work, human or agent.
| AIDLC concept | Inside the engine | Example |
|---|---|---|
| A phase | A state in a workflow state machine, with explicit transitions | A ticket moves from ideate to develop only through a transition the engine owns |
| An artifact | A typed, versioned record that the next state reads | The requirements brief, spec, ticket contract, plan, pull request, release plan and runbook |
| Exit criteria | Automated checks, then named human approvals | Tests written first and green in CI, then a reviewer at the ticket's risk tier |
| Hard rules | Policy enforced by the runtime, outside the model | The agent's identity has no permission to push to a protected branch |
| The learn loop | An event that must produce a rule, test or eval | An incident cannot close until a pull request adds the rule that would have caught it |
This is the same separation Agent Orchestration describes: agents propose, the engine decides, and a verdict only counts once something enforces it.
A Seven-Layer Reference Architecture
The layers below are responsibilities, not products. A small team may cover several with one service and a few scripts; a platform team may give each its own owner. What matters is that every responsibility has a home, and that no layer quietly depends on a model behaving well.
Work intake
The tracker and the forms that create work: requirements briefs, ticket contracts, risk tier and lane labels. Work without a contract does not enter the engine.
Orchestrator
The phase state machine: states, transitions, gates, retries and controlled backward moves, persisted durably. It is the single answer to "where is this work, and what happens next?" See the conductor is a state machine.
Agent runtime
The agents themselves, one role per phase, each running in a sandbox or worktree with its own budget and a pinned model. Agent definitions are versioned like code. See sandbox and budget.
Context
What each agent is allowed to know: the repo instruction file, the approved spec, ADRs and contracts, plus tools exposed through MCP servers for the tracker, repository, CI and docs. See Context Engineering.
Policy and identity
Agent identities, least-privilege permissions, risk tiers, data classification and the agent hard rules, enforced where the agent cannot reach them. See identity and data classification.
Verification
Tests written from the acceptance criteria before the code, a mutation gate on critical modules, evals for agents and prompts, review agents, and human review at each risk tier. See tests first and AI Code Review at Scale.
Telemetry and learning
A trace for every agent run (inputs, model, cost, gate result), the delivery metrics on Measuring Impact, and the learn loop that turns each escaped defect into a new rule, test or eval. Without this layer the engine repeats its mistakes at machine speed.
How One Ticket Moves Through the Layers
Follow a single ticket contract through Develop. The agent never decides that its own work is done: the gate and a person do.
- Intake accepts the ticket contract only if its required fields are filled: acceptance criteria, risk tier, flag, rollback plan.
- The orchestrator moves it into
developand picks the coding agent definition for its risk tier. - The context layer hands the agent the contract, the approved spec, the relevant ADRs and the instruction file - and nothing from other tenants or unrelated repos.
- The agent proposes a plan, waits for approval, writes failing tests from the criteria, then implements until they pass and opens a pull request under its own identity.
- Verification confirms the tests came first and fail without the change, that no existing test was weakened, and that CI is green. A failure goes back to the agent with the reasons, at most twice.
- A reviewer at the ticket's risk tier approves, and that approval event - not the agent - moves the ticket toward Launch. Telemetry records every step.
Phase by Phase: What the Engine Does
Each phase gets a state, an agent role, a record it writes, an automated gate and a human gate. The details come from the five phase pages; this table is the engine's view of them.
| Phase | Agent role | Record it writes | Automated gate | Human gate |
|---|---|---|---|---|
| Analyze | Research agent | Requirements brief | All six sections present; every criterion written as Given/When/Then | Product owner signs off |
| Ideate | Design agent | Design note, ADR, contract, spec | Spec traces to every acceptance criterion; contract validates against its schema | Tech lead approves the design |
| Develop | Coding agent | Ticket contract, plan, tests, pull request | Unit, integration and contract tests written first and failing, then green in CI; mutation gate on critical modules; no agent edits to existing tests | Plan approval; review at the risk tier |
| Launch | QA and DevOps agent | Assurance report, release plan | Full suite green on the integrated build; mutation re-check; smoke tests pass; rollback rehearsed. A failing gap test sends the work back to Develop | Release owner approves; a human reads every infrastructure plan |
| Curate | Monitoring agent (read-only) | Incident review, runbook update, new rule | Alert correlated with recent merges; a rule, test or eval pull request opened | On-call accepts the cause; the new rule is reviewed |
Artifacts as Typed Records
Store every artifact as structured data with a schema, a version, an author (a person or an agent identity) and its approvals kept separately from its content. The next phase reads only an approved version. An agent can write a new version; it can never approve one.
Here is the ticket contract template as a record, using the same invented invoice-export feature as the worked example. Field names are illustrative; keep whatever your tracker already uses.
{
"id": "BILL-412",
"kind": "ticket_contract",
"version": 3,
"phase": "develop",
"risk_tier": 2,
"lane": "A",
"data_classification": "Confidential",
"feature_flag": "invoice_export_v2",
"acceptance_criteria": [
{
"id": "AC-1",
"given": "an account with three paid invoices",
"when": "the owner requests a CSV export",
"then": "the file lists exactly those three invoices"
},
{
"id": "AC-2",
"given": "two accounts on the same tenant",
"when": "the export runs for one of them",
"then": "no invoice from the other account appears"
}
],
"rollback_plan": "Turn off invoice_export_v2",
"blast_radius": ["billing-service"],
"out_of_scope": ["PDF export"],
"authored_by": "agent:design-agent",
"approvals": [
{ "role": "tech_lead", "by": "user:tech-lead-1", "version": 3 }
]
}Gates as Code
Write each phase's exit criteria as configuration the orchestrator evaluates, so a gate is reviewable, versioned and identical for every team. Automated checks run first and send failures back with reasons. Human approvals come second, by role, and are the only thing that moves work forward.
The check names below are placeholders for scripts or services you already have, such as your test runner, a mutation tool and your tracker's API. Thresholds are deliberately left to the owner of each gate.
# aidlc-gates.yaml - illustrative; map each check to a script in your engine
phases:
analyze:
exit:
checks:
- brief_has_sections: [problem, users, acceptance_criteria, constraints, open_questions, risks]
- criteria_format: given_when_then
approvals:
- role: product_owner
ideate:
exit:
checks:
- spec_traces_every_criterion
- contract_matches_schema
approvals:
- role: tech_lead
develop:
entry:
approvals:
- role: senior_engineer # approves the agent's plan before any code
artifact: plan
exit:
checks:
- tests_written_before_implementation # unit, integration and contract
- new_tests_fail_without_the_change
- existing_tests_unmodified_by_agent
- mutation_gate: touched_critical_modules # threshold owned by the QA lead
- ci_green
approvals:
- role: reviewer_for_risk_tier
launch:
exit:
checks:
- full_suite_green_on_release_candidate
- mutation_recheck: critical_modules
- smoke_tests_pass
- rollback_rehearsed
on_failing_gap_test:
return_to: develop # the failing test is the feedback artifact
approvals:
- role: release_owner
curate:
close_incident:
checks:
- rule_test_or_eval_pull_request_opened
approvals:
- role: on_call_engineer
policy:
max_repair_attempts: 2 # then stop and ask a human
agent_can_approve: false
agent_can_push_protected_branches: false
agent_can_read_production_secrets: falseThe policy block mirrors the agent hard rules. Enforce it in the runtime and the identity provider, then keep the file as the human-readable record of what is enforced.
The Orchestrator Loop
The heart of the engine is a short loop. It is shown here as language-neutral pseudo-code; a production version adds durable persistence, idempotent steps and timeouts, which Agent Orchestration covers in depth.
function advance(workItem):
phase = workItem.phase
agent = agentFor(phase, workItem.riskTier) # versioned definition, scoped identity, budget
context = contextFor(workItem, phase) # instruction file, approved spec, ADRs, MCP tools
for attempt in 1..policy.maxRepairAttempts:
draft = agent.run(workItem, context) # writes a new artifact version
result = gates.check(phase, draft) # automated checks only
telemetry.record(workItem, agent, draft, result)
if result.passed:
approvals.request(phase, draft) # people, by role and risk tier
return # the approval event moves the state
context.feedback = result.failures # send the reasons back
escalate(workItem, "gate still failing after repair attempts")
on approval(workItem, artifact, approver):
require approver.isHuman
stateMachine.transition(workItem, next(workItem.phase))Two properties make this safe: the transition happens in an approval handler that only a person can trigger, and the repair loop is bounded, so a stuck agent becomes a visible escalation instead of a silent cost.
When the AI Engine Is the Product
If the engine you are building is itself model-powered - an assistant, a classifier, a retrieval system - AIDLC still runs the delivery. What changes is the definition of "tested": evals take the place that unit tests hold for code, and they follow the same rule. They are written first.
Define good enough as cases
Agree the behaviors that must never happen and the ones that must always happen, as concrete input and expected-behavior pairs. These become the blocking eval cases.
Design for the wrong answer
Decide fallbacks, human handoff and confidence display, and choose the model family and retrieval design against the eval cases rather than a demo.
Evals before the prompt change
Add the eval cases for a change before editing the prompt, model or retrieval configuration, and keep all three pinned and versioned as code.
Gate on the eval suite
Every prompt or model change runs the suite in CI. Release behind a flag, compare against the current version, and keep a one-step rollback to the previous configuration.
Every bad output becomes a case
Sample production outputs, watch for drift, and add each failure to the eval set so it can never pass unnoticed again. AIDLC vs the ML Lifecycle covers the model side; Example 4 shows the files.
Where to Start
Do not build all seven layers before the first ticket runs. Add them in the order that pays back soonest, and let each step prove itself before the next.
Make the artifacts real
Put the requirements brief and ticket contract into your tracker as required fields. Nothing else works until work arrives with acceptance criteria and a risk tier.
Gate Develop in CI
Require tests written from the criteria, block agent edits to existing tests, and route review by risk tier. Develop carries the most agent volume, so its gates matter first.
Give agents identities and a trace
Run every agent under its own service identity with least-privilege permissions, and record each run. This is the foundation for both safety and the learn loop.
Add the state machine for Develop and Launch
Move the two most mechanical phases into the orchestrator, with the full-suite run on the integrated build, the mutation re-check and the release plan as Launch's exit. Keep Analyze and Ideate human-led with agent drafting.
Close the learn loop
Make incident closure require a new rule, test or eval. From here the engine gets better with every failure instead of repeating it.
For the organizational side of the same sequence, see the Rollout Playbook and the Maturity Model.
Frequently Asked Questions
Treat the method as data and gates. Model the five phases as states in the engine's workflow, store each artifact - requirements brief, spec, ticket contract, plan, pull request, release plan - as a typed and versioned record, and turn each phase's exit criteria into automated checks followed by named human approvals. Enforce the hard rules in the runtime rather than in prompts, and record every agent run for the learn loop.
No. AIDLC is model-agnostic. The phases, artifacts and gates work with any coding agent or model API, including Claude, ChatGPT, Gemini, Claude Code, Codex, Copilot and Cursor, or with an in-house engine. Pin whichever model you use and run your evals before changing it, so a model upgrade is a reviewed change rather than a silent shift in behavior.
Start with the artifacts and the Develop gates, because that is where agent volume is highest. Put the ticket contract in your tracker as required fields, then make CI require tests written from the acceptance criteria, block agent edits to existing tests, and route review by risk tier. Add agent identities, run tracing and orchestrator states for the other phases once those gates hold.
Make the Method Executable
See the same ideas as working files, then take the templates into your own tracker and repository.