markdown-search

ドキュメント検索（Context 最適化）

実装・設計・レビューの前に、既存ドキュメントから必要最小限だけを Context に載せる SKILL である。 全文をいきなり読まず、見出し一覧（行範囲）→ 指定範囲 →（必要なら）全文 の順で深さを上げる。

段階の意図は references/context-loading.md を参照する。

いつ使うか

• コーディング・詳細設計・レビュー前のナレッジ収集
• 「どこに書いてあるか」を探すとき
• ### DO: / ### DO NOT: を横断したいとき
• 大きな *.md を読む前に構造だけ把握したいとき

優先して見る配置

リポジトリルート（.git があるディレクトリ）からの相対パス:

• AGENTS.md やRule/Instructionによって指定されたプロジェクト固有ディレクトリ
• docs/: 標準ドキュメントディレクトリ
• README.md: 標準README
• .cursor/skills/
• .agents/skills/
• apm_modules/
• .ai-agent/memory/（場所は workspace-layout / 用途は workspace-agent-temporary）

同梱スクリプト

行範囲付き TOC と範囲抽出は、この SKILL の scripts/md_section.py を使う（Python 3 / 標準ライブラリのみ）。 SKILL_DIR は本 SKILL.md があるディレクトリ（.cursor/skills/・.agents/skills/・packages/.../.apm/skills/ いずれでも可）。

SCRIPT="$SKILL_DIR/scripts/md_section.py"

# Stage 1: 見出し + 行範囲（子見出しを含む終端）
# 内容 SHA-256 が同一のファイルは、先に現れた 1 件だけ対象にする（コピー二重ロード防止）
python3 "$SCRIPT" toc path/to/file.md
python3 "$SCRIPT" toc --max-level 2 path/to/dir
python3 "$SCRIPT" toc --grep 'DO NOT' path/to/file.md

# 内容重複を落とした path 一覧だけ欲しいとき
python3 "$SCRIPT" unique path/to/directory
python3 "$SCRIPT" unique -v path/a.md path/b.md   # 除外した path を stderr に出す

# Stage 2: 指定範囲だけ出力
python3 "$SCRIPT" print path/to/file.md 629 637
python3 "$SCRIPT" print path/to/file.md --at 675
python3 "$SCRIPT" print path/to/file.md --title '循環参照'

path:start-end が既に分かっているときは sed -n 'start,endp' file でもよい。

コードフェンス内の # は見出し扱いにしない。終端は同レベル以上の次見出しの直前（末尾空行は trim）。 toc / unique は既定で内容ハッシュ重複を除外する。意図的に全コピーを見たいときだけ toc --keep-duplicates を使う。

把握手順（3 段階）

Stage 1 — 見出し一覧と行範囲を取る

• 対象 path（ファイルまたは少数の候補）を決め、TOC を取る
• 複数ファイル横断の当たり付けは --max-level 2 から始め、必要ならレベルを下げる
• 出力の path:start-end と見出しテキストだけで関連性を判断する（この時点で本文を読まない）
• HQ / APM で同内容が複数 path にコピーされていることがある。内容ハッシュが一致するファイルは先頭 1 件だけを候補にし、以降の Stage でも同じ本文を二重ロードしない

DO / DO NOT を探すときも、まず TOC か見出し grep で当たりを付ける。 横断検索の前に unique で重複を落とし、一致する内容は最初の 1 ファイルだけを対象にする: