Menu
Architecture Decision Records, API docs, inline documentation standards. Use when making architectural decisions, changing APIs, or shipping features. Document the why, not the what.
| name | documentation-and-adrs |
| description | Architecture Decision Records, API docs, inline documentation standards. Use when making architectural decisions, changing APIs, or shipping features. Document the why, not the what. |
Document architectural decisions, API contracts, and system behavior. Focus on the "why" rather than the "what" because code already tells you what happens. Documentation should explain why it was designed that way.
Record significant architectural decisions:
Save as: docs/decisions/{YYYY-MM-DD}-{title}.md
Document public APIs with:
Every project should have:
| Rationalization | Reality |
|---|---|
| "The code is self-documenting" | Code tells you what. Documentation tells you why. Both are needed. |
| "Documentation goes stale immediately" | Stale docs are a signal to update, not to stop documenting. |
| "I will document later" | Later never comes. Document alongside the implementation. |
| Excuse | Counter |
|---|---|
| "The code is self-documenting" | Code tells you what. Documentation tells you why. Both are needed. |
| "Documentation goes stale immediately" | Stale docs are a signal to update, not to stop documenting. |
| "I'll document later" | Later never comes. Document alongside the implementation. |
| "ADRs are too formal for this decision" | Even small decisions benefit from recorded rationale. Future you will thank present you. |
| "No one reads documentation" | People read docs when they are stuck. Good docs prevent being stuck. |
Daily research agent for
Weekly research agent for
Daily research agent for
Build, run, and secure Docker containers with current best practices. Use for Dockerfile review, multi-stage builds, Compose orchestration, image hardening, and CI/CD integration.
Operate GitHub repositories, workflows, and PRs efficiently. Use for Actions optimization, PR hygiene, repo maintenance, and team collaboration patterns.
Deploy, manage, and troubleshoot Kubernetes workloads. Use for manifest review, Helm chart validation, resource tuning, RBAC, and cluster operations.
