Create an Architectural Decision Record

An ADR is a short, durable document that captures a significant technical choice: what was decided, why, what was rejected, and what consequences to expect. Its primary audience is future engineers — months or years later — who need to understand why the codebase is shaped the way it is, not just how it works. Writing an ADR also forces you to surface hidden assumptions and trade-offs at the moment they are freshest.

Process

1. Extract context from the conversation

Read the conversation carefully before asking anything. Identify:

• The decision being made (or recently made)
• The problem or constraint that forced it
• Alternatives that were considered or dismissed
• The author (git config user.name / git config user.email if available, otherwise ask)

If a critical piece is still missing after reading the context, ask one focused question. Asking multiple questions at once creates friction and often isn't necessary — you can make reasonable inferences and note them in the draft.

2. Check for existing ADRs