skill-optimization

# スキルコンテンツ最適化 ## 基本方針 1. **指摘ベース**: すべての変更は、記録済みの指摘を解消するか、明記されたプロジェクト固有の情報源に従う 2. **具体的**: 各パターンに検出条件と変換方法を提供 3. **構造特化**: 表現と構成を最適化し、ドメイン知識は変更しない 4. **意図を保持**: 構造、表現、制約、コンテキスト、例を変える前に、元の要件を記録する 5. **追跡可能**: 適用するすべての変更を、指摘または明記されたプロジェクト情報源へ結び付ける 6. **自己完結**: 各pure skillを単独で読み込んでも実行できる状態に保つ。単独での実行に同じ内容が必要な場合は、独立して読み込まれるpure skill間の重複を許容する ## コンテンツ最適化パターン ### P1: 重大（修正必須） スキル読み込み時のLLM実行精度に直接影響する問題。 #### BP-001: 否定形の指示 → 肯定形への変換 | 検出条件 | 変換方法 | |----------|----------| | 「〜しない」「〜を避ける」「禁止」等の否定形指示 | 望ましい操作または許可された状態を先に示す。違反が不可逆な運用操作であり、呼び出し元が通常は回復できず、肯定形だけでは境界が曖昧になる場合に限り、明示的な禁止を残す。その場合も、安全な代替手段と境界を越えるための条件を併記する。レビュー可能な品質方針は肯定形に書き換える。 | **例外の境界例**: - 許容: 「不要になった記録は復元可能なarchiveへ移す。ユーザーが恒久削除を明示的に許可した場合を除き、完全には削除しない」 - 肯定形に書き換え: 「問題を捏造しない」→「全ての指摘をBPパターンまたは10原則に基づいて行う」、「P1問題を省略しない」→「全レビューモードで全P1問題を評価する」、「P1がある時にグレードAを付与しない」→「P1問題が0件の場合のみグレードAを判定する」 品質ポリシー、ロール境界、採点基準、一般的な作業ルールは常に肯定形を使用する。呼び出し元が検証・上書き・破棄する出力は不可逆ではない。 **スキルでの例:** - 変更前: 「汎用的な変数名を使わないこと」 - 変更後: 「目的を表す具体的な変数名を使用する（例: `x`ではなく`userId`）」 **スキルで重大な理由**: 禁止だけでは、実行すべき目標状態が示されない。 #### BP-002: 曖昧な指示 → 具体的な判断基準 | 検出条件 | 変換方法 | |----------|----------| | 成果に必要な判断を残す曖昧語（「適切に」「良い」「正しく」「ベスト」「明確に」等）で、解釈の違いが実行や検証を実質的に変えるもの | **必要な精度を満たす、最も制約の少ない基準**で解決する（手順は下記） | | 形式・長さ・スコープ・トーン・成功基準が未定義でも、想定されるどの解釈でも成果を同等に満たすもの | 許容される自由度として扱い、解釈を一つに絞る必要がある場合のみ制約を追加する（下流の利用側が要求する形式はBP-003を参照） | **解決手順**（1行目の該当箇所向け）: 1. 必要な精度を満たす、最も制約の少ない基準を選ぶ（除外する有効な挙動が最も少ない、測定可能なif-then基準または閾値）。 2. その**精度への寄与**を記録する: その明確化によって、意図した成果に関するどの観測可能な出力差が改善されるか。 3. その**制約コスト**を記録する: 元の意図が許容していたのに除外してしまう有効な解。 4. 精度への寄与を特定でき、かつ制約コストが元の意図を保つ場合にのみ適用する。 5. 入力やプロジェクトのコンテキストから判断できない場合は、推測せず判断に必要な情報源を記録する。 **スキル例外**: 入力コンテキストから一意に解決できる表現（例: ユーザーのプロンプトと照合できる状況での「ユーザーが省略した箇所」）は曖昧ではない — 主観的判断ではなく決定論的な処理を記述している。 **スキルでの例:** - 変更前: 「エラーは適切に処理する」 - 変更後（基準を情報源から導出した場合）: 「プロジェクトのエラーハンドリング方針（docs/error-handling.md）に従う。外部API呼び出し・ファイルI/O・JSON.parseをtry-catchで囲み、error.name・error.stack・タイムスタンプをログ出力し、呼び出し元での処理が必要な場合はコンテキスト付きで再throwする。」 - 変更後（情報源がない場合）: 「try-catch対象・ログ項目・閾値を根拠なく設定する代わりに、判断に必要な情報源として『エラーハンドリング方針』を記録する。」 **スキルで重大な理由**: 曖昧な指示は、成果に影響する振る舞いを、基準なしにモデルへ選ばせる。 #### BP-003: 出力形式の欠落 → 構造化出力の明示 | 検出条件 | 変換方法 | |----------|----------| | 何をすべきかは書いてあるが成果物の形式が未定義 | 出力の利用側が要求する構造・フィールド・順序を定義した出力セクションを追加する（パース、振り分け、比較、検証のため）。慣習で形式を選ばない | スキルレビューの出力契約には、BP-001〜BP-009の網羅結果、再レビューでも維持する指摘ID、重大度、場所、引用した根拠、根拠付きで却下した指摘、保持すべき要件、未解決の入力、最終評価を含める。スキル作成の出力は、完成した`SKILL.md`の内容と、必要な同一ディレクトリ内のreferenceまたはscriptとする。 **スキルでの例:** - 変更前: 「コードの問題を分析する」 - 変更後（レビューレポートの利用側が要求する形式）: 「`## 検出した問題` を、レポート描画側がパースできるテーブルで出力する: | 重大度 | 箇所 | 説明 | 修正案 |」 **スキルで重大な理由**: 構造化出力の制約はハルシネーションを抑制し、スキル適用結果の一貫性を確保する。 #### BP-009: 作業の無制限な生成 → 成果に比例した作業 | 検出条件 | 変換方法 | |----------|----------| | 指摘、可能性、または技術的に有効な改善が、成果、必要な境界、実際の利用側、必要な証明を変えないまま必須作業になる | 候補として扱い、必要な作業だけを残し、変更なし、再利用、根拠に基づく却下を許容する | | 調査範囲が実装または成果物の範囲を決める | 必要な成果を観測できた時点で完了し、発見だけを理由に作業を増やさない | **スキルで重大な理由**: 能力の高いモデルは暗黙の義務も実行するため、根拠のない可能性が成果を改善せずに作業を生み出す。 ### P2: 高影響（修正推奨） 対処により実効性が向上する問題。 #### BP-004: 未構造化コンテンツ → 整理されたフォーマット | 検出条件 | 変換方法 | |----------|----------| | 見出しのない文章の塊 | 標準セクション順序を適用（下記参照） | | 複数トピックが1セクションに混在 | 見出し付きの個別セクションに分割 | | 参照データがリスト形式のまま | テーブル形式に変換 | **標準セクション順序:** 1. コンテキスト/前提条件 2. 中核概念（定義、パターン） 3. プロセス/手順（ステップ形式） 4. 出力形式/具体例 5. 品質チェックリスト 6. 参照 **適用条件**: 30行未満かつ単一トピックのスキルには構造化を省略。 #### BP-005: コンテキストの不足・過剰 → 必要十分なコンテキスト | 検出条件 | 変換方法 | |----------|----------| | 記述されていない前提知識に依存 | 必要な前提を列挙したPrerequisitesセクションを追加 | | 定義なしにドメイン用語を使用 | インラインまたは用語テーブルで定義を追加。**スキル例外**: LLMのベースライン知識に含まれる用語（広く使われる技術用語、標準的なドメイン語彙）は定義不要。プロジェクト固有の用語、内部命名規則、LLMの一般知識に含まれないドメイン用語のみ明示的な定義が必要。 | | 使用場面の指針がない | 具体的なシナリオ付きのトリガー条件を追加 | | 後続の判断・実行・検証に影響せず、重複している、本筋から逸れる、または実行に結び付かないコンテキスト | 繰り返される事実を一つの実効的な記述に集約する。抽出した事実だけが必要な場合は、元の背景情報はパスや参照の形で残す。プロジェクト固有の事実には情報源を明記する。 | **スキルでの例:** - 変更前: 「移行にはStrangler Patternを適用する」 - 変更後: 「**前提**: モジュール境界が識別可能な既存モノリス。**使用場面**: 本番トラフィックを維持しながらレガシーモジュールを置換する場合。」 #### BP-006: 手続き制御の不足・過剰 → 根拠に基づくゲート | 検出条件 | 変換方法 | |----------|----------| | 前提となる根拠がなければ後続の操作が無効になる | 必要な根拠と遷移条件を示すゲートを追加する | | 権限、不可逆な操作、機械が読み取る契約、完了条件が暗黙的 | その境界を明示する | | 可逆な選択に一つの経路を必須としている | 目的、根拠、選択基準を示し、経路はモデルに選択させる | | 機械による厳密な形式要求がないのに、特定のラベルや成果物だけをゲートが要求する | 意味的に同等な根拠を受け入れる | **要点**: 予測した経路ではなく、境界と必要な根拠を制御する。 スキル作成では、以下の3つのゲートを順に使用する： 1. **分析ゲート**: 元の要件を記録し、BP-001〜BP-009をすべて確認し、各指摘に根拠があり、忠実な作業を妨げる未解決の入力がない 2. **最適化ゲート**: 各指摘に適用または見送りの解決方法が1つあり、すべての変更を追跡でき、保持すべき要件が残っている 3. **バランスゲート**: 意図の保持、判断に必要な情報、情報密度、制約の必要性、作業量の妥当性、追跡可能性を確認してから最終結果とする レビュー指摘に基づく修復では、現状レビューを分析の根拠とし、合意済みの修復範囲に最適化ゲートとバランスゲートを適用する。 ### P3: 改善（対応可能なら） 特定の状況で効果がある段階的な改善。 #### BP-007: 不要または偏った例示 → 必要最小限の例 | 検出条件 | 変換方法 | |----------|----------| | LLMが既に知っている挙動を例が繰り返しているだけ | 簡潔なルールまたは利用側が要求する出力形式に置き換え、例を削除する | | ドメイン・製品・組織固有のマッピング、非自明な例外、ルールで表現できない境界を例が担っている | その曖昧さを解消できる最小限の例だけを残し、各例を対応する曖昧さに紐づける | | 複数の例が同じ曖昧さを解消している、または全例が同じ表層パターン | 必要最小限の例に絞り、別の曖昧さを解消する場合だけ異なるケースを追加する | #### BP-008: 不確実性の許容なし → 明示的なエスカレーション | 検出条件 | 変換方法 | |----------|----------| | 常に確定的な回答を要求 | 主張を観測事実・推論・不明に分類し、曖昧な場合のエスカレーション基準を追加 | | 「いつ止めるか」の指針がない | 「不明」が次のステップを塞ぐ場合、そのゲートで停止し、続行に必要なエビデンスまたはユーザー判断を明示する | **スキルでの例:** - 変更前: 「根本原因を特定する」 - 変更後: 「根本原因を観測済み、推測、不明のいずれかに分類する。不足している根拠によって次のステップへ進めない場合は、現在のゲートで止まり、継続に必要な根拠またはユーザー判断を具体的に示す。」 ## 10の編集原則 スキルコンテンツの測定可能な品質基準。各原則に合否判定基準を設定。 | # | 原則 | 合格基準 | 不合格例 | |---|------|----------|----------| | 1 | コンテキスト効率 | 各文がベースライン外の知識、判断規則、必要な境界、または実行根拠を提供する | 観測された失敗、レビュー指摘、プロジェクト要件との関係がないベースライン知識の説明 | | 2 | 重複排除 | 1つのスキル内で同じ抽象度の概念を二重に説明しない。独立して読み込まれるpure skill間の重複は、各スキルの単独実行に必要な場合は有効とする。その場合はsibling skillへの参照に置き換えず、意味の整合性を確認する | 1つのスキル内で、異なる実行上の役割を加えずに同じルールを再記述 | | 3 | 関連内容の集約 | 関連する基準を1セクションに集約（読み込み回数最小化） | エラーハンドリング規則が4セクションに散在 | | 4 | 測定可能性 | 各基準が観測可能なエビデンス、決定論的な判断ルール、または根拠のある閾値を示す | 「きれいなコードを書く」に観測可能な条件がない | | 5 | 肯定形 | 指示は「何をするか」を記述（BP-001適用済み） | 「一切使わないこと」→「Xのみ使用する」 | | 6 | 表記の一貫性 | 見出しレベル、リスト記法、テーブル形式が統一 | 同一文脈で`-`、`*`、`1.`が混在 | | 7 | 前提条件の明示 | プロジェクト固有・非ベースラインの前提を記述またはリンクする。ベースラインの技術知識は簡潔にとどめる | 「DI」を定義もリンクもせずに使用 | | 8 | 重要度順の記述 | 最重要項目が先頭、例外は末尾 | エッジケースが共通パターンより先に記述 | | 9 | スコープ境界 | スキルが扱う範囲と、条件付き内容を有効にする条件を明示する。pure skillは単独実行に必要なコンテキストを自身に含める。スキル間参照は、orchestrationまたはskill selectionを担うスキルに限定する | 他のpure skillにも同じ内容があることを理由に、実行に必要なルールがpure skillから欠けている | | 10 | 作業量の妥当性 | 必須の成果物、テスト、ゲート、判断が、成果、境界、利用側の結果、または必要な証明を変える | 全ての指摘や技術的に有効な改善を実装必須にする | ## References - **スキル生成時**: [references/creation-guide.md](references/creation-guide.md) - 生成フローとdescription指針 - **スキルレビュー時**: [references/review-criteria.md](references/review-criteria.md) - 評価フローとグレード判定基準