machenjie layered-architecture-design
Registry Trigger
Use when
- design presentation application domain infrastructure and persistence layering
Do not use when
- no task-local layered architecture design decision is required
Skill Role
Define layer responsibilities, dependency direction, domain independence, orchestration, adapter boundaries, cross-cutting placement, and layer evidence. Exclude architecture-style selection and module decomposition.
High-Value Rules
- Define layers by responsibility and authority. Distinguish transport or presentation, application orchestration, domain decisions, and infrastructure capabilities using actual ownership rather than folder names.
- Point dependencies toward stable policy. Keep business rules independent of delivery and storage mechanisms, and represent required external capabilities through contracts owned at the appropriate inner boundary.
- Keep orchestration distinct from domain decisions. Let application code coordinate use cases, transactions, identity context, and effects while domain owners enforce invariants and infrastructure adapters implement external mechanisms.
- Translate at boundaries. Map transport, persistence, provider, event, and framework models to owned internal meaning so external schema or lifecycle changes do not leak across layers silently.
- Place cross-cutting behavior at the decision point. Align validation, authorization, transactions, retries, logging, caching, and error translation with the layer holding the required context and authority.
- Avoid ceremonial pass-through. Retain a layer or interface only when it protects a real policy, substitution, ownership, lifecycle, compatibility, or test boundary.
- Prove dependency and behavior effects. Inspect imports, construction, runtime calls, state and side effects, tests, generated code, and bypass paths, then state repository and runtime limits.
Anti-Patterns
- Put business rules in controllers, persistence models, framework callbacks, or adapters because those locations already have data.
- Mirror identical models and pass-through methods across layers without protecting a semantic boundary.
- Infer architecture from directory layout while runtime dependencies, callbacks, service location, or generated wiring point elsewhere.
Stop Conditions
Escalate when responsibility or authority is ambiguous, domain logic depends directly on volatile infrastructure, or transactions or permissions span layers without an owner. Also escalate when a proposed layer lacks a decision boundary, or actual dependency direction cannot be established.
Output Contract
- layered-architecture decision with responsibilities, dependency direction, domain and orchestration boundary, adapters, cross-cutting placement, evidence, proof limits, and residual owners
Targeted References
| Path | Type | Load when | Do not load when | Required by | Required output |
|---|---|---|---|---|---|
| benchmarks and patterns | benchmark-pattern | placement transaction or failure translation has competing layer choices | current dependency direction and ownership select one layer placement | analysis-agent, task-agent | option-comparison, selected-approach |
| checklist | decision-checklist | change crosses presentation application domain infrastructure or adapter boundaries | owner-internal change preserves all established layer contracts | analysis-agent, task-agent | checklist-result, residual-risk |
| evidence patterns | evidence-pattern | layer dependency transaction or exception claims need current proof | post-edit imports tests and architecture checks prove each claim | analysis-agent, task-agent | evidence-record, proof-limit, residual-risk |