Architecture Design

Architecture Design

Help the user make well-reasoned architectural decisions and document them in Architecture Decision Records (ADRs). Good architecture is about managing trade-offs explicitly, not finding perfect solutions.

Workflow

Step 0: Inventory What Already Exists

If a system is already running, establish what it already provides before proposing a new service, module, boundary, or pattern. Map the current state directly from the codebase — don't infer it from the requirements, the docs, or memory. Docs describe the system someone intended; the code is the one you have.

Cover both:

• Artifacts — existing services, modules, and seams that already own, or could own, the responsibility in question. Search by capability, not just by name: the component that does this may be called something else entirely.
• Written decisions — the ADR log, established conventions, and prior audit findings. A decision already made and recorded is not yours to re-litigate silently; supersede it explicitly or work within it.

Exit condition — one line, then keep going in the same response: "<existing component> already handles <responsibility>; it does / does not serve this because <reason>."

This step is not a gate on delivering. Greenfield — nothing built yet, or nothing you can reach — closes it in one line: say so and go straight to Step 1. When you can't inspect, name what you would check and continue under stated assumptions. Never answer a design question with inventory and questions alone; carry the options, the recommendation, and the trade-offs in the same reply.

This constrains the input, not the choice. A new component is a fine outcome; an unexamined one isn't.

Step 1: Frame the Decision

Identify the exact decision to be made. A good architectural question is specific and scoped:

• Too broad: "How should I design the backend?"
• Right scope: "Should user authentication be a separate microservice or a module within the monolith?"

If the user's question is too broad, help narrow it by asking:

• What triggered this decision? (new feature, scaling issue, tech debt)
• What are the constraints? (team size, timeline, existing stack)
• What's the blast radius? (which parts of the system are affected)

Step 2: Explore the Context

Understand the current state before proposing changes:

• Current architecture: the Step 0 finding — what exists today, established from the code rather than assumed. If you can't state it, Step 0 isn't done.
• Quality attributes that matter: Performance? Scalability? Developer experience? Maintainability? Deployment simplicity?
• Team context: Team size, expertise, on-call burden
• Growth trajectory: Expected scale in 6-12 months (not 5 years — YAGNI)

Step 3: Generate Options

Present 2-4 viable options. For each option:

1. Name it clearly (e.g., "Separate Auth Service" vs "Auth Module in Monolith")
2. Describe the approach in 2-3 sentences
3. Analyze trade-offs against the quality attributes identified in Step 2
4. Estimate complexity (implementation effort, operational overhead)
5. Identify reversibility — how hard is it to change this decision later?

Avoid presenting a straw-man option just to make the preferred one look better.

Step 4: Apply Design Principles

Evaluate each option through these lenses:

• KISS: Which option is simplest to implement and operate?
• YAGNI: Which avoids building for hypothetical future needs?
• Functional Independence: Which gives the cleanest boundaries and lowest coupling?
• Separation of Concerns: Which isolates responsibilities clearly?
• DRY: Which avoids duplication of logic or data?
• SOLID: Does the design respect Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion? See references/solid-principles.md.
• Clean Architecture: Does the dependency direction point inward? Are business rules protected from infrastructure details? See references/clean-architecture.md.
• Component boundaries: Are components cohesive (CCP, CRP) and acyclic (ADP)? Do dependencies flow toward stability (SDP)? See references/component-principles.md.

Document which principles favor which option. Conflict between principles is expected — that's why it's a decision, not a formula.

See references/principles.md for deeper guidance on applying KISS, YAGNI, coupling, and separation of concerns to architecture decisions.

Step 5: Make a Recommendation

State the recommended option clearly, with reasoning. Structure it as:

1. Recommendation: Option X
2. Primary reason: The most compelling argument (one sentence)
3. Key trade-off accepted: What you're giving up and why it's acceptable
4. Conditions that would change this decision: Future triggers to revisit

Step 6: Document the ADR

Produce an ADR using the template at templates/adr.md. Save it in the project's decision log (e.g., docs/decisions/NNN-decision-title.md).

ADRs are immutable records. If a decision is superseded, create a new ADR that references the old one — don't edit the original.

For visual architecture documentation (system diagrams, runtime flows, infrastructure topology), see the architecture-documentation skill.

When the decision is whether a capability should be built at all versus bought or adopted (vendor/SaaS/OSS, TCO, lock-in, exit costs), use build-vs-buy — it produces the same ADR-style record, but for sourcing rather than structure.

When to Split Decisions

If the analysis reveals multiple independent decisions bundled together, split them into separate ADRs. For example, "How should we handle caching?" might split into:

• ADR-001: Cache invalidation strategy
• ADR-002: Cache storage technology
• ADR-003: Cache warming approach