architecture-design

Imported from duc01226/easy-claude (.agents/skills/architecture-design/SKILL.md). Install upstream with npx skills add duc01226/easy-claude --skill architecture-design. Copyright stays with the author.

Codex compatibility note:

• Invoke repository skills with $skill-name in Codex; this mirrored copy rewrites legacy Claude /skill-name references.
• 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_agent subagent(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 Project-Reference Loading (No Hooks)

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/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): project-structure-reference.md
• Backend/CQRS/API/domain/entity changes: backend-patterns-reference.md, domain-entities-reference.md
• Frontend/UI/styling/design-system: frontend-patterns-reference.md, scss-styling-guide.md, design-system/README.md
• Spec authoring, docs/specs/ pathing, or TC format: feature-spec-reference.md, spec-system-reference.md, spec-principles.md
• Behavior/public-contract changes or spec-test-code sync: workflow-spec-test-code-cycle-reference.md plus the spec docs above
• Derived spec indexes/ERDs/reimplementation guides: spec-system-reference.md and source Feature Specs under docs/specs/
• Integration test implementation/review: integration-test-reference.md
• E2E test implementation/review: e2e-test-reference.md
• Code review/audit work: code-review-rules.md plus domain docs above based on changed files

Do 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_progress when step starts, set completed when 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.

Quick Summary

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:

• Testability contract: resolve Unit/Integration/System/E2E applicability from runner/config evidence; record owner/root/data, copy-ready full + focused commands, zero-match behavior, CI/simple-Windows entry, unique run/data identity, and repeat proof; unresolved applicable fields block handoff, while non-applicable tiers require evidence-backed N/A.

• Decide mode FIRST (Step 1): greenfield researches every concern from scratch; brownfield reads reference docs + accepted ADRs, constrains research to existing stack — NEVER re-litigate a settled ADR-recorded decision without superseding-ADR rationale.

• Rank every decision by REVERSIBILITY first (Step 2): one-way door (data model, tenancy, consistency model, service boundaries, public contracts, sync-vs-async) → ADR + user validation MANDATORY; two-way door → decide and move. — why: architecture IS the set of decisions expensive to reverse; treating a one-way door as reversible is the costliest error this skill can make.

• Drive style choice with NUMBERS, not adjectives: quantify Step-2 quality-attribute scenarios (latency p95/p99, throughput, SLO, RPO/RTO, data growth, concurrency); pick ≤3 DRIVING attributes and name which ones you SACRIFICE; any unknown target becomes explicit Unresolved question, never a silent guess.

• Profile the workload before selecting a scaling technique: read/write ratio · sustained/peak RPS · query shapes · data size/growth · burstiness/hot keys · consistency/staleness · user geography. Escalate through the smallest reversible rung: measure/tune → choose vertical and/or stateless horizontal scale from headroom + availability needs → read/write-specific tactics → partition/shard LAST. — why: a scalable product is a sequence of evidenced bottleneck removals, not a shopping list of distributed components.

• Simplicity is the default; complexity must be BOUGHT with a measured requirement — modulith-first, distribute only against a named + measured extraction trigger (Step 3A). Reason FROM .claude/docs/architecture-knowledge.md (laws, coupling taxonomy, style triggers, trade-off + anti-pattern catalogs) — never from familiarity or fashion.

• Every concern needs 3+ researched options with cited evidence (stars, last release, downloads, CVE scan) + confidence % — familiarity alone never sufficient grounds for a recommendation.

• Interrogate before deciding, DESIGN IT TWICE, then self-audit: run the 15-question pre-decision script (§20.1) on every one-way door (Step 2-2) · produce ≥2 MATERIALLY different candidates per one-way door before choosing (Step 3A) · run the 11 thinking red flags (§20.3) against your own draft before emitting. Prescribe the TACTIC (§2), never the product. — why: a first-idea design with no rejected alternative and no named falsifier is a belief, not a decision.

• Produce the two binding downstream contracts or the chain breaks: emit an ADR per hard-to-reverse decision (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.

• Main steps/tasks (run in order, track each): 1 Load Context (+pick greenfield/brownfield mode) → 2 Derive Architecture Requirements (+workload profile/scaling ladder, reversibility ranking, ≤3 driving attributes, 6-part quality-attribute scenarios, 2-2 pre-decision interrogation, user-validate) → 3A Backend Styles (selection procedure incl. DESIGN IT TWICE + extraction triggers) → 3B Backend Design Patterns → 3C Data & Consistency Architecture (store/substrate per access pattern, replication/failover, cache contract, consistency + staleness, transaction boundary, tenancy, partitioning, migrations, retention) → 3D Integration & API Architecture (sync-vs-async + acceptance state, API/edge cache style, versioning, contract tests, outbox, idempotency, event granularity) → 4 Frontend Architecture (styles + patterns) → 4B UI System Architecture (styling/tokens/components/responsive, user-validate; skip if backend-only) → 5 Library Ecosystem Research (3 options/concern) → 6 Testing Architecture → 7 CI/CD & Deployment (+expand–contract migrations, backward AND forward compat) → 8 Observability & Monitoring (signal roles + sampling/cardinality) → 9 Code Quality + Scaffold Handoff table → 10 Dependency Risk Assessment → 11 Generate Report + emit ADRs → 12 User Validation Interview (8-12 questions, mark confirmed) → Next Steps + always-offer council escalation. — why: AI keeps forgetting the skill's own steps; this is the recovery anchor.

Workflow (12 steps):

1. Load Context — Read domain model, tech stack, business evaluation, refined PBI
2. Derive Architecture Requirements — Profile workload + ordered scaling ladder, rank reversibility, pick ≤3 driving attributes, quantify 6-part scenarios, run 2-2 pre-decision interrogation on every one-way door
3. Backend Architecture — 3A styles (selection procedure) · 3B design patterns · 3C data & consistency · 3D integration & APIs
4. Frontend Architecture — Research top 3 frontend architecture styles + design patterns
5. Library Ecosystem Research — Best-practice libraries per concern (validation, caching, logging, utils, etc.)
6. Testing Architecture — Unit, integration, E2E, performance testing frameworks + strategy
7. CI/CD & Deployment — Pipeline design, containerization, orchestration, IaC
8. Observability & Monitoring — Logging, metrics, tracing, alerting stack
9. Code Quality & Clean Code — Linters, analyzers, formatters, enforcement tooling
10. Dependency Risk Assessment — Package health, obsolescence risk, maintenance cost
11. Generate Report — Full architecture decision report with all recommendations
12. User Validation — Present findings, ask 8-12 questions, confirm all decisions

Key Rules:

• MANDATORY IMPORTANT MUST ATTENTION research minimum 3 options per architecture concern with web evidence
• MANDATORY IMPORTANT MUST ATTENTION include confidence % with evidence for every recommendation
• MANDATORY IMPORTANT MUST ATTENTION run user validation interview at end (never skip)
• Delegate to solution-architect agent for complex architecture decisions
• All claims must cite sources (URL, benchmark, case study, or codebase evidence)
• Base every recommendation on evidence, never on familiarity alone

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Inputs & Handoffs (consume vs produce)

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.

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.

Step 1: Load Context

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/):

• Domain model / ERD (complexity, bounded contexts, aggregate count)
• Tech stack decisions (confirmed languages, frameworks, databases)
• Business evaluation (scale, constraints, compliance)
• Refined PBI (scope, acceptance criteria)
• Discovery interview (team skills, experience level)

Extract, summarize:

Step 2: Derive Architecture Requirements

Reason FROM the knowledge body, not from memory. .claude/docs/architecture-knowledge.md is 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 — VERIFY is 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.

2-0: Rank every decision by REVERSIBILITY (do this FIRST)

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.

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:

Quality-Attribute Scenarios (quantify — these drive the style choice)

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.

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.

Workload Profile + Scaling Ladder (MANDATORY before technique selection)

Record read:write ratio · sustained/peak RPS or events/s · dominant query/write shapes · dataset size + growth · payload size · burst duration · hot-key/tenant skew · user regions · latency percentile targets · consistency/staleness tolerance. For every proposed scaling component, name the measured bottleneck it removes and the next bottleneck it creates.

MANDATORY IMPORTANT MUST ATTENTION NEVER jump to sharding, multi-region writes, or an extra datastore without evidence that earlier rungs cannot meet the quantified target — why: these are hard-to-reverse operational systems, not generic performance upgrades.

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.

2-1: Pick ≤3 DRIVING attributes — and name what you SACRIFICE

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.

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.

2-2: Pre-Decision Interrogation (MANDATORY for every one-way door from 2-0)

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:

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 Scorecard Inputs (feeds 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.

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.

Step 3: Backend Architecture

3A: Architecture Styles

WebSearch top 3 backend architecture styles. Candidates:

Full 16-style matrix with per-style buys / costs / choose-when / avoid-when → .claude/docs/architecture-knowledge.md §5.

Style selection procedure (MANDATORY order — never shortcut)

1. Take the ≤3 quantified driving attributes from Step 2-1.
2. ELIMINATE every style that cannot meet them (state which attribute eliminated it).
3. DESIGN IT TWICE — produce ≥2 MATERIALLY different surviving candidate designs (not two spellings of one idea) and write what each SACRIFICES. — why: committing to the first idea that occurred to you is the most common architecture failure and the one nobody records; a second real candidate is what makes the first one a choice.
4. Among survivors take the SIMPLEST — not the most capable.
5. Emit an ADR (Step 11) naming the rejected alternative AND the measurable trigger that would revisit the choice.

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.

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.

3B: Backend Design Patterns

Evaluate applicability per layer:

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).

Purpose-oriented abstraction naming gate: Name ports, interfaces, modules, APIs, and adapters by the capability or domain contract consumers rely on; keep provider, SDK, framework, database, and transport details on concrete implementations (IStorage/Storage → AzureBlobStorage). Check the proposed name against callers and all implementations, use a narrower name when the contract is narrower, preserve local interface syntax, and require an evidenced boundary/substitution need before adding an abstraction.

Step 3C: Data & Consistency Architecture

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.

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.

Step 3D: Integration & API Architecture

Skip if: no boundary is crossed — no external consumer, no second service, no message bus, no third-party integration. Otherwise MANDATORY.

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.

Step 4: Frontend Architecture

4A: Architecture Styles

WebSearch top 3 frontend architecture styles. Candidates:

4B: Frontend Design Patterns

Step 4B: UI System Architecture

Skip if: Backend-only project, no frontend component.

Research, recommend project design system architecture. Use ask the user directly for each decision.

4B-1: Styling Approach

WebSearch top 3 styling approaches for confirmed frontend framework:

4B-2: Design Token Strategy

4B-3: Component Library Strategy

4B-4: Responsive Strategy

| Decision | Options | Default | | ----------- | ---

Truncated - read the full file at https://github.com/duc01226/easy-claude/blob/e46c5f1a56e43f9a04e7704ede06824623450bf6/.agents/skills/architecture-design/SKILL.md.