architecture-decision

Documenting an architecture decision involves capturing context, alternatives considered, rationale, and consequences in a standardized ADR format. This approach ensures future work can reuse past reasoning without re-explaining the original technical choices.

An architectural decision record (ADR) is a standardized document that captures major technical choices, selecting between alternatives and managing long-term consistency. You need one when software teams must document key decisions for future recall and project alignment.

Saving architectural decisions stores the ADR text as memory in Hindsight, retaining it as decision memory or mental models. This allows future development work to directly reuse past reasoning without requiring team members to re-explain the original context.

An architecture decision should update CLAUDE.md only when the decision establishes a true hard rule or pattern that must be followed. Standard decisions are retained in Hindsight without modifying the project's CLAUDE.md configuration.

Yes, the ADR process applies to software teams documenting major technical choices and selecting between alternatives. It parses decision inputs and generates a complete record to manage long-term consistency across different feature areas.

Retaining ADRs in Hindsight stores decision memory for recall but does not enforce rules unless CLAUDE.md is updated. Decisions that require strict enforcement must trigger a CLAUDE.md update to establish hard patterns.