79573df7cb
20 specialized agents, 10 skills, 17 slash commands, 6 plugins, 12 hooks with scripts, 8 rule sets, 3 CLAUDE.md templates, 14 MCP server configs, and interactive setup installer.
44 lines
1.9 KiB
Markdown
44 lines
1.9 KiB
Markdown
# Documentation Rules
|
|
|
|
## What to Document
|
|
- Public API functions: parameters, return types, error conditions, examples.
|
|
- Architecture decisions: why a particular approach was chosen (ADRs).
|
|
- Setup and installation: prerequisites, steps, common issues.
|
|
- Configuration: all options, defaults, environment variables.
|
|
- Non-obvious behavior: edge cases, gotchas, workarounds.
|
|
|
|
## What Not to Document
|
|
- Obvious code (getters, setters, simple wrappers).
|
|
- Implementation details that change frequently.
|
|
- Anything the type system already expresses.
|
|
- Temporary workarounds without a tracking issue.
|
|
|
|
## Keep Docs Current
|
|
- Update documentation in the same PR that changes the code.
|
|
- Review docs in code review. Stale docs are worse than no docs.
|
|
- Use CI to verify that documentation examples compile or run.
|
|
- Keep CLAUDE.md or AGENTS.md updated with current project context.
|
|
|
|
## Documentation Formats
|
|
- Inline code comments: explain **why**, not what. One line, placed above the code.
|
|
- JSDoc/docstrings: for public APIs. Include parameters, returns, throws, and an example.
|
|
- README: installation, quick start, configuration, contribution guidelines.
|
|
- CLAUDE.md: project context, conventions, build commands, key architecture decisions.
|
|
- ADRs: date, status, context, decision, consequences. Store in `docs/adr/`.
|
|
|
|
## Style Guidelines
|
|
- Use concrete examples, not abstract descriptions.
|
|
- Write for the reader who will maintain this code in 6 months.
|
|
- Use consistent terminology. Define domain terms in a glossary if needed.
|
|
- Keep sentences short. One idea per paragraph.
|
|
- Use code blocks with language tags for syntax highlighting.
|
|
- Use tables for option lists, comparison matrices, and configuration references.
|
|
|
|
## README Structure
|
|
1. Project name and one-line description.
|
|
2. Installation / quick start (copy-paste ready).
|
|
3. Usage examples (the most common use case first).
|
|
4. Configuration reference.
|
|
5. Contributing guidelines.
|
|
6. License.
|