Claude Codeで「半自動レビュー」を仕込んだら開発が安定した話
1. 結論
Claude Codeはそのまま使うと不安定 👉 レビューを構造として組み込むと一気に安定する
2. 背景（あるある）
- コードはそれっぽい
- でも構造がぐちゃぐちゃ
- ファイル分割が雑
- 同じ処理が増殖する
- 自己レビューは「問題なし」になる
👉 人間の新人エンジニアと同じ挙動
3. 問題の本質
問題はプロンプトではない
AI単体で品質を担保しようとしていること👉 解決策は「ハーネス設計」
4. やったこと（超シンプル）
「レビューして」と言ったら 👉 強制的にレビューが走る仕組みを作った
5. 仕組みの全体像
通常モード
↓
（開発）
↓
「レビューして」
↓
レビュー専用モード発動
↓
構造チェック
↓
修正指示👉 これだけ
6. 実装のコア
① ADRでルール固定
docs/harness/adr/0001-review-mode.md- レビュー観点
- 判定基準（定義 / NG / OK）
- セキュリティルール
👉 「憲法」みたいなもの
② CLAUDE.mdでトリガー定義
レビューして
review👉 これでモード切替
③ テンプレで出力を固定
docs/harness/templates/review-template.md👉 レビューのブレを防ぐ
④ レポート保存
docs/harness/reports/👉 地味に重要（再発防止）
7. なぜフルハーネスにしなかったか（ここが重要）
最初に結論👇
👉 重すぎるからやめた
フル構成はこうなる：
Planner → Generator → Reviewer → Evaluator理想的な構成ではあるが、実際に回すと👇
- 毎回Plannerが動く
- 小さい修正でも設計フェーズが入る
- 思考コストが高い
- 開発テンポが落ちる
さらに👇
👉 トークン消費が大きすぎる
フルハーネスだと：
- 各エージェントが同じファイルを読む
- ADR / テンプレ / コードを何回も読む
- コンテキストがどんどん膨らむ
結果👇
- 長いファイルが読めなくなる
- 精度が落ちる
- セッションが崩れる
- コストも上がる
👉 理想構成だが、今回の用途（小規模修正）にはオーバースペック
今回の用途では👇
- 既存コードの改善
- UI調整
- 小さな機能追加
このフェーズって👇
設計ミスより「構造崩れ」の方が問題になる👉 だからReviewerだけで十分だった
8. なぜ「半自動」にしたか
完全自動にもできるけど、あえてやってない
理由は3つ👇
① 無駄なレビューを防ぐ
途中のコードや書きかけに対して毎回レビューすると👇
- ノイズが増える
- 無意味な指摘が増える
👉 人間でもやらない
② 思考の区切りになる
ここで一回止まる👉 これがめちゃくちゃ重要
③ 自分でトリガーを握る
レビューしてこの一言で👇
👉 開発モード → レビューモードに切り替える
👉 これが一番しっくりきた
9. ハマったポイント（ここが重要）
❌ 最初の失敗
- 観点だけ書いて満足
- 判定基準がない
- 人によってレビューが変わる
👉 AIレビューが再現不能
修正
各観点に
・定義
・NG例
・OK例👉 これで安定
10. もう一つの重要ポイント
レビュー対象の定義
これやらないと地獄👇
どこレビューするの？解決
デフォルト: git status の差分オプション：
レビューして --all
レビューして src/👉 CIっぽくなる
11. 実際どう変わったか
Before
- 速いけど壊れる
- 後で修正地獄
After
- 少し遅い
- でも安定
- 修正コスト激減
12. 本質
やってることはこれ👇
AIに書かせる
AIに壊させる
AIに直させる👉 人間チームと同じ構造
13. 使ってみた感想（リアル）
- Claudeが暴走しなくなる
- ファイル構造が安定する
- 次のClaudeでも読めるコードになる
👉 一番効いたのは「AI可読性」
14. 注意点
- レビューをサボると即崩壊
- ADRが曖昧だと意味ない
- ルールは1箇所に集約する（Single Source of Truth）
15. 応用
これ応用すると👇
- 修正モード
- 設計モード
- デプロイモード
👉 完全にAIチーム化
16. まとめ
- AIは単体だと信用できない
- でも構造を作れば使える
- フルハーネスは理想だがオーバースペック
- トークン制約も設計判断に影響した
- 今回は「レビューだけ」に絞った
👉 半自動レビューはちょうどいい落としどころ
17. おまけ（コピペ）
レビューしてこれだけでレビューが走るようになる
👉 これが一番デカい