# ai-development-patterns: a catalogue for teams coding with agents

> ai-development-patterns is a documentation repository, not a library. It organises 29 patterns for working with coding agents into Foundation, Development and Operations phases, and, unusually for a pattern catalogue, it ships the machinery to check its own claims, with deterministic CI checks, a status file and a local agent workflow for model-backed evidence.

**PaulDuvall/ai-development-patterns** — A comprehensive collection of AI development patterns for building software with AI assistance, organized by implementation maturity and development lifecycle phases. Includes Foundation, Development, and Operations patterns with practical examples and anti-patterns.

- Repository: https://github.com/PaulDuvall/ai-development-patterns
- Website: https://paulduvall.github.io/ai-development-patterns/
- Stars: 669 · Forks: 55
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/paulduvall-ai-development-patterns

## A pattern catalogue, structured by lifecycle phase

The repository describes itself as a comprehensive collection of patterns based on the author's experience for building software with AI assistance, organised by implementation maturity and development lifecycle phases, and it says up front that the patterns are subject to change as the field evolves. Three categories carry the structure. Foundation patterns are described as essential patterns for team readiness and basic AI integration, Development patterns as daily practice patterns for AI-assisted coding workflows, and Operations patterns sit at the end of the lifecycle, with the README's own summary of that group cut off mid-sentence in the version available here. The badge in the header counts 29 patterns, and the diagram in the README maps how they depend on each other, from Agent Readiness and Codified Rules at the top through Spec-Driven Development, Incremental Generation and Parallel Agents in the middle, to Policy Generation, Evidence Automation and Drift Remediation in the Operations group. The homepage is a GitHub Pages site, and the licence is MIT with no GitHub releases published.

## The terminology the catalogue insists on

Before any pattern, the README fixes the vocabulary, and that choice does more work than it looks. The catalogue uses coding agent for tools such as Claude Code, OpenAI Codex and Google Jules that can generate and execute code, run checks and iterate on results, and uses agentic engineering for 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. That reservation is the point of the section, because the difference between a system that suggests and a system that executes and validates is the difference between a pattern that applies and one that does not. A practice such as Bounded Autonomy or an Adversarial Evaluator means something specific only in the first world. The same care shows up in the repository layout, where an .agents/ directory, a .codex/ directory, a .tasks/ directory, AGENTS.md and CLAUDE.md sit at the top level next to the patterns themselves.

## How a pattern becomes a verdict rather than a slogan

The most distinctive part of the repository is that it tries to be checkable. The README states that adoption verdicts are mechanically recomputed from structured, tiered evidence, and that model-backed evidence research runs only on demand in a signed-in local Codex session with an explicit plan approval, while GitHub Actions never calls an evaluator model or receives an evaluator API key. Continuous integration performs deterministic checks covering schema, provenance, derivation, status drift, links and content, including a weekly read-only freshness check. The state of each pattern is recorded in verification/STATUS.md, which the README points to for every stable and exploratory pattern's assessed, pending and freshness state, and verification/README.md holds the local-agent workflow and the trust model.

The trust model is the interesting design decision here. A catalogue that claims patterns are good, and proves it by asking a model in CI, has a supply chain problem and a reproducibility problem, because a model verdict changes with the model, the prompt and the day. This one keeps the model out of CI entirely, keeps the automated checks deterministic, and confines the judgement to a local run a person has explicitly approved. The cost is that verdicts are not produced on every push, and the freshness of the assessment depends on a human deciding to run it. The repository has a tests/ directory with a passing quality gate badge and a pattern-validation workflow, plus a CONFORMANCE.md and a pattern-spec.md that define what a well-formed pattern looks like.

## The dependency graph is the argument for reading in order

The diagram in the README is not decoration, it is the sequencing advice. In the Foundation group, Agent Readiness leads to Codified Rules, which leads to Security Sandbox, then Developer Lifecycle and Tool Integration, with Issue Generation branching off Agent Readiness. The Development group hangs off the Foundation ones: Developer Lifecycle feeds Spec-Driven Development, Incremental Generation leads to Atomic Decomposition and to Parallel Agents, and Codified Rules feeds Agent Memory, which leads to Progressive Disclosure, plus Agent Hooks into Custom Commands. In Operations, Security Sandbox leads to Policy Generation and then Evidence Automation, Codified Rules leads to Centralized Rules, and Agent Observability leads to Drift Remediation, Guided Chaos and, through Guided Refactoring, Debt Forecasting.

Read that as a dependency claim rather than a taxonomy. An agent that has no codified rules cannot have agent memory that points at anything, and a team with no security sandbox cannot sensibly grant an agent bounded autonomy. The pattern names are ordinary engineering words, but the graph says the order matters, and adopting Bounded Autonomy before Security Sandbox inverts the safety argument the catalogue is making. Every node in the graph links to its own anchor section in the repository, so the reference is navigable rather than a flat list.

## The examples directory is a directory of practice

Every pattern has a corresponding example directory, and the list in the repository is long enough to describe the catalogue in one glance: agent-hooks, agent-memory, agent-observability, atomic-decomposition, bounded-autonomy, centralized-rules, code-research, codified-rules, custom-commands, debt-forecasting, developer-lifecycle, drift-remediation, error-resolution, guided-chaos, guided-refactoring, image-spec, issue-generation, parallel-agents, planned-implementation, policy-generation, progressive-disclosure, security-sandbox, spec-driven-development and tool-integration. Twenty-three example directories, and the examples folder is where a pattern stops being a description and becomes something you can look at. A pattern named Spec-Driven Development is a phrase until you see what a spec artefact looks like in practice, and an example directory is the cheapest possible way to show that.

There is also a scripts/ directory, a tests/ directory with its own pytest.ini at the root, and a patterns.yaml alongside pattern-spec.md, which together suggest the catalogue is stored as structured data and validated against a schema rather than as loose Markdown that nobody checks. The repository also carries a PATTERN_MIGRATION_GUIDE.md, which tells you that the pattern set has been reorganised at least once, and the presence of both that and a CHANGELOG-style history of changes means a reader has to expect the numbering and the names to move.

## The validation tooling and what it will and will not tell you

The Python in this repository exists to police the catalogue, not to power a product, and the pyproject.toml makes that explicit. The project is named ai-development-patterns-validation at version 0.0.0, described as repository validation tooling for AI Development Patterns, and it requires Python 3.11 or newer.

```toml
[project]
name = "ai-development-patterns-validation"
version = "0.0.0"
description = "Repository validation tooling for AI Development Patterns"
requires-python = ">=3.11"
dependencies = [
  "beautifulsoup4==4.15.0",
  "idna==3.19",
  "PyYAML==6.0.3",
  "requests==2.34.2",
  "urllib3==2.7.0",
]
```

The dependency list is telling. beautifulsoup4 and requests with a pinned urllib3 are for fetching and parsing pages, which is what link checking and the weekly freshness check need, PyYAML is for reading the structured pattern data, and idna is for internationalised domain names, which is what a link checker comparing domain names across scripts needs to avoid false failures. Every dependency is pinned to an exact version, which is the right call for a validation harness whose output decides whether a pattern ships. What the tooling cannot do is judge whether a pattern is any good. Schema conformance, a valid derivation, a working link and a fresh status say nothing about whether Parallel Agents produces better code than a single agent on your codebase, and the README is careful to say the model-backed research is local, on demand, and approval-gated.

## What this catalogue is not

Three things are worth ruling out before you adopt it. First, it is not a framework and not a library. There is nothing to pip install and call, so a team looking for a tool to run agents has found the wrong repository. Second, it is not a settled body of knowledge. The README says the patterns are subject to change as the field evolves, the repository has no GitHub releases, and the pattern set has been migrated at least once, so a reader who takes pattern names as stable identifiers will be disappointed. Third, it does not hand you a maturity assessment of your organisation. The scores in STATUS.md are assessments of the patterns, mechanically recomputed from tiered evidence, and the readiness scorecard the README links to is a separate self-assessment tool hosted off the repository, so the two should not be confused.

The honest alternative is a plain team style guide. A written set of conventions, a few decision records and a review checklist cost nothing to maintain and are entirely under your control, whereas this catalogue brings a taxonomy, an opinionated ordering, and a verdict mechanism that is only as good as the local agent session that produced it. What the catalogue adds is the taxonomy and the ordering, and what it costs is that you now have a dependency on a document that others are actively rewriting. A middle path is to read the Foundation group, take what matches how your team already works, and leave the Operations group alone until the daily practice has settled.

## Conclusion

ai-development-patterns fits a team lead who wants a shared vocabulary for AI-assisted development and, more importantly, a way to tell which of those practices are actually settled in their own organisation rather than assumed. It does not fit a developer looking for tooling, because the deliverable is prose and structure rather than code you link against, and it does not fit a team that wants the evidence verdicts to be produced automatically, because the model-backed assessments only run locally. Before you rely on the catalogue, read verification/STATUS.md and check how many of the patterns are marked assessed rather than pending, and treat the maturity labels as a starting point for your own evaluation rather than a verdict on your team.

## FAQ

### What is ai-development-patterns?

It is a collection of patterns for building software with AI assistance, organised by implementation maturity and development lifecycle phases, and the README says the patterns are based on the author's own experience. The three groups are Foundation patterns for team readiness and basic AI integration, Development patterns for daily practice workflows, and Operations patterns, and the header badge counts 29 patterns in total.

### How does the project define a coding agent?

The catalogue uses coding agent for tools such as Claude Code, OpenAI Codex and Google Jules that can generate and execute code, run checks and iterate on results, and uses agentic engineering for the practice of building software with those agents. AI assistant and AI coding assistant are reserved for systems that may suggest or chat without independently executing and validating changes.

### How are the adoption verdicts in this catalogue produced?

Adoption verdicts are mechanically recomputed from structured, tiered evidence, and the state of every pattern is recorded in verification/STATUS.md with its assessed, pending and freshness state. Model-backed evidence research runs only on demand in a signed-in local Codex session with an explicit plan approval, while GitHub Actions never calls an evaluator model or receives an evaluator API key, and CI performs deterministic schema, provenance, derivation, status-drift, link and content checks.

### Does the repository contain runnable code?

The Python in the repository is validation tooling rather than a product. The pyproject.toml describes ai-development-patterns-validation as repository validation tooling, and its dependencies are a pinned set of beautifulsoup4, idna, PyYAML, requests and urllib3, which are what a link checker and schema validator need. The pattern content itself lives in Markdown with a patterns.yaml and a pattern-spec.md, and each pattern has a matching directory under examples/.

### In what order should the patterns be adopted?

The dependency diagram in the README encodes the order, with Agent Readiness and Codified Rules leading to Security Sandbox, then Developer Lifecycle and Tool Integration, and the Development patterns hanging off those, for example Incremental Generation leading to Atomic Decomposition and Parallel Agents. The Operations group then depends on Security Sandbox and Agent Observability, so the structure argues that a team should not reach for Bounded Autonomy before it has a security sandbox in place.

## Sources

- [Issues](https://github.com/PaulDuvall/ai-development-patterns/issues)
- [License: MIT](https://github.com/PaulDuvall/ai-development-patterns/blob/main/LICENSE)
- [PaulDuvall/ai-development-patterns on GitHub](https://github.com/PaulDuvall/ai-development-patterns)
- [Project website](https://paulduvall.github.io/ai-development-patterns/)
- [README](https://github.com/PaulDuvall/ai-development-patterns/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/paulduvall-ai-development-patterns