docs-organization

---
name: docs-organization
description: >-
  Organize project documentation by size, audience, and freshness. Trigger when
  setting up docs for a new project, restructuring existing documentation, slimming
  a bloated CLAUDE.md/AGENTS.md, deciding where a doc should live, or on doc best
  practices questions. Also trigger when CLAUDE.md exceeds ~250 lines or docs are
  duplicated across files.
  Triggers on: organize docs, reorganize documentation, slim CLAUDE.md, AGENTS.md
  too long, where to put docs, docs structure, doc best practices, set up
  documentation, docs are messy, flatten docs, doc migration.
version: 1.1.0
metadata:
  author: zning1994
  openclaw:
    homepage: https://github.com/zning1994/docs-organization
    os:
      - macos
      - linux
      - windows
---

# Documentation Organization

A practical guide for organizing project documentation so that every fact has one home,
AI agents load only what they need, and humans can find things without grep.

## Why This Matters

Poor doc organization creates three problems that compound over time:

1. **Drift** — the same fact copied into 3 files eventually becomes 3 different "truths"
2. **Context waste** — a 2000-line CLAUDE.md burns AI tokens on every conversation, most of it irrelevant
3. **Lost docs** — flat directories with 20+ files make everything hard to find

The fix is simple: organize by who reads it and whether it stays current.

## Step 0: Root-Level Noise Audit

Before touching docs, clean non-documentation clutter from the project root.
Root-level noise (screenshots, recordings, debug logs, AI chat exports) is often
the biggest source of visual chaos — and it has nothing to do with documentation structure.

Run `ls | wc -l` and capture the count. Then identify and relocate:

| What to look for | Where it goes |
|-----------------|---------------|
| Screenshots, recordings (`.png`, `.mov`, `.mp4`) | `archive/media/` or `screenshots/` if curated |
| Debug/build logs (`*.log`, `firebase-debug.log`) | `archive/` or delete |
| AI chat exports, temp markdown dumps | `archive/` or delete |
| One-off config experiments | `archive/` or delete |

Do this first — it dramatically reduces root-level item count and makes the real
structure visible before you start reorganizing docs.

## Step 1: Assess Project Size

Ask yourself (or the user) these questions:

| Question | Small | Medium | Large |
|----------|-------|--------|-------|
| Source files | < 5 | 5-50 | 50+ |
| Has deployment target? | No | Yes | Yes, multiple |
| Has API or database? | No | Yes | Yes |
| Ongoing operations (cron, monitoring)? | No | Maybe | Yes |
| Multiple services/containers? | No | No | Yes |

Pick the column that best matches. When in doubt, start smaller — you can always add structure later.

## Step 2: Apply the Right Template

### Small Project

Single-service tools, scripts, simple packages.

```
project/
├── CLAUDE.md    # 50-100 lines: what it does, how to run, gotchas
└── README.md    # For humans / GitHub
```

No `docs/` directory needed. Everything fits in two files.

### Medium Project

Multi-component apps with deployment targets and external integrations.

```
project/
├── CLAUDE.md    # 100-200 lines: constraints + doc index
└── docs/
    ├── plans/       # Implementation plans
    ├── design/      # Design specs
    └── reference/   # API tables, config reference, schema
```

Add directories only when you have 2+ files that belong there. One API doc doesn't need
a `reference/` folder — just put it in `docs/api.md`.

### Large Project

Systems with operational burden: multiple services, cron jobs, monitoring, multi-environment deployment.

```
project/
├── CLAUDE.md    # 200-250 lines: constraints + doc index + key gotchas
└── docs/
    ├── README.md      # Documentation map
    ├── reference/     # API endpoints, DB schema, CLI commands, config reference
    ├── runbooks/      # Deploy, operations, troubleshooting, known issues
    ├── guides/        # How-to guides for users and operators
    ├── product/       # Roadmap, product direction
    ├── design/        # Design specs (frozen after implementation)
    ├── plans/         # Implementation plans (frozen after execution)
    ├── research/      # Investigation notes, audits, system reviews
    ├── decisions/     # Architecture Decision Records (ADRs)
    └── archive/       # Superseded docs, old logs, historical patches
```

### Multi-Repo / Monorepo Workspace

An umbrella directory containing multiple independent repos (often not a git repo itself).
The key rule: **umbrella-level docs are for cross-repo concerns only**.

```
workspace/                          # NOT a git repo
├── CLAUDE.md                       # Repo map + cross-repo conventions + doc index
├── docker-compose.yml              # Cross-repo orchestration (lives at root)
├── .env / .env.example             # Shared secrets (lives at root)
│
├── repo-a/                         # Independent git repo
├── repo-b/                         # Independent git repo
│
├── deploy/                         # Cross-repo: nginx, infra configs, deploy scripts
├── scripts/                        # Cross-repo: shared tooling
├── tools/                          # Cross-repo: shared CLI utilities
│
├── docs/                           # Cross-repo documentation ONLY
│   ├── design/                     #   System-wide architecture specs
│   ├── research/                   #   Cross-cutting investigations
│   ├── runbooks/                   #   Deploy, ops, incident response
│   └── plans/                      #   Cross-repo implementation plans
│
├── screenshots/                    # Curated product screenshots (if needed)
└── archive/                        # Superseded docs + one-off media
    ├── media/                      #   Old screenshots, recordings
    └── docs/                       #   Outdated documents
```

Key differences from single-repo Large template:
- Repo-specific docs stay **inside each repo** (e.g., `repo-a/docs/`)
- Umbrella `docs/` only holds docs that span multiple repos
- Orchestration files (`docker-compose.yml`, `.env`) live at workspace root
- `deploy/` holds all infra/nginx configs — don't scatter them in root

## Step 3: Apply the Core Principles

### Principle 1: Single Source of Truth

Every fact lives in exactly one place. Other docs can *link* to it, never *copy* it.

**Bad**: API endpoint table in CLAUDE.md AND roadmap.md AND usage-guide.md
**Good**: API endpoint table in `docs/reference/api-endpoints.md`, others link to it

When you change something, update the one canonical location. Not two files, not three — one.

### Principle 2: CLAUDE.md Is an Instruction Manual, Not an Encyclopedia

CLAUDE.md (or AGENTS.md) is loaded into every AI conversation. Keep it under 250 lines.
The reason is simple: every token in CLAUDE.md is consumed on every single conversation,
whether relevant or not. A bloated CLAUDE.md wastes context and money.

**What belongs in CLAUDE.md:**
- Behavioral constraints (naming conventions, rules, gotchas)
- Architecture summary (what connects to what)
- Documentation index (where to find details)
- Key file paths

**What does NOT belong:**
- Full API tables → move to `reference/`
- Historical changelogs → move to `product/roadmap.md`
- Deployment procedures → move to `runbooks/`
- CLI command references → move to `reference/`
- Design specs → move to `design/`

If CLAUDE.md is over 250 lines, extract the largest non-essential sections first.

### Principle 3: Organize by Audience + Freshness

Two questions determine where any doc belongs:

| Question | Options |
|----------|---------|
| **Who reads it?** | agent (AI), operator (maintainer), user (end-user), contributor |
| **Does it stay current?** | canonical (kept updated), snapshot (frozen in time), archived (superseded) |

This maps directly to directories:

| Directory | Status | Audience | Contains |
|-----------|--------|----------|----------|
| `reference/` | canonical | agent, operator | Look-up tables: API, DB, CLI, config |
| `runbooks/` | canonical | operator | Deployment, ops, incident response |
| `guides/` | canonical | user, contributor | How-to instructions |
| `product/` | canonical | operator | Roadmap, direction, milestones |
| `design/` | snapshot | agent, contributor | Feature design specs |
| `plans/` | snapshot | agent, contributor | Implementation plans |
| `research/` | snapshot | operator | One-off investigations, audits |
| `decisions/` | snapshot | contributor | Architecture Decision Records |
| `archive/` | archived | — | Old/superseded docs |

### Principle 4: No Cross-Doc Mirroring

This rule prevents drift:

> After code or config changes, update the affected canonical doc only.
> Do not mirror the same fact across multiple docs.

If you find yourself maintaining a rule like "always update roadmap, deploy, known-issues,
AND CLAUDE.md" — that's a sign of mirroring. Pick one canonical location for each fact.

## Document Metadata

Add this frontmatter to any non-trivial doc:

```yaml
---
status: canonical | snapshot | archived
audience: agent | operator | user | contributor
last_reviewed: YYYY-MM-DD
---
```

- **canonical**: Must stay current. If code changes, this doc must be updated.
- **snapshot**: True at time of writing. Never updated. Dated filename is its version.
- **archived**: Superseded or obsolete. Kept for reference only.

## Anti-Patterns to Watch For

| Anti-Pattern | Why It's Bad | Fix |
|-------------|-------------|-----|
| Same fact in 3+ files | Guaranteed drift | Pick one canonical location, link from others |
| 2000-line CLAUDE.md | Wastes AI context every conversation | Keep < 250 lines, extract reference docs |
| Flat `docs/` with 20+ files | Can't find anything | Group by audience/purpose |
| Research notes in `docs/` root | Pollutes navigation | Move to `research/` or `archive/` |
| Chat logs in `docs/` | Not documentation | Move to `archive/` or delete |
| "Always update these 4 files" rule | Creates busywork and drift | "Update the one canonical source" |
| Empty directories "for later" | Confusing, no content to navigate | Create directories when you have content |
| Flat `archive/` dumping ground | Archive itself becomes a junk drawer | Use `archive/media/` for images/video, `archive/docs/` for old text |

## Migration Checklist

When reorganizing existing docs:

1. **Snapshot before state**: Run `ls | wc -l` at root and `docs/`. Save the counts for a before/after comparison.
2. **Root-level noise audit**: Move stray media, logs, and temp files out of root first (see Step 0).
3. **Measure docs**: Count lines in CLAUDE.md, count files in `docs/`, identify duplicated facts.
4. **Classify**: For each doc, determine audience + freshness status.
5. **Create structure**: Make only the directories you need right now.
6. **Check implicit references before moving**: `rg <filename>` (or `grep -r <filename>`) across the project to find references in `docker-compose.yml`, CI/CD configs, `Makefile`, shell scripts, `.gitignore`, etc. Moving a file that is referenced by a config will cause silent runtime failures.
7. **Move files**: Relocate docs to their new homes.
8. **Update implicit references**: Fix all paths found in step 6 (docker volume mounts, script paths, etc.).
9. **Extract from CLAUDE.md**: Pull reference tables, procedures, and specs into dedicated files.
10. **Add doc index**: Update CLAUDE.md with a table pointing to where things moved.
11. **Add metadata**: Put frontmatter on each non-trivial doc.
12. **Remove duplicates**: Delete mirrored content, keep only the canonical copy.
13. **Verify links**: Make sure markdown cross-references still work.
14. **Show before/after**: Compare root item count before vs. after. This validates the effort and gives the user a tangible result.

## Example: CLAUDE.md Doc Index

After extracting content, add a table like this to CLAUDE.md:

```markdown
## Documentation Index

| What you need | Where to find it |
|---------------|-----------------|
| API endpoints | `docs/reference/api-endpoints.md` |
| Database schema | `docs/reference/database-schema.md` |
| Deployment guide | `docs/runbooks/deploy.md` |
| Known issues | `docs/runbooks/known-issues.md` |
| Roadmap | `docs/product/roadmap.md` |
```

This keeps CLAUDE.md as a routing table rather than trying to contain everything.