utility-doc-reading

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) を飛ばして解説を始める — 深度の基準がないまま話すと過剰解説になる
• 抽出したすべての用語を確認・解説する — 土台概念だけに絞る
• ドキュメントの改善提案や品質批評を混ぜる — 本スキルの仕事は理解支援のみ。問題に気づいたら末尾で一行報告に留める
• プロファイルにある「既知」概念を再解説する