domains / families / software-engineering / documentation-and-adrs

documentation-and-adrs

authentic

Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning behind a design choice, when changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.

When to use

• Making a significant architectural decision
• Choosing between competing approaches
• Adding or changing a public API
• Shipping a feature that changes user-facing behavior
• Onboarding new team members (or agents) to the project
• When you find yourself explaining the same thing repeatedly

When not to use

• documenting obvious code
• adding comments that restate what the code says
• writing docs for throwaway prototypes

Skill page

Source