documentation-and-adrs
Documentation and ADRs helps teams record the reasoning behind significant technical decisions through structured Architecture Decision Records. Store decisions in `docs/decisions/` with context, alternatives considered, and consequences so future engineers and AI agents understand not just what was built, but why.
Documentation and ADRs captures the reasoning behind technical decisions using structured architecture decision records.
AI-generated summary based on this skill's SKILL.md
Install
shashankswe2020-ux/whoop-mcp/documentation-and-adrs · repository language: TypeScript
git clone https://github.com/shashankswe2020-ux/whoop-mcp
cp -r whoop-mcp/.github/skills/documentation-and-adrs ~/.claude/skills/documentation-and-adrsnpx skillfed install shashankswe2020-ux/whoop-mcp/documentation-and-adrsFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to write architecture decision records?
Documentation and ADRs guides you to structure each ADR with a clear title, context explaining the problem, decision statement, alternatives considered, and consequences. Store records in `docs/decisions/` so your team and AI agents can trace why technical choices were made. Include enough detail that someone unfamiliar with the project understands both the reasoning and trade-offs without needing to ask the original author.
When should I write ADRs for my project?
Documentation and ADRs recommends writing ADRs whenever you make significant architectural choices—database selections, framework decisions, API design patterns, or major refactors. Capture decisions early rather than retroactively; this preserves engineering context for onboarding and helps future maintainers (including AI agents) understand not just what was built, but why certain alternatives were rejected.
What is an ADR template for technical decisions?
Documentation and ADRs suggests a template with sections for title, status, context (the problem driving the decision), decision (what you chose), alternatives (options you considered and rejected), and consequences (trade-offs and impacts). This structure ensures decisions are documented consistently across your project and captures the reasoning needed for long-term maintenance and knowledge transfer.
How do I document design trade-offs and rejected alternatives?
Documentation and ADRs emphasizes recording alternatives considered and why each was rejected in your ADR's alternatives section. Explicitly state the trade-offs: what you gained by choosing your solution and what you sacrificed. This prevents future engineers from re-debating settled decisions and helps new team members understand the constraints and priorities that shaped your architecture.
What inline documentation best practices should I follow?
Documentation and ADRs recommends writing inline comments for non-obvious code behavior, gotchas, and the reasoning behind complex logic—not for self-explanatory code. Link comments to related ADRs when architectural decisions influenced implementation. This preserves context for maintainers and reduces onboarding friction, especially when AI agents need to understand intent beyond syntax.
How should I structure a project README and documentation standards?
Documentation and ADRs suggests establishing standards that include a clear README with project purpose, setup instructions, and links to decision records; API documentation; and a `docs/decisions/` folder for ADRs. Consistent structure helps new team members and AI agents navigate your project's technical landscape and understand both current architecture and the reasoning behind it.
SKILL.md
rendered from the published skill — quoted content, verbatim
Documentation and ADRs
Overview
Document decisions, not just code. The most valuable documentation captures the why — the context, constraints, and trade-offs that led to a decision. Code shows what was built; documentation explains why it was built this way and what alternatives were considered. This context is essential for future humans and agents working in the codebase.
When to Use
- Making a significant architectural decision
- Choosing between competing approaches
- Adding or changing a public API
- Shipping a feature that changes user-facing behavior
- Onboarding new team members (or agents) to the project
- When you find yourself explaining the same thing repeatedly
When NOT to use: Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.
Architecture Decision Records (ADRs)
ADRs capture the
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
.github/skills/documentation-and-adrs/SKILL.md