ai-development-patterns

AI Development Patterns

📋 How ready is your team for AI-assisted development? Take the free AI Development Readiness Scorecard to find out — and discover which patterns to adopt first.

A comprehensive collection of patterns based on my experience for building software with AI assistance, organized by implementation maturity and development lifecycle phases. These patterns are subject to change as the field evolves.

Terminology

This catalog uses coding agent for tools such as Claude Code, OpenAI Codex, and Google Antigravity that can generate and execute code, run checks, and iterate on results. Agentic engineering is the professional practice of building software with those agents. The broader terms AI assistant and AI coding assistant are reserved for systems that may provide suggestions or chat without independently executing and validating changes.

Adoption verdicts are mechanically recomputed from structured, tiered evidence. Model-backed evidence research runs only on demand in a signed-in interactive evaluator session with an explicit plan approval, implemented today by the local Codex app; GitHub Actions never calls an evaluator model or receives an evaluator API key. CI performs deterministic schema, provenance, derivation, status-drift, link, and content checks, including a weekly read-only freshness check. See verification/STATUS.md for every stable and exploratory pattern's assessed, pending, and provenance state, and verification/ for the local-agent workflow and trust model.

graph TB
    subgraph F[Foundation]
        RDY[Agent Readiness] --> CR[Codified Rules] --> SS[Security Sandbox]
        SS --> DL[Developer Lifecycle] --> TI[Tool Integration]
        RDY --> IG[Issue Generation]
    end

    subgraph D[Development]
        DL --> SD[Spec-Driven Development]
        PI[Planned Implementation] --> INCR[Incremental Generation]
        INCR --> AD[Atomic Decomposition] --> PA[Parallel Agents]
        INCR --> AE[Adversarial Evaluator]
        CR --> AM[Agent Memory] --> PD[Progressive Disclosure]
        CR --> AH[Agent Hooks] --> CC[Custom Commands]
        SD --> IS[Image Spec]
        CR --> GR[Guided Refactoring]
        DL --> AO[Agent Observability] --> ER[Error Resolution]
        TI --> MR[Model Routing]
        AM --> CRES[Code Research]
        PA --> BA[Bounded Autonomy]
    end

    subgraph O[Operations]
        SS --> PG[Policy Generation] --> EVA[Evidence Automation]
        CR --> CZR[Centralized Rules]
        AO --> DR[Drift Remediation]
        GR --> DF[Debt Forecasting]
        AO --> GC[Guided Chaos]
    end

    classDef foundation fill:#a8d5ba,stroke:#2d5a3f,stroke-width:2px,color:#1a3a25
    classDef development fill:#f9e79f,stroke:#b7950b,stroke-width:2px,color:#7d6608
    classDef operations fill:#f5b7b1,stroke:#c0392b,stroke-width:2px,color:#78281f
    class RDY,CR,SS,DL,TI,IG foundation
    class SD,PI,INCR,AD,PA,AE,AM,PD,AH,CC,IS,GR,AO,ER,MR,CRES,BA development
    class PG,EVA,CZR,DR,DF,GC operations

    click RDY "https://github.com/PaulDuvall/ai-development-patterns#agent-readiness"
    click CR "https://github.com/PaulDuvall/ai-development-patterns#codified-rules"
    click SS "https://github.com/PaulDuvall/ai-development-patterns#security-sandbox"
    click DL "https://github.com/PaulDuvall/ai-development-patterns#developer-lifecycle"
    click TI "https://github.com/PaulDuvall/ai-development-patterns#tool-integration"
    click IG "https://github.com/PaulDuvall/ai-development-patterns#issue-generation"
    click SD "https://github.com/PaulDuvall/ai-development-patterns#spec-driven-development"
    click PI "https://github.com/PaulDuvall/ai-development-patterns#planned-implementation"
    click INCR "https://github.com/PaulDuvall/ai-development-patterns#incremental-generation"
    click AM "https://github.com/PaulDuvall/ai-development-patterns#agent-memory"
    click AH "https://github.com/PaulDuvall/ai-development-patterns#agent-hooks"
    click CC "https://github.com/PaulDuvall/ai-development-patterns#custom-commands"
    click PD "https://github.com/PaulDuvall/ai-development-patterns#progressive-disclosure"
    click AD "https://github.com/PaulDuvall/ai-development-patterns#atomic-decomposition"
    click GR "https://github.com/PaulDuvall/ai-development-patterns#guided-refactoring"
    click AO "https://github.com/PaulDuvall/ai-development-patterns#agent-observability"
    click IS "https://github.com/PaulDuvall/ai-development-patterns#image-spec"
    click AE "https://github.com/PaulDuvall/ai-development-patterns#adversarial-evaluator"
    click PA "https://github.com/PaulDuvall/ai-development-patterns#parallel-agents"
    click ER "https://github.com/PaulDuvall/ai-development-patterns#error-resolution"
    click MR "https://github.com/PaulDuvall/ai-development-patterns#model-routing"
    click CRES "https://github.com/PaulDuvall/ai-development-patterns#code-research"
    click BA "https://github.com/PaulDuvall/ai-development-patterns#bounded-autonomy"
    click PG "https://github.com/PaulDuvall/ai-development-patterns#policy-generation"
    click EVA "https://github.com/PaulDuvall/ai-development-patterns#evidence-automation"
    click CZR "https://github.com/PaulDuvall/ai-development-patterns#centralized-rules"
    click DR "https://github.com/PaulDuvall/ai-development-patterns#drift-remediation"
    click DF "https://github.com/PaulDuvall/ai-development-patterns#debt-forecasting"
    click GC "https://github.com/PaulDuvall/ai-development-patterns#guided-chaos"

Legend: 🟢 Foundation | 🟡 Development | 🔴 Operations

Pattern Organization

This repository provides a structured approach to AI-assisted development through three pattern categories:

• Foundation Patterns - Essential patterns for team readiness and basic AI integration
• Development Patterns - Daily practice patterns for AI-assisted coding workflows
• Operations Patterns - CI/CD, security, and production management with AI
• Experimental Patterns - Advanced and experimental patterns under active development and/or consideration.

• Moved to experiments: Security Orchestration

• Moved to experiments: Autonomous Remediation

Harness Engineering Lens

The Harness Engineering framing — Agent = Model + Harness — describes the controls built around a coding agent (separate from the model) to make its output trustworthy. Harness Engineering isn't one of the patterns in this catalog; it's a lens over them — a way of grouping the patterns below and understanding why you'd use them together. Every control is one of two kinds and runs in one of two ways:

• Feedforward (guides) steer the agent before it acts.
• Feedback (sensors) observe after it acts so it can self-correct.
• Computational controls are deterministic, fast, and reliable — linters, type checks, tests, fitness functions.
• Inferential controls are semantic, slower, and probabilistic — AI review, LLM-as-judge.

A healthy harness balances all four: feedforward-only agents never learn whether the rules worked; feedback-only agents repeat the same mistakes. The catalog maps onto the lens as follows.

Pattern	Direction	Execution	Regulates
Codified Rules / Centralized Rules	Feedforward	—	Conventions
Spec-Driven Development	Feedforward	—	Behaviour
Planned Implementation	Feedforward	—	Approach
Custom Commands	Feedforward	—	Workflow
Agent Observability	Feedforward + Feedback	Computational + Inferential	Architecture fitness
Guided Refactoring	Feedback	Computational + Inferential	Maintainability
Adversarial Evaluator	Feedback	Inferential	Behaviour
Error Resolution	Feedback	Computational	Runtime
Agent Hooks	Feedforward + Feedback	Computational	Workflow boundaries
Bounded Autonomy	Feedforward + Feedback	Computational	Autonomous loops

Two principles from the source are worth stating directly:

• Keep Quality Left — run cheap, fast controls early (linters, basic review pre-commit) and reserve expensive ones (mutation testing, deep AI review) for later, so issues are caught where they cost least.
• Steer, don't automate — when the agent repeats a mistake, improve the harness (the guides and sensors), not just the prompt. The human's job is to iterate on the harness.

Source: Birgitta Böckeler, "Harness Engineering", martinfowler.com.

Loop Engineering Lens

Most of this catalog treats a single AI task as the unit of work: write a prompt, get an output, review it. The Loop Engineering Lens zooms out. When you remove a human from the inner loop and let an agent iterate — read tool output, act, re-check, repeat — the loop becomes the thing you design, bound, and verify, not the task. Like the Harness Engineering Lens, this is a lens over the catalog, not a pattern to adopt. The two are complementary: Harness Engineering asks how good the controls around an agent are (the quality of its guides and sensors); Loop Engineering asks how much autonomy that control quality earns you, and how to bound the blast radius once no human inspects each iteration. Better verification reach buys more autonomy; weak verification caps it — no matter how capable the model.

Three principles set the lens's dimensions:

• No executable done-check, no loop — gate before you start. If "done" isn't a state a command can check (exit 0 or 1), and failure isn't cheaply reversible, run it interactively instead of looping.
• The test arbitrates, not the model — one task per loop, deterministic verification, and the agent never certifies its own work. Producer ≠ grader: the thing that writes the code is never the thing that decides it's correct.
• Your verification reach sets the autonomy ceiling — bound the loop with turn, spend, and stall/divergence limits; keep state in git; let humans own the upstream policy and the downstream merge.

Principle	What the loop must have	Catalog patterns that satisfy it
No executable done-check, no loop	An observable goal, acceptance criteria written first, and cheap reversal	Spec-Driven Development, Planned Implementation, Agent Observability; reversible failure via Parallel Agents worktrees
The test arbitrates, not the model	Tight scope, an independent verifier, and checks wired to fire on every change	Atomic Decomposition, Adversarial Evaluator, Test Promotion, Agent Hooks, Autonomous Acceptance
Verification reach sets the autonomy ceiling	Hard bounds, state in git, and human-owned edges	Bounded Autonomy, Agent Memory, Long-Running Orchestration, Centralized Rules, Handoff Protocols

The Bounded Autonomy pattern supplies the control layer that caps turns, spend, and time, detects stalls and divergence, and captures an in-loop diagnostic trail.

Two principles from the source are worth stating directly:

• The unit of work is the loop, not the task — design, bound, and verify the loop as a whole. A single task is just one iteration of it; optimizing the task while leaving the loop unbounded is how runaway cost and silent drift happen.
• One writer per resource — when loops fan out, canonicalize work-item keys before grouping so two agents never write the same file. Parallel loops corrupt state at the seams (collisions over a shared resource), not because any individual agent reasoned badly.

The detailed, tool-specific field checklist for gating, scoping, and bounding loops lives at Loop Engineering Checklist.

Source: Synthesis of the "verification reach sets the autonomy ceiling" idea with field practice for running autonomous coding loops; see the companion Loop Engineering Checklist for the operational form. Conceptually complementary to the Harness Engineering Lens above, which addresses the quality of the controls this lens treats as the autonomy-setting constraint.

Lifecycle Lens

Most of this catalog reads like a menu: pick the patterns you need. The Lifecycle Lens instead orders them along one feature's path from problem to production, so you can see which pattern does the work at each stage and where the handoffs happen. Like the Harness Engineering Lens and Loop Engineering Lens, this is a lens over the catalog, not a pattern to adopt. The adoptable discipline — run the stages in order, don't skip ahead to code — lives in the Developer Lifecycle pattern; this lens is the map of which patterns carry each stage.

Stage	What it produces	Catalog patterns
1. Problem definition	A scoped problem statement and a readiness check	Agent Readiness
2-3. Plan & requirements	Architecture, tasks, and API specs	Planned Implementation, Issue Generation
4-5. Specifications & tests	Acceptance criteria written before any code	Spec-Driven Development
6. Implementation	Working code in small, verifiable increments	Atomic Decomposition, Incremental Generation
7. Testing & review	Test results, security scan, independent review	Agent Observability, Adversarial Evaluator
8. Deployment	A shipped change	Custom Commands, Agent Hooks
9. Monitoring & correction	Runtime signals and human-approved fixes	Agent Observability, Drift Remediation, Error Resolution

Read top to bottom it is a feedforward chain: each stage's output is the next stage's input. The catalog's three categories (Foundation -> Development -> Operations) are the same arc at coarser grain; this lens is the per-feature zoom of it.

Source: The nine-stage workflow from the Developer Lifecycle pattern, generalized into a mapping over the catalog. See examples/developer-lifecycle/ for a runnable end-to-end implementation.

Pattern Dependencies & Implementation Order

Important: These phases represent a learning progression for teams new to AI development, not a waterfall approach. Teams with existing DevOps/security expertise should implement patterns continuously across all phases from day one, following a "continuous everything" model.

graph TD
    subgraph "Phase 1: Foundation (Weeks 1-2)"
        A[Agent Readiness] --> B[Codified Rules]
        B --> C[Security Sandbox]
        C --> D[Developer Lifecycle]
        A --> E[Issue Generation]
        D --> F[Tool Integration]
    end

    subgraph "Phase 2: Development (Weeks 3-4)"
        D --> G[Spec-Driven Development]
        H[Planned Implementation]
        H --> I[Incremental Generation]
        I --> J[Adversarial Evaluator]
        Q[Agent Hooks]
        R[Custom Commands]
        S[Progressive Disclosure]
        U[Image Spec]
        I --> K[Atomic Decomposition]
        K --> L[Parallel Agents]
        D --> O[Agent Observability]
        B --> GR[Guided Refactoring]
        F --> MR[Model Routing]
        F --> RS[Code Research]
        L --> BA[Bounded Autonomy]
    end

    subgraph "Phase 3: Operations (Weeks 5-6)"
        C --> M[Policy Generation]
        M --> EV[Evidence Automation]
        B --> T[Centralized Rules]
        O --> DR[Drift Remediation]
        O --> GC[Guided Chaos]
        GR --> DF[Debt Forecasting]
    end

    B --> Q
    C --> Q
    Q --> R
    G --> R
    B --> S
    R --> S
    B --> T
    S --> T
    G --> U
    I --> U

Continuous Implementation Note: Security patterns (Security Sandbox, AI Security & Compliance) and deployment patterns should be implemented continuously throughout development, not delayed until specific phases. The dependencies shown represent learning prerequisites, not deployment gates.

Complete Pattern Reference

Pattern	Maturity	Category	Type	Description	Dependencies
Foundation		Foundation		Team readiness and basic AI integration infrastructure
Agent Readiness	Beginner	Foundation	Foundation	Evaluate codebase and team readiness for AI integration	None
Codified Rules	Beginner	Foundation	Foundation	Version and maintain AI coding standards as explicit configuration files	Agent Readiness
Security Sandbox	Beginner	Foundation	Foundation	Run AI tools in isolated environments without access to secrets or sensitive data	Codified Rules
Developer Lifecycle	Intermediate	Foundation	Workflow	Take one feature from problem to production through a staged, plan-first discipline	Codified Rules, Security Sandbox
Tool Integration	Intermediate	Foundation	Foundation	Connect AI systems to external data, APIs, and tools	Security Sandbox, Developer Lifecycle
Issue Generation	Intermediate	Foundation	Foundation	Generate deployable work items sized under one AI-assisted hour, with acceptance criteria and dependencies	Agent Readiness
Development		Development		Daily coding workflows and tactical controls
Spec-Driven Development	Intermediate	Development	Development	Guide code generation with executable specifications and acceptance criteria	Developer Lifecycle
Planned Implementation	Beginner	Development	Development	Interview, constrain, and plan before writing code	None
Incremental Generation	Beginner	Development	Development	Build complex features through small, deployable iterations	Planned Implementation
Agent Memory	Intermediate	Development	Development	Preserve useful context and decisions across sessions	Codified Rules
Agent Hooks	Intermediate	Development	Development	Run commands and policy checks at assistant lifecycle hooks	Codified Rules, Security Sandbox
Custom Commands	Intermediate	Development	Development	Encode repeatable domain workflows in assistant commands	Agent Hooks, Spec-Driven Development
Progressive Disclosure	Intermediate	Development	Development	Load only the task-specific rules needed for the current work	Codified Rules, Agent Memory
Atomic Decomposition	Intermediate	Development	Development	Split complex work into independently implementable agent tasks	Incremental Generation
Guided Refactoring	Intermediate	Development	Development	Improve code against measurable quality rules while preserving behavior	Codified Rules
Agent Observability	Intermediate	Development	Development	Capture traces, tool events, evaluations, and runtime context for diagnosis and improvement	Developer Lifecycle
Image Spec	Intermediate	Development	Development	Translate screenshots and design mockups into UI code with visual feedback	Spec-Driven Development, Incremental Generation
Adversarial Evaluator	Intermediate	Development	Development	Separate generation from independent adversarial evaluation	Incremental Generation
Parallel Agents	Advanced	Development	Development	Run agents concurrently on isolated tasks or environments	Atomic Decomposition
Error Resolution	Intermediate	Development	Development	Diagnose failures and apply proposed fixes only after human review and deterministic validation	Developer Lifecycle, Agent Observability
Model Routing	Advanced	Development	Development	Match task requirements to model capability, context, latency, and cost	Tool Integration
Code Research	Intermediate	Development	Workflow	Answer technical questions with isolated executable experiments	Agent Memory, Tool Integration
Bounded Autonomy	Advanced	Development	Workflow	Bound agent loops by turns, spend, time, stalls, and verification reach	Parallel Agents, Agent Observability
Security & Compliance		Operations		Policy, evidence, and organization-wide controls
Policy Generation	Advanced	Operations	Operations	Generate validated Cedar, Rego, OPA, or Gatekeeper policy-as-code	Security Sandbox
Evidence Automation	Advanced	Operations	Operations	Continuously collect dated, audit-ready control evidence	Policy Generation, Agent Observability
Centralized Rules	Advanced	Operations	Operations	Synchronize organization-wide AI instructions from a central source	Codified Rules, Progressive Disclosure
Deployment Automation		Operations		Infrastructure correction and controlled change
Drift Remediation	Advanced	Operations	Operations	Detect declared-state drift and generate reviewable corrective patches	Agent Observability, Bounded Autonomy
Monitoring & Maintenance		Operations		Reliability experiments and maintainability forecasting
Debt Forecasting	Intermediate	Operations	Operations	Forecast maintenance burden from code and repository trends	Guided Refactoring, Tool Integration
Guided Chaos	Advanced	Operations	Operations	Generate hypothesis-driven chaos experiments with explicit safety controls	Agent Observability, Bounded Autonomy

---

Pattern Maturity Levels

Patterns are classified by implementation complexity and prerequisite knowledge:

Beginner: Basic AI tool usage with minimal setup required

• Prerequisites: Basic programming skills, access to AI tools
• Complexity: Single tool usage, straightforward prompts
• Examples: Simple code generation, basic constraint setting

Intermediate: Multi-tool coordination and process integration

• Prerequisites: Development workflow experience, team coordination
• Complexity: Multiple tools, orchestration patterns, quality gates
• Examples: Testing strategies, parallel workflows, choice generation

Advanced: Complex systems with enterprise concerns

• Prerequisites: Architecture experience, security/compliance knowledge
• Complexity: Multi-agent systems, advanced safety, compliance automation
• Examples: Enterprise security, compliance automation, chaos engineering

Task Sizing Framework

The patterns use different task sizing approaches based on their purpose and context:

graph TD
    A[Feature Request] --> B[Issue Generation]
    B --> C[Sub-1-Hour Work Items]
    C --> D{Parallel Implementation?}
    D -->|Yes| E[Atomic Decomposition]
    D -->|No| F[Incremental Generation]
    E --> G[1-2 Hour Atomic Tasks]
    F --> H[Daily Deployment Cycles]

    G --> I[Parallel Agent Execution]
    H --> J[Sequential Enhancement]
    C --> K[Standard Kanban Flow]

Task Sizing Hierarchy:

• Issue Generation (<1 hour with AI assistance): Small, deployable work items for continuous flow and rapid feedback
• Atomic Decomposition (1-2 hours): Ultra-small tasks for parallel agent execution without conflicts
• Incremental Generation (Daily cycles): Deployment-focused iterations that may contain multiple work items

When to Use Each Approach:

• Use Issue Generation for standard team development with human developers
• Use Atomic Decomposition when implementing with parallel AI agents
• Use Incremental Generation when prioritizing rapid market feedback over task granularity

Pattern Differentiation:

• Issue Generation: Creates small, deployable work items (<1 hour with AI assistance) for human team workflows
• Atomic Decomposition: Creates ultra-small tasks (1-2 hours) for parallel AI agents
• Incremental Generation: Creates deployment cycles (daily) focused on user feedback

Pattern Selection Decision Framework

Choose the right patterns based on your team's context, project requirements, and AI development maturity:

Decision Tree

graph TD
    A[Starting AI Development] --> B{Team AI Experience?}
    B -->|New to AI| C[Start with Foundation Patterns]
    B -->|Some Experience| D[Focus on Development Patterns]
    B -->|Advanced| E[Implement Operations Patterns]

    C --> F[Agent Readiness]
    F --> G[Codified Rules]
    G --> H[Security Sandbox]
    H --> I{Need Structured Development?}
    I -->|Yes| J[Developer Lifecycle]
    I -->|No| K[Planned Implementation]
    K --> L[Incremental Generation]

    D --> M{Multiple Developers/Agents?}
    M -->|Yes| N[Parallel Agents]
    M -->|No| O[Spec-Driven Development]
    N --> P[Atomic Decomposition]

    E --> R{Enterprise Requirements?}
    R -->|Compliance| S[Policy Generation]
    R -->|Scale| T[Centralized Rules]
    R -->|Quality| U[Debt Forecasting]

Context-Based Pattern Selection

For New Teams (First 2 weeks):

1. Agent Readiness - Evaluate current state
2. Codified Rules - Establish consistent standards
3. Security Sandbox - Ensure safe experimentation
4. Planned Implementation - Learn structured planning approaches
5. Incremental Generation - Start with simple iterations

For Development Teams (Weeks 3-8):

1. Developer Lifecycle - Structured development process
2. Spec-Driven Development - Quality-focused development
3. Issue Generation - Organized work breakdown
4. Testing Orchestration - Quality assurance

For Parallel Implementation:

1. Atomic Decomposition - Ultra-small independent tasks
2. Workflow Orchestration - Agent coordination
3. Review Automation - Automated integration
4. Security Sandbox - Enhanced with parallel safety

For Enterprise/Production (Month 2+):

1. Policy Generation - Compliance automation
2. Evidence Automation - Continuous, audit-ready control evidence
3. Centralized Rules - Organization-wide AI standards
4. Debt Forecasting - Proactive maintenance

Project Type Recommendations

MVP/Startup Projects:

• Primary: Incremental Generation, Planned Implementation
• Secondary: Security Sandbox, Adversarial Evaluator
• Avoid: Complex orchestration patterns until scale demands

Enterprise Applications:

• Primary: Developer Lifecycle, Policy Generation
• Secondary: Spec-Driven Development, Evidence Automation
• Essential: All foundation patterns before development patterns

Research/Experimental Projects:

• Primary: Code Research, Adversarial Evaluator
• Secondary: Agent Memory, Model Routing
• Focus: Learning and exploration over production readiness

High-Scale Production:

• Primary: Parallel Agents, Agent Observability
• Secondary: Guided Chaos, Incident Automation
• Critical: All security and monitoring patterns

Team Size Considerations

Solo Teams:

• Focus on Incremental Generation and Adversarial Evaluator
• Add Agent Observability for debugging
• Skip parallel orchestration patterns

Two-Pizza Teams (small, autonomous teams):

• Implement Issue Generation for coordination
• Use Spec-Driven Development for quality
• Consider Tool Integration for role clarity
• Full Developer Lifecycle implementation
• Parallel Agents for complex features
• Spec-Driven Development for quality gates and traceability

Multi Two-Pizza Team Organizations:

• Atomic Decomposition for parallel work across teams
• Spec-Driven Development for coordination at scale via shared specifications
• All Operations Patterns for organizational management

Technology Stack Considerations

Cloud-Native Applications:

• Emphasize Policy Generation and Evidence Automation
• Implement Drift Remediation for infrastructure
• Use Pipeline Synthesis for safe delivery workflows

On-Premise Systems:

• Focus on Security Sandbox with network isolation
• Implement Agent Memory for institutional knowledge
• Use Debt Forecasting for maintenance planning

Microservices Architecture:

• Parallel Agents for service coordination
• Agent Observability across service boundaries
• Agent Hooks for deterministic cross-service policy checks

Monolithic Applications:

• Incremental Generation for gradual modernization
• Guided Refactoring for code quality improvement
• Planned Implementation to prevent over-engineering through its constraint phase

---

Foundation Patterns

Foundation patterns establish the essential infrastructure and team readiness required for successful AI-assisted development. These patterns must be implemented first as they enable all subsequent patterns.

Agent Readiness

Maturity: Beginner Description: Systematic evaluation of codebase and team readiness for AI-assisted development before implementing AI patterns.

Related Patterns: Codified Rules, Issue Generation

Source: Factory.ai, "Agent Readiness"; Kodus, "agent-readiness"; Guillaume Moigneu, "Making coding agents reliable", February 17, 2026

Industry tooling commonly calls this practice agent readiness (Factory.ai, Kodus) or an AI readiness assessment (Microsoft).

📋 Quick start: Use the free AI Development Readiness Scorecard to score your team against this framework in about 10 minutes and get a tailored pattern adoption sequence.

Assessment Framework

graph TD
    A[Codebase Assessment] --> B[Team Assessment]
    B --> C[Infrastructure Assessment]
    C --> D[Readiness Score]
    D --> E[Implementation Plan]

Codebase Readiness Checklist

## Code Quality Prerequisites
□ Consistent code formatting and style guide
□ Comprehensive test coverage (>80% for critical paths)
□ Clear separation of concerns and modular architecture
□ Documented APIs and interfaces
□ Version-controlled configuration and secrets management

## Documentation Standards
□ README with setup and development instructions
□ API documentation (OpenAPI/Swagger)
□ Architecture decision records (ADRs)
□ Coding standards and conventions documented
□ Deployment and operational procedures

Anti-pattern: Premature Adoption

Starting AI adoption without proper assessment leads to inconsistent practices, security vulnerabilities, and team frustration.

---

Codified Rules

Maturity: Beginner Description: Version and maintain AI coding standards as explicit configuration files that persist across sessions and team members.

Related Patterns: Agent Readiness, Agent Memory, Progressive Disclosure, Agent Hooks, Custom Commands, Centralized Rules

See also: Harness Engineering Lens

Source: "AGENTS.md" open format specification (OpenAI, Google Jules, Cursor, Factory); Cursor, "Rules" documentation

Industry tooling implements this pattern as AGENTS.md (open format stewarded under the Linux Foundation), Rules (Cursor), CLAUDE.md memory (Anthropic Claude Code), and repository custom instructions (GitHub Copilot).

Standardized Project Structure

project/
├── .ai/                          # AI configuration directory
│   ├── rules/                    # Modular rule sets
│   │   ├── security.md          # Security standards
│   │   ├── testing.md           # Testing requirements
│   │   ├── style.md             # Code style guide
│   │   └── architecture.md      # Architectural patterns
│   ├── prompts/                 # Reusable prompt templates
│   │   ├── implementation.md    # Implementation prompts
│   │   ├── review.md            # Code review prompts
│   │   └── testing.md           # Test generation prompts
│   └── knowledge/               # Captured patterns and gotchas
│       ├── successful.md        # Proven successful patterns
│       └── failures.md          # Known failure patterns
├── .cursorrules                 # Cursor IDE configuration
├── CLAUDE.md                    # Claude Code session context
└── .windsurf/                   # Windsurf configuration
    └── rules.md

Complete Example: See examples/codified-rules/ for:

• Comprehensive development workflow rules and standards
• Pipeline automation and CI/CD rules
• Code quality standards and enforcement guidelines
• Claude Code configuration for rules-as-code implementation

Anti-pattern: Broken Context

Each developer maintains their own prompts and preferences, leading to inconsistent code across the team.

---

Security Sandbox

Maturity: Beginner Description: Run AI tools in isolated environments without access to secrets or sensitive data to prevent credential leaks and maintain security compliance.

Related Patterns: Policy Generation, Codified Rules, Agent Hooks

Source: Anthropic, "sandbox-runtime"; Anthropic, "Sandboxing" (Claude Code documentation)

Core Security Implementation

Claude Code Users: Use the /sandbox command to instantly create isolated environments without manual Docker configuration:

/sandbox
# Creates a secure, isolated environment with:
# - No access to credentials or sensitive files
# - Restricted network access
# - Controlled file system permissions

Docker-Based Implementation: For custom isolation or multi-agent scenarios:

# Basic AI isolation with complete network isolation
services:
  ai-development:
    network_mode: none                    # Zero network access
    cap_drop: [ALL]                       # No system privileges
    volumes:
      - ./src:/workspace/src:ro           # Read-only source code
      # DO NOT mount ~/.aws, .env, secrets/, etc.

Complete Example: See examples/security-sandbox/ for:

• Complete Docker isolation configurations for single and multi-agent setups
• Resource locking and emergency shutdown procedures
• Security monitoring and violation detection
• Multi-agent coordination with conflict resolution

Production Implementations

Modern AI development platforms provide enterprise-grade implementations of these security controls:

Cloud-Based Sandboxes:

• Claude Code for the web: Sandboxed AI coding with isolated execution environments
• Google Antigravity: Google's agentic development platform; manages multiple local agents in parallel across workspaces
• OpenAI Codex: Cloud-based AI coding with secure execution environments
• Google Vertex AI Agent Engine Code Execution: Managed secure runtimes for AI agent code execution
• GitHub Codespaces: Isolated cloud development VMs with configurable security policies
• E2B: Specialized AI agent sandboxes with microVM isolation

Cloud & Self-Hosted Options:

• Daytona: microVM-based isolation for development environments (available as cloud service or self-hosted)
• Coder: Cloud development environments with enterprise security controls (available as cloud service or self-hosted)

Anti-pattern: Unrestricted Access

Allowing AI tools full system access risks credential leaks, data breaches, and security compliance violations.

Anti-pattern: Conflicting Workspaces

Allowing multiple parallel agents to write to the same directories creates race conditions, file conflicts, and unpredictable behavior that can corrupt the development environment.

---

Developer Lifecycle

Maturity: Intermediate Description: A staged, plan-first discipline for taking a single feature from problem to production with AI assistance.

Related Patterns: Codified Rules, Security Sandbox, Planned Implementation, Spec-Driven Development, Atomic Decomposition, Agent Observability

See also: Lifecycle Lens

Source: GitHub, "Spec Kit"; AWS DevOps & Developer Productivity Blog, "AI-Driven Development Life Cycle: Reimagining Software Engineering", July 31, 2025

This pattern is the per-feature discipline: plan before you generate, and stop retrying a failing approach after a few tries instead of looping on it. For how each stage maps onto the rest of the catalog, see the Lifecycle Lens.

Workflow Interaction Sequence

sequenceDiagram
    participant D as Developer
    participant AI as AI Assistant
    participant S as System/CI
    participant T as Tests
    participant M as Monitoring
    
    Note over D,M: Stage 1-3: Problem → Plan → Requirements
    D->>AI: Problem Definition (e.g., JWT Authentication)
    AI->>D: Technical Architecture Plan
    D->>AI: Requirements Clarification
    AI->>D: API Specs + Kanban Tasks + Security Requirements
    
    Note over D,M: Stage 4-5: Issues → Specifications
    D->>AI: Generate Executable Tests
    AI->>T: Gherkin Scenarios + API Tests + Security Tests
    T->>D: Test Suite Ready (Performance Criteria: <200ms)
    
    Note over D,M: Stage 6: Implementation
    D->>AI: Implement Following Specifications
    AI->>S: Code + Tests + Error Handling + Logging
    S->>D: Implementation Results
    
    Note over D,M: Stage 7-9: Testing → Deployment → Monitoring
    D->>S: Run All Tests
    S->>D: Test Results + Security Scan + Performance Benchmark
    alt Tests Pass
        S->>S: Deploy to Production
        S->>M: Setup Monitoring Alerts
        M->>D: Deployment Complete + Monitoring Active
    else Tests Fail
        S->>D: Failure Report
        D->>AI: Fix Issues
        AI->>S: Updated Implementation
    end
    
    Note over D,M: Continuous Monitoring
    M->>D: Performance Alerts + Security Events

Complete Example: See examples/developer-lifecycle/ for full 9-stage workflow scripts, detailed prompts for each stage, enhanced implementation techniques (Five-Try Rule, markdown iteration, function decomposition), and integration with CI/CD pipelines.

Anti-pattern: Unplanned Development

Jumping straight to coding with AI without proper planning, requirements, or testing strategy. Also avoid continuing with the same AI approach after 3-4 failures without decomposing the problem or changing strategy.

---

Tool Integration

Maturity: Intermediate Description: Connect AI systems to external data sources, APIs, and tools for enhanced capabilities beyond prompt-only interactions.

Related Patterns: Security Sandbox, Developer Lifecycle, Agent Observability

Source: Anthropic, "Introducing the Model Context Protocol", November 25, 2024; Model Context Protocol, "modelcontextprotocol/servers" reference servers

The industry implements this pattern as tool use (Anthropic), function calling (OpenAI), and the Model Context Protocol (MCP).

Core Concept

Modern AI development requires more than chat-based interactions. AI systems become significantly more capable when connected to real-world data sources and tools. This pattern demonstrates the architectural shift from isolated prompt-only AI to tool-augmented AI systems.

Implementation Overview

# Core tool-augmented AI system with security controls
class ToolAugmentedAI:
    def __init__(self, config_path: str = ".ai/tools.json"):
        self.available_tools = {
            "database_query": self._query_database,     # Read-only SQL queries
            "file_operations": self._file_operations,   # Controlled file access
            "api_requests": self._api_requests,         # Allowlisted HTTP requests
            "system_info": self._system_info            # Safe system information
        }
    
    def execute_with_tools(self, ai_request: str, tool_calls: list) -> dict:
        """Execute AI request with secure tool access"""
        # Process tool calls with security validation
        # Return structured results with error handling

Tool Categories & Security

• Database Access: Read-only queries with operation whitelisting (SELECT, WITH only)
• File Operations: Path-restricted read/write within configured directories
• API Integration: HTTP requests limited to allowlisted domains with timeouts
• System Information: Safe environment data without sensitive details

Configuration Example

{
  "allowed_apis": ["api.github.com", "api.openweathermap.org"],
  "file_access_paths": ["./data/", "./logs/", "./generated/"],
  "max_query_results": 100,
  "security": {
    "read_only_database": true,
    "api_rate_limits": true,
    "file_size_limits": "10MB"
  }
}

Model Context Protocol (MCP) Integration

This pattern can be implemented using Anthropic's Model Context Protocol (MCP) for standardized tool integration across AI systems:

{
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "./data"]
    },
    "sqlite": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-sqlite", "app_data.db"]
    }
  }
}

What Tool Integration Enables

• Real-time data access: AI queries current database state, not training data
• File system interaction: Read logs, write generated code, manage project files
• API integration: Fetch live data from external services and APIs
• System awareness: Access to current environment state and configuration
• Enhanced context: AI decisions based on actual system state, not assumptions

Complete Example: See examples/tool-integration/ for:

• Full Python implementation with security controls
• Configuration examples and MCP integration
• Usage patterns and deployment guidelines
• Integration with Security Sandbox

Anti-pattern: Disconnected Prompting

Attempting to solve complex data analysis, system integration, or real-time problems using only natural language prompts without providing AI access to actual data sources, APIs, or system tools. This leads to hallucinated responses, outdated information, and inability to interact with real systems.

---

Issue Generation

Maturity: Intermediate Description: Generate small, deployable work items (<1 hour with AI assistance) from requirements using AI to ensure continuous delivery with clear acceptance criteria and dependency tracking.

Methodology Note: This pattern aligns well with Kanban principles (continuous flow, small batches) but works with any development methodology including Scrum, Scrumban, or ad-hoc workflows.

Related Patterns: Agent Readiness, Spec-Driven Development

Source: GitHub Docs, "Using GitHub Copilot to create issues"; Eyal Toledano, "Task Master"

Issue Generation Framework

graph TD
    A[Requirements Document] --> B[AI Feature Analysis]
    B --> C[Work Item Splitting]
    C --> D{<1 hour?}
    D -->|No| E[Split Further]
    E --> C
    D -->|Yes| F[Story Generation]
    F --> G[Acceptance Criteria]
    G --> H[Cycle Time Target]
    H --> I[Dependency Mapping]
    I --> J[Work Item Creation]

Core Principles

• Small Batch Sizing: Each work item sized to complete in under an hour with AI assistance, enabling continuous delivery and rapid feedback
• AI-Assisted Decomposition: Use AI to break down requirements into implementable tasks
• Traceability Integration: Connect issues to implementation files and CI workflows
• Dependency Mapping: Establish clear relationships between work items and epics
• Acceptance-Driven: Each task includes specific, testable acceptance criteria

Work Item Attributes

Generated issues must include:

• Title: Specific, actionable description of the work
• Cycle Time Target: Estimated completion time (<1 hour with AI assistance)
• Acceptance Criteria: Testable conditions for completion
• File Scope: Which files will be added, updated, or removed
• CI Requirements: Test coverage, pipeline steps, quality gates
• Dependencies: Blocking and enabling relationships with other issues

Epic Relationship Management

• Bidirectional Linking: Parent-child references maintained automatically
• Progress Tracking: Epic completion calculated from subissue status
• Dependency Validation: Automated checking for circular dependencies
• Status Propagation: Subissue changes update epic progress

Complete Example: See examples/issue-generation/ for detailed AI prompts, epic breakdown workflows, CI integration patterns, and traceability implementations. For AI-first workflows, see Beads guide - a git-native issue tracker with CLI access and persistent agent memory.

"Small, frequent deliveries expose issues early and keep teams aligned." – Agile Alliance

Kanban Context: This pattern embodies Kanban principles of continuous flow and small batch sizes. If using Kanban: "If a task takes more than one day, split it." (Kanban Guide, Lean Kanban University). However, the pattern works equally well with Scrum sprints, continuous delivery, or any methodology that values incremental progress.

Anti-pattern: Under-Specified Issues

Creating generic tasks without specific acceptance criteria, proper sizing, or clear dependencies leads to scope creep and estimation errors.

Anti-pattern: Broken Integration

Creating issues without CI workflow integration, file tracking, or traceability requirements leads to disconnected development cycles and poor visibility into implementation progress.

Anti-pattern Examples:

❌ "Fix the login page"
❌ "Make the dashboard better"
❌ "Add some tests"
❌ "AUTH-002: Implement password validation" (no file tracking or CI requirements)

✅ "Add OAuth 2.0 token validation endpoint (<1 hour with AI)"
✅ "Implement dashboard metric WebSocket connection (45 minutes)"
✅ "Write unit tests for user service login method (30 minutes)"
✅ "AUTH-002: Password validation service with CI integration"
   - Files: src/auth/validators.py, tests/test_validators.py
   - Coverage: 95%, unit + integration tests
   - CI: lint, test, security-scan must pass
   - AI-assisted: Use AI for implementation and test generation

---

Development Patterns

Development patterns provide tactical approaches for day-to-day AI-assisted coding workflows, focusing on quality, maintainability, and team collaboration.

Spec-Driven Development

Maturity: Intermediate Description: Use executable specifications to guide AI code generation with clear acceptance criteria before implementation.

Core Principle: Precision Enables Productivity

SpecDriven AI combines three key elements:

• Machine-readable specifications with unique identifiers and authority levels
• Rigorous Test-Driven Development with coverage tracking and automated validation
• AI-powered implementation with persistent context through structured specifications

For large systems, keep the specification reviewable by splitting it into bounded domain fragments with shared global invariants. Within each fragment, describe successful behavior, explicit rejection behavior, and safe degraded behavior, then connect every normative outcome to executable validation. This preserves traceability without turning one document into an unreviewable, application-wide prompt.

Key Innovation: Authority Level System

Specifications use authority levels to resolve conflicts and establish precedence:

• authority=system: Core business logic and security requirements (highest precedence)
• authority=platform: Infrastructure and technical architecture decisions
• authority=feature: User interface and experience requirements (lowest precedence)

When requirements conflict, higher authority levels take precedence, enabling clear decision-making for AI implementation.

Related Patterns: Developer Lifecycle, Tool Integration, Custom Commands, Image Spec, Testing Orchestration, Agent Observability

See also: Harness Engineering Lens

Source: GitHub, "Spec Kit"; Birgitta Böckeler, "Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl", October 15, 2025

SpecDriven AI Workflow

graph TD
    A[Machine-Readable Specifications<br/>with Authority Levels] --> B[Coverage Tracking<br/>& Validation]
    B --> C[AI Implementation<br/>with Ephemeral Prompts]
    C --> D[Automated Testing<br/>& Compliance Check]
    D --> E{Specs Pass?}
    E -->|No| F[Refine Prompts<br/>Not Specs]
    F --> C
    E -->|Yes| G[Coverage Report<br/>& Deployment]
    G --> H[Specification Persistence<br/>for Regression]
    
    style A fill:#e1f5e1
    style B fill:#e1f5e1
    style H fill:#e1f5e1
    style C fill:#ffe6e6
    style F fill:#ffe6e6

Core Implementation

Machine-Readable Specification with Authority Levels

# IAM Policy Generator Specification {#iam_policy_gen}

## CLI Requirements {#cli_requirements authority=system}
The system MUST provide a command-line interface that:
- Accepts policy type via `--policy-type` flag
- Validates input parameters against AWS IAM constraints
- Generates syntactically correct IAM policy JSON [^test_iam_syntax]
- Returns exit code 0 for success, 1 for validation errors

## Input Validation {#input_validation authority=platform}  
The system MUST:
- Reject invalid AWS service names with clear error messages
- Validate resource ARN format before policy generation
- Implement rate limiting for API calls [^test_rate_limit]

[^test_iam_syntax]: tests/test_iam_policy_syntax.py
[^test_rate_limit]: tests/test_rate_limiting.py

Automated Coverage Tracking

# Run specification compliance validation
pytest --cov=src --cov-report=html --spec-coverage
python spec_validator.py --check-coverage --authority-conflicts

# Output shows specification coverage
# Specification Coverage Report:
# ✅ cli_requirements: 100% (3/3 tests linked)
# ✅ input_validation: 85% (6/7 tests linked) 
# ⚠️  Missing test: [^test_malformed_arn] in line 23

Tooling Integration

# Pre-commit hook validates specification compliance
# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: spec-coverage
        name: Specification Coverage Check
        entry: python spec_validator.py --check-coverage
        language: python
        pass_filenames: false

# Git workflow with specification traceability  
git commit -m "feat: implement rate limiting [spec:rl2c]
  
Implements rate limiting requirement from input_validation
section. Closes specification anchor #failed_auth.

Coverage: 94% (31/33 spec requirements covered)"

Key Benefits

• Authority-based conflict resolution prevents requirement ambiguity
• Automated coverage tracking ensures no specifications are missed
• AI tool independence through persistent, machine-readable requirements
• Precise traceability from specification anchors to test implementations
• Living documentation that evolves with the system

Automated Traceability

Specification anchors ({#cli_requirements}) and test footnotes ([^test_iam_syntax]) are the link layer that ties requirements to tests to code to docs. Maintain those links automatically on every change instead of in a spreadsheet:

# After each commit, validate anchor coverage and flag drift
git diff --name-only HEAD~1 | while read file; do
    ai "For $file: confirm referenced spec anchors still exist, propose new
        anchor links for any uncovered behavior, and emit an impact list of
        which downstream tests and docs need updating."
done

When a spec section moves or a test is renamed, the same loop surfaces the broken link before it ships. The result is a living traceability graph that stays accurate without manual upkeep — the alternative (traceability in a spreadsheet) is stale within a week.

Anti-pattern: Broken Traceability

Maintaining requirement-to-test links in spreadsheets or manual documentation that becomes stale and inaccurate within days of being written.

Complete Example: See examples/spec-driven-development/ for:

• Complete IAM Policy Generator implementation
• spec_validator.py tool for automated compliance checking
• Pre-commit hooks and Git workflow integration
• Full specification examples with authority levels
• Coverage tracking and reporting