documentation-and-adrs

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

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

No, never delete old ADRs because they capture historical context. When a decision changes, write a new ADR that references and supersedes the old one, preserving the full decision timeline.

Comment the why, not the what. Explain non-obvious intent, constraints, and known gotchas rather than restating what the code does. Avoid TODO comments for work you should do now and delete commented-out code since git preserves history.

Use JSDoc-style comments with @param, @returns, @throws, and @example tags directly on exported functions. For REST APIs, maintain an OpenAPI/Swagger specification describing endpoints, request schemas, and response codes.

Skip documentation for self-explanatory code, throwaway prototypes, and comments that merely restate what the code already says. Documentation should capture intent, trade-offs, and constraints that code cannot express.