06-30
How To Make Codebases AI Agents Love
This article argues that codebase structure matters more than prompts or AGENTS.md files for AI agent output quality. The core idea is applying 'deep modules' from A Philosophy of Software Design: each module exposes a simple interface controlling lots of implementation. The author introduces 'grey box modules'—developers own and test the interface, AI owns the implementation inside. This improves feedback loops (tests are feedback), navigability (filesystem mirrors mental model), and reduces cognitive load (developers only track 7-8 module boundaries). The article notes TypeScript's difficulty enforcing boundaries and recommends the Effect library. For engineers optimizing AI coding workflows.