LLM-Optimized Documentation

LLM-Optimized Documentation

Core Principles

Banned Patterns

# Filler words - NEVER use
simplement, il suffit de, en fait, basically, just, simply,
it's important to note, as mentioned, obviously, of course,
please note that, keep in mind, remember that

# Redundant structures - NEVER use
"This file contains..." (obvious from filename)
"In this section we will..." (just do it)
"The following example shows..." (just show it)

Format Rules

Tables over Prose

# BAD - 45 tokens
The system supports three modes: development mode which
enables hot reload, production mode which optimizes for
performance, and test mode which mocks external services.

# GOOD - 20 tokens
| Mode | Behavior |
|------|----------|
| dev | Hot reload |
| prod | Optimized |
| test | Mocked services |

Bullets over Paragraphs

# BAD - Narrative
To run the project, first ensure Node.js is installed,
then install dependencies with npm install, and finally
start the dev server with npm run dev.

# GOOD - Scannable
## Run
1. Requires: Node.js 18+
2. `npm install`
3. `npm run dev`

Code over Explanation

# BAD - Explaining
To create a new user, call the createUser function
with an object containing name and email properties.

# GOOD - Showing
```ts
createUser({ name: "Jo", email: "[email protected]" })

## Structure Template

For CLAUDE.md / agent docs:

```markdown
# Project Name

## Stack
- Frontend: React/​Vite
- Backend: FastAPI
- DB: PostgreSQL

## Commands
| Action | Command |
|--------|---------|
| Dev | `npm run dev` |
| Test | `npm test` |
| Build | `npm run build` |

## Architecture
[Brief description, link to detailed docs if needed]

## Conventions
- [Rule 1]
- [Rule 2]

Progressive Disclosure

For long docs (>200 lines):

# Main Doc

## Quick Reference
[Essential info here]

## Details
See [ARCHITECTURE.md](ARCHITECTURE.md)
See [API.md](API.md)

Self-Check

Before finalizing, verify:

• No filler words?
• Tables used where possible?
• Bullet points, not paragraphs?
• Examples over explanations?
• < 500 lines (or split)?
• No redundant info?

Examples

See patterns.md for before/​after examples.