- 公開日:
GridgramをAIエージェントフレンドリーにする
- Authors
- Name
前回の記事でGridgramのコンセプトと基本的な使い方を紹介した。今回は、このCLIツールを「AIエージェントから使いやすい状態」にするために取り組んだことを記録する。
CLIツールを作ることと、AIエージェントがそのツールをうまく使えることは別の話だ。エージェントはドキュメントを読み、コマンドを試し、診断結果を解釈できなければならない。それを可能にするには、CLIの設計段階からエージェントを意識した工夫が要る。
AIエージェントへのツール提供は試行錯誤の段階にある
本題に入る前に、前提を共有しておく。
AIエージェントに対するツール側の能力提供は、まだまだ発展途上の領域だ。どの粒度でドキュメントを渡すのが効果的か、どの形でコマンド群を配布するのが自然か、といった知見はこれから積み上がっていく段階にある。「このやり方が正解」と言える定型は、現時点では存在しない。
Gridgramでも、現時点で有効そうに見える経路をいくつか試し、手応えを観察している段階だ。本記事では、その試行錯誤の内容を取り組みごとに紹介する。
取り組みの全体像——2系統のアプローチ
Gridgramで実施したAIエージェント対応を整理すると、大きく2系統に分かれる。
ドキュメント系——.gg DSLの書き方やCLIの使い方を、AIが参照しやすい形に整えて提供するもの:
- llms.txt / llms-full.txt のWeb公開
- Context7 への登録（MCP経由で検索可能にする）
gg llmサブコマンド（手元でLLM向けリファレンスMarkdownを取り出す）
コマンド（スキル）系——AIエージェントが作業の中で呼び出せるワークフローやサブコマンド:
- Skills（Anthropic Claude Marketplace /
gh skill installの2経路で配布） gg iconsサブコマンド（エージェントがアイコン検索に使う）
この区別が後の説明の軸になる。ドキュメント系は「エージェントが知識を得るための経路」、コマンド系は「エージェントが作業を実行するための経路」だ。
なお、これらの出口を複数持つことは、逆に言えば「同じ情報を複数の場所に保つ」ことを意味する。手で同期すれば必ず内容がずれる。この問題への答えが、後述するSSOT（単一情報源）からの自動派生だ。
ドキュメント系の取り組み
llms.txt / llms-full.txt——Web公開のLLM向けドキュメント
llmstxt.orgが提唱するパブリック標準に対応した。サイト直下の/llms.txtにリンク集Markdownを、/llms-full.txtに全文連結を配置する。
curl https://gridgram.ideamans.com/llms.txt
curl https://gridgram.ideamans.com/llms-full.txtこれはVitePressで構築したドキュメントサイトのビルド前に生成スクリプト（bun run build-llms-txt）を走らせる形で実現した。生成物はgitignoreとし、毎回のビルドで作り直す。
Context7——MCP経由のドキュメント配信
Context7はUpstashが提供するMCPサービスだ。リポジトリにcontext7.jsonを置いてAdd Docsから登録すると、Context7側がドキュメントをクロールしてMCP経由で各種エージェントに配信してくれる。
{
"$schema": "https://context7.com/schema/context7.json",
"projectTitle": "gridgram",
"description": "Grid-based diagram rendering library and CLI...",
"folders": ["docs/en", "examples", "src/generated"],
"excludeFolders": ["docs/.vitepress", "docs/public", "docs/ja", ...],
"rules": [
"Use `doc { … }` command statements. The legacy `%%{…}%%` form is removed.",
"Built-in Tabler icons are referenced as `tabler/<name>` (outline) or `tabler/filled/<name>` (filled).",
"Diagnostics are warnings, not exceptions. An SVG with diagnostics is still a valid render.",
...
]
}foldersにsrc/generatedを含めているのは、後述のgg llmが生成するllm-reference.md（CLIリファレンス）をContext7にも読ませるためだ。人が書いたドキュメントだけでは拾えないCLIの詳細仕様が検索でヒットするようになる。
rules配列の設計にも意図がある。「コードを読めば当然わかること」ではなく、「ハマりやすい落とし穴」だけを5〜10本に絞って書く。doc { }の記法（旧来の%%{…}%%記法の廃止）や、ダイアグノスティクスがエラーではなく警告である点など、実際にエージェントが間違えやすいポイントを選んだ。
Context7のMCPツールをAIエージェント（例: Claude Code）に設定しておけば、エージェントは.ggファイルの記法について質問したとき、自動的にリポジトリのドキュメントを参照できる。
gg llm——手元でリファレンスを取り出すサブコマンド
gg llmはエージェントが実行時に叩くというより、ドキュメント配布パイプラインの一部として機能するサブコマンドだ。
gg llm
gg llm --format json実行すると、.ggのDSL文法、CLIオプションの一覧、doc { }ブロックの設定キー、代表的な使用例をひとつのMarkdownドキュメントとして出力する。この出力物がllms.txt / llms-full.txt / Context7 / Skills内のリファレンスに使われる。
バイナリとしてコンパイルしたときも、生成済みのMarkdownが静的に埋め込まれているので同様に動作する。オフライン環境のエージェントが自習のために叩く使い方も想定しているが、主眼はパイプラインでの利用だ。
SSOT（Single Source of Truth）設計——情報を1か所から自動派生する
ドキュメントの出口が llms.txt・llms-full.txt・Context7・Skills内リファレンス・gg llm出力と複数になると、人力で同期するのはすぐ破綻する。CLIのオプションを1つ変えたとき、それを5か所に反映するのは現実的ではない。
そこで、すべての派生物をソースコードから自動生成する構造にした。具体的には、次のような派生構造になっている。
src/gg/dsl.ts（BNF文法コメント）、src/cli/args.ts（CLIオプション定義）、src/templates/llm-reference.template.md（テンプレート）、examples/*.gg（サンプル群）の4つがSSOTだ。これらを原本としてbun run ai:regen（または/regen-aiスキル）を実行すると、src/generated/llm-reference.md・src/generated/icon-index.json・docs/public/llms.txt・docs/public/llms-full.txtの4つが自動生成される。
派生ファイルは直接編集せず、原本を修正してからbun run ai:regen（または/regen-aiスキル）で再生成する。
このポリシーを強制するために、.claude/rules/ai-artifacts-policy.mdというClaude Code向けのルールファイルをリポジトリにコミットしている。Claude Codeがセッションを開始するたびにこのルールを読み込み、派生物への手動編集を防ぐ仕組みだ。
さらにregen-triggers.mdというルールファイルもある。こちらはfrontmatterのpaths:で対象ファイルを指定し、SSOTに当たるファイルを編集したセッションでだけ読み込まれる。「/regen-aiを実行してください」とリマインドする役割で、常駐ルールにするとノイズになるため、必要なときだけ表示される設計にしている。
コマンド（スキル）系の取り組み
Skillsの設計——エージェントが呼び出せるワークフロー
Gridgramはリポジトリ内にplugins/gridgram/ディレクトリを持ち、4つのスキルを定義している。
| スキル | 役割 |
|---|---|
gg-render | .ggファイルをSVG/PNG/JSONにレンダリング |
gg-icons | Tablerアイコンの検索ワークフロー |
gg-author | 説明文から.ggファイルを作成してレンダリング |
gg-install | gg CLIをGitHubリリースから導入・更新 |
各スキルはSKILL.mdというMarkdownファイルで定義する。frontmatterにはスキル名・説明・ライセンス・互換性要件・許可ツールを書き、本文にはAIエージェント向けのワークフロー手順を書く。
---
name: gg-render
description: Render a .gg file to SVG, PNG, or a JSON envelope using the gridgram CLI.
license: MIT
compatibility: Requires the gridgram `gg` CLI on PATH.
allowed-tools: Bash(gg:*) Bash(bun:*) Read Write
---Agent Skills標準フィールドのみを使う
ここで重要な設計判断がある。SKILL.mdにはAgent Skills標準フィールドのみを書くという方針だ。
Claude Code固有の拡張フィールド（disable-model-invocation、argument-hint、pathsなど）はmetadata.claude-code.*以下にのみ記述する。こうすることで、同一のSKILL.mdがClaude Code、GitHub Copilot、Cursor、Gemini CLI、Codexのいずれでも動作する。
このポリシーを維持するためにscripts/validate-plugin-skills.tsという検証スクリプトを自作し、CIで必ず通過させている。検証項目はnameフィールドと親ディレクトリ名の一致、descriptionの文字数、必須キーワードの有無、plugin.jsonのバージョンがpackage.jsonと一致しているかなどだ。
配布経路——Anthropic Claude Marketplaceとgh skillの2系統
Anthropic Claude Marketplace経由
Anthropic Claude Marketplace経由でClaude Codeにインストールするには2リポジトリ構成を採用した。
ideamans/gridgram（本体リポ）
└── plugins/gridgram/ ← プラグイン本体
ideamans/claude-public-plugins（別リポ）
└── .claude-plugin/marketplace.json ← git-subdirで本体を参照マーケットプレイスリポがgit-subdirで本体リポのplugins/gridgramを参照するため、本体リポを更新するだけでマーケットプレイスにも自動で反映される。
/plugin marketplace add ideamans/claude-public-plugins
/plugin install gridgram@ideamans-pluginsgh skillコマンド経由
GitHubが追加したgh skillコマンドにも同じSKILL.mdで対応できる。
gh skill install ideamans/gridgram plugins/gridgram/skills/gg-render --agent claude-code
gh skill install ideamans/gridgram plugins/gridgram/skills/gg-icons --agent copilotgh skill installは実行時にリポジトリ情報（repository、ref、tree SHA）をfrontmatterに注入する。この仕組みにより、gh skill updateがバージョン変更を検出できる。本体リポでSKILL.mdを更新すれば、ユーザー側はgh skill updateを実行するだけで最新版を取得できる。
Agent Skills標準フィールドのみというポリシーが、ここでも活きてくる。同じファイルをClaude CodeとCopilotで共有できるため、「エージェントホストごとにSKILL.mdを別々に管理する」という手間がない。
gg-installスキルによるggコマンドの導入
配布を意識してgg-installスキルも用意した。スキルをインストールしてもggコマンドがPATHにないと動かない。gg-installはOSとアーキテクチャを自動検出してGitHubリリースから適切なバイナリをダウンロードし、書き込み可能なディレクトリに設置する。
gg icons——AIエージェントが実行時に叩くアイコン検索
gg iconsは、エージェントが実行時に呼び出すサブコマンドだ。GridgramにはTablerアイコン6,000種類以上が組み込まれているが、その中から目的のアイコンを探すのは人間でも難しい。エージェントが総なめで検討するのは不可能だ。
# キーワードで意味的に検索
gg icons --search database --limit 10 --format json
# タグで絞り込む
gg icons --tag cloud --limit 15
# 使えるタグの一覧
gg icons --tags --limit 30--searchはアイコン名・ラベル・タグ・カテゴリを横断するファジー検索で、スコアで結果をランキングする。エージェントはgg-iconsスキルの手順に従い、まず--tagsでドメイン関連の語彙を確認し、--searchで候補を絞り込むというフローを取れる。
この検索インデックス（src/generated/icon-index.json）はTablerアイコンのJSONダンプに加え、src/data/icon-tags.jsonという手書きのタグ補完ファイルから生成している。Tablerのメタだけでは拾えない語（cache、kubernetes、loadbalancerなど）をここで補っている。なおicon-index.jsonもSSOTから自動生成される派生物の一つだ。
プロジェクトローカルなClaude Code環境
プロジェクトローカルな.claude/ディレクトリにも仕掛けを入れている。これはリポジトリにコミットしてあるので、チームの誰がチェックアウトしても同じ環境が再現する。
.claude/
├── rules/
│ ├── ai-artifacts-policy.md # 派生物の手編集禁止ポリシー（常駐ロード）
│ └── regen-triggers.md # SSOT編集時にだけ読まれるリマインダー
└── skills/
└── regen-ai/
└── SKILL.md # /regen-ai スラッシュコマンド/regen-aiスキルはbun run ai:regenの実行、型チェック、テストの3ステップをまとめたものだ。SSOTを変更したあとにこれを実行すれば、すべての派生物が整合性を保って再生成される。
AI時代のCLIツール設計——今回の試行から見えたこと
今回の取り組みを通じて、「AIエージェントフレンドリーなCLIツール」に共通して必要な要素が見えてきた。ただしこれらはあくまでも現時点での仮説であり、実際にエージェントとの協働の中で検証を続けている段階だ。
1. ドキュメントの出口を複数持つ Web公開（llms.txt）・MCP（Context7）・CLIコマンド（gg llm）・Skills内リファレンスという複数の経路を用意することで、エージェントの環境や状況に関わらずドキュメントへのアクセス手段を確保できる。
2. SSOTと自動派生で情報の整合性を保つ 出口が増えるほど同期の問題が深刻になる。ソースコードを正とし、すべての出口をビルドスクリプトで自動生成する構造が必要だ。
3. セマンティック検索のサポート 6,000件のアイコンをキーワード・タグで絞り込めるgg iconsのように、大量の選択肢をエージェントが効率よく探せる仕組みが重要だ。
4. 決定論的な出力とエラー情報 Gridgramは--diagnosticsフラグで配置上の問題をJSON形式でstderrに出力する。エラーが起きても途中経過のSVGを返し、診断情報を別途提供することでエージェントが修正のループを回しやすくなる。
5. ポータブルなスキル定義 特定のエージェントホスト固有の仕様に依存しないAgent Skills標準フィールドで書くことで、Claude Code、GitHub Copilot、Cursorなど複数のエージェント環境に同一のスキルを提供できる。
Gridgramはまだ開発中のツールだが、この一連の取り組みは「CLIツールをAIエージェントと一緒に使う」という新しい開発スタイルの実験でもある。
- 公式ドキュメント（日本語）: https://gridgram.ideamans.com/ja/?utm_source=notes.ideamans.com&utm_medium=owned_media&utm_campaign=regular&utm_content=gridgram-ai-agent
- GitHub: https://github.com/ideamans/gridgram
コンセプト編はこちら: Mermaid風のテキストから図解を生成するGridgram