git:20261008.3f25f14 to git:20261015.f440cbb

- description: Use when designing high-level system architecture, reviewing or auditing existing designs, or making architectural decisions — produces TECH docs and ADRs with evidence-grounded decisions (each cites real OSS or case references facing similar requirements) and a human-audit loop: draft → audit → confirmed → revised → mature. Triggers on "system design", "架构设计", "ADR", "scalability", "系统设计", "架构决策" — also when user says "这个技术方案怎么审计" / "技术决策要引用哪些参考".

- Design system-level architecture: pick patterns, size components, choose datastores, and record

- decisions as ADRs. Pragmatic trade-offs over theoretical purity. Core principle:

- **evidence-grounded and auditable** — every decision cites real implementations that faced

- similar requirements (never designed from nothing), and the document matures through a

- human-audit loop: draft → human audit → confirmed → mature, with revisions looping back on

- findings.

-

- - Designing new system architecture, or reviewing/auditing an existing one

- - Choosing between architectural patterns (monolith vs microservices, event-driven, serverless)

- - Making technology choices that carry lock-in (database, message bus, auth provider)

- - Planning for scalability or evaluating NFR trade-offs (performance, availability, cost)

- - Writing Architecture Decision Records (ADRs)

- - Triggers on "system design", "architecture review", "scalability", "ADR", "架构设计"

- **Not for:** Code-level design patterns (use `simplify` or `codebase-design`), database-only design without system context, or feature-level API contracts (use `api-design`). Requirements/product-spec writing without system design (use `spec` — architecture takes the spec as input).

- ### 1. Gather requirements (functional + non-functional)

-

- Take the PRD (the `spec` output) as input. Collect functional requirements, constraints

- (budget, timeline, team), and NFRs. Use the NFR checklist to make scalability, performance,

- availability, security, reliability, and cost targets explicit — never assume "it should be

- fast." Link each NFR to the goal it serves. _Verify: every NFR category has a concrete target

- or an explicit "not applicable" decision recorded._

-

- - Load `references/nfr-checklist.md` when gathering NFRs

- - Load `references/system-design.md` for the full design template

-

- ### 2. Research references before designing

-

- Reference-first: for every candidate pattern, datastore, or component, find real

- implementations that faced similar requirements — OSS repos, engineering blogs, official case

- studies, RFCs. A nameable reference item is mandatory; never design from nothing. If none is

- at hand, research first and record the retrieval date. _Verify: every candidate carries ≥1

- real reference with link, access date, and what matched vs differed from our constraints._

-

- - Load `references/tech-audit-guide.md` for reference selection criteria and the evidence format

-

- ### 3. Evaluate architectural patterns

-

- Match requirements to patterns. Don't pick microservices because they sound modern — pick the

- pattern whose trade-offs match your team size, domain complexity, and scaling needs. Ground

- each candidate in its references: what did they run, at what scale, what did they outgrow?

-

- - Load `references/architecture-patterns.md` for the pattern comparison (monolith, modular monolith,

- microservices, serverless, event-driven, CQRS) with when-to-use criteria

- - For each candidate: what it makes easy and what it makes hard; which references support it

- and where their constraints differ from ours

-

- ### 4. Design components and data layer

-

- Design component interactions, data flow, and the data layer. Choose datastores per workload —

- relational for transactions, document for flexible schemas, key-value for caching, time-series for

- metrics, graph for relationships, search for full-text.

-

- - Load `references/database-selection.md` for the database decision matrix

- - Load `references/error-resilience.md` for the cross-cutting error-handling strategy — throw-vs-return conventions, error propagation across layers, retry/circuit-breaker/backoff, idempotency under retry, fallback UX, error-to-user-message mapping

- - Produce high-level diagrams (Mermaid — see `${CLAUDE_PLUGIN_ROOT}/references/mermaid-diagrams.md`).

- One figure answers one question; every figure carries a FIG ID, a title, a 1–2 sentence

- caption, and its linked components; branch flows show outcomes; the body stands without rendering

- - Document failure modes and mitigations for each component

-

- ### 5. Record decisions as ADRs

-

- Write an ADR when a decision is **hard to reverse**, **surprising without context**, and the

- result of a **real trade-off**. Skip reversible or obvious ones — they clutter the log.

-

- - Every ADR carries evidence: its References section names the real implementations consulted —

- what was adopted, what was adapted, and how our constraints differ. A bare link list is not evidence

- - A minimal paragraph (context + decision + why + reference) is the default; most ADRs need nothing more

- - Load `references/adr-template.md` for the expanded format (Status / Context / Decision /

- Consequences / Alternatives / References) when the trade-offs warrant recording in full

- - Number sequentially: `docs/design/adr/0001-slug.md` — never renumber; superseded ADRs record their successor

-

- ### 6. Publish

- Two layers: `docs/TECH.md` — project-level architecture overview (diagram, components, NFRs,

- data layer), concise (mermaid-heavy), on main; `docs/vX.Y/tech.md` — the current version's

- detailed architecture, on the version branch (falls back to `docs/TECH.md` alone for

- single-version projects). Plus `docs/design/adr/NNNN-slug.md` per significant decision (shared

- across versions). TECH.md is the overview; ADRs are the decision records — TECH.md references

- the ADRs it depends on. Commit both — living documents.

- ### 7. Human-audit gate: audit → confirm → revise → mature

- A TECH doc is not done when written — it's done when a human has audited it. Write an AUD

- section into the doc (6–12 items covering reference authenticity, reference fit, alternatives,

- NFR measurability, failure/recovery, consistency, cost & ops, reversibility — see

- `references/tech-audit-guide.md`), each with required evidence and a close criterion. Status on

- the first screen tracks the loop: 草案 draft → 人工审计 in-audit → 已确认 confirmed → 成熟

- mature. Only the human moves the status. Findings drive revision; revisions preserve ADR

- numbers and IDs; re-audit until every item closes. _Verify: audit feedback is incorporated or

- explicitly overridden with rationale; all AUD items pass before the doc is called mature._

- **Output:** `docs/TECH.md` (project-level, concise, main) + `docs/vX.Y/tech.md` (version-level, detailed, version branch) + `docs/design/adr/NNNN-slug.md` (decision records, cross-version). Single-version projects fall back to `docs/TECH.md` alone.

- - [ ] ADR written for every significant decision (hard to reverse, surprising, real trade-off)

- - [ ] Every ADR and pattern/datastore candidate cites ≥1 real reference (link + access date) facing similar requirements — none designed from nothing

- - [ ] Trade-offs documented for each choice — rejected alternatives with reasons, not just benefits

- - [ ] Architecture diagram renders (Mermaid valid); figures have IDs/titles/captions; all components and data flows shown

- - [ ] Every NFR category has a concrete target or explicit "not applicable", linked to the goal it serves

- - [ ] Failure modes identified with mitigations; operational complexity and cost considered

- - [ ] AUD section present (6–12 items) with evidence and close criteria; statuses tracked; unverified claims marked; no fabricated confirmations

- - [ ] Status reflects the loop honestly (草案/人工审计/已确认/成熟); revisions preserved ADR numbers

- - [ ] Human audit passed — every AUD item closed

-

- **Red flags:** over-engineering for hypothetical scale; choosing technology without evaluating

- alternatives; decisions without real references; ignoring operational costs; designing without

- understanding NFRs; skipping security considerations; no ADRs for decisions that will be hard to

- reverse; calling a doc done without human audit.

- - [${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md](${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md) — shared discipline (surface assumptions, push back, verify don't assume)

- - [${CLAUDE_PLUGIN_ROOT}/references/mermaid-diagrams.md](${CLAUDE_PLUGIN_ROOT}/references/mermaid-diagrams.md) — Mermaid syntax for architecture diagrams