My Project Docs Aren't For Humans Anymore. They're For an Agent That Re-Reads Them Every Session.

Short summary

The author argues project documentation should be written for AI agents that re-read files fresh each session, not humans who skim with existing mental models. After a stale fact file caused a repeated bug six weeks later, they restructured docs into terse, purpose-specific files with routing protocols that function like if/else logic for the agent. The core insight: writing for an agent is closer to authoring an API contract than a wiki page—every line must be self-contained enough to act on without follow-up.

• •Documentation for AI agents must be terse, literal, and self-contained—agents can't skim or apply skepticism
• •Splitting facts, decisions, and bugs into separate files prevents irrelevant prose from polluting agent queries
• •Every fact should carry an expiry breadcrumb linking to the incident that produced it

Generated with AI, which can make mistakes.