How a "Semi-Automatic Review" Harness Stabilized My Claude Code Workflow

1. The Conclusion

Claude Code, used as-is, is unstable. 👉 But once you wire reviews in as a structure, it stabilizes dramatically.

2. The Familiar Pain

• The code looks plausible.
• But the structure is a mess.
• File splits are sloppy.
• The same logic gets duplicated.
• Self-review always says “looks fine.”

👉 Exactly how a junior human engineer behaves.

3. The Real Problem

The problem is not the prompt.

The problem is trying to guarantee quality with the AI alone.

👉 The fix is harness design.

4. What I Did (Very Simple)

When I say “review it,” 👉 a review is forced to run, by design.

5. The Whole Picture

Normal mode
  ↓
(development)
  ↓
"review it"
  ↓
Review-only mode triggers
  ↓
Structural checks
  ↓
Fix instructions

👉 That’s all there is to it.

6. The Implementation Core

▸ ① ADR Locks Down the Rules

docs/harness/adr/0001-review-mode.md

• Review viewpoints
• Judgment criteria (definition / NG / OK)
• Security rules

👉 Think of it as the “constitution.”

▸ ② CLAUDE.md Defines the Trigger

review

👉 This switches modes.

▸ ③ Templates Lock Down the Output

docs/harness/templates/review-template.md

👉 Prevents review drift.

▸ ④ Save the Reports

docs/harness/reports/

👉 Quietly important — for preventing recurrence.

7. Why I Didn’t Go Full-Harness (Important)

The conclusion first:

👉 It’s too heavy. I dropped it.

The full setup looks like this:

Planner → Generator → Reviewer → Evaluator

It’s the ideal architecture, but in practice:

• The Planner runs every single time.
• Even tiny fixes go through a design phase.
• The thinking cost is high.
• Development tempo collapses.

And on top of that:

👉 Token consumption explodes.

With a full harness:

• Every agent re-reads the same files.
• ADRs / templates / code get read over and over.
• The context just keeps growing.

The result:

• Long files stop fitting.
• Accuracy drops.
• The session falls apart.
• Cost goes up.

👉 An ideal architecture, but overkill for this use case (small fixes).

For my actual use case:

• Improving existing code
• UI tweaks
• Small feature additions

In this phase:

Structural decay matters more than design mistakes.

👉 So just the Reviewer was enough.

8. Why I Made It “Semi-Automatic”

I could fully automate it. I deliberately didn’t.

Three reasons:

▸ ① Avoid Pointless Reviews

If you review every mid-flight or half-written change:

• Noise increases.
• Meaningless nitpicks pile up.

👉 Even humans don’t do this.

▸ ② It Creates a Thinking Break

You stop here, on purpose.

👉 This is enormously important.

▸ ③ I Hold the Trigger

レビューして

That single phrase:

👉 Switches from dev mode to review mode.

👉 This was the version that actually felt right.

9. Where I Got Burned (Important)

▸ ❌ The First Failure

• I wrote viewpoints and called it done.
• No judgment criteria.
• The review changes depending on who runs it.

👉 The AI review was not reproducible.

▸ The Fix

For each viewpoint:
- Definition
- NG example
- OK example

👉 This is what made it stable.

10. The Other Critical Piece

▸ Defining the Review Target

Skip this and you’re in hell:

What exactly are we reviewing?

▸ The Solution

Default: the diff from `git status`

Options:

review  --all
review  *****

👉 Now it feels like CI.

11. The Before / After

▸ Before

• Fast, but breaks.
• Fix-it-later hell.

▸ After

• A bit slower.
• But stable.
• Fix cost drops dramatically.

12. The Essence

What I’m actually doing is this:

Have AI write.
Have AI break.
Have AI fix.

👉 The same structure as a human team.

13. How It Actually Felt

• Claude stops going off the rails.
• File structure stays stable.
• The next Claude can still read the code.

👉 The biggest win was AI readability.

14. Caveats

• Skip the review and it collapses fast.
• A vague ADR is worthless.
• Keep rules in one place (Single Source of Truth).

15. Where This Extends

Apply the same idea and you get:

• Fix mode
• Design mode
• Deploy mode

👉 A full AI team.

16. Summary

• AI alone is not trustworthy.
• But with structure, it’s usable.
• A full harness is ideal but overkill.
• Token constraints shaped the design too.
• This time, I scoped it down to “review only.”

👉 Semi-automatic review is the right level of compromise.

17. Bonus (Copy-Paste)

review

That single line is enough to trigger the whole review pipeline.

👉 And honestly, that’s the biggest deal.