scaffold-docs

ドキュメントの骨組み作成

ユーザーに各ステップで確認してもらいながら、コードライブラリの技術ドキュメントをトップダウンで段階的に作成します。ドキュメントの執筆は文章を書く作業の一部です。構成だけでなく、文章の質も重視します。

基本原則

これらの原則は、あらゆる判断の指針になります。必ず守ってください。

1. 特定の読者に向けて書く。 ドキュメントは誰かのために書くものです。主な対象読者（フェーズ 1b で選定）が、その後のすべての選択を左右します。ユースケース、骨組み、メリットの伝え方、説明する内容、省略する内容が対象です。全工程で references/audience-check.md を適用してください。副次的な対象読者は、判断が分かれた場合の参考にしますが、主な対象読者より優先されることはありません。
2. メンタルモデルを第一に考える。 ドキュメントで読者に伝えるのは、コードの逐語的な説明ではなく、ライブラリを使うためのメンタルモデルです。何を含めるか、何を省くかを判断する際は、それが読者のメンタルモデルの形成に役立つかどうかを考えてください。
3. パッケージの構成ではなく、ユーザーのメンタルモデルを基準にする。 読者がやろうとしていることに沿って内容をまとめてください。ソースコードのディレクトリ構成が、ドキュメントに適した構成であることはほとんどありません。
4. 何をするかより、なぜそうするかを説明する。 設計上の判断が理解や正しい使い方に関わる場合は、何をしたかだけでなく、なぜそうしたのかも説明してください。意図の根拠として、コードコメント、命名の選択、コードの不自然な点を活用してください。
5. 読者に必要な依存関係だけを示す。 各トピックが何に依存しているかを特定し、そのトピックについて機能するメンタルモデルを形成するために必要な依存関係だけを伝えてください。
6. 段階的に情報を開示する。 読者が使い始めるために、ライブラリ全体を理解する必要があってはなりません。どの段階で読み終えても、役立つメンタルモデルが得られるようにドキュメントを構成してください。
7. 一度で仕上げず、反復する。 各フェーズの最後にユーザーの確認を受けてください。現在の段階をユーザーが承認するまでは、次の作業に進まないでください。
8. 明快で、そっけなくならない文章にする。 成果物には文章の質も含まれます。文章を整える各工程で references/prose-style.md を適用してください。

出力構成

3 つのカテゴリに分けます。それぞれ目的、構成、ファイル配置が異なります。

• 入門：getting-started.md。ライブラリの最も重要なコンポーネントに触れる、代表的なユースケースを 1 つ扱う、物語仕立ての一貫したチュートリアルです。取り組みやすい内容にしてください。読了または実践後、読者が自力で探索を進められるだけのメンタルモデルを身につけている状態を目指します。
• 詳しく学ぶ：diving-deeper/<topic>.md。トピックごとに 1 ファイルを用意します。各トピックでは、まずそのトピックの目的を説明し、次に設計上の判断とその理由を示し、その後、各オブジェクトの目的に沿って関連 API を順に説明します（アルファベット順にはしません）。
• リファレンス：reference/<module>.md。モジュールごとに 1 ファイルを用意します。純粋な API 仕様に近い形式で、クラス、関数、モジュールごとに整理します。物語形式ではなく、必要な情報を素早く探せる構成にしてください。
• メタデータ：.scaffold-docs.yml。対象読者、最後に同期した git SHA、ask_audience フラグを機械可読形式で記録します。フェーズ 1 で書き込み、フェーズ 5 でコード変更後のドキュメント更新時に読み込みます。

ワークフローの概要

Phase 1: Discovery and overall structure          → phases/1-discovery.md         [USER REVIEW]
  (read code → audiences → use case → topic inventory → overall-structure.md)
Phase 2: Build Getting Started in three passes    → phases/2-getting-started.md   [USER REVIEW × 3]
  Pass A: headers + learning bullets + code blocks
  Pass B: sub-headers + paragraph topic sentences (≤20 words, single SVO, no `; : — – ()`)
  Pass C: full paragraphs (using references/prose-style.md)
Phase 3: Build each selected Diving Deeper topic  → phases/3-diving-deeper.md     [USER REVIEW × 2 per topic]
Phase 4: Build Reference                          → phases/4-reference.md         [USER REVIEW per module]
Phase 5: Update existing docs after code changes  → phases/5-update.md            [USER REVIEW per bucket]
  (read .scaffold-docs.yml → baseline diff → classify changes → walk buckets)

このスキルの使い方

各フェーズには、phases/ 内に専用のファイルがあります。現在取り組んでいるフェーズのファイルだけを読み込んでください。

既存のドキュメントを更新しますか？ ドキュメントがすでにあり、コードの変更後に更新するようユーザーから依頼された場合は、フェーズ 1 ではなくフェーズ 5（phases/5-update.md）から始めてください。フェーズ 5 では .scaffold-docs.yml を読み込み、対象読者と最後に同期したコミットを確認します。

フェーズ間でコンテキストをクリアしてもかまいません。 ディスク上の成果物（overall-structure.md、getting-started.md など）が、引き継ぎに使う永続的な情報です。各フェーズのファイルの冒頭には「コンテキストをクリアした状態から再開する」セクションがあり、そのフェーズを開始する前に状況を把握するために読むべきファイルが正確に記載されています。会話が長くなったとき、セッションをまたぐとき、または集中しやすくなる場合に活用してください。

references/ 内の参考ファイルは、必要に応じて読み込みます。

• references/audience-check.md：フェーズ 2 とフェーズ 3 の開始時、およびフェーズ 5 で対象読者が見つかった場合に必読です。フェーズ 1b で選択した主要な対象読者が、すべての執筆上の判断の基準になります。
• references/diving-deeper-heuristics.md：フェーズ 1d でトピックにタグを付ける際と、フェーズ 4 で差し戻しを判断する際に使用します。
• references/headline-style.md：セクション名を決める構成の確認時（フェーズ 1e、フェーズ 2 パス A、フェーズ 3 パス A）に必読です。単なる名詞ではなく、読者の行動に基づいてセクション名を付けます。文章スタイルの確認時に読み込む prose-style より先に読み込みます。
• references/prose-style.md：文章を確認するパスに入る前に必読です（フェーズ 2 のパス C、フェーズ 3 のパス B）。読み込むタイミングは各フェーズのファイルに明記されています。

実行ルール（すべてのフェーズに適用）

• ファイルを保存するときは、必ずファイルパスを表示してください。
• ユーザーが先を急いでいるように見えても、チェックポイントを省略しないでください。このスキルでは、反復的なレビューが重要です。
• 現在のパスを修正するときに、次のパスの内容を書かないでください。ユーザーがパス A で変更を依頼した場合は、パス A を修正してレビューに戻してください。パス B の内容をこっそり加えてはいけません。
• フェーズの作業量が多い場合（例：トピックが 12 件ある「さらに詳しく」フェーズ）は、分割して進めることを提案し、優先順位はユーザーに決めてもらってください。
• コードを文章に言い換えないでください。API の項目がシグネチャから明らかな場合は、その旨を伝えて次に進んでください。考え方に関する説明は、コードを読んだだけでは分からない点を補うためのものです。