Practical patterns for building software that works as well with AI agents as it does with humans — and recognizing that the gap between those two audiences is wider than most teams think.
AI coding agents are becoming standard tools. But most codebases weren't built for them. They were built for humans who can mentally bridge gaps, tolerate partial feedback, rely on intuition to navigate messy directories, and instinctively know which warnings to ignore.
AI agents can't do any of that. They need:
- Complete feedback — a test either passes or fails, and the failure tells them exactly where to look
- Structured context — information organized so complexity is discoverable, not dumped all at once
- Enforced discipline — rules that are impossible to bypass, not just written in a wiki
- Deterministic environments — no "it works on my machine," no shared state leaking between tests
These aren't new ideas. Deep modules, progressive disclosure, and evidence-based engineering are decades old. What's new is how critical they become when your coworker is an AI with no memory of your codebase and no intuition to fall back on.
Traditional software engineering optimizes for human developers. Agentic development optimizes for AI agents — and it turns out the practices that make codebases agent-friendly also make them better for humans. The discipline is higher, but the payoff is a codebase that any contributor (human or AI) can work in effectively from day one.
Peter Steinberger, creator of OpenClaw, has described building production software entirely with AI agents — managing 5-10 parallel agents, closing the feedback loop so agents verify their own work, investing heavily in planning before implementation, and treating code reviews as architecture discussions. His core insight: "I don't think software engineering is dead with AI: in fact, quite the opposite." Agentic development demands more engineering discipline, not less.
These patterns extract and structure the thinking behind that approach. They come from a production-grade Telegram trading bot built fully agentically with Claude Code as the primary development tool. That project developed Stack-First Development — bringing up the entire application stack in Docker and testing through API endpoints only. Each stack test is an atomic user journey — the stack must pass or fail as a whole, with no partial results or mocked components to hide behind.
The patterns here generalize that approach — and the supporting practices around project structure, skills, guardrails, optimization, and documentation rigor — into a framework any team can adopt.
This isn't theory. These patterns are in daily production use. They've been refined through hundreds of agent sessions building real features, fixing real bugs, and passing real tests.
Patterns are organized into five levels, each building on the previous. Adopt them in order — skipping levels creates fragile foundations.
L0: Foundation — Structure your codebase so an AI with zero prior context can navigate, understand, and contribute. Deep modules, progressive disclosure, conceptual file organization, CLAUDE.md as project constitution, unit tests as contract, documentation as system map, and aggressive cleanup. The "can a new starter figure this out?" test.
L1: Feedback Loops — Replace the traditional test pyramid with closed-loop testing. Stack tests bring up the full application stack and test through APIs only — no mocks, no partial integration, no ambiguous results. Full-loop assertion layering catches regressions at primary, secondary, and tertiary levels.
L2: Behavioral Guardrails — Rules written in prose are suggestions. Skills and hooks are enforcement. Overlay skills on top of base agent capabilities, chain them into a complete development lifecycle, and automate discipline through the tool layer.
L3: Optimization — Agent efficiency is quality, not just speed. Smart routing redirects shell commands to specialized tools (60-80% token reduction). Intent classification, environment-aware routing, and the Scout Pattern (from the WISC context engineering framework: Write, Isolate, Select, Compress) turn exploration into structured context.
L4: Standards & Measurement — Evidence-based claims, spec drift detection, the new starter audit, and development metrics. The maturity layer that verifies L0-L3 are holding and measures their impact over time.
- New to agentic development? Start with L0: Foundation. The structural changes there are the highest-impact, lowest-effort starting point.
- Already using AI coding tools? Jump to L1: Feedback Loops to understand why your tests might be giving your agent incomplete feedback.
- Building team practices? L2: Behavioral Guardrails and L4: Standards & Measurement together establish the discipline layer.
- Want a phased adoption plan? See the Migration Guide for a step-by-step path from traditional to agentic practices.
- Solo developers and small teams using Claude Code, Cursor, or similar tools — adopt patterns incrementally starting at L0
- Team leads and architects establishing agentic development practices across an organization
- Anyone curious about what "agentic-friendly" software engineering actually looks like in practice
docs/ # Pattern documentation (L0-L4) and guides
examples/ # Working code examples (TypeScript + Python)
stack-test/ # Minimal stack test setups in both languages
guardrails/ # Token optimization middleware example
project-structure/ # Before/after directory layouts
docs/cross-cutting/ # Anti-patterns, migration guide, glossary
docs/references/ # Case study and further reading
This is a living pattern library. Contributions welcome:
- New patterns that extend or challenge the existing framework
- Real-world examples from different domains (the current examples lean toward ecommerce and trading)
- Corrections when a pattern doesn't match your experience — document the exception
- Translations of concepts to other frameworks and tools
- Reference Telegram Trading Bot Case Study — the production system these patterns were extracted from
- Further Reading — articles, videos, and tools that informed this work
- Glossary — terminology reference
