Comprehensive code documentation skill — use this any time documentation is requested, after any significant code change, when onboarding a new subsystem, au...
---
name: code-documentation
description: >
Comprehensive code documentation skill — use this any time documentation is requested, after
any significant code change, when onboarding a new subsystem, auditing existing docs for accuracy,
or when asked to "document", "update docs", "write docs", or "clean up comments". Covers three
tightly coupled concerns: (1) inline file/function headers in source code, (2) subsystem-level
.md docs, and (3) global architecture + API reference docs. Always apply this skill — do not
improvise documentation standards. Also triggers for requests like "add comments", "document
this file", "our docs are out of date", "generate API reference", or after a PR or feature branch
is completed.
---
# Code Documentation Skill
## Purpose
This skill governs how code is documented at every level — from individual file headers to
global architecture docs. Apply it consistently across all projects. When in doubt: document
the *why*, not the *what*. The code already says what it does.
---
## Phase 0 — Before You Write Anything
1. **Scan the repo structure.** Understand what exists before touching anything.
2. **Identify subsystems.** Group files by domain (Auth, Billing, API Layer, etc.).
3. **Read existing docs first.** Check `/docs/` in both frontend and backend. Note what's
present, missing, or stale.
4. **Confirm the active branch.** Never document against stale or wrong code.
---
## Phase 1 — Source File Standards
Apply to every file that is ≥ 20 lines OR is imported by other modules.
### 1.1 — Line 1: Full Path Comment
The very first line of every source file must be a comment containing the file's full path
from the project root. Use the comment syntax appropriate to the language.
```js
// src/services/auth/tokenService.js
```
```py
# src/services/auth/token_service.py
```
### 1.2 — File Header Block (lines 2–N)
Immediately after the path comment, add a header block. Use the language's block comment
syntax. This block is mandatory and must be kept accurate.
```
/**
* File: src/services/auth/tokenService.js
*
* Overview:
* Issues, validates, and refreshes JWT tokens for authenticated sessions.
* Exists to centralise all token logic so Auth routes stay thin.
*
* Exports:
* - issueToken(userId, role) → signed JWT string
* - verifyToken(token) → decoded payload or throws
* - refreshToken(oldToken) → new signed JWT string
*
* Imported By:
* - src/routes/auth.js
* - src/middleware/requireAuth.js
*
* Imports:
* - jsonwebtoken — signing/verification
* - config/env — JWT_SECRET, TOKEN_TTL
*
* Notes:
* - Tokens expire in 15 min; refresh window is 7 days.
* - verifyToken throws on expiry — callers must handle.
*/
```
**Rules:**
- Keep it current. If you add an export, update Exports. If a new file imports this, update
Imported By.
- Do not pad with boilerplate. Every line must be accurate and useful.
### 1.3 — Function Headers
Top of every non-trivial function (any function with logic beyond a single expression):
```js
/**
* Signs a new JWT for the given user. Embeds userId and role in payload.
* Throws if JWT_SECRET is not set in env.
*/
function issueToken(userId, role) { ... }
```
**Rules:**
- Max 2 sentences.
- Explain *why* the function exists or what makes it non-obvious, not just what it does.
- No parameter/return type breakdown unless the types are genuinely surprising.
### 1.4 — Inline Comment Rules
**Allowed (rare exceptions only):**
```js
const TIMEOUT = 5000 // 5 seconds
```
**Prohibited — remove on sight:**
| Pattern | Example | Why banned |
|---|---|---|
| Restating the code | `// enable proxy` above `proxy: true` | Zero information |
| Removed/old code notes | `// removed legacy handler` | Use git for history |
| Change log comments | `// changed to use v2 API` | Not a changelog |
| Section dividers | `// ---- helpers ----` | Use modules instead |
| Obvious steps | `// loop through users` above a users.forEach | Noise |
If you encounter these, **delete them**. They are clutter that erodes trust in real comments.
---
## Phase 2 — Subsystem Documentation
See `references/subsystem-doc.md` for the full template and field-by-field instructions.
**One `.md` file per subsystem, located at:**
- `/backend/docs/<subsystem>.md`
- `/frontend/docs/<subsystem>.md`
**Subsystem identification heuristics:**
- A cohesive domain handled by a directory or cluster of files
- Examples: `auth`, `billing`, `search`, `notifications`, `api-layer`, `data-layer`,
`file-upload`, `websockets`, `admin`, `onboarding`
**Discovery checklist — identify a subsystem when you find:**
- [ ] A directory with 3+ related files
- [ ] A shared service/utility used by 3+ other files
- [ ] A distinct API surface (routes/controllers grouped by concern)
- [ ] A background job or scheduled process
- [ ] A third-party integration (Stripe, S3, Twilio, etc.)
**If a subsystem doc already exists:**
- Compare it against current code
- Remove anything describing code that no longer exists
- Add anything the doc misses
- Update all file maps, function names, and flow diagrams
---
## Phase 3 — Global Architecture Document
Location: `/docs/architecture.md` (or `/backend/docs/architecture.md` depending on repo layout)
See `references/architecture-doc.md` for the full template.
Required sections:
1. System Overview — what this product does in 2–3 sentences
2. Subsystems — bulleted list, one-liner per subsystem, link to its `.md`
3. High-Level Diagram — ASCII or Mermaid, showing subsystem relationships
4. Tech Stack — language, framework, DB, cache, queue, infra
5. Cross-Cutting Concerns — how auth, error handling, validation, config, logging, and
testing work *across* the system (not per-subsystem)
---
## Phase 4 — API Reference
**Required if a backend exists.** Location: `/backend/docs/api.md`
For large backends: one file per subsystem, e.g. `/backend/docs/api-auth.md`,
`/backend/docs/api-billing.md`, then an index in `/backend/docs/api.md`.
See `references/api-reference.md` for the full endpoint template.
Every endpoint must document:
- Method + path
- Description (1 sentence — what this does for the caller)
- Request: path params, query params, body schema
- Response: success schema + status codes + error codes
- Source mapping: which controller file and service methods handle it
---
## Phase 5 — Validation Pass
After writing or updating docs, audit them:
```
## Documentation Audit
### Missing
- List any subsystem without a doc
### Outdated
- List any doc that references removed files, functions, or endpoints
### Incorrect
- List any wrong dependency, wrong export name, wrong flow description
### Recommendations
- Specific fixes with file locations
```
Do not skip this pass. Stale documentation is worse than none — it actively misleads.
---
## Enforcement Rules
These apply any time you touch code:
1. **Changed a function's logic?** → Update its header.
2. **Added or removed an export?** → Update the file header's Exports section.
3. **Added a new file that others import?** → Add the file header; update importers'
"Imported By" lists if practical.
4. **Added or changed an API endpoint?** → Update `api.md`.
5. **Structural change to a subsystem?** → Update that subsystem's `.md`.
6. **Added a new subsystem?** → Create its `.md` from the template in
`references/subsystem-doc.md`.
7. **Removed a file or feature?** → Find every doc that mentions it and remove those
references.
**Never leave documentation in a state that describes code that doesn't exist.**
---
## Quick Reference: What Goes Where
| Concern | Location |
|---|---|
| File path + module summary | Top of every source file |
| Function purpose | Top of every non-trivial function |
| Subsystem deep-dive | `/[frontend\|backend]/docs/<name>.md` |
| System-wide architecture | `/docs/architecture.md` |
| API contracts | `/backend/docs/api.md` (or per-subsystem) |
---
## Reference Files
- `references/subsystem-doc.md` — Full subsystem doc template + instructions
- `references/architecture-doc.md` — Full architecture.md template
- `references/api-reference.md` — Full API endpoint documentation template
don't have the plugin yet? install it then click "run inline in claude" again.