/architecture

name: architecture
description: "Compare interface designs and find structural friction. Use when: a change spreads across modules or a boundary is unclear. For code changes, use Refactor."
practices: [hexagonal-architecture, ddd-bounded-context, legacy-code-seams, refactoring, pragmatic-programmer, design-patterns]
hexagonal_role: domain
consumes: [repo-context]
produces: [architecture-proposal]
context_rel:
- kind: supplier-to
  with: refactor
- kind: supplier-to
  with: plan
- kind: partnership
  with: domain
skill_api_version: 1
user-invocable: true
metadata:
  graph_root: true
  tier: judgment
  dependencies: []
  capabilities: [locate_change_friction, compare_interface_designs, propose_module_boundaries]
  effects: []
  canonical_status: canonical
  disposition: keep_specialist
output_contract: 'located friction and ranked structural proposals, each with call-site sketch, migration path and reversibility, or an honest no-proposal result; no code edits'

Architecture

Architecture finds where a codebase's structure makes change expensive and proposes a better shape: a deeper module, a seam where behavior has to vary, or a boundary moved to where the domain language changes. It analyses and proposes; it edits nothing. Neighbours: [Refactor](../refactor/SKILL.md) executes one behavior-preserving transformation, [Implement](../implement/SKILL.md) changes behavior, [Plan](../plan/SKILL.md) slices a chosen change, [Domain](../domain/SKILL.md) settles what terms mean per context, and [Review](../review/SKILL.md) advises on an existing plan or diff.

Lineage: Parnas on information hiding, Ousterhout on deep modules and designing twice, Evans on bounded contexts, Cockburn on ports and adapters, Feathers on seams.

Vocabulary

Use these meanings in every proposal so the caller can compare them.

• **Module**: anything with an interface and an implementation: a function,

type, package or service.

• **Interface**: everything a caller must know to use the module correctly:

the signature, plus call order, invariants, error cases, required configuration and cost.

• **Implementation**: the code behind the interface.
• **Depth**: how much the interface hides relative to what callers must know.

A deep module hides a lot behind a little; a shallow one asks callers to know nearly as much as it does.

• **Seam**: a place where behavior can vary without editing the code there,

such as a parameter, an injected dependency or a module edge.

• **Adapter**: code that fits a technology or external system to a seam the

domain defines.

• **Locality**: what changes together lives together, so one decision has one

place to change.

• **Information leakage**: one design decision known in several modules, so

changing it means editing each of them.

Procedure

1. **Start from named pain.** Use the pain the caller names: a change that was hard, a defect class that returns, a test that breaks for unrelated reasons. With none named, gather candidates from evidence before reading code broadly: files that change together in history, churn hotspots, fix clusters, slow or brittle tests (see the [history queries](references/module-depth.md#gathering-evidence-from-history)). State which evidence you used and its window. Without history (pasted code, shallow clone), say co-change and churn are unknown. With no pain and no evidence, ask for one change that hurt instead of surveying the whole codebase. 2. **Read recorded decisions** for the area: ADRs, architecture docs, contracts. Leave a settled decision alone unless the located friction justifies reopening it, and then say which decision and why. 3. **Locate the friction.** Trace the files and call sites a typical change in the pain area touches, and cite file:line. Shallow-module signals: a pass-through layer; an interface about as complex as its implementation; callers that must call in a set order; one decision repeated across modules; options added one caller at a time; tests that mock internals; a helper split out to be tested while the caller wiring it stays untested. Ask what callers would have to know if a suspect module disappeared: nothing new means it was a pass-through; the same rule reproduced in several callers means it earns its place. A signal becomes a finding only when located and tied to the pain; rarely changed code with an awkward shape usually costs less left alone. How to confirm each signal, and its look-alikes, is in the [module depth reference](references/module-depth.md). 4. **Check boundaries and direction.** Where a word changes meaning, or two words name one thing, a context boundary is likely; confirm the terms with Domain. Domain rules should not import adapters such as storage, HTTP, CLI parsing or file formats; adapters depend on ports the domain defines. 5. **Design it twice.** For each friction worth a proposal, sketch at least two interface alternatives plus "leave it". Judge them by the call sites they produce and the change they make cheaper, not by internal elegance. When the caller brings a candidate shape, it is one of the alternatives. Vary one [design axis](references/module-depth.md#designing-alternatives) at a time. 6. **Name how tests move.** A deep module is tested through its interface. Say which tests that mock internals or pin call order would be replaced by tests at the new interface, and which stay; what sits behind the seam decides the [test placement](references/module-depth.md#seams-and-how-tests-cross-them). 7. **Rank, return and stop.** Report the strongest proposals first in the shape below, with a [migration](references/module-depth.md#migration-that-stays-working) that keeps every step working. The caller chooses one; a single behavior-preserving transformation goes to Refactor, anything larger or behavior-changing to Plan.

Shared code

Repeated text is not always repeated