ast-outline: AI coding agent に AST 予読レイヤーを足す

最近ローカル AI coding tool を見ていて、かなり頻繁にぶつかるのに、意外と放置されがちな非効率があります。

多くの coding agent は、コードベースを理解する前段で、まだ丸ごとのファイルを読みがちです。

もちろん、そのやり方は確実です。ただし高くつきます。

ある module にどんな class があるのか、ある method がどの type に属しているのか、ある directory の輪郭がどうなっているのかを知りたいだけなら、最初から数百行、数千行の source を全部 context に入れる必要はないことが多いです。実際、context の膨張はこの初手から始まることがよくあります。

今日取り上げたい ast-outline/ast-outline は、まさにそこを狙った小さな tool です。

GitHub repository page、release page、README、docs site を 2026-06-30 時点で確認すると、この repository は 33 stars、2 forks、作成日は 2026-04-22、直近の公開更新は 2026-06-30 です。主言語は Python、コードの license は Apache 2.0。最新 release は v1.7.0 で、公開日は 2026-06-30 です。

Project overview

項目	内容
Repository	ast-outline/ast-outline
位置づけ	coding agent 向け AST 構造予読 CLI
Stars	33
Forks	2
主言語	Python
作成日	2026-04-22
直近の公開更新	2026-06-30
Latest version	v1.7.0
Release date	2026-06-30
Code license	Apache 2.0
中心の発想	まず構造を見て、必要な symbol だけ展開する

これは「検索できない」問題ではなく、「読み方が重すぎる」問題への対処です

README はこの project の立ち位置をかなりはっきり書いています。

AI coding agent はコードを理解するとき、「この file には何があるか」「この method はどこで定義されているか」「この module の形はどうなっているか」といった問いに答えるために、しばしば source file 全体をそのまま context に入れます。

それは間違いではありません。ただ、重すぎます。

ast-outline の発想は、新しい platform や長期常駐の semantic backend を作ることではありません。agent が file を本格的に開く前に、もっと軽い構造ビューを差し込むことです。

• outline で file structure を見る;
• digest で directory や module の要約を見る;
• show で特定 symbol の body だけ抜く;
• grep で AST-aware な構造検索をする。

これによって agent は最初から全文を読むのではなく、先に次の判断ができます。

• この file を本当に開く価値があるか;
• 必要なのは class 全体か、ある method だけか;
• 見たいのは定義位置か、利用位置か;
• この directory は module map だけで十分か。

いわば、

モデルに最初から本文を全部渡すのではなく、先に目次と骨格を渡す。

それがこの project の価値です。

agent に「構造の目次ページ」を与える感じが近いです

ast-outline でいちばん良いと思ったのは、自分の役割を増やし過ぎていないことです。

やっていることは明確で、コード読解の前段に 1 層足すだけです。

README にある比較はかなり分かりやすいです。従来の workflow だと agent は、

1. Player.cs のような大きい file を読む;
2. Enemy.cs も読む;
3. method 名を grep する;
4. さらに別 file を開く;

という流れになりがちです。

ast-outline はこれを、

1. まず directory の digest を見る;
2. 次に単一 file の outline を見る;
3. 必要な symbol だけ show で展開する;
4. 最後に本当に必要な source だけ全文を読む;

という流れに変えようとします。

差は小さく見えますが、長く agent を使っている人ほど効いてきます。

本当に token を燃やすのは、最後の精読より、前段で本来不要だった全文予読であることが多いからです。

RAG でも MCP server でもなく、かなり節度あるローカル CLI です

この project を書き留めておきたいもう 1 つの理由は、その節度です。

README の design section では次の点が強調されています。

• stateless;
• no index;
• no cache;
• no embeddings;
• no network;
• no MCP server。

ここにある考え方はかなり明快です。

作者は「コード理解」を、また別の維持コストを持つ data system に変えようとしていません。多くの場合、十分速く、十分構造化され、十分組み合わせやすいローカル CLI があれば、最初の無駄をかなり削れると見ています。

この判断は面白いです。

AI coding 周辺の project は、どうしても重い方向へ伸びがちです。

• index を作る;
• vector retrieval を作る;
• daemon を置く;
• MCP で包む;
• 長期 cache を持つ。

ast-outline は逆に、もっと Unix らしい答えを選んでいます。

まず、読む前の初手を軽くする。

agent が shell から明確で安定した無状態 tool を呼べるなら、それだけで十分に leverage が出る、という考え方です。

setup-prompt はかなり実務的です

単に command を並べるだけでなく、agent workflow への入り方がうまいです。

README の主な導線は、「人間が command を覚えること」ではなく、agent 自身に次を実行させることです。

ast-outline setup-prompt

そのうえで、対応する snippet を

• AGENTS.md
• CLAUDE.md
• GEMINI.md

や必要なら subagent 用の設定へ入れていきます。

これはかなり現実的です。

こういう tool の典型的な失敗は、機能不足ではなく、

• 作者は強い CLI を作った;
• ユーザーは install した;
• でも普段使う agent がその存在を知らない;
• 結果として従来通り file 全体を読み続ける;

という経路だからです。

ast-outline は install prompt の段階でその断絶を埋めにいっています。つまり想定ユーザーは、たまに shell で単発利用する人ではなく、Codex、Claude Code、Cursor、Gemini CLI を日常的に使う人です。

command 設計が、明らかに agent 向けです

README にある代表的な command は次の通りです。

ast-outline src/
ast-outline digest src/Services
ast-outline show Player.cs TakeDamage
ast-outline grep User.save src/

この command 群の良さは、それぞれの操作範囲が狭いことです。

digest は曖昧に「project を分析する」のではなく、1 ページの module map を返します。show は file 再読ではなく、指定した symbol の body だけを返します。grep も単純な text match ではなく、可能な範囲で AST 構造に沿って match を適切な scope に束ねます。

つまり作者は、agent が本当に必要としているものをよく分かっています。

• もっと多くの text ではなく;
• もっと適切な展開粒度。

この tool が最適化しているのは、モデルの賢さそのものではなく、

モデルに渡す context の形です。

対応言語は広いですが、重点はあくまで構造抽出です

README が挙げる対応言語はかなり広いです。

• Python
• TypeScript / JavaScript
• Go
• Rust
• Java / Kotlin / Scala
• C# / C++
• PHP / Ruby / Lua / Swift
• Vue / HTML / CSS / SCSS
• Markdown / YAML / SQL

しかも「解析できる」だけではなく、class、method、inheritance、imports、symbol body のような構造情報を取り出すことに重心があります。

これは agent にとって重要です。

単なる text slicing では価値が薄いですが、「この type はここ、この method body はここ、この import 群はここ、この directory の輪郭はこう」という見え方を作れれば、context 制御への効き方はかなり変わります。

どんな場面に向くか

ast-outline が特に向いているのは、次のような場面だと思います。

• すでに coding agent を高頻度に使っている;
• repository が玩具規模ではなく、単一 file や module が大きい;
• token cost と context noise の両方を気にしている;
• 追加の index service を管理したくない;
• ローカル CLI と AGENTS.md ベースの監査可能な接続を好む。

特に、agent はコードを書けるのに、既存コードの理解段階で読み方が太り過ぎる、と感じている人にはかなり刺さるはずです。

もちろん、境界もあります

ast-outline は万能ではありません。

これは次のものを置き換える project ではありません。

• IDE の本格的な language service;
• 大規模な cross-repo semantic platform;
• 複雑な rewrite tool;
• 長期 knowledge base や vector retrieval system。

むしろ、前置レイヤーであり、入力整形器に近いです。

だから期待すべきなのは、すべてのコード知能問題を解くことではなく、

agent が乱暴に全文を読む前に、最初の視界を整えることです。

この狭さがあるからこそ、逆に日常 workflow に入りやすいとも言えます。解いている問題が十分に狭く、しかも頻出だからです。

まとめ

ast-outline/ast-outline が面白いのは、「agent 向け tool がまた 1 つ増えた」からではありません。

この project は、かなり地味だけれど確実に何度もぶつかる現実を捉えています。

• coding agent は仕事ができないわけではない;
• ただし、仕事を始める前の context 読み込みが重すぎることがある;
• 初手で膨らめば、その後の推論も編集も高くつく。

ast-outline の答えはとても節度があります。

• ホスト型 service は作らない;
• vector DB も作らない;
• 常駐 backend も前提にしない;
• まずコード構造ビューを正しく出す;
• agent には outline、digest、symbol body を先に見せる。

Codex、Claude Code、Cursor と長く付き合う段階に入っているなら、この project が扱っているのは周辺的な問題ではありません。

agent が本当にコードを読み始める前に、どうやって context を無駄なく整えるか。

その問いに対する、かなり筋の良いローカル CLI だと思います。