brainharness-docs · diff
v1.0.0 to v1.1.0
78 added, 20 removed. Audit A to A.
---
name: docs-organization
description: >-
- Organize project documentation by size, audience, and freshness. Use this skill whenever
- the user wants to set up docs for a new project, restructure existing documentation,
- slim down a bloated CLAUDE.md/AGENTS.md, decide where a new doc should live, or asks
- about documentation best practices. Also trigger when you notice CLAUDE.md exceeding
- ~250 lines, when docs are duplicated across files, or when the user says things like
- "where should I put this doc", "my docs are a mess", "reorganize docs", or
- "set up documentation structure".
- 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.0.0
+ 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. **Measure**: Count lines in CLAUDE.md, count files in `docs/`, identify duplicated facts
- 2. **Classify**: For each doc, determine audience + freshness status
- 3. **Create structure**: Make only the directories you need right now
- 4. **Move files**: Relocate docs to their new homes
- 5. **Extract from CLAUDE.md**: Pull reference tables, procedures, and specs into dedicated files
- 6. **Add doc index**: Update CLAUDE.md with a table pointing to where things moved
- 7. **Add metadata**: Put frontmatter on each non-trivial doc
- 8. **Remove duplicates**: Delete mirrored content, keep only the canonical copy
- 9. **Verify links**: Make sure cross-references still work
+ 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.