# Harness Design Review > This skill should be used to run a structured multi-dimension code review of any software project. Evaluates architecture fitness, maintainability, testability, security, observability, and deployment readiness using harness engineering principles. Use before major refactors, after large PRs, when onboarding to a module, or as a periodic full-codebase fitness check. - **Type:** Skill - **Install:** `agentstack add skill-microstone88-claude-harness-skills-harness-design-review` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [microstone88](https://agentstack.voostack.com/s/microstone88) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [microstone88](https://github.com/microstone88) - **Source:** https://github.com/microstone88/claude-harness-skills/tree/main/harness-design-review ## Install ```sh agentstack add skill-microstone88-claude-harness-skills-harness-design-review ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 ```bash # 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) 3. **Error path coverage** — Check that `catch` branches and guard/else paths have corresponding test cases 4. **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 ```bash # 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](https://github.com/microstone88) - **Source:** [microstone88/claude-harness-skills](https://github.com/microstone88/claude-harness-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-microstone88-claude-harness-skills-harness-design-review - Seller: https://agentstack.voostack.com/s/microstone88 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.