4 The Agentic SDLC Reference Architecture

Most organizations planning AI adoption ask “which tool should we buy?” The better question is “which layers of our software lifecycle should agents touch first, and what infrastructure do they need?” This chapter provides the diagram that answers both — and explains why the context you accumulate along the way matters more than any tool you select.

4.1 The Three Layers

At every phase of the software development lifecycle, work happens across three distinct layers. Understanding them is the difference between a coherent AI strategy and a collection of disconnected tool purchases.

The Human Layer is where judgment, accountability, and strategic decisions live. Humans set objectives, make architectural choices, define quality standards, and bear responsibility for what ships. No current AI system replaces these functions. The question is not whether humans remain in the loop (they do) but which decisions require human judgment and which are better delegated.

The Agent Layer is where AI capabilities execute within defined boundaries. Agents generate code, produce reviews, draft tests, surface patterns in data, and automate repetitive cognitive work. They operate with varying degrees of autonomy, from passive suggestion to autonomous task execution, but always within constraints set by the Human Layer. The PROSE framework from Chapter 1 defines those constraints: Progressive Disclosure determines what context agents receive, Safety Boundaries determine what they can do with it.

The Platform Layer is the infrastructure that enables both humans and agents: source control, CI/CD pipelines, identity and access management, observability, artifact registries, and the APIs that connect them. This layer is often invisible in AI adoption conversations, which is precisely why adoption stalls. An agent that can generate code but cannot run tests, read build output, or access your dependency graph is an agent working blind.

The layers are not independent. They form a stack where each depends on the one below it:

flowchart LR
    subgraph HUMAN ["HUMAN LAYER"]
        direction LR
        HR["Roles: Product, Architecture,<br/>Engineering, QA, Operations"]
        HF["Functions: Decisions,<br/>Governance, Accountability"]
    end

    subgraph AGENT ["AGENT LAYER"]
        direction LR
        AC["Capabilities: Generate,<br/>Analyze, Test, Review"]
        AB["Boundaries: Scoped authority,<br/>context-dependent, auditable"]
    end

    subgraph PLATFORM ["PLATFORM LAYER"]
        direction LR
        PI["Infrastructure: SCM, CI/CD,<br/>Auth, Observability"]
        PN["Integrations: APIs, Webhooks,<br/>Context Sources, Artifacts"]
    end

    HUMAN -- "sets constraints,<br/>delegates tasks" --> AGENT
    AGENT -- "escalations,<br/>approvals, results" --> HUMAN
    AGENT -- "invokes tools,<br/>reads context" --> PLATFORM
    PLATFORM -- "build results,<br/>test output, telemetry" --> AGENT

Figure 4.1: The three-layer reference architecture: Human, Agent, Platform

This structure is not a proposal. It is a description of what already exists in any organization using AI coding tools — whether they’ve designed it deliberately or not. The agent in your developer’s editor is already operating across these three layers. The question is whether the boundaries, the context flow, and the governance are intentional.

4.2 Mapping the Layers Across the Lifecycle

The three layers apply at every phase of software delivery. The table below maps what each layer does in each phase and, critically, which capabilities are available today versus emerging or directional.

Maturity tiers: Now = available across two or more vendors. Emerging = available in one or two tools, or in limited preview. Directional = announced, demonstrated, or on public roadmaps but not production-ready.

	Ideate	Plan	Code	Build	Test	Review	Release	Operate
	INTENT		BUILD				OPERATE
Human	Set objectives and scope	Make architecture choices	Review agent output	Own build config	Define test policy	Final code sign-off	Go/no-go decision	Own incident response
Agent	Research prior art, surface conflicts	Draft ADRs, decompose tasks	Multi-file code generation	Diagnose build failures	Generate tests, find coverage gaps	Automated review, catch defects	Draft changelogs, flag breaking changes	Correlate alerts, suggest actions
Platform	Knowledge bases, collaboration tools	Issue trackers, project management	IDE, SCM, context APIs	CI/CD pipelines, dependency management	Test frameworks, infrastructure	Pull request APIs, policy engines	Deployment pipelines, gates	Monitoring, alerting, log systems
Maturity	Emerging	Emerging	Now	Now	Emerging	Now	Emerging	Directional

Executives do not need to think in eight phases. They need three buckets that map to planning cadences, budget lines, and organizational accountability:

Intent (Ideate + Plan) answers “what are we building and why?” Agent assistance here is mostly emerging. Research agents that surface prior art, planning agents that draft architecture decision records and decompose epics into tasks. These exist in early forms, but no tool reliably automates the judgment calls that make planning valuable.

Build (Code + Build + Test + Review) answers “how do we turn intent into verified software?” This is where agent capabilities are most mature. Code generation, build diagnostics, test generation, and automated code review all have production-ready implementations across multiple vendors. This is also where most organizations start, and where the Vibe Coding Cliff from Chapter 1 hits hardest if context is not structured.

Operate (Release + Operate) answers “how do we get software to users and keep it running?” Agent assistance in release management is emerging; in incident response, it is directional. Correlating alerts to recent deployments, drafting incident timelines, suggesting rollback actions. These capabilities exist in point solutions (e.g., PagerDuty’s AIOps, Datadog’s Watchdog) but not yet in workflows integrated end-to-end with the development lifecycle.

The practical implication: based on vendor maturity and published adoption patterns, most organizations appear to have concentrated investment in the Build bucket, with minimal coverage in Intent and almost none in Operate. This is not a failure. It reflects where the technology is mature. But it means the next high-value investments are in Plan, Test, and Review — where the work is expensive, the feedback loops are slow, and structured context makes the difference between useful automation and expensive noise.

4.2.1 Three-Tier Honesty

Vendor presentations tend to show the full architecture as if it were all available today. It is not. Presenting the vision as current reality is what vendor whitepapers do. This book tags every capability honestly.

Phase	Agent capability	Maturity	Justification
Ideate	Research synthesis, prior-art surfacing	Emerging	Available in conversational tools; no reliable autonomous implementation
Plan	ADR drafting, task decomposition, estimation	Emerging	Early implementations exist (GitHub Copilot, Claude); accuracy varies significantly
Code	Multi-file generation, refactoring, boilerplate	Now	Production-ready across GitHub Copilot, Cursor, Claude Code, Windsurf, others
Build	Build failure diagnosis, dependency resolution	Now	CI integration available in multiple tools; quality depends on structured error output
Test	Test generation, coverage gap analysis	Emerging	Generation works; strategic test design still requires human judgment
Review	Automated code review, defect detection	Now	Shipping in GitHub Copilot, Amazon Q; effectiveness depends on documented standards
Release	Changelog drafting, breaking-change detection	Emerging	Partial implementations in CI tools; end-to-end release automation is not production-ready
Operate	Alert correlation, incident timeline drafting	Directional	Research demos and early integrations; no vendor ships reliable autonomous incident response

The pattern is clear. Build-phase capabilities are mature. Intent-phase and Operate-phase capabilities are early. If a vendor tells you they have end-to-end lifecycle automation today, ask which cells in this table they would tag as Now, and how they define the term. The honest answer will tell you more about the vendor than any feature demo.

4.3 What Changes About Roles

The three-layer model clarifies what happens to human roles when agents enter the lifecycle. The answer is not that roles disappear. The answer is that the proportion of activities within each role shifts.

Human role	What stays human	What agents handle	What shifts
Product Manager	Strategic prioritization, stakeholder alignment, go/no-go decisions	Research synthesis, competitive analysis, requirement drafting from rough notes	More time on judgment, less on information gathering
Architect	System design decisions, technology selection, cross-team coordination	ADR drafting, dependency analysis, pattern detection across codebases	More time on review, less on documentation
Developer	Code review, architectural compliance, complex problem-solving	Routine implementation, boilerplate, test generation, refactoring	More time specifying intent, less time typing code
QA Engineer	Test strategy, edge case identification, exploratory testing	Test generation, coverage analysis, regression detection	More time on test design, less on test writing
SRE / Ops	Incident ownership, capacity planning, reliability decisions	Alert correlation, runbook execution, incident timeline drafting	More time on system understanding, less on routine response

The pattern across every row: agents absorb the mechanical and information-processing work, while humans focus on the judgment, strategy, and accountability work. This is not a temporary state. It reflects the fundamental properties of language models described in Chapter 1: they process and generate; they do not decide or bear responsibility.

Chapter 6 covers the organizational design implications in detail: team structures, the junior pipeline, and new hiring profiles. Here, the point is architectural: the Human Layer does not shrink. It concentrates on the activities that require human judgment, and those activities become more visible and more important.

4.4 The Context Moat

Your competitors have access to the same AI models you do. They can license the same coding tools. What they cannot replicate is your organization’s accumulated engineering knowledge — if you have made it structured and agent-consumable. If you have not, your AI tools are working with the same generic training data as everyone else’s. This is the context moat.

Why context beats models. Model quality commoditizes. In 2022, OpenAI’s Codex was the dominant commercial code-generation offering. By mid-2025, several model families compete credibly (OpenAI, Anthropic, Google, Meta, Mistral, among others). Pricing has trended downward as competition increases. The model powering your agent is a procurement decision, not a strategic advantage. Context is the opposite: it is proprietary, it accumulates over time, and it directly determines the quality of every agent interaction.

Consider two teams of similar size, working on codebases of similar complexity, using identical AI tools on the same underlying model. Team A has documented its coding conventions, API patterns, error-handling standards, and module boundaries in structured instruction files that agents load automatically. Team B has not; its conventions exist in senior engineers’ heads and scattered code comments.

Team A’s agents generate code that passes linting on the first attempt, follows the internal API surface, and produces pull requests that reviewers approve with minor comments. Team B’s agents generate plausible code that calls deprecated APIs, invents its own error patterns, and produces pull requests that require substantial rework. The rework cost compounds across every developer, every day. Over six months, Team A’s context investment has paid for itself many times over, while Team B is still debating whether AI tools are “worth it.”

The difference is not the tool. It is the context.

Context operates across three domains, each with different characteristics:

Context Layer	What It Contains	Examples	Sources
Work Context	Decisions, requirements, meeting outcomes, strategic priorities	ADRs, sprint plans, product briefs, stakeholder notes	Collaboration tools, wikis, project management systems
Data Context	Business intelligence, domain models, analytics, structured domain knowledge	Data dictionaries, domain glossaries, schema docs	BI platforms, data catalogs, knowledge graphs
Code Context	Architecture, conventions, dependency graphs, API surfaces	Coding standards, instruction files, module boundaries	Repositories, CI/CD systems, artifact registries

Work context captures why decisions were made and what the organization intends. Most of this knowledge exists today in meeting notes, Slack threads, and individual memory. Making it machine-readable — through structured ADRs, specification templates, and decision logs — is a documentation investment with a new payoff: agents that understand the reasoning behind the code, not just the code itself.

Data context captures the domain the software operates in. A financial services team whose agents can reference the company’s data dictionary and regulatory terminology will produce more accurate code than one whose agents work from generic training data alone. This context is often the hardest to structure because it lives in specialized systems outside the engineering toolchain.

Code context captures how the codebase works and what conventions it follows. This is the most immediately actionable domain, because it maps directly to the instruction files, custom rules, and agent configurations that current AI coding tools support. Documenting your API conventions, error-handling patterns, module boundaries, and architectural invariants — and structuring them so agents can consume them — is the highest-ROI starting investment for any team.

4.4.1 The Compounding Mechanism

Structured context is not a one-time cost. It compounds.

When an agent produces a code review using your team’s documented quality standards, that review generates structured feedback. When a developer resolves the feedback and updates a convention document, the convention becomes richer. When the next agent interaction loads that richer convention, the output improves. Each cycle reinforces the next:

graph LR
    A["Structured<br/>context"] --> B["Better agent<br/>output"]
    B --> C["Richer<br/>artifacts"]
    C --> A

Figure 4.2: The context compounding flywheel

This flywheel means the gap between organizations that invest in context early and those that defer widens over time. It is not a linear gap. An organization that starts structuring context in 2025 does not just have two years’ head start over one that starts in 2027; it has two years of compounding context that the late starter must build from scratch while the early adopter’s agents are already leveraging it.

Evidence: the 75-file PR. This book’s primary case study — PR #394, a pull request touching 75 files — did not succeed because the AI model was unusually powerful. It succeeded because the repository had accumulated context primitives over the preceding weeks: coding conventions, architecture decision records, module boundary definitions, error-handling patterns, and instruction files scoped from global rules down to directory-specific overrides. Each was created when an agent interaction failed due to a context gap. Without that accumulated context, the same task on the same model would have produced 75 files of plausible code riddled with convention violations — the exact failure mode described in Chapter 1’s Vibe Coding Cliff. The delta between “75 files of rework” and “75 files merged” is the context moat, demonstrated. Full metrics and escalation details are documented in the APM Overhaul case study.

Convergence evidence: the platform intelligence layer. This pattern is not unique to one vendor. Microsoft’s own platform architecture illustrates the convergence: WorkIQ (workplace intelligence from M365 — meetings, email, calendar), FoundryIQ (AI model and deployment intelligence), and FabricIQ (data and analytics intelligence) each contribute organizational context that no coding tool can replicate independently. This three-layer intelligence stack — workplace, AI, and data — mirrors the broader industry pattern: the defensible advantage in AI-assisted development is not the model or the IDE, but the organizational context layer that connects them. As platform vendors integrate these intelligence surfaces, the context moat deepens for organizations that structure their knowledge to take advantage.

4.4.2 Technical Debt Gets a New Cost

AI changes the ROI calculus for documentation debt, convention debt, and knowledge-base debt. Consider an illustrative example: in a representative scenario, documenting your API conventions might take two days of engineering time. Without that documentation, agents hallucinate your internal patterns. In teams we have observed, pull request reviews frequently caught three to five convention violations that required rework. With documentation, the agent generates convention-compliant code from the first attempt. The payback period in these cases was roughly two weeks.

This recalculation applies across the codebase. Undocumented module boundaries, implicit architectural decisions, tribal knowledge stored only in senior engineers’ heads: all of these were always technical debt. AI makes the cost of that debt visible on every agent interaction, because the agent fails precisely where the documentation fails.

The implication for leaders: re-prioritize your backlog. Items that were perpetually deferred — “document the authentication flow,” “write down the module ownership model,” “formalize the error-handling conventions” — now have a concrete, measurable payoff that they did not have before AI tools existed. Chapter 11 provides the methodology for auditing and structuring this context systematically.

4.5 The Architecture Decision Matrix

The reference architecture is an adoption map, not a prerequisite checklist. Any phase can run as a single agent-assisted loop — or expand into governed, multi-agent workflows as maturity grows. The question for leaders is where to start and how to expand.

The matrix below maps adoption decisions across two dimensions: the lifecycle phase and the investment required. Use it to scope your first pilot and plan the expansion path.

Phase	Start here if…	First investment	Maturity prerequisite	Expected timeline
Code	Your developers already use AI tools	Custom instructions encoding your conventions	Linter, test suite, CI pipeline	2-4 weeks
Review	PR review is a bottleneck	Agent-assisted review with human sign-off	Documented quality standards, clear review criteria	4-8 weeks
Test	Test coverage is low or tests are brittle	Agent-generated tests with human-defined strategy	Test framework, coverage tooling, defined test policy	4-8 weeks
Plan	Planning is slow and produces inconsistent artifacts	ADR templates, specification structures for agent drafting	Issue tracker, documented architecture decisions	8-12 weeks
Build	CI failures consume significant developer time	Agent-assisted build diagnostics and fix suggestions	CI/CD pipeline with structured error output	4-8 weeks
Release	Release process is manual and error-prone	Agent-drafted changelogs and breaking-change detection	Semantic versioning, structured commit history	8-12 weeks
Ideate	Research and discovery are ad hoc	Agent-assisted research synthesis and prior-art surfacing	Knowledge base, searchable decision history	12-18 weeks
Operate	Incident response is slow to diagnose	Agent-assisted alert correlation and timeline drafting	Observability stack, structured runbooks	12-18 weeks

Three observations from the matrix:

Start where the tooling is mature and the payoff is immediate. Code, Review, and Test have production-ready agent capabilities across multiple vendors. They are also the phases where structured context produces the most measurable improvement. Most organizations should start here.

Invest in context before investing in agents. Every row in the matrix lists a maturity prerequisite — and most of those prerequisites are documentation, structure, and tooling that should exist regardless of AI adoption. If your conventions are not documented, your tests are not reliable, and your CI pipeline does not produce structured output, no agent tool will compensate. Fix the foundation first.

Expand based on evidence, not ambition. Move to the next phase when the current one is producing measurable results — faster reviews, fewer convention violations, higher test coverage. Do not expand because a vendor demo looked impressive. Chapter 8 provides the metrics that distinguish real improvement from optimistic interpretation.

4.6 Build, Buy, or Compose

For each context domain, leaders face a decision: build internal tooling, buy from a platform vendor, or compose solutions from multiple sources.

Context domain	Build	Buy	Compose
Work context	Internal knowledge base, custom ADR tooling	Platform-integrated wikis (Notion, Confluence, GitHub Wikis)	API connectors bridging collaboration tools to agent context
Data context	Custom domain model documentation, internal domain taxonomies	Data catalog platforms (Collibra, Alation, dbt)	Federation layers that expose data definitions to coding agents
Code context	Instruction files, custom rules, agent configurations	IDE-integrated context from platform vendors	Open-source primitive packages, shared community configurations

The pattern: work and data context often require building or composing because they are organization-specific. Code context is the most composable because the formats are increasingly standardized — custom instructions in GitHub Copilot, rule files in Cursor, CLAUDE.md in Claude Code — and community-shared configurations can provide a starting point that teams customize.

No single vendor covers all three context domains comprehensively today. This is a practical observation, not a criticism; the integration surface is large, and the standards are still forming. Plan for a composed solution and evaluate vendors on how well they expose APIs for context integration, not on whether they claim to cover everything.

4.7 The Agentic Computing Stack

The components in the build-buy-compose decision above are not independent purchases. They are layers in a technology stack, and as with any stack, each layer depends on the ones below it.

flowchart BT
    L1["<b>LLM</b><br/>GPT, Claude, Gemini<br/><i>≈ CPU</i>"]
    L2["<b>Harness</b><br/>Copilot CLI, Cursor, Claude Code<br/><i>≈ Runtime / OS</i>"]
    L3["<b>PROSE Constraints</b><br/><i>≈ Arch Standards</i>"]
    L4["<b>Markdown Primitives</b><br/>.instructions.md, .agent.md<br/><i>≈ Source / Config</i>"]
    L5["<b>Package Managers</b><br/>(APM, plugin.json, …)<br/><i>≈ Package Manager</i>"]
    L6["<b>Spec-Kit, Squad</b><br/><i>≈ Frameworks</i>"]
    L7["<b>Agentic Workflows</b><br/><i>≈ Applications</i>"]

    L1 --> L2 --> L3 --> L4 --> L5 --> L6 --> L7

    style L1 fill:#e8f0fe,stroke:#4285f4,color:#1a1a1a
    style L2 fill:#e8f0fe,stroke:#4285f4,color:#1a1a1a
    style L3 fill:#fef7e0,stroke:#f9ab00,color:#1a1a1a
    style L4 fill:#fef7e0,stroke:#f9ab00,color:#1a1a1a
    style L5 fill:#e6f4ea,stroke:#34a853,color:#1a1a1a
    style L6 fill:#e6f4ea,stroke:#34a853,color:#1a1a1a
    style L7 fill:#fce8e6,stroke:#ea4335,color:#1a1a1a

Figure 4.3: The Agentic Computing Stack — seven layers mapping agentic components to their classical analogs.

This stack is not a theoretical proposal — it is forming independently across vendors, which is the strongest evidence that the layers are real. Anthropic’s Claude plugin.json converged on manifest-based primitive bundling independently of APM¹. GitHub’s Agentic Workflows bring CI/CD-native execution to the application layer. Brady Gaster’s Squad² and GitHub’s Spec-Kit³ represent framework-layer emergence: opinionated ways to compose primitives into multi-agent orchestration and spec-driven development. Spec-Kit and Squad are to agentic development what Spring and React are to traditional development — they make orchestration easier in one dimension, constrain freedom in another. They consume primitives via package managers. Any harness can run the resulting workflows. When independent efforts converge on the same layering without coordination, the layers are not an abstraction. They are a discovery.

The maturity distribution across this stack tells you where to invest. The processing layer (LLMs) is powerful and improving on a cadence measured in weeks. The package management and framework layers are embryonic — roughly where npm was in 2012 or where web frameworks were in the early Rails era. This maturity gap between the bottom and top of the stack is exactly what the early PC era looked like: powerful CPUs, primitive operating systems, no standardized distribution. The strategic implication is clear: invest in the layers that compound — primitives, context infrastructure, distribution standards — not the layers that commoditize. Models get cheaper. Context gets more valuable.

4.8 Start Anywhere, Expand Deliberately

The architecture presented in this chapter is designed to be adopted incrementally. There is no prerequisite checklist that must be completed before you begin. The following thresholds are starting points based on patterns observed across early-adopter teams; calibrate them to your baseline. The most common — and most effective — starting point:

Month 1. Pick one team, one phase (usually Code), and one investment (custom instructions encoding your top five conventions). Measure agent output quality before and after. Gate to expand: agent-generated code passes linting on first attempt ≥70% of the time, and the team has documented at least five conventions in machine-readable form.

Month 3. Extend to Review. Add agent-assisted code review with human sign-off on every PR. Measure review turnaround time and defect escape rate. Gate to expand: agent-assisted PRs achieve a review rejection rate no worse than the team’s human-only baseline, and median review turnaround time has decreased by ≥15%.

Month 6. Add Test. Use agents to generate test cases for new features, with human-defined test strategy. Measure coverage change and test maintenance cost. Gate to expand: test coverage has increased by ≥10 percentage points on agent-covered modules, and agent-generated tests require human rework less than 30% of the time.

Month 12. Evaluate Plan and Build phases. By this point, your team has accumulated six months of structured context, and your agents are materially more effective than they were on day one — the compounding flywheel at work. Gate to expand: the team’s human intervention rate on agent tasks has declined by ≥20% from the Month 3 baseline, and at least two context feedback cycles have produced measurable improvement in agent output quality.

Month 18. Assess readiness for Operate phase automation. This requires the most mature infrastructure and the strongest governance — Chapter 5 covers the governance requirements in detail. Gate: the team has structured runbooks for ≥80% of common incident types, and agent-assisted alert correlation achieves ≥90% accuracy in retrospective testing against the past quarter’s incidents.

This is a planning horizon, not a schedule. Some organizations will move faster; some will spend longer at each stage. The sequence matters more than the timeline: start where the tooling is mature and the context is structured, expand where the evidence supports it, and invest in context continuously.

The reference architecture gives you a shared vocabulary for planning. The context moat gives you a reason to start now rather than wait. But architecture without governance is a blueprint without building codes. Chapter 5 addresses the hardest question in AI-assisted delivery: who is accountable when agents are participants in your software lifecycle, and how do you build the trust frameworks that make autonomous work auditable and safe?

Anthropic, “Claude Code Plugins,” https://docs.anthropic.com/en/docs/claude-code/plugins↩︎
Brady Gaster, “How Squad Runs Coordinated AI Agents Inside Your Repository,” GitHub Blog, March 2026. https://github.blog/ai-and-ml/github-copilot/how-squad-runs-coordinated-ai-agents-inside-your-repository/↩︎
GitHub, “Spec Kit — Build High-Quality Software Faster,” https://github.com/github/spec-kit↩︎