code-sample-documentation

コードサンプルのドキュメント

このスキルを使用して、有用で正確、コピー可能かつ保守しやすいコードサンプルを作成・レビューします。実行可能な例、説明用のスニペット、API のリクエストとレスポンスの組み合わせ、CLI コマンド、設定ファイル、生成されたリファレンスに適用されます。

このスキルは、特に第 5 章「コードサンプルの組み込み」を参考に、『Docs for Developers: An Engineer's Field Guide to Technical Writing』を基にしています。ガイダンスは変換・言い換えたものです。書籍の文章をユーザー向けの出力にコピーしないでください。出典：https://link.springer.com/book/10.1007/978-1-4842-7217-6

クイックスタート

1. guidelines.md を読み込み、必要最小限の参考資料を選びます。
2. サンプルを実行可能、説明用、またはリクエスト／レスポンスの組み合わせに分類します。
3. サンプルが説明されているか、簡潔か、明確か、使用可能か、信頼できるかを確認します。
4. サンプルを徹底的にレビューするには、workflows/review-code-sample.md を使用します。
5. 実行やテストが可能な場合はそれを優先します。難しい場合は、未検証の箇所を明記します。

デフォルトの出力

コードサンプルをレビューまたは設計する際は、次の内容を返します。

1. サンプルの目的 - 読者が何を学ぶか、何を達成するか。
2. サンプルの種類 - 実行可能、説明用、リクエスト／レスポンス、CLI、設定、または生成されたもの。
3. 問題点または設計上の注意点 - 読者へのリスクが高い順。
4. 修正したサンプル - 要求された場合は、簡潔でコピー可能なもの。
5. テスト計画 - 実行時の動作、出力、バージョンに関する前提を検証する方法。
6. 保守に関する注意点 - 信頼できる情報源、担当者、生成物と手作業による部分の境界。

目次

必要な内容	ここから始める
サンプルの種類を理解する	references/core/knowledge.md
サンプルのルールを適用する	references/core/knowledge.md
修正前／修正後の例を見る	references/core/knowledge.md
サンプルをレビューまたは設計する	workflows/review-code-sample.md
タスクに応じて参照先を選ぶ	guidelines.md

基本方針

• サンプルはドキュメントであり、ソフトウェアでもあります。両方として扱ってください。
• サンプルの複雑さを、読者の習熟段階に合わせます。
• プレースホルダー、入力、出力、制限事項を明示します。
• 使用目的に合わせてレビューおよびテストされていない限り、サンプルが本番環境でそのまま使えるかのように示してはいけません。