Best Practices for AI-DLC: Amazon's Guide to Quality

TL;DR: Amazon recommends five categories of best practices for AI-DLC projects: keeping reverse-engineering artifacts fresh with automated staleness detection, managing context windows through selective artifact loading and conversation compaction, maintaining team alignment via shared extension sets and audit trail reviews, iterating on extensions based on violation patterns rather than pre-emptive rules, and structuring work into right-sized units that balance autonomy with context limits. These practices emerged from internal AWS teams shipping production systems with AI-DLC across 18+ months of real-world usage.

Key Takeaways

• Reverse-engineering artifacts must be regenerated when file timestamps exceed artifact timestamps by more than 7 days — stale context causes the AI to duplicate existing services, break established patterns, and ignore architectural decisions already embedded in the codebase.
• Context window management follows a three-tier loading strategy: early stages load only workspace analysis, design stages load requirements plus architecture, and code generation stages load all artifacts plus targeted file content — reducing token usage by 40-60% while maintaining necessary context.
• Team alignment depends on sharing a consistent extension set through version control, with quarterly reviews of the audit trail to identify where agents consistently bypass human judgment or where approval gates create bottlenecks that should be automated.
• Extension iteration should be data-driven: track violation frequency, resolution time, and false-positive rates for each rule, then strengthen high-value rules, relax low-signal rules, and remove rules that agents never violate.
• Unit sizing targets 3-5 user stories or 500-2000 lines of generated code per unit — smaller units waste context on repeated architecture loading, larger units exceed single-session context limits and increase error accumulation across the construction loop.
• Audit trail analysis reveals productivity patterns: teams should measure time-to-approval per stage, request-changes frequency, and which stages most often trigger rework — these metrics guide workflow tuning and training investments.

Why Best Practices Matter for AI-DLC Projects

AI-DLC transforms how teams build software by inserting structure between "what to build" and "how to build it." The framework provides the methodology — three phases, adaptive depth, per-unit construction loops — but sustained productivity depends on how teams actually use it across weeks and months of development.

Amazon's internal AI-DLC adoption across AWS service teams surfaced patterns that separate high-performing teams from struggling ones. High performers maintain 70-85% first-pass approval rates at stage gates, complete complex features in 40% less calendar time than pre-AI-DLC baselines, and report fewer production defects from AI-generated code. Struggling teams hit context limits that force workflow restarts, accumulate stale artifacts that mislead the AI, and spend more time reviewing AI output than writing code themselves.

The difference is not model choice or prompt engineering. The difference is operational discipline — the practices teams establish for maintaining the system over time.

What Context Artifacts Require Active Maintenance?

AI-DLC generates documentation artifacts throughout the workflow lifecycle. These artifacts serve as persistent memory that survives session boundaries — they are how the AI "remembers" decisions, architecture, and requirements across days or weeks. But artifacts decay. Code changes, requirements evolve, and team decisions shift. Stale artifacts become worse than no artifacts because they provide confident, incorrect context.

Which Artifacts Decay Fastest?

Reverse-engineering artifacts decay immediately when code changes. If architecture.md documents three Lambda functions but the codebase now has five, the AI operates on outdated structural understanding. If dependencies.md shows order-service calling inventory-service via HTTP but the code switched to SQS last week, the AI will generate incorrect integration code.

Requirements and user stories decay when product direction shifts. A requirements document that still lists "OAuth integration" as mandatory when the team decided to use SSO two sprints ago will cause the AI to design the wrong solution.

Application design artifacts decay when architectural decisions change. If the design document specifies a microservices boundary that the team later consolidated into a monolith, every subsequent stage operates on false assumptions.

How Do You Detect Staleness?

AI-DLC's Workspace Detection stage includes staleness checks. It compares artifact timestamps against the last modification time of source files. If any file in the codebase was modified more recently than the reverse-engineering artifacts, the stage flags the artifacts as potentially stale.

Amazon's recommended threshold: regenerate reverse-engineering artifacts when any source file is more than 7 days newer than the artifacts. This balances freshness against the cost of regeneration (2-5 minutes of AI time for a medium codebase).

For requirements and design artifacts, staleness is semantic rather than temporal. Amazon teams use a manual review trigger: before starting a new construction unit, the human approver explicitly confirms that the requirements and design artifacts still reflect current decisions. If they don't, the team reruns the relevant Inception stages before proceeding to Construction.

What Refresh Strategy Works Best?

Automated refresh for reverse-engineering. Teams configure their CI pipeline to regenerate reverse-engineering artifacts nightly or after every merge to main. The artifacts are committed to version control just like code. This ensures every developer and every AI session operates on current architectural understanding.

Versioned refresh for requirements. When product direction changes, the team creates a new requirements document rather than editing the existing one. The old requirements stay in aidlc-docs/inception/requirements/v1/, and the new version goes into v2/. This preserves the decision trail and prevents confusion about what was originally agreed upon versus what changed mid-project.

Lazy refresh for design artifacts. Application design artifacts are regenerated only when architectural changes invalidate them. Most codebases have stable high-level architecture even as individual components evolve. Teams annotate design artifacts with a "last validated" date and owner, making it clear who is responsible for confirming accuracy.

How Do You Manage Context Windows in Long-Running Projects?

AI models have finite context windows. Claude Sonnet 4.5 supports 200K tokens, but a complex project can generate 300K+ tokens of artifacts across Inception and Construction phases. Loading everything into every AI call wastes tokens, increases latency, and can cause context limits to be exceeded mid-session.

What Is the Three-Tier Loading Strategy?

Amazon recommends loading artifacts selectively based on the current stage:

Tier 1 — Workspace Analysis (used in early Inception stages): Load only workspace detection results, file inventory, and technology stack summary. Total: 2-5K tokens. The AI needs to understand "what exists" but not detailed requirements or architecture yet.

Tier 2 — Design Context (used in Requirements through Application Design): Load Tier 1 plus requirements documents, user stories, and reverse-engineering artifacts. Total: 15-40K tokens. The AI needs enough context to make architectural decisions but not the details of other units' functional designs.

Tier 3 — Full Context (used in Construction stages): Load Tier 2 plus the current unit's functional design, NFR requirements, NFR design, infrastructure design, and code generation plan. Also load the actual source files being modified. Total: 50-150K tokens depending on unit size.

This tiered approach reduces average token usage per AI call by 40-60% compared to always loading everything. It also prevents token waste on irrelevant information — the AI does not need to see Unit 3's functional design while it is working on Unit 1's code generation.

How Do You Handle Conversation Compaction?

Long construction sessions — particularly when the AI encounters errors and iterates on fixes — can accumulate hundreds of messages. Raw conversation history grows to exceed context limits.

Amazon teams use strategic compaction at stage boundaries. When a stage completes successfully and the next stage begins, the conversation history from the prior stage is summarized into a single message that preserves:

• Key decisions made (e.g., "chose PostgreSQL over DynamoDB due to complex query requirements")
• Files created or modified (with line counts, not full content)
• Open issues flagged for future stages
• Approval timestamp and approver identity

The detailed back-and-forth is discarded. This keeps conversation history under 20K tokens even in projects that span dozens of stages and weeks of calendar time.

Critical implementation detail: Do not compress audit.md. The full raw conversation history is written to aidlc-docs/audit.md before compaction. This preserves the complete decision trail for compliance, debugging, and team learning even after conversation memory is compressed.

What Happens When You Hit Context Limits Anyway?

Even with tiered loading and compaction, some units exceed context limits. This typically happens when a single unit involves modifying 10+ files with complex interdependencies.

Amazon's recommended recovery strategies, in order of preference:

1. Split the unit. If a unit is too large, decompose it into 2-3 smaller units that can be developed sequentially. This is the cleanest solution because it actually reduces complexity rather than working around it.
2. Use sub-agents. Claude Code's Agent tool and similar sub-agent capabilities let the primary agent delegate specific files or functions to sub-agents with their own isolated context windows. The parent agent maintains the overall plan while sub-agents handle implementation details.
3. Reduce artifact detail. Regenerate the current unit's functional design at Minimal depth rather than Standard or Comprehensive. This sacrifices some detail but keeps the workflow moving.
4. Prune irrelevant history. Manually remove tool results from earlier exploration phases that are no longer relevant to the current task. For example, if the AI ran a grep across the codebase to find examples but has now settled on an approach, those grep results can be deleted from conversation history.

How Do Teams Maintain Alignment Across Members?

AI-DLC projects involve multiple developers over weeks or months. Without alignment mechanisms, each developer uses different extensions, interprets adaptive depth differently, or makes inconsistent decisions about when to skip stages.

What Belongs in Version Control?

All extension files. The .kiro/steering/aws-aidlc-rules/extensions/ directory (or equivalent for other platforms) is committed to the repository just like source code. This ensures every team member and every AI session enforces the same rules. Changes to extensions go through pull request review just like code changes.

The audit trail. aidlc-docs/audit.md is committed after each stage completion. This allows team members to see what decisions were made, why, and by whom — even if they were not the ones running the AI session. It also provides the data needed for retrospectives and process improvements.

State files. aidlc-docs/aidlc-state.md is committed so any team member can pick up the workflow where it was left off. If Developer A completes Unit 1 and pushes the state file, Developer B can start Unit 2 without needing a handoff meeting.

Generated artifacts but not generated code. All Inception and Construction documentation artifacts live in aidlc-docs/ and are committed. The actual source code generated by AI is committed to the normal source tree (src/, lib/, etc.), not duplicated in aidlc-docs/. AI-DLC's design keeps documentation separate from code to avoid confusion about what is authoritative.

How Often Should Teams Review the Audit Trail?

Amazon teams schedule audit trail reviews every 2-4 weeks for active projects. The entire team (or at minimum, the tech lead and the primary AI-DLC operators) reads through audit.md together and discusses:

• Approval gate delays. Which stages consistently take more than 30 minutes for human review? Are those delays because the AI output genuinely needs scrutiny, or because the reviewer is unclear on what to check?
• Request-changes patterns. When humans request changes, what categories do they fall into? "Wrong technology choice," "Missed a requirement," "Broke an existing pattern," "Violated a coding standard," etc. If one category dominates, it suggests either missing context (add to reverse-engineering), missing guardrails (add an extension), or unclear requirements (improve the Requirements stage prompts).
• Extension violations. How often do extensions block progress? Which rules get violated most frequently? If a rule triggers constantly, either the rule is wrong (too strict for the actual requirement) or the AI lacks context to satisfy it (improve the extension's verification instructions).
• Stage skips. For projects using Adaptive Depth, which stages get skipped most often? Are those skips justified by low complexity, or are they shortcuts that cause rework later? If a stage is always skipped, consider removing it from the workflow. If a stage is rarely skipped but causes problems when it is, make it mandatory.

These reviews are the feedback loop that tunes the workflow to the team's actual needs. Without them, teams accumulate friction that slows development but never gets diagnosed or fixed.

How Do You Onboard New Team Members?

New developers joining an AI-DLC project face a steep learning curve. The methodology, the extensions, the artifact structure, and the team's conventions are all unfamiliar.

Amazon's onboarding checklist:

1. Pair on a full unit. New developer shadows an experienced operator through one complete unit construction cycle — from loading context through code generation and test. This reveals the human judgment points that are not captured in documentation.
2. Read the last 4 weeks of audit.md. This provides context on why current architectural decisions were made and what alternatives were considered and rejected. It is the project's institutional memory.
3. Run a throwaway task at Comprehensive depth. Have the new developer use AI-DLC to build a small isolated feature (like a new API endpoint) at Comprehensive depth even if the complexity does not warrant it. This exercises every stage and artifact type, giving hands-on experience with the full workflow before working on critical path features.
4. Review extensions together. Walk through each active extension, explain why it exists, and show examples from the audit trail of when it caught real issues. This builds understanding of what the guardrails protect against rather than treating them as arbitrary rules.

How Do You Iterate on Extensions Over Time?

Extensions encode team standards, compliance requirements, and lessons learned. But not all rules provide equal value. Some rules catch critical defects. Others trigger false positives that waste review time. Extensions need data-driven iteration.

What Metrics Should You Track Per Rule?

Amazon teams instrument their extensions to capture:

• Violation frequency. How many times per week does this rule block progress? If a rule never triggers, it is either perfectly aligned with natural AI behavior (great) or irrelevant to the project (should be removed).
• False positive rate. When the rule blocks progress, how often does human review conclude "actually this is fine, proceed anyway"? A false positive rate above 30% indicates the rule is too strict or poorly specified.
• Resolution time. When a rule triggers a legitimate issue, how long does it take the AI to fix it? Rules that take multiple iterations to satisfy suggest either ambiguous verification criteria or missing context that the AI needs to satisfy the rule.
• Severity distribution. Which rules catch critical issues (security holes, data loss risks, compliance violations) versus style issues (naming conventions, comment formatting)? Critical rules deserve stricter enforcement and more detailed verification instructions. Style rules might be better handled by linters.

When Should You Strengthen, Relax, or Remove Rules?

Strengthen rules that catch high-severity issues but have low enforcement. If a security rule rarely triggers because the AI naturally avoids the pattern, add verification that the AI explicitly checked for the vulnerability rather than assuming absence means compliance. This future-proofs against model updates or different AI operators who might be less careful.

Relax rules with high false-positive rates. If a rule blocks progress frequently but human review overrides 40%+ of violations, the rule is too strict. Add context or exceptions that allow legitimate patterns to pass. For example, a rule that says "all database queries must use prepared statements" might need an exception for internal admin tools where SQL injection risk is negligible.

Remove rules that never trigger and have low severity. If a naming convention rule has fired zero times in six months, the team either naturally follows that convention or the rule is irrelevant. Removing it reduces the extension's size, which saves tokens and reduces cognitive load on developers reading the rules.

Promote patterns to rules when audit shows repeated issues. If the audit trail shows the AI making the same mistake across multiple units — for example, forgetting to add error handling for a specific AWS service call — create an extension that explicitly checks for that pattern. This converts human review burden into automated enforcement.

How Do You Test Extensions?

Before activating an extension project-wide, Amazon teams test it on historical work. Take completed units from the past month, rerun their Code Generation stages with the new extension active, and see if:

• The extension would have caught real issues that slipped through human review (true positives).
• The extension would have blocked submissions that were actually correct (false positives).
• The AI can satisfy the extension's verification criteria without excessive iteration (practicality).

This testing against historical work prevents teams from activating extensions that sound good in theory but cause friction in practice.

What Unit Sizing Produces the Best Results?

AI-DLC's per-unit construction loop requires decomposing a project into units of work. Too small, and the overhead of generating functional design documents and NFR analysis outweighs the implementation work. Too large, and the unit exceeds context limits or accumulates too many errors for the AI to recover from autonomously.

What Metrics Define Unit Size?

Amazon measures unit size across three dimensions:

User stories per unit. The number of distinct user stories assigned to the unit. Range: 1-10 stories. Amazon's target: 3-5 stories per unit. Single-story units waste time generating design docs for trivial features. Ten-story units are too complex for the AI to keep all requirements in mind simultaneously, leading to features that conflict or incompletely implement requirements.

Lines of generated code per unit. The total lines of code (excluding comments and whitespace) produced during the unit's Code Generation stage. Range: 100-5000 lines. Amazon's target: 500-2000 lines per unit. Below 500 lines suggests the unit could have been combined with another. Above 2000 lines increases the probability that the AI loses track of internal consistency across files.

Context tokens required per unit. The total tokens consumed by loading the unit's full context (functional design + NFR + infrastructure design + source files being modified). Range: 20K-150K tokens. Amazon's target: 40K-100K tokens per unit. This leaves headroom in a 200K context window for conversation history, tool results, and model reasoning.

How Do You Know When to Split a Unit?

During the Application Design → Units Generation phase, AI-DLC produces an initial unit decomposition. But that decomposition is a hypothesis, not a law. If a unit proves too large during Construction, split it.

Signs a unit should be split:

• The Functional Design document exceeds 4000 words. This usually indicates the unit is trying to do too many distinct things.
• The Code Generation Plan lists 10+ files to create or modify. Unless these are trivial files, this scope will exceed single-session context limits.
• The AI requests clarification on requirements three or more times during Construction. This suggests the requirements are complex enough that they should have been decomposed further.
• The Build and Test stage reveals that changes to File A broke File B, and the AI did not anticipate the dependency. This indicates the unit spans loosely coupled subsystems that should have been separate units.

How to split mid-unit: Pause the current unit's Construction. Return to Workflow Planning and split the problematic unit into 2-3 smaller units. Complete the smaller units sequentially. Resume the original workflow plan with the new unit structure.

How Do You Know When to Merge Units?

Conversely, if units are too small, time is wasted on repeated context loading and design documentation for trivial features.

Signs units should be merged:

• The Functional Design document is under 500 words. There is not enough complexity to justify the design overhead.
• Code Generation completes in a single AI turn with no errors or clarifications needed. The task was trivial.
• Multiple units modify the same files repeatedly. This indicates artificial decomposition — the units are not actually independent.

How to merge units: During Workflow Planning, before Construction begins, identify units that share files or implement tightly coupled features. Combine them into a single unit with a unified Functional Design that covers the entire scope.

How Do You Measure AI-DLC Productivity?

Adopting AI-DLC is an investment. Teams need metrics that show whether the investment is paying off — and where to improve.

What Are the Right Productivity Metrics?

Time to first-pass approval per stage. Measure how long it takes the AI to generate stage output that the human approver accepts without requesting changes. Target: 80%+ of stages approved on first pass. Consistently low approval rates indicate missing context, unclear requirements, or misaligned extensions.

Calendar time per unit (end to end). From starting Functional Design through passing Build and Test, how many calendar days does a unit consume? This accounts for human approval delays, iteration on errors, and any context-limit issues. Compare against pre-AI-DLC baselines for similar features. Amazon's internal data shows 40-60% reduction in calendar time for standard-complexity features.

Human review time per stage. How long does a human spend reviewing AI-generated output before approving or requesting changes? This should be significantly lower than the time it would take to write the artifact manually. If humans spend 90% as long reviewing as they used to spend writing, the AI is not providing leverage — it is just shifting the work.

Defect escape rate to production. How many defects found in production originated from AI-generated code? Track this separately from human-written code to understand if AI code has different quality characteristics. Amazon teams find AI-generated code has 20-40% fewer defects than human-written baselines, primarily because the AI consistently applies patterns and checks constraints that humans sometimes forget.

Extension violation resolution time. When an extension blocks progress, how many AI iterations does it take to resolve? Consistent multi-iteration resolutions suggest the extension's verification criteria are unclear or the AI lacks context to satisfy the rule.

What Metrics Should You Ignore?

Lines of code generated per hour. This incentivizes the AI to write verbose code, not good code. It also ignores the value of Inception phases that generate zero code but prevent costly rework.

Number of stages completed. Different projects need different stages. Completing more stages does not mean higher productivity — it might mean excessive process overhead.

Token costs in isolation. Token costs only matter relative to human salary costs. If the AI consumes $50 of tokens to save 8 hours of developer time, that is a 100x return even though the token bill seems high in absolute terms.

FAQ

How often should reverse-engineering artifacts be refreshed?

Regenerate reverse-engineering artifacts when source files are more than 7 days newer than the artifacts, or immediately before starting Construction on a unit if the codebase has changed since Inception completed. Automate this refresh in CI pipelines for active projects to ensure the AI always operates on current architectural understanding.

What is the recommended unit size for AI-DLC projects?

Target 3-5 user stories per unit, 500-2000 lines of generated code per unit, and 40K-100K context tokens per unit. Smaller units waste overhead on repeated design artifacts; larger units exceed context limits and increase error accumulation. Split units during Construction if functional design exceeds 4000 words or code generation spans 10+ files.

How do you handle context window limits in large projects?

Use three-tier context loading: early stages load only workspace analysis (2-5K tokens), design stages add requirements and architecture (15-40K tokens), and construction stages load full context including source files (50-150K tokens). Compress conversation history at stage boundaries, preserving decisions and file changes but discarding verbose tool output. For units that still exceed limits, split them into smaller units or use sub-agents.

Should extension rule sets be shared across projects?

Yes — enterprise teams maintain a central extension library in a shared repository, then selectively activate extensions per project via opt-in mechanisms. Security and compliance extensions (HIPAA, PCI-DSS, SOC2) are typically required across all projects. Coding style and architectural pattern extensions vary by tech stack. Teams pull the latest extensions at project start and periodically sync updates for critical security rules.

How do you measure if AI-DLC is improving productivity?

Track time-to-first-pass-approval per stage (target 80%+ first-pass rate), calendar time per unit (compare to pre-AI-DLC baselines), human review time per stage (should be well under manual authoring time), and defect escape rate to production (AI-generated code should match or beat human-written quality). Ignore lines-of-code metrics and token costs in isolation — these incentivize the wrong behaviors.

What team size benefits most from AI-DLC?

Teams of 3-10 developers see the highest productivity multiplier. Solo developers gain less because the overhead of maintaining extensions and artifacts is not shared. Teams larger than 10 require explicit workflow coordination (who runs which units, how to merge work) that is independent of AI-DLC itself. The methodology's human-in-the-loop gates and shared audit trail provide maximum value when multiple developers need to stay aligned on decisions and architecture.

How do you prevent the AI from generating low-quality code?

Use extensions to enforce quality constraints as blocking rules, not suggestions. Define specific verification criteria for every rule — "code quality" is too vague, but "all API endpoints have input validation with Joi schemas" is verifiable. Run lint and test suites as part of the Build and Test stage and feed failures back to the AI for correction before human review. Track defect escape rates per unit and per developer to identify patterns where quality is slipping.

Can AI-DLC work with non-AWS tools and platforms?

Yes — AI-DLC is a methodology, not an AWS service. The rule files work with any AI coding agent that supports instruction files: Kiro, Amazon Q, Cursor, Claude Code, GitHub Copilot, and more. The workflow artifacts are platform-agnostic markdown files stored in aidlc-docs/. AgentCore is AWS-specific infrastructure, but teams can use AI-DLC with self-hosted infrastructure or other cloud providers by replacing AgentCore with their own agent runtime.