fernbrook-labs/beginner-reference-book

初心者向け参考書（入門ガイド）を作る

プログラミング言語やフレームワークの入門参考書を、これまでに作った TypeScript・Rust・Angular・Go の入門ガイド（見本は references/examples/）と同じデザイン・同じ機能・同じ進め方で作る。できあがるのは次の 2 つ。

• デスクトップに置く 1 ファイルの HTML（〇〇入門ガイド.html。ダブルクリックで開ける）
• claude.ai の共有ページ（非公開。ユーザーが Share メニューから共有する）。Artifact ツールが使える環境（Claude Code など）のときだけ作る

同じデザインを保つために、見た目と動きはこのスキルの部品（assets/ と scripts/）をそのまま使う。毎回 CSS や JavaScript を書き直さないこと。書くのは、本の中身（原稿）と、言語に合わせたコードの確かめ方だけ。

参考書のいちばんの価値は「載っているコードと結果が本当に正しい」ことにある。コード例・エラーメッセージ・実行結果は、必ず実際のコンパイラや公式 Playground で確かめたものを載せる（想像で書かない）。バージョンや新機能の説明も、公式のリリースノートなどで確かめてから書く。

作業は数時間かかる長い仕事になる。節目ごとに、何をしているかを 1〜2 文でユーザーに伝える。

1. 入力を確かめる

入力は、スキル名のあとに書かれた文字（このスキルの本文の最後に ARGUMENTS: として付いていることが多い）か、ユーザーの依頼文の中の言語名・フレームワーク名。

• 何も書かれていないとき：作業を始めず、「どのプログラミング言語・フレームワークの参考書を作りますか？」と聞き返す（AskUserQuestion に Python・Java・React・Vue.js などの候補を 4 つまで出す。ほかは「Other」で自由に書いてもらえる）。
• プログラミング言語やフレームワーク以外のものが書かれたとき：その理由を 1 文で伝え、言語かフレームワークを入力し直してもらう。入力し直されたものも同じように確かめ、正しいものが入力されるまで先へ進まない。
• 判断に迷うもの・書き方のゆれ・複数の指定の扱いと、伝える文の例は references/questions.md の「入力の確かめ方」にある。迷ったら必ず読む。

AskUserQuestion が使えない環境では、同じ内容を文章で聞いて、そこで止まる。

2. 質問の前に下調べをする

選択肢の説明を正しく書くために、質問の前に次のことを確かめる（数分で済ませる。大きなダウンロードはまだしない）。

1. 最新の安定版のバージョンと公開日：公式サイトやリリースノートで確かめる。参考書の「〇〇 対応」に使う。
2. **公式の Playground（ブラウザで動かせる公式サイト）**があるか。あれば、外から送ってコンパイル・実行できる窓口があるか、URL にコードを入れて開けるか、共有リンク（サーバーにコードを保存する）方式か。
3. パソコンにすでに入っているか（python --version などで確かめる）。入っていなければ、一時的に入れる場合の大きさ（公式のダウンロードの大きさ）。
4. ディスクの空き容量（Windows の PowerShell なら Get-PSDrive C、Git Bash なら df -h /c、macOS・Linux なら df -h ~）。
5. ユーザーの環境の決まり（CLAUDE.md・AGENTS.md など）。たとえば「クラウドと同期しているフォルダー（OneDrive など）には触れない」といった決まりがあれば、下調べから片付けまで守る。

調べ方と、言語ごとの確かめ方の候補は references/verification.md にある。

3. 選択項目を聞く（これまでと同じ項目）

AskUserQuestion で、次の 4 つを1 回で聞く。項目と選択肢の書き方は、これまでの参考書を作ったときと同じにする（文面の型は references/questions.md）。おすすめの選択肢を先頭に置き、「（推奨）」を付ける。AskUserQuestion がない環境（Codex など）では、同じ 4 つの質問と選択肢を番号付きの文章で示し（範囲の章立ても書き添える）、答えを待つ。

1. 想定読者：たとえば「JS／TS 経験者（推奨）」「プログラミング初心者」。TypeScript を土台にするフレームワーク（Angular・NestJS など）なら「TypeScript 経験者（推奨）」、Python のフレームワーク（Django など）なら「Python 経験者（推奨）」のように、その対象に合わせる。
2. 範囲：「基本だけ（短め・8〜9 章）」「基本＋よく使う機能（推奨・12〜14 章）」「応用まで（長め・16〜18 章）」。それぞれ preview に章立てを書いて見せる。
3. 形式：「これまでと同じ形（推奨）」＝デスクトップに 1 ファイルの HTML ＋ 共有ページ、確認問題・コードのコピー・読んだ章の記録・キーワード検索つき。ほかに「HTML ファイルだけ」「機能を選ぶ」。共有ページを作れない環境（Artifact ツールがない）では、「これまでと同じ形」は HTML ファイルだけになる。そのときは「HTML ファイルだけ」を出さず、説明にも共有ページを書かない。
4. 確認方法：下調べの結果から、使える方法だけを並べる。「公式 Playground で確認」「一時的に入れて確認」「すでに入っている〇〇で確認」など。ディスクの空きが少ないときは、パソコンに何も入れない方法をおすすめにする。

答えによっては、続けてもう 1 回だけ聞く。

• 「機能を選ぶ」→ 章末の確認問題・コードのコピーボタン・読んだ章のチェック・用語・キーワード検索を複数選択で聞く。
• 確認に使う Playground が「共有リンク方式」（Go Playground のように、コードをサーバーに保存してリンクを作る）なら、「共有リンクを作る」か「コピーして貼り付け」かを聞く。共有リンクは外部への公開になり、消せないので、必ず了承を得る。URL にコードを入れて開ける Playground（Rust・TypeScript）は保存しないので聞かなくてよい。

選ばれた内容は、そのあとの作業ですべて守る。聞いたことをもう一度聞き直さない。

4. 計画を立てる

1. 章立てを決める（references/writing-guide.md）。1 章 10 分前後で読める量。言語なら最後の章は「よくあるエラーの読み方」にする。過去の 4 冊の章立ては references/past-books.md にある。
2. spec.json を書く（references/book-spec.md に項目と例がある）。表紙の名前、バージョン、想定読者、章の題、コードの言語、Playground の開き方、特色（ブランドカラー）など。
3. 特色は、その言語やフレームワークの公式のブランドカラーを使う。scripts/make_palette.mjs が、1 色からライトとダークの色を作り、文字が読めるコントラストかも確かめる（new_book.mjs が自動で呼ぶ）。

5. ひな形を作って、原稿を書く

1. 作業フォルダーは、セッションの一時フォルダー（Claude Code の scratchpad など。なければ OS の一時フォルダーの中に新しく作ったフォルダー）の中に作る。クラウドと同期しているフォルダー（OneDrive など）の下には作らない。
2. ひな形を作る：node <このスキル>/scripts/new_book.mjs <本のフォルダー> --spec spec.json
   • book.json・palette.json・src/body.html・src/ja-errors.json ができる。
   • src/body.html の目次・表紙・使い方・章の枠・確認問題の枠・付録の枠はできている。<!-- TODO … --> をすべて書き換える（残っていると組み立てで「要修正」になる）。
3. 書き始める前に、見本を読む。references/examples/ には、これまでの 4 冊から表紙・使い方・代表的な 1 章・エラーの章・付録を抜き出した原稿がある（どれもこのスキルの部品で組み立てて確かめ済み）。references/examples/README.md の表で、作る対象に近いものを 1〜2 冊選んで body.html を読む（言語なら go と rust、TypeScript が土台のフレームワークなら angular と typescript など）。決まりを言葉で読むより、実物を見たほうが、文章の調子・説明の深さ・節の大きさ・コード例の見せ方・確認問題の粒度がそろう。ただし、まねるのは書き方だけで、バージョンや機能などの事実は必ず確かめ直す。見本の文を写して言葉だけ置き換えることもしない。
4. 原稿を書く。部品（囲み・表・手順・確認問題・エラーの見出しなど）の HTML は references/components.md、コード例の書き方は references/code-blocks.md、文章の書き方は references/writing-guide.md に従う。章の数が多いので、数章ずつ書いては組み立てて確かめるとよい。

6. コード例を確かめる

node <このスキル>/scripts/build.mjs extract <本のフォルダー>   # コード例を work/ に書き出す
node <このスキル>/scripts/checkers/go-playground.mjs <本のフォルダー>   # 言語に合った確認スクリプト（下の表）
node <このスキル>/scripts/build.mjs render <本のフォルダー>    # 結果を付けて dist/ に HTML を作る

確認スクリプト	使う場面
checkers/go-playground.mjs	Go。公式 Go Playground でコンパイル・実行・go vet・gofmt。--share で共有リンクを作る
checkers/rust-playground.mjs	Rust。公式 Rust Playground でコンパイル・実行・型のヒント
checkers/typescript-local.mjs	TypeScript／JavaScript。一時的に入れた TypeScript で、エラー（公式の日本語訳つき）・吹き出し・実行
checkers/local-command.mjs	Python・Java・C# など。手元（または一時的に入れた）のコマンドで確認・実行

ここにない言語やフレームワーク（Angular のように画面の表示まで載せたいものなど）は、同じ形の結果（work/results.json）を書き出す確認スクリプトを新しく作る。結果の形は references/code-blocks.md、作り方の考え方と過去の例は references/verification.md。

• render が「要修正: なし」になるまで直す。エラーを載せる例には、行に // ❌（警告は // ⚠）を書いておくと、想定どおりのエラーが出ているかを組み立てのたびに確かめられる。
• dist/report.txt を読み、エラーメッセージ・実行結果・型の表示が本文の説明と合っているかを確かめる。
• 一時的に入れたものは、セッションの一時フォルダーの中だけに入れ、キャッシュの置き場所もそこに向ける（references/verification.md）。

7. 画面で確かめる

scripts/test_guide.py を実行する。dist/ は、このスクリプトが 127.0.0.1 の指定したポートで配信する。

python <このスキル>/scripts/test_guide.py --book <本> --port 8770 --search "<本文に出てくる言葉>"

• Python の Playwright と Chromium が必要。入っていなければ、入れてよいか（合わせて数百 MB）をユーザーに確かめる。入れられないときは、この確認を飛ばし、そのことを報告に書く。
• すべて合格するまで直す。そのあと <本>/shots/ のスクリーンショット（表紙・使い方・各章・早見表・ダーク・スマホ）を目で見て、はみ出し・読みにくい色・崩れがないかを確かめる。
• 本文の外部リンクが開けることと、Playground のリンクが正しく開けること（1 件は実際に開いて実行してみる）も確かめる。

8. 渡して、片付ける

1. 共有リンクを作ることになっていれば、本文が確定してから作り（--share）、すべてのリンクが正しいコードを開くかを確かめる。
2. dist/full.html を、ユーザーのデスクトップ（Windows なら C:\Users\<ユーザー>\Desktop、macOS なら ~/Desktop）に <名前>入門ガイド.html としてコピーする。同じ名前のファイルがあるときは、上書きせずにユーザーに確かめる。
3. 形式に共有ページが含まれていて、Artifact ツールが使える環境なら、quickstart を呼んでから dist/artifact.html を公開する（icon は book、description は日本語で 1 文）。公開されたページは非公開で、共有はユーザーが Share メニューから行うことを伝える。使えない環境では、この手順を飛ばす。
4. 一時的に入れたもの・キャッシュ・スクリーンショットを消す。自分の作業で共有の場所（npm のキャッシュなど）に書き込んだものがあれば、自分の分だけを確かめて消す。
5. 日本語で報告する：置き場所・共有ページの URL（作ったとき）・内容（章立ての要点）・確かめたこと（件数）・注意点（確かめられなかった環境、Playground の制約など）。

参考資料

ファイル	読むとき
references/questions.md	入力の確かめ方と、選択項目の聞き方（文面の型）
references/book-spec.md	spec.json と book.json の書き方
references/writing-guide.md	章立て・文章の書き方・正確さの決まり
references/components.md	原稿の HTML の部品
references/code-blocks.md	コード例の書き方・属性・確認スクリプトの結果の形
references/verification.md	言語ごとの確かめ方、一時的に入れるときの手順と片付け
references/past-books.md	これまでの 4 冊の章立て・色・確かめ方・気付いたこと
references/examples/README.md	原稿の見本（4 冊からの抜き出し）の選び方。原稿を書く前に読む