skills.rest
Coldaine
ColdaineCOMMUNITY
Explore all skills by this author →
GitHub

documentation-and-adrs

Documentescribe architectural decisions and rationale in ADR format with lifecycle states.

Updated Aug 23, 2026
Search Tags:#documentation#adr#engineering#docs#architecture-decisions#decision-records
One-click install
npx skills add https://github.com/Coldaine/agent-skills-vscode --skill documentation-and-adrs-coldaine
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: documentation-and-adrs
Source: https://github.com/Coldaine/agent-skills-vscode/tree/main/skills/documentation-and-adrs
Command: npx skills add https://github.com/Coldaine/agent-skills-vscode --skill documentation-and-adrs-coldaine

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

ADRs codify decisions, rationale, and alternatives to prevent knowledge loss and misalignment in evolving systems.

Core Features & Use Cases

  • Standard ADR format (ADR-xxx): context, decision, alternatives, consequences
  • Lifecycle management: Proposed, Accepted, Deprecated, Superseded
  • Co-location with code: stored near the codebase for traceability
  • Documentation of architectural decisions to onboarding and audits

Quick Start

Create a new Architecture Decision Record (ADR) documenting the rationale, alternatives considered, and consequences for a recent design decision.

Frequently Asked Questions about documentation-and-adrs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is an architecture decision record and when should I document one?▼

An architecture decision record (ADR) documents a design decision's context, alternatives, and consequences. You should create an ADR at design time when teams need to capture rationale and track changes to prevent knowledge loss in evolving software projects.

How do I structure an ADR to capture context and consequences?▼

To structure an ADR, use the standard format containing Context, Decision, Alternatives, and Consequences. This format codifies decisions and rationale near the codebase, ensuring traceability and preventing misalignment across software engineering teams.

Can I track ADR lifecycle states like deprecated or superseded decisions?▼

Yes, you can track ADR lifecycle states including Proposed, Accepted, Deprecated, and Superseded. Managing these states supports tracking changes across software projects, ensuring past architecture decisions remain visible even when replaced.

What is the best way to store ADRs for codebase traceability?▼

The best way to store ADRs is co-locating them near the codebase within your software projects. Storing decisions near the code ensures traceability during onboarding and audits while preventing knowledge loss in evolving systems.

Do I need any specific dependencies to start writing architecture decision records?▼

No dependencies are required to start writing architecture decision records. You can document your design decisions and rationale immediately using the standard ADR format to prevent misalignment in your evolving systems.

Why document architecture rationale and alternatives instead of just writing code?▼

Documenting architecture rationale and alternatives prevents knowledge loss and misalignment in evolving systems. ADRs codify decisions so teams understand why specific choices were made, which is critical for onboarding and audits.

Related Skills

Explore More Software Engineering Skills→
learnzdevelopmenthublearnzdevelopmenthub
1

dev-adr

Generate structured ADR markdown files with context, alternatives, and rationale.

Community
Advanced
wesleyegbertowesleyegberto
3

architecture-decision-records

Document architectural decisions as structured ADR files under docs/adr.

Community
Advanced
ChrstprJohnChrstprJohn

architecture-decision-records

Document and manage Architecture Decision Records with Markdown templates and frontmatter metadata.

Community
Advanced
boomNDSboomNDS

architecture

Capture architectural decisions with ADR templates and rationale.

Community
Basic