architecture-validate-srp（架构验证 SRP）

Validate Single Responsibility Principle (SRP)

Automated detection of SRP violations using actor-driven analysis, metrics, and AST patterns.

Purpose

Detect Single Responsibility Principle violations using multi-dimensional analysis including naming patterns, class metrics, method complexity, cohesion measurements, and project-specific architectural patterns. Provides actionable fix guidance with confidence scoring and refactoring estimates.

Table of Contents

Core Sections

• Purpose - What this skill detects and validates
• Quick Start - Immediate SRP validation workflow
• When to Use This Skill - Triggers and integration points
• What This Skill Does - SRP definition and detection methods
• Instructions - Complete step-by-step validation process
• Usage Examples - Real-world validation scenarios
• Supporting Files - References and examples

Detailed Sections

• Validation Levels - Fast, thorough, and full analysis modes
• Detection Methods - 4-level validation approach
• Integration with Other Skills - code-review, validate-architecture, quality-gates
• Parameters - Configuration options
• Output Format - Text and JSON report formats
• Success Metrics - Accuracy and performance targets
• Requirements - Dependencies and installation
• Red Flags to Avoid - Common pitfalls
• Troubleshooting - Common issues and solutions
• Expected Benefits - Metrics and improvements

Quick Start

User asks: "Check if this class is doing too much" or "Validate SRP compliance"

What happens:

1. Scans code for SRP violations (naming, size, complexity, dependencies)
2. Calculates cohesion metrics (TCC, ATFD, WMC)
3. Detects project-specific anti-patterns
4. Reports violations with specific refactoring guidance
5. Estimates refactoring time and effort

Result: ✅ SRP compliant OR ❌ Violations with actionable fixes

When to Use This Skill

Invoke this skill when:

• User asks: "check SRP", "single responsibility", "is this doing too much"
• User asks: "god class", "too many dependencies", "method too long"
• Before commit (as part of code-review skill)
• During refactoring or architectural review
• As quality gate (via run-quality-gates skill)
• When class/method feels complex but can't articulate why

Integration triggers:

• code-review skill Step 2: Architectural Review (SRP sub-check)
• validate-architecture skill: SRP at layer level
• run-quality-gates skill: Optional SRP quality gate
• multi-file-refactor skill: SRP-driven refactoring coordination

What This Skill Does

SRP Definition (Actor-Driven)

Robert C. Martin: "A module should be responsible to one, and only one, actor."

• Actor: A group of users or stakeholders who would request changes
• NOT "do one thing" (task-driven) - a class can have multiple methods
• IS "have one reason to change" (actor-driven)

Example: See examples/violation-naming-patterns.py for violation and correct implementation showing Employee class serving 3 actors (Accounting, HR, DBA) and the correct split into PayCalculator, HourReporter, and EmployeeRepository.

Detection Methods (Multi-Dimensional)

This skill uses 4 validation levels:

1. Level 1 (Fast, 5s): Naming patterns via AST-grep

- Methods with "and" in name → 40% confidence violation - Quick scan of entire codebase

1. Level 2 (Fast, 10s): Size metrics via AST analysis

- Class >300 lines → Review needed - Method >50 lines → 60% confidence violation - 15 methods per class → Review needed

1. Level 3 (Moderate, 30s): Cohesion metrics

- God Class: ATFD >5 AND WMC >47 AND TCC <0.33 → 80% confidence - Constructor >4 params (warning), >8 params (critical) → 75% confidence

1. Level 4 (Manual, 5min): Actor analysis (guided questions)

- "How many actors would request changes to this class?" - "Can you split by actor responsibility?"

Default mode: Level 2 (Fast + Size metrics) - balance speed and accuracy

Validation Levels

Instructions

Step 1: Determine Validation Level

# User request → Validation level
"quick check" → fast
"review this class" → thorough (default)
"plan refactoring" → full

Step 2: Detect Naming Violations (All Levels)

Pattern 1: Methods with "and" in name (40% confidence)

Use the validation script to detect naming violations:

Using validation script:

./scripts/validate-srp.sh <path> --level=fast

Or manually with MCP tools:

mcp__ast-grep__find_code(
    pattern="def $NAME_and_$REST",
    project_folder="/path/to/project",
    language="python"
)

Example violations and fixes: See examples/violation-naming-patterns.py showing validate_and_save_user() violation and the correct split into validate_user() and save_user().

Step 3: Analyze Size Metrics (Thorough+)

Pattern 2: Class size (300+ lines → review)

Use the validation script for size analysis:

./scripts/validate-srp.sh <path> --level=thorough

Or use God Class detection script:

./scripts/check-god-class.sh <file.py>

Thresholds:

• Class: >300 lines = warning, >500 lines = critical
• Method: >50 lines = warning, >100 lines = critical
• Methods per class: >15 = warning, >25 = critical

Step 4: Calculate Cohesion Metrics (Thorough+)

God Class Detection (80% confidence):

• ATFD (Access to Foreign Data): >5 = excessive coupling
• WMC (Weighted Methods per Class): >47 = too complex
• TCC (Tight Class Cohesion): <0.33 = low cohesion

Formula: ATFD >5 AND WMC >47 AND TCC <0.33 → God Class

Calculate metrics using radon:

# If radon available
uv run radon cc src/ -a -nb  # Cyclomatic complexity (WMC proxy)
uv run radon raw src/        # Raw metrics

See: references/srp-principles.md for detailed metric calculations and formulas.

Step 5: Detect Constructor Dependencies (Thorough+)

Pattern 4: Constructor parameters (>4 warning, >8 critical)

Use the God Class detection script:

./scripts/check-god-class.sh <file.py>

Thresholds (75% confidence):

• 1-4 params: ✅ Good
• 5-8 params: ⚠️ Warning (consider parameter object)
• 9+ params: ❌ Critical (God Class indicator)

Example violations and fixes: See examples/violation-god-class.py showing UserService with 9 constructor parameters and the correct split into UserAuthService, UserNotificationService, and UserAnalytics.

Step 6: Detect Project-Specific Patterns

Read CLAUDE.md for project anti-patterns:

Check for project-specific SRP violations using grep:

# Pattern 1: Optional config parameters (project anti-pattern)
grep -rn "config.*Optional\|config.*None.*=" src/

# Pattern 2: Domain entities doing I/O (layer violation)
grep -r "import.*requests\|import.*database" domain/

# Pattern 3: Application services with business logic
grep -r "def calculate\|def compute" application/services/

# Pattern 4: Repositories with orchestration
grep -A 10 "class.*Repository" infrastructure/repositories/

Common project-specific violations:

• Domain entities importing infrastructure
• Application services implementing business logic (should orchestrate only)
• Repositories containing orchestration (should be data access only)
• Optional config parameters (violates fail-fast)

See: references/srp-principles.md for actor identification guidance.

Step 7: Actor Analysis (Full Mode Only)

Guided questions for user:

1. "List all actors who would request changes to this class:"

- Example: "HR department, Accounting team, DBA"

1. "Can you group methods by actor?"

- Example: calculate_pay() → Accounting, report_hours() → HR

1. "How would you name classes split by actor?"

- Example: PayCalculator, HourReporter, EmployeeRepository

Actor count → Violation confidence:

• 1 actor: ✅ SRP compliant
• 2 actors: ⚠️ Warning (consider split)
• 3+ actors: ❌ Violation (must split)

Step 8: Generate Report

Report structure:

SRP Validation Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Passed: X/Y classes (Z%)

❌ Violations Found: N

[CRITICAL] God Class: ClassName (path/file.py:line)
  - Lines: X (threshold: 300)
  - Methods: Y (threshold: 15)
  - Constructor params: Z (threshold: 4)
  - ATFD: A, WMC: B, TCC: C
  - Actors detected: N (actor1, actor2, actor3)
  - Fix: Split into Class1 (actor1), Class2 (actor2), Class3 (actor3)
  - Estimated refactoring: A-B hours

[WARNING] Method Name Violation: method_and_other (path/file.py:line)
  - Method name contains 'and'
  - Confidence: 40%
  - Fix: Split into method() and other()
  - Estimated refactoring: 15-30 minutes

[WARNING] Long Method: process_request (path/file.py:line)
  - Lines: X (threshold: 50)
  - Cyclomatic complexity: Y (threshold: 10)
  - Confidence: 60%
  - Fix: Extract 2-3 smaller methods
  - Estimated refactoring: 30-60 minutes

Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- X critical violations (must fix)
- Y warnings (should fix)
- Total estimated refactoring time: A-B hours
- Top priority: ClassName (god class)

Usage Examples

Example 1: Quick Pre-Commit Check

# User: "Quick SRP check before commit"

# Skill runs level: fast (5s)
→ Scans for method names with "and"
→ Reports 2 violations

Output:
⚠️ 2 SRP warnings found:

1. validate_and_save_user (src/services/user.py:45)
   - Method name contains 'and'
   - Fix: Split into validate_user() and save_user()

2. fetch_and_transform_data (src/utils/data.py:78)
   - Method name contains 'and'
   - Fix: Split into fetch_data() and transform_data()

Run with --thorough for complete analysis.

Example 2: Class Review (Default)

# User: "Review UserService for SRP compliance"

# Skill runs level: thorough (30s)
→ Naming patterns
→ Size metrics
→ Cohesion metrics
→ Constructor analysis

Output:
❌ UserService violates SRP (src/application/services/user_service.py:12)

Violations:
- Lines: 487 (threshold: 300) ❌
- Methods: 23 (threshold: 15) ⚠️
- Constructor params: 9 (threshold: 4) ❌
- ATFD: 12 (threshold: 5) ❌
- WMC: 89 (threshold: 47) ❌
- TCC: 0.21 (threshold: 0.33) ❌

Detected actors (3):
1. Authentication (login, logout, verify_token)
2. Profile Management (update_profile, get_profile, delete_account)
3. Notifications (send_welcome_email, send_reset_email)

Recommended split:
- UserAuthService: authentication methods
- UserProfileService: profile management
- UserNotificationService: notification methods

Estimated refactoring: 4-6 hours

Example 3: Deep Refactoring Analysis

# User: "Plan refactoring for PaymentProcessor - full SRP analysis"

# Skill runs level: full (5 min with user interaction)
→ All automated checks
→ Actor analysis questions
→ Refactoring plan

Questions asked:
1. "List actors who request changes to PaymentProcessor"
   User: "Finance team, Fraud detection, Customer support, Compliance"

2. "Group methods by actor"
   User provides grouping...

Output:
❌ PaymentProcessor is a God Class (4 actors detected)

Actor breakdown:
1. Finance (3 methods): process_payment, refund_payment, calculate_fees
2. Fraud Detection (2 methods): check_fraud_score, block_suspicious
3. Customer Support (2 methods): get_transaction_history, dispute_charge
4. Compliance (2 methods): log_transaction, generate_audit_report

Refactoring plan:
Phase 1 (2 hours): Extract PaymentProcessor (Finance actor)
Phase 2 (1.5 hours): Extract FraudDetectionService
Phase 3 (1.5 hours): Extract TransactionHistoryService (Support)
Phase 4 (1 hour): Extract ComplianceReporter
Phase 5 (1 hour): Integration tests and validation

Total estimated time: 7 hours
Recommended approach: Incremental (1 phase per day)

Integration with Other Skills

With code-review

The code-review skill invokes SRP validation in Step 2 (Architectural Review) as a sub-check. When SRP violations are detected, they are reported as warnings in the overall code review report.

Integration point: Automatic invocation during code review workflow with level="fast" for speed.

With validate-architecture

The validate-architecture skill checks SRP compliance at the layer level, while this skill checks at the class/method level. Domain layers should have high cohesion (TCC > 0.5), and this skill can detect low cohesion violations.

Integration point: Cross-layer validation to ensure architectural boundaries maintain SRP.

With run-quality-gates

SRP validation can be added as an optional quality gate in .claude/quality-gates.json:

{
  "optional_gates": ["srp_validation"],
  "srp_threshold": "warning"
}

Set threshold to "critical" to block commits on violations.

With multi-file-refactor

When refactoring God Classes that span multiple files, use multi-file-refactor skill to coordinate changes. This skill identifies God Classes and provides refactoring guidance; multi-file-refactor executes the split.

Parameters

Usage:

# Default (thorough mode on src/)
Skill(command: "validate-srp")

# Custom path and level
Skill(command: "validate-srp --path=src/application --level=full")

# JSON output for tooling integration
Skill(command: "validate-srp --output_format=json")

Output Format

Text Output (Default)

See Step 8 in Instructions for complete example.

JSON Output

{
  "summary": {
    "total_classes": 45,
    "violations": 7,
    "warnings": 12,
    "passed": 26,
    "compliance_rate": 0.58
  },
  "violations": [
    {
      "severity": "critical",
      "type": "god_class",
      "class": "UserService",
      "file": "src/application/services/user_service.py",
      "line": 12,
      "metrics": {
        "lines": 487,
        "methods": 23,
        "constructor_params": 9,
        "atfd": 12,
        "wmc": 89,
        "tcc": 0.21
      },
      "actors": ["Authentication", "Profile", "Notifications"],
      "confidence": 0.80,
      "fix": "Split into UserAuthService, UserProfileService, UserNotificationService",
      "estimated_hours": 5.0
    }
  ],
  "warnings": [
    {
      "severity": "warning",
      "type": "method_naming",
      "method": "validate_and_save_user",
      "file": "src/services/user.py",
      "line": 45,
      "confidence": 0.40,
      "fix": "Split into validate_user() and save_user()",
      "estimated_minutes": 20
    }
  ]
}

Supporting Files

References

• references/srp-principles.md - Core SRP concepts, actor-driven definition, real-world examples, cohesion metrics formulas

Examples

• examples/examples.md - Overview of all examples with expected results
• examples/violation-naming-patterns.py - Methods with "and" in name, multiple actors
• examples/violation-god-class.py - Constructor with too many parameters
• examples/correct-single-actor.py - Proper SRP implementation with single actor

Scripts

• scripts/validate-srp.sh - Main validation script with 3 levels (fast/thorough/full)
• scripts/check-god-class.sh - God Class detection for individual files

Success Metrics

Utility Scripts

validate-srp.sh

Main validation script with multi-level analysis:

# Fast check (naming patterns only - 5 seconds)
./scripts/validate-srp.sh src/ --level=fast

# Thorough check (naming + size + constructors - 30 seconds)
./scripts/validate-srp.sh src/ --level=thorough

# Full analysis (with actor questions - 5 minutes)
./scripts/validate-srp.sh src/ --level=full

# JSON output for CI/CD integration
./scripts/validate-srp.sh src/ --output-format=json

check-god-class.sh

Focused God Class detection for single files:

# Check specific file
./scripts/check-god-class.sh src/services/user_service.py

# Returns:
# - Constructor parameter count
# - Method count
# - File size
# - God Class recommendation

Requirements

Minimum:

• Python 3.10+ (for AST analysis)
• Read, Grep, Bash, Glob tools
• Source code in supported language (Python/JS/TS)
• Validation scripts in scripts/ directory

Optional:

• radon for accurate metrics: uv pip install radon
• mcp__ast-grep__* tools for precise AST analysis
• mcp__project-watch-mcp__search_code for context

Installation:

# Make scripts executable
chmod +x scripts/*.sh

# Optional: Install radon for accurate metrics
uv pip install radon

# Verify installation
uv run radon --version

Red Flags to Avoid

Architectural Violations

1. God Classes - ATFD >5, WMC >47, TCC <0.33
2. Constructor Dependencies - >8 parameters
3. Method Naming - Methods with "and" in name
4. File Size - >500 lines per file

Detection Anti-Patterns

1. Ignoring warnings - Small violations compound into big issues
2. Not validating fixes - Re-run after refactoring
3. Skipping actor analysis - Metrics alone miss context
4. Assuming SRP = "one method" - SRP is actor-driven, not task-driven

Process Mistakes

1. Refactoring without tests - Always have test coverage first
2. Big bang refactoring - Incremental refactoring safer
3. Not estimating effort - Plan time for refactoring
4. Skipping after major changes - Validation most critical after refactoring

Troubleshooting

Issue: Too Many False Positives

Symptom: Small helper methods flagged as violations

Fix: Adjust thresholds in .claude/srp-config.json:

{
  "thresholds": {
    "class_lines": 400,
    "method_lines": 75,
    "constructor_params": 6
  }
}

Issue: Metrics Not Calculated

Symptom: "Metrics unavailable" in report

Fix: Install radon:

uv pip install radon

Or use simplified heuristics (less accurate but faster).

Issue: Can't Identify Actors

Symptom: Actor analysis unclear

Fix: Ask targeted questions:

1. "Who would request changes to this class?"
2. "Can you group methods by job role?"
3. "What teams interact with this code?"

Expected Benefits

See Also

• validate-architecture - Layer-level architecture validation
• code-review - Comprehensive pre-commit review (includes SRP)
• run-quality-gates - Quality gate orchestration
• multi-file-refactor - Coordinate SRP-driven refactoring
• @code-review-expert - Agent for code review guidance
• @architecture-guardian - Agent for architectural decisions
• ARCHITECTURE.md - Project architecture documentation

Last Updated: 2025-11-02 Version: 1.0.0