Architect Change
Choose the simplest architecture that satisfies current invariants and makes failure, migration, and reversal explicit.
Workflow
- Inspect existing boundaries, ownership, dependencies, runtime topology, data flow, and conventions.
- Extract quality attributes from the spec: correctness, latency, availability, consistency, privacy, security, cost, operability, and evolvability.
- State forces and constraints. Distinguish fixed constraints from preferences.
- Develop at least two credible options plus “keep the current design” when applicable.
- Evaluate options against the same decision matrix. Identify failure modes and operational burden.
- Select one option and define interfaces, ownership, migration, compatibility, observability, rollout, rollback, and deletion of transitional paths.
- Validate with the smallest useful spike or contract test when uncertainty is technical rather than product-level.
ADR template
Write .workshop/decisions/ADR-<number>-<slug>.md:
# <decision>
Status: proposed | accepted | superseded
Date: YYYY-MM-DD
## Context and forces
## Decision drivers
## Options considered
## Decision matrix
## Decision
## Boundaries and interfaces
## Data, consistency, and failure modes
## Security and privacy
## Observability and operations
## Migration, rollout, rollback, and cleanup
## Consequences
## Validation evidence
## Open risks
Guardrails
- Do not introduce a service, queue, cache, abstraction, framework, or dependency without tying it to a named decision driver.
- Treat distributed state, retries, idempotency, timeouts, and partial failure as first-class when relevant.
- Avoid future-proofing for uncommitted scenarios.
- Record rejected alternatives fairly enough that a future maintainer can revisit the choice.
- “No ADR required” is a valid outcome when the change does not alter a meaningful boundary; record the reason.
Evidence packet
Return the ADR, chosen option, decisive evidence, validation performed, migration and rollback summary, and risks that could invalidate the decision.
1---2name: architect-change3description: Design a consequential software change across boundaries, data, APIs, deployment, or reliability and record the decision as a lightweight ADR. Use when implementation choices affect long-term structure or migration. Do not use for trivial local edits.4license: Apache-2.05---67# Architect Change89Choose the simplest architecture that satisfies current invariants and makes failure, migration, and reversal explicit.1011## Workflow12131. Inspect existing boundaries, ownership, dependencies, runtime topology, data flow, and conventions.142. Extract quality attributes from the spec: correctness, latency, availability, consistency, privacy, security, cost, operability, and evolvability.153. State forces and constraints. Distinguish fixed constraints from preferences.164. Develop at least two credible options plus “keep the current design” when applicable.175. Evaluate options against the same decision matrix. Identify failure modes and operational burden.186. Select one option and define interfaces, ownership, migration, compatibility, observability, rollout, rollback, and deletion of transitional paths.197. Validate with the smallest useful spike or contract test when uncertainty is technical rather than product-level.2021## ADR template2223Write `.workshop/decisions/ADR-<number>-<slug>.md`:2425```markdown26# <decision>27Status: proposed | accepted | superseded28Date: YYYY-MM-DD2930## Context and forces31## Decision drivers32## Options considered33## Decision matrix34## Decision35## Boundaries and interfaces36## Data, consistency, and failure modes37## Security and privacy38## Observability and operations39## Migration, rollout, rollback, and cleanup40## Consequences41## Validation evidence42## Open risks43```4445## Guardrails4647- Do not introduce a service, queue, cache, abstraction, framework, or dependency without tying it to a named decision driver.48- Treat distributed state, retries, idempotency, timeouts, and partial failure as first-class when relevant.49- Avoid future-proofing for uncommitted scenarios.50- Record rejected alternatives fairly enough that a future maintainer can revisit the choice.51- “No ADR required” is a valid outcome when the change does not alter a meaningful boundary; record the reason.5253## Evidence packet5455Return the ADR, chosen option, decisive evidence, validation performed, migration and rollback summary, and risks that could invalidate the decision.
leihuang23