elct9620/architecture

Related Skills

This skill owns structural planning — how the system is organised. Two neighbouring concerns are different kinds of problem and stay separate:

• Defining what the domain concepts are (Entity, Value Object, Aggregate, Domain Event)? → domain-modeling. Structure follows the model: context and module boundaries align with aggregate boundaries, so let domain-modeling settle those first.
• Solving a recurring local problem with a named pattern (Strategy, Adapter, Observer…)? → design-patterns.
• Moving code between structures safely? → refactoring for the mechanical steps.
• A trust boundary in the structure? → security + schema.

A design-forces memo, when one exists, is the input to this skill: it carries the force signals that decide whether and what to structure. Principles (KISS, SOLID, DRY, YAGNI, fail-fast) are how every structure is implemented, never something a structure replaces.

The default is no extra structure

Start from the position that the feature needs no architectural ceremony beyond what the framework already gives you. A framework is itself an architecture; following its grain plainly is a legitimate, often correct, answer. Structure earns its place only when forces make the absence of it more expensive than the cost of adding it.

Resist mapping a framework to a named style by reflex ("Rails, so DCI"; "Spring, so layers"). That is mechanical correspondence wearing a different hat — it bypasses the judgement that makes structure fit. The framework's nature is one input to the force judgement, not a lookup that pre-decides the answer.

When this skill applies — two modes

Mode A — follow the recorded structure (cheap path)

docs/architecture.md is a deliberately cheap, maintainable signal. When it exists and covers the area being touched:

1. Read its style declaration and Patterns section.
2. Apply the recorded structure as-is.
3. Re-open the decision only if a recorded revisit trigger has fired.

No fresh analysis — this is what makes a structural decision persist across features instead of being re-litigated every time.

Mode B — decide the structure (fresh)

When there is no record covering this area, or a revisit trigger has fired, the question is not "is docs/architecture.md missing?" — it is "is this now complex enough to need structural planning?"

Read the force signals — from the design-forces memo if present, otherwise a light read of the same lenses. Rule complexity, change rate, blast radius, and team fragmentation push toward structure; delivery pressure and code maturity pull back.

• Forces are quiet → stay with the default: framework as-is, no extra structure.

• Forces are loud → they surface as a concrete symptom. Recognise it, then read the technique that answers it (the reference explains how):

  • Changes keep rippling outward — touch one thing and you keep breaking code others depend on → references/clean-architecture.md
  • The same word means different things in different places — subdomains crammed into one model, teams tripping over each other's invariants → references/ddd.md
  • A use case's behaviour is scattered — one scenario's logic spans several objects with no place that tells its story → references/dci.md

These are starting points, not a menu; they compose, and a symptom matching none means reasoning from forces and principles directly.

After committing, record the decision so Mode A applies next time (see Recording below).

Module Type

Pick once per package; it decides whether the source is the documentation or whether signatures must carry intent. Feeds the principles Commenting rules.

| Module type | Audience | Public symbols | |-------------|----------|----------------| | Application | Operators, end users | Source is the documentation | | Library / shared module | Other developers via IDE | Signatures carry doc comments stating intent | | Monorepo with both | Both | Decide per package, not per file |

Recording the decision

A fresh Mode B decision should leave a trace, so the next feature reads it instead of re-deciding. Match the weight of the record to the weight of the decision:

• Default — Patterns section in docs/architecture.md (~6–10 lines): name in this project's vocabulary / when to apply / shape / canonical example / forces it resolves / revisit-if.
• Style declaration in docs/architecture.md when the choice sets a project-wide default (e.g. "layered with an inward dependency rule").
• ADR in docs/decisions/ only when the decision is large-blast-radius, multi-team, or hard to reverse.

If docs/architecture.md does not exist and a structure was chosen, create it with the style declaration, a directory→structure mapping, and the dependency guidelines for the chosen technique.

Completion Rubric

| Criterion | Pass | |-----------|------| | Record respected | An existing structure in docs/architecture.md is followed without re-analysis; a fresh decision leaves a record sized to it (Patterns entry, style declaration, or ADR) | | Structure earned | Default is no extra structure; it is added only on a loud force named as a symptom — never from a missing doc or a framework→style reflex | | Boundaries follow the model | Context/module partitioning aligns with aggregate boundaries from domain-modeling | | Dependency direction sound | If a layered/CA technique was chosen, dependencies point inward; no circular references | | Principles as baseline | KISS / SOLID / DRY / YAGNI treated as how the structure is built, never as something it defers |