AI-Readable Documentation

The .ai/ Folder Pattern

During Ada’s development, we discovered that AI assistants need different documentation than humans. This led to the emergence of the .ai/ folder pattern.

The Problem

Humans need tutorials, examples, and narrative explanations.

AI assistants need structure, relationships, and architectural patterns.

Traditional approaches (single .cursorrules files, instructions in README) work for small projects but don’t scale well.

Our Solution

Ada uses a dedicated .ai/ folder for machine-readable documentation:

.ai/
├── README.md               # Pattern explanation
├── context.md              # Architecture overview
├── codebase-map.json       # Module dependencies
├── CONVENTIONS.md          # Documentation strategy
├── QUICKSTART.md           # Common tasks
├── CLEANUP_NOTES.md        # Current status
├── GOTCHAS.md              # Known pitfalls
└── PATTERN.md              # Meta-documentation

Plus AI.md in the repository root as an entry point.

Separation of Concerns

Location

Audience

Content Type

docs/*.rst

Humans

Tutorials, examples, narrative

.ai/*.{md,json}

AI assistants

Structure, dependencies, patterns

Inline comments

Developers

Code-level explanations

Why This Matters

For AI assistants:

  • Faster architectural understanding

  • Better code placement suggestions

  • Fewer clarifying questions

  • Understanding of project conventions

For humans:

  • Documentation stays focused on their needs

  • Less noise in tutorials

  • Clear separation between “how to” and “how it works”

Not a Standard (Yet)

This pattern emerged organically from our development process. We’re sharing it as an example, not prescribing it as a rule.

Key principles:

  • Start minimal (just AI.md + .ai/context.md)

  • Grow as needed

  • Keep it current

  • Adapt freely for your context

Integration Points

Ada provides multiple entry points for AI assistants:

  1. GitHub Copilot - .github/copilot-instructions.md forwards to .ai/ folder

  2. General AIs - AI.md in repository root explains the pattern

  3. MCP clients - Documentation exposed as MCP resources (ada://docs/*)

  4. Direct access - Browse .ai/ folder for structured docs

All paths lead to the same source of truth, just through different protocols.

Learn More

Credits

This pattern developed collaboratively by luna system and Claude Sonnet 4.5 during Ada’s development (2025).

Inspired by:

  • Cursor’s .cursorrules pattern

  • The Aider project’s context files

  • Decades of README-driven development

  • Real pain points from AI-assisted development

The pattern is public domain - use and adapt freely!