商品づくり（プロダクトマネジメント）のスキル集を、判断力も育つ形で書いて保つ

## 判断の理由と例を残して、使う人の判断力を育てる ### 二つの対象者に対応する プロダクトマネジメント・スキルは、実務者が有用な作業を完了し、その技術を高めるのに役立つものでなければなりません。どのスキルも、判断力を養う人間とワークフローを実行するエージェントの両方に向けて設計してください。一方を優先するために、もう一方を犠牲にしてはいけません。 推奨事項が信頼でき、説明可能で、応用できるように、ワークフローの背後にある推論を十分に見える形にします。ユーザーは完成した成果物を受け取るだけでなく、なぜそのアプローチが機能するのかを理解できる必要があります。 ### 学習構造を守る - 適切な意思決定に必要な推論が失われる場合は、説明を短縮しないでください。 - 実際の状況で何を見分け、避けるべきかをユーザーが学べるように、明示されたアンチパターンを維持してください。 - 最終成果だけでなく、推論の過程を示す例を使ってください。 - 専門用語は初出時に定義し、トレードオフを明示してください。 - コーチングの層を取り除くことなく、実用的でエージェントが実行できるワークフローを維持してください。 効率を改善するときは、教訓、例、失敗パターンを省く前に、繰り返し、冗長な表現、本筋と関係のない背景を省いてください。ある一節が理解を支える足場なのか不要な情報なのか不明な場合は、その機能を理解するまで残してください。 ### 複数の文脈で品質を示す 根拠が意思決定につながる過程を示す具体例を少なくとも一つ含めてください。十分に作り込まれたスキルには、再利用可能なテンプレートと、ソフトウェアサービスと物理的または業務運用型の事業など、意味のある違いを持つ二つのビジネス環境での実例を追加してください。架空の組織とデータを使用します。 ## スキルごとにフォルダを分け、自動で作られる一覧は手で直さない ### 正本と派生成果物を分ける 各スキルを一貫した名前の専用フォルダに置き、正本となるスキル文書を一つと、スキル固有の補助アセットやスクリプトを格納してください。再利用可能なオーケストレーション用コマンドは、個々のスキルとは別に保管します。調査、ユーザー文書、プレビューアプリケーション、リリース成果物を、所有者が明確な別々の領域で管理してください。 生成されたカタログ、索引、パッケージのコピー、配布用バンドルは派生成果物として扱ってください。直接編集せず、正本から再生成します。 スキルフォルダ名には小文字のkebab-caseを使い、フォルダ名をスキルで宣言された名前と一致させてください。可能な限り安定したパスを維持します。スキル名は必要な場合に限って変更し、その際はすべての参照を更新してください。 ### 所有境界に従う コンテンツを編集する前に、どのリポジトリまたはワークスペースがそのコンテンツを所有しているか確認してください。共有ライブラリ、製品固有のプレイブック、配布用リポジトリは、互いに参照しながら異なる正本を持つ場合があります。所有元で作業し、タスクでその境界の変更が明示されていない限り、他の場所は読み取り専用の参照先として扱ってください。 見慣れたディレクトリ名だけを根拠に構造を推測しないでください。構造に関する決定を下す前に、そのリポジトリ固有の定義、コントリビューション規則、スクリプト、既存例を確認してください。 ### 最も具体的な能力を見つける プロダクトマネジメントの指針を独自に考案する前に、利用可能なスキルを調べ、最も具体的に合致するものを選んでください。一般的な領域には、ディスカバリー、Jobs to Be Done、ペルソナ、プロダクト戦略、優先順位付け、ロードマップ、要件文書、ユーザーストーリー、受け入れ基準、人工知能製品の業務、エージェントのワークフロー、ステークホルダー間の合意形成があります。 これらは一般的なソフトウェアエンジニアリングのタスクではなく、コーチングと成果物生成のワークフローとして扱ってください。 ## スキルの文書に例とよくある失敗を入れ、使う人への質問は1つずつにする ### 一貫した文書契約を使う 各スキルに、目的、入力、主要概念、適用、例、よくある落とし穴、参考資料などの明確な順序を持たせてください。frontmatterにはname、description、typeの各フィールドを含めます。対象プラットフォームがその制限を課す場合は、nameを64文字以内、descriptionを200文字以内にしてください。 明確なMarkdown見出しと短い段落を使用してください。フェンス付きコードブロックには言語識別子を付けます。文章は簡潔で明確な立場を持たせつつ、必要な推論、条件、例を犠牲にしないでください。 ### 入力を必須条件ではなく招待として扱う 入力セクションでは、ユーザーが提供できる内容を平易な言葉で説明し、呼び出し例を含めてください。依頼文ですでに提供された情報は、回答済みとして扱います。 初期入力は一部だけでも、まったくなくても受け付けてください。ユーザーを止めるのではなく、ガイド付きの進行で不足情報を収集する方法を説明します。サポートされていない環境でそのまま表示される、実行環境固有のプレースホルダーやテンプレート構文は避けてください。 ### 対話型フローを意図的に設計する 対話型スキルでは、次のようにします。 - 質問は一度に一つずつ行うか、まとまりのある小さな単位に分けてください。 - 各回答を次の質問に反映してください。 - 文脈に応じた次の手順の推奨を番号付きで提示してください。 - 番号による選択と自由入力の両方を受け付けてください。 - ユーザーの選択によって関連する経路が変わる場合は、ワークフローを適応させてください。 暗黙の前提に頼らず、スキル単体で完結し、エージェントが利用できるようにしてください。明示的なアンチパターンを少なくとも一つ含め、それが失敗する理由を説明します。 ## 共有する前に、スキル集のツールで中身とリンクを確かめる ### ライブラリ固有の検証経路を使う 場当たり的なチェックよりも、リポジトリで文書化された検出、検証、パッケージ化、ライブラリ全体のテスト用ツールを優先してください。変更を提出する前に、ファイル検出と対象を絞った参照検索を使い、スキルの場所と相互参照を確認します。 正本のスキルパスが解決できること、メタデータが有効であること、必須セクションが存在すること、例と参考資料が正確であること、リンクの整合性が保たれていることを検証してください。自動テストを利用できない場合は、未検証の成功を主張せず、これらを手動で確認してください。 パッケージビルダーとカタログ生成ツールは、保守されているエントリーポイントから実行してください。プレビューアプリケーションを変更した場合は、該当するローカルプレビュー経路を実行し、その文書も確認してください。 ### 互換性と安全な自動化を維持する 必要な場合のファイル名の大文字・小文字の完全一致を含め、プラットフォーム固有のパッケージ要件を守ってください。ワークフローがネットワークアクセスを明示的に要求し、管理している場合を除き、補助スクリプトは決定論的で、文書化され、ネットワークアクセスを行わない状態に保ってください。 スクリプトやパッケージ化されたコンテンツは、共有または実行する前に安全性を確認してください。管理対象のマーケットプレイス、プラグイン、互換性関連ファイルは、無関係に見えるという理由だけで取り除かないでください。正本を修正する代わりに、生成済みのリリース成果物を編集してはいけません。 ### 真の正本を確認する カテゴリー、スキル種別、パッケージ構造を変更する前に、ローカルの基準と関連する正本スキルに基づいて判断してください。個人的な慣習よりも、保守されているバリデーターとリポジトリ用ツールから得られる根拠を優先します。 依頼された作業が別のリポジトリに属する場合は、現在の境界で書き込みを止め、所有元の正本へ変更を向けてください。参考資料は作業に役立てても、編集対象にしてはいけません。 ## 変更は小さくし、出す前にチェックリストで確かめる ### レビューしやすい変更を準備する 変更は小さく、保守しやすく、明示された目的の範囲内に保ってください。コミットの件名には、明確な命令形を使用します。レビュー依頼では、変更を要約し、関連するissueへのリンクを示し、スキル種別を明記し、互換性や動作に関する重要な変更を明示してください。 スキルを追加または改名するときは、カタログ項目、件数、表、パス、相互リンクを更新してください。リリース前にすべての参照が解決できることを確認します。 ### 完全なリリースチェックリストを適用する - 正本のスキルフォルダとメタデータを検証します。 - ダウンロード可能なパッケージと生成済みカタログを正本から再構築します。 - 例、参考資料、ナビゲーションリンクが引き続き正確であることを確認します。 - frontmatterの構文と、プラットフォーム固有のパッケージコピーを検証します。 - プレビューアプリケーションを変更した場合は、インターフェース文書とリリースノートを更新します。 - 生成物、無関係なファイル、意図しない広範な置換が変更に混入していないことを確認します。 ### 教育上の成果を最終基準にする リリース可能なスキルは、教育的で、エージェントが実行でき、自己完結していて、実用的です。推論、少なくとも一つの実例、明示的なアンチパターン、定義された専門用語、明示されたトレードオフを含みます。十分に作り込まれたスキルには、再利用可能なテンプレートと対照的な領域の例も含まれます。 長さを減らすという理由だけで、説明、アンチパターン、例を取り除かないでください。そのスキルが有用な結果を生み、ユーザーの判断力を高め、サポート対象の環境全体で保守可能な状態を維持できる場合に限り、リリースを承認してください。