Document

Documentation explains how to use and maintain the system. Apply these rules to project docs, agent guidance, skills, docstrings, and comments.

Core rules

• Lead with the problem or purpose, then describe behavior and usage.
• Prefer one concrete example over repeated explanation.
• Remove stale descriptions of behavior that no longer exists. Do not add historical notes to preserve them.
• Document supported behavior, not aspirations.
• Use lists instead of tables unless the user requests a table.
• Write short, grammatical sentences. Remove framing and repeated instructions.
• State concrete constraints. "Dataset must not import training" is clearer than "respect boundaries".
• Consolidate duplicated guidance and link to its owner.

Project docs

Answer what the project does, why it exists, how to use it, and where related documentation lives. Include a minimal working example. Keep a README under 200 lines, moving detail into docs/ when needed.

Agent guidance

Put project-wide rules, constraints, style preferences, and pointers in CLAUDE.md or its equivalent. Per-task instructions belong in docs/tasks/<slug>.md.

Skills

• Preserve name and description frontmatter. The description determines when an agent loads the skill.
• Cover when to use it, the process, key rules, required output, and terminal state.
• Use descriptive headings. Aim for a body under about 150 lines without removing required behavior.

Docstrings

For a large class or module, explain its responsibility and boundaries:

class DatasetBuilder:
    """Build dataset shards from raw episodes.

    Validate inputs, transform records, and checkpoint progress.
    Training-time loading belongs in training/loader.py.
    """

For a small utility, one line is enough. Omit docstrings that merely repeat an internal helper's name.

Inline comments

Explain non-obvious reasons: a workaround, required ordering, hidden invariant, or surprising choice. Remove narration such as # increment counter, change-history notes, and placeholder apologies.

Keep a concrete historical cause when it explains a current constraint. "Guard against overflow that corrupted billing totals" explains a guard. "Added in the billing cleanup" does not.

Process

1. Identify the audience and the question the document must answer.
2. Choose a list, example, or paragraph that fits the content.
3. Draft concise instructions grounded in the implementation.
4. Remove text that adds no instruction or explanation. Do not cut to a percentage target.
5. Include a concrete example where it helps the reader act.
6. Check references and remove stale, aspirational, or duplicated claims.