Question 1

How do I write an architecture decision record?

Accepted Answer

Create a numbered Markdown file in docs/decisions/ with sections for Status, Date, Context, Decision, Alternatives Considered, and Consequences. Document each rejected alternative with its pros, cons, and the reason it was not chosen.

Question 2

When should I write an ADR?

Accepted Answer

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.

Question 3

Should old ADRs be deleted when decisions change?

Accepted Answer

No, old ADRs should be kept because they capture historical context. When a decision changes, write a new ADR that references and supersedes the previous one, following the Proposed to Accepted to Superseded lifecycle.

Question 4

What is the difference between good and bad code comments?

Accepted Answer

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.

Question 5

When should I not write documentation?

Accepted Answer

Skip documentation for obvious self-explanatory code, throwaway prototypes, and comments that merely restate what the code does. Focus documentation effort on decisions, public APIs, known gotchas, and context future readers cannot infer.

documentation-and-adrs

SYSTEM DOCUMENTATION & REQUIREMENTS

Frequently Asked Questions about documentation-and-adrs

Related Skills

spike

architecture-decision

context-guidance-audit

architecture-decision-records