Ontology Atlas：codebase の意味も git diff に乗せる
AI coding agent が速く code を変えられるほど、review は単に diff を読むだけでは足りなくなる。Diff はどの行が変わったかを示す。Agent summary は agent が何をしたと言っているかを示す。ただ、その間に抜けやすい層がある。この code はどの product capability に属するのか。なぜこの boundary があるのか。ここを変えるとどの module や検証観点に影響するのか。どこまでが evidence で、どこからが推測なのか。
今日見るのは wlsdks/ontology-atlas。これは新しい code index ではなく、repository の中に atlas/ Markdown folder を置き、固定された node type と relation で codebase の「意味の層」を書く project だ。人間は desktop app で map を見て編集し、review できる。Agent は MCP 経由で読み、query し、update を提案できる。最終的に受け入れるかどうかは git diff に戻る。
GitHub repository API、README、LICENSE、package.json、release API、tags、commits feed を 2026-09-01 18:06 Asia/Shanghai 時点で確認すると、wlsdks/ontology-atlas は 86 stars、14 forks。主要言語は TypeScript、license は MIT、default branch は main、repository 作成日は 2026-04-29 12:21:36 UTC、latest push は 2026-09-01 09:57:48 UTC。main の最新 commit は f734c4d、commit time は 2026-09-01 09:51:48 UTC、内容は fast-sensor lane と one-shot verification reminder hooks。最新 GitHub Release は v1.0.2、published time は 2026-09-01 07:57:14 UTC。package.json の version も 1.0.2 で、source checkout の runtime requirement は Node.js >=24 <25 だ。
プロジェクト概要
| 項目 | 内容 |
|---|---|
| リポジトリ | wlsdks/ontology-atlas |
| 位置づけ | Codebase 向け local Markdown ontology、visual app、CLI、MCP server |
| Stars | 86 |
| Forks | 14 |
| 主要言語 | TypeScript |
| ライセンス | MIT |
| 作成日 | 2026-04-29 12:21:36 UTC |
| Latest push | 2026-09-01 09:57:48 UTC |
| 最新 commit | f734c4d、2026-09-01 09:51:48 UTC |
| 最新 Release | v1.0.2、2026-09-01 07:57:14 UTC |
| 実行要件 | Desktop download は MCP server 同梱。Source path は Node.js >=24 <25 |
| キーワード | codebase ontology、MCP、local-first、impact analysis、AI agents |
code と intent の間を埋める
多くの team には、すでに十分な source-level information がある。Language server は symbol を知っている。grep は文字列を探せる。AST tool は call graph を描ける。CI は test が通るかを教えてくれる。ただし、それらは普通、「この file は checkout capability のどこに関係するのか」「この boundary はなぜ越えてはいけないのか」「agent がここを変えた後、business level で何を検証すべきか」までは答えない。
Ontology Atlas は、その判断を repository 内の Markdown ontology として残す。README では、author が書ける node を project、domain、capability、element、document に絞っている。Relation や evidence も file frontmatter に書かれる。この制限が大事だ。何でも書ける wiki でも、agent が自由に積む memory でもなく、review できる semantic claim を普通の file にする。
この形は AI agent workflow と相性がよい。Agent は directory を素早く読み、patch plan を作り、summary を生成できる。しかし「どの意味が人間に受け入れられた状態なのか」を自然には保持しない。Atlas はその層を repo に固定する。次の agent task の前に、MCP server へ capability、boundary、dependency、unknown を聞ける。Agent が作業した後は ontology update を提案でき、人間は diff で受け入れるかを決められる。
MCP は飾りではなく主要 interface
この project で面白いのは、ontology を人間向けの図だけにしていないところだ。mcp/README.md はかなり具体的で、MCP server は stdio 経由で tool を公開し、Claude Code、Cursor、Codex、その他 MCP client が code の横にある Markdown vault を読み、query し、保守できる。compile_ontology と query_ontology は Markdown を deterministic runtime graph artifact に変換する。別の backend database を立てる設計ではない。
つまり、これは codebase meaning layer の shared state に近い。人間は desktop app の map、architecture、docs、insights、projects、git history を見る。Agent は同じ vault から compile された query result を読む。二つの別 system を同期するのではなく、同じ versionable Markdown file を別々の interface で扱う。
Security boundary も控えめに書かれている。MCP server は現時点で local stdio であり、local HTTP service ではない。Write tool には expected mtime、dry-run、confirm、overwrite、force などの guard がある。Destructive dry-run は machine-readable な decision fields を返す。Agent に project semantics を書かせる tool では、このあたりの細部が「MCP 対応」という表札より重要になる。
なぜ別の knowledge base ではないのか
README は、これは general-purpose ontology editor ではなく、wiki でも agent memory でも code index でもない、と何度も線を引いている。この narrowness はむしろ強みだ。General knowledge base は「何でも書けるが、最後は誰も保守しない」になりやすい。Agent memory は「model が書いたものを誰が判断するのか」が曖昧になりやすい。Atlas は arbitration point を git に戻す。追加や変更された意味の claim は、code と同じように diff、comment、revert できるべきだ、という立場だ。
既存の code understanding tool を置き換えるものでもない。より自然な使い方は、「どの構造的な質問をすべきか」を決める層として使うことだろう。たとえば checkout flow を変えるなら、Atlas はそれがどの capability に属するか、どの domain に依存するか、どの architecture rule や stale evidence を見るべきかを agent に教えられる。その後は grep、LSP、test、人間の review で具体的な code を確認する。
この boundary は、one-shot question より long-running project に向いている。新しい repo では初期コストが重く見えるかもしれない。一方、何度も agent に変更させ、document と reality がずれ始めた repo では価値が見えやすい。中心にある問いは「すべての code を自動理解できるか」ではなく、「team が小さく明確で、agent も使える project meaning map を保守できるか」だ。
install と利用経路
README では desktop app が主な入口になっている。macOS 版は signed and notarized の app で、download bundle に compiled MCP server が入っている。Windows x64 は public beta で、しかも unsigned なので、SmartScreen や managed work PC の policy に止められる可能性があると明記されている。Source checkout も使えるが、package.json は Node.js 24.x を要求する。
また、project は npm で配布されていない。npx ontology-atlas は入口ではない。TypeScript、CLI、MCP という組み合わせを見ると npm package を探したくなるが、現在の理解としては、desktop app が server を同梱し、source checkout は fallback、agent config は app または CLI が local file として書く、という形だ。
向いている人
一つ目は、coding agent をすでに深く開発に入れている team だ。単発の agent patch は review できる。難しいのは、それが何度も続いた後、project boundary、capability description、verification checklist、architecture intent が summary の山に埋もれることだ。Atlas はそれらを maintainable asset にしようとしている。
二つ目は、local-first と auditability を重視する人だ。Project semantics は cloud service ではなく repository の Markdown として残る。Branch できる。Commit できる。Review できる。Revert できる。Agent も MCP 経由で同じ material を読む。
三つ目は、impact analysis が必要な人だ。ただし、単なる import graph ではない。より product / architecture semantics に近い blast radius だ。ある capability を変えると、どの boundary、document、element、unknown を一緒に見るべきか、という問いに向いている。
Caveats
第一に、ontology の保守には discipline が必要だ。Tool は graph を描けるし、agent は update を提案できる。しかし何を capability と呼ぶか、何が implementation detail なのか、どの evidence が十分なのかは、人間が判断し続けなければならない。この review habit がなければ、別の古びる document になる。
第二に、project はまだ若い。Repository は 2026-04-29 作成で、commit と release は非常に活発だが、real team での長期運用経験はこれから積まれる段階だろう。Core repository に入れる前に、boundary がはっきりした subsystem で試すのがよい。
第三に、install path は普通の npm CLI より軽くない。Desktop app が primary path で、Windows は unsigned beta。Source checkout は Node.js 24.x が必要だ。これは気軽な one-command utility というより、agent を真面目に使う team の workbench に近い。
まとめ
wlsdks/ontology-atlas が面白いのは、AI agent 時代の review pain をかなり具体的に扱っている点だ。Code は速く変わる。その一方で、「この code は今何を意味しているのか」も versioned artifact として扱う必要がある。Atlas はすべてを自動理解すると約束しない。小さく reviewable な Markdown vault に project meaning layer を押し込み、desktop app、CLI、MCP で人間と agent を同じ state に接続する。
もし team がすでに agent に cross-file、cross-module の作業を任せ始めているなら、Ontology Atlas は追っておく価値がある。Cost は低くないが、問題設定は鋭い。長期的に保守すべきなのは code diff だけではなく、その diff が触った capability、boundary、verification responsibility でもある。
プロジェクトアドレス：https://github.com/wlsdks/ontology-atlas