documentation-and-adrs

Documentation and ADRs - Guide to Technical Documentation and Architecture Decision Records

Skill Overview

Documentation and ADRs provides comprehensive guidance on writing technical documentation, helping teams record architecture decisions, write API documentation, and maintain READMEs so that the “why” and the “what” of code are equally clear.

Applicable Scenarios

1. When making major technical decisions

When your team needs to choose a framework, design a data model, select an authentication solution, or decide on an API architecture, this skill guides you in creating an Architecture Decision Record (ADR) to capture the decision’s context, constraints, and trade-offs. A ten-minute ADR can prevent the same decision from being debated again six months later.

2. When releasing a public API or changing user behavior

Before adding or modifying a public API or releasing a feature that changes user behavior, use this skill to ensure that API parameters, return types, and exceptions are fully documented, preventing future confusion and repeated questions.

3. When onboarding new members or repeatedly explaining the same thing

When you find yourself repeatedly explaining the same technical choice or project convention, it is a sign that the content needs to be documented. This skill helps you record project conventions in CLAUDE.md, allowing AI agents and future engineers to quickly understand the project context.

Core Features

1. Creating and managing Architecture Decision Records (ADRs)

Provides a standardized ADR template covering key sections such as status, date, context, decision, alternatives, and consequences. It guides you to match the existing ADR conventions of the project (location, format, numbering, and titles), rather than blindly introducing a new approach. It includes complete ADR lifecycle management (PROPOSED → ACCEPTED → SUPERSEDED/DEPRECATED), ensuring that historical decisions are preserved rather than deleted.

2. Best practices for inline documentation and comments

Teaches you when to write comments (explain “why,” not “what”), when not to write them (self-explanatory code does not need comments that merely restate it), and how to document known pitfalls (to prevent AI agents and developers from falling into traps). Distinguishes between stable comments (the rationale behind decisions) and comments that are likely to become outdated (descriptions of the code), and encourages writing only the former.

3. A multi-level documentation system

Covers API documentation (TypeScript JSDoc, OpenAPI/Swagger), README structure (quick start, command list, architecture overview), changelog maintenance (Added/Fixed/Changed), and documentation standards specifically for AI agents (CLAUDE.md, spec files, and inline pitfalls).

Frequently Asked Questions

When should an Architecture Decision Record (ADR) be created?

When choosing a framework, library, or major dependency; designing a data model or database architecture; selecting an authentication strategy; deciding on an API architecture (REST vs. GraphQL vs. tRPC); or choosing build tools, hosting platforms, or infrastructure. Any decision that is difficult to reverse is worth documenting in an ADR.

What should an ADR contain?

A complete ADR should include: status (Accepted/Superseded/Deprecated), date, context (requirements, constraints, and conditions), decision (the approach you selected), alternatives (other options considered and their pros and cons), and consequences (the positive and negative effects of the choice). If the project already has ADR conventions, match its existing section headings and format.

What is the difference between code comments and technical documentation?

Code comments are temporary and embedded in the code, used to explain non-obvious “why” questions (such as why a sliding-window algorithm is used). Technical documentation is standalone and structured, aimed at future readers and AI agents, and explains the decision context, API usage, project architecture, and other aspects. Code comments focus on specific implementation details, while documentation focuses on the broader context and design rationale.