Architecting Changes

Architecting Changes

This skill is the first stop for non-trivial architecture decisions.

It is both a compact guide and a router to deeper project docs and domain skills. Use it to decide shape and boundaries, then continue through the normal planning or implementation flow.

For coding-related work, engineering-principles should already be loaded as the foundation for explicitness, validation, boundaries, testing, and tooling.

engineering-principles
  -> brainstorming / planning-implementation / unclear implementation task
     -> architecting-changes  (you are here, when boundaries or ownership matter)
          -> api-design / security-and-hardening / performance-optimization
          -> documentation-and-adrs       (if decision should be durable)
          -> planning-implementation      (if work needs decomposition)
          -> incremental-implementation   (if direction is clear enough to execute)

Core Idea

Architecture is about expected change.

Split things when they change for different reasons. Keep things together when a split only adds ceremony.

Good architecture answers:

  What owns this responsibility?
  What is allowed to know about what?
  What will change independently later?
  What boundary prevents invalid states or dependency leaks?

Default Flow

Incoming non-trivial change
        │
        ▼
Classify the change
        │
        ▼
Find the expected change axis
        │
        ▼
Identify the real architecture question
        │
        ▼
Choose the smallest sufficient boundary
        │
        ▼
Route to deeper skills only when needed

1. Classify the change.
2. Ask what is actually expected to change later.
3. Identify the real architecture question.
4. Apply the heuristics below.
5. Load the matching deeper skill when available.
6. Continue to planning or implementation.

Change Classification

Expected Change Axes

Ask which part is likely to evolve independently:

Business rules
    │
    ├── Validation / decoding
    ├── Transport / request-response shape
    ├── UI / CLI / API presentation
    ├── Infrastructure / persistence / third-party calls
    ├── Platform integration / OS behavior
    └── Observability / dry-run / operational controls

If two concerns change for different reasons, they probably deserve a boundary. If they always change together, splitting them may be ceremony.

Core Heuristics

Boundaries And Layers

• Keep a small fix local unless the bug was caused by the wrong boundary.
• Extract shared behavior downward into domain, application, or utility code instead of duplicating it across entry points.
• Keep business rules separate from validation plumbing, transport shapes, auth/session concerns, and raw infrastructure.
• Wrap third-party, OS-specific, network, file system, or weakly typed boundaries when typing, exception isolation, portability, or replacement matters.

Presentation / transport
        │
        ▼
Application use case / service
        │
        ▼
Domain rules / pure decisions
        │
        ▼
Infrastructure wrappers

Dependencies should point inward or downward. Domain code should not import UI, HTTP handlers, framework lifecycle, or persistence implementation details.

Presentation Boundaries

Presentation layers are adapters, but the adapter boundary depends on the repository and deployment shape.

Single application codebase:

CLI command ───┐
GUI screen ────┼──> Application / Domain Core ──> Infrastructure wrappers
API handler ───┘

Separate frontend/backend applications:

Frontend app ──> API contract / generated client ──> Backend API ──> Backend domain
      │                                                    │
      └── frontend state, UX validation                    └── server invariants

Do not move logic across a frontend/backend boundary just to satisfy "shared core" as a pattern. Share contracts first. Share implementation only when the repo and deployment model make that coupling intentional.

Reuse Versus Custom Code

• Prefer boring popular maintained libraries and frameworks for commodity infrastructure: auth, routing, migrations, packaging, builds, queues, caching, deployment, and orchestration.
• Do not build ad hoc systems on top of a tiny framework when the domain already implies substantial backend or operational concerns.
• For tiny one-off helpers or stable details, simple custom code is often better than heavyweight scaffolding.
• When selecting a library, verify current docs and compare options; do not choose from memory alone.

Composition And State

• Prefer composition, explicit data flow, and small interface-shaped boundaries over deep class hierarchies.
• Add stateful classes or services for lifecycle and orchestration, not to manufacture abstractions.
• Hidden mutable state is a smell. Important state changes should be visible in code, logs, or explicit state models.

Reusable Cores

• If CLI, GUI, API, worker, or automation code may share logic in the same application boundary, build a reusable core plus thin adapters.
• Start with one useful implementation, but do not trap durable business logic inside the first interface.
• Prefer composable pieces over one giant super-tool.

Transparency And Operations

• Important workflows should be inspectable: clear validation, explicit errors, logs at operation boundaries, and dry-run behavior where practical.
• For risky multi-step actions, prefer explicit step/state models over opaque helper chains.
• If a failure would be costly or hard to debug, design for traceability early instead of bolting it on later.

Pattern Awareness

Architecture is not only about boundaries. It is also about choosing the right pattern for the problem at the right scope. A wrong or missing pattern in a sensitive area produces a web of ifs and small tangled functions that becomes impossible to evolve, test, or trust. A pattern applied in a trivial area is just ceremony.

For every non-trivial change, ask: which established pattern fits this job, at which scope, and what happens if I skip it?

Three Scopes Of Patterns

File-level / within one module
  -> state machines, parsers/combinators, builders, strategies,
     result types, value objects, specification/predicate, mappers
System-level / across files inside one application
  -> outbox, inbox, mediator/dispatcher, saga, CQRS, repository,
     unit of work, dependency injection, observer/publisher,
     idempotency keys, retries with backoff, circuit breakers,
     feature flags, ACL (anti-corruption layer)
Architecture-level / system shape
  -> hexagonal/ports-and-adapters, modular monolith, microservices,
     event-driven, message bus, event sourcing, read replicas,
     separate OLTP vs OLAP stores, queue per workload, cache layers,
     gateway / BFF, strangler fig

These scopes compose: an architecture choice (e.g. modular monolith) sets the system, a system pattern (e.g. outbox) lives inside it, and file-level patterns (e.g. a state machine for order status) make the pieces legible.

When Patterns Are Required, Not Optional

Some areas are pattern-sensitive by nature. If the wrong or no pattern is chosen, the code will rot quickly and the cost of fixing it later is high. Treat the following as a non-exhaustive list of areas where pattern thinking is part of the architecture step, not a polish step:

Money, billing, payments, accounting
  -> state machines, double-entry invariants, idempotency, outbox,
     transactional boundaries, money value objects (no floats),
     append-only audit log, reconciliation

High-throughput data pipelines, ingest, ETL, protocol converters
  -> backpressure, bounded queues, batching, idempotent consumers,
     dead-letter queues, schema evolution, partitioning/sharding,
     streaming vs batch choice, error classification

Authentication, authorization, session, secrets
  -> strategy/handler for providers, repository for sessions,
     mediator for events, audit log, ACL at trust boundaries,
     token rotation, fail-closed defaults

Long-running workflows, multi-step business processes
  -> saga / process manager, explicit state model, compensation
     steps, timeouts, idempotency keys, durable state

Multi-tenant or regulated data
  -> repository + unit of work, row-level access policy, audit log,
     soft delete with retention, separation of PII stores

External integrations and third-party APIs
  -> anti-corruption layer, adapter, retry with backoff, circuit
     breaker, idempotency keys, schema/version negotiation,
     dead-letter handling, sandbox/mock mode

Caching, search, read-heavy domains
  -> CQRS, read models, cache-aside vs write-through, eventual
     consistency windows, cache invalidation strategy

Configuration, feature flags, operational control
  -> feature flag service, config repository, dry-run / shadow mode,
     observability hooks, kill switch

If the change touches one of these areas, the architecture step is incomplete until the matching patterns are named and their boundaries drawn — even if their bodies are not yet implemented.

Right-Sized Engineering

Pattern awareness does not mean "apply every pattern everywhere". It means: invest pattern effort where the cost of under-engineering is high, and stay boring where the cost of over-engineering is higher.

Invest in patterns when:
  - the area is pattern-sensitive (see list above)
  - business rules are non-trivial or expected to grow
  - failures are costly, hard to detect, or hard to undo
  - multiple actors, tenants, or processes share state
  - the code is on a known scale or complexity axis

Stay boring when:
  - it is a one-off helper, glue, or boilerplate
  - the rules are stable and the change axis is purely cosmetic
  - the cost of rewriting from scratch is lower than the cost of the
    pattern
  - the lifetime of the code is short and well bounded

A useful self-check: if this area is going to grow, what shape will make the next change easy? That shape is usually a pattern. If the area is not going to grow, the pattern is overhead.

Common Failure Mode: If-Webs And Helper Spaghetti

The signature of under-engineered sensitive code is recognizable:

- long functions with many flags and early returns
- "manager" objects that take a context blob and branch on type
- state stored in scattered booleans or magic strings
- retries and rollbacks hidden inside ad-hoc helpers
- implicit ordering between operations that must be transactional
- "just one more if" added every time a case is reported
- no place to attach tests, observability, or rollback

When this shape starts to appear, stop and reach for the right pattern instead of another conditional. The goal is not to add layers for their own sake; the goal is to make the next change a normal local edit rather than a global surgery.

Pattern Selection Questions

Use these as a quick gate before leaving the architecture step:

1. Which scope does this change live at? (file / system / architecture)
2. Is the area pattern-sensitive? (billing, throughput, auth, workflow, ...)
3. What is the dominant force?
     - state transitions           -> state machine
     - async work / fan-out        -> queue, outbox, saga
     - external boundary           -> adapter / ACL
     - multiple representations   -> CQRS, read model
     - many independent rules      -> strategy / specification
     - cross-cutting concern       -> mediator / observer
4. What existing pattern in the codebase already solves something
   similar? Reuse or evolve it before introducing a new one.
5. What is the smallest pattern that makes the next change local?

A pattern does not have to be implemented fully on day one. Naming it in the architecture step is enough to make the boundary visible and to keep the next change from sliding back into the if-web.

Router

Use this table to decide whether to stay in this skill or load a deeper one.

If a language-specific route is missing, make the architecture decision with this skill and engineering-principles, then note any needed follow-up in the handoff.

Decision Checklist

Before leaving this skill, be able to answer:

Responsibility:
  What owns the new behavior?

Boundary:
  What must not leak across this boundary?

Change axis:
  What is expected to change independently later?

Reuse:
  Is shared logic actually shared, or only hypothetically reusable?

Framework:
  Is this commodity infrastructure that a boring framework should own?

Pattern:
  Is the area pattern-sensitive? If yes, which pattern fits at which scope, and is the boundary visible even if the pattern is not fully implemented yet?

Handoff:
  Which deeper skill, plan, or implementation step comes next?

Common Mistakes

Handoff

After the architecture direction is clear:

Tiny obvious change       -> implement directly
Small known-code change   -> quick inline plan, then implement
Moderate multi-file work  -> planning-implementation
Risky assumption          -> prototype-first or doubt-early
ADR-worthy decision       -> documentation-and-adrs

If language-specific routing is needed but no canonical skill exists, record the gap explicitly rather than pretending the local skill exists.