Debtmap - 技術的負債を感覚のリストから risk ranking に変える
技術的負債で一番難しいのは、「負債がある」という事実そのものではありません。どこから直すべきかについて、チーム内の感覚がばらばらになりやすいことです。ある人は長い file を気にし、別の人は最近 bug が出た module を気にし、また別の人は coverage の低い場所を見ます。結果として、全部大事そうだけれど priority が決めにくい list が残ります。
今日紹介する iepathos/debtmap は、この問題を sortable な analysis result にしようとする tool です。Rust で書かれた technical debt / code risk analysis CLI で、terminal、TUI、dashboard で使えます。JSON / Markdown output もあり、automation や AI coding assistant の input にできます。GitHub page では現在およそ 40 stars、5 forks。主な言語は Rust、license は MIT です。Repository は 2025 年 8 月に作成され、2026 年 6 月現在も active で、Cargo.toml の current version は 0.17.1 です。
プロジェクト概要
| 項目 | 内容 |
|---|---|
| リポジトリ | iepathos/debtmap |
| 位置づけ | Technical debt と code risk を分析する CLI |
| Stars | 約 40 |
| Forks | 5 |
| 主な言語 | Rust |
| ライセンス | MIT |
| Current version | 0.17.1 |
| Install | cargo install debtmap または release installer |
Complexity だけを見る tool ではない
多くの code quality tool は complexity から始まります。Cyclomatic complexity、cognitive complexity、nesting depth などです。これらは重要ですが、それだけで判断すると誤解が生まれます。複雑な function でも、test coverage が高く、あまり変更されず、boundary が明確なら、今すぐ直すべきとは限りません。逆に、それほど複雑に見えない function でも、頻繁に変更され、bug fix に何度も出てきて、coverage gap が大きいなら risk は高くなります。
Debtmap の README は、使う signal を明確に分けています。Complexity、coverage、git history、coupling、purity、entropy です。価値は単一指標ではなく、組み合わせて見るところにあります。
たとえば:
- Complexity は code の理解コストを見る。
- Coverage は変更時の behavior risk を見る。
- Git history は何度も変わる場所、何度も壊れる場所を見つける。
- Coupling は変更が codebase の中でどう広がるかを見る。
- Purity は side effect、I/O、testability を見る。
- Entropy は意図的な複雑さを false positive にしにくくする。
これらの signal は unified priority score にまとめられ、critical、high、medium、low の severity band に分かれます。Maintainer にとっては、「ここがなんとなく気持ち悪い」よりも action に移しやすい形です。
Rust、Python、JavaScript、TypeScript に対応
Debtmap は現在、Rust、Python、JavaScript、TypeScript を support しています。Rust は syn による AST analysis を使い、macro expansion や trait detection も扱います。Python、JavaScript、TypeScript は tree-sitter を使い、function、class、decorator、JSX、async workflow、TS/TSX などの pattern を見ます。
この scope は実用的です。最初から全 language を対象にするのではなく、現代の開発と AI agent の変更対象になりやすい stack に寄せています。特に TypeScript と Python は、coding agent がすでに実務で触り始めている repository が多いです。Agent が issue だけを見て patch すると、既存の複雑な area をさらに太らせることがあります。
基本の使い方は短いです。
cargo install debtmap
debtmap analyze .特定 language だけを分析することもできます。
debtmap analyze . --languages rust,python,javascript,typescriptTUI は人間の探索に、JSON は automation に向いている
debtmap analyze . は default で interactive な exploration view として使えます。README によると、TUI では severity で並んだ debt items を見たり、score breakdown を掘ったり、git history、dependency、function-level coverage を確認したり、必要に応じて AI assistant 用の context を clipboard に copy できます。
この TUI の意味は、「どこを先に直すか」を議論しやすくすることです。ある item が上位に来る理由は、tool が score を付けたからだけではありません。Reviewer は、その score の中身を見られます。Complexity が高いのか、coverage が低いのか、call relationship が広がりすぎているのか、history 上ずっと変更されているのかを確認できます。
Automation には JSON output が向いています。
debtmap analyze . --format json --top 10 --output debt.jsonJSON は script、CI、internal dashboard に渡せます。Quality gate を作りたい team では、local で一回見るだけより役に立ちます。たとえば毎週 main branch で risk list を生成したり、大きな refactor の前後で debt score が本当に下がったかを比較したりできます。
Markdown output は AI workflow と相性がよい
Debtmap は AI workflow を明確に意識しています。--format markdown があり、この output を AI coding assistant に渡せます。README では、context suggestions、structured metadata、compact output、deterministic output が説明されています。
これは重要です。AI に技術的負債を直させるとき、悪い指示はたいてい「この project を改善して」のように広すぎます。Scope が大きすぎ、goal が曖昧で、agent は表面的な refactor を選んで終わるかもしれません。より良い方法は、まず小さく明確な問題を渡すことです。どの function か、なぜ high risk なのか、どの file range を読むべきか、score はどの signal から来ているのか、という材料です。
README の例もわかりやすいです。
debtmap analyze . --format markdown --top 1 | claude "Fix this technical debt"私はこの使い方を、agent に task を渡す前の filter として見ています。Debtmap は修正の正しさを証明しませんし、test や review の代わりにもなりません。より前の step、つまり直す価値の高い risk area を見つけ、context を agent が読める形に圧縮する役目です。
Dashboard は risk distribution を見せてくれる
Terminal output だけでなく、Debtmap には online dashboard もあります。使うには、context と coverage を含んだ JSON を生成します。
debtmap analyze . --format json -o debtmap.json --lcov coverage.lcov --contextその後 dashboard に file を読み込ませます。README では、risk quadrant、top debt items、module flow、risk radar が提供されると説明されています。また、処理は browser client-side で行われ、data は browser から外に出ないとされています。
これは team communication に効きます。技術的負債が CLI output の中だけにあると、少数の maintainer の知識に閉じやすいです。Visualize されると、refactor planning、quality retrospective、milestone review に載せやすくなります。特に risk quadrant は、complexity と coverage gap を一緒に見るため、片方の metric だけに寄りにくくなります。
CI/CD では threshold を慎重に扱う
README には GitHub Actions の例もあり、iepathos/debtmap-action@v1 を使って max-complexity-density や fail-on-violation のような threshold を設定できます。
ただし、最初から hard gate にするのは慎重でよいと思います。Technical debt analysis は lint とは違います。Lint rule は比較的明確ですが、debt score は project structure、coverage data、commit history、language parsing quality に影響されます。すぐ CI を fail させると、team は tool threshold との交渉に時間を使ってしまうかもしれません。
現実的な流れは次のようなものです。
- まず main branch で定期 report を作る。
- Team が納得できる high risk case をいくつか見て校正する。
- 新しく増えた high risk debt に alert を出す。
- 最後に特定 directory や特定 metric にだけ blocking rule を置く。
こうすると tool は判断支援になりやすく、noise になりにくいです。
向いている場面
Debtmap は次のような場面に向いています。
- Codebase が長く運用され、技術的負債は見えているが priority がない。
- Refactor task を小さく、説明可能な item に分けたい。
- AI coding assistant が fix、refactor、test 補強に参加している。
- Coverage、complexity、git history を一緒に見たい。
- JSON / Markdown output を CI、dashboard、internal tool に接続したい。
一方で、すべての code quality 判断を一つの score に任せる tool ではありません。High score の item は見る価値がありますが、すぐ直すかどうかは business risk、release plan、module ownership と一緒に判断する必要があります。Legacy system では、古い protocol や data format のために複雑になっている code もあります。その場合、tool は risk を示せますが、判断そのものは team の仕事です。
まとめ
iepathos/debtmap の中心は、「code が美しくない場所を探す」ことではありません。Technical debt を sortable で explainable で automation に渡しやすい risk list に変えることです。Complexity、coverage、git history、coupling、side effect などの signal をまとめ、maintainer が「今日どこから直すべきか」を考えやすくします。
AI workflow との組み合わせもよい方向です。Agent にどこから直すかを丸投げするのではなく、先に analysis tool で high risk area を見つけ、scope、reason、context を渡す。そのあと test と review で検証する。この「分析してから渡す」流れは、AI に広い refactor を直接任せるよりも現実的です。