Agentic SDLC Adoption Guide

Start Here

Software engineering teams are being asked to adopt agents into real delivery work.

Agents can help design, build, test, refactor, document, and operate software. That part is no longer the hard question. The harder question is whether engineers, architects, and technical leaders can keep agent-assisted work aligned with the domain, architecture, security posture, and business outcome.

This workbench gives teams a way to do that. Start with the problem, workflow, constraints, architecture options, tests, and review gates. Then use agents to help execute the work, update artifacts, strengthen tests, and prepare review evidence.

Use the full path when a team needs an adoption model. Use one section when the team only needs help with intake, architecture, validation, security, readiness, roadmap planning, or agent handoff.

Checklist

Operating Principles

First-principles hierarchy

At the highest level, an application is a controlled mechanism for helping users complete a business process. The code is an implementation of that mechanism. The UI is an access path to it. The database is its memory. The architecture is the set of boundaries and tradeoffs that allow the mechanism to evolve safely.

Business outcome
  -> User jobs and workflow
  -> Decisions, states, and rules
  -> Data and audit trail
  -> Application use cases
  -> UI, API, storage, integrations, deployment
  -> Tests, observability, operations, release controls

Practical architecture doctrine

The most maintainable system is not the most sophisticated one. It is the system whose important decisions are explicit, whose boundaries match the business, whose failure modes are known, whose tests protect core behavior, and whose next engineer can understand the intent without reconstructing it from scattered code.

Avoiding over-engineering

Over-engineering usually starts when the architecture is designed around imagined scale, imagined teams, imagined integrations, or imagined reuse. Responsible engineering starts with observed workflow, real risk, measurable quality attributes, and reversible decisions.

Checklist

Project Intake and Classification

Project classification

Most engineering projects fall into one of several routes. A prototype productionization project is different from a greenfield build. A data/reporting application is different from a workflow application. A client-facing product requires different evidence than an internal tool.

Intake dimensions

Capture enough context to determine the risk class and the minimum artifact set. Do not let intake become an analysis paralysis exercise. The goal is to determine the next responsible step.

Checklist

First-Principles Product Canvas

The product canvas converts intent into engineering inputs. It should be short enough to use in a workshop and precise enough to drive architecture, testing, and UAT.

Core questions

• What job is the user trying to accomplish?
• What decision does the system help the user make?
• What work is the system taking out of the process?
• What must be deterministic, auditable, and repeatable?
• What exceptions cause risk, confusion, rework, or delay?
• What should the system explicitly not do?

Product thesis formula

For [primary user], who needs to [job], this application will [capability]
so that [business outcome]. Unlike [current method], it will [key differentiator]
while preserving [controls, accuracy, auditability, or speed].

Checklist

Prototype and Current-State Discovery

A sophisticated prototype often contains excellent product insight and fragile implementation shortcuts at the same time. The task is to harvest the product knowledge without accidentally promoting demo architecture into long-term architecture.

Discovery rule

For every finding, classify it as one of four evidence types:

• Observed fact: directly supported by repository, UI behavior, schema, workflow note, or stakeholder confirmation.
• Reasonable inference: likely true based on multiple observations, but not yet confirmed.
• Assumption: useful working belief that needs validation.
• Open question: unknown that could affect design, scope, security, or delivery sequence.

Prototype disposition categories

• Retain: production-suitable behavior or code.
• Refactor: valuable behavior with weak structure.
• Replace: demo-only implementation or unsafe design.
• Spike: uncertain area requiring small technical investigation.
• Unknown: not enough evidence yet.

Checklist

Workflow and Process Mapping

Workflow mapping translates screens and functions into a process model. The model should describe who acts, what state changes, what data changes, what rules fire, and what evidence is recorded.

Workflow model format

Workflow name:
Primary actor:
Trigger:
Preconditions:
Main path:
Decision points:
Exception paths:
Data created or changed:
Roles allowed:
Audit requirements:
Acceptance criteria:

State model discipline

Do not confuse screen navigation with workflow state. A record can move from draft to submitted to approved to completed independent of how the UI is organized. Production architecture should make those states explicit and testable.

Checklist

Domain and Data Model

The domain model is the language of the business. The data model is the durable structure that preserves that language. In deterministic workflow systems, the most important data questions are about ownership, lifecycle, validation, audit, and configuration.

Entity analysis

• What are the core business entities?
• Who creates, owns, modifies, approves, and retires them?
• What lifecycle does each entity follow?
• Which fields are required, calculated, derived, or configured?
• Which fields require history, audit, or immutability?
• Which records must never be physically deleted?

Data architecture posture

For most internal workflow applications, start with a relational database. Use explicit constraints where possible. Use migrations. Use seed data intentionally. Separate demo data from test fixtures and production data.

Checklist

Architecture Options and Decision Matrix

Do not ask an agent for the best architecture in the abstract. Define options, define quality attributes, score the tradeoffs, and record why the decision is responsible now.

Starting hypothesis

For many small-to-medium deterministic workflow/data applications, a modular monolith with clean domain boundaries is a useful starting hypothesis. Treat that as something to test against project evidence, not as an automatic architecture decision.

When to split services

Split only when concrete evidence justifies it: independent deployment, independent scaling, hard team boundaries, strong integration boundaries, differing reliability requirements, or external ownership. Do not split only because the system may grow.

Checklist

Target Architecture Package

The architecture package should be lightweight but complete enough to prevent drift. Use multiple diagrams instead of one overloaded diagram. A progressive view is easier to reason about and easier for agents to update.

Minimum diagram set

• System context: users, external systems, identity provider, application boundary, database, integrations.
• Container/runtime: frontend, backend/API, database, jobs, storage, external services, hosting.
• Component/module: workflow, domain modules, authorization, reporting, administration, audit, integrations.
• Data model/ERD: entities, relationships, lifecycle, audit, configuration.
• Workflow state: states, transitions, exceptions, reversals, terminal states.
• Sequence diagram: critical workflow path from user action to persisted result.
• Deployment view: environments, runtime nodes, secrets, network boundaries, deployment path.
• Security/trust-boundary view: authentication, authorization, sensitive data, audit, admin paths.

Architecture text structure

Use a pragmatic blend of C4 and arc42: context, goals, constraints, solution strategy, building blocks, runtime view, deployment, crosscutting concepts, decisions, quality requirements, risks, and glossary.

Checklist

Agentic Engineering SDLC

Software teams using agents change the throughput profile of delivery work. Agents can create code, tests, documentation, summaries, and refactors faster than a team can inspect casually. The SDLC has to adapt so review, validation, governance, and traceability keep pace with implementation.

Operating loop

Human frames the problem
  -> Agent performs read-only discovery
  -> Human validates understanding
  -> Agent drafts product shape brief or technical design
  -> Human approves direction
  -> Agent creates execution plan
  -> Human reviews plan
  -> Agent implements small vertical slice
  -> Automated tests and checks run
  -> Human reviews diff and behavior
  -> UAT validates business outcome
  -> Agent helps update artifacts, tests, decision log, and handoff
  -> Human accepts or rejects the update
  -> Next slice begins

Human verification gates

Human review is strongest when it happens at known gates: orientation, product shape, architecture selection, execution plan approval, PR review, UAT readiness, production readiness, and release decision. Agents can prepare the evidence and update the artifacts, but local owners still decide whether the work is correct, secure, maintainable, and ready for the next step.

Checklist

Testing and Validation Strategy

Tests should make the system safer to change. They should not become a second system that is harder to maintain than the application. Start with core business rules and golden workflows, then add coverage where failure would matter.

Layered strategy

• Domain unit tests: business rules, calculations, state transitions, permission logic.
• Application/use-case tests: validation, orchestration, transactions, error handling.
• Integration tests: database, migrations, repositories, external adapters, serialization.
• API tests: contract behavior, status codes, validation responses, authorization boundaries.
• Workflow/E2E tests: critical user journeys and exception paths.
• UAT scripts: business-readable validation with expected evidence.
• Security tests: auth, authorization, direct object access, input validation, secrets, dependency checks.

Golden scenario suite

For deterministic business applications, maintain a small suite of known-good scenarios with fixtures and expected results. These become the shared validation language between product owner, engineer, QA, client, and agent.

Checklist

Environments, Release Path, and Operations

Environment strategy is a risk-management decision. More environments do not automatically create more quality. Each environment must have a clear job.

Recommended baseline

• Local: fast development loop, test fixtures, no production secrets.
• Preview: branch or PR validation when feasible, disposable data, technical review.
• UAT: stable candidate for business validation, realistic synthetic or masked data.
• Production: controlled access, backups, monitoring, rollback, support ownership.

Promotion path

Local -> PR/preview -> UAT -> Production

Every promotion should have evidence: passing checks, reviewed diffs, release notes, migration status, known limitations, and rollback posture.

Checklist

Security and Secure-by-Design Checklist

For internal business applications, the practical minimum is explicit authentication, server-side authorization, least privilege, secrets management, input validation, audit logging, dependency hygiene, backup/restore, and secure deployment configuration.

Security posture

Use NIST SSDF as the secure SDLC vocabulary and OWASP ASVS as the web application verification checklist. Apply a risk-based subset rather than attempting every control on day one.

Agent-specific security considerations

• Do not give agents production secrets.
• Limit agent permissions to the task scope.
• Require review for migrations, auth changes, data deletion, infrastructure changes, and dependency changes.
• Keep prompt history and generated code out of sensitive-data paths when required.
• Use generated code governance: origin, intent, review, tests, owner, and production responsibility.

Checklist

Client Visibility and Governance

The client should see product and delivery evidence, not raw development churn. The purpose of visibility is alignment, decision-making, and confidence.

Client-visible artifacts

• Product brief
• Workflow diagrams
• Backlog by business capability
• Acceptance criteria
• Demo environment or screenshots
• UAT scenarios
• Decision log
• Known limitations
• Release notes
• Open owner decisions

Keep internal by default

• Raw agent chats
• Experimental branches
• Security-sensitive implementation details
• Credentials, environment values, and deployment secrets
• Unreviewed architecture speculation
• Low-level task churn that does not require client action

Checklist

Production Readiness

A production readiness review should answer a direct question: are we comfortable owning this system after users rely on it? The answer must be based on evidence, not confidence.

Readiness domains

• Product: workflow validated, MVP clear, UAT passed, users trained.
• Data: schema reviewed, migrations tested, backup/restore defined, retention addressed.
• Security: auth, authorization, secrets, audit, dependency checks, sensitive-data controls.
• Quality: critical tests passing, UAT evidence captured, known limitations documented.
• Operations: deployment repeatable, rollback known, logs available, support owner named.
• Business: launch communication, escalation path, enhancement backlog, ownership model.

Checklist

30/60/90 Roadmap Builder

The roadmap should be iterative and stack-aware. You will move up and down from product intent to infrastructure, from workflow to data model, from tests to UI, and from client communication to code.

Baseline path

• Days 1-10: understand and map. Produce orientation, current-state architecture, workflow map, data model sketch, risks, and open questions.
• Days 11-30: shape and decide. Produce product shape brief, technical design, architecture decision record, module map, test strategy, and first vertical-slice plan.
• Days 31-60: build foundation and first vertical slice. Implement app skeleton or refactor foundation, auth/RBAC baseline, database migrations, core domain module, tests, and preview/UAT deployment.
• Days 61-90: harden and pilot. Add workflow slices, exception paths, audit trail, UAT package, operational runbook, and production readiness evidence.

Roadmap rule

Every 30 days should produce durable understanding and working evidence. Do not allow the project to produce only code without artifacts, or only artifacts without working behavior.

Checklist

Templates and Worksheets

This section contains standard templates. Use them as living documents. Keep them concise, update them as evidence changes, and link them to source files, decisions, and tests.

Decision object

Decision:
Context:
Problem:
Options:
Constraints:
Quality attributes:
Evidence:
Recommendation:
Risks:
Mitigations:
Owner:
Date:
Revisit trigger:

Implementation slice object

Slice name:
Business outcome:
User story:
Acceptance criteria:
Affected modules:
Data impact:
Security impact:
Test plan:
Demo evidence:
Rollback considerations:

Business rule object

Rule ID:
Rule statement:
Applies when:
Inputs:
Output:
Source of truth:
Examples:
Exceptions:
Owner:
Test cases:

Checklist

Prompt Library

Prompts should specify operating mode, evidence requirements, output structure, non-goals, and approval gates. The best prompts constrain the agent enough to preserve architecture, while leaving room for implementation intelligence.

Keep prompts tied to artifacts. Agents should not work from memory when project context is captured in current-state discovery, product shape brief, technical design, execution plan, tests, and decision logs.

Checklist

You are working in read-only discovery mode. Do not modify files.

Project: [PROJECT NAME].

Goal: help me understand the current system deeply enough to correlate implementation with business workflows, identify architecture and productionization gaps, and prepare a target architecture decision.

Start broad before narrowing. Inspect repository instructions, README files, package/build files, entry points, UI routes, API routes/controllers, domain/business logic, database/schema/migrations, integrations, authentication/authorization, tests, deployment files, environment configuration, and CI/CD clues.

Create a current-state discovery report with these sections:
1. Executive summary
2. Repository structure and technology stack
3. Runtime architecture
4. User-facing workflows
5. Screens, routes, and navigation
6. APIs and backend use cases
7. Domain model and business rules
8. Data model, persistence, migrations, and seed/demo data
9. Roles, permissions, authentication, and trust boundaries
10. Integrations and external dependencies
11. Tests and validation coverage
12. Deployment and environment assumptions
13. Observability, logging, and supportability
14. Prototype elements to retain, refactor, replace, spike, or classify as unknown
15. Productionization gaps
16. Risks of premature implementation
17. Recommended lifecycle route
18. Next five owner decisions

For every finding, distinguish observed fact, reasonable inference, assumption, and open question. Include repository-relative file path evidence. Do not create an implementation plan yet.

Using the current-state discovery report and repository evidence, create a visual architecture package for [PROJECT NAME].

Generate Mermaid diagrams for:
1. System context
2. Container/runtime view
3. Component/module view
4. Data model / ERD
5. Primary workflow state machine
6. Sequence diagram for the most important user workflow
7. Deployment view
8. Security and trust-boundary view

For each diagram:
- Include a short explanation.
- State what is observed from code versus inferred.
- Highlight unknowns.
- Identify productionization risks.
- Do not invent integrations, roles, or services that are not supported by evidence.
- If prototype code conflicts with documentation or workflow notes, call out the contradiction.

Create a product shape brief for [PROJECT NAME].

Use the current-state discovery, stakeholder notes, prototype behavior, and workflow artifacts as evidence. Do not invent features. Separate observed facts, assumptions, and open questions.

Include:
1. Product thesis
2. Problem statement
3. Business outcomes
4. Primary users and secondary stakeholders
5. Jobs to be done
6. Current manual or prototype-supported process
7. Core workflows
8. Exception workflows
9. Business rules
10. Decision tables
11. Conceptual data model
12. Roles and permissions
13. MVP scope
14. Explicit non-goals
15. Deferred roadmap
16. Acceptance criteria
17. UAT scenarios
18. Risks and unresolved questions
19. Owner decisions needed before technical design

Keep the document practical enough to drive implementation and client review.

Compare architecture options for [PROJECT NAME] using evidence from the current-state discovery and product shape brief.

Options to evaluate:
1. Productionize the prototype in place
2. Refactor the prototype into a modular architecture
3. Rebuild as a production modular monolith
4. Build service-oriented or microservice architecture
5. Use low-code/configuration platform
6. Defer implementation pending additional discovery

Score each option from 1 to 5 on:
- Maintainability
- Modularity
- Security
- Testability
- Delivery speed
- Long-term scalability
- Operational simplicity
- Team skill fit
- Agent compatibility
- Client fit
- Cost
- Risk

Provide:
- Decision matrix
- Recommendation
- Rationale
- Risks
- Mitigations
- Revisit trigger
- First vertical slice that would prove the decision.

Create a practical technical design for [PROJECT NAME] based on the approved architecture decision.

Include:
1. Executive summary
2. System boundaries
3. Technology stack
4. Module boundaries
5. Data model and migrations
6. API/use-case design
7. Workflow state model
8. Roles and authorization model
9. Validation and error-handling strategy
10. Audit logging strategy
11. Testing strategy
12. Environment strategy
13. Deployment and rollback approach
14. Observability and supportability
15. Security checklist
16. Open questions
17. First three implementation slices

Keep the design implementation-ready but avoid speculative architecture.

Create an execution plan for the first vertical slice of [PROJECT NAME].

The slice must exercise UI, application/use-case logic, domain rule, database persistence, authorization, validation, and tests. Keep the slice small enough to review in one PR.

Include:
1. Objective
2. Business outcome
3. Acceptance criteria
4. Files and modules likely affected
5. Data model changes
6. Migration plan
7. API/use-case changes
8. UI changes
9. Authorization impact
10. Test plan
11. Manual validation steps
12. Risks
13. Rollback considerations
14. Commit/PR plan
15. Definition of done

Do not implement yet. Wait for approval.

Create a practical test strategy for [PROJECT NAME].

Use the product shape brief, architecture decision, technical design, and current-state discovery. Focus on tests that protect business-critical behavior and avoid test bloat.

Include:
1. Testing principles
2. Domain unit tests
3. Application/use-case tests
4. Integration tests
5. API tests
6. Workflow/E2E tests
7. UAT scripts
8. Security tests
9. Golden scenario suite
10. Test data and fixtures
11. CI gating strategy
12. Maintenance rules
13. Tests to avoid or defer

For each proposed test, explain the business risk it protects.

Perform a security review of [PROJECT NAME] using a pragmatic subset of NIST SSDF and OWASP ASVS concepts.

Focus on:
1. Authentication
2. Authorization and role enforcement
3. Direct object access risks
4. Input validation
5. Secrets management
6. Sensitive data handling
7. Audit logging
8. Dependency and supply-chain risk
9. Error handling and information disclosure
10. Configuration by environment
11. Admin functions
12. Data backup and restore
13. Agent-generated code governance

Classify findings as blocker, high, medium, low, or observation. For each finding, provide evidence, impact, recommended fix, and validation method.

Review this PR for [PROJECT NAME] as an architecture-aware reviewer.

Evaluate:
1. Alignment with approved architecture and module boundaries
2. Business behavior and acceptance criteria
3. Data integrity and migrations
4. Authorization and security impact
5. Error handling
6. Test quality and meaningful assertions
7. Maintainability and readability
8. Unnecessary abstraction or over-engineering
9. Hidden coupling
10. Documentation updates
11. Risk to production operations

Return:
- Summary
- Must-fix issues
- Should-fix issues
- Questions
- Suggested tests
- Approval recommendation
- Follow-up technical debt items

Conduct a production readiness review for [PROJECT NAME].

Review evidence across:
1. Product readiness
2. Data readiness
3. Security readiness
4. Quality readiness
5. Operational readiness
6. Business readiness
7. Support readiness
8. Deployment and rollback readiness

For each area, classify as ready, conditionally ready, not ready, or unknown. Identify launch blockers, accepted risks, missing evidence, owner decisions, and post-launch follow-ups. End with a readiness assessment, required local reviewers, and the local approval gate. Do not approve launch, compliance, security acceptance, or production release.

Create a client-facing progress summary for [PROJECT NAME].

Tone: clear, practical, business-readable, not overly technical.

Include:
1. What has been clarified
2. What has been built or validated
3. Workflow or product decisions made
4. Current risks or known limitations
5. Decisions needed from the client/product owner
6. Next milestone
7. What will be demonstrated next

Do not expose raw agent activity, credentials, security-sensitive implementation details, or low-level engineering churn.

Study Guide and Research Foundation

Use this study path when a team needs the source foundation behind the workbench. It draws from software architecture, lean documentation, secure SDLC practices, modern testing, and emerging agent-assisted delivery workflows.

Study path

1. Engineering performance and AI impact: start with DORA and GitLab to understand the productivity/control tradeoff.
2. Agentic workflow mechanics: study Codex, Claude Code, GitHub Copilot, and AGENTS.md to structure agent work safely.
3. Architecture communication: use C4 and arc42 to create diagrams and documents that are understandable and maintainable.
4. Application architecture: use clean architecture and monolith-first thinking to avoid premature distribution while preserving modularity.
5. Security: use NIST SSDF for SDLC vocabulary and OWASP ASVS for verification requirements.
6. Testing and release: use Playwright, pytest, feature-flag hygiene, and twelve-factor configuration principles for practical delivery controls.

Checklist

Source Library

These sources help teams keep the methodology current as agent-assisted delivery practices, tools, and governance expectations change.

1. DORA State of AI-assisted Software Development 2025 - Google Cloud DORA. Source. Field research foundation for AI-assisted delivery, throughput, quality, organizational capabilities, and control systems.
2. GitLab 2026 AI Accountability Report - GitLab. Source. Evidence that AI coding shifts the bottleneck from writing code to review, validation, traceability, governance, and technical-debt control.
3. Codex best practices and Codex skills - OpenAI Developers. Source. Practical agent workflow guidance for context, planning, validation, skills, and repeated workflows.
4. Claude Code common workflows and best practices - Anthropic. Source. Plan-before-editing, subagents for discovery, reviewable workflows, and repository-scale exploration.
5. GitHub Copilot coding agent AGENTS.md support - GitHub. Source. Repository-level instructions for guiding coding agents on build, test, and validation behavior.
6. AGENTS.md open format - agents.md. Source. Simple standard for durable agent instructions in repositories.
7. NIST Secure Software Development Framework SP 800-218 - NIST CSRC. Source. Secure software development vocabulary and practice model that can be integrated into any SDLC.
8. NIST SSDF Version 1.2 Initial Public Draft - NIST CSRC. Source. Updated draft direction for secure and reliable development, delivery, and improvement of software.
9. OWASP ASVS 5.0 - OWASP. Source. Concrete web-application security verification requirements for pragmatic launch gates.
10. Common web application architectures and clean architecture - Microsoft Learn. Source. Layered and clean architecture framing, with business logic at the core and infrastructure as an outer concern.
11. Monolith First - Martin Fowler. Source. Rationale for starting with a monolith and discovering boundaries before moving to distributed services.
12. The C4 model for visualising software architecture - Simon Brown. Source. Simple progressive architecture views: context, containers, components, and code.
13. arc42 architecture documentation template - arc42. Source. Lean architecture documentation structure: context, strategy, building blocks, runtime, deployment, decisions, quality, risks, and glossary.
14. Playwright best practices - Playwright. Source. E2E testing guidance with resilient locators, auto-waiting, and user-facing selectors.
15. pytest documentation - pytest. Source. Small readable tests that can scale to complex functional testing.
16. Reducing technical debt from feature flags - LaunchDarkly. Source. Flag hygiene, lifecycle ownership, and stale-flag removal discipline.
17. The Twelve-Factor App - 12factor.net. Source. Practical cloud application principles for configuration, dependencies, backing services, logs, and deployment.