documentation-and-adrs

Name: documentation-and-adrs
Author: addyosmani

byaddyosmani· 31 skills

Installs

17k

Stars

80k

Forks

8.7k

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.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/addyosmani/agent-skills" --skill "addyosmani/agent-skills/documentation-and-adrs"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/addyosmani/agent-skills" that are relevant to the current task. Run `npx skills add "https://github.com/addyosmani/agent-skills"` and select the relevant skills, then follow their instructions.

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 items.reduce((sum, item) => sum + item.price * item.quantity, 0);
123	}
124
125	// Don't leave TODO comments for things you should just do now
126	// TODO: add error handling ← Just add it
127
128	// Don't leave commented-out code
129	// const oldImplementation = () => { ... } ← Delete it, git has history
130	```
131
132	### Document Known Gotchas
133
134	```typescript
135	/**
136	* IMPORTANT: This function must be called before the first render.
137	* If called after hydration, it causes a flash of unstyled content
138	* because the theme context isn't available during SSR.
139	*
140	* See ADR-003 for the full design rationale.
141	*/
142	export function initializeTheme(theme: Theme): void {
143	// ...
144	}
145	```
146
147	## API Documentation
148
149	For public APIs (REST, GraphQL, library interfaces):
150
151	### Inline with Types (Preferred for TypeScript)
152
153	```typescript
154	/**
155	* Creates a new task.
156	*
157	* @param input - Task creation data (title required, description optional)
158	* @returns The created task with server-generated ID and timestamps
159	* @throws {ValidationError} If title is empty or exceeds 200 characters
160	* @throws {AuthenticationError} If the user is not authenticated
161	*
162	* @example
163	* const task = await createTask({ title: 'Buy groceries' });
164	* console.log(task.id); // "task_abc123"
165	*/
166	export async function createTask(input: CreateTaskInput): Promise<Task> {
167	// ...
168	}
169	```
170
171	### OpenAPI / Swagger for REST APIs
172
173	```yaml
174	paths:
175	/api/tasks:
176	post:
177	summary: Create a task
178	requestBody:
179	required: true
180	content:
181	application/json:
182	schema:
183	$ref: '#/components/schemas/CreateTaskInput'
184	responses:
185	'201':
186	description: Task created
187	content:
188	application/json:
189	schema:
190	$ref: '#/components/schemas/Task'
191	'422':
192	description: Validation error
193	```
194
195	## README Structure
196
197	Every project should have a README that covers:
198
199	```markdown
200	# Project Name
201
202	One-paragraph description of what this project does.
203
204	## Quick Start
205	1. Clone the repo
206	2. Install dependencies: `npm install`
207	3. Set up environment: `cp .env.example .env`
208	4. Run the dev server: `npm run dev`
209
210	## Commands
211	\| Command \| Description \|
212	\|---------\|-------------\|
213	\| `npm run dev` \| Start development server \|
214	\| `npm test` \| Run tests \|
215	\| `npm run build` \| Production build \|
216	\| `npm run lint` \| Run linter \|
217
218	## Architecture
219	Brief overview of the project structure and key design decisions.
220	Link to ADRs for details.
221
222	## Contributing
223	How to contribute, coding standards, PR process.
224	```
225
226	## Changelog Maintenance
227
228	For shipped features:
229
230	```markdown
231	# Changelog
232
233	## [1.2.0] - 2025-01-20
234	### Added
235	- Task sharing: users can share tasks with team members (#123)
236	- Email notifications for task assignments (#124)
237
238	### Fixed
239	- Duplicate tasks appearing when rapidly clicking create button (#125)
240
241	### Changed
242	- Task list now loads 50 items per page (was 20) for better UX (#126)
243	```
244
245	## Documentation for Agents
246
247	Special consideration for AI agent context:
248
249	- CLAUDE.md / rules files — Document project conventions so agents follow them
250	- Spec files — Keep specs updated so agents build the right thing
251	- ADRs — Help agents understand why past decisions were made (prevents re-deciding)
252	- Inline gotchas — Prevent agents from falling into known traps
253
254	## Common Rationalizations
255
256	\| Rationalization \| Reality \|
257	\|---\|---\|
258	\| "The code is self-documenting" \| Code shows what. It doesn't show why, what alternatives were rejected, or what constraints apply. \|
259	\| "We'll write docs when the API stabilizes" \| APIs stabilize faster when you document them. The doc is the first test of the design. \|
260	\| "Nobody reads docs" \| Agents do. Future engineers do. Your 3-months-later self does. \|
261	\| "ADRs are overhead" \| A 10-minute ADR prevents a 2-hour debate about the same decision six months later. \|
262	\| "Comments get outdated" \| Comments on why are stable. Comments on what get outdated — that's why you only write the former. \|
263
264	## Red Flags
265
266	- Architectural decisions with no written rationale
267	- Public APIs with no documentation or types
268	- README that doesn't explain how to run the project
269	- Commented-out code instead of deletion
270	- TODO comments that have been there for weeks
271	- No ADRs in a project with significant architectural choices
272	- Documentation that restates the code instead of explaining intent
273
274	## Verification
275
276	After documenting:
277
278	- [ ] ADRs exist for all significant architectural decisions
279	- [ ] README covers quick start, commands, and architecture overview
280	- [ ] API functions have parameter and return type documentation
281	- [ ] Known gotchas are documented inline where they matter
282	- [ ] No commented-out code remains
283	- [ ] Rules files (CLAUDE.md etc.) are current and accurate

6 picks

Type

Run `npx skills use "https://github.com/addyosmani/agent-skills" --skill "addyosmani/agent-skills/documentation-and-adrs"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/addyosmani/agent-skills" that are relevant to the current task. Run `npx skills add "https://github.com/addyosmani/agent-skills"` and select the relevant skills, then follow their instructions.

documentation-and-adrs

How to install documentation-and-adrs?

Related

documentation-and-adrs

How to install documentation-and-adrs?

Related