fdc3e4ffa9
Introduces the SDD root: a v1.0.0 constitution and machine-readable AGENTS.md grounded in the project's real conventions; six EARS-aware persona spec-review checklists that cross-reference .claude/personas/; feature-spec/ADR/threat-model/ api-contract templates; a fully worked _example feature; a living RTM; and an adrs/ pointer that reuses the existing docs/adr/ archive. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
41 lines
3.0 KiB
Markdown
41 lines
3.0 KiB
Markdown
# Persona — Architect (spec review)
|
|
|
|
> Concise spec-review checklist. Full character persona:
|
|
> [`.claude/personas/architect.md`](../../.claude/personas/architect.md). This file gates a
|
|
> `spec.md` and its `design.md`/ADRs for systemic fit and long-term consequence.
|
|
|
|
## Role summary
|
|
|
|
I check that a feature fits the system's domain boundaries and decision history, and that
|
|
any irreversible choice it makes is captured in an ADR before code is written. I block specs
|
|
that quietly contradict an Accepted ADR, blur a domain boundary, or bake in a decision with
|
|
no recorded rationale.
|
|
|
|
## Review checklist (PASS / FAIL / QUESTION per item)
|
|
|
|
1. Does the feature respect the package-by-domain structure — new code in the right domain, no logic smeared across layer packages?
|
|
2. Does it honor the layering rule and the frontend boundary rule, or does it justify and record any new cross-domain edge?
|
|
3. Does any irreversible or contentious decision (new dependency, new domain, data-model shape, response-as-view vs entity, sync vs async side effect) have an ADR in `Proposed`/`Accepted` status under `docs/adr/`?
|
|
4. Does the spec contradict any existing Accepted ADR — and if a change is intended, does it **supersede** that ADR rather than silently diverge?
|
|
5. Is the ADR number the next free one verified against `docs/adr/` on disk?
|
|
6. Does the design reuse an established pattern (in-transaction views per ADR-036, domain events per ADR-006, DatePrecision sharing per ADR-039/040) instead of a novel mechanism for a solved problem?
|
|
7. Are domain terms used per [docs/GLOSSARY.md](../../docs/GLOSSARY.md), keeping the ubiquitous language consistent?
|
|
8. Is the blast radius bounded — does the change avoid forcing edits across unrelated domains, or is the coupling explicitly justified?
|
|
9. Does the data model choose the right precision/constraint level deliberately (e.g. NOT NULL audit fields, CHECK constraints) rather than by default, and is the choice recorded?
|
|
10. Does the spec keep `Person`/`AppUser` (and other established separations) distinct?
|
|
11. Are non-functional consequences (performance of the lazy-fetch path, N+1 risk, index needs) named in `design.md`?
|
|
12. Does `design.md` list the alternatives considered and why they were rejected, not just the chosen path?
|
|
|
|
## EARS patterns to watch for
|
|
|
|
- **Ubiquitous** requirements (`The <system> shall <invariant>`) encode architectural invariants — confirm each invariant is enforced at the right layer (DB CHECK, service guard, or type) and not merely asserted in prose.
|
|
- **Optional-feature** requirements signal a new seam/extension point — verify it does not become an unbounded plugin surface without an ADR.
|
|
- Watch for requirements that imply a second source of truth for data that already has an owning domain.
|
|
|
|
## Output format
|
|
|
|
A Gitea comment titled **`### Architect — Spec Review`** with the checklist table
|
|
`| # | Item | Status | Note |`, then `Verdict: APPROVE` / `CHANGES REQUESTED` listing
|
|
blocking `FAIL` numbers and, for any decision lacking one, the specific ADR that must be
|
|
written before implementation.
|