--- title: "Software Architecture That Agents Actually Like" description: "Structural patterns that make codebases easier for AI agents to navigate: composition over monoliths, stateless mini-CLIs, typed languages, and the editor navigation test." type: note pubDate: 2026-01-30T00:00:00.000Z topics: ["agents", "architecture", "software-design"] canonicalUrl: "https://actuallymaybe.com/blog/agent-friendly-architecture/" --- > Structural patterns that make codebases easier for AI agents to navigate: composition over monoliths, stateless mini-CLIs, typed languages, and the editor navigation test. I've been thinking a lot about the structural techniques that agents seem to favour. There are patterns I keep noticing: things that make them work better, and things that confuse them. ## Composition Over Monoliths Agents really like composition out of different parts. Monorepos where they can see over everything. One big project? They tend to get confused. But if you can break it down into multiple projects, things go smoother. So rather than have a CLI that does all the different things, what you want is lots of little tiny mini CLIs and a CLI router between them. Then try to think of each CLI as stateless as possible, or centralise all the data management in one place. These are ideas I've noticed agents seem to favour. And structurally, they're just good software practices anyway. If you can have a design that's limited in scope and stateless, you're gonna have a better outcome. This carries over to more complex systems too. You're just building them out of compositional pieces, smaller pieces. ## The Multi-Service Sweet Spot There's a nicer experience when you can push towards more of a multi-service architecture in a monorepo. You iterate on different pieces and there's a defined contract between them. Lots of linting rules help. You can make custom linting rules. Agents don't really care about the overhead, they just follow them. Git hooks too. I don't really like git hooks personally, but agents work quite well with them because it forces them to check things. And because there are so many different standards between different agents, git hooks are a nice standard way that just forces them to confront issues before they become problems. ## Types Are Your Friend I do think there are other things worth exploring. Compiled languages have a nice experience. I've had some luck with Go when building things because there are explicit errors when you compile. But I think that's kind of a known thing already. You can see that drive towards adding types to Python, the usage of TypeScript, or some sort of types for JavaScript like JSDoc. ## The Editor Navigation Test Here's another pattern I've noticed: if a codebase is easy to navigate in your editor, agents will probably handle it well too. Think about it: you're looking for how routes are handled in some large React application. If you can think ahead of time about where that code lives, bring up the command menu, and jump directly to that file... that feeling of navigating a codebase like that? That's generally also a codebase where agents work quite well. There's something implicit here. By the weakness of your own working memory, if you can have a codebase where you can do that kind of navigation, then agents can handle it better. They can infer and understand the structure. If you're lost, they're lost. ## Further reading - [Notes on Visual Interfaces, AI Tooling, Fast LLMs and Decision Models](https://actuallymaybe.com/blog/notes-visual-interfaces-ai-tooling-fast-llms-decision-models/) — Why agentic work is stuck in text, and what canvases, fast models, branching version graphs, and decision models might add. - [Building Explainers Random Thoughts - Drone 101](https://actuallymaybe.com/blog/building-explainers-random-thoughts-drone-101/) — An experiment in interactive explainers: drone control, Fourier, Bret Victor, philosophical prompts, accessibility, and learning with LLMs. - [Emerging Field of Epistemic Engineering or Stochastic Management](https://actuallymaybe.com/blog/emerging-field-epistemic-engineering/) — Practices around context, uncertainty, and evals are hardening into a discipline, with belief states at its centre: probabilistic, grounded views of a work process. - [Cheaper Code Should Mean More Experiments](https://actuallymaybe.com/blog/cheaper-code-more-experiments/) — When working with agentic tools, the instinct to solve hard problems inside your main project is usually wrong. Isolate the core problem first, experiment freely, then bring what works back. - [Using Agentic AI Tools for Anki Flashcard Creation](https://actuallymaybe.com/blog/agentic-ai-anki-flashcard-creation/) — How Claude Code and similar tools can handle the tedious work of expanding concepts into multiple flashcards, and why Anki Connect is the key to making it work.