Skip to main content

Don't Write Docs Twice

· 2 min read

I recently wrote about optimizing repos for AI, and since then I've been maintaining separate docs for humans (README, contributing guides) and AI agents (.cursorrules, CLAUDE.md, etc.). The problem? I keep writing the same information twice.

The duplication problem​

You're documenting the same things in multiple places​

info

Nearly everything I put in agent-specific docs is also useful for human developers - architecture decisions, coding conventions, common pitfalls, useful commands. Without AI agents I might not document all of this, but once written, there's no reason it shouldn't serve both audiences.

AI agent doc organization is fragmented​

Each coding agent uses its own configuration file pattern for repo-specific instructions:

fragmentation

This creates a hassle just keeping guidelines between agents consistent, much less making information available for humans.

Instead of duplicating content across agent configs, organize information for humans first and link to it from agent-specific files1:

easy-for-humans

This approach eliminates duplication - you write documentation once, and it serves both humans and AI. It's also more future-proof when agent file schemes inevitably change.

For commands/skills, automation can help avoid duplication entirely - for example, I wrote the just-claude utility for automatically synchronizing Just recipes with Claude Code Skills.

There's really no difference between the goal of economical token use for AI and reducing cognitive overhead for humans. By organizing for humans first, you write documentation once and everyone benefits.

Footnotes​

  1. I wrote about what content I put in these files in the (ironically titled) post Optimizing repos for AI ↩