dawiddutoit/custom-claude/architecture-validate-layer-boundaries

Key terms: Clean Architecture, layer boundaries, domain layer, application layer, infrastructure

Validate Clean Architecture Layer Boundaries

Purpose

Validates that all layers respect Clean Architecture dependency rules by checking that domain has no external imports, application doesn't import from interfaces, and infrastructure implements repository interfaces correctly. Ensures architectural integrity before commits and during quality gates.

Table of Contents

Core Sections

• Purpose - What this skill validates
• When to Use This Skill - Triggers and use cases
• Triggers - Explicit trigger phrases
• What This Skill Does - Layer dependency rules and validation process
• Quick Start - Immediate validation workflow
• Usage Examples - Real-world scenarios
• Supporting Files - References, examples, and scripts

Detailed Sections

• Validation Process - Step-by-step validation workflow
• Expected Outcomes - Success and failure scenarios
• Detection Patterns - Grep patterns for violations
• Integration Points - Hooks, quality gates, and agents
• Expected Benefits - Performance metrics
• Success Metrics - Measurement criteria

When to Use This Skill

Use this skill when:

• Making changes to files in domain/application/infrastructure/interface layers
• Adding new dependencies to any layer
• Reviewing code for architecture compliance
• Running pre-commit quality gates
• User asks "Does this follow Clean Architecture?"

Triggers

Trigger with phrases like:

• "validate architecture"
• "check layer boundaries"
• "verify Clean Architecture"
• "does this follow Clean Architecture?"
• "validate my changes follow Clean Architecture"
• "check architectural compliance"
• "are my layer dependencies correct?"
• "validate domain layer imports"

What This Skill Does

Validates that all layers respect Clean Architecture dependency rules:

Layer Dependency Rules

Domain Layer (src/project_watch_mcp/domain/)

• ❌ CANNOT import from: infrastructure, interfaces, application
• ✅ CAN import from: domain only
• Rationale: Domain is innermost layer, pure business logic

Application Layer (src/project_watch_mcp/application/)

• ❌ CANNOT import from: interfaces
• ✅ CAN import from: domain, application
• Rationale: Application orchestrates domain, but doesn't know about interfaces

Infrastructure Layer (src/project_watch_mcp/infrastructure/)

• ✅ CAN import from: any layer
• ✅ CAN import external dependencies (Neo4j, etc.)
• Must: Implement domain repository interfaces
• Rationale: Infrastructure is outermost layer, connects to external systems

Interface Layer (src/project_watch_mcp/interfaces/)

• ❌ CANNOT import from: infrastructure, domain directly
• ✅ CAN import from: application
• Rationale: Interfaces depend on application use cases only

Validation Process

1. Identify Layer: Determine which layer the file belongs to based on path
2. Extract Imports: Parse all import and from ... import statements
3. Check Rules: Validate imports against layer-specific rules
4. Report Violations: List violations with file:line references

Quick Start

User: "Validate my architecture changes"

What happens:

1. Skill identifies which layer each file belongs to
2. Checks imports against Clean Architecture rules
3. Reports violations with specific fixes

Result: ✅ Pass (boundaries respected) or ❌ Fail (violations with fixes)

Example output:

Success: All files respect boundaries with 0 violations detected.

Failure: Specific violations reported with file location, issue description, and fix guidance.

See examples/examples.md for detailed output examples.

Supporting Files

• references/layer-rules.md - Complete layer dependency matrix with examples
• references/violation-fixes.md - Common violations and how to fix them
• examples/examples.md - Detailed validation scenarios and expected outputs
• scripts/validate.sh - Executable validation script for Clean Architecture layer boundaries

Usage Examples

Example 1: Validate Single File

User: "Is this domain model valid?"

Claude invokes skill by reading file and checking imports:

• Identify layer from path
• Extract all imports using Grep
• Check each import against layer rules
• Report violations

See examples/examples.md for detailed output.

Example 2: Validate All Changes

User: "Check if my changes follow Clean Architecture"

Claude invokes skill for all modified files:

1. Run: git diff --name-only
2. Filter Python files
3. Validate each file's imports
4. Report summary of violations

See examples/examples.md for detailed output.

Example 3: Pre-Commit Gate

Invoked automatically by pre-commit hook:

1. Get staged files
2. Validate layer boundaries
3. Block commit if violations found

See examples/examples.md for implementation details.

Expected Outcomes

Success (No Violations)

All files checked with 0 violations detected. Layer boundaries are respected across all layers.

Failure (Violations Found)

Violations reported with:

• File path and line number
• Issue description (which layer rule violated)
• Offending code line
• Specific fix guidance

See examples/examples.md for detailed violation output examples.

Detection Patterns

The skill uses Grep patterns to detect violations across layers:

• Domain layer violations: Detects imports from application/infrastructure/interfaces
• Application layer violations: Detects imports from interfaces
• Interface layer violations: Detects direct imports from domain or infrastructure

See scripts/validate.sh for the exact grep patterns and validation logic used.

Integration Points

With Pre-Flight Validation Hook

The pre-flight validation hook in .claude/scripts/pre_flight_validation.py can invoke this skill to validate architectural boundaries before allowing tool execution.

With Quality Gates

Quality gate scripts in ./scripts/check_all.sh can run the validation script to ensure Clean Architecture compliance as part of CI/CD.

With @architecture-guardian

The architecture guardian agent can delegate boundary validation to this skill rather than implementing validation inline, reducing context load by 96%.

Expected Benefits

Success Metrics

After implementation, measure:

• Invocation Rate: Skill invoked in 80%+ of architecture validation tasks
• Context Reduction: 90%+ reduction vs agent approach
• Violation Detection: 95%+ recall (catches all major violations)
• False Positives: <5% (no incorrect violations)