memos/docs/adr/README.md
amblued 9d2b77ced8 feat(space): add client-defined UIDs and identity cues
- Generate UUID v4 values in the client with validated custom UID
  support.\n- Show immutable UIDs where Space titles need
  disambiguation.\n- Standardize Space surfaces on the Lucide Astroid
  icon.
2026-08-28 00:33:09 +08:00

2.1 KiB

Architecture Decision Records

Architecture Decision Records (ADRs) document significant technical and product decisions whose rationale should remain available after the related implementation work is complete.

Index

ADR Title Status Date
0001 Tag Syntax and Recognition Accepted 2026-08-01
0002 Username Format and References Accepted 2026-08-02
0003 Space UID Allocation and Format Accepted 2026-08-27

Conventions

  • Name files NNNN-short-kebab-case-title.md, using a four-digit number that is never reused.
  • Assign the next number when an ADR is opened, even if an earlier ADR is later rejected or superseded.
  • Use the title # ADR NNNN: Title and record dates as YYYY-MM-DD.
  • Keep accepted ADRs as historical records. Replace a decision with a new ADR rather than rewriting the original rationale.
  • When one ADR replaces another, add Supersedes: ADR NNNN to the new ADR and Superseded by: ADR NNNN to the old ADR.

Statuses

  • Proposed: Under discussion; unresolved questions may remain.
  • Accepted: Approved as the decision to implement and maintain.
  • Rejected: Considered but not selected.
  • Superseded: Replaced by a later ADR.

Suggested structure

Each ADR should contain enough information to understand the decision without reconstructing the original discussion:

# ADR NNNN: Title

Status: Proposed

Date: YYYY-MM-DD

## Context

## Decision drivers

## Decision

## Consequences

## Alternatives considered

## Open questions before acceptance

## References

Optional sections may be omitted when they do not add useful context.

Process

  1. Create a Proposed ADR with the next available number and add it to the index.
  2. Discuss the proposal with maintainers, updating the ADR as the decision develops.
  3. Change the status to Accepted or Rejected when the outcome is clear.
  4. If an accepted decision changes materially, create a new ADR and cross-link the superseding records.