Documentation and ADRs

What Is This

The "Documentation and ADRs" skill is focused on capturing the context and reasoning behind technical decisions in a software project, particularly when implementing features that change user-facing behavior. Unlike simple in-code comments, this skill emphasizes recording the motivations, trade-offs, and alternatives considered during the development process. The primary artifact produced by this skill is the Architecture Decision Record (ADR). An ADR is a concise document that explains the why behind critical technical choices, making it easier for future developers, engineers, or AI agents to understand the rationale and context behind the system's evolution.

This skill is especially important for teams working on complex systems, shared codebases, or projects that are expected to be maintained and extended over time. By systematically documenting decisions, you reduce onboarding time for new contributors, minimize knowledge silos, and prevent repeated debates over previously settled questions.

Why Use It

Software projects are constantly evolving. Features are added, APIs change, and architectural decisions are made to address new challenges. Over time, the original context behind these changes is often lost, leading to confusion, redundant effort, or even costly mistakes. Relying solely on code to tell the story falls short - code shows what was built, but not why it was done that way.

Using the "Documentation and ADRs" skill ensures that:

• The intent behind significant changes is preserved for the future.
• Teams can easily revisit the reasoning behind major decisions when requirements change or issues arise.
• New team members or AI agents can quickly come up to speed on the project's design considerations and history.
• The same questions do not need to be answered repeatedly, improving efficiency and reducing frustration.

In short, high-quality documentation and ADRs help maintain project clarity, reduce onboarding friction, and foster a culture of thoughtful engineering.

How to Use It

The process of using this skill can be broken down into two primary activities: writing documentation and creating ADRs.

1. Writing Documentation

Focus on documenting the why and how, not just the what. For example, instead of only describing how to use a function, explain the design rationale behind its interface and any trade-offs involved.

Example:

## Why we use JWT for authentication

We chose JSON Web Tokens (JWT) instead of server-side sessions to enable stateless authentication across multiple services. This approach improves scalability but requires careful management of token expiration and revocation.

2. Creating Architecture Decision Records (ADRs)

ADRs are short markdown documents that capture a specific technical decision, its context, and alternatives considered. A typical ADR contains the following sections:

• Title: Short summary of the decision.
• Context: Why this decision was needed.
• Decision: The choice made.
• Consequences: The result of the decision and any trade-offs.
• Alternatives Considered: Other options that were evaluated.

Example ADR:

## ADR 001:

Adopt REST for Public API

## Context
We need to expose a public API for third-party integrations. The main requirements are simplicity, widespread tooling support, and ease of client implementation.

## Decision
We will use REST over HTTP as the architecture for the public API.

## Consequences
- Easy integration for most clients due to REST's popularity.
- Clear conventions for endpoints and resource representation.
- Potential limitations if more complex interactions are needed in the future.

## Alternatives Considered
- GraphQL: More flexible, but steeper learning curve and less mature tooling for some clients.
- gRPC: High performance, but less accessible for web-based clients.

Tips for Effective ADRs:

• Keep each ADR focused on a single decision.
• Use clear, straightforward language.
• Store ADRs in a version-controlled repository for easy access and history tracking.

When to Use It

Apply the "Documentation and ADRs" skill in the following scenarios:

• Making significant architectural or design decisions
• Selecting or replacing libraries, frameworks, or major dependencies
• Designing or modifying public APIs
• Shipping features that change user-facing behavior
• Creating or altering data models and database schemas
• Onboarding new team members or AI agents to the project
• When you find yourself explaining the same decision or reasoning multiple times

Avoid using this skill for trivial code comments, obvious implementation details, or temporary prototypes that will not be maintained.

Important Notes

• Focus on documenting decisions with lasting impact, not every minor change.
• Do not restate what is already clear from the code itself.
• Keep ADRs succinct but comprehensive - clarity is more valuable than length.
• Review and update ADRs if decisions are revisited or reversed.
• Store documentation and ADRs in an accessible location within your project's repository.
• Consistent use of this skill greatly enhances maintainability and knowledge sharing across teams and over time.

By systematically applying the "Documentation and ADRs" skill, you ensure that both humans and agents working on your codebase can understand the reasoning behind key decisions, reducing confusion and redundant effort as your project evolves.