Harness Design Review

Harness Design Review

To audit any software project, apply Harness Engineering principles. A harness is the system of constraints, context, and verification that keeps code safe, correct, and evolvable. This skill runs a structured multi-dimension review and produces a scored report with actionable findings.

> Definition: A harness consists of two control mechanisms: > - Guides (Feedforward): Steer work before it happens — conventions, architecture docs, linting rules, CLAUDE.md, templates > - Sensors (Feedback): Detect drift after the fact — tests, CI gates, static analysis, code review, custom scripts

> Reference: Martin Fowler — "Harness Engineering for Coding Agents" / Ford, Parsons, Kua — "Building Evolutionary Architectures" (fitness function-driven development)

---

When to Invoke

/harness-design-review                    # Full codebase review
/harness-design-review src/auth           # Scoped to a module
/harness-design-review --quick            # Architecture + Security only (5 min)

---

The 6 Dimensions

Full dimension checklists are in [references/dimensions.md](references/dimensions.md).

| Dimension | What It Measures | Guides | Sensors | |-----------|-----------------|--------|---------| | Architecture Fitness | Layering, DI patterns, module boundaries, concurrency contracts | Architecture docs, naming conventions | Structural linting, import analysis | | Maintainability | Naming, complexity, documentation, dead code | Style guides, complexity limits | Static analysis (cyclomatic complexity, duplication) | | Behavior / Testability | Test coverage, test quality, error path coverage, contract observability | TDD workflow, test patterns | Coverage tools, CI gate on coverage % | | Security | Secrets management, input validation, auth patterns, dependency CVEs | Secure coding guidelines | SAST, dep scan, secret scanner | | Observability | Structured logging, distributed tracing, metrics, alerting | Logging conventions | Log format linting, trace coverage check | | Deployment Fitness | CI/CD pipeline, rollback capability, feature flags, DORA proxy metrics | Deployment runbook | Pipeline audit, rollback test |

---

How to Run This Review

Step 0: Scope

If an argument was provided (path or module name), scope all phases to that subtree. Otherwise default to the full source tree and test tree.

Step 1: Architecture Fitness

Read any architecture documentation (CLAUDE.md, CONVENTIONS.md, ARCHITECTURE.md, README.md, or equivalent). Then verify:

1. Layer boundaries — ViewModels/controllers do not import view-layer types directly; services accessed through protocols/interfaces, not concrete singletons
2. Dependency injection — Protocol-based DI used for all testable dependencies; no service locator anti-pattern
3. File/module size discipline — Flag files exceeding the project's stated size limit (default: >300 lines indicates missing decomposition)
4. Circular dependencies — Check for circular imports across modules
5. Single responsibility — Each file/class has one clear responsibility; flag files mixing concerns

# Find largest files (adapt path and extension)
find src/ -name "*.ts" -exec wc -l {} + | sort -rn | head -20
# Or for Swift, Python, Go, Java, etc. — change the extension

Output: List of violations with file:line references and severity (CRITICAL / HIGH / MEDIUM / LOW).

---

Step 2: Maintainability

Spot-check 10 files across the codebase for:

1. Naming conventions — Consistent with the project's stated convention (camelCase, snake_case, PascalCase, etc.); no single-letter variables outside closures/lambdas
2. Complexity hotspots — Functions with deep nesting (>3 levels) or long parameter lists (>5 params) or cyclomatic complexity >10
3. Comment quality — Non-obvious logic has inline comments; API boundaries have doc comments; no redundant comments restating what code already says
4. Dead code — Unused private functions, commented-out code blocks, unreferenced exports
5. Error handling — catch blocks do not silently swallow errors; error context is preserved and logged

Output: Maintainability score 0–10 with top 5 specific findings.

---

Step 3: Behavior / Testability

1. Coverage scan — Identify major classes/modules in scope. For each, check whether a corresponding test file exists
2. Test quality — Spot-check 3–5 test files for:

• Uses the project's test framework assertions (not print / manual inspection)
• No sleep() / polling in async tests — uses proper async testing primitives
• Mocks/stubs are interface-based, not inheritance-based where possible
• Tests are deterministic (no reliance on wall clock or uncontrolled external state)

1. Error path coverage — Check that catch branches and guard/else paths have corresponding test cases
2. Integration vs unit isolation — Verify unit tests do not make real network calls; integration tests are gated behind explicit configuration

Output: Coverage gap table (module → has tests: yes/no) + test quality issues found.

---

Step 4: Security

1. Secrets discipline — No API keys, tokens, or credentials hardcoded in source files; secrets stored in environment variables, vault, or gitignored config files
2. Dependency CVEs — Run dependency audit (npm audit, pip audit, bundle audit, govulncheck, etc.)
3. Input validation — User-supplied input validated/sanitized before use in queries, commands, or external API calls; parameterized queries for any database access
4. Authentication/authorization — Auth state verified before protected operations; no auth bypass paths
5. Network security — All external calls use HTTPS/TLS; no allowArbitraryLoads or verify=False in production paths

# Generic secret pattern scan (adapt to your codebase)
grep -rn "sk-\|AIza\|Bearer \|api_key\s*=\|password\s*=" src/ | grep -v "test\|mock\|example\|template" | head -20

Output: Security findings with OWASP category tags where applicable.

---

Step 5: Observability

1. Structured logging — Logs are structured (JSON or key-value pairs), not bare print/console.log strings; log levels used correctly (debug vs info vs warn vs error)
2. Trace coverage — Distributed trace IDs propagated across service/async boundaries; no "blind spots" in request flows
3. Metrics/dashboards — Key business and technical metrics instrumented (request rate, error rate, latency); at least one dashboard exists for production monitoring
4. Alerting — Alerts exist for error rate spikes, latency degradation, and critical business events
5. Correlation IDs — Request IDs propagated through all logs for a given user action

Output: Observability score 0–10 with gaps identified.

---

Step 6: Deployment Fitness

Evaluate against DORA proxy metrics and pipeline completeness:

| Check | Present? | Notes | |-------|----------|-------| | CI runs on every PR | | | | All tests run in CI (not just unit) | | | | Linting / static analysis in CI | | | | Automated deployment to staging | | | | Rollback mechanism documented and tested | | | | Feature flags for risky changes | | | | Zero-downtime deployment supported | | | | Dependency vulnerability scan in CI | | |

Output: Deployment fitness score 0–10.

---

Step 7: Harness Fitness Gaps

Identify what automated enforcement is missing — constraints that exist only as conventions but aren't machine-verified. For each gap, recommend a concrete guide (feedforward) or sensor (feedback) to close it.

Use the 11 Engineering Excellence Pillars as a checklist scaffold. Full checklist in [references/dimensions.md](references/dimensions.md).

---

Step 8: Write the Report

HARNESS DESIGN REVIEW REPORT
=============================
Scope: [path or "full codebase"]
Date:  [today]
Project: [project name]

DIMENSION SCORES
----------------
Architecture Fitness:  [0-10]
Maintainability:       [0-10]
Behavior Coverage:     [0-10]
Security:              [0-10]
Observability:         [0-10]
Deployment Fitness:    [0-10]
Overall:               [0-10]

CRITICAL (fix before next PR)
------------------------------
1. [file:line] Description — why it matters

HIGH (fix this sprint)
----------------------
1. ...

MEDIUM (fix within 2 sprints)
------------------------------
1. ...

LOW / IMPROVEMENTS
------------------
1. ...

TOP 3 MISSING HARNESS MECHANISMS
----------------------------------
1. [Guide/Sensor] What to add and why
2. ...
3. ...

---

Quick-Run Mode

For a fast 5-minute spot check (architecture + security only):

/harness-design-review --quick [optional path]

Runs only Phase 1 (Architecture) and Phase 4 (Security). Produces a condensed findings list.

---

Overall Health Brackets

| Score | Meaning | |-------|---------| | ≥8.0 | Production-hardened codebase | | 6.0–7.9 | Solid foundation, specific gaps to address | | 4.0–5.9 | Significant gaps, delivery risk | | <4.0 | Pre-production quality, major structural work required |

---

Integration with Other Skills

| Finding | Next Step | |---------|-----------| | CRITICAL architecture violations | Add missing tests with everything-claude-code:tdd-workflow | | Security findings | Deep audit with everything-claude-code:security-review | | Maintainability score <7 | Dead code cleanup with everything-claude-code:refactor-cleaner | | Harness fitness gaps | Add enforcement hooks with update-config | | AI feature in scope | Cross-run with agent-harness-review for runtime harness quality |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: microstone88
• Source: microstone88/claude-harness-skills
• License: MIT

Install and usage instructions live in the source repository linked above.