write-guide

コンセプトグラフに沿ってガイドを書く

このリポジトリには、整合している必要がある2種類のコンテンツがあります。

• コンセプト（plugins/runpod/skills/runpod-usage/concepts/*.yaml）には、公開ソースを根拠として示した、ルール形式の正確な事実が記載されています。コンセプトは「何が真実か」の信頼できる情報源です。
• ガイド（すべての SKILL.md、reference/*.md、ゴールデンパス）は、説明、指導、実演を行います。ガイドは「どのように行うか」の信頼できる情報源です。

ガイドでは、コンセプトのルールに裏付けられた事実を述べ、対象とするコンセプトへのリンクを記載します。 各コンセプトは、少なくとも1つのガイドで扱う必要があります。pnpm check:guides は、両方のリンクを検証します。

ガイドを書く、または変更する

1. 執筆する前に、関連するコンセプトを見つけます（ontology/tools/ で次を実行します）。

   pnpm build:sqlite
   pnpm query tree "<concept>"      # the concept, its children and the guides that cover them
   pnpm query search "<question>"   # the rules that answer a question
   pnpm query concept "<name>"      # every rule on one concept, with evidence
   

2. ルールに基づいて書きます。 事実に関する主張（制限、デフォルト、状態、操作の内容、存在するもの）はすべて、ルールと一致させる必要があります。自分の言葉で説明し、さらに「どのように」行うか、つまりコマンド、順序、注意点、検証方法を加えます。

   • ガイドにルールにない事実が必要な場合は、add-concept スキルを使い、仕様、公開ドキュメント、または実環境での確認を根拠としてルールを先に追加します。その後、ガイドを書きます。
   • ルールに誤りがある、または古くなっている場合は、同じ変更で根拠も含めて修正します。
   • ガイドとルールの内容に食い違いがないようにします。食い違いを見つけた場合は、どちらを変更するかを公開ソースに基づいて決めます。

3. リンクを宣言します。

   ガイド	場所	例
   SKILL.md	frontmatter の metadata.concepts	concepts: [pod, network-volume]
   リファレンスドキュメント	冒頭の frontmatter にある concepts: 行	--- concepts: [runpod-secret] ---
   ゴールデンパス	frontmatter の lanes、mcp、concepts	plugins/runpod/skills/runpod/golden-paths/README.md を参照

   言及しているすべての単語ではなく、ガイドで実際に説明または使用するコンセプトを列挙します。 pnpm build:bundle --suggest は、候補として各ゴールデンパスが挙げているコンセプトを一覧表示します。 ルールの根拠としてすでに引用されているリファレンスドキュメントは自動的にリンクされますが、引用元のルール以外も扱う場合は、そのコンセプトも列挙します。

4. ドキュメントがあるコンセプトの主な説明となる場合は、ルールを示します。 各コンセプトファイルへの Markdown リンクを含む「Exact rules」セクションを末尾に追加します（リファレンスドキュメントからのリンク先は ../concepts/<id>.yaml です）。

5. 適切な場所から参照できるようにします。 新しいリファレンスドキュメントは、そのスキルの SKILL.md の表に行を追加します。新しいゴールデンパスは、ルーターの表と golden-paths/README.md に行を追加します。

コンセプトを追加または変更した後

1. 新しいコンセプトにガイドがないと、pnpm check:guides は失敗します。上記の手順に従って、既存のドキュメントを拡張するか、新しいドキュメントを作成します。

2. すでにそのコンセプトを扱っているガイドを見つけ、ルールとの整合性を確認します。

   pnpm query tree "<concept>"                    # guides linked to it
   grep -rln "<name or alias>" ../../plugins/     # guides that mention it without a link
   

3. ルールが根拠としてスキルファイルを引用していて、そのファイルを変更した場合は、ルールを読み直します。 grep -rn "<path>" ../../plugins/runpod/skills/runpod-usage/concepts/

スタイル

plugins/runpod/skills/runpod-usage/concepts/README.md →「Writing style」と、リポジトリの規約である AGENTS.md に従います。簡潔な現在形を使い、「Runpod」と表記し、コード識別子はバッククォートで囲み、「currently」や「not yet」は使わず、何かが欠けているという主張よりも肯定的な主張を優先します（機能がないという主張には仕様またはドキュメントによる根拠が必要です。また、CLI に関する不在の主張は hooks/check_cli_absence_claims.py で確認します）。

確認

cd ontology/tools
pnpm format && pnpm validate --strict && pnpm check:guides && pnpm test
cd ../.. && python3 hooks/check_links.py && python3 hooks/check_runpod_branding.py

check:guides でエラーが報告されず、ビルドの「concepts with a guide」の数がすべてのコンセプトについて維持されている必要があります。