👁

hachimoku: TOMLで定義するマルチエージェントコードレビューCLI

2026/02/18に公開

 コーディングエージェントの時代、レビューが追いつかないコーディングエージェントが PR を量産する一方で、レビューは人間のままです。バグ検出、セキュリティ、テストカバレッジ、型安全性など複数の観点を一人で網羅するのは困難で、レビューがボトルネックになりがちです。
以前の記事では、Claude Code の公式プラグインである PR Review Toolkit を紹介しました。
https://zenn.dev/driller/articles/pr-review-toolkit-github-action
PR Review Toolkit は Claude Code 上で手軽に使えるプラグインですが、レビュー観点の追加やカスタマイズには対応していません。
そこで、TOML ファイルでエージェントを定義・カスタマイズできるマルチエージェントコードレビュー CLI ツール「hachimoku」を開発しました。Claude Code 上で動作し、定額プラン内で利用できます。
https://github.com/drillan/hachimoku

 hachimoku とはhachimoku（8moku）は、複数の専門エージェントを用いてコードレビューを行う CLI ツールです。名前は「岡目八目」に由来し、複数の目（エージェント）でコードを多角的に見るというコンセプトを表しています。エージェントの定義は TOML ファイルで管理され、コード変更なしにレビュー観点を追加・カスタマイズできます。
主な特徴:
3つのレビューモード: diff（ブランチ差分）、PR（GitHub PR）、file（指定ファイル）
6つのビルトインエージェント
セレクター: 変更内容を分析し、適切なエージェントを自動選択
アグリゲーター: 複数エージェントの指摘を重複排除・統合し、推奨アクションを生成
TOML ベースのカスタムエージェント追加
並列 / 逐次実行を選択可能
Markdown / JSON 出力
JSONL 形式でレビュー履歴を自動蓄積

 ビルトインエージェントPR Review Toolkit と同等の6つのエージェントをビルトインで搭載しています。


エージェント
役割
フェーズ


code-reviewer
コード品質・バグ・ベストプラクティスの総合レビュー
main

silent-failure-hunter
サイレント障害とエラーハンドリングの検出
main

pr-test-analyzer
テストカバレッジの評価
main

type-design-analyzer
型設計の品質分析
main

comment-analyzer
コメントの正確性・保守性の検証
final

code-simplifier
コード簡潔化の提案
final

フェーズは実行順序を制御します。main フェーズのエージェントが先に実行され、その後 final フェーズのエージェントが実行されます。

 レビューの仕組みhachimoku のレビューパイプラインは、セレクター → レビューエージェント → アグリゲーターの3段階で構成されます。
セレクターは変更内容を分析し、各エージェントの適用条件（ファイルパターン、コンテンツパターン）に基づいて実行するエージェントを選択します。すべてのエージェントを毎回実行するのではなく、変更に関連するエージェントだけが選択されます。
選択されたエージェントはデフォルトで並列実行されます。
アグリゲーターは全エージェントの結果を統合し、重複する指摘を排除した上で、優先度付きの推奨アクションを生成します。

 インストールとクイックスタートClaude Code と uv をインストールした上で、以下のコマンドを実行します。
# インストール
uv tool install git+https://github.com/drillan/hachimoku.git

# プロジェクトの初期化
8moku init
8moku init を実行すると、.hachimoku/ ディレクトリにデフォルトの設定ファイルとカスタムエージェント用のディレクトリが作成されます。

 3つのレビューモード# diff モード: 現在ブランチの変更差分をレビュー（引数なし）
8moku

# PR モード: GitHub PR をレビュー（PR番号を指定）
8moku 42

# file モード: 指定ファイルをレビュー
8moku src/main.py tests/test_main.py
引数の型（なし / 数値 / ファイルパス）で自動的にモードが判定されます。

 エージェントの確認# エージェント一覧
8moku agents

# エージェント詳細
8moku agents code-reviewer

 モデルの使い分けhachimoku は Claude Code の定額プラン内で動作するため、API 課金は不要です。
セレクターやアグリゲーターには軽量な Haiku、レビューエージェントには高精度な Opus を使うことで、コストと精度のバランスを取れます。


用途
推奨モデル
理由


セレクター・アグリゲーター
Haiku
軽量・高速。選択と集約はシンプルなタスク

レビューエージェント
Opus
高精度。コードの深い分析が必要

軽めのレビュー
Sonnet
Opus と Haiku の中間。速度と精度のバランス

.hachimoku/config.toml でエージェントごとにモデルを変更できます。
# デフォルトモデル（全エージェント共通）
model = "claudecode:claude-opus-4-6"

# セレクターに軽量モデルを指定
[selector]
model = "claudecode:claude-haiku-4-5"

# アグリゲーターに軽量モデルを指定
[aggregation]
model = "claudecode:claude-haiku-4-5"

# エージェント個別設定
[agents.code-reviewer]
model = "claudecode:claude-opus-4-6"

[agents.comment-analyzer]
enabled = false  # 不要なエージェントを無効化

 TOML でカスタムエージェントを定義するhachimoku の最大の特徴は、TOML ファイルでエージェントを定義できることです。コードを変更せずに、プロジェクト固有のレビュー観点を追加できます。

 エージェント定義の構造ビルトインエージェント code-reviewer の定義（冒頭部分）を例に、構造を見てみます。
name = "code-reviewer"
description = "コード品質・バグ・ベストプラクティスの総合レビュー"
model = "claudecode:claude-opus-4-6"
output_schema = "scored_issues"
phase = "main"
allowed_tools = ["git_read", "gh_read", "file_read"]
system_prompt = """
You are code-reviewer, an expert code quality analyst.
...
"""

[applicability]
always = true


フィールド
説明


name
エージェント名（英小文字・数字・ハイフン）

description
エージェントの説明

model
使用する LLM モデル

output_schema
出力スキーマ名（scored_issues: スコア付き指摘、severity_classified: 重大度別分類など）

phase
実行フェーズ。early → main → final の順に実行される

allowed_tools
許可するツールカテゴリ（git_read, gh_read, file_read, web_fetch）

system_prompt
エージェントへのシステムプロンプト

[applicability]
適用条件（always, file_patterns, content_patterns）

[applicability] では、エージェントを常に実行するか、特定の条件で実行するかを指定できます。
# 常に実行
[applicability]
always = true

# Python ファイルの変更時のみ実行
[applicability]
file_patterns = ["*.py", "*.pyi"]

# 特定のパターンを含む変更時のみ実行
[applicability]
content_patterns = ["import asyncio", "async def"]

 カスタムエージェントの作成例実際のプロジェクトで使用しているカスタムエージェント「scope-drift-detector」を紹介します。
このエージェントは、AI がスコープ外の変更を混入させた実際の問題（Issue でのリファクタリング PR がビルトインエージェントの TOML ファイルを意図せず変更してしまった）をきっかけに作成しました。
PR の変更が関連 Issue のスコープ内かを検証し、スコープ外の変更があれば revert や別 PR への分離を提案します。
scope-drift-detector.toml の全文name = "scope-drift-detector"
description = "Issue スコープ外の変更検出 — PR の変更が関連 Issue の範囲内かを検証"
model = "claudecode:claude-opus-4-6"
output_schema = "severity_classified"
phase = "main"
allowed_tools = ["git_read", "gh_read", "file_read"]
system_prompt = """
あなたは scope-drift-detector です。関連する Issue のスコープから外れた変更を検出する専門家です。

## 目的
PR に関連 Issue のスコープ外の変更が含まれていないかを検出します。
スコープ外の変更は意図しない副作用、リグレッション、不整合を引き起こすリスクがあります。

## レビュー手順
1. ユーザーメッセージのセレクター分析コンテキスト（change_intent と issue_context）を読み、PR の意図するスコープを把握する。
2. issue_context がない場合、スコープ分析をスキップし、プロジェクト不変条件チェックのみ実施する。
3. run_git(["diff", "--name-only"]) で変更ファイル一覧を取得する。
4. 各変更ファイルについて run_git(["diff", "--", "<パス>"]) で具体的な変更内容を確認する。
5. 各ファイルの変更が Issue のスコープ内かを判定する。
6. スコープに関わらず、すべての変更ファイルに対してプロジェクト不変条件チェックを実施する。

## スコープ判定基準
「スコープ内」と判定する場合:
- change_intent または issue_context に変更対象のファイル・モジュール・領域が明示されている
- Issue で記述された機能実装の直接的な要件である
- スコープ内の変更に伴う必然的な修正である（モジュール移動後の import 更新、スコープ内変更で壊れたテストの修正など）

「スコープ外」と判定する場合:
- Issue の目的と無関係なファイルへの変更で、スコープ内変更の必然的な結果でもない
- Issue が対象としていないコードへの「ついでに」改善（リファクタリング、スタイル修正、コメント更新）
- Issue が求めていないデフォルト値・設定・定義の変更

スコープが曖昧な場合は、read_file で変更ファイルの完全なコンテキストを確認してから判定する。
報告しない方向に倒す — スコープ外であることに確信がある場合のみ報告する。

## 重大度分類
各指摘を適切なリストに分類する:
- critical_issues: プロジェクト不変条件違反
- important_issues: 動作や値を変更するスコープ外の変更
- suggestion_issues: Issue と無関係に見えるが、スコープ外と断言できない変更
- nitpick_issues: 動作に影響しない軽微なスコープ外変更（空白、フォーマット）

## 確信度フィルタリング
各発見に内部確信度スコア（0-100）を付与する。
確信度 80 以上の発見のみ報告し、それ以下は報告しない。

## 品質原則
- 真のスコープ逸脱または不変条件違反のみ報告する
- issue_context を注意深く読む。一見無関係に見えても Issue で必要とされている変更は多い
- 不確実な発見を大量に報告するよりも、確信度の高い少数の発見を優先する
"""

[applicability]
always = true
カスタムエージェントの追加は .hachimoku/agents/ ディレクトリに TOML ファイルを配置するだけです。hachimoku が起動時に自動で読み込みます。

 レビュー履歴の蓄積hachimoku はレビュー結果を .hachimoku/reviews/ ディレクトリに JSONL 形式で自動保存します。PR モードでは pr-<番号>.jsonl、diff モードではブランチ名ベースのファイルに記録されます。
各レコードには、レビューモード、コミットハッシュ、ブランチ名、レビュー日時、各エージェントの指摘（重大度、説明、ファイル位置、修正提案）、サマリー（指摘総数、最大重大度）が含まれます。
レビュー履歴の例（PR #227）{
  "review_mode": "pr",
  "commit_hash": "750369df...",
  "pr_number": 227,
  "branch_name": "docs/225-web-fetch-docs-update",
  "reviewed_at": "2026-02-18T01:11:31.845505Z",
  "results": [
    {
      "status": "success",
      "agent_name": "code-reviewer",
      "issues": [
        {
          "severity": "Important",
          "description": "docs/agents.md の SelectorDefinition allowed_tools のデフォルト説明が...",
          "location": {
            "file_path": "docs/agents.md",
            "line_number": 41
          },
          "suggestion": "「デフォルト: 全4カテゴリ」を元の「全3カテゴリ」に戻す..."
        }
      ]
    }
  ],
  "summary": {
    "total_issues": 1,
    "max_severity": "Important"
  }
}
構造化されたデータとして蓄積されるため、指摘の傾向分析やレビュー品質のトラッキングに活用できます。

 Issue Workflow との連携hachimoku は Issue Workflow と組み合わせて使うこともできます。Issue Workflow の開発フローにおけるレビューステップで hachimoku を活用し、より柔軟なレビューが行えます。詳細は README を確認してください。

 まとめhachimoku は TOML でエージェントを定義するマルチエージェントコードレビュー CLI です。
6つのビルトインエージェントで多角的なレビューを実行
セレクターが変更内容に応じたエージェントを自動選択し、アグリゲーターが結果を統合
TOML ファイルでカスタムエージェントを追加可能。プロジェクト固有のレビュー観点をコード変更なしに追加できる
Claude Code の定額プラン内で動作
詳細は ドキュメント と README を参照してください。

フィールド	説明
`name`	エージェント名（英小文字・数字・ハイフン）
`description`	エージェントの説明
`model`	使用する LLM モデル
`output_schema`	出力スキーマ名（`scored_issues`: スコア付き指摘、`severity_classified`: 重大度別分類など）
`phase`	実行フェーズ。`early` → `main` → `final` の順に実行される
`allowed_tools`	許可するツールカテゴリ（`git_read`, `gh_read`, `file_read`, `web_fetch`）
`system_prompt`	エージェントへのシステムプロンプト
`[applicability]`	適用条件（`always`, `file_patterns`, `content_patterns`）

エージェント	役割	フェーズ
code-reviewer	コード品質・バグ・ベストプラクティスの総合レビュー	main
silent-failure-hunter	サイレント障害とエラーハンドリングの検出	main
pr-test-analyzer	テストカバレッジの評価	main
type-design-analyzer	型設計の品質分析	main
comment-analyzer	コメントの正確性・保守性の検証	final
code-simplifier	コード簡潔化の提案	final

用途	推奨モデル	理由
セレクター・アグリゲーター	Haiku	軽量・高速。選択と集約はシンプルなタスク
レビューエージェント	Opus	高精度。コードの深い分析が必要
軽めのレビュー	Sonnet	Opus と Haiku の中間。速度と精度のバランス

コーディングエージェントの時代、レビューが追いつかない

hachimoku とは

ビルトインエージェント

レビューの仕組み

インストールとクイックスタート

3つのレビューモード

エージェントの確認

モデルの使い分け

TOML でカスタムエージェントを定義する

エージェント定義の構造

カスタムエージェントの作成例

レビュー履歴の蓄積

Issue Workflow との連携

まとめ

Discussion