ZacharyZhang-NY
e74dafcd36
Three independently ugly bugs that all fed the same log flood:
* Electron's `WebFrameMain.send` writes every "Render frame was disposed"
to stderr via `console.error`. When the worker fans a second
agent-event past a reloading renderer, we produced thousands of
identical lines and stalled the main loop on stderr I/O. Added a
`mainFrame.detached` guard so the send is short-circuited before
Electron's own catch block fires, and installed a targeted filter in
`suppress-warnings.ts` (now actually imported from the entry point)
so the specific `console.error("Error sending from webFrameMain:"…)`
noise never reaches the terminal. Any other payload still surfaces.
* `dispatchAgentMessage` accepted the human-reader sentinel as a wake
target when an agent replied to `__board__` — `wakeAgentIfPossible`
then called `db.getAgent("__board__")`, threw, and the dispatcher
kept repeating on every send. Strip `HUMAN_SENDER_ID` at
`resolveMessageWakeTargets`, and keep a defense-in-depth guard in the
heartbeat so a stray caller (future automation fan-out) cannot
reintroduce the crash.
* Pi's skills loader rejects any SKILL.md whose frontmatter `name`
diverges from its parent directory. The four bundled `my-writing-style`
copies declared `name: writing-style-skill`, so every install emitted
a warning and dropped the skill. They also lived as orphan gitlinks
(mode 160000 without .gitmodules), and the global `*.md` gitignore
hid every other SKILL.md from version control. Fixed the frontmatter
to match the dir, converted the dangling submodules to plain trees,
and allowlisted `builtin-skills/**/*.md` so a fresh clone carries the
catalogue instead of silently losing it.
114 lines
7.2 KiB
Markdown
114 lines
7.2 KiB
Markdown
---
|
|
name: clean-architecture
|
|
description: Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.
|
|
---
|
|
|
|
# Clean Architecture Best Practices
|
|
|
|
Comprehensive guide to Clean Architecture principles for designing maintainable, testable software systems. Based on Robert C. Martin's "Clean Architecture: A Craftsman's Guide to Software Structure and Design." Contains 42 rules across 8 categories, prioritized by architectural impact.
|
|
|
|
## When to Apply
|
|
|
|
Reference these guidelines when:
|
|
- Designing new software systems or modules
|
|
- Structuring dependencies between layers
|
|
- Defining boundaries between business logic and infrastructure
|
|
- Reviewing code for architectural violations
|
|
- Refactoring coupled systems toward cleaner structure
|
|
|
|
## Rule Categories by Priority
|
|
|
|
| Priority | Category | Impact | Prefix |
|
|
|----------|----------|--------|--------|
|
|
| 1 | Dependency Direction | CRITICAL | `dep-` |
|
|
| 2 | Entity Design | CRITICAL | `entity-` |
|
|
| 3 | Use Case Isolation | HIGH | `usecase-` |
|
|
| 4 | Component Cohesion | HIGH | `comp-` |
|
|
| 5 | Boundary Definition | MEDIUM-HIGH | `bound-` |
|
|
| 6 | Interface Adapters | MEDIUM | `adapt-` |
|
|
| 7 | Framework Isolation | MEDIUM | `frame-` |
|
|
| 8 | Testing Architecture | LOW-MEDIUM | `test-` |
|
|
|
|
## Quick Reference
|
|
|
|
### 1. Dependency Direction (CRITICAL)
|
|
|
|
- [`dep-inward-only`](references/dep-inward-only.md) - Source dependencies point inward only
|
|
- [`dep-interface-ownership`](references/dep-interface-ownership.md) - Interfaces belong to clients not implementers
|
|
- [`dep-no-framework-imports`](references/dep-no-framework-imports.md) - Avoid framework imports in inner layers
|
|
- [`dep-data-crossing-boundaries`](references/dep-data-crossing-boundaries.md) - Use simple data structures across boundaries
|
|
- [`dep-acyclic-dependencies`](references/dep-acyclic-dependencies.md) - Eliminate cyclic dependencies between components
|
|
- [`dep-stable-abstractions`](references/dep-stable-abstractions.md) - Depend on stable abstractions not volatile concretions
|
|
|
|
### 2. Entity Design (CRITICAL)
|
|
|
|
- [`entity-pure-business-rules`](references/entity-pure-business-rules.md) - Entities contain only enterprise business rules
|
|
- [`entity-no-persistence-awareness`](references/entity-no-persistence-awareness.md) - Entities must not know how they are persisted
|
|
- [`entity-encapsulate-invariants`](references/entity-encapsulate-invariants.md) - Encapsulate business invariants within entities
|
|
- [`entity-value-objects`](references/entity-value-objects.md) - Use value objects for domain concepts
|
|
- [`entity-rich-not-anemic`](references/entity-rich-not-anemic.md) - Build rich domain models not anemic data structures
|
|
|
|
### 3. Use Case Isolation (HIGH)
|
|
|
|
- [`usecase-single-responsibility`](references/usecase-single-responsibility.md) - Each use case has one reason to change
|
|
- [`usecase-input-output-ports`](references/usecase-input-output-ports.md) - Define input and output ports for use cases
|
|
- [`usecase-orchestrates-not-implements`](references/usecase-orchestrates-not-implements.md) - Use cases orchestrate entities not implement business rules
|
|
- [`usecase-no-presentation-logic`](references/usecase-no-presentation-logic.md) - Use cases must not contain presentation logic
|
|
- [`usecase-explicit-dependencies`](references/usecase-explicit-dependencies.md) - Declare all dependencies explicitly in constructor
|
|
- [`usecase-transaction-boundary`](references/usecase-transaction-boundary.md) - Use case defines the transaction boundary
|
|
|
|
### 4. Component Cohesion (HIGH)
|
|
|
|
- [`comp-screaming-architecture`](references/comp-screaming-architecture.md) - Structure should scream the domain not the framework
|
|
- [`comp-common-closure`](references/comp-common-closure.md) - Group classes that change together
|
|
- [`comp-common-reuse`](references/comp-common-reuse.md) - Avoid forcing clients to depend on unused code
|
|
- [`comp-reuse-release-equivalence`](references/comp-reuse-release-equivalence.md) - Release components as cohesive units
|
|
- [`comp-stable-dependencies`](references/comp-stable-dependencies.md) - Depend in the direction of stability
|
|
|
|
### 5. Boundary Definition (MEDIUM-HIGH)
|
|
|
|
- [`bound-humble-object`](references/bound-humble-object.md) - Use humble objects at architectural boundaries
|
|
- [`bound-partial-boundaries`](references/bound-partial-boundaries.md) - Use partial boundaries when full separation is premature
|
|
- [`bound-boundary-cost-awareness`](references/bound-boundary-cost-awareness.md) - Weigh boundary cost against ignorance cost
|
|
- [`bound-main-component`](references/bound-main-component.md) - Treat main as a plugin to the application
|
|
- [`bound-defer-decisions`](references/bound-defer-decisions.md) - Defer framework and database decisions
|
|
- [`bound-service-internal-architecture`](references/bound-service-internal-architecture.md) - Services must have internal clean architecture
|
|
|
|
### 6. Interface Adapters (MEDIUM)
|
|
|
|
- [`adapt-controller-thin`](references/adapt-controller-thin.md) - Keep controllers thin
|
|
- [`adapt-presenter-formats`](references/adapt-presenter-formats.md) - Presenters format data for the view
|
|
- [`adapt-gateway-abstraction`](references/adapt-gateway-abstraction.md) - Gateways hide external system details
|
|
- [`adapt-mapper-translation`](references/adapt-mapper-translation.md) - Use mappers to translate between layers
|
|
- [`adapt-anti-corruption-layer`](references/adapt-anti-corruption-layer.md) - Build anti-corruption layers for external systems
|
|
|
|
### 7. Framework Isolation (MEDIUM)
|
|
|
|
- [`frame-domain-purity`](references/frame-domain-purity.md) - Domain layer has zero framework dependencies
|
|
- [`frame-orm-in-infrastructure`](references/frame-orm-in-infrastructure.md) - Keep ORM usage in infrastructure layer
|
|
- [`frame-web-in-infrastructure`](references/frame-web-in-infrastructure.md) - Web framework concerns stay in interface layer
|
|
- [`frame-di-container-edge`](references/frame-di-container-edge.md) - Dependency injection containers live at the edge
|
|
- [`frame-logging-abstraction`](references/frame-logging-abstraction.md) - Abstract logging behind domain interfaces
|
|
|
|
### 8. Testing Architecture (LOW-MEDIUM)
|
|
|
|
- [`test-tests-are-architecture`](references/test-tests-are-architecture.md) - Tests are part of the system architecture
|
|
- [`test-testable-design`](references/test-testable-design.md) - Design for testability from the start
|
|
- [`test-layer-isolation`](references/test-layer-isolation.md) - Test each layer in isolation
|
|
- [`test-boundary-verification`](references/test-boundary-verification.md) - Verify architectural boundaries with tests
|
|
|
|
## How to Use
|
|
|
|
Read individual reference files for detailed explanations and code examples:
|
|
|
|
- [Section definitions](references/_sections.md) - Category structure and impact levels
|
|
- [Rule template](assets/templates/_template.md) - Template for adding new rules
|
|
|
|
## Reference Files
|
|
|
|
| File | Description |
|
|
|------|-------------|
|
|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
|
|
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
|
|
| [metadata.json](metadata.json) | Version and reference information |
|