documentation-and-adrs

An Architecture Decision Record (ADR) preserves the context, rationale, alternatives, and consequences of engineering decisions. You should write an ADR when making architectural trade-offs or public API changes to ensure future developers understand the why behind a decision.

To write an ADR, create a file under docs/decisions/ that states the decision, lists alternatives considered, records the chosen option, and describes consequences and verification steps. This captures context to prevent engineers from repeating past mistakes.

A README for onboarding should include a clear project structure, setup instructions, and actionable guidance. Maintaining a clear README alongside an updated changelog supports onboarding and maintenance by making project context discoverable.

Document API changes by adding OpenAPI or Swagger snippets for public endpoints and maintaining an actionable changelog. This records public API modifications and feature trade-offs, ensuring safe and consistent changes by future developers.

Document non-obvious intent and known gotchas through inline comments that explain the why behind specific logic. This prevents agents or engineers from repeating past mistakes when making code changes in areas with hidden trade-offs.

A post-documentation verification checklist should confirm ADR coverage, README completeness, API docs exist for public endpoints, known gotchas are documented, and commented-out code is removed to ensure safe and consistent changes.