An argument for storing all project documentation directly in the code repository alongside source code. Key benefits include version control, proximity to code, formal review processes, automatic generation, and testability. AI agents make this approach even more compelling by solving the stale docs problem — they can automatically check for documentation inconsistencies during PRs and benefit from richer in-repo context. The post also argues that AI-specific rules files (.mdc) are essentially documentation and should be treated as such. Common objections (waiting for code review, AI writing verbose docs, non-engineer access) are addressed with practical counterpoints.
Table of contents
We will be spending more time writing docsWhy AI makes it even more meaningful to move docs into your repoAnswer to objectionsReferences and articlesSort: