メインコンテンツまでスキップ

スキル作成ガイド（Skill Authoring Guide / How-to）

このガイドは、River Review のスキル（skills/**/*.md）を追加・更新するときに、迷いを減らし、品質のブレを抑えるための「書き方」をまとめたものです。

目的（Goals）​

  • 1スキル = 1観点で、指摘の粒度と意図を揃える
  • 誤検知（うるさいだけ）を減らし、レビューを読みやすくする
  • 変更に強い（拡張しても運用が崩れない）スキルを書く
  • 人間のレビューで「毎回言っていること」を自動化する

非目的（Non-goals）​

  • 好み・宗教論争（インデント、命名の流派など）をしない
  • スキル本文で「実装方法」や「プロジェクト固有の事情」を断定しない
  • “nit” を増やすためのスキルを作らない（重要度と効果が薄い指摘の濫発は避ける）
  • 変更されていないコードへの網羅的な指摘をしない

スキルの構造​

スキルは YAML frontmatter（メタデータ）と Markdown 本文（指示文）で構成します。

  • メタデータ: ルーティング・検証・優先度のための情報
  • 本文: レビュアー（LLM/ヒューリスティック）が従うチェック観点と書き方

メタデータの定義は schemas/skill.schema.json、一覧は pages/reference/metadata-fields.md を参照してください。

最小の frontmatter（必須）:

  • id: 安定した識別子（移動・リネームしても不変）
  • name: 人間向けの短い名前
  • description: 何をチェックするか（1文）
  • phase: upstream / midstream / downstream
  • applyTo: 対象ファイルの glob

推奨テンプレ（最小）​

新規作成時は skills/_template.md をベースにし、まずは次を揃えます。

  • applyTo を絞る（いきなり **/* にしない）
  • “抑制条件” を書く（誤検知ガード）
  • “扱わない領域” を書く（Non-goals）
  • 指摘文は短くし、次の行動へつながるようにする

スキルの粒度（1テーマ/1観点）​

スキルは「1テーマ/1観点」で分けるのが基本です。1つのスキルに異なる目的を詰め込まないことで、誤検知が減り、運用が安定します。

  • 1スキル = 1種類のリスク（例: 入力検証の欠落、Accessible Name の欠落）
  • フレームワーク固有の知識は1スキルに閉じる（汎用ルールと混ぜない）
  • 例外や派生条件が多い場合は別スキルに分割する

Diff を主入力にする（Diff-first）​

スキルは diff を主入力として、再現可能な指摘を行うレビュー単位です。

  • 可能な限り「変更行」を優先して評価する
  • 変更外に言及する場合は、Confidence を下げて断定を避ける
  • 「プロジェクトの文脈がなければ判断できない設計批評」は避ける

推奨: Signals（適用判断材料）​

signals は frontmatter のフィールドではありませんが、本文に「このスキルを適用する判断材料」を書くとブレが減ります。

  • 例: 「例外を握りつぶす catch（ログなし、再throwなし）が差分に含まれる場合は適用する」
  • 例: 「認証情報らしき文字列（AKIA/ghp_/sk- など）が差分に含まれる場合は適用する」

Severity の基準（目安）​

severity は「レビューを受けた人がどう扱うべきか」の目安です。

  • critical: セキュリティ事故やデータ破壊につながる、即対応が必要
  • major: バグ・運用障害のリスクが高い、原則対応したい
  • minor: 将来の保守性・読みやすさに効く、余力があれば直したい
  • info: 判断材料の提示（“検討ポイント”）

補足:

  • しばしば blocker / warning / nit の3段階で語られるが、本リポジトリの enum は info / minor / major / critical である。

Confidence（確信度）の表現（特に low の場合）​

Confidence が low（推測が混じる）場合は、読み手に「断定ではない」ことが伝わる書き方にする。

  • must / should / definitely などの断定表現を避ける
  • may / might / consider など “可能性/提案” を示す表現を使う
  • 事実（Evidence）と提案（推測）を分けて書く（例: “差分上は X が見える。Y の可能性があるため確認を検討する”）

Evidence（根拠）の必須要件​

River Review のコメントは <file>:<line>: <message> 形式で投稿されます。最低限、以下を満たしてください。

  • どこを見て言っているかが分かる（ファイルと行に紐づく）
  • 推測を断定しない（不確実な場合は “可能性” として書く）
  • 再現や確認の手がかりがある（何を確認すれば良いか）
  • 日本語でコメントする（レビューコメントは日本語で返す）

出力フォーマット（必須）​

スキルが返す message は長くできません。最低限、次の要素が読み取れるように書きます。

  • Finding: 何が問題か（短く、断定しすぎない）
  • Evidence: 根拠（どのファイル/行の、どの差分か）
  • Impact: 放置した場合の影響（短く）
  • Fix: 最小の修正案（次の一手）

補足:

  • Evidence が書けない指摘は、原則として書かない。
  • Confidence や Severity はスキーマフィールド（confidence: high|medium|low, severity: critical|major|minor|info）として JSON 出力に含まれる。LLM に出力させる場合は Confidence: や Severity: ラベルをメッセージ中に含めると自動的にパースされる。

推奨: 指摘文の型（短文版）​

<message> は長くできないため、短くても読みやすい「型」を揃えます。

  • Finding: 何が問題か（1文）
  • Evidence: 根拠（ファイルと行、diff で見える事実）
  • Impact: 何が困るか（短く）
  • Fix: 最小の修正案（次の一手）

例:

  • src/foo.ts:42: 例外が握りつぶされる可能性。障害調査が困難。Fix: catch でログ+再throw（or 呼び出し元へ返す）

禁止事項（アンチパターン）​

  • 断定口調の決め打ち（「必ず〜」「〜に違いない」）
  • 状況依存の押し付け（プロジェクトの前提が不明なのに “こうすべき” を断言）
  • “nit” の濫発（意味の薄い指摘を大量に出す）
  • 差分と無関係な一般論の連発
  • 他スキルと役割が被る実装（重複が増えてノイズになる）

誤検知を減らすためのルール（Guards）​

スキルは「抑制条件」を持つ必要があります。誤検知は “直す価値がある不具合” として扱います。

例:

  • 既に入力検証が存在する場合は指摘しない
  • context 付きログがある場合はログ改善を提案しない

PR 時の最小チェック​

スキルを追加・更新したら、PR 本文に以下を残します。

  • npm run skills:validate
  • npm test
  • 可能なら “誤検知ガード/Non-goals” の確認観点（何を言わないか）

Fixtures と評価ワークフロー​

各スキルには fixtures/（入力 diff サンプル）と golden/（期待出力）という兄弟ディレクトリを用意できます。これらは Minimum Acceptance Bar を客観的に検証するための評価セットです。

ディレクトリ構造​

skills/<phase>/<skill-id>/
├── SKILL.md
├── fixtures/
│   ├── 01-true-positive-<説明>.md   # 指摘すべきケース
│   └── 02-false-positive-<説明>.md  # 指摘しないべきケース
├── golden/
│   ├── 01-true-positive-<説明>.md   # 期待される出力
│   └── 02-false-positive-<説明>.md  # 期待される出力（指摘なし）
└── eval/
    └── promptfoo.yaml               # promptfoo 設定（任意）
  • ファイル名は <数字プレフィックス>-<種別>-<説明>.md の形式にします（例: 01-true-positive-undocumented-dependency.md）。
  • fixtures/ と golden/ のファイル名は完全一致させます（ペアで評価するため）。
  • true-positive ケースでは、スキルが少なくとも1件の指摘を返すことを確認する。
  • false-positive ケースでは、スキルが指摘を返さないこと（または無関係な指摘を返さないこと）を確認する。

評価の実行​

npm run eval:fixtures

promptfoo を直接使う場合は npx promptfoo eval でも実行できます。eval の詳細なセットアップは pages/guides/repo-wide-review.md を参照してください。

なぜ fixtures が重要か​

fixtures がないと、スキルが「本当に指摘すべき差分を検知できるか」「誤検知ガードが機能しているか」を人手でしか確認できません。Minimum Acceptance Bar（下記）の検証は fixtures があって初めて再現可能になります。

スキル追加・変更時のチェックリスト​

  • 指摘が 1 観点に絞られている
  • Evidence（ファイル/行、diff の事実）が明確である
  • 誤検知ガード（抑制条件）がある
  • Non-goals（扱わないこと）が書かれている
  • fixtures/ と golden/ に true-positive / false-positive ケースがある（Minimum Acceptance Bar の検証に必須）

Minimum Acceptance Bar（最低合格ライン）​

A skill is considered “acceptable” when it meets the following minimum bar: （スキルが「合格」と見なされるのは、次の最低基準を満たしている場合です。）

  • It produces at least one actionable finding when applicable (a concrete next step, not just a vague note).
  • （該当する場合、少なくとも1つの具体的な次の一手につながる指摘があること。）
  • It includes clear evidence that can be traced to the diff (file and line).
  • （差分（ファイルと行）に追跡できる明確な根拠が含まれること。）
  • It avoids noise (no “nit” spam) and stays focused on meaningful risks.
  • （ノイズ（“nit”の濫発）を避け、意味のあるリスクに集中していること。）

良いスキルの目安​

  • 指摘が「当たる」確率が高い（誤検知が少ない）
  • 修正案が具体的で、次の一手が明確である
  • ノイズが少なく、1観点に集中している

より厳密な採用基準（優先順）は pages/guides/governance/skill-policy.md を参照してください。