neo-clean-architecture
Skill7 starsChanged 6 months agoMITView on GitHub
Use this skill when the user wants to design, implement, review, or refactor software systems conforming to Clean Architecture principles. It structures code into Domain, Application, Infrastructure, and Presentation/API layers, enforcing inward-only dependencies. It advocates rich domain models, CQRS, and the Result pattern, operating on technology-neutral concepts without database or framework bindings.
In this repository28 other files it gives its agents.
- AGENTS.mdAGENTS.md
- generate-skillSkill
- neo-azure-pipelinesSkill
- neo-clarificationSkill
- neo-code-reviewSkill
- neo-csharp-interface-generatorSkill
- neo-csharpSkill
- neo-dotnet-ef-coreSkill
- neo-dotnet-minimal-apisSkill
- neo-dotnet-mvcSkill
- neo-dotnetSkill
- neo-dotnet-tag-helperSkill
- neo-dotnet-webapiSkill
- neo-harness-projectSkill
- neo-harnessSkill
- neo-javascriptSkill
- neo-opentelemetrySkill
- neo-prSkill
- neo-python-managerSkill
- neo-pythonSkill
- neo-rabbitmqSkill
- neo-rustSkill
- neo-stop-slopSkill
- neo-sub-agentSkill
- neo-swiftSkill
- neo-swift-uiSkill
- neo-typescriptSkill
- neo-vueSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Pointless Value Objects: Avoid wrapping primitives (e.g., string, number) unless they encapsulate validation (e.g., email format) or …
- Distinctive: line 19
Deep Object Graphs: Do not nest full entities for associations.
- Distinctive: line 21
Exception Control Flow: Do not throw runtime exceptions for expected business failures (e.g., duplicate title, user not found).
- Distinctive: line 43
Read design_principles.md for architectural details.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Clean Architecture
Design and review software systems using Clean Architecture. The core objective is separating concerns based on their rate of change, directing all source code dependencies inward toward the Domain core.
Gotchas
- Anemic Models: Entities that are mere data containers (only getters/setters) leak business logic. Entities must protect their invariants. State changes must go through explicit, business-oriented methods.
- Pointless Value Objects: Avoid wrapping primitives (e.g., string, number) unless they encapsulate validation (e.g., email format) or behavior (e.g., auto-slug generation).
- Deep Object Graphs: Do not nest full entities for associations. Loading a parent entity will trigger database performance issues. Reference other aggregates using IDs instead.
- Dependency Leakage: Repository interfaces must reside in the Application layer, with implementations in Infrastructure. Never return query streams (e.g.,
IQueryable) to Application, as it leaks database concerns. - Exception Control Flow: Do not throw runtime exceptions for expected business failures (e.g., duplicate title, user not found). Use the Result pattern for flow control.
Workflow Checklist
Progress:
- Step 1: Analyze Core & Boundaries (See
references/design_principles.md). - Step 2: Design Domain Layer (Build entities and value objects; protect invariants).
- Step 3: Design Application Layer (Define use case handlers, CQRS inputs, and repository interfaces).
- Step 4: Implement Outer Layers (Implement database mapping, external services, and API controllers).
- Step 5: Audit Architecture Health (Use
assets/review_checklist.mdto scan code).
Detailed Guidelines
Step 1 — Analyze Core & Boundaries
- Categorize business rules:
- Domain Layer: Core rules that would exist even without a computer system.
- Application Layer: System orchestration, workflows, and protocols.
- Outer Layers (Infrastructure/Presentation): Delivery mechanisms and persistence details.
- Read design_principles.md for architectural details.
Step 2 — Design Domain Layer
- Entities: Keep setters private or read-only.
- Domain Methods: Expose semantic operations (e.g.,
updateContent(),addTag()) that validate rules inside the entity. - Associations: Keep aggregates decoupled by referencing other aggregate roots via ID only.
Step 3 — Design Application Layer
- Separate write operations (Commands) from read operations (Queries) using CQRS.
- Define technology-neutral interfaces (e.g.,
IUserRepository), keeping database or network specifics out of Application. - Wrap use case outcomes in a Result type containing success/failure status, value, error type, and message. Refer to layer_specifications.md for concepts mapping.
Step 4 — Implement Infrastructure & Presentation
- Infrastructure: Implement interfaces defined in Application. Configure ORM/database mappings, value conversions, and call external services.
- Presentation/API: Handle transmission protocols (e.g., HTTP, gRPC). Map request payload to Command/Query, dispatch it to Application, and translate the Result into appropriate responses (e.g., HTTP 200, 201, 400, 404, 409).
Output Templates
1. Architecture Blueprint Template
# [System Name] Clean Architecture Blueprint
## 1. Domain Layer
* **Entities & Aggregate Roots**:
- `EntityName` (ID-association explanation)
* **Value Objects**:
- `ValueObjectName` (Validation and behavior description)
## 2. Application Layer
* **Use Cases (CQRS / Handlers)**:
- `CreateSomethingCommand` & Handler
- `GetSomethingQuery` & Handler
* **External Interfaces (Gateways / Repositories)**:
- `ISomethingRepository` (Interface methods)
## 3. Infrastructure Layer
* **Persistence Configurations**:
- `SomethingRepository` implementation notes
- Value Object persistence mapping rules
## 4. Presentation / API Layer
* **Contracts (Request/Response)**:
- `CreateSomethingRequest` -> `SomethingResponse`
* **Route & Status Code Mappings**:
- `POST /api/something` -> `201 Created` / `400 Bad Request` / `409 Conflict`2. Architecture Review Template
# Clean Architecture Review — [Project Name]
## Health Score: [Score]/10
[Brief architectural health assessment]
## Findings & Recommendations
### 🔴 Critical (Dependency Violation / Invariant Leakage)
* **Location**: `path/to/file.ext#L12-30`
* **Problem**: [Description of the clean architecture violation]
* **Remediation**:
```[language]
// Corrected code snippet🟡 Warning (Anemic Model / Pointless Wrapping)
- Location:
path/to/file.ext - Problem: [Issue description]
- Remediation: [Code or prose description]
🟢 Info (Structural / Pipeline Enhancements)
- Location:
path/to/file.ext - Remediation: [Suggestion details]
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

