Дмитрий
75 lines
3.2 KiB
Markdown
75 lines
3.2 KiB
Markdown
# ADR-000 Adopt the ADR process and decision-store boundaries
|
|
|
|
## Status
|
|
|
|
Accepted, 2026-05-17.
|
|
|
|
## Context
|
|
|
|
Лидерра already records open product, business, and legal questions in the
|
|
`docs/Открытые_вопросы_v8_3.md` registry (identifiers `Б-`, `CTO-`, `Ю-`,
|
|
`Диз-`, `DO-`, `OPEN-`), each closed only by an explicit owner decision.
|
|
|
|
Integrating the `adr-kit` plugin adds a second store, `docs/adr/`, and the
|
|
`mermaid` skill adds a third, `docs/architecture/`. Without explicit
|
|
boundaries the three overlap, and a reader cannot tell where a given decision
|
|
belongs. This ADR is the first written under the new process; it fixes the
|
|
boundaries so ADR-001 onward have a clear home.
|
|
|
|
## Decision
|
|
|
|
- **`docs/adr/`** holds Architecture Decision Records — a *technical or
|
|
architectural decision that has already been made*: stack choice, structural
|
|
boundary, data-layer strategy, cross-cutting pattern. One file per decision,
|
|
named `ADR-NNN-kebab-title.md`, following the seven-section adr-kit template.
|
|
- **`docs/architecture/`** holds diagrams and models (C4, system context),
|
|
generated with the `mermaid` skill. Visual, not normative; an ADR may
|
|
reference a diagram there.
|
|
- **The `docs/Открытые_вопросы` registry** continues to track *unresolved*
|
|
product, business, and legal questions. It is not machine-enforced.
|
|
- A registry question that resolves into a technical choice may graduate into
|
|
an ADR; the registry entry is then closed by the normal owner process.
|
|
- An ADR may carry a machine-readable `## Enforcement` block; `adr-judge`
|
|
applies it to staged diffs at commit time (wired as a `lefthook` job).
|
|
Enforcement rules target architecture-level constraints only — they do not
|
|
duplicate `larastan`, `eslint`, or `squawk` rules.
|
|
|
|
## Alternatives Considered
|
|
|
|
- **Keep every decision in the Открытые_вопросы registry.** Rejected: the
|
|
registry is designed for *open* questions awaiting a decision, not for
|
|
recording *closed* technical choices, and it has no enforcement mechanism.
|
|
- **Record architecture decisions inside `CLAUDE.md`.** Rejected: `CLAUDE.md`
|
|
is the operational map, edited only through the `claude-md-management`
|
|
plugin (`CLAUDE.md` §5 п.10), and would grow without bound if it absorbed
|
|
every decision rationale.
|
|
|
|
## Consequences
|
|
|
|
**Positive:**
|
|
|
|
- A reader can locate any decision by class: open question, closed decision,
|
|
or diagram.
|
|
- Architecture decisions become version-controlled, reviewable, and — where an
|
|
Enforcement block exists — machine-checked at commit time.
|
|
|
|
**Negative:**
|
|
|
|
- Three stores must be kept disjoint; a contributor has to know the boundary
|
|
rule above before adding to any of them.
|
|
- An ADR superseded by a later decision must be marked
|
|
`Superseded by ADR-MMM` rather than edited in place — process discipline the
|
|
team has to follow.
|
|
|
|
## Related Decisions
|
|
|
|
- ADR-001 — first technical ADR written under this process.
|
|
- ADR-002 — first data-layer ADR written under this process.
|
|
|
|
## References
|
|
|
|
- `docs/superpowers/plans/2026-05-17-a6-architecture-tooling-integration.md` —
|
|
the integration plan that introduced `docs/adr/`.
|
|
- `docs/Открытые_вопросы_v8_3.md` — the open-questions registry.
|
|
- `.claude/adr-kit-guide.md` — the adr-kit authoring guide.
|