For years, the argument for keeping documentation in your code repository was theoretical. Version control is better than Google Docs for technical writing. Code proximity means docs stay current. Pull request reviews catch errors early. All true, all mostly ignored. Most teams still kept their docs in Confluence, Notion, or Google Drive because that's where non-engineers could reach them.
AI coding agents just broke that calculus.
Agents Can Only Read What's in the Repo
When you point Claude Code, Cursor, or Copilot at your project, they see your repository. They don't see your Confluence space. They don't see the Google Doc where your PM wrote the product requirements. They don't see the Slack thread where your team decided on the API design.
Every piece of context that lives outside the repo is invisible to your AI tools. That means your agents are writing code based on incomplete understanding of what the code should do, how it should behave, and why certain decisions were made.
Move your specs, RFCs, architecture decision records, and product requirements into the repo, and your AI tools immediately get smarter. Not because the models improved, but because they finally have the context they needed all along.
The Maintenance Problem Is Solved
The classic objection to repo-based docs was always maintenance. Documentation goes stale because nobody wants to update it manually. That objection has largely evaporated. AI agents can now flag when code changes make documentation inaccurate. Some teams are running CI checks that validate code examples embedded in their docs, similar to Python's doctest pattern where sample code actually executes during testing.
One practical approach gaining traction: treat your AI rules files (like .cursor/rules or .claude/CLAUDE.md) as documentation. Developer Simon Dein argues that 80% of what people put in AI rules files should actually be proper documentation that benefits both humans and agents. He's right. A rules file that says "always use snake_case for database columns" is just an undiscoverable style guide.
How to Start
You don't need to migrate everything at once. Start with three categories:
- Architecture decisions that AI agents need to respect when generating code
- API specifications that define contracts between services
- Setup and deployment docs that agents reference when helping with infrastructure tasks
GitHub renders Mermaid diagrams natively now, so even visual documentation like system architecture diagrams can live in markdown files. Google Docs has a "Copy as Markdown" feature for migrating existing collaborative documents.
The shift happening here is philosophical as much as practical. Engineers are spending less time writing code and more time writing specifications and guidelines that AI agents follow. Documentation isn't a chore anymore. It's becoming the primary way you control what your AI tools produce.