エージェント統合

dowsing はコーディングエージェントを第一の消費者として設計されています。人間向けの表やレポートより先に、エージェント向けのインターフェースが用意されています。

なぜエージェント優先なのか

CodeScene が設計された時代の前提は「テックリードがダッシュボードを見る」でした。いまは Claude Code のようなエージェントがリファクタ対象を決めて実行します。

エージェントは「このファイルは複雑です」という警告を必要としません。必要なのは根拠のある優先順位です。dowsing はそれを構造化データで返します。

MCP サーバは持ちません

Phase 1 で実装しましたが、2026-07-31 に削除しました。公開していた tool は CLI のサブコマンドと 1:1 で、エージェントはそもそもシェルを実行できます。同じ機能に 2 つの表面を持つのは保守コストだけが増える一方、MCP は tool 定義が常時コンテキストを占めます。実際に呼ぶのは 1 セッションに 1〜2 回です。

残したものはもっと小さく、届く範囲は広くなりました。

dowsing --help

この出力が正本です。コマンドとオプションの一覧に続けて、表では表現できないもの（前提とする git 履歴・出力形式・終了コード・キャッシュの挙動）が出ます。--agent-help のような専用フラグは用意していません —— エージェントはどのみち --help を叩きますし、フラグを分けるとコマンド一覧が二重管理になってズレるだけです。

すべてのコマンドに --json があるので、エージェントは整形済みの表ではなくデータを読みます。

Agent Skill を入れる

CLI 単体で動きますが、任意の Agent Skill を入れると、いつ dowsing を使うべきか、そして返ってきた数字をどう読むかをエージェントが知ることができます。

gh skill install yhay81/dowsing dowsing --agent claude-code --scope user

claude-code は codex / cursor / github-copilot / opencode / cline / kiro-cli / windsurf に置き換えられます。エージェント自身に入れさせるなら install-agent.md を読ませてください。

skill にはフラグを書きません（それは --help の役目で、書き写すと CLI の変更で陳腐化します）。代わりに入っているのは解釈です。

• score 0 のファイルは、どれだけ複雑でも提案しない —— 誰も触っていないので直しても返りがない
• hidden coupling は必ず dowsing why で裏を取る —— コピーされたコードと意図的なプロトコルは数値上まったく同じに見える
• churn を額面どおりに受け取らない —— effectiveRatio が低ければリネームで水増しされている
• health は必ず内訳とともに示す —— 「health 4.9」だけでは行動できない
• bus factor は人ではなくリスクの話として扱う

ホストではなくリポジトリに教える

skill はホストごとに入るので、入れた本人のエージェントにしか届きません。AGENTS.md に 1 行書くほうはリポジトリに乗って伝播し、そこで作業するあらゆるホストのエージェントが読みます。dowsing を知らないエージェントにも届く、という違いです。

npx dowsing init            # AGENTS.md に dowsing のセクションを追記する
npx dowsing init --dry-run  # 何が書かれるか先に見る

再実行しても増えません（dowsing のセクションだけを更新します）。

結果に必ず添えられるもの

解析結果にはその解析が行われた条件が入っています。

{
  "meta": {
    "git": {
      "since": "12 months ago",
      "commitCount": 3920,
      "exclusions": { "merges": 6, "bots": 0, "formatOnly": 1 },
      "shallow": false
    }
  },
  "config": { "complexity": "loc" }
}

エージェントが「255 回変更されている」ではなく「直近 12 か月で、merge と bot を除いて 255 回」と報告できるようにするためです。

2 回目以降は速い

大きなリポジトリでも初回は数秒です。結果は .dowsing/cache に、HEAD・作業ツリーの状態・解析オプションをキーにして残るので、同じセッションで hotspots → coupling → why と続けて叩いても即答します。

キャッシュを使ったときは stderr にその旨を表示します（黙って古い数字を新しい解析のように見せません）。大きく変更した直後は --refresh を付けてください。

dowsing はコードを直しません

直すのはエージェントの仕事です。dowsing は直す前に「どこを」を示し、直した後に「効いたか」を測ります。

dowsing diff origin/main

変更されたファイルを両方のリビジョンで測り直し、複雑度が実際にどう動いたかを返します。誰が変更したかは問わないので、人間のコミットでも、エージェントのリファクタでも、CI 上の PR でも同じように使えます。悪化した場合も同じ形式でそのまま報告します。