Agent skill
validate-architecture
Validates architectural patterns and code quality per CLAUDE.md, detects anti-patterns and design violations
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/validate-architecture
SKILL.md
Validate Architecture Skill
Purpose
Validates architectural patterns and code quality standards per CLAUDE.md. Detects anti-patterns, placeholders, and violations of Pierre's design principles.
CLAUDE.md Compliance
- ✅ Enforces zero tolerance policies (no unwrap, no anyhow!, no placeholders)
- ✅ Validates architectural patterns (DI, resource management)
- ✅ Checks algorithm isolation (enum-based DI)
- ✅ Detects Claude Code anti-patterns
Usage
Run this skill:
- Before committing code
- Before pull requests
- After refactoring
- Weekly code quality audits
- After major feature additions
Prerequisites
- Python 3 (for pattern parsing)
- ripgrep (
rg) - Validation patterns file:
scripts/ci/validation-patterns.toml
Commands
Comprehensive Validation
# Run all architectural validations
./scripts/ci/architectural-validation.sh
Specific Pattern Categories
Critical Failures
# Check for placeholder implementations
python3 scripts/ci/parse-validation-patterns.py \
scripts/ci/validation-patterns.toml placeholder_patterns
# Check for unwrap/expect/panic
rg "\.unwrap\(\)|\.expect\(|panic!\(" src/ --type rust -n | \
grep -v "^tests/" | \
grep -v "^src/bin/" | \
grep -v "// Safe:"
Error Handling Anti-Patterns
# Check for anyhow::anyhow! (FORBIDDEN per CLAUDE.md)
rg "anyhow::anyhow!|\\banyhow!\(" src/ --type rust -n
# Verify structured error types
rg "#\[derive.*thiserror::Error" src/ --type rust -A 5 | head -30
Algorithm DI Validation
# Detect hardcoded algorithm formulas
python3 scripts/ci/parse-validation-patterns.py \
scripts/ci/validation-patterns.toml algorithm_di_patterns
# Verify enum-based algorithm dispatch
rg "pub enum.*Algorithm" src/intelligence/algorithms/ --type rust -A 10
Resource Management
# Check for direct resource creation (should use DI)
rg "AuthManager::new|OAuthManager::new|TenantOAuthManager::new" src/ --type rust -n | \
grep -v "^tests/" | \
grep -v "^src/bin/"
# Check for fake ServerResources (test-only pattern)
rg "Arc::new\(ServerResources" src/ --type rust -n | \
grep -v "^tests/"
Unsafe Code Policy
# ZERO tolerance for unsafe (except approved locations)
rg "unsafe " src/ --type rust -n | \
grep -v "^src/health.rs" && \
echo "❌ Unauthorized unsafe code!" || \
echo "✓ Unsafe code properly isolated"
Validation Categories
1. Placeholder Detection
Catches incomplete implementations:
// ❌ FORBIDDEN patterns
"Implementation would..."
"TODO: Implementation"
"stub implementation"
"placeholder implementation"
unimplemented!()
todo!()
2. Error Handling
Enforces proper error handling:
// ❌ FORBIDDEN
.unwrap() // except tests/bins with "// Safe:"
.expect() // except tests/bins with "// Safe:"
panic!() // except tests only
anyhow::anyhow!() // ZERO TOLERANCE
// ✅ REQUIRED
Result<T, E>
AppError or specific error types
thiserror::Error enums
3. Algorithm Isolation
Ensures formulas in algorithm modules:
// ❌ FORBIDDEN (hardcoded formula outside algorithms/)
let max_hr = 220.0 - age; // In random module
// ✅ CORRECT (enum-based DI)
let max_hr = MaxHrAlgorithm::Fox.calculate(age)?; // In algorithms/maxhr.rs
4. Architectural Patterns
Validates design patterns:
// ❌ FORBIDDEN (direct resource creation)
let auth = AuthManager::new(config); // Should use DI
// ✅ CORRECT (dependency injection)
pub struct MyService {
resources: Arc<ServerResources>, // Contains auth_manager
}
5. Code Quality
Checks for anti-patterns:
// ❌ String allocation anti-patterns
.to_string().as_str() // Unnecessary round-trip
String::from("text").as_str()
// ✅ Use &str directly
"text"
// ❌ Iterator anti-patterns
let mut vec = Vec::new();
for item in items {
vec.push(process(item));
}
// ✅ Use functional style
let vec: Vec<_> = items.iter().map(process).collect();
Pattern Validation Results
Expected Output (Success)
✓ No placeholder implementations found
✓ No unwrap/expect/panic in production code
✓ No anyhow::anyhow! usage (using structured errors)
✓ Algorithm formulas properly isolated
✓ Resource creation uses dependency injection
✓ Unsafe code limited to approved files
✓ No development artifacts (TODO/FIXME)
✓ Clone usage within threshold (600 max)
ARCHITECTURAL VALIDATION: PASSED
Failure Example
❌ Found 3 placeholder implementations:
src/new_feature.rs:45: "stub implementation"
src/new_feature.rs:67: "TODO: Implementation"
❌ Found 2 unwrap() calls in production:
src/routes/new_endpoint.rs:123: .unwrap()
src/services/processor.rs:89: .unwrap()
❌ Found 1 anyhow::anyhow! usage (FORBIDDEN):
src/error_handler.rs:56: anyhow::anyhow!("Error")
❌ Found hardcoded formula:
src/intelligence/new_module.rs:34: 220.0 - age
ARCHITECTURAL VALIDATION: FAILED
6. SQL Injection Detection
Catches format!() used to build SQL queries:
# Check for format! SQL construction (FORBIDDEN per CLAUDE.md Security Rules)
echo "🛡️ Checking for format! SQL injection risks..."
rg "format!\(.*(?:SELECT|INSERT|UPDATE|DELETE|CREATE|DROP|ALTER)" src/ --type rust -n && \
echo "❌ SECURITY: format! used in SQL query construction!" || \
echo "✓ No format! SQL injection risks"
# Verify all SQL uses parameterized queries
rg "sqlx::query(?:_as|_scalar)?\(" src/ --type rust -n | wc -l
echo "Parameterized query count (safe)"
7. HTML Template Safety
Catches unescaped user input in server-rendered HTML:
# Check for raw string interpolation in HTML output
echo "🛡️ Checking HTML template safety..."
rg "format!\(.*<.*>.*\{" src/ --type rust -n | \
rg -v "html_escape|encode_text" && \
echo "⚠️ Potential XSS: HTML with unescaped interpolation" || \
echo "✓ HTML output properly escaped"
# Verify html_escape usage
rg "html_escape::encode_text|html_escape::encode_double_quoted_attribute" src/ --type rust -n | wc -l
echo "HTML escape function calls (safe)"
8. Tenant Isolation in Non-DB Code
Catches global/shared state that should be per-tenant:
# Check for global OAuth config (should be per-tenant)
echo "🛡️ Checking tenant isolation in non-DB code..."
rg "static.*OAuth|static.*Config|LazyLock.*OAuth" src/ --type rust -n | \
rg -v "test|DEFAULT" && \
echo "⚠️ Global OAuth/Config state (should be per-tenant)" || \
echo "✓ No global OAuth/Config state"
Success Criteria
- ✅ Zero placeholder implementations
- ✅ Zero unwrap/expect/panic in src/ (except approved)
- ✅ Zero anyhow::anyhow! usage
- ✅ All algorithms use enum-based DI
- ✅ All resources use dependency injection
- ✅ Unsafe code only in approved files (src/health.rs)
- ✅ Clone count under threshold (600)
- ✅ No hardcoded secrets
- ✅ No development artifacts (TODO/FIXME) in src/
- ✅ No format!() SQL query construction (injection risk)
- ✅ No unescaped HTML interpolation (XSS risk)
- ✅ No global OAuth/Config state (tenant isolation risk)
Related Files
scripts/ci/architectural-validation.sh- Main validation scriptscripts/ci/validation-patterns.toml- Pattern definitions (539 lines)scripts/ci/parse-validation-patterns.py- Pattern parser.claude/CLAUDE.md- CLAUDE.md standards
Related Skills
strict-clippy-check- Code quality lintingcheck-no-secrets- Secret detectiontest-multitenant-isolation- Security validation
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?