anytime-markdown-usage

name	anytime-markdown-usage
description	anytime-markdown の Markdown ドキュメントを検索・調査・編集・整形する時、特にトークン（cache_read 加重）を抑えたい時に使用する。mcp-markdown の search_docs/search_sections/grep_markdown/get_outline/get_section/update_section/get_frontmatter/update_frontmatter/format_markdown/compute_diff を使う時、検索・調査をサブエージェントへ委譲する時の運用手順と委任プロンプト雛形。

mcp-markdown 利用ガイド（検索・編集のトークン削減）

更新日: 2026-07-11

原則: 加重コストの本丸は「文脈サイズ × 再読込（cache_read）」。Markdown 本文をメイン文脈に載せないことが削減の核心。 mcp-markdown ツールはそれを実現する手段（[[markdown-ext-doc-core-pipeline]] / [[markdown-ext-bundle-mcp-markdown]]）。

A. 検索・編集の使い分け（目的 → ツール）

目的	使うツール	避ける（高コスト）
どのファイルか特定	search_docs（path/title/excerpt/snippet を返す＝開かず判断）	Grep で複数ファイルを開く
節単位で検索	search_sections（見出し＋snippet・search_docs→outline→section を1コールに圧縮）	全文 Read
ファイル内を文字列検索	grep_markdown（行番号＋囲み見出し＋snippet・search_docs の文書内版）	全文 Read して目視
関係をたどる	doc_backlinks / doc_neighbors	多数の frontmatter を Read
ファイル内の場所把握	get_outline（見出し+行番号のみ）	全文 Read
必要な節だけ取得	get_section（maxChars で上限）	全文 Read
frontmatter の取得・更新	get_frontmatter / update_frontmatter（本文を読まず）	全文 Read＋Edit
節を書き換え	update_section（見出し＋新内容のみ）	Read＋Edit（全文＋old_string 再現＝二重コスト）
規約準拠の整形	format_markdown（mode fix/check・差分サマリのみ返す＝本文を載せない）	本文を往復させて手で整形
HTML 無害化・tiptap 往復正規化	sanitize_markdown（整形目的では使わない）	—
変更検証	update_section / update_frontmatter の返却サマリ（追加コール不要）。独立比較のみ compute_diff	両ファイル再 Read
新規作成・全面書き換え	write_markdown（このケースのみ）	部分編集目的の read_markdown→write_markdown 全文往復（最高コスト経路。部分編集は必ず update_section / update_frontmatter）

format_markdown と sanitize_markdown は別物。整形（anytime-markdown-check 規約準拠）は format_markdown。sanitize_markdown は DOMPurify による HTML 無害化＋tiptap ラウンドトリップ用マーカー付与で、整形目的に使うと ZWSP/ZWNJ・ハードブレークを注入してしまう。

黄金ルート: 検索 search_docs/search_sections→snippet で選別→get_outline→get_section。編集 get_section→修正→update_section（返却の差分サマリ oldLines/newLines/bytesDelta/warnings で検証。compute_diff の追加往復は不要）。整形 format_markdown(path, mode="fix")（ルート外は不可）。

B. 注意（実装仕様）

• doc_fts は trigram。検索語・snippet は 3文字以上でないと一致しない（2字語は 0 件）。
• search_docs の既定 limit は 8、snippetTokens 既定 24（trigram トークン≒文字数・最大 64）。多すぎる limit は逆にトークン増。search_sections は query 必須（facet のみの節検索は不可。facet だけなら search_docs）。
• get_section は maxChars で巨大節を切詰め（…(truncated)）。
• 重複見出し: get_section / update_section は同一 level＋text の見出しが複数あると曖昧エラー（行番号一覧つき）。occurrence: n（1-based）で指名する。
• update_section / update_frontmatter は実施サマリを返す（前者: oldLines/newLines/bytesDelta/warnings、後者: setKeys/removedKeys/createdFrontmatter）。warnings に「content が見出し行で始まらない」等が出たら意図どおりか確認する。
• doc_backlinks の type フィルタは references / depends-on / implements / part-of / supersedes / refines の 6 値。
• 検索系は <workspace>/.anytime/markdown/doc-core.db を readonly 参照。未構築なら明示エラー→拡張コマンド「Rebuild Doc Search Index」で ingest 後に使う。

C. サブエージェントへの委譲（検索・調査）

検索・トリアージ・ログ解析は Haiku サブエージェントへ委譲し、メイン（Opus）文脈を保護する。 サブエージェントは CLAUDE.md を継承しないため、本文を返さないルールは委任プロンプトに必ず明記する。

委任プロンプト雛形:

対象: <調査テーマ>。anytime-markdown のドキュメント検索。
ツール: mcp-markdown の search_docs（query/category/type/lang）・doc_backlinks・doc_neighbors・get_outline・get_section を使う。
手順: search_docs の excerpt/snippet で候補を選別 → 必要時のみ get_section で該当節だけ読む。
出力（厳守）: 結論＋関連 path の一覧＋（あれば）該当見出しと1〜2行要約のみ。
**Markdown 本文の貼り付け禁止**。全文 Read 禁止（get_outline→get_section で必要箇所のみ）。

モデル指定は Agent ツールの model パラメータ（model: "haiku"）で行う。プロンプト本文に書いても効かない。

よくある失敗

• snippet を使わず全 Read → snippet 分だけ増えて逆効果。limit 小・snippet で選別してから開く。
• update_section の content に見出し行を含め忘れ → 見出しごと消える。見出し行を必ず含める（返却サマリの warnings が検知するので必ず確認）。
• 同名見出し（「### 例」等の反復）への編集 → 曖昧エラーになる。get_outline で行番号を確認し occurrence で指名する。
• 新しい節の追加は update_section ではできない（既存節の置換のみ）。直前の既存節を get_section で取り、新節を末尾に連結して update_section する（親節ごとの書き換えは不可避に大きいので、隣接する最小の節を選ぶ）。ファイルが小さい（目安 200 行未満）場合のみ write_markdown 全文置換も許容。
• 2文字キーワードで 0 件 → trigram 制約。3文字以上に。