clean-architecture-checker
Verifies code follows Clean Architecture principles in Polibase. Activates when creating or modifying src/domain, src/application, src/infrastructure, or src/interfaces files. Checks dependency rules, entity independence, repository patterns, DTO usage, and type safety.
When & Why to Use This Skill
The Clean Architecture Checker is a specialized Claude skill designed to automate the enforcement of architectural integrity within software projects. It proactively monitors code changes across domain, application, infrastructure, and interface layers to ensure strict adherence to dependency rules, entity independence, and standardized patterns like DTOs and Repositories, significantly reducing technical debt and improving long-term maintainability.
Use Cases
- Automated Architectural Guardrails: Real-time verification of dependency rules (Domain ← Application ← Infrastructure) during the development process to prevent architectural erosion and circular dependencies.
- Framework Decoupling: Ensuring domain entities remain pure and independent of external frameworks (e.g., SQLAlchemy, Pydantic, or UI libraries), facilitating easier unit testing and future technology migrations.
- Standardized Data Transfer: Enforcing the strict use of DTOs (Data Transfer Objects) at layer boundaries to prevent internal domain models from leaking into external interfaces, ensuring a clean API contract.
- Type Safety & Quality Assurance: Automatically checking for comprehensive Python type hints and proper 'Optional' handling to enhance code robustness and developer productivity through better IDE support.
- Onboarding & Pattern Consistency: Helping new team members adhere to project-specific architectural standards (such as the Polibase structure) by providing immediate feedback on common violations.
| name | clean-architecture-checker |
|---|---|
| description | Verifies code follows Clean Architecture principles in Polibase. Activates when creating or modifying src/domain, src/application, src/infrastructure, or src/interfaces files. Checks dependency rules, entity independence, repository patterns, DTO usage, and type safety. |
Clean Architecture Checker
Purpose
Verify that new code follows Clean Architecture principles as defined in the Polibase project.
When to Activate
This skill activates automatically when:
- Creating or modifying files in
src/domain/,src/application/,src/infrastructure/, orsrc/interfaces/ - Reviewing code changes across multiple layers
- Adding entities, repositories, use cases, or services
Quick Checklist
Before approving code, verify:
- Dependency Rule: Dependencies point inward (Domain ← Application ← Infrastructure ← Interfaces)
- Entity Independence: Domain entities have no framework dependencies (no SQLAlchemy, Streamlit, etc.)
- Repository Pattern: All repos inherit from
BaseRepository[T]and use async/await - DTO Usage: DTOs used for layer boundaries, not raw entities
- DTO Placement: DTOは
src/application/dtos/に配置（UseCaseファイル内に混在させない） - UseCase間依存: Orchestratorパターンとして許容される場合のみ（抽出ログ統合等）
- Type Safety: Complete type hints with proper
Optionalhandling - Tests: Unit tests for domain services and use cases
Core Principles
1. Dependency Rule
Dependencies must point inward: Domain ← Application ← Infrastructure ← Interfaces
✅ Domain imports nothing from outer layers ✅ Application only imports Domain ✅ Infrastructure imports Domain and Application ✅ Interfaces imports all inner layers (but not other Interface modules)
2. Entity Independence
Domain entities must not depend on external frameworks
✅ Use @dataclass or Pydantic BaseModel
❌ No SQLAlchemy models in Domain
❌ No UI framework imports in Domain
3. Repository Pattern
All repositories follow async/await with ISessionAdapter
✅ Interfaces in Domain: class IRepo(BaseRepository[T])
✅ Implementations in Infrastructure: class RepoImpl(BaseRepositoryImpl[T], IRepo)
✅ All methods are async def
4. DTO Pattern
Always use DTOs between layers
✅ DTOs in src/application/dtos/（専用ファイルに配置）
✅ Input DTO → Use Case → Output DTO
❌ Never expose domain entities directly to outer layers
❌ UseCaseファイル内にDTO定義を混在させない（Issue #969）
5. UseCase間依存（Orchestratorパターン）
UseCase間依存は条件付きで許容
✅ Orchestrator UseCase が 子UseCase を呼び出すパターンは許容
✅ 抽出ログ統合（UpdateEntityFromExtractionUseCase）への依存は許容（ADR-0005）
❌ UseCase間で循環依存を作らない
❌ Bronze Layer / Gold Layer の保護機構をバイパスしない
6. Type Safety
Leverage Python 3.11+ type hints
✅ All public methods have type hints
✅ Use T | None for nullable types
✅ Explicit None checks for Optional values
Common Violations
See examples.md for detailed good/bad code examples.
Detailed Reference
For comprehensive architecture guidelines, see reference.md.
Templates
Use templates in templates/ directory for creating new:
- Domain entities
- Repository interfaces and implementations
- Use cases with DTOs
- Domain services