Design software for AI agents as primary users — six patterns¶
Insight: Writing more documentation (bigger CLAUDE.md files, detailed READMEs) is a necessary but insufficient strategy for making codebases AI-agent-friendly. The more effective path is redesigning software, libraries, and APIs with the AI agent as the primary user. Six patterns: (1) every output is a prompt, (2) make the next step obvious, (3) minimize external context needs, (4) leverage familiar conventions from popular tools, (5) design for workflows not concepts (co-locate code that changes together), (6) build confidence with programmatic verification beyond unit tests.
Detail: Pattern 1 is particularly actionable: CLI tool outputs (both success and failure) should be designed as prompts for the agent's next turn — including suggested next commands with IDs pre-filled. Pattern 4 means modeling your internal tools after well-known ones (CLI like kubectl, testing like pytest, data transforms like pandas) so agents can leverage training data. Pattern 5 advocates organizing code by feature/domain rather than by technical layer, since agents handle localized changes better. The "victory test" for AI-friendliness: can you give the agent a real customer feature request and have it implement changes end-to-end? Shrivu also notes documentation is "a necessary first step" — the trap is expecting it to be sufficient alone.
Sources
- Shrivu Shankar — "AI Can't Read Your Docs" (2025-08-17)