Harness Engineering

Mechanical constraints for AI agents. Ship faster without the chaos.

Why This Exists

AI coding agents are powerful, but unreliable without structure. Left unconstrained, they introduce circular dependencies, violate architectural boundaries, and generate drift that compounds across a codebase. Teams respond with code review backlogs and manual checklists — trading agent speed for human bottlenecks.

Harness Engineering takes a different approach: mechanical enforcement, not hope.

Instead of relying on prompts and conventions, harness encodes your architectural decisions as machine-checkable constraints. Agents get real-time feedback when they violate boundaries. Entropy is detected and cleaned automatically. Every rule is validated on every change.

For tech leads and architects: Scale AI-assisted development across your team with confidence. Define constraints once, enforce them everywhere — across agents, developers, and CI.

For individual developers: Stop babysitting your AI agent. Give it guardrails and let it execute. Spend your time on design decisions, not cleanup.

Key Features

• Context Engineering — Repository-as-documentation keeps agents grounded in project reality, not stale training data
• Architectural Constraints — Layered dependency rules enforced by ESLint, not willpower
• Agent Feedback Loop — Self-correcting agents with peer review and real-time validation
• Entropy Management — Automated detection of dead code, doc drift, and structural decay
• Implementation Strategy — Depth-first execution: one feature to 100% before the next begins
• Key Performance Indicators — Measure agent autonomy, harness coverage, and context density

Quick Start

# Install the CLI
npm install -g @harness-engineering/cli

# Scaffold a new project
harness init my-project

# Validate constraints
harness validate

Or explore an example directly:

git clone https://github.com/Intense-Visions/harness-engineering.git
cd harness-engineering/examples/hello-world
npm install && harness validate

Packages

Package	Description
@harness-engineering/types	Shared TypeScript types and interfaces
@harness-engineering/core	Validation, constraints, entropy detection, state management
@harness-engineering/cli	CLI: validate, check-deps, skill run, state show
@harness-engineering/eslint-plugin	5 rules: layer violations, circular deps, forbidden imports, boundary schemas, doc exports
@harness-engineering/linter-gen	Generate custom ESLint rules from YAML configuration
@harness-engineering/mcp-server	MCP server with 37 tools and 11 resources for AI agent integration
@harness-engineering/graph	Knowledge graph for codebase relationships and entropy detection

Architecture

Harness enforces a strict layered dependency model. Each layer may only import from layers below it.

graph TD
    A[agents] --> S[services]
    S --> R[repository]
    R --> C[config]
    C --> T[types]

    style A fill:#4a90d9,stroke:#2c5f8a,color:#fff
    style S fill:#50b86c,stroke:#2d7a3e,color:#fff
    style R fill:#f5a623,stroke:#c17d12,color:#fff
    style C fill:#9b59b6,stroke:#6c3483,color:#fff
    style T fill:#7f8c8d,stroke:#566573,color:#fff

Loading

Violations are caught at lint time via @harness-engineering/eslint-plugin — not at code review.

AI Agent Integration

Connect your AI coding agent to harness for real-time constraint validation:

# Configure MCP server for Claude Code and Gemini CLI
harness setup-mcp

This adds the harness MCP server to your AI client, giving it access to 37 tools (validation, entropy detection, skill execution, state management, code review, graph queries, and more) and 11 resources (project context, skills catalog, rules, learnings, state, graph, entities, relationships).

Manual setup:

Claude Code — add to .mcp.json in your project root:

{
  "mcpServers": {
    "harness": {
      "command": "npx",
      "args": ["@harness-engineering/mcp-server"]
    }
  }
}

Gemini CLI — add to .gemini/settings.json in your project root:

{
  "mcpServers": {
    "harness": {
      "command": "npx",
      "args": ["@harness-engineering/mcp-server"]
    }
  }
}

Then add your project directory to ~/.gemini/trustedFolders.json (Gemini ignores workspace MCP servers in untrusted folders):

{
  "/path/to/your/project": "TRUST_FOLDER"
}

Client	MCP Config Location	Additional Setup
Claude Code	.mcp.json	None
Gemini CLI	.gemini/settings.json	Add project to ~/.gemini/trustedFolders.json

What's Included

Component	Count	Description
Packages	7	Core library, CLI, ESLint plugin, linter generator, MCP server, graph, shared types
Skills	26	Agent workflows for TDD, execution, debugging, verification, planning, and more
Personas	6	Architecture enforcer, code reviewer, documentation maintainer, entropy cleaner, parallel coordinator, task executor
Templates	5	Base, basic, intermediate, advanced, and Next.js scaffolds
Examples	3	Progressive tutorials from 5 minutes to 30 minutes

Examples

Learn by doing. Each example builds on the previous:

Example	Level	Time	What You Learn
Hello World	Basic	5 min	Config, validation, AGENTS.md — see what a harness project looks like
Task API	Intermediate	15 min	Express API with 3-layer architecture enforced by ESLint
Multi-Tenant API	Advanced	30 min	Custom linter rules, Zod boundary validation, personas, full state lifecycle

Documentation

Getting Started

• Getting Started Guide — From zero to validated project
• Best Practices — Patterns for effective harness usage
• Agent Worktree Patterns — Running multiple agents in parallel

Core Concepts

• The Core Principles — Foundational concepts behind harness engineering
• Implementation Guide — Adoption levels and rollout strategy
• KPIs — Measuring agent effectiveness

API Reference

• CLI Reference — All commands and flags
• Configuration Reference — harness.config.json schema

Contributing

See CONTRIBUTING.md for development setup, coding standards, and pull request guidelines.

License

MIT License — see LICENSE for details.