Write Blog Article

ブログ記事を執筆する

調査と実行結果に裏付けられた日本語記事を contents/blogPost/ に下書きとして作成する。ユーザーとの合意、検証、レビューを省略しない。

目的

ブログ記事を書く第一の目的を、ユーザーが新しい技術を学ぶことに置く。完成した記事だけでなく、テーマを選び、一次情報を調べ、設計理由を理解し、サンプルを動かすまでの過程を学習機会として扱う。この学習の積み重ねをブログを続ける理由として尊重し、記事の完成だけを優先して過程をブラックボックスにしない。

執筆中は、ユーザーの判断や理解に役立つ次の内容を適切なタイミングで解説する。

• 初出の概念と前提知識
• 調査で判明した重要な事実
• 現在の仕様と策定時の議論の違い
• API が現在の形になった理由と代替案
• サンプルで観測した挙動と、そこから言えること
• 記事の構成や表現を選んだ理由

説明は作業報告だけで終わらせず、ユーザーが技術を自分の言葉で理解できる粒度にする。疑問が生じた場合は執筆を進めながら回答し、必要に応じて調査、サンプル、記事へ反映する。記事の完成後もユーザーからの質問に答え、一次情報と検証結果に基づいて理解を支援する。

必須リソース

作業開始時に以下を読む。

• ../../../contents/BLOG_WRITING_GUIDE.md: このブログの構成・文体・frontmatter・チェックリスト
• references/article-types.md: 記事タイプごとの構成

新しい API・機能、Web 標準、ライブラリの新機能を扱う場合は、追加で以下を読む。

• references/research-and-validation.md: 一次情報の調査とサンプル検証

ワークフロー

1. リポジトリから判断できることを調べる

既存記事、関連サンプル、利用可能なコマンド、対象技術の依存関係を調べる。コードベースから判断できることをユーザーに質問しない。

依頼を次のいずれかに分類する。

1. 新しい API・機能の紹介
2. ハンズオン・実装チュートリアル
3. 調査・比較記事
4. 意見・経験記事

分類に確信が持てない場合だけ確認する。

2. grill-me で執筆方針を合意する

利用中のエージェント環境に合わせて grill-me スキルを呼び出す（Codex では $grill-me、Claude Code では /grill-me）。回答によって論旨、根拠、サンプル、構成、読者の到達点が変わる依存判断は一問ずつ確認する。各質問におすすめの回答と理由を添える。

依頼の範囲が狭く、リポジトリとユーザーの依頼から推奨案を安全に決められる場合は、短縮経路を使う。想定読者、扱う範囲、中心的な結論、サンプル、見出しなど、互いに独立した低リスクな既定案をまとめて提示し、一度の明示的な承認を得る。ユーザーが一括案を承認した項目は個別に質問せず、異論、曖昧さ、依存関係が生じた項目だけを一問ずつ掘り下げる。

次の項目を確定する。

• 回答から生じる依存判断を追跡し、論旨、根拠、サンプル、構成、読者の到達点を変える未解決事項がなくなるまで続ける

• 後の回答と矛盾する決定が見つかった場合は、以前の決定へ戻って再確認する

• ユーザーが質問の意味を尋ねた場合は説明し、その後で未回答の質問へ戻る

• 単なる相槌や対象が曖昧な同意だけで合意済みと判断しない。一括案全体への明示的な承認は合意として扱い、曖昧・矛盾・未指定の回答だけを具体例とトレードオフで掘り下げる

• 想定読者と前提知識

• 読者が持ち帰る結論

• 扱う範囲と扱わない範囲

• 調査すべき論点と一次情報

• サンプルで証明する主張

• 検証環境と成功条件

• 見出し構成

• タイトルと about の方向性

ユーザーの意図に関わる分岐だけ質問する。最後に合意事項、前提、却下した選択肢、残っている非ブロッキングな不確実性を要約する。執筆開始を含めて承認済みなら再確認せず進め、未承認の場合だけ明示的な承認を得る。短縮経路の一括案には執筆開始も含める。承認前に記事ファイルを作成しない。

3. 信頼できるソースを調査する

記事タイプにかかわらず、主張を信頼できるソースで裏付ける。最新情報が関係する場合は必ず Web を調査する。技術的な調査では公式文書、仕様、公式リポジトリなどの一次情報を優先する。

新しい API・Web 標準では references/research-and-validation.md の調査をすべて行う。現在の仕様だけでなく、Issue、Pull Request、メーリングリスト、Explainer などから設計理由と代替案の議論を調べる。議論が見つからない場合は、推測で補わず「確認できなかった」と扱う。

調査後、次をユーザーに提示する。承認済みの方針から論旨、範囲、構成、サンプルの成功条件が変わる場合だけ、変更点と理由を示して合意を得る。方針が変わらなければ、学習に役立つ解説を行い、そのまま進める。

• 記事の中心的な主張
• 重要な根拠と仕様策定の背景
• 扱う制約・互換性・未解決事項
• 見出し案
• サンプルと検証計画
• 主要な参考資料

提示時には結論だけでなく、読者の理解に重要な設計理由、意外だった点、古い情報と現行仕様の違いを短く解説する。ユーザーから質問があれば、根拠となる一次情報を示して回答してから次へ進む。

4. 下書きを作成する

リポジトリルートで次を実行する。

npm run new:article

コマンドが作成した日本語と英語のファイルを特定する。日本語側の contents/blogPost/<id>.md だけを編集し、英語側は変更しない。

• published: false を維持する
• サムネイルは設定しない。生成された空の thumbnail ブロックは、下書きのスキーマ検証を通すため日本語側から削除する
• title、slug、about、tags、本文を埋める
• selfAssessment.quizzes は本文確定まで空のままにする

5. 必須サンプルを実装・検証する

記事タイプが「新しい API・機能の紹介」の場合、サンプル作成と実行検証を必須とする。詳細は references/research-and-validation.md に従う。

サンプルを examples/<slug>/ に作り、人間が同じ手順で再実行できる状態にする。自動削除・自動ステージ・自動コミットしない。

examples/<slug>/ は、記事の主張を裏付ける内部検証成果物として扱う。記事に付随して公開されるとは想定しない。ユーザーが公開用サンプルとして含めることへ明示的に合意しない限り、記事本文でローカルパス、ディレクトリ名、起動コマンド、リポジトリ上の配置、読者が利用できるサンプルとしての存在へ言及しない。

検証は必須だが、検証手順、比較コード、テスト結果を本文へ掲載することは必須ではない。中心的な主張の理解、再現、採用判断に必要な検証日、環境、条件、観測結果だけを本文へ記載する。技術的正確性を担保するためだけのテストは、記事の流れを妨げずに examples/<slug>/ へ残す。

検証用サンプルは、対象の新しい API を呼び出して中心的な正常系が動くことを確認できる最小構成にする。記事の説明をサンプル画面へ再掲したり、テスト結果一覧、デモ専用 UI、過度な装飾を追加したりしない。失敗条件や複数の主張をサンプルへ含めるのは、記事の中心的な結論を証明するために不可欠な場合だけにする。

検証後は、実行結果だけでなく「どのコードが新しい技術の本質か」「観測結果が仕様のどの説明と対応するか」をユーザーへ解説する。

対象 API を実行できる環境がない場合は、未検証のまま記事を完成扱いにしない。安全な準備方法を調べ、追加インストールやフラグ変更が必要なら承認を得る。同じ対象・操作について承認済みなら再確認しない。検証できなければ「検証待ち」とし、未確認の結果を書かず、資料調査、観測に依存しない説明、静的レビューを進める。独立して進められる作業が終わったら、未完了の検証と再開に必要な条件を報告する。

ブラウザだけで完結する HTML/CSS/JavaScript サンプルを CodePen で共有する場合は、独立した codepen-share スキルを使う。CodePen 共有は執筆の必須条件ではない。Node.js、CLI、サーバー、ビルド、複数プロセスが必要なサンプルでは使用しない。

6. 記事を書く

合意済みの構成と ../../../contents/BLOG_WRITING_GUIDE.md に従う。

• 問題・背景から始め、読者の到達点を導入で明示する
• 新しい Web 標準の記事では、Web Platform DX の公式 web-features データで対象機能の ID を確認し、frontmatter の直後かつ導入文の前に b> <baseline-id> を必ず置く。ID を推測せず、見つからない場合はその旨をユーザーへ伝える。中心的な機能が複数ある場合は 1 行ずつ置く
• 主張の近くに一次情報へのリンクを置く
• 仕様の現状と、策定時に議論された設計理由を区別して説明する
• コードの前に目的、後に重要な行と観測結果を書く
• 本文へ掲載する観測結果には、必要な検証日、環境、バージョン、成功条件を書く
• 事実、観測結果、推測、著者の意見を区別する
• 互換性、失敗条件、フォールバックを隠さない
• 想定読者にとって初出となる API、専門用語、略語を最初の登場箇所で説明する。具体的な公開 API で表現できる内部用語は置き換え、説明に必要な内部用語だけを残す
• 同じ疑問の流れで読む情報を分散させない。ある挙動の既定動作、具体例、検出方法、例外、フォールバックは、理解を妨げる理由がない限り近くに配置する
• ## まとめ と ## 参考 を置く
• ## まとめ は段落ではなく箇条書きにする。本文にない新情報を加えず、各項目を単独で意味が通る具体的な命題として書く

見た目、操作、時間変化が中心的な主張では、静的な結果に画像、動きに動画、操作による変化に CodePen などのインタラクティブな例を使う。媒体を用意できない場合は、必要な位置へ次の形式の非表示コメントを置く。

<!-- TODO(media): <画像|動画|インタラクティブデモ>で<具体的な状態または操作>を示す。読者が確認する点: <具体的な結果>。代替テキスト・キャプション: <説明>。 -->

コメントの前で見るべき点を説明し、後で確認できる結果を解釈する。存在しない媒体、URL、観測結果を作らない。

7. 役割の異なるレビューを通す

本文とサンプルが完成したら、次の順でレビューする。

1. article-review: .md を付けない下書き ID を渡し、textlint、誤字脱字、文法、表記を確認する
2. tech-review: 日本語の記事ファイルを渡し、技術的正確性、構成、コード、読者体験を確認する

利用中のエージェント環境のスキル呼び出し構文を使用する。Codex では $article-review と $tech-review、Claude Code では /article-review と /tech-review を使用する。

誤字脱字、明白な文法ミス、検証結果との不一致は修正する。技術的主張、構成、筆者の意見を変える指摘は、根拠と修正案をユーザーに示して再合意する。修正後は修正箇所と影響する主張に絞って該当レビューを再実行する。新しい問題や広範な影響がなければ全体レビューを繰り返さない。技術レビューの P0・P1、中心的な主張の根拠や再現性に関わる P2、文章校正の必須修正が解消され、必要な検証が完了したらレビューを終える。その他の P2 は対応または残す理由を記録し、P3 など任意の改善は完成を妨げない。

完成前に同じ記事タイプの既存記事を 2〜3 本選び、導入、about、見出しの進行、説明のリズム、コード前後の説明、対応状況の位置、視覚的証拠、まとめ、参考、日本語と英数字の間のスペースを比較する。表現をコピーせず、繰り返し使われている編集上の判断と語調に合わせる。

8. 理解度クイズと構造を確定する

レビュー後の本文に対して q スキルを使用する（Codex では $q、Claude Code では /q）。3〜5 問の selfAssessment を生成する。本文に書かれていない内容を出題しない。各問題を 4 択、正答 1 つ、全選択肢に explanation がある形で frontmatter に反映する。

次のコマンドで記事の frontmatter と本文をリポジトリのスキーマで検証する。

npx tsx .claude/skills/write-blog-article/scripts/validate-article.mts contents/blogPost/<id>.md

9. 完了報告をする

次を簡潔に報告する。

• 記事ファイル
• 記事タイプ、想定読者、中心的な結論
• 主要な一次情報と設計理由
• サンプルの場所、再現コマンド、検証環境、結果
• 未保存の CodePen Prefill または launcher と、iframe コメントの位置
• レビューと構造検証の結果
• 未解決事項、ユーザーが行う作業
• ユーザーが学んだ主要なポイントと、追加の質問を受け付けること

公開、翻訳、サムネイル作成、Git ステージ・コミットは行わない。

完了報告後も、この執筆で扱った技術に関するユーザーの質問へ回答する。質問から理解の不足や記事の説明不足が判明した場合は、根拠を確認したうえで解説し、ユーザーが望めば記事も更新する。