documentation-and-adrs

Name: documentation-and-adrs
Author: addyosmani

15kinstalls8.6kforks

How to install documentation-and-adrs?

addyosmani/agent-skills/documentation-and-adrs

$npx -y skills add addyosmani/agent-skills --skill documentation-and-adrs

Installs into the current project.

Summary

Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.

Files · 1

View on GitHub

SKILL.md

1	# Documentation and ADRs
2
3	## Overview
4
5	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.
6
7	## When to Use
8
9	- Making a significant architectural decision
10	- Choosing between competing approaches
11	- Adding or changing a public API
12	- Shipping a feature that changes user-facing behavior
13	- Onboarding new team members (or agents) to the project
14	- When you find yourself explaining the same thing repeatedly
15
16	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.
17
18	## Architecture Decision Records (ADRs)
19
20	ADRs capture the reasoning behind significant technical decisions. They're the highest-value documentation you can write.
21
22	### When to Write an ADR
23
24	- Choosing a framework, library, or major dependency
25	- Designing a data model or database schema
26	- Selecting an authentication strategy
27	- Deciding on an API architecture (REST vs. GraphQL vs. tRPC)
28	- Choosing between build tools, hosting platforms, or infrastructure
29	- Any decision that would be expensive to reverse
30
31	### Match the existing convention first
32
33	Before creating an ADR, inspect the available repository context for an established convention — existing ADRs, project instructions, and ADR-related configuration or tooling (e.g. an `.adr-dir` file). An established convention overrides the defaults below. Match:
34
35	- Location and format — e.g. `docs/adr/.md`, `Documentation/Decisions/.rst`, a MADR layout, or an `adr-tools` setup. Match the existing directory, file extension, and markup (Markdown vs reStructuredText).
36	- Numbering and naming — continue the existing sequence and filename pattern (`ADR-004-Title.rst`, `0004-title.md`, …); don't restart at 001 or introduce a second scheme.
37	- Section headings — reuse the project's heading set rather than imposing this template's.
38
39	If the available evidence conflicts, surface the conflict rather than silently introducing another scheme. Only when no convention can be established do you apply the default below.
40
41	### ADR Template
42
43	Store ADRs in `docs/decisions/` with sequential numbering (unless the project already uses another location — see above):
44
45	```markdown
46	# ADR-001: Use PostgreSQL for primary database
47
48	## Status
49	Accepted \| Superseded by ADR-XXX \| Deprecated
50
51	## Date
52	2025-01-15
53
54	## Context
55	We need a primary database for the task management application. Key requirements:
56	- Relational data model (users, tasks, teams with relationships)
57	- ACID transactions for task state changes
58	- Support for full-text search on task content
59	- Managed hosting available (for small team, limited ops capacity)
60
61	## Decision
62	Use PostgreSQL with Prisma ORM.
63
64	## Alternatives Considered
65
66	### MongoDB
67	- Pros: Flexible schema, easy to start with
68	- Cons: Our data is inherently relational; would need to manage relationships manually
69	- Rejected: Relational data in a document store leads to complex joins or data duplication
70
71	### SQLite
72	- Pros: Zero configuration, embedded, fast for reads
73	- Cons: Limited concurrent write support, no managed hosting for production
74	- Rejected: Not suitable for multi-user web application in production
75
76	### MySQL
77	- Pros: Mature, widely supported
78	- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling
79	- Rejected: PostgreSQL is the better fit for our feature requirements
80
81	## Consequences
82	- Prisma provides type-safe database access and migration management
83	- We can use PostgreSQL's full-text search instead of adding Elasticsearch
84	- Team needs PostgreSQL knowledge (standard skill, low risk)
85	- Hosting on managed service (Supabase, Neon, or RDS)
86	```
87
88	### ADR Lifecycle
89
90	```
91	PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)
92	```
93
94	- Don't delete old ADRs. They capture historical context.
95	- When a decision changes, write a new ADR that references and supersedes the old one.
96
97	## Inline Documentation
98
99	### When to Comment
100
101	Comment the why, not the what:
102
103	```typescript
104	// BAD: Restates the code
105	// Increment counter by 1
106	counter += 1;
107
108	// GOOD: Explains non-obvious intent
109	// Rate limit uses a sliding window — reset counter at window boundary,
110	// not on a fixed schedule, to prevent burst attacks at window edges
111	if (now - windowStart > WINDOW_SIZE_MS) {
112	counter = 0;
113	windowStart = now;
114	}
115	```
116
117	### When NOT to Comment
118
119	```typescript
120	// Don't comment self-explanatory code
121	function calculateTotal(items: CartItem[]): number {
122	return

People who liked this also viewed

6 picks

Type

documentation-and-adrs

15kinstalls8.6kforks

View on GitHub

How to install documentation-and-adrs?

addyosmani/agent-skills/documentation-and-adrs

$npx -y skills add addyosmani/agent-skills --skill documentation-and-adrs

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Documentation and ADRs
2
3	## Overview
4
5	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.
6
7	## When to Use
8
9	- Making a significant architectural decision
10	- Choosing between competing approaches
11	- Adding or changing a public API
12	- Shipping a feature that changes user-facing behavior
13	- Onboarding new team members (or agents) to the project
14	- When you find yourself explaining the same thing repeatedly
15
16	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.
17
18	## Architecture Decision Records (ADRs)
19
20	ADRs capture the reasoning behind significant technical decisions. They're the highest-value documentation you can write.
21
22	### When to Write an ADR
23
24	- Choosing a framework, library, or major dependency
25	- Designing a data model or database schema
26	- Selecting an authentication strategy
27	- Deciding on an API architecture (REST vs. GraphQL vs. tRPC)
28	- Choosing between build tools, hosting platforms, or infrastructure
29	- Any decision that would be expensive to reverse
30
31	### Match the existing convention first
32
33	Before creating an ADR, inspect the available repository context for an established convention — existing ADRs, project instructions, and ADR-related configuration or tooling (e.g. an `.adr-dir` file). An established convention overrides the defaults below. Match:
34
35	- Location and format — e.g. `docs/adr/.md`, `Documentation/Decisions/.rst`, a MADR layout, or an `adr-tools` setup. Match the existing directory, file extension, and markup (Markdown vs reStructuredText).
36	- Numbering and naming — continue the existing sequence and filename pattern (`ADR-004-Title.rst`, `0004-title.md`, …); don't restart at 001 or introduce a second scheme.
37	- Section headings — reuse the project's heading set rather than imposing this template's.
38
39	If the available evidence conflicts, surface the conflict rather than silently introducing another scheme. Only when no convention can be established do you apply the default below.
40
41	### ADR Template
42
43	Store ADRs in `docs/decisions/` with sequential numbering (unless the project already uses another location — see above):
44
45	```markdown
46	# ADR-001: Use PostgreSQL for primary database
47
48	## Status
49	Accepted \| Superseded by ADR-XXX \| Deprecated
50
51	## Date
52	2025-01-15
53
54	## Context
55	We need a primary database for the task management application. Key requirements:
56	- Relational data model (users, tasks, teams with relationships)
57	- ACID transactions for task state changes
58	- Support for full-text search on task content
59	- Managed hosting available (for small team, limited ops capacity)
60
61	## Decision
62	Use PostgreSQL with Prisma ORM.
63
64	## Alternatives Considered
65
66	### MongoDB
67	- Pros: Flexible schema, easy to start with
68	- Cons: Our data is inherently relational; would need to manage relationships manually
69	- Rejected: Relational data in a document store leads to complex joins or data duplication
70
71	### SQLite
72	- Pros: Zero configuration, embedded, fast for reads
73	- Cons: Limited concurrent write support, no managed hosting for production
74	- Rejected: Not suitable for multi-user web application in production
75
76	### MySQL
77	- Pros: Mature, widely supported
78	- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling
79	- Rejected: PostgreSQL is the better fit for our feature requirements
80
81	## Consequences
82	- Prisma provides type-safe database access and migration management
83	- We can use PostgreSQL's full-text search instead of adding Elasticsearch
84	- Team needs PostgreSQL knowledge (standard skill, low risk)
85	- Hosting on managed service (Supabase, Neon, or RDS)
86	```
87
88	### ADR Lifecycle
89
90	```
91	PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)
92	```
93
94	- Don't delete old ADRs. They capture historical context.
95	- When a decision changes, write a new ADR that references and supersedes the old one.
96
97	## Inline Documentation
98
99	### When to Comment
100
101	Comment the why, not the what:
102
103	```typescript
104	// BAD: Restates the code
105	// Increment counter by 1
106	counter += 1;
107
108	// GOOD: Explains non-obvious intent
109	// Rate limit uses a sliding window — reset counter at window boundary,
110	// not on a fixed schedule, to prevent burst attacks at window edges
111	if (now - windowStart > WINDOW_SIZE_MS) {
112	counter = 0;
113	windowStart = now;
114	}
115	```
116
117	### When NOT to Comment
118
119	```typescript
120	// Don't comment self-explanatory code
121	function calculateTotal(items: CartItem[]): number {
122	return

People who liked this also viewed

6 picks

Type