この連載は「段階的開示」で作る。迷わないドキュメント設計（連載2/全8章）
第1回では、段階的開示（Progressive Disclosure）がエージェントのコンテキスト設計に効く、って話をしました。
第2回の今回は、それをそのまま 人間向けのドキュメント（学習も含む） に持ち込みます。
というか。
この連載自体を、その設計で作ります。
読者が迷わず読み進められるように、情報の「置き場」を分ける。分ける。分ける。
（最初に言い切るけど、これ、才能じゃなくて仕組みです）
いきなり懺悔。
僕のNotion、昔は「便利な倉庫」だったんですよ。
今は「便利なはずの沼」になりました。
メモがある。
手順もある。
でも、欲しい瞬間に見つからない。
しかも新人（＝未来の自分）が来ると、だいたいこう言う。
「で、どれ読めばいいですか？」
……わかる。俺もそう思う。
「全部書いてある」のに「読めない」。
ここが地獄の入口です。
TL;DR
人間もモデルも、いきなり全部を渡されると迷子になりがちです。学習も運用も止まる。
ドキュメントは Core（本文）/ Reference（辞書）/ Practice（実践）/ Ops（運用） の4つに分けると、読めて・引けて・作れて・更新できます。
章の中も「結論→理由→手順→例→深掘り」で揃えると、集中力が落ちたときでも復帰しやすい。
この記事でわかること
スキル周りのドキュメントを「読める形」にする4つの置き場（Core / Reference / Practice / Ops）
章・節の中でも段階的開示を作る書き方の型
個人利用→チーム共有へスケールさせやすくなる理由
5分でできる小課題（手元の資料を4分類する）
読者の前提
個人でスキルを作って使い始めた人向けです（将来、チームで共有・運用したくなる人も含みます）。
第1回（概観）を読んでいる前提で書きます（が、今回単体でも読めるようにします）。
結論
段階的開示（Progressive Disclosure）は、エージェントだけの話じゃないです。
人間向けのドキュメントにも、そのまま効くと思っています。
「全部書いてある」ことと「読める」ことは違う。
読めるドキュメントにするには、情報の置き場を分けて、必要なタイミングで必要な深さだけ触れられるようにする。
要するに、ドキュメントにも「間取り」が要る。
背景：人間も“いきなり全部”は無理です
初学者にとって、いきなり細かい仕様や例外や運用論が並ぶと、だいたいこうなります。
何が重要か分からない
途中で疲れて離脱する
「結局なにをすればいいの？」になる
これは根性の問題じゃない。
人間の作業記憶（ワーキングメモリ）には限界があって、情報を一気に詰めると学習が止まりやすい。
第1回で言った「巨大プロンプトの破綻」と、構造が似てるんですよね。
（似てる、です。同じとは言わない。ここはちゃんと慎重に。）
ドキュメントの4つの置き場：Core / Reference / Practice / Ops
ここからが本題。
僕がいま推してる置き場は、4つです。
名前は何でもいい。大事なのは「分ける」こと。
便宜上、こう呼びます。
Core : book/ (読むための本文)
Reference : reference/ (引くための辞書)
Practice : project/ (作って理解する実践)
Ops : ops/ (更新と検証の運用)
Core（book/）：読ませるための“道筋”
Coreは「読ませたい順番」がある場所です。
読み物。ストーリー。道筋。
まず結論を言う
次に理由を言う
それから手順を出す
例外？
詳細？
それは、抱えない。抱えない。
（抱えた瞬間に、Coreが辞書になって死にます）
Reference（reference/）：迷ったときに戻れる“辞書”
Referenceは「順番を気にしない」場所です。
必要なときに、ピンポイントで引く。
用語集
仕様の抜粋
チェックリスト
テンプレ
よくある質問（FAQ）
ここがあると、「本文を細くできる」。
これがデカい。
Practice（project/）：作りながら理解する“実践”
Practiceは成果物の置き場です。
章に対応して、少しずつ“手が動く”ようにする。
章1でREADMEを書く
章2でフォルダ分けする
章3で最小のスキルを作る
みたいに、「学習」と「成果物」を結びつける。
読むだけの人が、読んだまま帰らないようにする。
（経験上、ここが無いと理解は霧になります）
Ops（ops/）：更新できるドキュメントにする“運用”
Opsは「壊さないために回す」場所です。
更新ルール、検証手順、差分の追跡。
版管理の方針
回帰チェックの手順
変更ログ（changelog）
テスト（Evals）を置く場所
CIの雛形
地味。
でも、ここが無いと「資産」にならない。
コラム：「読める」と「全部書いてある」は違います
「全部書いてある」は親切に見えるけど、初学者には過剰です。
最初に必要なのは“道筋”。詳細は、あとで拾えれば勝ち。
未来の自分が一番の初学者です
個人で回す段階は、頭の中に前提が残ってる。
だから回る。
でも時間が経つと、前提が揮発する。
そして 未来の自分が一番の初学者 になります。
チームで共有する段階になると、その初学者が増える。
ここで初めて、ドキュメントの構造が効いてくる。
置き場が分かれてると、知識が“移植”しやすい。
これが、スケールの話です。
章の中でも段階的開示を作る（書き方の型）
フォルダを分けるだけだと、章の中が散らかります。
だから章・節の型も揃えます。
おすすめはこれ。
結論（何が大事か）
理由（なぜそう言えるか）
手順（どうやるか）
例（具体）
深掘り（コラム/用語解説/注意）
読み手が疲れてきても、今どこにいるか分かる。
型って、やさしいんですよ。
注意：深掘りを本文に混ぜすぎない
「ここ重要！」を連発すると、集中力が溶けます。
深掘りはコラムや辞書へ逃がして、本文の流れは細く保つ。
エージェント向けの3層と“揃える”と運用がラクになる
第1回で触れた「3層（Discovery / Activation / Execution）」を覚えてますか。
あれと、今回の置き場を“揃える”と、運用がラクになります。
普段は軽く：索引・目次・章の冒頭（Discoveryっぽい）
必要なら読む：Coreの本文（Activationっぽい）
必要なぶんだけ引く/回す：Reference / Ops / Practice（Executionっぽい）
同じ問題（情報の肥大、例外の増殖、更新のつらさ）に対して、
ドキュメント側とスキル側で 同じ対処 ができるようになる。
結果として、破綻しにくい。
（ここ、地味に効きます）
判断基準（チェックリスト）
この設計が効いてるか、次でチェックできます。
Core（book/）が“道筋”になっている（辞書の羅列になっていない）
迷ったときに戻る場所（reference/）が明確になっている
実践（project/）が「章の理解」と結びついている
更新・検証（ops/）が後回しにされていない
余談。Notionは“置き場”を勝手に増やす
Notionって便利じゃないですか。
便利すぎて、置き場を増やせる。無限に。
だから僕は、油断すると「置き場を作ること」が目的になります。
綺麗な棚を作って満足して、肝心の手順が書いてない、みたいな。
（やりました。やったんだよ……）
話を戻す。
置き場は増やすほど良いんじゃない。
置き場は少ないほど強い。4つで十分。たぶん。
やってみよう（5分）：手元の資料を4分類する
あなたの手元の資料（Notion/社内Wiki/README/設計ドキュメント/プロンプト集など）から、次を1つずつ拾って「どの置き場にあるべきか」を考えてみてください。
用語の説明（例：glossary）
セキュリティの要件（例：checklist）
作業の雛形（例：template）
章に対応する成果物（例：project）
分類に迷ったら、こう考えると早いです。
それは“読ませたい”か（Core）
それは“引かせたい”か（Reference）
それは“作らせたい”か（Practice）
それは“壊さないために回したい”か（Ops）
まとめ
段階的開示は、人間向けのドキュメントにも効く（人間も“いきなり全部”は無理）。
ドキュメントは Core / Reference / Practice / Ops に分けると、読めて・引けて・作れて・更新できる。
章の中も「結論→理由→手順→例→深掘り」で揃えると、迷子を減らせる。
次回予告
次回は、スキル側のインターフェース設計です。
SKILL.md とフォルダ構造が“API” だと思って読んでください。
参考（考え方の元ネタ）
Progressive Disclosure（段階的開示）：UI/UXで「まず必要なものだけ見せて、残りは後から出す」という考え方。(Nielsen Norman Group)
Cognitive Load Theory（認知負荷理論）：一度に処理する情報が多いと学習が阻害されやすい、という枠組み。(ScienceDirect)
Diátaxis（ドキュメントの4分類）：Tutorials / How-to / Reference / Explanation の4象限で整理する有名な枠組み（今回の「4つの置き場」と近い発想）。(Diátaxis)
