菜单
[Architecture] Use when designing solution architecture across backend, frontend, data & consistency, integration & APIs, deployment, monitoring, testing, and code quality. Architecture laws, style-selection triggers, coupling taxonomy, trade-off tables and the anti-pattern catalog live in `.claude/docs/architecture-knowledge.md`.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
[Architecture] Use when auditing the ENTIRE project architecture and production readiness in one pass — bundles architecture-review + architecture-scalability-review + production-readiness-review at project or diff scope, then synthesizes one consolidated Architecture Health Report.
[Code Quality] Use when reviewing architecture compliance for layers, messaging, service boundaries, CQRS, repos, entity events, and data/consistency/tenancy boundaries. Universal architecture laws, coupling taxonomy and the anti-pattern catalog live in `.claude/docs/architecture-knowledge.md` (project docs always outrank it).
[Code Quality] Use when you need to review artifact quality (PBI, user story, test spec, design spec) before handoff. Supports --type={pbi|story|spec-tests|design}.
[Code Quality] Use when reviewing current changes, staged or unstaged diffs, or branch-to-branch diffs.
[Code Quality] Use when evaluating review feedback, requesting targeted code-quality review, or verifying completion claims.
[DDD Quality] Use when you need to review domain entities and value objects for DDD design quality.
| name | architecture-design |
| description | [Architecture] Use when designing solution architecture across backend, frontend, data & consistency, integration & APIs, deployment, monitoring, testing, and code quality. Architecture laws, style-selection triggers, coupling taxonomy, trade-off tables and the anti-pattern catalog live in `.claude/docs/architecture-knowledge.md`. |
Codex compatibility note:
- Invoke repository skills with
$skill-namein Codex; this mirrored copy rewrites legacy Claude/skill-namereferences.- Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.
- User-question prompts mean to ask the user directly in Codex.
- Ignore Claude-specific mode-switch instructions when they appear.
- Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.
- Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required
spawn_agentsubagent(s) for that task.- Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.
- For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence.
- If a required step/tool cannot run in this environment, stop and ask the user before adapting.
Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.
Always read:
docs/project-config.json (project-specific paths, commands, modules, and workflow/test settings)docs/project-reference/docs-index-reference.md (routes to the full docs/project-reference/* catalog)docs/project-reference/lessons.md (always-on guardrails and anti-patterns)Missing/stale context route: If docs/project-config.json, the docs index, lessons.md, CLAUDE.md, AGENTS.md, or any task-required reference doc is missing or stale, auto-run $project-init or the narrow setup route ($project-config, $docs-init, $scan-all, $scan --target=<key>, $claude-md-init) before ordinary project-specific work. If Codex mirrors or AGENTS.md are missing/stale, ask the user to run $sync-codex; do not auto-run it.
Situation-based docs:
project-structure-reference.mdbackend-patterns-reference.md, domain-entities-reference.mdfrontend-patterns-reference.md, scss-styling-guide.md, design-system/README.mddocs/specs/ pathing, or TC format: feature-spec-reference.md, spec-system-reference.md, spec-principles.mdworkflow-spec-test-code-cycle-reference.md plus the spec docs abovespec-system-reference.md and source Feature Specs under docs/specs/integration-test-reference.mde2e-test-reference.mdcode-review-rules.md plus domain docs above based on changed filesDo not read all docs blindly. Start from docs-index-reference.md, then open only relevant files for the task.
[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: set
in_progresswhen step starts, setcompletedwhen step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.
Goal: As solution architect, deliver a complete, evidence-backed, user-validated architecture decision report covering ALL concerns (backend, frontend, design patterns, library ecosystem, testing, CI/CD, deployment, monitoring, code quality, dependency management) — every concern researched with 3+ options, every recommendation carrying confidence % + cited evidence, every decision user-confirmed — so implementation proceeds on sound, owned architectural choices.
Summary:
Unresolved question, never a silent guess..claude/docs/architecture-knowledge.md (laws, coupling taxonomy, style triggers, trade-off + anti-pattern catalogs) — never from familiarity or fashion.architecture-review Cat 9 enforces) and the Scaffold Handoff tool-choices table (scaffold/harness-setup consume), then run the MANDATORY Step-12 user-validation interview before confirming.confirmed) → Next Steps + always-offer council escalation. — why: AI keeps forgetting the skill's own steps; this is the recovery anchor.Workflow (12 steps):
Key Rules:
solution-architect agent for complex architecture decisionsBe skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).
Skill sits mid-workflow — consumes settled upstream decisions, produces artifacts downstream steps build on. Do NOT re-derive what upstream step already owns; do NOT leave downstream consumer without its needed artifact. — why: re-deriving settled decisions wastes effort and risks divergence from the recorded choice.
| Consumes (read, don't re-derive) | From | Produces (named deliverable) | Consumed by |
|---|---|---|---|
| Bounded contexts, aggregates, domain events, ERD | domain-analysis | Architecture decision report ({plan-dir}/research/...) | plan, plan-execute |
| Confirmed languages/frameworks/databases | tech-stack-research | Confirmed decisions ({plan-dir}/phase-02b-architecture.md) | plan, scaffold |
| Expected scale, compliance, budget constraints | business-evaluation | Scaffold Handoff table (tooling + fitness rules) | scaffold, harness-setup |
| Existing stack/patterns/ADRs (brownfield) | reference docs, docs/adr/** | ADRs for hard-to-reverse decisions (docs/adr/) | architecture-review (conformance) |
If upstream artifact missing, capture minimum needed here and note gap — NEVER silently re-run full upstream analysis. — why: a silent re-run hides the missing-input gap that the owning step should resolve.
Mode (decide first): Greenfield (new project, e.g. via
workflow-greenfield-init) → research every concern from scratch, full 3-options-per-concern. Brownfield (large feature in existing codebase, e.g.workflow-big-feature) → FIRST read project reference docs + accepted ADRs, constrain research to existing stack/patterns, propose changes only where new requirement genuinely outgrows them — NEVER re-litigate settled ADR-recorded decision without superseding-ADR rationale. — why: re-deciding a recorded choice churns the codebase and breaks downstream conformance checks.
Read artifacts from prior workflow steps (search plans/ and team-artifacts/):
Extract, summarize:
| Signal | Value | Source |
|---|---|---|
| Bounded contexts | ... | domain model |
| Aggregate count | ... | domain model |
| Cross-context events | ... | domain model |
| Confirmed tech stack | ... | tech stack phase |
| Expected scale | ... | business eval |
| Team architecture exp. | ... | discovery |
| Compliance requirements | ... | business eval |
| Real-time needs | Yes/No | refined PBI |
| Integration complexity | Low/Med/High | domain model |
| Deployment target | ... | business eval |
Reason FROM the knowledge body, not from memory.
.claude/docs/architecture-knowledge.mdis AUTHORITATIVE for architecture laws (CAP/PACELC, Conway, Amdahl, USL, Little, Gall, Hyrum, Parnas), the coupling taxonomy + four coupling dimensions, style-selection triggers, the trade-off cheat sheet, and the ~100-entry anti-pattern catalog. Read the sections relevant to this design before recommending. Honor the catalog's provenance markers in §3/§8/§9/§10 — a row (or section banner) marked— VERIFYis an UNVERIFIED assertion, so cite it as a hypothesis to check against the named source where one is named (a[model-knowledge]row names none — check the project's own docs or a primary source instead), NEVER as settled fact in a recommendation. The project's own reference docs and accepted ADRs OUTRANK that catalog on any conflict — the catalog supplies universal reasoning, the project supplies binding convention. — why: universal names hardcoded as project rules rot against real repos.
Architecture = the set of decisions expensive to reverse; everything cheap to reverse is design — leave it to implementers. Classify each decision BEFORE researching it, because the classification sets how much rigour it earns.
| Class | Meaning | Required treatment |
|---|---|---|
| One-way door | Reversal costs a migration, a rewrite, or a breaking change to consumers | ADR (Step 11) + user validation (Step 12) MANDATORY — research 3+ options, name the rejected alternative AND the measurable revisit trigger |
| Two-way door | Reversal is a refactor inside one module | Decide, record one line, move on — NEVER burn a validation question on it |
One-way doors (assume MANDATORY ADR unless proven otherwise): data model + primary-key strategy · tenancy model · consistency model per read path · sync-vs-async at a boundary · public API/event contract · service boundary lines · cloud-primitive lock-in · auth/identity model · data residency + retention.
MANDATORY IMPORTANT MUST ATTENTION never treat a one-way door as a two-way door to save a step — why: an unreviewed irreversible decision is the single most expensive failure mode of this skill, and it surfaces months later as a migration.
Map signals to architecture constraints:
| Signal | Architecture Requirement | Priority |
|---|---|---|
| Many bounded contexts | Clear module boundaries, context isolation | Must |
| High scale | Horizontal scaling, stateless services, caching strategy | Must |
| Complex domain | Rich domain model, separation of domain from infra | Must |
| Cross-context events | Event-driven communication, eventual consistency | Must |
| Small team | Low ceremony, fewer layers, convention over configuration | Should |
| Compliance | Audit trail, immutable events, access control layers | Must |
| Real-time | Event sourcing or pub/sub, WebSocket/SSE support | Should |
| High integration complexity | Anti-corruption layers, adapter pattern, API gateway | Should |
Qualitative "Must/Should" cannot decide, e.g., modular monolith vs microservices. Capture measurable targets; ask user for any unknown by asking the user directly (guess acceptable only when labelled an assumption with confidence %). These targets become ADR-recorded budgets architecture-review Category 9 later checks changes against. — why: a style chosen without numbers is a guess, not an enforceable decision.
| Quality attribute | Scenario (stimulus → measurable response) | Target (fill in) |
|---|---|---|
| Latency | p95 / p99 response time for the hottest read and write paths | e.g. p99 < 300ms |
| Throughput | Sustained req/s and peak burst the system must absorb | e.g. 500 rps peak |
| Availability / SLO | Target uptime and error budget | e.g. 99.9% |
| Data durability (RPO) | Max acceptable data loss on failure | e.g. ≤ 5 min |
| Recovery (RTO) | Max acceptable time to restore service | e.g. ≤ 30 min |
| Data-volume growth | Row/document/event growth → storage, index, partition strategy | e.g. 10M rows/yr |
| Concurrency | Concurrent users/sessions and contention hot spots | e.g. 2k concurrent |
| Compliance/retention | Regulated data, retention window, residency, audit | e.g. GDPR, 7yr |
| Cost unit economics | $/request, $/tenant, $/MAU — and whether unit cost RISES with scale | e.g. <$0.002/req |
Scenario template — all SIX parts, none optional: [SOURCE: who/what triggers] [STIMULUS: the event] on [ARTIFACT: which component] under [ENVIRONMENT: the conditions] SHALL produce [RESPONSE] within [MEASURE: threshold + instrument]. "Must be scalable" decides nothing; "5,000 concurrent checkout sessions at 400 rps SHALL complete p99 < 800 ms, ≤0.1% errors, verified by the CI k6 profile" selects a structure.
MUST ATTENTION a scenario missing SOURCE or ARTIFACT is untestable — you cannot write a fitness function for "the system" under "load", so name the actor and the component. — why: an unattributed scenario gets no owner, no test and no budget, so it is never verified and silently degrades.
Rule: any target left unknown is explicit Unresolved question (Step 11), NEVER a silent omission — an architecture chosen without scale numbers is a guess, not a decision.
Move each attribute with a TACTIC, not a product. Once a target is unmet or at risk, select the mechanism from the tactics inventory in .claude/docs/architecture-knowledge.md §2 (availability · performance · modifiability · security · testability · usability) — "bulkhead a pool per dependency" is a design decision; "add Kubernetes" is a shopping list. — why: the tactic is portable across stacks and makes the trade-off legible, the product imports costs nobody asked for.
Quality attributes CONFLICT, and that conflict IS the architecture: consistency↔availability · latency↔durability · flexibility↔simplicity · security↔usability · cost↔redundancy · performance↔modifiability.
MANDATORY IMPORTANT MUST ATTENTION name at most 3 DRIVING attributes and explicitly record which attributes are being SACRIFICED to buy them — a design claiming to maximize everything has decided nothing — why: unnamed sacrifices resurface as production surprises nobody agreed to.
| Field | Record |
|---|---|
| Driving attributes (≤3) | ... + the quantified target for each (from the table above) |
| Explicitly sacrificed | ... + the acceptable degradation, e.g. "search may lag ≤5 s" |
| Trade-off purchased | Use the "buy this / pay with this" table in .claude/docs/architecture-knowledge.md §19 — state cost, never just benefit |
Availability arithmetic (compute it, never assert it): dependencies in a request path MULTIPLY — five 99.9% deps ⇒ ~99.5% (≈43 h/yr down). Redundancy in PARALLEL adds 9s only when failure modes are genuinely independent; shared config, control plane, DNS and the deploy pipeline are the usual hidden serial term. Ladder: 99% = 3.65 d/yr · 99.9% = 8.77 h · 99.95% = 4.38 h · 99.99% = 52.6 min · 99.999% = 5.26 min.
Cost is a quality attribute, not a later phase. Model unit economics now — an architecture whose UNIT cost RISES with scale fails eventually regardless of elegance. Biggest web-system drivers: egress + cross-AZ/cross-region traffic · idle over-provisioned compute · unbounded log/metric/trace retention and cardinality · per-request managed-service pricing at steady high volume · always-on non-prod. Serverless vs always-on inverts with utilization — model it, don't assume it.
MANDATORY IMPORTANT MUST ATTENTION validate derived requirements with user by asking the user directly before proceeding.
Answer the 15-question pre-decision script in .claude/docs/architecture-knowledge.md §20.1 for each one-way door BEFORE researching options. Record answers in the Step 11 report; any question answered "unknown" becomes an Unresolved question, never a silent gap.
The five that most often expose a wrong decision — never skip these:
| # | Question | Why it changes the answer |
|---|---|---|
| 3 | Is this a one-way or two-way door, and what makes it so? | Sets how much rigour the decision earns; misclassification is this skill's most expensive failure |
| 5-6 | Expected load NOW and at 10× — and what breaks FIRST? | Names the actual bottleneck instead of the imagined one; 10×, never 1000× |
| 8 | What is the consistency requirement PER read path, and what staleness is acceptable? | Consistency is decided per path, never once globally |
| 14 | What existing thing could be used instead of building? | Generic subdomains (auth, billing, notifications, search) are the top source of wasted architecture budget |
| 15 | What would have to be TRUE for this to be the WRONG choice — and how would I detect it? | Becomes the ADR's measurable revisit trigger |
MANDATORY IMPORTANT MUST ATTENTION a one-way door with no answer to question 15 is a BELIEF, not a decision — NEVER emit its ADR without a named falsifier and a measurable revisit trigger. — why: with no trigger nobody ever revisits it, so the decision outlives the constraints that justified it.
architecture-scalability-review)Record these decisions now so the init-time architecture-scalability-review scorecard (mode=init) can grade them later against enforceable mechanisms, not intent. Each row is a design decision, not a finding — capture the choice AND where it is enforced. Leave any unknown as explicit Unresolved question (Step 11), never a silent omission. — why: a scorecard can only grade decisions actually recorded with an enforcement home.
| Scorecard input | Design prompt (decide + record where enforced) | Enforcement handoff |
|---|---|---|
| Build & CI scalability | As the codebase grows, how are build/CI times kept bounded? Decide incremental builds, changed/affected-only detection, local + remote cache strategy, and CI test/build parallelism. Name the build-system fit (single-package vs monorepo tool such as Nx / Turborepo / Bazel) as an evaluated option, not a default. | Step 7 (CI/CD provider parallelism + caching) |
| Horizontal scaling budgets | From the Step 2 scale targets, decide stateless app nodes, load balancing, caching tiers, async/queue + back-pressure, DB scale plan (sharding/partitioning/replication), connection pooling, rate limits, and a SPOF scan of every single-instance dependency. | ADR + Step 8 observability SLOs |
| Strategic DRY | Decide the strategic DRY / shared-knowledge strategy: monorepo, shared domain lib, custom platform / util lib — AND explicitly when NOT to share. Keep domain concepts OUT of generic/shared/infra layers (a shared layer coupled to one consumer's domain is no longer reusable). | Step 9 arch-rules + scaffold foundation |
| Dependency-boundary enforcement | Decide explicit dependency directions between modules/contexts and the mechanism that enforces them (no circular deps). | Step 9 "Arch rules / fitness" handoff → linter-setup |
These inputs are graded at init/audit by architecture-scalability-review; per-change regressions are caught by architecture-review. Do NOT turn this step into an auditor — record decisions here and route grading to those skills.
WebSearch top 3 backend architecture styles. Candidates:
| Style | Best For | Research Focus |
|---|---|---|
| Clean Architecture | Complex domains, long-lived projects | Dependency rule, testability, flexibility |
| Hexagonal (Ports+Adapt) | Integration-heavy, multiple I/O adapters | Port contracts, adapter isolation |
| Vertical Slice | Feature-focused teams, rapid delivery | Slice isolation, code locality |
| Modular Monolith | Starting simple, eventual decomposition | Module boundaries, migration path |
| Microservices | Large teams, independent deployment | Service boundaries, operational overhead |
| CQRS + Event Sourcing | Audit-heavy, complex queries | Read/write separation, event store |
| Layered (N-Tier) | Simple CRUD, small teams | Layer responsibilities, coupling risk |
Full 16-style matrix with per-style buys / costs / choose-when / avoid-when → .claude/docs/architecture-knowledge.md §5.
MANDATORY IMPORTANT MUST ATTENTION design-it-twice applies to EVERY one-way door from 2-0, not only the style choice — data model, tenancy model, consistency model per read path, sync-vs-async at a boundary. NEVER emit a one-way-door ADR whose "Alternatives considered" section was written to justify a decision already made. — why: a retrofitted alternative is advocacy, not evaluation, and it hides the sacrifice the reviewer needs to see.
Styles COMPOSE — modular monolith + event-driven integration + 2-3 extracted services is the most common good real answer. Recommending a single pure style is usually a sign step 2 was skipped.
MANDATORY IMPORTANT MUST ATTENTION — modulith-first default. Default to a modular monolith with CI-ENFORCED module boundaries (architecture tests, Step 9) and extract services ONLY against a named, measured trigger from the table below. Microservices are a destination reached under pressure, NEVER a starting point — the 2025-2026 industry correction is documented: many organizations re-consolidated after debugging complexity, ops overhead and network latency outweighed autonomy gains. — why: distribution bought speculatively pays every distributed cost immediately and collects the benefit never.
| Legitimate extraction trigger (record BEFORE building) | NOT a trigger (reject these) |
|---|---|
| Independent scaling profile ≥10x divergent | "The codebase feels big" |
| Different compliance / data-residency boundary | "Microservices are best practice" |
| Different availability requirement | A resume, a conference talk, or framework support |
| A team boundary PROVABLY blocked by shared deploys | One slow endpoint (fix the endpoint) |
| Genuinely different runtime need (GPU, language, memory profile) | A new team was hired |
| Fault isolation for a KNOWN-unreliable dependency | The domain has many entities |
MUST ATTENTION verify platform maturity before recommending microservices: CI/CD, IaC, distributed tracing, on-call, and a platform team. Microservices without them is the most reliable predictor of a failed migration — recommend the modulith and say so explicitly.
MUST ATTENTION draw boundaries around capabilities/behaviors (Checkout, Fulfilment, Pricing), NEVER around nouns/data (UserService, ProductService). Entity-per-service guarantees every real use case must synchronously traverse many services — a distributed monolith produced by design. The unit of extraction is the bounded context, not the entity.
Evaluate applicability per layer:
| Pattern | Layer | When to Apply |
|---|---|---|
| Repository | Data Access | Abstract data store, enable testing |
| CQRS | Application | Separate read/write models, complex queries |
| Mediator | Application | Decouple handlers from controllers |
| Strategy | Domain/App | Multiple interchangeable algorithms |
| Observer/Events | Domain | Cross-aggregate side effects |
| Factory | Domain | Complex object creation with invariants |
| Decorator | Cross-cutting | Add behavior without modifying (logging, caching) |
| Adapter | Infrastructure | Isolate external dependencies |
| Specification | Domain | Composable business rules, complex filtering |
| Unit of Work | Data Access | Transaction management across repositories |
| Saga/Orchestr. | Cross-service | Distributed transactions, compensating actions |
| Outbox | Messaging | Reliable event publishing with DB transactions |
| Circuit Breaker | Infrastructure | External service resilience |
Per recommended pattern document: Apply to, Why, Example, Risk if skipped.
MUST ATTENTION patterns are a VOCABULARY for a solution you already need, never a menu to shop from — applying patterns to demonstrate knowledge produces the gas factory anti-pattern. The right number of patterns is the SMALLEST number that removes a DEMONSTRATED pain. Watch the chronically over-applied ones: Singleton (global mutable state → prefer one DI registration), Service Locator (hides dependencies from compiler and tests), CQRS on simple CRUD, event sourcing used as an audit log (an audit table is the right answer).
Skip if: the change touches no persistence, no consistency boundary, and no tenant-scoped data. Otherwise MANDATORY.
Data outlives every service, framework and team — this is the MOST irreversible step in this skill. Treat every row below as a one-way door (Step 2-0) until proven otherwise: each needs an ADR and a Step-12 validation question.
| Decision | Decide + record | Failure if skipped |
|---|---|---|
| Store per access pattern | Pick each store from the ACCESS PATTERN, not familiarity: relational (relations/transactions/ad-hoc queries — the correct default) · document (aggregate-shaped reads) · key-value (lookup/session) · wide-column (huge writes, known queries) · graph (traversal) · time-series (append + rollups) · search (relevance/facets) · vector (semantic/ANN) · columnar (aggregation scans) · object storage (blobs). Each ADDITIONAL store needs its own justification — polyglot persistence costs per store (ops, backup, monitoring, expertise, and transactional impossibility across stores). | Golden-hammer: the wrong store makes the dominant query permanently expensive |
| One writer per dataset | Name the single owning module/service for every dataset. Many READERS are fine — via API, replica, or published event stream. | Shared write access is shared coupling with NO contract; data diverges and nobody owns correctness |
| NEVER integrate through the database | External consumers get an API, an event stream, or at most a published view/replica — never your tables. | Fastest known path to a distributed monolith and to "we can never change this table" |
| Consistency model per read path | Per read path choose strong / causal / session guarantees (read-your-writes, monotonic reads) / eventual — and write the STALENESS BUDGET ("search index may lag ≤5 s") as a monitored SLI (Step 8). | Unbounded, unmeasured lag IS the defect. Most user-visible "consistency bugs" are missing read-your-writes from a lagging replica, NOT missing linearizability |
| Isolation level + check-then-act protection | NAME the isolation level per critical write path — "we use transactions" says nothing about correctness. Read Committed permits write skew AND lost update; snapshot isolation permits write skew and — on any engine whose REPEATABLE READ is not true first-committer-wins SI — lost update too, so name the ENGINE as well as the level and protect every check-then-act invariant one of FOUR deliberate ways: a DB constraint (unique/check/exclusion — cheapest and most durable) · SELECT … FOR UPDATE on the rows read · Serializable + an app-side retry loop for serialization failures · a single atomic conditional write (UPDATE … WHERE version = n). An invariant spanning rows that DO NOT YET EXIST (no double-booking, no overlapping shift, at most N per tenant) cannot be protected by row locks. Full anomaly table → .claude/docs/architecture-knowledge.md §8. | Two concurrent transactions both pass their check and both write — the classic on-call corruption bug that passes every single-user test |
| Storage engine + index strategy | Choose B-Tree (mixed read/write, ad-hoc queries, strong secondary indexes) vs LSM (write-heavy ingest with known query shapes — pay with compaction stalls in p99 and space amplification). Record the WAL/fsync policy as the durability↔latency knob the RPO depends on. Index rules: composite indexes obey the leftmost-prefix rule ((a,b,c) never serves b alone) · covering indexes remove the row fetch · every index slows writes, so index-per-query-shape has a ceiling · size the connection pool by Little's Law. | An unpooled service DOSes its own database; a wrong engine makes the dominant workload permanently expensive; fsync settings chosen by default silently violate the stated RPO |
| Distributed lock / leader election — fencing | If any flow takes a distributed lock or elects a leader, name the fencing token (monotonic, rejected by the storage layer when stale), the lease duration, and the behaviour when the lease expires mid-operation. Consensus (Raft/Paxos) needs a MAJORITY — a 2-node or even-sized cluster buys nothing — and stays OFF the hot path. NEVER order distributed events, compute expiry, or resolve conflicts by wall clock — use versions/sequences, logical/vector clocks, or HLC. | An unfenced lock fails exactly once — under a GC/VM pause, at peak, writing corrupted state — and looks correct in every test (split brain) |
| Transaction / aggregate boundary | One aggregate per transaction; reference other aggregates by ID only; keep aggregates SMALL; cross-aggregate consistency is EVENTUAL via domain events. Money movement, uniqueness, inventory decrement and auth state stay strong inside ONE aggregate/DB transaction. | Large aggregates cause lock contention; cross-aggregate transactions force 2PC or silent divergence |
| Cross-boundary transaction mechanism | Local ACID (ALWAYS prefer) → saga + compensation → reservation/TCC. AVOID 2PC/XA in web-scale distributed systems. Compensations are NEW BUSINESS FACTS (RefundIssued), not technical rollbacks — design them as product decisions, and design for the intermediate state being USER-VISIBLE. | "We'll use a distributed transaction" is a non-answer that blocks on coordinator failure |
| Tenancy model | Shared-schema tenant_id (default for most B2B SaaS) · schema-per-tenant · DB-per-tenant (regulated / residency / white-label / large enterprise) · hybrid tiering (pooled small + siloed whales — the mature scale-up shape). | Retrofitting tenancy is a full data migration |
| Tenant isolation ENFORCEMENT | In a pooled model, name the LOWEST-layer mechanism: database row-level security, an ORM global filter/interceptor, or a mandatory repository base injecting tenant from the authenticated principal — plus a test asserting cross-tenant reads return zero rows (Step 6 + Step 9 fitness rule). NEVER take tenant_id from a client-supplied field. | One missing WHERE tenant_id = ? is a cross-tenant breach that passes every functional test |
| Keys & partitioning | Prefer time-ordered IDs (UUIDv7/ULID/Snowflake) — sequential ints leak volume and are enumerable; UUIDv4 destroys index locality on write. NEVER expose an internal sequential PK publicly. Partition key must be uniformly distributed AND query-aligned; plan resharding (consistent hashing / virtual buckets) BEFORE needing it. | Hot partitions (time-based ⇒ hot latest; tenant-based ⇒ whale tenants) and write amplification |
| OLTP / OLAP separation | Analytics go to a replica, CDC, or warehouse — never the transactional primary. | Reports saturating production is a top incident cause |
| Denormalization / caching as a PURCHASE | For each denormalized copy or cache, name the mechanism keeping it correct and its invalidation strategy (TTL + jitter · event-driven · versioned/namespaced keys). Bound every cache (max size + eviction). NEVER cache authorization decisions or per-tenant data under a key omitting the identity/tenant/permission dimension. | Cache-key omission is a recurring cross-tenant leak that passes all functional tests; unbounded caches OOM |
| Migration strategy | Expand–contract (add nullable → dual write → backfill → switch reads → stop writing old → drop), forward-only, idempotent, non-blocking on large tables, deployable independently of the code using it. | A breaking migration in one deploy breaks old pods during a rolling deploy and makes rollback impossible |
| Lifecycle: classification, retention, residency, deletion | Classify (PII/PHI/PCI/public), set retention + archival tiering + deletion (GDPR/CCPA erasure) + residency NOW. | Retrofitting deletion into an event-sourced or heavily-denormalized system is brutally expensive — and erasure conflicts with immutable event stores by design |
| RPO / RTO per dataset | Set them PER DATASET (they drive topology and cost) and schedule a restore drill. | "We have backups" is a hypothesis; an undrilled DR plan has an RTO of "unknown" |
MANDATORY IMPORTANT MUST ATTENTION emit an ADR for the store choice, the tenancy model, the consistency model per read path, and the key strategy — these four are the least reversible decisions in the entire design — why: each one reversed later is a full data migration with downtime, not a refactor.
Skip if: no boundary is crossed — no external consumer, no second service, no message bus, no third-party integration. Otherwise MANDATORY.
| Decision | Decide + record | Failure if skipped |
|---|---|---|
| Sync vs async per boundary | Synchronous only when the caller genuinely cannot proceed without the answer (user-awaited QUERIES). Asynchronous for EFFECTS (notification, fan-out, work completable later). A sync chain deeper than 2-3 hops is an availability + latency defect — flatten, cache, or make it an event. | Sync chains MULTIPLY availability (five 99.9% deps ⇒ 99.5%) and SUM latency |
| API style per consumer | REST/HTTP+JSON (public, broad compat, HTTP caching) · GraphQL (client-driven queries, aggregation — needs depth/complexity limits + persisted queries + dataloader or it becomes a DoS and N+1 surface) · gRPC (low-latency internal, streaming, codegen) · webhooks (push to third parties — needs retries + signature verification) · WebSocket/SSE (real-time; SSE when one-way suffices). | Wrong style makes the dominant interaction chatty or uncacheable |
| Versioning + deprecation policy | Version from day one (URL path versioning is the pragmatic default); version the CONTRACT, not every field; support ≥N-1 with a published deprecation policy + per-version usage telemetry. | Versionless contracts mean any producer change breaks consumers — and you cannot tell who |
| Contract-first + contract tests in CI | OpenAPI / protobuf / AsyncAPI as the source of truth; consumer-driven contract tests are what make independent deploys SAFE (Step 6 + Step 9 gate). Tolerant reader — unknown fields ignored, never fatal. | Without contract tests, "independently deployable" is an aspiration, not a property |
| Write-then-publish ⇒ transactional outbox or CDC | MANDATORY whenever a flow writes the DB and publishes. NEVER two independent operations. | Dual-write: DB commits + publish fails ⇒ silent divergence; publish succeeds + DB rolls back ⇒ phantom downstream data |
| Idempotency everywhere | Exactly-once DELIVERY is impossible (Two Generals/FLP) ⇒ effectively-once via idempotency. Idempotency keys (with the stored RESULT + TTL) on all unsafe mutations; consumers dedup on message ID; prefer naturally idempotent operations (SET status='paid' over balance += x); optimistic concurrency via version/ETag. Assume duplicate, out-of-order and delayed arrival — carry a version/sequence and discard backward transitions. | Duplicate side effects: double charge, double email, double shipment |
| Message taxonomy — never conflate | Command ("do this", one handler, may be rejected) vs Event/fact ("this happened", 0..N subscribers, cannot be rejected) vs query vs document message. An "event" with exactly one permitted consumer that MUST handle it, whose failure means the flow failed, is a COMMAND in an event costume — name it a command and own the coupling honestly. | You pay async debugging difficulty AND keep sync coupling |
| Event granularity per stream | Deliberate choice: thin/notification (ID only — restores temporal coupling + read load) vs fat/state-transfer (self-contained, leaks more model, bigger payloads) vs hybrid (thin event + queryable snapshot endpoint). NEVER leak raw DB rows as events — CDC without a mapping layer publishes your internal schema as a frozen public contract (Hyrum). | Consumers become coupled to columns you can then never rename |
| Schema evolution | Versioned, registered, backward-compatible event schemas with a CI compatibility check. In event sourcing, event schemas are public contracts forever. | One producer change silently breaks every consumer |
| Broker semantics — ordering, replay, durability | Decide the three properties BEFORE naming a vendor: required ordering scope (global / per-entity-key / none) · required replay window (queue = consume-and-gone; log = offset-based replay by many consumer groups) · durability acknowledgement (replication factor + min-in-sync-replicas + producer acks — acks=1 accepts data loss on leader failure, and acks=all waits for the replicas CURRENTLY in the ISR — so min.insync=1 still waits for a healthy 3-replica ISR but silently degrades to acks=1 durability once the ISR shrinks to the leader alone). Log partition count is hard to raise without rekeying, and ordering on a key costs parallelism on that key. Health SLI: queue depth + oldest-message age, or consumer lag for a log. | Vendor picked first ⇒ the one property you actually needed (ordering, replay, or durability) turns out to be the one that is expensive to change |
| Load-balancing + rate-limiting algorithm | LB: least-outstanding-requests is the best general default (routes away from slow hosts automatically) · power-of-two-choices · consistent hashing only for cache/shard affinity (accept hot keys) · slow-start for new instances so a cold cache/JIT node is not handed full traffic. Rate limiting: token bucket for burst-tolerant public APIs · sliding-window counter for accuracy · concurrency/in-flight limiter when per-request cost is unknown or highly variable (it bounds the resource, not the count). Limit BY the protected dimension (tenant/principal/endpoint), never only by IP; always return Retry-After. Distributed enforcement needs a shared counter (new hot-path dependency) or per-node quota division (accept N× slack) — state which. | Round-robin ignores request cost and feeds a dying host; fixed-window limiters permit a 2× burst across the boundary; sticky sessions become the reason state was never externalized |
| Queue hygiene | Bounded queues + DLQ + a redrive procedure + DLQ-depth alerting; capped exponential backoff with jitter; poison-message handling. | An unbounded queue converts a throughput problem into unbounded latency then OOM; a DLQ nobody watches is data loss with extra steps; unjittered retries synchronize into a thundering herd |
| Resilience config on EVERY outbound call | Timeout (derived from the caller's remaining budget) on every network call, lock and query · capped jittered retries for idempotent ops ONLY · retry BUDGET as a % of traffic · circuit breaker with a defined fallback · bulkheads per dependency/tenant · load shedding at the edge by priority. | A missing timeout is the single most common resilience defect; retry amplification turns a blip into an outage. The dangerous failure is SLOW, not down — it exhausts your resources while looking healthy |
| Graceful degradation per feature | Pre-decide the degraded mode per feature (stale data / hide module / read-only) — a PRODUCT decision, made now, not during the incident. | Undesigned degradation becomes a total outage |
| Trust boundary rules | Validate at the boundary (allow-list); NEVER trust client-supplied authorization data — IDs, roles, prices, tenant IDs come from the authenticated principal. Machine-readable error contract (stable code, message, details, traceId; RFC 9457 problem+json is a good default) — NEVER leak stack traces. Propagate a correlation/trace ID through EVERY hop including async. | Broken access control is the #1 real-world risk; untraceable async hops make incidents unexplainable |
| Edge component responsibilities | Gateway = TLS, routing, authn, rate limiting, quotas, versioning — NEVER business logic (smart-gateway anti-pattern: a shared bottleneck every team queues for). BFF only when a client genuinely needs its own aggregation AND the frontend team owns it — skip it with one client or when GraphQL already fills the role. | A gateway or BFF holding domain rules duplicates the domain in a layer no team owns |
MANDATORY IMPORTANT MUST ATTENTION every sync-vs-async choice at a boundary and every public API/event contract is a one-way door — ADR + Step-12 validation, no exceptions — why: consumers you cannot see will depend on both, and Hyrum's Law makes every observable behavior a contract you must then keep.
WebSearch top 3 frontend architecture styles. Candidates:
| Style | Best For | Research Focus |
|---|---|---|
| MVVM | Data-binding heavy, forms-over-data apps | ViewModel responsibility, two-way binding |
| MVC | Server-rendered, traditional web apps | Controller routing, view separation |
| Component Architecture | Configured SPA/component framework | Component isolation, props/events, reuse |
| Reactive Store (Redux) | Complex state, multi-component sync | Single source of truth, immutable state |
| Signal-based Reactivity | Fine-grained reactivity in frameworks that support signals | Granular updates without broad change detection |
| Micro Frontends | Multiple teams, independent deployment | Module federation, routing, shared state |
| Feature-based Modules | Large monolith SPA, lazy loading | Feature boundaries, route-level splitting |
| Server Components (RSC) | SEO, initial load performance | Server/client boundary, streaming |
| Pattern | Layer | When to Apply |
|---|---|---|
| Container/Presentational | Component | Separate logic from UI rendering |
| Reactive Store | State | Centralized state, cross-component communication |
| Facade Service | Service | Simplify complex API interactions |
| Adapter/Mapper | Data | Transform API response to view model |
| Observer (RxJS) | Async | Event streams, real-time data, debounce/throttle |
| Strategy (renderers) | UI | Conditional rendering strategies per entity type |
| Composite (components) | UI | Tree structures, recursive components |
| Command (undo/redo) | UX | Form wizards, canvas editors, undoable actions |
| Lazy Loading | Performance | Route/module-level code splitting |
| Virtual Scrolling | Performance | Large lists, infinite scroll |
Skip if: Backend-only project, no frontend component.
Research, recommend project design system architecture. Use ask the user directly for each decision.
WebSearch top 3 styling approaches for confirmed frontend framework:
| Approach | Best For | Research Focus |
|---|---|---|
| Utility-first (Tailwind CSS) | Rapid prototyping, design enforcement | JIT, custom config, design tokens |
| CSS Modules / Scoped CSS | Component isolation, no global conflicts | Naming, composition patterns |
| SCSS/SASS with BEM | Complex theming, token variables | BEM methodology, mixin libraries |
| CSS-in-JS | Dynamic styling, theme providers | Runtime perf, SSR support |
| CSS Custom Properties | Native theming, framework-agnostic | Browser support, fallback strategy |
| Decision | Options | Default |
|---|---|---|
| Token format | CSS custom properties / JSON / SCSS variables | CSS custom properties |
| Token categories | Color, spacing, typography, breakpoints, shadows, z-index | All |
| Token naming | Semantic (--color-primary) vs Functional (--btn-bg) | Semantic first |
| Theming | Light/dark toggle / Multi-brand / Single theme | Single + dark mode |
| Decision | Options | Default |
|---|---|---|
| Library | Build custom / Headless (Radix, Headless UI) / Full kit (MUI, Ant, PrimeNG) | Based on team and timeline |
| Component tiers | Common → Domain-Shared → Page (per ui-wireframe-protocol) | Standard 3-tier |
| Documentation | Storybook / Docusaurus / In-code only | Based on team size |
| Decision | Options | Default |
|---|---|---|
| Approach | Mobile-first / Desktop-first / Adaptive | Mobile-first |
| Breakpoints | 320/768/1024/1280 / Custom | Standard |
| Grid system | CSS Grid / Flexbox / Framework grid | CSS Grid + Flexbox |
MANDATORY IMPORTANT MUST ATTENTION validate all UI system decisions with user by asking the user directly before proceeding to Step 5.
Per concern below, WebSearch top 3 library options for confirmed tech stack. Evaluate: maturity, community, bundle size, maintenance activity, license, learning curve.
MUST ATTENTION never recommend a library from familiarity alone — every pick needs cited evidence (stars, release date, downloads, CVE scan). — why: familiarity bias ships unmaintained or insecure dependencies.
| Concern | What to Research | Evaluation Criteria |
|---|---|---|
| Validation | Input validation, schema validation, form validation | Type safety, composability, error messages |
| HTTP Client / API Layer | REST client, GraphQL client, API code generation | Interceptors, retry, caching, type generation |
| State Management | Global store, local state, server state caching | DevTools, SSR support, bundle size |
| Utilities / Helpers | Date/time, collections, deep clone, string manipulation | Tree-shakability, size, native alternatives |
| Caching | In-memory cache, distributed cache, HTTP cache, query cache | TTL, invalidation, persistence |
| Logging | Structured logging, log levels, log aggregation | Structured output, transports, performance |
| Error Handling | Global error boundary, error tracking, crash reporting | Source maps, breadcrumbs, alerting integration |
| Authentication / AuthZ | JWT, OAuth, RBAC/ABAC, session management | Standards compliance, SSO, token refresh |
| File Upload / Storage | Multipart upload, cloud storage SDK, image processing | Streaming, resumable, size limits |
| Real-time | WebSocket, SSE, SignalR, Socket.io | Reconnection, scaling, protocol support |
| Internationalization | i18n, l10n, pluralization, date/number formatting | ICU support, lazy loading, extraction tools |
| PDF / Export | PDF generation, Excel export, CSV | Server-side vs client-side, template support |
### {Concern}: Top 3 Options
| Criteria | Option A | Option B | Option C |
| ---------------- | ----------------- | -------- | -------- |
| GitHub Stars | ... | ... | ... |
| Last Release | ... | ... | ... |
| Bundle Size | ... | ... | ... |
| Weekly Downloads | ... | ... | ... |
| License | ... | ... | ... |
| Maintenance | Active/Slow/Stale | ... | ... |
| Learning Curve | Low/Med/High | ... | ... |
**Recommendation:** {Option} — Confidence: {X}%
Research best testing tools, strategy for confirmed tech stack:
| Testing Layer | What to Research | Top Candidates to Compare |
|---|---|---|
| Unit Testing | Test runner, assertion library, mocking framework | Repository's configured unit-test stack |
| Integration Testing | API testing, DB testing, service testing | Supertest, TestContainers, WebAppFactory |
| E2E Testing | Browser automation, BDD, visual regression | Playwright/Cypress/Selenium, SpecFlow |
| Performance Testing | Load testing, stress testing, benchmarking | k6/Artillery/JMeter/NBomber, BenchmarkDotNet |
| Contract Testing | API contract validation between services | Pact, Dredd, Spectral |
| Mutation Testing | Test quality validation | Stryker, PITest |
| Coverage | Code coverage collection, reporting, enforcement | Istanbul/Coverlet, SonarQube |
| Test Data | Factories, fixtures, seeders, fakers | Bogus/AutoFixture/Faker.js |
### Test Pyramid
- **Unit (70%):** {framework} — {what to test}
- **Integration (20%):** {framework} — {what to test}
- **E2E (10%):** {framework} — {what to test}
### Test-Strength Targets
- Line coverage (diagnostic only — NEVER fail the build on a coverage %): Unit: {X}% | Integration: {X}% | E2E: critical paths only
- Gate: mutation score ({tool}) in CI pipeline — fail build on surviving mutants / mutation-score regression, not on a line-coverage %
Research deployment architecture, CI/CD tooling:
| Concern | What to Research | Top Candidates to Compare |
|---|---|---|
| CI/CD Provider | Pipeline orchestration, parallelism, caching | Repository's configured CI/CD tooling |
| Containerization | Container runtime, image building, registry | Docker/Podman, BuildKit, ACR/ECR/GHCR |
| Orchestration | Container orchestration, service mesh, scaling | Kubernetes/Docker Compose/ECS/Nomad |
| IaC (Infra as Code) | Infrastructure provisioning, drift detection | Terraform/Pulumi/Bicep/CDK |
| Artifact Management | Package registry, versioning, vulnerability scanning | NuGet/npm/Artifactory/GitHub Packages |
| Feature Flags | Progressive rollout, A/B testing, kill switches | LaunchDarkly/Unleash/Flagsmith |
| Secret Management | Vault, key rotation, environment variables | Azure KeyVault/HashiCorp Vault/SOPS |
| Database Migration | Schema versioning, rollback, seed data | EF Migrations/Flyway/Liquibase/dbmate |
| Strategy | Risk | Downtime | Complexity | Best For |
|---|---|---|---|---|
| Blue-Green | Low | Zero | Medium | Critical services |
| Canary | Low | Zero | High | Gradual rollout |
| Rolling | Med | Zero | Low | Stateless services |
| Recreate | High | Yes | Low | Dev/staging environments |
| Feature Flags | Low | Zero | Medium | Feature-level control |
| Rule | Requirement |
|---|---|
| Decouple deploy from release | Flags / canary with SLI gates + auto-rollback. A flag needs an EXPIRY date or it becomes permanent branching complexity |
| Backward AND forward compatible for one version | MANDATORY — a rolling deploy runs both versions SIMULTANEOUSLY. Applies to APIs, event schemas AND database schemas alike |
| Expand–contract migrations | Add nullable → dual write → backfill → switch reads → stop writing old → drop. Forward-only, idempotent, non-blocking, deployed INDEPENDENTLY of the code using it. NEVER a breaking schema change in one deploy |
| One artifact, external config | Build once, promote the same artifact across environments (12-factor); config and secrets injected per environment |
| Graceful shutdown | Stop accepting → drain in-flight with a deadline → flush buffers/metrics → close pools → exit. Without it EVERY deploy sheds requests |
| Liveness ≠ readiness | Readiness reflects dependencies; liveness must NOT (or one dependency blip restarts the whole fleet). Add startup probes for slow boots |
| Legacy replacement | Strangler fig (facade + capability-by-capability routing) or branch by abstraction, with parallel run / shadow compare for high-risk replacements. NEVER a big-bang rewrite of a system you don't fully understand — you inherit all undocumented behavior as invisible requirements |
| DORA as delivery SLIs | Deploy frequency, lead time, change-failure rate, MTTR — measure outcomes, never proxy metrics (Goodhart) |
MANDATORY IMPORTANT MUST ATTENTION if the design changes a database schema or a published contract, the migration plan is part of THIS design, not an implementation detail deferred to plan-execute — why: a schema change designed without expand–contract makes the whole release irreversible.
| Concern | What to Research | Top Candidates to Compare |
|---|---|---|
| Structured Logging | Log format, correlation IDs, log levels, aggregation | Serilog/NLog/Winston/Pino |
| Log Aggregation | Centralized log search, dashboards, alerts | ELK/Loki+Grafana/Datadog/Seq |
| Metrics | Application metrics, custom counters, histograms | Prometheus/OpenTelemetry/App Insights |
| Distributed Tracing | Request tracing across services, span visualization | Jaeger/Zipkin/OpenTelemetry/Tempo |
| APM | Application performance monitoring, auto-instrumentation | Datadog/New Relic/App Insights/Elastic |
| Alerting | Threshold alerts, anomaly detection, on-call routing | PagerDuty/OpsGenie/Grafana Alerting |
| Health Checks | Liveness, readiness, startup probes | AspNetCore.Diagnostics/Terminus |
| Uptime Monitoring | External availability monitoring, SLA tracking | UptimeRobot/Pingdom/Checkly |
### Recommended Observability Stack
| Pillar | Tool | Why |
| -------- | ------ | ----------- |
| Logs | {tool} | {rationale} |
| Metrics | {tool} | {rationale} |
| Traces | {tool} | {rationale} |
| Alerting | {tool} | {rationale} |
Research, recommend tooling for automated code quality:
| Concern | What to Research | Top Candidates to Compare |
|---|---|---|
| Linter (Backend) | Static analysis, code style, bug detection | Roslyn Analyzers/SonarQube/StyleCop/ReSharper |
| Linter (Frontend) | JS/TS linting, accessibility, complexity | ESLint/Biome/oxlint |
| Formatter | Auto-formatting, consistent style | Prettier/dotnet-format/EditorConfig |
| Code Analyzer | Security scanning, complexity metrics, duplication | SonarQube/CodeClimate/Codacy |
| Pre-commit Hooks | Git hooks, staged file validation | Husky+lint-staged/pre-commit/Lefthook |
| Editor Config | Cross-IDE consistency | .editorconfig/IDE-specific configs |
| Architecture Rules | Layer dependency enforcement, naming conventions | ArchUnit/NetArchTest/Dependency-Cruiser |
| API Design Standards | OpenAPI validation, naming, versioning | Spectral/Redocly/swagger-lint |
| Commit Conventions | Commit message format, changelog generation | Commitlint/Conventional Commits |
| Code Review Automation | Automated PR review, suggestion bots | Danger.js/Reviewdog/CodeRabbit |
### Code Quality Gates
| Gate | Tool | Trigger | Fail Criteria |
| ----------- | ------ | -------------- | --------------------- |
| Pre-commit | {tool} | git commit | Lint errors, format |
| PR Check | {tool} | Pull request | Surviving mutants / mutation-score regression, issues (line-coverage diagnostic only) |
| CI Pipeline | {tool} | Push to branch | Build fail, test fail |
| Scheduled | {tool} | Weekly/nightly | Security vulns, debt |
$scaffold)After code-quality research, produce this handoff table in the architecture report. $scaffold reads it to generate actual config files — without it, scaffold cannot auto-configure quality tooling. — why: the handoff table is the only contract scaffold has for tool choices.
### Scaffold Handoff — Tool Choices
| Concern | Chosen Tool | Config File | Rationale |
| -------------- | ----------------- | ----------- | --------- |
| Linter (FE) | {tool} | {filename} | {why} |
| Linter (BE) | {tool} | {filename} | {why} |
| Formatter | {tool} | {filename} | {why} |
| Pre-commit | {tool} | {filename} | {why} |
| Arch rules / fitness | {tool: ArchUnit / NetArchTest / Dependency-Cruiser} | {filename} | {layer + dependency rules and Step-2 NFR budgets to enforce} |
| Error handling | {pattern} | {files} | {why} |
| Loading state | {pattern} | {files} | {why} |
| Docker | {compose pattern} | {files} | {why} |
Also include: Error handling strategy (4-layer pattern), loading state approach (global vs per-component), Docker profile structure. Specific tool choices → docs/project-reference/ or project-config.json. The Arch rules / fitness row MUST encode Step-2 quality-attribute budgets and layer/dependency rules as executable checks — harness-setup wires these into CI so recorded ADR decisions stay enforced, not merely documented. — why: documented-but-unenforced budgets erode silently as code changes.
Example patterns to scaffold (golden-path reference set): the handoff MUST also name the worked, copy-me examples $scaffold emits under an isolated, production-excluded examples/ tree — one per applicable pattern, using the scaffolded base abstractions, so the post-scaffold $architecture-review-full has real code to grade. Target set (≥ 11 when a UI is present; skip absent layers and log why):
### Scaffold Handoff — Golden-Path Examples
| Layer | Example patterns (one worked `*.example.*` each) |
| --------- | ------------------------------------------------------------------------------------------------------ |
| Backend | command · query · command/query handler · entity-with-invariants · value-object · repository (concrete) · domain event + event handler |
| Frontend | form component · list component · state store · API service *(only if a UI stack is present)* |
| Tests | one integration test exercising an example command/query on BOTH the happy path AND a failure path |
Every example carries the GOLDEN-PATH EXAMPLE — copy into src/ …; NOT compiled into the production build header, contains NO secrets/real endpoints (placeholders only: EXAMPLE_API_KEY, example.invalid), and compiles/lints under the CI (non-production) target. — why: empty base abstractions are unverified skeletons; one worked example per pattern turns each into demonstrated, reviewable, copy-me usage.
Per recommended library/package, evaluate maintenance, obsolescence risk:
| Criteria | Score (1-5) | How to Verify |
|---|---|---|
| Last Release Date | ... | npm/NuGet page — stale if >12 months |
| Open Issues Ratio | ... | GitHub issues open vs closed |
| Maintainer Count | ... | Bus factor — single maintainer = high risk |
| Breaking Change Freq. | ... | Changelog — frequent major versions = churn cost |
| Dependency Depth | ... | npm ls --depth / dependency graph depth |
| Known Vulnerabilities | ... | Snyk/npm audit/GitHub Dependabot |
| License Compatibility | ... | SPDX identifier — check viral licenses (GPL) |
| Community Activity | ... | Monthly commits, PR merge rate, Discord/forums |
| Migration Path | ... | Can swap to alternative if abandoned? |
| Framework Alignment | ... | Official recommendation by framework team? |
| Risk Level | Criteria | Action |
|---|---|---|
| Low | Active, >3 maintainers, recent release, no CVEs | Use freely |
| Medium | 1-2 maintainers, release <6mo, minor CVEs patched | Use with monitoring plan |
| High | Single maintainer, >12mo stale, open CVEs | Find alternative or plan exit strategy |
| Critical | Abandoned, unpatched CVEs, deprecated | DO NOT USE — find replacement |
### Recommended Practices
1. **Automated scanning:** {tool} (Dependabot/Renovate/Snyk) — weekly PR for updates
2. **Lock file strategy:** Commit lock files, pin major versions, allow patch auto-update
3. **Audit schedule:** Monthly `npm audit` / `dotnet list package --vulnerable`
4. **Vendor policy:** Max {N} dependencies per concern, prefer well-maintained alternatives
5. **Exit strategy:** For each High-risk dependency, document migration path to alternative
Write report to {plan-dir}/research/architecture-design.md with sections:
$/request or $/tenant, the dominant drivers, and whether unit cost rises with scaleMUST ATTENTION every diagram needs a legend, a date and an owner — an undated diagram is a rumor. Show trust boundaries and failure domains explicitly: that is the entire point of drawing a deployment view.
For each decision significant AND costly to reverse — every one-way door classified in Step 2-0: backend/frontend style, data model + key strategy, tenancy model, consistency model per read path, sync-vs-async at a boundary, public API/event contract, service boundary lines, auth/identity model, data residency + retention, messaging approach, a Step-2 quality-attribute budget, a rejected-with-reason alternative — write one ADR to docs/adr/{NNNN}-{slug}.md following the repo's existing ADR format (Status, Date, Context, Decision, Consequences [Positive/Negative/Neutral], Alternatives Considered, Related; see docs/adr/0001-skill-lifecycle.md for canonical shape). Start Status: Proposed; promote to Accepted after Step-12 user validation confirms it. These ADRs are the binding record architecture-review Category 9 checks changed code against — a decision not written as an ADR cannot be enforced downstream. Route ADR authoring through the architect sub-agent for cross-service/security/performance impact analysis.
ADR minimum content — the two most-skipped fields are the most valuable: Context (forces, constraints, quantified attributes) · Decision · Alternatives considered WITH why each was rejected (prevents relitigating, and later explains the constraint to whoever is tempted to break it) · Consequences (what we now CANNOT do easily) · Status · Revisit trigger (the measurement that would reopen this decision).
MUST ATTENTION an architectural rule NOT automatically verified is a SUGGESTION and will be violated within one quarter. Every ADR-recorded constraint that CAN be machine-checked MUST also land in the Step-9 Scaffold Handoff as an executable fitness rule (layer/dependency rules, no module cycles, domain purity, API + event schema compatibility, tenant-isolation test, "every outbound call has a timeout", bundle/latency budgets, cost-per-request regression). Pay existing architectural debt with a RATCHET — block new violations in CI, then decrement the existing count — never with a "cleanup sprint later" that never happens.
```mermaid
graph TB
subgraph "Frontend"
UI[SPA / Micro Frontend]
STORE[State Management]
end
subgraph "API Gateway"
GW[Gateway / BFF]
end
subgraph "Backend Services"
CMD[Commands / Handlers]
QRY[Queries / Read Models]
SVC[Domain Services]
ENT[Entities / Aggregates]
end
subgraph "Infrastructure"
DB[(Database)]
CACHE[(Cache)]
MSG[Message Bus]
SEARCH[(Search Index)]
end
subgraph "Observability"
LOG[Logging]
METRIC[Metrics]
TRACE[Tracing]
end
subgraph "CI/CD"
PIPE[Pipeline]
REG[Container Registry]
K8S[Orchestration]
end
UI --> GW --> CMD & QRY
CMD --> SVC --> ENT --> DB
QRY --> CACHE & SEARCH
ENT -.-> MSG
CMD & QRY -.-> LOG & METRIC & TRACE
PIPE --> REG --> K8S
```
MANDATORY IMPORTANT MUST ATTENTION present findings, ask 8-12 questions by asking the user directly: