クイックスタート

必要なもの

• Node.js 22 以上
• git 履歴のあるリポジトリ ―― 変更頻度を計算するために使います
• TypeScript のコードベース（モノレポでも単一パッケージでも動きます）

shallow clone では動きません

git clone --depth 1 や CI の既定設定で履歴が浅いと、変更頻度・hotspot・coupling がすべて壊れます。dowsing は起動時に検出して警告しますが、結果は信用できません。CI では fetch-depth: 0 を指定してください。

まず動かす

インストールは不要です。

npx dowsing analyze

数秒で、次のような出力が得られます（2,238 ファイル / 3,920 コミットのモノレポで約 7 秒）。

  Discovering workspace... 40 packages (pnpm)
  Reading git history (since 12 months ago)... 3920 commits
    excluded: 6 merge, 0 bot, 1 format-only, 0 ignore-revs
  Parsing AST (oxc)... 2238 files
  Building package graph... 40 packages, 168 edges
  Computing change coupling... 500 file pairs, 25 package pairs (1 hidden)

⚠ Top hotspots (complexity=loc):
┌───┬─────────────────────────────┬───────┬────────┬────────┬─────────┐
│ # │ file                        │ score │   freq │     cx │ commits │
├───┼─────────────────────────────┼───────┼────────┼────────┼─────────┤
│ 1 │ services/api/src/runtime.ts │ 0.999 │ 100pct │ 100pct │     255 │
└───┴─────────────────────────────┴───────┴────────┴────────┴─────────┘

📌 Top findings (where to look first):
  🔥 services/api/src/runtime.ts — 頻繁に変更され複雑（255 commits, 857 LoC）
  🔗 @acme/admin-web ↔ @acme/customer-web — 依存関係がないのに 91 回同時に変更されている

結果は .dowsing/dowsing.json にも保存されます。

除外件数が表示される理由

merge / bot / format-only コミットを除外したことを毎回明示します。silent に除外すると「全部見た結果」だと誤解されるためです。何を見て何を見なかったかが分からない数字は信用できません。

気になったところを掘る

なぜ一緒に変わるのか

隠れた結合が出たら、実体を確認します。

npx dowsing why @acme/admin-web @acme/customer-web

■ 最も一緒に変わるファイルの組
  src/lib/server-api.ts        ↔  src/lib/server-api.ts          13
  src/app/(authed)/page.tsx    ↔  src/app/(authed)/page.tsx      15

■ 代表コミット（新しい順）
  c23db79c 2026-07-09 セッション失効時の再ログイン誘導を両方の Web アプリへ追加 [A:3 B:6 files]

同名のファイルが両方にあり、同じ変更が手作業でコピーされていることが分かります。共通パッケージへの抽出候補です。

その変更頻度は本物か

npx dowsing analyze --verify-churn

AST を比較して、リネーム・整形だけの変更を見分けます。

🔍 Churn 検証（AST 比較, 上位 20 ファイル）:
  568 リビジョン中 513 が実質的な変更（55 は偽 churn: リネーム 12 / 整形のみ 35 / 内容不変 8）
  ⚠ customer-detail-panel.tsx: churn の 42% は意味を変えない変更

リビジョンごとに git show を実行するため、上位 N 件だけを対象にするオプトインです。

なぜ複雑なのか

npx dowsing health --file src/foo.ts

  health: 4.9 / 10（LoC のみのベースライン: 10.0）
  10.0 からの減点内訳:
    -3.00 認知的複雑度が高い (50 > 閾値 15, severity 1.00)
         → validateConfig (cognitive=50, L3)
    -2.13 複雑な関数 (27 > 閾値 10, severity 0.85)
         → validateConfig (cyclomatic=27, L3)

LoC ベースラインが 10.0 なのに health が 4.9 ―― 短いけれど密なファイルです。行数だけを見る指標では見落とされます。

知識がどこに集中しているか

npx dowsing knowledge

パッケージ単位の bus factor と、主要開発者が抜けたときの影響が出ます。

エージェントから使う

登録するものはありません。エージェントは CLI を叩けるので、インターフェースは 1 コマンドで伝わります。

npx dowsing --help

任意の Agent Skill を入れておくと、いつ使うべきか・数値をどう読むかをエージェントが知ることができます。

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

以降、セッション内で「このリポジトリで次に直すべきところは？」と聞けば、dowsing の解析結果に基づいて答えます。詳しくは エージェント統合 を参照してください。

リファクタが効いたか確かめる

npx dowsing diff origin/main

変更されたファイルを両方のリビジョンで測り直し、複雑度が実際にどう動いたかを返します。

📉 複雑度の実測（base → head）:
  cognitive -41 / cyclomatic -22 / LoC -111

誰が変更したかは問いません（自分でも、エージェントでも、CI 上の PR でも）。詳しくは 効果を実測する を参照してください。

次に読む

• 結果の読み方 ―― スコアをどう解釈し、何を無視すべきか
• CLI リファレンス ―― 全コマンドとオプション
• CI 連携 ―― 品質ゲートと PR コメント