anastasiyaw/codex-claude-code-config/architecture-first

Architecture first — the shape before the first file

Most bad structure is not a bad decision. It is an absent one: code goes where the smallest diff puts it, and the smallest diff is always "next to the last thing". This skill exists to make the layout an explicit, cheap, early decision.

Scope guard — read first

Match the ceremony to the problem. Over-applying this is its own failure mode.

The one law

Dependencies point inward, toward policy. Business rules must not import the web framework, the ORM, the queue, or the file layout. The reverse is required.

Violating it silently is the failure — a violation that is written down, with the reason and the cost, is a decision. A violation nobody named is erosion.

Practical test: could this module be exercised by a test with no network, no database and no framework? If not, something outer leaked inward.

Pre-code checklist — before the first file

1. Name the modules by reason to change, not by technical layer. queue, billing,

catalog — not controllers, models, utils. A module that changes for two unrelated reasons is two modules.

1. Say what each module owns. Especially state: every piece of mutable state has

exactly one owning module, and everyone else asks that module. Module-level mutable state shared across features is the coupling that later makes a split expensive.

1. Draw the dependency arrows. Any cycle is a design bug, not a build inconvenience.

Any arrow from domain to framework is inverted — fix it with an interface owned by the inner side.

1. Establish the ubiquitous language. One term, one meaning, in code and in speech.

If the same word means different things in two places, you have found a bounded context boundary — draw it there.

1. Define the aggregates. What must be consistent in one step, and what may lag.

Transaction boundaries follow this, not the other way round.

1. Write one vertical slice end-to-end — UI to store to test — before broadening.

A slice that works proves the seams; six half-built layers prove nothing.

1. Record it. One page: modules, ownership, data flow, external systems. Plus one

short ADR per decision that was genuinely a choice (context, options, decision, consequences). Both live in git, next to the code.

1. Name the promotion boundaries. When one verified result becomes the input to

another stage, name its contract, inputs, output, and invalidation keys before implementation. A missing signer, VM, account, or remote service is a future BLOCKED stage, not a reason to keep reopening already-proven code.

Stage contracts - when proof becomes an input

For multi-stage work, architecture includes delivery boundaries as well as module boundaries. Keep these states separate:

• VERIFIED: the scoped behavior passed at one exact revision.
• SEALED: the verified scope has an immutable receipt and may be consumed by a

following stage.

• BLOCKED: a named external prerequisite is absent; upstream proof remains valid.
• SUPERSEDED: a contract, source, or input digest changed, so a successor must be

verified instead of editing history.

The stage map is deliberately smaller than a release plan. For each boundary, name the owning scope, frozen contract, inputs, output, and what invalidates it. Use the machine-readable ledger only when there is a real hand-off between stages: ../proof-verify/references/proven-stage-contracts.md. Do not add it to a one-file change merely because the word "stage" exists.

Review checklist — once code exists

• Does any inner module import an outer one? Name it or fix it.
• Is there module-level mutable state touched by more than one feature?
• Does one file hold routes/handlers for more than one reason to change?
• Are there two names for the same concept, or one name for two?
• Can each module's tests run without the framework?
• Does the ARCHITECTURE.md still describe what is actually there?

Fast decision table

References — load on demand

• references/clean-architecture/boundaries-and-layers.md — boundaries, Humble Object
• references/clean-architecture/solid-and-components.md — SOLID applied correctly, REP/CCP/CRP, ADP/SDP/SAP
• references/clean-architecture/details-and-code-organization.md — DB/web/frameworks as details
• references/clean-architecture/python-implementation.md — entities, use cases, repositories, wiring
• references/domain-driven-design/bounded-contexts.md — context mapping
• references/domain-driven-design/ubiquitous-language.md — one term, one meaning
• references/domain-driven-design/building-blocks.md — entities, value objects, aggregates
• references/domain-driven-design/domain-events.md, repositories-factories.md, strategic-design.md
• *-original.md — the source skills' own framework prose, kept verbatim

Gotchas

• "We'll structure it later." Later costs more per caller, and callers only grow. The

cheapest moment is before the first file; the second cheapest is now.

• Ceremony as architecture. Four layers around a CRUD endpoint is not architecture,

it is cost. The scope guard above exists to stop this.

• Folders instead of boundaries. Moving files without changing who imports whom

changes nothing. The arrows are the architecture; folders only display it.

• The domain importing the framework "just for a type". That is the whole violation,

arriving politely.

Troubleshooting