claude-harness
Set up and diagnose AI harness environments for any project — guardrails, context, and workflows that help Claude work effectively.
What is a Harness?
A harness is the structured environment that helps AI agents work safely and effectively in your codebase. It combines three layers:
| Layer | Purpose | Examples |
|---|
| Guardrails | Prevent destructive actions | git push --force blocking, DROP TABLE detection, permission modes |
| Context | Give AI the knowledge it needs | CLAUDE.md project map, glob-targeted rules, tech stack awareness |
| Workflows | Structure common tasks | /start-task for planning, /review for verification, /session-wrap for learning |
Without a harness, AI agents operate with generic defaults — no awareness of your project's conventions, no safety nets for dangerous operations, no structured process for complex tasks.
With a harness, they become effective team members that follow your project's patterns, plan before coding, and improve over time.
Why claude-harness?
The problem: Setting up CLAUDE.md, rules, hooks, and commands from scratch is tedious and error-prone. Most teams either skip it entirely or over-engineer it with rules that quickly go stale.
The solution: claude-harness provides two commands:
/harness-setup — An interactive wizard that analyzes your project, asks the right questions, and generates a tailored harness in minutes/harness-check — A diagnostic tool that audits your existing harness across 6 axes and identifies what to add, improve, or remove
"Every component of a harness encodes an assumption about what the model can't do on its own.
Those assumptions go stale fast as models improve." — Anthropic Engineering
claude-harness is designed around this insight: a good harness evolves. It adds constraints when needed and removes them when outgrown.
Important: A Foundation, Not a Finished Product
claude-harness builds the foundation. You carve the details.
This plugin generates a baseline harness — a solid starting point with sensible defaults for any project. But every project has its own domain, conventions, team dynamics, and risk profile. The generated rules, commands, and hooks are generic scaffolding that gets you from zero to functional in minutes.
The real value comes from what you do next:
- Refine the rules to match your actual coding conventions, not just generic best practices
- Adjust the hooks to block the dangerous commands specific to your infrastructure
- Customize the commands to fit your team's workflow (PR process, deploy pipeline, review cadence)
- Add domain-specific rules that only your project needs (e.g., data pipeline conventions, compliance requirements)
- Remove what doesn't apply — a Python project doesn't need TypeScript rules, a solo project doesn't need team approval workflows
Think of it like a house frame: claude-harness gives you the structure, but the interior design is yours. The more you tailor it to your project, the more effective your AI collaboration becomes.
The 6-Axis Framework
claude-harness evaluates and builds your project's AI environment across six axes:
┌─────────────┐
│ Structure │ ← Folder layout, permissions, safety hooks
└──────┬──────┘
│
┌────────────┼────────────┐
│ │ │
┌──────┴──────┐ │ ┌───────┴──────┐
│ Context │ │ │ Planning │
└──────┬──────┘ │ └───────┬──────┘
│ │ │
│ ┌──────┴──────┐ │
└────►│ Execution │◄────┘
└──────┬──────┘
│
┌────────────┼────────────┐
│ │
┌──────┴───────┐ ┌───────────┴──┐
│ Verification │ │ Compounding │
└──────────────┘ └──────────────┘
