serena

autonomous-dev — A Development Harness for Claude Code

A harness that wraps Claude Code with enforcement, specialist agents, and alignment gates to deliver consistent, production-grade software engineering outcomes.

A harness is the software and structure that wraps an AI model to keep it on track — the prompts, tools, feedback loops, constraints, and validation that turn a capable but undisciplined model into a reliable system. Without a harness, the model is a wild horse with raw power but no direction. With one, that power is controlled, directed, and accountable.

What Is This?

The problem: Claude Code is brilliant at execution but unreliable at process. It skips tests, declares "good enough" on failing code, bypasses security reviews, and drifts from your project's intent. Not out of malice — it's trained to complete tasks, not follow engineering discipline. Prompt-level instructions ("please run tests") get ignored under context pressure.

The solution: autonomous-dev is a harness that enforces the full software development lifecycle:

1. You define your project in a file called PROJECT.md - your goals, what's in/out of scope, constraints, architecture
2. You track work in GitHub Issues - each feature or bug is an issue
3. You run one command - /implement "#72"
4. Claude executes a full development pipeline - research, planning, acceptance tests, implementation, code review, security scan, documentation
5. Claude stays aligned - if a feature doesn't fit your PROJECT.md scope, it's blocked before any code is written

In short: You define the rules once. The harness enforces them for every feature.

What Does It Actually Do?

When you type /implement "#72", Claude coordinates specialist agents through a 15-step pipeline (the default full mode). The step numbers below are the real STEP N/15 ids you'll see in the run output and logs:

One command. Full software development lifecycle. Aligned to your project.

Why Use This?

Without a harness:

• You ask Claude to build a feature
• Claude makes assumptions about your architecture
• It skips tests when context gets long (context anxiety)
• It approves its own work as "good enough" (poor self-evaluation)
• You review the code, find issues, ask for fixes
• Repeat until it's acceptable
• Hope you didn't introduce security issues

With autonomous-dev:

• You define your project once (PROJECT.md)
• You create a GitHub issue for each feature
• You run /implement "#X"
• The harness enforces every step — research, planning, testing, implementation, adversarial review, security audit, documentation
• You review a complete, tested, documented, security-scanned result

The difference: Claude stops guessing. The harness keeps it honest.

Four-Layer Harness Architecture

autonomous-dev enforces process through four layers, each addressing a different failure mode — enforce now, add intelligence, learn from the session, then evolve:

• 1. Hooks (deterministic enforcement) — Run on every tool call, commit, and prompt. Hard gates that can't be argued with: tests must pass with 0 failures before code review starts, no stubs or placeholders allowed, security scan is mandatory, documentation must stay in sync. Functional infrastructure (agents/, hooks/, lib/, commands/) is write-protected outside the pipeline, and a dispatch sentinel keeps the coordinator from directly editing those paths mid-pipeline — it must re-dispatch the implementer agent (#1296). These are the harness equivalent of guardrails — if the model tries to skip a step, it's physically blocked.

• 2. Agents (adversarial evaluation) — Each pipeline step is handled by a specialist agent with a specific job and constrained tools. The implementer never reviews its own work — a separate reviewer agent with a skeptical mandate evaluates it (generator/evaluator pattern). Skills power this layer: instead of stuffing every rule into context upfront, domain knowledge is injected progressively — testing standards load during test writing, security patterns during security review — keeping each agent focused within its current step.

• 3. Continuous Improvement (post-session, self-correcting) — Every session logs JSONL to .claude/logs/activity/. The continuous-improvement-analyst evaluates those logs against PROJECT.md + CLAUDE.md and emits structured finding records; /improve --auto-file promotes recurring findings into GitHub issues labeled auto-improvement. Runs asynchronously, never blocks active work. (This is the layer that, earlier today, caught this very session's gate mis-scopes and filed #1385/#1387/#1388.)

• 4. Autonomous Self-Improvement (closed-loop, evidence-driven) — /triage clusters the improvement queue by root cause → /drain-queue (and the scheduled cloud-drain) works it through /implement --issues behind safety guardrails → benchmarks gate whether a change is kept or reverted. Effectiveness benchmarks measure reviewer/agent accuracy; HIGH-confidence diagnoses are applied autonomously, the rest filed as issues.

The result: Every feature goes through every step — not because Claude remembers to, but because the harness won't let it skip — and the harness itself gets better every week from its own runtime data.

Recent Improvements

Substantial enforcement hardening shipped recently. Current focus areas:

• Mode- and intent-aware enforcement — hooks respect the active pipeline mode (full / light / fix / tdd-first) so a --light run isn't held to the full agent set, and an intent/session-mode classifier scopes the SDLC gates to actual software-development edits (not scratch/exploration/meta-work). The gate also short-circuits message-only git commit --amend — context-aware gating, not surface-signal gating
• Default-ON global enforcement — the SDLC gates fire in every repo by default, opt out per-repo with .claude/.bypass (Phase 1 polarity flip, #1142+/#1361)
• Autonomous operations loop — /triage clusters the open improvement queue by root cause, /drain-queue drains it through /implement --issues behind safety guardrails, and a scheduled cloud-drain runs the same loop unattended. Cross-machine issue claiming (a GitHub in-progress label + marker-comment mutex) stops a local run and the cloud drainer from racing the same cluster. /goa is a standing infra-health observer
• Planning workflow — 7-step /plan + adversarial plan-critic review (1-5 Likert, composite ≥3.0 → PROCEED)
• Session analytics — every conversation archived to ~/.claude/archive/ with a 17-column SQLite index
• Closed-loop self-improvement — benchmark → modify → re-benchmark → commit-or-revert (see EVALUATION.md)

See CHANGELOG.md for complete release-over-release details with issue references.

The 12 Elements of Harness Engineering

The core insight of harness engineering: reliability in multi-step AI workflows is difficult because failures compound. A 10-step process with 90% accuracy per step fails over 60% of the time. "Agent skills" that are just prompts or markdown files — where you hope the AI follows instructions — lack the dependability required for production work.

The solution is deterministic rails: a software layer that gates and validates every stage. autonomous-dev implements all 12 elements of this framework:

What's PROJECT.md?

A simple markdown file that defines your project. Example: