Harness Optimizer

Harness Optimizer

Diagnose and improve your Claude Code harness configuration based on 8 design principles from Anthropic's "Harness design for long-running application development." This skill scans your project's plugin components, grades each principle with a 2-layer diagnostic (signal collection + semantic judgment), and offers tiered auto-fixes.

Flag Parsing

Parse $ARGUMENTS for these flags:

Workflow

Phase 0: Setup

1. Detect language from user message or system locale (Korean/English)
2. Resolve target path from --path flag or current working directory
3. Check minimum requirements:
   • Look for CLAUDE.md OR .claude/ directory in the target path
   • If neither exists, display an informative message (not an error) and exit gracefully:

     "This project doesn't appear to have a Claude Code configuration (no CLAUDE.md or .claude/ directory found). Create a CLAUDE.md to get started, then run this diagnostic again."

4. Scan components using scripts/scan-components.mjs:

   node "$(dirname "$SKILL_PATH")/scripts/scan-components.mjs" "<target_path>"
   

   If Node.js is unavailable, fall back to manual scanning with Glob:
   • Glob("skills/*/SKILL.md") and Glob(".claude/skills/*/SKILL.md")
   • Glob("agents/*.md") and Glob(".claude/agents/*.md")
   • Glob("commands/*.md") and Glob(".claude/commands/*.md")
   • Glob("hooks/*") and check for hooks.json
   • Check existence of plugin.json, CLAUDE.md, .mcp.json, .claude/settings.json
5. Determine project type: isPlugin = true if plugin.json exists
6. If --help flag is present, display usage and exit

Phase 1: Component Discovery

Present the scan results to the user:

## Project Scan Results

| Component | Count | Detected |
|-----------|-------|----------|
| Skills | {n} | {paths} |
| Agents | {n} | {paths} |
| Commands | {n} | {paths} |
| Hooks | {n} | {paths} |
| plugin.json | {yes/no} | |
| CLAUDE.md | {yes/no} | {line count} |
| .mcp.json | {yes/no} | |
| settings.json | {yes/no} | |

**Project type:** {Plugin / Non-plugin (CLAUDE.md + .claude/)}
**Total components:** {n}

If isPlugin=false, note that plugin-specific diagnostics (plugin.json analysis) will be skipped.

Phase 2: Principle Diagnostics (2-Layer)

For each of the 8 principles, perform a 2-layer diagnostic. Read references/principles-checklist.md for the detailed check logic for each principle.

Layer 1 — Signal Collection:

• Run the Grep/Glob patterns specified in references/principles-checklist.md for the current principle
• Record all matches as a signal list (file path, line number, matched content)
• DO NOT make any PASS/FAIL/PARTIAL judgment at this layer — collect signals only

Layer 2 — Semantic Judgment:

• Read the actual content of files identified in Layer 1 signals
• Apply the Layer 2 judgment guidelines from references/principles-checklist.md
• Determine: PASS (7-10), PARTIAL (3-6), or FAIL (0-2) with specific evidence
• A keyword match alone is never sufficient for PASS. The principle must be meaningfully implemented.

The 8 Principles:

Phase 3: Health Report

Present the diagnostic results:

## Harness Health Report

| # | Principle | Status | Score | Weight | Weighted | Evidence |
|---|-----------|--------|-------|--------|----------|----------|
| 1 | Evaluator Separation | {PASS/FAIL/PARTIAL} | {0-10} | 20% | {s*w} | {brief evidence} |
| ... | ... | ... | ... | ... | ... | ... |
| | **Health Score** | | | | **{total}/100** | |
| | **Grade** | | | | **{grade}** | |

Grade scale: Excellent (80-100), Good (60-79), Fair (40-59), Poor (20-39), Critical (0-19)

Calculate health score inline:

Health Score = (P1×0.20 + P2×0.15 + P3×0.15 + P4×0.10 + P5×0.10 + P6×0.07 + P7×0.08 + P8×0.15) × 10

Refer to references/scoring-system.md for score ranges and grade definitions.

Save a Before snapshot in memory (do not write to file):

{
  "timestamp": "<ISO 8601>",
  "scores": [{"principle": "<id>", "status": "<PASS|FAIL|PARTIAL>", "score": 8, "evidence": ["..."]}],
  "healthScore": 72.5,
  "grade": "Good",
  "componentCount": 12,
  "isPlugin": true
}

If --report-only flag is set, stop here.

Phase 4: Auto-Fix Tier 1 (Existing File Modifications)

Read references/autofix-catalog.md for the specific Tier 1 fixes for each FAIL/PARTIAL principle.

Tier 1 fixes modify existing files only (prompts, settings, configuration). They do not create new files.

1. Collect all applicable Tier 1 fixes based on FAIL/PARTIAL results
2. Present them to the user with AskUserQuestion:

   "Found {n} Tier 1 improvements (existing file modifications). Apply all / Select individually / Skip?"

3. If --dry-run, show proposed diffs without applying
4. Apply approved changes using Edit tool

Phase 5: Auto-Fix Tier 2 (New File Creation)

Read references/autofix-catalog.md for Tier 2 fixes.

Tier 2 fixes create new files (agents, hooks, skill templates). These always require explicit user confirmation.

1. Collect applicable Tier 2 fixes
2. Present each with a preview of what will be created:

   "Tier 2: Create evaluator agent template at agents/evaluator.md? [Preview below]"

3. If --dry-run, show file contents that would be created without creating them
4. Create approved files using Write tool
5. For complex skill creation, suggest: "For a full-featured skill, consider using /skill-creator"

Phase 6: Verification

1. Re-run a lightweight Phase 2 diagnostic (only for principles that had fixes applied)
2. Generate an After snapshot in the same schema as Phase 3
3. Present Before/After comparison:

## Before/After Comparison

| Principle | Before | After | Change |
|-----------|--------|-------|--------|
| Evaluator Separation | FAIL (2) | PARTIAL (5) | +3 |
| ... | ... | ... | ... |
| **Health Score** | **{before}** | **{after}** | **{delta}** |
| **Grade** | **{before}** | **{after}** | |

Reference Files

• references/principles-checklist.md — Detailed 2-layer diagnostic logic for each principle: Layer 1 Grep/Glob patterns and Layer 2 semantic judgment guidelines. Read the relevant principle section during Phase 2.
• references/scoring-system.md — Score ranges (PASS 7-10, PARTIAL 3-6, FAIL 0-2), weight table, health score formula, and grade definitions.
• references/autofix-catalog.md — Tier 1 and Tier 2 fix catalog with Before/After examples for each principle. Read during Phase 4/5.
• references/harness-article-summary.md — Key insights from the original Anthropic article, organized by principle. Useful for explaining WHY each principle matters to the user.