人向けに書いたドキュメントを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 は構造解析する:
主な流れ:
- 先頭YAML frontmatterを厳密に保持
- heading、code、table、list、HTML、paragraphをblock検出
- 種類ごとに文脈対応のトークン節約整形
- 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"bashuse 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 ignorebashlintはエージェント向けJSONだ:
agent-md lint README.md
agent-md --human lint README.md
agent-md lint --content "# Title\nContent here"
agent-md lint-file README.mdbash合格時の例:
{
"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 serverdiff既定では太字除去、空行圧縮、連続空白圧縮、水平線除去、強調除去、HTML一行化、無名コードに text 付与、空list削除、list indent 2スペース化もする。
ファイル全体を読まずSectionだけ読む#
エージェント向け最良機能だ。700行READMEを全部読まず目的sectionだけ取れる。
# まず構造を見る
agent-md headings README.md
agent-md read README.md --field headings
# Developmentだけ読む
agent-md read README.md --content "## Development"
# 入れ子も可
agent-md read README.md --content "## Development > Build"
# field指定
agent-md read README.md --field content
agent-md read README.md --field word_count
# 検索、統計、JSONL化
agent-md search README.md "TODO"
agent-md stats README.md
agent-md to-jsonl README.mdbash推奨フロー:
# 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 なら再整形不要だ
参考文献#
- 本家: loclv/agent-md on GitHub ↗
- Rustパッケージ: agent-md on crates.io ↗
- Markdown作法:
docs/markdown-writing-rules.mdinagent-mdrepo - エージェント指針:
docs/llm-agent-rule.mdinagent-mdrepo - 拡張: Agent-MD Formatter on VS Code Marketplace ↗
- 関連規格: llms.txt ↗