SKILL ARTICLE / web-doc-example-verifier
コード例を、説明の飾りではなく検証対象にする
本文を直したら、サンプルコードも確かめる。
技術ドキュメント内のコード例を抽出し、対象バージョンで実行・表示・リンクまで確認して、本文との不一致を報告するSkill案です。
この記事で紹介するSkill案は、参考資料を読んだうえで私が考えたものです。参照先が提供・評価・推奨しているものではありません。
OVERVIEW → CAN DO → BUILD
知ったことをSkillづくりに活かす
技術説明はコード例と結びついて初めて試せる。仕様や依存バージョンが変わると、本文より先にサンプルが古くなることがある。
読者が最初に試すサンプルの破損を、公開前と更新時に見つける。
コードブロックだけを抜き出して終わらず、言語、依存関係、セットアップ、入力、期待結果を一組として扱います。不足している前提そのものも、重要な検出結果です。
01 / OVERVIEW
資料の概要
MDN Web Docsは、HTML、CSS、JavaScript、Web APIなどを扱う開発者向け資料です。MDNの執筆ガイドでは、コード例をStatic examples、Interactive examples、Live samples、GitHub live samplesなどに分けています。長い例は説明しやすい小さな単位へ分けることや、APIの機能を示すだけでなく実際の利用場面も考えることが勧められています。
これはMDNの編集方針であり、任意の技術サイトを自動検証する機能の説明ではありません。
02 / CAN DO
できるようになること
MDNが示しているのは執筆方針で、検証ツールではありません。この記事では、その方針をドキュメントの点検手順へ応用します。コード例を集め、必要な環境、対象バージョン、期待される結果を整理したうえで、安全に実行できる例だけを検証するSkill案です。
公開前と依存関係の更新後に、実行結果と本文の一致、リンク切れ、再現条件の不足を同じ一覧で確認します。
活かしやすい場面
- SDKやAPIの利用ガイド
- READMEに実行例が多いOSS
- 複数バージョンを案内する開発者向けサイト
使う前に確認したい場面
- 実行すると外部データを書き換えるサンプル
- 検証環境を安全に分離できないコード
03 / BUILD
自分たちのSkill作成に活かせること
文章やコードをそのまままねるのではなく、自分たちのSkillに取り入れたい判断基準や工程の分け方を整理しました。
例示を単独で動かせる単位にする
コードブロックだけを抜き出して終わらず、言語、依存関係、セットアップ、入力、期待結果を一組として扱います。不足している前提そのものも、重要な検出結果です。
実行前の静的確認を必須にする
外部通信、ファイル変更、認証情報の参照、長時間処理などを先に分類し、許可された例だけを一時環境で実行します。「検証Skillだから実行してよい」という前提を置かないことが、安全性につながります。
成功と説明の一致を別々に採点する
エラーなく動いても、本文で説明した結果と違えば良い例とは言えません。実行可否、期待結果との一致、説明の十分さを別項目にすると、修正すべき場所が分かりやすくなります。
04 / WORKFLOW
Skillにするときの流れ
- 01
例示を抽出
言語、前提、期待結果、対象バージョンを集める。
- 02
隔離して実行
安全な一時環境で最小例を動かす。
- 03
本文と比較
結果、画面、リンクが説明と一致するか報告する。
05 / TRY
試すときに使える依頼文
これは完成したSkillではありません。先に依頼文として試し、期待する結果が返ってくるかを確かめるための試作プロンプトです。
docs配下のコード例を一覧化し、対象言語と必要な依存関係を示してください。まだ実行せず、外部通信・ファイル書き込み・認証情報が必要な例を先に分類してください。06 / BUILD BRIEF
試作するときの設計メモ
これは配布済みのSkillではありません。対象を小さく絞り、停止条件と評価ケースを足しながら確かめるための出発点です。
技術ドキュメント内のコード例を安全に検証するSkillを作る。
まず静的に危険操作を分類し、許可された例だけを一時環境で実行する。
期待結果、リンク切れ、対象バージョン、本文との不一致をファイルと行番号つきで返す。07 / WATCHOUTS
人が確認するところ
- 不明なコード例はサンドボックスで実行し、ネットワークと認証情報へのアクセスを制限します。
- 外部APIを呼ぶ例は、モックまたは明示的な許可を優先します。