architecture-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# Architecture Design

## Contents

- **Read scope** - how to consume this skill when a read is truncated.
- **Objective** - minimise system complexity and increase locality of change;
  cross-language scope.
- **Priority order** - the 10-point precedence order; a lower number wins.
- **Prohibited designs** - designs to avoid.
- **Explore before proposing** - what to inspect, and when to load the grilling
  interview.
- **Boundaries** - domain/application/infrastructure/adapter roles and the seven
  boundary conditions.
- **Dependency direction** - where dependencies point.
- **SOLID** - diagnostics, not goals.
- **Semantic DRY** - when to share versus duplicate.
- **Method arguments and data shapes** - request/options structures, including
  Cancellation, Lightweight representations, and API ergonomics.
- **Output** - the nine-part design output order.
- **Skill boundaries** - when to load review, code-review, domain-modeling, or
  tdd.

## Read scope

Read this entire skill, including every section listed in Contents, before
applying it. If a read is truncated, continue from the next unread line until
the end.

## Objective

Design architecture that minimises total system complexity and increases
locality of change. Preserve the repository's existing architectural philosophy.
Do not design a feature in isolation and do not apply a pattern because the
pattern exists.

Design across C#, ASP.NET, C++, Rust, Go, and TypeScript, respecting each
repository's conventions.

## Priority order

Apply in this order; a lower number wins a conflict:

1. Requirements and correctness.
2. Repository conventions and existing architecture.
3. Domain and application boundaries that provide value (see "Boundaries").
4. Cohesive, deep modules with small interfaces.
5. Locality of change.
6. Dependency direction (see "Dependency direction").
7. Explicit designs.
8. SOLID as diagnostic guidance.
9. Clean Architecture, Hexagonal, or Ports and Adapters as guides when a
   boundary benefits from them.
10. DRY as guidance when two concepts are genuinely the same.

## Prohibited designs

Do not produce any of:

- Interface-per-class or repository-per-entity.
- Service or manager classes that only delegate.
- Mandatory `Controller`, `Service`, `Repository` layering.
- Ceremonial Clean Architecture layers.
- Speculative extension points or abstract factories with no variability.
- Abstractions created only to satisfy SOLID.
- DRY abstractions that couple concepts with different reasons to change.
- DTOs whose only purpose is renaming another object.
- Inheritance used primarily for code reuse.
- Splitting cohesive code into multiple tiny modules.
- A domain layer with no independent behaviour and no boundary.

## Explore before proposing

1. Read applicable `AGENTS.md` instructions and architectural documentation.
2. Inspect the feature, its callers, and neighbouring modules.
3. Identify the current dependency direction.
4. Identify existing domain, application, infrastructure, and adapter
   boundaries.
5. Find existing abstractions that already solve part of the problem.
6. Identify the authoritative owner of each state and behaviour.
7. Read existing tests and established seams.
8. Extend an existing architectural boundary instead of adding a competing one.

Investigate these facts yourself. If a user-owned requirement or constraint is
still unresolved, load `../grill-with-docs/SKILL.md` and run its interview
before implementation.

## Boundaries

These four are conceptual roles, not mandatory directories:

- **Domain**: business concepts, rules, invariants, and behaviour. Must not
  depend on infrastructure for infrastructure's sake.
- **Application**: use cases and orchestration. Coordinates domain behaviour and
  external capabilities.
- **Infrastructure**: databases, HTTP clients, filesystems, queues, OS APIs,
  frameworks, external services, and other mechanisms.
- **Adapters / transport / presentation**: controllers, CLI handlers, Pi hooks,
  HTTP endpoints, UI integration, and message handlers.

Introduce a boundary only when it provides at least one of these benefits:

1. It gives a useful dependency direction.
2. It enables a test.
3. It isolates a volatile dependency.
4. It establishes one authoritative owner of each state and behaviour.
5. It makes a dependency replaceable.
6. It improves locality of change.
7. It marks a real domain or application boundary.

For ASP.NET, do not create `Controller`, `Service`, `Repository`, `IRepository`,
`UnitOfWork`, `DbContext` layering by default. Evaluate each boundary against
the list above. A framework or ORM that already provides the capability needs no
wrapper that only renames it.

## Dependency direction

- Dependencies point toward stable concepts and useful boundaries.
- Do not make domain depend on infrastructure.
- Do not couple application logic to transport or framework concerns.
- Do not create an abstraction whose only purpose is to reverse a harmless

From mineugene/pi-dev-config, MIT.

More from mineugene/pi-dev-config