blog.dopana

戻る

人向けに書いたドキュメントをAIエージェントが毎日読み、星マークや余分な空白にもトークン課金される。心当たりはないだろうか。

問題: Markdownは人を美しく見せるための形式だ。LLMに美しさは不要で、必要なのはコンパクトさ、明確な構造、section単位の取出しやすさだ。agent-mdはそこを直すRust製CLIで、MarkdownをLLMフレンドリーにし、トークンを節約し、人にも読めるままにする。

Agent-mdとは?#

10歳向けに説明すると、友達のためにお弁当を詰めるイメージだ。人には仕切りが多く飾り付けされた箱が嬉しいが、ロボットにはラベルが明確で開ければすぐ取れるコンパクトな箱がいい。agent-mdはロボットのためにお弁当を詰める人だ。

具体的には、agent-mdは以下だ:

  • AIエージェント向けMarkdown整形とlintの高速Rust CLI、単一バイナリ
  • Rustライブラリ (agent_md) として format_markdown、parse_markdown、validate_markdown を提供
  • Agent-MD FormatterというVS Code拡張、保存時フォーマット対応
  • 全コマンドがJSONを返しLLMが parse しやすく、--human で人向け表示

現行バージョンは 0.2.16 で、cargo install agent-md かソースビルドで導入できる。

なぜ普通のMarkdownはトークンを浪費するのか?#

LLM生成のMarkdownは冗長になりがちだ:

  • 装飾の **bold** や italic は機械には意味を足さない
  • 幅広テーブルと長い区切り |----------|、本来は |---| で十分
  • コード内コメントの大量空白: bun dev # run server
  • 空行の連続、水平線 ---、通常文の4スペースインデント
  • [https://example.com](https://example.com) のような無意味リンク
  • 罫線文字の図や手書き風ツリーは parse が難しい

LLMが読むたびに装飾税を払う。ドキュメントが多いリポジトリほど累積は大きい。

仕組みは?#

単純な行フォーマッタではない。agent-md は構造解析する:

Markdown入力YAML frontmatter分離block検出: heading, table, list,code, HTML種類ごとに最適整形17ルールでlintコンパクト出力、必要ならJSON

主な流れ:

  1. 先頭YAML frontmatterを厳密に保持
  2. heading、code、table、list、HTML、paragraphをblock検出
  3. 種類ごとに文脈対応のトークン節約整形
  4. linterで検証し valid、errors、warnings のJSONを返す

Agent-md作法のルール#

linterは17ルールで二群だ。エラーは書込み阻止、警告は修正推奨だ。

よく出るエラー系:

  • no-bold: コード外の **bold** と __bold__ を禁止、下例参照
  • simple-table: 最大5列、区切りは |---|、配置コロン除去
  • table-trailing-spaces: セル内末尾の余分空白を禁止
  • no-ascii-graph: 罫線図を禁止、CSV、JSON、Mermaid、listへ
  • heading-structure: H1は一つ、H1からH3への飛びを禁止
  • code-blocks: 言語指定と閉じfence必須
  • list-formatting: マーカー統一、空item禁止
  • space-indentation: 通常文は最大2スペース、コード免除
  • no-useless-links: リンク文言はURLと別にする

no-boldの例:

This line fails because it has double stars.
Replace with plain text, or use a heading, or use code.
Code blocks may keep their original syntax.
text

警告系は重複見出し、連続空行、見出し前後空行不足、先頭H1不足、末尾改行不足、ハードタブ、行末空白だ。

全文は本家 docs/markdown-writing-rules.md にある。

インストール#

cargo install agent-md

# ソースビルド
cargo build --release
# Binaryは target/release/agent-md

# Rustライブラリとして
# Cargo.toml: agent-md = "0.2.16"
bash
use agent_md::{format_markdown, validate_markdown};

let input = "# Heading\n\nSome text with *emphasis*.";
let formatted = format_markdown(input);
let result = validate_markdown(&formatted);
assert!(result.valid);
rust

実践: FormatとLint#

.gitignore と .markdownlintignore を尊重して単体や再帰整形する:

agent-md README.md
agent-md fmt README.md
agent-md fmt .

# ファイルに効く設定を確認
agent-md config path/to/document.md

# 結合ignore一覧を確認
agent-md ignore
bash

lintはエージェント向けJSONだ:

agent-md lint README.md
agent-md --human lint README.md
agent-md lint --content "# Title\nContent here"
agent-md lint-file README.md
bash

合格時の例:

{
  "valid": true,
  "errors": [],
  "warnings": []
}
json

テーブル前後:

 | Function | Arguments | Return Type | Description |
-|----------|-----------|-------------|-------------------------------|
-| `add()`  | a, b      | i32         | Adds two numbers              |
+|---|---|---|---|
+| `add()` | a, b | i32 | Adds two numbers |
diff

コード内コメントの空白圧縮:

-bun i                      # Install dependencies
-bun run dev                # Run the development server
+bun i # Install dependencies
+bun run dev # Run the development server
diff

既定では太字除去、空行圧縮、連続空白圧縮、水平線除去、強調除去、HTML一行化、無名コードに text 付与、空list削除、list indent 2スペース化もする。

ファイル全体を読まずSectionだけ読む#

エージェント向け最良機能だ。700行READMEを全部読まず目的sectionだけ取れる。

推奨フロー:

# 1. 構造取得
agent-md read README.md --field headings

# 2. 修正箇所を検索
agent-md search README.md "TODO"

# 3. 書く前に検証
agent-md lint --content "# New Title\nValid content"

# 4. 検証付きで書く
agent-md write README.md "# New Title\nValid content"

# 5. 一sectionだけ置換
agent-md write-section README.md --section "## Development" --content "New content"
bash

他に write、append、insert、delete、write-section、list がある。write は自動検証するので規格外を作りにくい。

エージェント運用に組込む#

AGENTS.md に一行足せばエージェントが守る:

After creating or updating any markdown file, always run agent-md lint path/to/file.md to validate before done.
On task completion, update docs, update README.md, and write unit tests.
text

短く言えば、Markdownの読み書き編集は直接編集でなく agent-md CLIを使うことだ。本家 docs/llm-agent-rule.md に統合指針がある。

VS CodeではAgent-MD Formatterを入れ、Markdown保存時整形を有効化する:

{
  "[markdown]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "agent-md.agent-md-formatter"
  }
}
json

[!TIP] LLM生成ドキュメントはcommit前に agent-md fmt を通す。情報を保ったまま多くの場合約20%トークンを減らし、読取高速化と課金削減になる。

使わない方がいい場合#

  • 人の印刷見栄え優先で凝った表配置が必要: 人版を残し、エージェント用に compact 版を作る
  • ASCII図がチーム文化: Mermaidへ移し人と機械の両読可能にする
  • 既にvalidなファイル: lint が valid なら再整形不要だ

参考文献#