Architecture & simplicity
Structure is what a change has to cross: the fewest boundaries the product needs
now, each with the change it protects named. A smaller feature set is not a
simpler design of the same requirement. Money amounts, currency handling, spend
order and refunds belong to money-path-safety; this skill decides where that
logic lives.
Modules and boundaries
- Split by reason to change. Different axes of change belong in different
modules: a PDF export must not touch billing, an auth change must not touch a
report generator. A file that keeps changing for unrelated reasons marks a
missing boundary, not a file that needs shortening.
- One business core, thin adapters. Business logic lives once; each client
channel (CLI, HTTP, desktop, chat) is a shell of I/O, auth and presentation, so
a polish bug is fixed in one place for every client.
- A boundary needs a job now. Every layer, package or service is crossed by
callers and paid for in ops and debugging. Add it when it isolates a change
boundary the product already has — a second client, a deployable that must
scale or fail independently, an external protocol — not for a hypothetical
consumer. Inside a single change, ponytail owns the minimal-code call.
- Pure core, impure edges. Assembly, formatting and export are pure
functions; I/O, time, randomness and network sit where a test can substitute
them.
- Make invalid states unrepresentable. Separate fields over boolean soup:
status: active | finished instead of is_active + is_finished +
is_deleted combinations nobody can reason about.
- Comments carry the ceiling. Say why the code exists and what limit it
tolerates, not what the next line does.
Configuration and evolution
- Config outside the repo, defaults in code. Secrets and per-environment
tuning never enter git; the code carries safe defaults and the environment
overrides them.
- Flags serve rollout, not avoidance. A flag is for operational variation the
product needs, never to dodge a required cutover or keep a hypothetical
compatibility path alive.
- Schema evolution is non-destructive by contract. A deploy never drops or
rewrites a table that holds production data, and never requires a
code-and-schema flip in the same instant. Staged expand-contract: add the new
column or table, backfill in bounded batches while both shapes work, add the
constraint or index once the data satisfies it (
NOT NULL, foreign keys and
unique indexes only after the backfill), switch reads and writes, then remove
the old shape in a later deploy after verifying nothing reads it. Index
creation on a large table needs its own rollout plan (concurrent/online build
where the engine requires it) because it can lock or rewrite. State the
rollback before running the migration: which deploy order leaves the old code
working against the new schema, and which backup covers an irreversible step.
Destructive maintenance on live data is an authority question (OPS §1), not a
migration detail.
- Deterministic rebuild beats stale cache. Rebuilding from source is cheaper
than debugging data whose provenance is unknown.
Failure and provider policy
A fallback exists only where the availability contract requires it and a
compatible alternative already exists and is authorized. Otherwise fail clearly
with the real error: a second vendor or a silent degraded mode is a product
decision, not a default feature.
1---2name: architecture-simplicity3description: 'Use when designing or reviewing structure: module and layer boundaries, splitting a god file, shared core with thin adapters, where config and defaults live, service boundaries, non-destructive DB schema evolution (expand-contract, backfill, constraints, indexes, rollback), or whether an extra layer is justified. Not for minimalism in one change (ponytail), money logic (money-path-safety), or library choice (production-first-decisions).'4license: MIT5compatibility: any language and stack, architecture design/review phase6metadata:7 source: https://skillmd.com/skills/oleg494/architecture-simplicity8 version: "6.1.0"9---1011# Architecture & simplicity1213Structure is what a change has to cross: the fewest boundaries the product needs14now, each with the change it protects named. A smaller feature set is not a15simpler design of the same requirement. Money amounts, currency handling, spend16order and refunds belong to money-path-safety; this skill decides where that17logic lives.1819## Modules and boundaries2021- **Split by reason to change.** Different axes of change belong in different22 modules: a PDF export must not touch billing, an auth change must not touch a23 report generator. A file that keeps changing for unrelated reasons marks a24 missing boundary, not a file that needs shortening.25- **One business core, thin adapters.** Business logic lives once; each client26 channel (CLI, HTTP, desktop, chat) is a shell of I/O, auth and presentation, so27 a polish bug is fixed in one place for every client.28- **A boundary needs a job now.** Every layer, package or service is crossed by29 callers and paid for in ops and debugging. Add it when it isolates a change30 boundary the product already has — a second client, a deployable that must31 scale or fail independently, an external protocol — not for a hypothetical32 consumer. Inside a single change, ponytail owns the minimal-code call.33- **Pure core, impure edges.** Assembly, formatting and export are pure34 functions; I/O, time, randomness and network sit where a test can substitute35 them.36- **Make invalid states unrepresentable.** Separate fields over boolean soup:37 `status: active | finished` instead of `is_active` + `is_finished` +38 `is_deleted` combinations nobody can reason about.39- **Comments carry the ceiling.** Say why the code exists and what limit it40 tolerates, not what the next line does.4142## Configuration and evolution4344- **Config outside the repo, defaults in code.** Secrets and per-environment45 tuning never enter git; the code carries safe defaults and the environment46 overrides them.47- **Flags serve rollout, not avoidance.** A flag is for operational variation the48 product needs, never to dodge a required cutover or keep a hypothetical49 compatibility path alive.50- **Schema evolution is non-destructive by contract.** A deploy never drops or51 rewrites a table that holds production data, and never requires a52 code-and-schema flip in the same instant. Staged expand-contract: add the new53 column or table, backfill in bounded batches while both shapes work, add the54 constraint or index once the data satisfies it (`NOT NULL`, foreign keys and55 unique indexes only after the backfill), switch reads and writes, then remove56 the old shape in a later deploy after verifying nothing reads it. Index57 creation on a large table needs its own rollout plan (concurrent/online build58 where the engine requires it) because it can lock or rewrite. State the59 rollback before running the migration: which deploy order leaves the old code60 working against the new schema, and which backup covers an irreversible step.61 Destructive maintenance on live data is an authority question (OPS §1), not a62 migration detail.63- **Deterministic rebuild beats stale cache.** Rebuilding from source is cheaper64 than debugging data whose provenance is unknown.6566## Failure and provider policy6768A fallback exists only where the availability contract requires it and a69compatible alternative already exists and is authorized. Otherwise fail clearly70with the real error: a second vendor or a silent degraded mode is a product71decision, not a default feature.