AI Development Patterns
Paul Duvall · article · 2026-10-08 source ↗ Reader 🖥️
Agent Governance (Internal)Intent DebtPolicy-as-CodePull Requests & Async Code ReviewSmall Teams & CompressionSRE & Incident ResponseTeam Harness / Team-Layer Coding-Agent Platforms
Organizations should adopt this catalog's AI-development patterns selectively and in an order diagnosed from their own team size, project type, and technology stack — not uniformly or in catalog order — because the coordination problems a solo developer needs to solve (rapid iteration, tool-matching) are categorically different from, and the patterns designed for them can actively mismatch, what a two-pizza team or a multi-team organization needs (parallel-agent isolation and conflict resolution, cross-team traceability, automated review of agent output at volume).
practical · expository — A GitHub README functioning as a pattern catalog: ~28 named patterns, each following a fixed template (Maturity, Description, Related Patterns, worked example, Anti-pattern), organized by lifecycle phase and complexity. Almost entirely prescriptive how-to content with no argued thesis beyond the organizing framework itself; this extraction focuses on that organizing thesis and the team/org-relevant patterns rather than enumerating all ~28.
Structure
| Part | Role |
|---|---|
| Pattern Organization: three categories (Foundation, Development, Operations) and the explicit 'continuous everything, not waterfall' caveat | framework |
| Pattern Maturity Levels (Beginner/Intermediate/Advanced) and Task Sizing Framework (three distinct, purpose-differentiated granularities) | classification framework |
| Pattern Selection Decision Framework: decision tree, context-based selection by team experience, project type recommendations, team size considerations, tech stack considerations | core prescriptive argument |
| Foundation Patterns (readiness assessment, rules as code, security sandbox, developer lifecycle, human-AI handoff protocol, issue generation) | team-readiness patterns |
| Development Patterns (spec-driven development, testing, progressive enhancement, parallelized agents, context window optimization, knowledge persistence, refactoring, traceability) | daily-practice patterns |
| Operations Patterns (security/compliance, deployment automation, monitoring & maintenance including on-call handoff) | production-governance patterns |
| Anti-Patterns Reference and Implementation Guide (phased rollout, success metrics, contribution guidelines) | conclusion / operationalization |
Key terms
- Continuous everything (model)
The practice, for teams with existing DevOps/security expertise, of implementing security and deployment patterns from day one across all phases simultaneously, rather than following the catalog's Foundation-then-Development-then-Operations phase numbering as a sequential rollout. - Task Sizing Hierarchy
Three distinct, non-competing granularities for breaking down work, each matched to a different purpose: 4-8 hour Kanban work items (AI Issue Generation, for human-team flow), 1-2 hour atomic tasks (Atomic Task Decomposition, for conflict-free parallel AI-agent execution), and daily deployment cycles (Progressive AI Enhancement, for rapid market feedback). - Human-AI Handoff Protocol
An explicit decision framework assigning work to AI-first, AI-with-human-review, human-first, or human-only based on task complexity and criticality, with named transition points (quality check, AI success check) rather than leaving the human/AI division of labor ambiguous. - Knowledge Hoarding (anti-pattern)
Creating extensive AI-prompting knowledge bases that become maintenance burdens rather than accelerators — recognized by knowledge files unused for months, entries too detailed to be referenced, overlapping/conflicting knowledge bases, and knowledge capture taking longer than the development work it was meant to speed up.
Propositions
- explicitThe catalog's three categories (Foundation, Development, Operations) and their numbered phases represent a learning progression for teams new to AI development, not a waterfall deployment sequence; teams with existing DevOps/security expertise should implement patterns from all three categories continuously, from day one.conf: high
- explicitPatterns are classified by a maturity ladder (Beginner, Intermediate, Advanced) tied to prerequisite knowledge and system complexity, so a team's adoption path should be gated by its own experience level, not purely by the catalog's listing order.conf: high
- explicitTask-sizing is purpose-differentiated rather than a single granularity: 4-8 hour Kanban work items suit standard human-team flow, 1-2 hour atomic tasks suit conflict-free parallel AI-agent execution, and daily deployment cycles suit rapid-feedback progressive enhancement — using the wrong granularity for a team's actual context is implicitly discouraged by the catalog's explicit 'when to use each approach' guidance.conf: high
- explicitWhich patterns a team should adopt depends on team size specifically, not just project maturity: solo teams should skip parallel-orchestration patterns entirely, two-pizza teams should add issue generation and the human-AI handoff protocol, and multi-team organizations need atomic task decomposition plus AI-driven traceability specifically to coordinate parallel work across teams.conf: high
- explicitA structured 9-stage AI Developer Lifecycle (problem, plan, requirements, issues, specs, implementation, testing, deployment, monitoring) is positioned as the direct alternative to its named anti-pattern, 'Ad-Hoc AI Development' — jumping straight into AI-assisted coding without proper planning, requirements, or a testing strategy.conf: high
- explicitHuman-AI work handoff should be governed by an explicit decision framework keyed to task complexity and risk (AI-first for low complexity, AI-with-human-review for medium, human-first for high, human-only for critical), because letting AI and humans work the same task simultaneously without clear handoff points causes conflicts, duplicated effort, and inconsistent quality — the catalog's named 'Unclear Boundaries' anti-pattern.conf: highsupportsYour AI agent just blamed the network team. Now what? · p11 — Both propose a graduated, risk-tiered trust/handoff framework rather than a blanket human-or-AI rule — Duvall's complexity-keyed AI-first/review/human-first/human-only ladder for a single task is the same structural move as the blame-network piece's shadow-mode-to-write-access trust-expansion phases for a whole system.
- explicitRunning multiple AI coding agents in parallel requires explicit isolation (containers or git worktrees), a shared-memory mechanism so agents can learn from each other's discoveries, and an automated conflict-detection/merge pipeline; without these, uncoordinated parallel execution produces race conditions, lost work, inconsistent implementations across features, and resource contention.conf: highextendsThe Orchestration Tax is You · p9 — Osmani's rule ('the correct number of parallel agents equals the number you can code-review properly') names the review-capacity ceiling; Duvall's pattern supplies the missing mechanics underneath that ceiling — isolation, shared memory, and automated conflict resolution — needed to run even that bounded number of agents without them colliding.
- explicitSuccessful and failed AI prompts/patterns should be captured as versioned, selective knowledge — only patterns with a high (>80%) success rate, and failures that wasted significant (>30 minute) time — rather than exhaustively documented, because exhaustive capture itself becomes a maintenance burden teams stop maintaining and developers stop trusting, the catalog's named 'Knowledge Hoarding' anti-pattern.conf: highrefinesThe Intent Debt · p22 — Osmani argues 'write down the why — it is becoming the most valuable thing you can leave in the repo'; Duvall's Knowledge Hoarding anti-pattern qualifies this with a selectivity ceiling — capture only high-impact (>80% success) patterns and costly failures — because indiscriminate externalization becomes a new, unmaintained debt of its own.
- explicitParallel-agent output review should itself be automated — detecting file, API-contract, dependency, and naming conflicts across agent workspaces, running quality gates, and auto-merging when gates pass — with human review reserved specifically for cases that fail those automated gates, because relying entirely on human reviewers for parallel-agent output creates a bottleneck and misses systematic integration issues automated tooling catches.conf: highsupportsSpec-Driven Production Grade Development In The Age Of Vibe Coding · p10 — Both independently arrive at the same requirement — a standing, automated reviewer watching every agent-produced change rather than an on-demand human-only process — with Duvall supplying a concrete worked pipeline (conflict detection, quality gates, auto-merge, human-review fallback) for the specific case of parallel-agent output.
- explicitAI tool sophistication should be deliberately matched to task complexity as a cost/performance optimization — 'using Claude for every task is like using a sledgehammer to hang a picture' — rather than defaulting to the single most capable available tool for every task regardless of size.conf: high
- explicitOn-call handoffs between engineers should be generated automatically by combining live incident/alert data with dashboard state into a single AI-written brief posted to a shared channel, replacing handoffs based on chat logs or email threads — the catalog's named 'Fragmented Handoffs' anti-pattern, which it says skips critical context and action items.conf: highextendsThe AI-Native SDLC playbook · p11 — Claxton's Stage 6 describes humans triaging a queue of autonomously-generated incident diagnoses; Duvall's On-Call Handoff Automation supplies a concrete generation mechanism (combining live alerts and dashboard state into one AI-written brief) for exactly the handoff moment between the humans doing that triaging.
- explicitCompliance requirements should be transformed directly into executable, testable policy code (e.g. Cedar/OPA) by AI, keeping the source requirement and the generated policy code directly traceable to each other, rather than hand-translated, because manual policy translation introduces inconsistencies and interpretation errors.conf: high
- explicitSecurity-tool output across multiple scanners should be aggregated and AI-summarized into a single actionable PR comment gated on severity, rather than posting every individual finding, because posting every low-severity finding causes alert fatigue that buries the issues that actually matter.conf: high
- explicitEvery pattern in the catalog follows the same fixed five-part template (Maturity, Description, Related Patterns, worked Examples, Anti-pattern), and practitioners are explicitly invited to contribute new patterns following that template, treating the catalog itself as a living, team-contributed artifact rather than a finished reference.conf: high
- implicitThe catalog assumes that patterns the author found useful in his own practice generalize across teams, project types, and organizations; no individual pattern cites an external case study, a controlled comparison, or an independent practitioner's replication — every worked example is the author's own prescriptive implementation presented as sufficient evidence of the pattern's value.conf: medium
Arguments
Teams should choose which patterns to adopt based on their own size and context rather than adopting the full catalog uniformly or in listed order. strength: medium
Explicit premises:
- Solo teams have no parallel-execution coordination problem to solve, so parallel-orchestration patterns add overhead without a corresponding problem.
- Two-pizza teams need coordination patterns (issue generation, handoff protocol) that a solo developer doesn't, because multiple humans (and agents) are now working the same codebase.
- Multi-team organizations face a distinct problem — cross-team parallel work and traceability at scale — that two-pizza-team patterns don't solve.
Implicit premises:
- Adopting a pattern designed for a larger-scale coordination problem than a team actually has (e.g. atomic task decomposition for a solo developer) imposes process overhead without a matching benefit.
Inferences:
- Pattern adoption should be diagnosed from a team's actual scaling pain, not from the catalog's maturity labels, which measure technical complexity rather than organizational fit.
Running AI agents in parallel safely requires treating agent coordination as its own engineering problem — isolation, shared memory, and automated conflict resolution together — not simply running several AI tools at once. strength: medium
Explicit premises:
- Agents modifying the same files without isolation cause race conditions.
- Agents with no shared memory cannot learn from or build on each other's discoveries.
- Merge conflicts between agent branches require resolution discipline similar to (or exceeding) human merge-conflict discipline, at higher volume.
Implicit premises:
- The concurrency-control problems (isolation, shared state, conflict resolution) that version-control and distributed-systems practice already solved for human developers transfer to AI agents largely unchanged.
Inferences:
- The catalog's prescribed solution (containers or worktrees + a shared JSON memory file + an AI-assisted merge script) is a direct port of existing concurrency-control techniques to agent coordination, rather than a response to something structurally new about AI agents specifically.
Narratives
- A worked example traces a single feature request ('Users need to be able to reset their passwords via email') through the full AI Issue Generation pipeline into Kanban-ready tasks with explicit acceptance criteria and dependencies.
→ Makes concrete how the 4-8 hour task-sizing granularity (P3) is meant to work end to end on a realistic input, rather than describing the pipeline only abstractly. - A worked example shows a Docker Compose and git-worktree setup running three parallel agents (auth, API, tests) against a shared, flock-locked JSON memory file, followed by a bash script that attempts to merge each agent's branch and invokes an AI agent to resolve any detected conflicts automatically.
→ Makes concrete argument A2's claim that agent coordination requires isolation, shared memory, and automated conflict resolution together, by showing the full mechanism rather than only asserting the requirement.
Questions addressed
- ✅ How should a team or organization decide which patterns from this large catalog to actually adopt, and in what order?
Diagnose by team size, project type, and technology stack using the decision tree and context-based selection framework, implementing continuously across categories if the team already has DevOps/security maturity, rather than adopting the full catalog uniformly or in listed order. - ✅ How do you run multiple AI coding agents on the same codebase without them destroying each other's work?
Isolate each agent in its own container or git worktree, give them a shared-memory mechanism, and automate conflict detection and resolution with a human-review fallback for anything the automated gates don't pass. - ✅ Does capturing AI-prompting knowledge as a team asset actually help, or can it become its own burden?
It can become its own burden (named as 'Knowledge Hoarding'); the prescribed fix is selective capture (only >80%-success patterns and costly failures) plus quarterly pruning, though no owner is assigned to that pruning work. - ⭕ Has any individual pattern in this catalog been validated outside the author's own practice?
Not addressed for any of the ~28 patterns — each is presented with the author's own worked example as sufficient evidence of value, with no external case study, controlled comparison, or independent practitioner data cited.
Gaps
- uninformedEvery pattern in the catalog is presented with the author's own prescriptive worked example as its sole evidence; the catalog never cites an external case study, a controlled comparison, or independent practitioner validation for any individual pattern, despite the patterns ranging from simple (constraint-based prompting) to organizationally significant (atomic task decomposition coordinating parallel work across multiple teams).
- incompleteThe 'Parallelized AI Coding Agents' pattern's own worked shared-memory implementation is a single JSON file written under a file lock (flock) — a mechanism that does not obviously scale past a handful of concurrent agents and is never stress-tested or benchmarked in the piece, even though the pattern's stated purpose is to let agent count scale with 'development speed and exploration.'
Read next: Read distributed-systems literature on shared mutable state under concurrent writers, and existing multi-agent coordination/harness-scaling heuristics, for whether a locked flat file remains viable past a small number of agents. - incompleteThe team-size framework (Solo / Two-Pizza / Multi Two-Pizza) treats team size as the organizing variable for pattern adoption but never addresses the transition itself — there is no migration path described from, say, a two-pizza team's Human-AI Handoff Protocol to a multi-team organization's Atomic Task Decomposition, only separate, static recommendations for each size category.
- incompleteThe Knowledge Hoarding anti-pattern correctly diagnoses that exhaustive AI-prompting documentation goes unmaintained, but its prescribed fix ('review and prune knowledge quarterly') assigns that maintenance work to no one in particular — the same ownership-diffusion problem the catalog's own 'Fragmented Handoffs' and 'Alert Fatigue' anti-patterns describe elsewhere, applied here to the knowledge base itself.
Related documents
- The Intent Debt
- The Orchestration Tax is You
- The AI-Native SDLC playbook
- Dropbox Integrates MCP and Dash to Close the Gap Between Security Design and Code Review
- Agentic Code Review
- The Agentic P&L: Beyond the Empire of Headcount
- Your AI agent just blamed the network team. Now what?
- Presentation: Autonomous Data Products for the Autonomous Era: Rethinking Data Architecture for GenAI
- AWS Expands DevOps Agent with AI-Powered Release Management to Validate Code Before Production
- Spec-Driven Production Grade Development In The Age Of Vibe Coding