{"id":"f4a5a975-6eb3-4055-8afb-f5c945f8bc50","shortId":"bmNYMT","kind":"skill","title":"Documentation And Adrs","tagline":"Agent Skills skill by Addyosmani","description":"# Documentation and ADRs\n\n## Overview\n\nDocument 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.\n\n## When to Use\n\n- Making a significant architectural decision\n- Choosing between competing approaches\n- Adding or changing a public API\n- Shipping a feature that changes user-facing behavior\n- Onboarding new team members (or agents) to the project\n- When you find yourself explaining the same thing repeatedly\n\n**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.\n\n## Architecture Decision Records (ADRs)\n\nADRs capture the reasoning behind significant technical decisions. They're the highest-value documentation you can write.\n\n### When to Write an ADR\n\n- Choosing a framework, library, or major dependency\n- Designing a data model or database schema\n- Selecting an authentication strategy\n- Deciding on an API architecture (REST vs. GraphQL vs. tRPC)\n- Choosing between build tools, hosting platforms, or infrastructure\n- Any decision that would be expensive to reverse\n\n### ADR Template\n\nStore ADRs in `docs/decisions/` with sequential numbering:\n\n```markdown\n# ADR-001: Use PostgreSQL for primary database\n\n## Status\nAccepted | Superseded by ADR-XXX | Deprecated\n\n## Date\n2025-01-15\n\n## Context\nWe need a primary database for the task management application. Key requirements:\n- Relational data model (users, tasks, teams with relationships)\n- ACID transactions for task state changes\n- Support for full-text search on task content\n- Managed hosting available (for small team, limited ops capacity)\n\n## Decision\nUse PostgreSQL with Prisma ORM.\n\n## Alternatives Considered\n\n### MongoDB\n- Pros: Flexible schema, easy to start with\n- Cons: Our data is inherently relational; would need to manage relationships manually\n- Rejected: Relational data in a document store leads to complex joins or data duplication\n\n### SQLite\n- Pros: Zero configuration, embedded, fast for reads\n- Cons: Limited concurrent write support, no managed hosting for production\n- Rejected: Not suitable for multi-user web application in production\n\n### MySQL\n- Pros: Mature, widely supported\n- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling\n- Rejected: PostgreSQL is the better fit for our feature requirements\n\n## Consequences\n- Prisma provides type-safe database access and migration management\n- We can use PostgreSQL's full-text search instead of adding Elasticsearch\n- Team needs PostgreSQL knowledge (standard skill, low risk)\n- Hosting on managed service (Supabase, Neon, or RDS)\n```\n\n### ADR Lifecycle\n\n```\nPROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)\n```\n\n- **Don't delete old ADRs.** They capture historical context.\n- When a decision changes, write a new ADR that references and supersedes the old one.\n\n## Inline Documentation\n\n### When to Comment\n\nComment the *why*, not the *what*:\n\n```typescript\n// BAD: Restates the code\n// Increment counter by 1\ncounter += 1;\n\n// GOOD: Explains non-obvious intent\n// Rate limit uses a sliding window — reset counter at window boundary,\n// not on a fixed schedule, to prevent burst attacks at window edges\nif (now - windowStart > WINDOW_SIZE_MS) {\n  counter = 0;\n  windowStart = now;\n}\n```\n\n### When NOT to Comment\n\n```typescript\n// Don't comment self-explanatory code\nfunction calculateTotal(items: CartItem[]): number {\n  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);\n}\n\n// Don't leave TODO comments for things you should just do now\n// TODO: add error handling  ← Just add it\n\n// Don't leave commented-out code\n// const oldImplementation = () => { ... }  ← Delete it, git has history\n```\n\n### Document Known Gotchas\n\n```typescript\n/**\n * IMPORTANT: This function must be called before the first render.\n * If called after hydration, it causes a flash of unstyled content\n * because the theme context isn't available during SSR.\n *\n * See ADR-003 for the full design rationale.\n */\nexport function initializeTheme(theme: Theme): void {\n  // ...\n}\n```\n\n## API Documentation\n\nFor public APIs (REST, GraphQL, library interfaces):\n\n### Inline with Types (Preferred for TypeScript)\n\n```typescript\n/**\n * Creates a new task.\n *\n * @param input - Task creation data (title required, description optional)\n * @returns The created task with server-generated ID and timestamps\n * @throws {ValidationError} If title is empty or exceeds 200 characters\n * @throws {AuthenticationError} If the user is not authenticated\n *\n * @example\n * const task = await createTask({ title: 'Buy groceries' });\n * console.log(task.id); // \"task_abc123\"\n */\nexport async function createTask(input: CreateTaskInput): Promise<Task> {\n  // ...\n}\n```\n\n### OpenAPI / Swagger for REST APIs\n\n```yaml\npaths:\n  /api/tasks:\n    post:\n      summary: Create a task\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              $ref: '#/components/schemas/CreateTaskInput'\n      responses:\n        '201':\n          description: Task created\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/Task'\n        '422':\n          description: Validation error\n```\n\n## README Structure\n\nEvery project should have a README that covers:\n\n```markdown\n# Project Name\n\nOne-paragraph description of what this project does.\n\n## Quick Start\n1. Clone the repo\n2. Install dependencies: `npm install`\n3. Set up environment: `cp .env.example .env`\n4. Run the dev server: `npm run dev`\n\n## Commands\n| Command | Description |\n|---------|-------------|\n| `npm run dev` | Start development server |\n| `npm test` | Run tests |\n| `npm run build` | Production build |\n| `npm run lint` | Run linter |\n\n## Architecture\nBrief overview of the project structure and key design decisions.\nLink to ADRs for details.\n\n## Contributing\nHow to contribute, coding standards, PR process.\n```\n\n## Changelog Maintenance\n\nFor shipped features:\n\n```markdown\n# Changelog\n\n## [1.2.0] - 2025-01-20\n### Added\n- Task sharing: users can share tasks with team members (#123)\n- Email notifications for task assignments (#124)\n\n### Fixed\n- Duplicate tasks appearing when rapidly clicking create button (#125)\n\n### Changed\n- Task list now loads 50 items per page (was 20) for better UX (#126)\n```\n\n## Documentation for Agents\n\nSpecial consideration for AI agent context:\n\n- **CLAUDE.md / rules files** — Document project conventions so agents follow them\n- **Spec files** — Keep specs updated so agents build the right thing\n- **ADRs** — Help agents understand why past decisions were made (prevents re-deciding)\n- **Inline gotchas** — Prevent agents from falling into known traps\n\n## Common Rationalizations\n\n| Rationalization | Reality |\n|---|---|\n| \"The code is self-documenting\" | Code shows what. It doesn't show why, what alternatives were rejected, or what constraints apply. |\n| \"We'll write docs when the API stabilizes\" | APIs stabilize faster when you document them. The doc is the first test of the design. |\n| \"Nobody reads docs\" | Agents do. Future engineers do. Your 3-months-later self does. |\n| \"ADRs are overhead\" | A 10-minute ADR prevents a 2-hour debate about the same decision six months later. |\n| \"Comments get outdated\" | Comments on *why* are stable. Comments on *what* get outdated — that's why you only write the former. |\n\n## Red Flags\n\n- Architectural decisions with no written rationale\n- Public APIs with no documentation or types\n- README that doesn't explain how to run the project\n- Commented-out code instead of deletion\n- TODO comments that have been there for weeks\n- No ADRs in a project with significant architectural choices\n- Documentation that restates the code instead of explaining intent\n\n## Verification\n\nAfter documenting:\n\n- [ ] ADRs exist for all significant architectural decisions\n- [ ] README covers quick start, commands, and architecture overview\n- [ ] API functions have parameter and return type documentation\n- [ ] Known gotchas are documented inline where they matter\n- [ ] No commented-out code remains\n- [ ] Rules files (CLAUDE.md etc.) are current and accurate","tags":["documentation","and","adrs","agent","skills","addyosmani"],"capabilities":["skill","source-addyosmani","category-agent-skills"],"categories":["agent-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/addyosmani/agent-skills/documentation-and-adrs","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"install_from":"skills.sh"}},"qualityScore":"0.300","qualityRationale":"deterministic score 0.30 from registry signals: · indexed on skills.sh · published under addyosmani/agent-skills","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T09:40:27.458Z","embedding":null,"createdAt":"2026-04-18T20:31:54.776Z","updatedAt":"2026-04-22T09:40:27.458Z","lastSeenAt":"2026-04-22T09:40:27.458Z","tsv":"'-001':222 '-003':610 '-01':238,838 '-15':239 '-20':839 '/api/tasks':706 '/components/schemas/createtaskinput':719 '/components/schemas/task':729 '0':513,540 '1':474,476,758 '1.2.0':836 '10':1003 '123':850 '124':856 '125':866 '126':881 '2':762,1008 '20':877 '200':670 '201':721 '2025':237,837 '3':767,993 '4':774 '422':730 '50':872 'abc123':691 'accept':229,427 'access':391 'accur':1144 'acid':261 'ad':80,406,840 'add':124,554,558 'addyosmani':8 'adr':3,11,143,144,166,211,214,221,233,424,435,447,609,818,912,999,1005,1080,1100 'adr-xxx':232 'agent':4,63,100,884,889,898,907,914,928,987 'ai':888 'alreadi':131 'altern':52,291,953 'api':85,188,622,626,703,966,968,1048,1115 'appear':860 'appli':959 'applic':250,353 'application/json':716,726 'approach':79 'architectur':74,140,189,805,1041,1086,1105,1113 'assign':855 'async':693 'attack':502 'authent':183,679 'authenticationerror':673 'avail':278,605 'await':683 'bad':467 'behavior':94 'behind':148 'better':364,378,879 'boundari':493 'brief':806 'build':197,797,799,908 'built':41,47 'burst':501 'button':865 'buy':686 'calculatetot':529 'call':583,589 'capac':284 'captur':22,145,437 'cartitem':531 'category-agent-skills' 'caus':593 'chang':82,90,266,443,867 'changelog':829,835 'charact':671 'choic':1087 'choos':76,167,195 'claude.md':891,1139 'click':863 'clone':759 'code':17,37,121,130,470,527,566,825,939,944,1067,1092,1135 'codebas':67 'command':782,783,1111 'comment':125,459,460,519,523,545,564,1018,1021,1026,1065,1072,1133 'commented-out':563,1064,1132 'common':934 'compet':78 'complex':322 'con':301,335,361 'concurr':337 'configur':330 'consequ':384 'consid':54,292 'consider':886 'console.log':688 'const':567,681 'constraint':27,958 'content':275,598,715,725 'context':26,56,240,439,602,890 'contribut':821,824 'convent':896 'counter':472,475,490,512 'cover':743,1108 'cp':771 'creat':638,653,709,724,864 'createtask':684,695 'createtaskinput':697 'creation':645 'current':1142 'data':176,254,303,315,325,646 'databas':179,227,245,390 'date':236 'debat':1010 'decid':185,924 'decis':14,36,75,141,151,204,285,442,815,918,1014,1042,1106 'delet':433,569,1070 'depend':173,764 'deprec':235,430 'descript':649,722,731,750,784 'design':174,614,814,983 'detail':820 'dev':777,781,787 'develop':789 'doc':136,963,976,986 'docs/decisions':216 'document':1,9,13,21,42,119,158,318,456,574,623,882,894,943,973,1051,1088,1099,1122,1126 'doesn':948,1056 'duplic':326,858 'easi':297 'ecosystem':372 'edg':505 'elasticsearch':407 'email':851 'embed':331 'empti':667 'engin':990 'env':773 'env.example':772 'environ':770 'error':555,733 'essenti':58 'etc':1140 'everi':736 'exampl':680 'exceed':669 'exist':1101 'expens':208 'explain':43,108,478,1058,1095 'explanatori':526 'export':616,692 'face':93 'fall':930 'fast':332 'faster':970 'featur':88,382,833 'file':893,902,1138 'find':106 'first':586,979 'fit':379 'fix':497,857 'flag':1040 'flash':595 'flexibl':295 'follow':899 'former':1038 'framework':169 'full':270,368,401,613 'full-text':269,367,400 'function':528,580,617,694,1116 'futur':60,989 'generat':658 'get':1019,1029 'git':571 'good':477 'gotcha':576,926,1124 'graphql':192,628 'groceri':687 'handl':556 'help':913 'highest':156 'highest-valu':155 'histor':438 'histori':573 'host':199,277,342,416 'hour':1009 'human':61 'hydrat':591 'id':659 'import':578 'increment':471 'infrastructur':202 'inher':305 'initializethem':618 'inlin':455,631,925,1127 'input':643,696 'instal':763,766 'instead':404,1068,1093 'intent':482,1096 'interfac':630 'isn':603 'item':530,536,873 'item.price':538 'item.quantity':539 'items.reduce':534 'join':323 'json':365 'keep':903 'key':251,813 'knowledg':411 'known':575,932,1123 'later':996,1017 'lead':320 'leav':543,562 'led':33 'librari':170,629 'lifecycl':425 'limit':282,336,484 'link':816 'lint':802 'linter':804 'list':869 'll':961 'load':871 'low':414 'made':920 'mainten':830 'major':172 'make':71 'manag':249,276,310,341,394,418 'manual':312 'markdown':220,744,834 'matter':1130 'matur':358 'member':98,849 'migrat':393 'minut':1004 'model':177,255 'mongodb':293 'month':995,1016 'months-lat':994 'ms':511 'multi':350 'multi-us':349 'must':581 'mysql':356 'name':746 'need':242,308,409 'neon':421 'new':96,446,640 'nobodi':984 'non':480 'non-obvi':479 'notif':852 'npm':765,779,785,791,795,800 'number':219,532 'obvious':120,481 'off':31 'old':434,453 'oldimplement':568 'onboard':95 'one':454,748 'one-paragraph':747 'op':283 'openapi':699 'option':650 'orm':290 'outdat':1020,1030 'overhead':1001 'overview':12,807,1114 'page':875 'paragraph':749 'param':642 'paramet':1118 'past':917 'path':705 'per':874 'platform':200 'post':707 'postgresql':224,287,362,375,398,410 'pr':827 'prefer':634 'prevent':500,921,927,1006 'primari':226,244 'prisma':289,385 'process':828 'product':344,355,798 'project':103,737,745,754,810,895,1063,1083 'promis':698 'propos':426 'pros':294,328,357 'prototyp':139 'provid':386 'public':84,625,1047 'quick':756,1109 'rapid':862 'rate':483 'ration':935,936 'rational':615,1046 'rds':423 're':153,923 're-decid':922 'read':334,985 'readm':734,741,1054,1107 'realiti':937 'reason':147 'record':142 'red':1039 'ref':718,728 'refer':449 'reject':313,345,374,955 'relat':253,306,314 'relationship':260,311 'remain':1136 'render':587 'repeat':112 'repo':761 'requestbodi':712 'requir':252,383,648,713 'reset':489 'respons':720 'rest':190,627,702 'restat':127,468,1090 'return':533,651,1120 'revers':210 'right':910 'risk':415 'rule':892,1137 'run':775,780,786,793,796,801,803,1061 'safe':389 'say':132 'schedul':498 'schema':180,296,717,727 'search':272,370,403 'see':608 'select':181 'self':525,942,997 'self-docu':941 'self-explanatori':524 'sequenti':218 'server':657,778,790 'server-gener':656 'servic':419 'set':768 'share':842,845 'ship':86,832 'show':38,945,950 'signific':73,149,1085,1104 'six':1015 'size':510 'skill':5,6,413 'slide':487 'small':280 'source-addyosmani' 'spec':901,904 'special':885 'sqlite':327 'ssr':607 'stabil':967,969 'stabl':1025 'standard':412,826 'start':299,757,788,1110 'state':265 'status':228 'store':213,319 'strategi':184 'structur':735,811 'suitabl':347 'sum':535,537 'summari':708 'supabas':420 'supersed':230,428,451 'support':267,339,360,366 'swagger':700 'task':248,257,264,274,641,644,654,682,690,711,723,841,846,854,859,868 'task.id':689 'team':97,258,281,408,848 'technic':150 'templat':212 'test':792,794,980 'text':271,369,402 'theme':601,619,620 'thing':111,547,911 'throw':662,672 'throwaway':138 'timestamp':661 'titl':647,665,685 'todo':544,553,1071 'tool':198,373 'trade':30 'trade-off':29 'transact':262 'trap':933 'trpc':194 'true':714 'type':388,633,1053,1121 'type-saf':387 'typescript':466,520,577,636,637 'understand':915 'unstyl':597 'updat':905 'use':70,116,223,286,397,485 'user':92,256,351,676,843 'user-fac':91 'ux':880 'valid':732 'validationerror':663 'valu':157 'valuabl':20 'verif':1097 'void':621 'vs':191,193 'way':49 'web':352 'week':1078 'wide':359 'window':488,492,504,509 'windowstart':508,514 'work':64 'would':206,307 'write':135,161,164,338,444,962,1036 'written':1045 'xxx':234 'yaml':704 'zero':329","prices":[{"id":"c6f22d35-5018-4c1d-b177-bad150edc0a8","listingId":"f4a5a975-6eb3-4055-8afb-f5c945f8bc50","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"addyosmani","category":"agent-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T20:31:54.776Z"}],"sources":[{"listingId":"f4a5a975-6eb3-4055-8afb-f5c945f8bc50","source":"github","sourceId":"addyosmani/agent-skills/documentation-and-adrs","sourceUrl":"https://github.com/addyosmani/agent-skills/tree/main/skills/documentation-and-adrs","isPrimary":false,"firstSeenAt":"2026-04-18T21:52:59.121Z","lastSeenAt":"2026-04-22T06:52:42.197Z"},{"listingId":"f4a5a975-6eb3-4055-8afb-f5c945f8bc50","source":"skills_sh","sourceId":"addyosmani/agent-skills/documentation-and-adrs","sourceUrl":"https://skills.sh/addyosmani/agent-skills/documentation-and-adrs","isPrimary":true,"firstSeenAt":"2026-04-18T20:31:54.776Z","lastSeenAt":"2026-04-22T09:40:27.458Z"}],"details":{"listingId":"f4a5a975-6eb3-4055-8afb-f5c945f8bc50","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"addyosmani","slug":"documentation-and-adrs","source":"skills_sh","category":"agent-skills","skills_sh_url":"https://skills.sh/addyosmani/agent-skills/documentation-and-adrs"},"updatedAt":"2026-04-22T09:40:27.458Z"}}