documentation-and-adrs

Writes architecture decision records, API documentation, READMEs, and changelogs for software projects.

Updated Jul 1, 2026

Search Tags:#changelog #documentation #technical writing #adr #readme #architecture decisions #api documentation

Ready to run

npx skills add https://github.com/raishoemi/traffic-sim-v2 --skill documentation-and-adrs-raishoemi

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: documentation-and-adrs
Source: https://github.com/raishoemi/traffic-sim-v2/tree/main/.github/skills/documentation-and-adrs
Command: npx skills add https://github.com/raishoemi/traffic-sim-v2 --skill documentation-and-adrs-raishoemi

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Engineering decisions and project context are often lost because teams document only code, not the reasoning behind it, leaving future engineers and AI agents without the context needed to work safely in the codebase. ## Core Features & Use Cases - Architecture Decision Records: Provides a numbered ADR template with status lifecycle, alternatives analysis, and consequences stored in docs/decisions/. - Inline and API Documentation: Defines when to comment code (the why, not the what), JSDoc-style API documentation patterns, and OpenAPI examples for REST endpoints. - Project Documentation Standards: Covers README structure, changelog maintenance, and documentation practices tailored for AI agent context files. - Use Case: After choosing PostgreSQL over MongoDB for a new service, use this Skill to write ADR-001 capturing the context, rejected alternatives, and consequences so future contributors never re-litigate the decision. ## Quick Start Write an ADR documenting the decision to use PostgreSQL with Prisma as the primary database for this project.

Frequently Asked Questions about documentation-and-adrs

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

FAQPage Schema

How do I write an architecture decision record?▼

Create a numbered Markdown file in docs/decisions/ with sections for Status, Date, Context, Decision, Alternatives Considered, and Consequences. Record why each alternative was rejected so the reasoning survives even if the decision is later superseded.

When should I write an ADR for a software project?▼

Write an ADR when choosing frameworks or major dependencies, designing data models, selecting authentication strategies, deciding API architecture, or making any decision that would be expensive to reverse. Trivial or easily reversible choices do not need one.

What is the difference between good and bad code comments?▼

Good comments explain why code exists, such as non-obvious constraints or design rationale, while bad comments restate what the code already says. Avoid TODO comments for work you should do now and delete commented-out code instead of leaving it.

Should old ADRs be deleted when a decision changes?▼

No, old ADRs should be kept because they capture historical context. When a decision changes, write a new ADR that references and supersedes the old one, following the lifecycle from proposed to accepted to superseded or deprecated.

What should a project README include?▼

A README should include a one-paragraph project description, quick start steps, a table of available commands, an architecture overview linking to ADRs, and contributing guidelines covering coding standards and the PR process.