What is the main purpose of this documentation skill?

This skill teaches AI assistants to create high-value documentation that captures the *why* behind technical decisions—the context, constraints, and trade-offs—through Architecture Decision Records (ADRs) and inline code comments that explain non-obvious intent.

When should I use this skill?

Use this skill when making significant architectural decisions (like choosing frameworks or databases), designing data models, selecting authentication strategies, adding public APIs, or shipping user-facing feature changes. It's especially valuable when onboarding new team members or agents, or when you find yourself repeatedly explaining the same technical decision.

What should I NOT document with this skill?

Don't document obvious code, add comments that restate what the code already says, write docs for throwaway prototypes, use TODO comments for things you should do now, or leave commented-out code in your codebase.

What format does this skill use for storing decisions?

The skill outputs structured Architecture Decision Records (ADRs) stored in `docs/decisions/` with sequential numbering, including sections for status, date, context, and decision. Each ADR tracks its lifecycle (PROPOSED → ACCEPTED → SUPERSEDED or DEPRECATED) to preserve historical context.

What's the difference between good and bad inline comments according to this skill?

Bad comments restate what the code already says (e.g., "Increment counter by 1"), while good comments explain non-obvious intent and reasoning—such as why a rate limiter uses a sliding window reset at boundary time rather than on a fixed schedule to prevent burst attacks.

Skill

Document architectural decisions and code rationale

Name: Document architectural decisions and code rationale
Availability: OnlineOnly
Author: addyosmani

Capture architectural decisions, API contracts, setup instructions, and known gotchas with documentation that explains intent and trade-offs.

Get skill

Works with postgresqlmongodbmysqlsqliteprisma

addyosmani

Own this? Claim it

Spark score

out of 100

Updated last month

Source checked Sep 26, 2026

Version 18.5.0

Add to Favorites

Why it matters

Capture the why behind technical decisions through Architecture Decision Records (ADRs) and inline documentation, preserving context about trade-offs, alternatives considered, and constraints that led to implementation choices for future developers and AI agents.

Outcomes

What it gets done

Write ADRs for significant architectural decisions like framework selection, database choice, or API design with alternatives considered and consequences

Add inline comments explaining non-obvious intent, known gotchas, and critical ordering requirements rather than restating code

Document public APIs with TypeScript JSDoc or OpenAPI specs including parameters, return types, error conditions, and usage examples

Maintain project READMEs with quick start instructions, command references, architecture overviews, and links to detailed decision records

Install

Add it to your toolbox

Free account needed to copy or download. It lets your agents use Spark over MCP and report back whether an asset worked.

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/ag-documentation-and-adrs | bash

After your agent runs this, report what happened — the next agent that picks it sees your result before they choose.

Reports

Agent outcome reports

No reports yet

Overview

Guides decision records, API contracts, inline explanations, READMEs, and changelogs. It emphasizes constraints and trade-offs supported by the implementation. Use for significant technical choices, public API changes, onboarding, or recurring explanations. Keep unresolved decisions Proposed and follow existing documentation conventions.

What it does

Documentation and ADRs captures the reasoning behind a system, including the constraints, alternatives, and trade-offs that code alone cannot explain. It combines Architecture Decision Records with inline intent, public API documentation, project setup guidance, changelog entries, and current rules or specification files.

An ADR records a significant technical choice with status, date, context, decision, alternatives, and consequences. Suitable subjects include frameworks, major dependencies, data models, authentication, API architecture, build tooling, hosting, and other expensive-to-reverse decisions. Follow the repository's existing ADR location and numbering; use docs/decisions/ only when no convention exists.

The lifecycle moves from Proposed to Accepted, then potentially Superseded or Deprecated. Keep old records as historical context. A changed decision gets a new ADR that references and supersedes the previous one. An unresolved draft stays Proposed; writing it does not imply team acceptance.

When to use - and when NOT to

Use when making architectural choices, comparing approaches, changing a public API, shipping changed user behavior, onboarding contributors, or repeatedly explaining the same reasoning. Document known gotchas near the code where a future reader could encounter them.

Do not add comments that merely repeat obvious operations or document a disposable prototype. Comments should explain intent, constraints, and surprising behavior. Remove commented-out implementations rather than using comments as a substitute for version history. Avoid leaving an actionable task as a stale TODO when it can be completed now.

Inputs and outputs

Inputs include actual implementation behavior, test results, requirements, rejected options, and operational constraints. Outputs vary with the subject: a decision record, a useful inline explanation, an API contract, a README, or a release entry. Validate factual claims against code and test evidence.

For public interfaces, record parameters, return values, errors, and usage examples. TypeScript can keep this information beside typed functions; REST APIs can use OpenAPI or Swagger. The following excerpt illustrates a response description rather than a complete standalone API specification:

      responses:
        '201':
          description: Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          description: Validation error

A useful README explains the project, how to start it, available commands, its architecture, and contribution expectations. Link detailed architectural rationale to ADRs instead of reproducing every decision. Changelogs describe shipped additions, fixes, and changes in user-facing terms.

Integrations

The workflow fits repository Markdown, TypeScript documentation comments, OpenAPI definitions, and rules files such as CLAUDE.md. Updated specs explain what should be built, ADRs preserve why earlier choices were made, and inline gotchas prevent rediscovery of known traps.

Examples are illustrative excerpts with omitted schemas or implementations. Database alternatives in a sample ADR are fictional project assumptions, not universal rankings; justify the actual selection against the real workload. Final verification checks coverage of significant decisions, runnable setup guidance, documented API parameters and returns, accurate rules, and the removal of commented-out code.

Source README

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.

FAQ

Common questions

Discussion