write-manual

マニュアルを書く

マニュアルでは、プロトコル、ファイル形式、ランタイムなど、1つの対象を特定のバージョンに絞って説明します。レッスンでは概念を教えて次へ進みます。マニュアルでは、本文で一度も取り上げていない状況でも読者が対象の動作を予測できるようになるまで、1つのシステムを掘り下げます。

このスキルでは、そのための手順をすべて説明します。調査、情報源の優先順位付け、情報源間の不一致を記録する台帳を扱います。また、オフラインのキャプチャキット、固定のセクション形式、文章の制約、TOTAL 0 を報告しなければならない監査についても説明します。どのリポジトリでも利用できます。AI Engineering from Scratch リポジトリでは、ツールがすでに用意されており、manuals/a2a-101/ に実例があります。

使用する場面

• 読者が、1つのシステムの1つのバージョンについて、本文で示していない状況での動作を予測する必要がある場合。
• 対象に仕様、スキーマ、または特定のコミットに固定できるソースツリーがある場合。
• 対象または忠実な代替手段をオフラインで実行し、リクエストとレスポンスを記録できる場合。
• 図を含めて60〜100ページの成果物を作成し、他の人が保守する場合。

使用しない場面

• アテンションや検索拡張など、一般的な概念を教える場合。代わりにレッスンを書いてください。
• 対象を特定のバージョンに固定できない場合、または毎週変更される場合。
• 対象を実行できず、出力も記録できない場合。キャプチャのないマニュアルはエッセイです。
• 短いハウツーを作成したい場合。セクションが約15未満のマニュアルには、この形式は必要ありません。

101マニュアルの規模

項目	目標
ページ数	60〜100
パート数	6〜8に、リファレンスパートを1つ追加
セクション数	約25
図の数	30〜40
manual.json の学習成果	3つ以上
セクションごとの要点	ちょうど1つのブロックに、2項目以上

実例は7パート、28セクション、7つのリファレンスセクション、31の図で構成されています。

手順

1. 対象を固定します。 バージョン、ソースURL、コミット、リリース日、確認日を記録します。
2. 情報源に優先順位を付けます。 スキーマまたは proto、仕様、プロジェクトのドキュメント、リファレンス SDK、キャプチャキットの順に列挙します。
3. ライセンスで許可されたものを取り込みます。 引用可能な各情報源を変更せずに research/sources/ にコピーし、そのライセンスファイルも隣に置きます。
4. 事実の概要を作成します。 使用するすべての規則を、セクションと行番号に基づいて research/ に索引化します。references/research-and-sources.md を参照してください。
5. 不一致の台帳を開きます。 2つの情報源の食い違いが見つかるたびに、ID（D1、D2、...）を付けます。
6. キャプチャキットを構築します。 対象をオフラインで動かし、決定的なファイルを capture/out/ に書き込みます。references/capture-kit.md を参照してください。
7. 仕様に基づいて目次を計画します。 各セクションには、読者が仕様から見つけられる1つの事柄を名前として付けます。
8. manual.json を作成します。 対象の固定情報、学習成果、パレット、優先順位を付けた情報源、引用元、キャプチャコマンド、パートを記入します。references/manual-json.md を参照してください。
9. 前付けを書きます。 タイトルを「このマニュアルの読み方」とし、以下の「前付け」の順序に従います。
10. セクションを1つずつ書きます。 以下のセクション形式を使います。掲載内容はすべてキャプチャファイルから切り出します。
11. 各図はキャプチャをもとに描きます。 以下の図の必須要件と、同階層の blueprint-figure スキルに従います。
12. ビルドして監査します。 監査結果が TOTAL 0 と表示されるまで、すべての指摘を修正します。references/audit.md を参照してください。
13. 判断に基づいてコミットの大きさを決めます。 図と追加するキャプチャを含むセクションを、適切な単位とします。

仕様書に基づいて目次を計画する

仕様書で使われている名称から目次を作り、各パートで何を示すのかを決めます。

• 前付け。 1つの文書 front.md を用意し、タイトルを「このマニュアルの読み方」とします。
• パート1、対象を1ページで。 2つのセクションを設けます。対象が標準化する内容と、キャプチャから取り出した完全なやり取りです。
• 中間のパート。 対象の各レイヤーに1つずつパートを設けます。たとえば、ディスカバリー、データモデル、オペレーション、バインディング、セキュリティ、拡張機能です。
• 最終パート、実装。 クライアントとサーバーを構築します。両方を公式の適合性テストツールでテストし、前のバージョンからの移行について説明します。
• リファレンスパート。 メソッドの表、オブジェクト、状態、エラー、用語集、出典と矛盾点、図の索引を含めます。

各セクションのタイトルには、仕様書に登場するオブジェクト、オペレーション、バインディング、ヘッダー、エラー、拡張機能の名称を使います。「CancelTask と終端状態」は適切なタイトルです。「状態マシン」は適切ではありません。仕様書ではその名称のオブジェクトが定義されていないからです。一般的な概念は、それを持つオブジェクトについてのセクションに記載します。

前付け

front.md では、次のトピックをこの順序で扱います。

1. 対象読者と、マニュアルを読み終えたあとにできること。
2. 作成方法と、出典の優先順位を示す表。
3. キャプチャキット。
4. 引用形式、リストの抜粋、IDの短縮に関する規約。
5. 読者がオフラインで試せる最初の実行。
6. パートの順序。空の parts ブロックとして記載します。
7. 図の色。空の palette ブロックとして記載します。
8. 図0.1。このマニュアルの矢印と色の文法を説明します。

セクションの構成

各セクションファイルは、次の順序に従います。リファレンスセクションと前付けには、主張と出典の行が必要ですが、成果文と要点は不要です。

1. # Title。仕様書で使われている名称にします。
2. タイトルの直下に > Thesis。セクションで証明する主張を、30語以内の1文で記します。
3. 読者が実際に経験した具体的な状況から始まる導入段落。
4. 最初の2段落以内に「このセクションを読み終えると、……できるようになります。」という文を入れます。
5. 本文：## の小見出し、**用語：** で始まる定義、図、リスト、規則、表。
6. takeaways ブロックをちょうど1つ設け、2つ以上のアクションを記載します。
7. Sources: で始まり、セクションの執筆に使ったすべてのファイルを挙げる最後の段落。

完全なテンプレートは references/section-template.md にあります。

フェンス付きブロックの種類

フェンス	内容	必須キー
figure	IDで指定した図1点	id、kind、title、claim、caption
listing	1つのキャプチャファイルから抜粋した行	title、source、lang、任意の note、続いて --- と行
rule	一語一句照合した引用1点	label、source、続いて --- と引用
takeaways	セクションのアクション	2行以上の - item
parts、palette、figure-index、contents	生成される表	本文なし

それ以外のフェンスにはすべて言語タグが必要です。json、jsonl、http、sse のフェンスは、代わりに listing にする必要があります。

Markdown のサブセット

すべてのエディションで同じように表示されるよう、次の構文だけを使います。

• 1行目に # のタイトルを1つ置き、その下に主張の引用を置きます。
• ## と ### の見出し。それぞれに {#anchor} を任意で付けられます。
• 段落と、1階層の - または 1. のリスト。
• ヘッダー行のあるパイプテーブル。
• 太字、斜体、インラインコード。
• {{key ref}} 形式の引用、[text](#s-5-3) 形式の相互参照、リポジトリへのリンク。

生の HTML、水平線、入れ子のリスト、#### の見出し、その他の引用ブロックがあるとビルドに失敗します。セクションアンカーは s- の後に、ドットをハイフンに置き換えたIDを続けたものです。たとえば s-1-4 や s-r-2 です。

リスト

• capture/out/ 内のファイルから各リストを切り出してください。リクエストやレスポンスを記憶から書いてはいけません。
• リストの各行は、ソースファイルに記載されたとおりにしてください。
• 切り出した箇所には、単独の行または行内に … を付けてください。
• 切り出した内容を note に記載してください。
• 読者が全記録を開けるよう、source にソースファイル名を記載してください。

ソース、引用、競合

• sources を権威の強さ順に並べてください。2つのソースが異なる内容を示す場合は、上位のソースを採用し、その旨を本文に記載してください。
• 規則を一字一句そのまま引用し、キーを付けてください。"quoted text" {{spec §3.1.5}}。
• すべての引用キーを quoteSources で宣言してください。キーに、同梱したファイルを対応付けるか、ソースを同梱できない場合は null を割り当ててください。
• SDK など、キーが null のソースは言い換えてください。引用してはいけません。
• ソース間に相違がある場合は、該当セクションで両方の内容を引用し、マニュアルでどちらを採用するかを明記して、レジスターの項目にリンクしてください。
• レジスターはソースの参照セクションに含めてください。列は id、sources、choice、sections、upstream status の5つにしてください。
• 他のガイド、コース、書籍の名前を出したり、引用したりしてはいけません。仕様、ソースコード、論文、対象自身のドキュメントを引用してください。

文章の制限

制限	値
1文あたりの単語数	最大25語
論旨	最大30語、1文
図の主張	最大28語、ピリオドで終わる1文
要点	最大20語、命令形
段落あたりの文数	最大6文

仕組みについて、読者に向けて書いてください。用語は一度定義し、以降は同じ用語を使い、用語集に追加してください。引用、コード、出典表記は制限の対象外です。

セミコロン、省略形、em ダッシュ、en ダッシュを使わないでください。may という単語を書いてはいけません。「can」を使うか、条件を明示してください。references/prose-rules.md に記載された禁止語は避けてください。

図に必須の要件

兄弟関係にある blueprint-figure スキルを使って図を作成してください。マニュアル内のすべての図は、次の要件も満たす必要があります。

• sequence、structure、flow、comparison、timeline、tree、state、decision、layers の9種類から選んでください。
• 実際のシステムを示してください。キャプチャにある実際の ID、フィールド名、メソッド名、シーケンス番号を使ってください。
• 28語以内で主張を1つ示してください。キャプションでは図の読み方を説明し、キャプチャファイル名を記載してください。
• 「Component A」のような汎用ボックス、統計カード、プログレスバーを描いてはいけません。
• 対象の2つの動作を比較してください。以前のビルドと比較してはいけません。
• マニュアルごとに、各色相の意味を1つに定めてください。rose は失敗、grey は対象外、amber はライフサイクル、teal は永続状態を表します。
• 以下の8種類の矢印スタイルでやり取りを描いてください。図0.1では、マニュアルで使用するスタイルを説明してください。
• viewBox="0 0 640 H" とし、H は760以下、テキストは11単位以上、ファイルサイズは40 KB以下にしてください。
• ルート要素に <title> と、40文字以上の <desc> を置き、role="img" を指定してください。
• すべての図で同じページを使うため、SVG 内のすべての id は図の ID で始めてください。
• 色は var(--m-<token>, #hex) の形式だけで記述し、hex にはトークンのライト値を指定してください。

矢印スタイル	意味
ink の実線	呼び出しまたはリクエスト
ink の破線	応答
teal の実線	永続的な書き込み
amber の破線	状態の変化
plum の実線	モデル呼び出しまたは計算
olive の破線	システム外への作用
indigo の点線	ストリームまたはイベント
rose の破線	失敗

ビルドと監査

AI Engineering from Scratch リポジトリ内で、リポジトリのルートから次のコマンドを実行してください。

node --test site/test_manuals.js
node site/build-manuals.js
node manuals/_shared/figkit.js build manuals/<id>
node scripts/audit_manuals.js --manual <id>

リポジトリの外では、references/audit.md に基づいて独自の監査を作成してください。各チェック項目が記載されているため、1つのスクリプトにまとめられます。制限を変えるのではなく、テキストを修正してください。監査で TOTAL 0 が出力されるまで、マニュアルをマージしてはいけません。

コミットのルール

• コミットの規模は適宜判断してください。図や追加するキャプチャと合わせた1つのセクションが、適切な単位です。複数のセクションにまたがる小さな修正は、1つのコミットにまとめてもかまいません。
• メッセージには feat(manual/<id>): <section slug> を使用してください。
• 生成された出力はコミットしないでください。リポジトリ内では、site/manual-<id>.html、site/manuals.html、site/manuals-data.js が該当します。
• マニュアルが完成するまで、status は draft のままにしてください。ready のマニュアルには README.md が必要です。
• ベンダーソースの更新は、manual.json の pin と合わせて行ってください。

完了前の確認

• manual.json が検証に合格し、pin に subject、version、source、commit、date、verified が設定されている。
• すべてのセクションタイトルが、仕様で定義されているものを1つ示している。
• すべてのセクションに、主旨、最初の2段落以内の成果を示す文、1つの要点ブロック、Sources: 行がある。
• すべての json、jsonl、http、sse ブロックが、キャプチャソースを伴う listing になっている。
• キャプチャチェックがオフラインで実行され、差分がないと報告される。
• 24文字以上の引用がすべて、ベンダー対象ファイル内に一字一句同じ形で見つかる。
• すべての競合にレジスター ID があり、該当する各セクションがその ID にリンクしている。
• すべての図の SVG が文書で使用され、元のスクリプトと一致している。
• 監査で TOTAL 0 が出力される。
• コミットの規模は適宜判断し、feat(manual/<id>): <section slug> のようなメッセージを使用している。

ファイル

• references/manual-json.md：manual.json の各フィールドとスターターファイル。
• references/section-template.md：各フェンス種別を含むセクションのひな形。
• references/research-and-sources.md：事実の概要、ベンダー化、引用、競合レジスター。
• references/capture-kit.md：決定論的なキャプチャの記録方法と、差分の確認方法。
• references/prose-rules.md：制限事項と禁止語の全リスト。
• references/audit.md：監査ルールのすべてと、リポジトリ外で監査を再現する方法。
• AI Engineering from Scratch リポジトリ内では、manuals/AUTHORING.md、manuals/manual.schema.json、manuals/a2a-101/ も参照してください。