Skip to content

feat: Claude harness — parallel review team + dev workflow - #4

Merged
nimrod-teich merged 1 commit into
mainfrom
feat/claude-harness
Apr 18, 2026
Merged

nimrod-teich merged 1 commit into
mainfrom
feat/claude-harness

Conversation

@nimrod-teich

Copy link
Copy Markdown
Contributor

Summary

Adds a .claude/ configuration to the repo that wires up a 6-agent team
for code review and code development. On any review or implementation
request, four reviewers (architecture, security, performance, style)
run in parallel and a synthesizer merges their findings into one
prioritised report.

What's in the harness

Agents (all model: opus):

  • architect-reviewer — module boundaries, dependency direction, concurrency ownership, transaction discipline
  • security-auditor — SQL injection (pgx), secret leakage, authz, input validation, TLS/crypto, container hardening
  • performance-analyst — hot-path allocations, goroutine leaks, pgx pool sizing, CopyFrom vs. loop-insert, retry amplification, indexer-specific concerns (batch sizing, AIMD tuning, dead-letter amplification, range fragmentation)
  • style-reviewer — Go idioms, naming, comments, project conventions inferred from existing code
  • report-synthesizer — lead; dedupes, re-ranks by severity, writes the consolidated report
  • implementer — writes new code for the dev workflow (used only by code-development)

Skills:

  • code-review — main review orchestrator (fan-out + synth)
  • code-development — dev orchestrator (implement → review the diff)
  • architecture-review, security-audit, performance-analysis, style-review — per-reviewer methodology + a dedicated reference doc with Go/pgx/Docker checklists calibrated to this codebase
  • finding-synthesis — shared finding schema, strict severity ladder, merge rules

Pattern: fan-out / fan-in.

  • Reviewers run in parallel, each writing _workspace/{category}_findings.md
  • Synthesizer reads all four, dedupes by file:line, re-ranks, emits _workspace/report.md
  • Previous runs are preserved as _workspace_prev_{timestamp}/

Key design choices

  • Findings are markdown, not JSON. Easier to write and read; schema is structural (headers + bullets).
  • Severity is strict. critical is reserved for exploit / data loss / outage on the live path. The severity guide in .claude/skills/finding-synthesis/references/severity-guide.md is the single source of truth that both reviewers and the synth apply.
  • Reviewers don't cross-talk. Four independent findings files; the synth catches cross-cutting concerns in its own section rather than via inter-reviewer messaging.
  • Implementer stages, never commits. The user decides when to commit, push, or PR. Iterative rounds (fix findings + re-review) are capped at 3 to avoid infinite loops.
  • Trigger descriptions are pushy. Each skill's `description` field lists the request phrasings that should invoke it, including iterative ones ("review again", "only the security part"). CLAUDE.md also explicitly calls out when NOT to use the harness (quick questions, terraform changes, urgent hotfix).

Directory layout

CLAUDE.md                          ← future sessions load this automatically
.claude/
├── agents/                        ← 6 agent definitions
└── skills/
    ├── code-review/               ← review orchestrator + scope-resolution ref
    ├── code-development/          ← dev orchestrator (wraps review)
    ├── architecture-review/       ← + go-architecture-patterns.md
    ├── security-audit/            ← + go-security-checklist.md
    ├── performance-analysis/      ← + go-performance-patterns.md
    ├── style-review/              ← + go-style-and-project-conventions.md
    └── finding-synthesis/         ← + finding-schema.md + severity-guide.md

Test plan

  • New session: ask Claude "review the changes in PR feat: honest gap accounting + in-run dead-letter retry + tip-first interleave #3 against main" — confirm the code-review skill triggers, four reviewers fan out, synth produces a report
  • Re-run single reviewer: "rerun only the security review" — confirm partial re-run path works (keeps other findings, re-runs security + synth)
  • Dev workflow: "implement a stub handler for lava_delegator_reward and review it" — confirm implementer runs first, then review runs on the diff
  • Empty scope: "review my changes" on a clean working tree — confirm orchestrator stops and asks
  • Quick question: "what does `processWithSplit` do?" — confirm Claude answers directly without invoking the harness (per CLAUDE.md's "when NOT to use" section)

Adds a .claude/ configuration with:
- 6 agents (architect, security, performance, style, synth, implementer),
  all pinned to opus
- 7 skills — 2 orchestrators (code-review, code-development) plus 5
  domain skills, each with its own references/ for Go + pgx + indexer
  checklists
- Finding-synthesis skill with a shared markdown finding schema and a
  strict severity ladder so the four parallel reviewers produce merge-
  able output
- Fan-out / fan-in pattern: the four reviewers run in parallel, each
  writes _workspace/{category}_findings.md, synthesizer merges into
  _workspace/report.md
- CLAUDE.md at repo root describing the harness, trigger rules,
  directory layout, and when NOT to use it

Triggers the harness for requests like 'review this', 'audit this PR',
'implement X and review it', etc. Simple questions bypass the harness
and are answered directly.
@nimrod-teich
nimrod-teich merged commit 701272a into main Apr 18, 2026
1 check passed
@nimrod-teich
nimrod-teich deleted the feat/claude-harness branch April 18, 2026 16:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant