Architecture Design

Architecture Design

Use This Skill When

• Designing a new module, service, subsystem, feature slice, integration, or architectural boundary.
• Deciding where business logic, validation, persistence, IO, retries, timeouts, mapping, configuration, or error handling belongs.
• Reviewing whether an existing design has unclear responsibility, leaky interfaces, pass-through layers, shallow abstractions, hidden coupling, or framework/SDK leakage.
• Reviewing architecture in a diff, proposal document, ADR candidate, implementation plan, review comment, or migration/refactor note.
• Considering Clean Architecture, Hexagonal Architecture, DDD, repositories, CQRS, events, queues, microservices, plugins, shared libraries, or other structural patterns.
• Refactoring architecture in brownfield code where tests, behavior, compatibility, or runtime wiring may constrain the change.

Do Not Use This Skill When

• The user only needs an ADR written for an already-settled decision. Use the create-project-adr skill.
• The user needs a product PRD, engineering spec, or implementation plan. Use the relevant planning skill and load this skill only for architecture judgment inside that workflow.
• The task is stack-specific enough that a domain skill should own it, such as database schema design, API design, frontend design, security architecture, or framework-specific conventions.
• The change is a local typo, copy edit, or narrow bug fix with no design choice, boundary movement, or dependency implication.

Iron Law

Architecture is responsibility and trade-off discipline, not pattern decoration. Do not recommend a layer, service, adapter, repository, event, queue, abstraction, framework pattern, or rewrite until the forces, responsibility, interface, seam, and accepted trade-offs are explicit.

Operating Process

Run the steps in order. If an earlier step returns Blocked, Rejected, or Not ready, stop on that state instead of producing a recommendation from later-step assumptions.

1. Establish Forces

Identify the facts that should shape the architecture before suggesting structure.

Minimum forces:

• goal and user-visible behavior;
• existing codebase patterns, rules, ADRs, and project constraints;
• scale, data volume, latency, reliability, security, privacy, compliance, operability, and team constraints that materially apply;
• current implementation state for brownfield work;
• external systems, persistent state, trust boundaries, and compatibility surfaces.

Before accepting the user's proposed shape, run a source and framing gate:

• If the request starts with a named pattern, layer, service split, adapter, repository, event, queue, plugin model, rewrite, or abstraction, identify the concrete pain, affected callers, current workaround, and consequence of doing nothing.
• Classify material inputs as confirmed fact, source-backed constraint, inferred assumption, background context, stale or conflicting source, or missing force.
• Before claiming the project lacks an ADR, boundary, adapter, seam, responsibility convention, dependency direction, or local pattern, inspect the relevant source or label the claim as an assumption.
• When code, ADRs, docs, diagrams, generated findings, runtime behavior, review comments, or external state disagree, classify the conflict before choosing authority: stale documentation, implementation drift, unresolved architecture decision, compatibility exception, or source-of-truth ambiguity.
• Carry exact source identifiers when available, such as paths, ADR IDs, module names, API or schema names, diagram names, runtime config names, or review-comment anchors.

Completion criterion: the architecture recommendation can name the forces it is optimizing for and the forces it is deliberately not optimizing for.

Failure output: Blocked: architecture decision depends on missing force: <specific missing fact>.

2. Locate Responsibility

Assign each important policy, invariant, state transition, data transformation, and side effect to a component.

Rules:

• Business policy belongs in the module that owns the domain concept, not in controllers, routes, UI components, database callbacks, SDK wrappers, or glue code.
• Persistence, network, filesystem, clock, random, process, queue, cache, analytics, and third-party calls belong behind adapters or tools unless the containing module's purpose is that mechanism.
• Validation splits by purpose: reject malformed input at system boundaries, enforce business invariants in the owning domain/application module, and enforce uniqueness/integrity in persistence where applicable.
• One conceptual change should have one primary edit site. If a change spreads across unrelated files, responsibility is probably wrong or duplicated.

Completion criterion: every named policy, invariant, state transition, and side effect has a clear component, and the rationale explains why the knowledge belongs in each component.

Failure output: Blocked: responsibility is ambiguous for <policy/invariant/side effect>.

3. Design The Interface And Seam

Define the interface before choosing the implementation shape.

For each proposed module or boundary, state:

• what callers need to know;
• what callers should not need to know;
• inputs, outputs, invariants, ordering requirements, error modes, configuration, and performance expectations;
• what complexity is hidden behind the interface;
• where the seam sits and what can vary across it.

Before accepting a new or changed interface, write the smallest usage sketch for each materially different caller role. Use the sketches to test the call shape, required context, invalid combinations, sequencing, and error handling before committing to the contract. These are disposable design probes, not implementation units or final syntax.

Apply the deep-module checks in Interface Depth And Seams.

Completion criterion: representative caller sketches expose no unjustified placeholder, mechanism detail, duplicated choreography, or caller knowledge; the interface hides more complexity than it adds and can be tested through its public contract.

Failure output: Rejected: proposed interface is shallow or leaky: <specific reason>.

4. Separate Policy From Mechanism

Keep the owning policy module independent from transport, persistence, SDK, and framework mechanisms.

Rules:

• Policy modules may depend on explicit interfaces or ports when variation is real.
• Adapters/tools own SDK calls, HTTP calls, database calls, filesystem calls, retries, timeouts, auth material, request correlation, metrics/logging transport, error mapping, and external response normalization.
• Controllers, route handlers, command handlers, workers, and UI event handlers translate boundary input/output; they do not accumulate business policy.
• Raw database models, SDK response objects, framework request objects, and transport envelopes do not cross into domain/application policy unless they are the explicit public contract of that layer.

Use Boundaries And Adapters when the work involves IO, third-party calls, framework entry points, persistence, or cross-layer data movement.

Completion criterion: the design can draw a clear line between policy and mechanism, and each crossing has an explicit interface, DTO, value object, command, event, or documented contract.

Failure output: Rejected: policy/mechanism boundary is leaking through <specific object/call/dependency>.

5. Prove Patterns And Alternatives

Before adopting a named pattern or new abstraction, prove it earns the complexity.

For each significant pattern or abstraction, answer:

1. What specific problem does it solve here?
2. What simpler alternative was considered?
3. What complexity does it add?
4. What would let us defer it safely?
5. What accepted trade-off makes this choice worthwhile?

Use Decision Framing for option comparison, quality attributes, and ADR handoff.

For broad or solution-shaped prompts, discover at least two materially different architecture options before recommending one. Candidate options may differ by component, boundary placement, seam timing, migration direction, policy/mechanism split, or compatibility strategy. Reject weak options with reasons tied to missing forces, shallow interfaces, boundary leaks, brownfield gaps, compatibility risks, or weak verification paths.

Completion criterion: each architectural choice has a concrete problem, rejected alternatives, accepted costs, and a revisit trigger when appropriate.

Failure output: Rejected: pattern not justified: <pattern> does not solve a proven problem in this context.

6. Handle Brownfield Risk

If the change touches existing behavior, weakly tested code, public contracts, persistent data, runtime wiring, or external consumers, treat it as brownfield architecture work.

Rules:

• Understand current behavior before redesigning it.
• Characterize uncertain behavior before changing semantics.
• Create the smallest useful seam before a broad restructure.
• Keep behavior changes, refactoring, and cleanup separate unless the spec explicitly binds them.
• Preserve public compatibility or provide a transition path when changing externally reachable interfaces.

If the request comes from a bug, regression, repeated workaround, review finding, incident, or unexplained behavior, treat it as failure-driven architecture. Require causal evidence that the symptom is architectural before moving responsibility or boundaries: wrong responsibility, leaky interface, duplicated policy, cross-subsystem interaction, unsafe side effect ordering, or a local fix that would only hide the design problem.

Use Brownfield Architecture before recommending migration, extraction, broad refactor, or replacement.

Completion criterion: the design identifies behavior to preserve, compatibility surfaces, test/characterization strategy, and a safe transition path.

Failure output: Blocked: brownfield behavior or compatibility surface is not characterized: <specific gap>.

7. Verify The Architecture Recommendation

Before presenting a recommendation as ready, run Architecture Review Checklist.

Minimum output:

• problem and forces;
• recommended responsibility and boundaries;
• interface/seam summary;
• policy/mechanism split;
• alternatives rejected and why;
• accepted trade-offs and risks;
• verification strategy;
• ADR candidates, if any.

When reviewing an existing artifact instead of designing from scratch, use bounded architecture review mode:

• Classify the artifact shape first: requirements-level architecture direction, ADR candidate, implementation plan, diff, migration/refactor proposal, interface sketch, or review comment.
• Match scrutiny to the artifact. Do not demand implementation sequencing from requirements-level architecture notes; do require implementability, transition, compatibility, and verification from plan-shaped artifacts.
• Report findings only when they name the affected component, boundary, interface, seam, pattern, or trade-off; cite the source evidence; explain the downstream consequence; and route the correction to the responsible skill or component.
• Treat weak or speculative concerns as residual risk, not confident findings.
• Do not own independent review verdicts, severity policy, reviewer dispatch, PR-comment resolution, or auto-application.

Completion criterion: the output gives a future implementer enough structure to preserve the design without duplicating the reasoning process.

Failure output: Not ready: architecture recommendation is missing <problem/forces/boundaries/interfaces/trade-offs/verification/ADR candidates>.

Handoff Boundaries

This skill may identify ADR candidates but does not write ADRs freehand. A decision qualifies for ADR handoff only when it meets the create-project-adr bar: reversal would be costly or risky, future contributors will need the context, and real alternatives were weighed. Use the create-project-adr skill to record confirmed ADRs.

When architecture work will feed a spec, implementation plan, review, commit, or PR, hand off architecture facts without absorbing downstream mechanics.

Architecture handoff should preserve:

• source evidence and unresolved authority conflicts;
• forces optimized for and deliberately not optimized for;
• responsibility decisions and affected boundaries;
• interfaces, seams, caller obligations, and hidden complexity;
• policy/mechanism split and adapter responsibilities;
• alternatives rejected and accepted trade-offs;
• brownfield behavior to preserve, compatibility surfaces, and transition notes;
• verification strategy and residual risks;
• ADR candidates and decisions that require another skill.

Do not add implementation units, file-list choreography, branch creation, commits, pushes, PR mutation, CI watching, tracker filing, review verdicts, or external publishing steps.

Rationalization Table

Red Flags

• The recommendation starts with a named pattern before stating forces and responsibility.
• A new layer mostly forwards calls.
• A proposed interface has one implementation and no test, variation, or responsibility reason.
• Controllers, routes, UI components, SDK wrappers, or database callbacks contain business decisions.
• Raw ORM/database/SDK/framework objects cross into policy modules.
• A brownfield design changes behavior and structure in the same unsafely broad move.
• A public interface changes without compatibility, migration, or consumer analysis.
• The design optimizes for file organization aesthetics rather than lower cognitive load, locality, and testability.
• The recommendation trusts a stale or conflicting source without classifying authority.
• Architecture review findings lack affected boundary, source evidence, or downstream consequence.
• A failure-driven architecture change moves responsibility before causal evidence shows a design signal.
• The output smuggles implementation units, commits, PRs, review verdicts, or delivery steps into architecture guidance.