edit-lint-feedback-loop

Edit → Lint Feedback Loop

The mechanical heart of the harness. Explains what happens between "Claude writes a file" and "Claude sees the lint violation on the next turn".

The full flow

1. Claude calls: Write({ file_path: "src/user.ts", ... })
                             │
2. Claude Code triggers PreToolUse hook
                             │
3. pre-tool-use.sh reads stdin once, fans out to:
   ├─ pre-config-protect.js  (exits 2 if biome.json/tsconfig/etc.)
   └─ pre-bash-firewall.js   (only relevant for Bash tool)
                             │
4. If no block → Claude Code executes Write → file is written to disk
                             │
5. Claude Code triggers PostToolUse hook with the same payload
                             │
6. post-tool-use.sh reads stdin once, fans out to:
   └─ post-edit-lint.js
                             │
7. post-edit-lint.js:
   ├─ Routes by file extension:
   │  ├─ .ts/.tsx → runTypeScript()
   │  ├─ .go      → runGo()
   │  └─ .proto   → runProto()
   ├─ Each runner:
   │  ├─ Silent auto-fix (biome format, oxlint --fix, gofumpt -w, buf format -w)
   │  ├─ Collect remaining violations (oxlint, golangci-lint, buf lint, buf breaking)
   │  └─ Return { file, tool, output } if violations remain
   └─ Aggregate → createHookOutput(message)
                             │
8. Hook writes JSON to stdout:
   {
     "hookSpecificOutput": {
       "hookEventName": "PostToolUse",
       "additionalContext": "# harness-engineering: lint/format violations\n..."
     }
   }
                             │
9. Claude Code injects additionalContext into the next assistant turn
                             │
10. Claude reads the violations in its next thinking step and fixes them.

Total latency target: under 3 seconds. The Rust-based tools (Biome, Oxlint, gofumpt, buf) are all sub-second. golangci-lint --fast mode is ~200–500ms on a single file. The bottleneck is Node.js startup for the hook itself (~80ms).

Why PostToolUse and not PreToolUse?

PreToolUse sees the intended write but the file on disk is still the old version. Running a linter at PreToolUse would either:

• Lint the old file (wrong answer, stale)
• Write a temp file, lint that, then allow or block (complex, slow)

PostToolUse runs after the write is committed to disk, so the linter sees the actual new content. If violations remain, we feed them back via additionalContext. No blocking — just feedback. Claude naturally fixes the issues on its next turn.

Why additionalContext instead of stderr?

Claude Code's PostToolUse hooks can emit JSON with hookSpecificOutput.additionalContext. This string is automatically included in Claude's context for the next assistant turn, like a system-level nudge.

Alternative: write to stderr and hope Claude sees it. This works but is less reliable — stderr sometimes goes to logs, sometimes to the transcript, depending on the Claude Code version. additionalContext is the documented, stable mechanism.

Adding a new language

Suppose you want to add Python support. Steps:

1. Add the runner to hooks/post-edit-lint.js

function runPython(fp, log) {
  // 1. Auto-format with Ruff
  if (commandExists('ruff')) {
    runCommand('ruff', ['format', fp], { timeout: 3000 });
  }
  // 2. Auto-fix with Ruff
  if (commandExists('ruff')) {
    runCommand('ruff', ['check', '--fix', fp], { timeout: 3000 });
  }
  // 3. Collect remaining violations
  const res = runCommand('ruff', ['check', fp], { timeout: 5000 });
  if (res.status === 0) return null;
  return {
    file: fp,
    tool: 'ruff',
    output: (res.stdout + res.stderr).trim().slice(0, 3000),
  };
}

2. Wire into the router

case '.py': {
  const v = runPython(fp, log);
  if (v) violations.push(v);
  break;
}

3. Add protected config files to hook-utils.js

// PROTECTED_CONFIG_BASENAMES
'pyproject.toml',
'ruff.toml',
'.ruff.toml',

4. Add a new skill: skills/python-stack/SKILL.md

Model it on go-stack/SKILL.md.

5. Add a template: templates/review-profile.python.yaml

6. Update _meta/manifest.yaml

Done. No changes to the hook runner scripts or config schema needed.

Debugging

Hook doesn't fire at all

# Check Claude Code logs
tail -f ~/.claude/logs/hook-*.log

# Manually invoke the hook
echo '{"tool_name":"Write","tool_input":{"file_path":"src/test.ts"}}' \
  | bash ~/.claude/plugins/harness-engineering/hooks/post-tool-use.sh

Hook fires but no feedback shown

• Check: is the file path under a skip pattern (node_modules, dist, vendor)?
• Check: does the file have a "Code generated ... DO NOT EDIT" header? Those are skipped.
• Check: is the relevant linter installed (biome, oxlint, gofumpt, buf)?

Hook is slow

• Run with time: time (echo '...' | bash hooks/post-tool-use.sh)
• Most common cause: golangci-lint run without --fast mode. Always use --fast in the hook.
• Second most common: trying to invoke tsc --noEmit on the whole project. Never do that in PostToolUse. Leave tsc for lefthook pre-commit.

Key learnings

• Silent failure philosophy: every branch that could throw has || true or a try/catch. A broken hook should never block Claude.
• Rust-based linters are non-negotiable: ESLint (Node) takes 500ms+ startup. Oxlint takes <50ms. That's the difference between "feels instant" and "feels laggy".
• Don't run expensive linters per-file in PostToolUse: gosec, knip, full tsc, buf breaking against remote → all belong in lefthook pre-commit or CI.
• Feedback loops compound: fast feedback means Claude iterates faster, which means better code sooner, which means less human review time.

Related Skills

• config-protect — the other half of the harness
• ts-stack, go-stack, proto-stack — per-language specifics

Gotchas

See gotchas.md.