loading…

Agentic Engineering Patterns

By Simon Willison (2026).

A comprehensive guide and pattern catalog for getting reliable, high-quality results from coding agents such as Claude Code and OpenAI Codex.

Core Extraction Summary

1. Named Frameworks & Patterns (Author’s Exact Words)

• Agentic Engineering Patterns: Discipline of applying structured software engineering principles to AI coding agents.
• “First run the tests”: Four-word prompt convention used when starting any session on an existing project.
• “Use red/green TDD”: Four-word prompt instructing the agent to author a failing test before writing implementation code.
• “Agentic manual testing”: Teaching agents to perform exploratory, stateful testing using terminal commands, browser automation, and visual screenshots.
• “Writing code is cheap now”: The realization that code generation cost has collapsed, making the cost of testing and proof negligible.
• “Hoard things you know how to do”: Maintaining personal libraries of patterns, cookiecutters, and recipes for agents to recombine.
• “AI should help us produce better code”: Reframing AI not as a shortcut to cut corners, but as leverage to write better-tested, better-documented software.
• “Compound engineering loop”: Iterative workflow where every agent mistake and edge case is codified into tests, documentation, or tool harnesses.
• “Linear walkthroughs” & “Interactive explanations”: Using agent-generated tools (Showboat, Present) to force human understanding of codebases.
• “Explore subagent” & “Specialist subagents”: Delegating bounded exploration or verification tasks to isolated agent instances.

2. Decision Rules

• When starting a session against an existing repo, prompt First run the tests (or pytest), because it forces the agent to locate the test runner, discovers project shape and size, and primes a testing mindset.
• When implementing any non-trivial feature or bug fix, prompt Use red/green TDD, because writing the failing test first proves the test is sensitive to the bug and prevents false-positive test passes.
• When validating user interfaces or CLI tools, combine automated tests with agentic manual testing (screenshots, CLI runs with output capture), because automated tests frequently pass on mock data while UI/runtime integration is broken.
• When an agent makes a mistake, immediately update project documentation or tests, because agents reuse existing patterns and prompt history in the repo.

3. Anti-Patterns & Failure Mechanisms

• “Inflicting unreviewed code on collaborators”: Dumping large, untested, agent-generated PRs onto colleagues or maintainers, offloading the cognitive burden of verification.
• “Skipping manual verification due to green automated tests”: Relying solely on unit tests that may test the wrong assertions or happy paths while edge-case behavior fails.
• “Blind code acceptance”: Accepting multi-file diffs without reading or executing them, leading to rapid technical and comprehension debt.

4. Quantitative Claims & Qualifiers

• Four-word prompts (First run the tests, Use red/green TDD) trigger substantial pre-trained software engineering discipline baked into foundation models.
• Automated tests that previously took hours to write and maintain now take “just a few minutes” with an agent.

5. What the Source Does NOT Claim

• Does NOT claim that coding agents make software engineering discipline obsolete; claims that agentic tooling makes rigorous testing and verification mandatory and frictionless.

---

Guide Structure & Full Outline

The guide is organized into five main sections:

1. Principles:
   • What is agentic engineering?: Distinguishing structured agentic workflows from undisciplined “vibe coding”.
   • Writing code is cheap now: Good code still has a cost in comprehension and maintenance; new habits are required.
   • Hoard things you know how to do: Recombining proven patterns with agent velocity.
   • AI should help us produce better code: Using agents to avoid technical debt, explore more architecture options, and embrace compound engineering.
   • Anti-patterns: Avoiding unverified code dumps on maintainers and teams.
2. Working with Coding Agents:
   • How coding agents work: LLMs, chat-templated prompts, token caching, tool calling loops, system prompts, reasoning.
   • Using Git with coding agents: Core concepts, atomic branching, history rewriting.
   • Subagents: Claude Code Explore subagent, parallel subagents, specialist subagents.
3. Testing and QA:
   • Red/green TDD: Failing tests before implementation.
   • First run the tests: Priming the agent context and discovering test harnesses.
   • Agentic manual testing: Browser automation, terminal capture, Showboat notes.
4. Understanding Code:
   • Linear walkthroughs: Step-by-step code explanation artifacts.
   • Interactive explanations: Dynamic UI explanations of algorithms.
5. Annotated Prompts & Workflows:
   • WebAssembly GIF optimization, newsletter tool extensions, artifact prompts, proofreaders, and audio highlights.