| name | utility-doc-reading |
| description | ドキュメント・技術文書を、知識プロファイル (~/.claude/knowledge-profile.md) を参照・更新しながら「ユーザが作業を進められるレベル」まで対話的に読解支援する。「このドキュメントを解説して」「この設計書を理解したい」「読むのを手伝って」「前提知識が足りない」など、単発の Q&A で済まない規模のドキュメント理解で起動。 |
| argument-hint | <ドキュメントのパスまたは URL> |
| user-invocable | true |
ドキュメント読解支援
大量・高密度なドキュメントを、ユーザの知識レベルと目的に合わせた深度で理解できるように導く。ゴールは「ドキュメントの完全理解」ではなく「ユーザが次の作業を進められる状態」。この違いが本スキルの深度調整のすべてを決める。
前提: 知識プロファイル
~/.claude/knowledge-profile.md がユーザの知識の永続記録。毎回の知識確認を減らし、回を重ねるごとに解説がユーザに最適化されていくための仕組み。
- 実体は dotfiles の
claude/knowledge-profile.md (mkOutOfStoreSymlink で ~/.claude/ に配置され、複数マシン間で git 同期される)
- symlink が存在しない場合はプロファイルなしとして進め、末尾で「
drs / hms 未適用のためプロファイルを更新できない」と報告する (勝手に実ファイルを作ると home-manager の symlink 配置と衝突する)
# Knowledge Profile
## 既知 (ユーザが知っていると申告した概念)
<!-- - 概念名 — 一言メモ (YYYY-MM-DD) -->
## 解説済み (本スキルで解説した概念)
<!-- - 概念名 — 解説した要点の一行要約 (YYYY-MM-DD) -->
フロー
1. ドキュメント読み込み
引数のパス / URL を読む。引数がなければ対象を尋ねる。複数ファイルの場合はすべて読み、相互参照関係を把握する。
2. 理解ゴールの確認 (解説より先に、必ず)
AskUserQuestion で「このドキュメントを読んで何ができればよいか」を確認する:
- A. 承認判断だけしたい (最浅: 結論・影響・リスクが分かればよい)
- B. レビューしてフィードバックしたい (中: 設計判断の妥当性を評価できる程度)
- C. 作業を引き継ぐ / 続きを実装したい (深: 構造と挙動を把握し手を動かせる程度)
- D. その他 (自由記述)
このゴールが解説深度の上限になる。以降のすべての解説で「この深さはゴールに必要か?」を自問し、超える詳細はユーザが追加で聞いたときだけ提供する。技術の内部実装を知らなくても、役割と挙動が分かれば作業を進められることが多い — その線で止める。
3. 前提概念の抽出と既知 / 未知の判定
ドキュメントを理解する上で土台になる概念だけを抽出する (登場する専門用語の網羅ではない。それを知らないと本文の議論が追えないもの、の基準で選ぶ)。ゴールが浅いほど抽出も絞る。
各概念を知識プロファイルと突き合わせて 3 分類する:
| 分類 | 判定 | 扱い |
|---|
| 既知 | プロファイルの「既知」に記載あり | 確認せず解説もスキップ |
| 解説済み | プロファイルの「解説済み」に記載あり | 「以前解説しましたが復習しますか?」と軽く確認 (陳腐化対策) |
| 未知候補 | プロファイルに記載なし | ステップ 4 で確認 |
4. 未知候補の確認
未知候補を AskUserQuestion (multiSelect) で提示し、ユーザに「知っているもの」を選んでもらう。概念が 5 個を超える場合は、本文理解への影響が大きい順に絞るかグループ化して、確認の往復が 1〜2 回で済むようにする。
ユーザが「知っている」と答えたものはプロファイルの「既知」へ、それ以外が解説対象になる。
5. 解説とウォークスルー
(a) 未知概念の解説 — 役割・挙動レベルで解説する:
- その概念は何のためにあり (役割)、入力に対してどう振る舞うか (挙動)
- このドキュメントの文脈でなぜ登場するか
- 内部実装・歴史的経緯・代替技術の比較には踏み込まない (聞かれたら答える)
例: 「mkOutOfStoreSymlink」なら —
✅「Nix 管理のファイルをコピーではなく元リポジトリへの symlink として配置する仕組み。これがあるので設定を編集すると再ビルドなしで即反映される。この設計書では live edit を実現する手段として登場する」
❌ Nix store の内部構造、derivation の仕組み、他の symlink 手法との比較表
(b) 本文ウォークスルー — セクション単位で進める:
- 各セクションの要旨をゴールに必要な粒度で示し、解説した概念と本文の記述を結びつける
- セクションごとに「ここまでで質問は?」と区切りを入れ、一方的な長文連投にしない
- ゴールに寄与しないセクション (例: 承認判断ゴールにおける実装詳細の章) は「○○の詳細だがゴールには不要なのでスキップ。必要なら掘ります」と宣言して飛ばす
6. 知識プロファイルの更新
セッション末尾に、今回解説した概念を「解説済み」セクションへ、ユーザが既知と申告した概念を「既知」セクションへ追記する (日付は date +%F で取得)。既存エントリと重複させない。更新したことを一行で報告する。
深掘り要求への対応
ウォークスルー中にユーザが特定の概念を深く聞いてきたら、それは深度上限の一時解除。その質問に限り詳細に答え、答え終わったら元の深度に戻る。深掘りした内容もプロファイルの「解説済み」に反映する。
してはいけないこと
- ゴール確認 (ステップ 2) を飛ばして解説を始める — 深度の基準がないまま話すと過剰解説になる
- 抽出したすべての用語を確認・解説する — 土台概念だけに絞る
- ドキュメントの改善提案や品質批評を混ぜる — 本スキルの仕事は理解支援のみ。問題に気づいたら末尾で一行報告に留める
- プロファイルにある「既知」概念を再解説する
