mcpField
P
performance

performance

github.com/duc01226開発1239 回インストール1 週間前に更新
リポジトリ

performance について

コード性能を調査するエージェント向けのワークフロースキルです。特にデータベースの無駄を対象に、ボトルネックの検出、測定、分析、検証を段階的に進めます。

主な機能

  1. 01段階的な性能調査
  2. 02測定と証拠の記録
  3. 03DB性能要因の個別確認
  4. 04変更前後の検証

活用シーン

  1. 01遅いクエリや全件スキャンの調査
  2. 02ループ内のクエリ増加の分析
  3. 03無制限ロードとメモリリスクの確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/duc01226/easyplatform --skill performance

インストール後、Claude Code で/performanceを入力して読み込まれたか確認します。

詳細

Codex 互換性に関する注意:

  • Codex では $skill-name を使ってリポジトリのスキルを呼び出します。このミラーコピーでは、従来の Claude の /skill-name 参照を書き換えています。
  • タスクトラッカーの必須ルール:ワークフローまたはスキルの手順を実行する前に、すべての手順のタスク追跡を作成または更新し、進捗に応じて同期してください。
  • ユーザーへの質問を求めるプロンプトは、Codex でユーザーに直接質問することを意味します。
  • Claude 固有のモード切り替え指示が含まれている場合は無視してください。
  • 厳格な実行契約:ユーザーがスキルを明示的に呼び出した場合は、そのスキルのプロトコルに記載されたとおりに実行してください。
  • サブエージェントの使用許可:スキルがユーザーによって呼び出された場合、または AI が検出した場合に、そのプロトコルがサブエージェントを必要とするなら、そのスキルの有効化によって、そのタスクに必要な spawn_agent サブエージェントの使用が許可されます。
  • ユーザーが逸脱を事前に明示的に承認しない限り、プロトコルの手順を省略、並べ替え、統合しないでください。
  • ワークフロースキルでは、列挙された各子スキルの手順を明示的に実行し、手順ごとの証拠を報告してください。
  • 必須の手順やツールをこの環境で実行できない場合は、適応策を講じる前に停止してユーザーに確認してください。

Codex でのプロジェクト参照資料の読み込み(フックなし)

Codex では、Claude のフックによるドキュメントの自動挿入は行われません。 コーディング、計画、デバッグ、テスト、レビューを行う際は、以下のルートに従ってプロジェクトのドキュメントを明示的に開いてください。

必ず読むもの:

  • docs/project-config.json(プロジェクト固有のパス、コマンド、モジュール、ワークフローおよびテスト設定)
  • docs/project-reference/docs-index-reference.md(docs/project-reference/* のカタログ全体へのルート)
  • docs/project-reference/lessons.md(常に適用されるガードレールとアンチパターン)

状況に応じて読むドキュメント:

  • バックエンド/CQRS/API/ドメイン/エンティティの変更:backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
  • フロントエンド/UI/スタイリング/デザインシステム:frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
  • 仕様/テストケースの計画または TC マッピング:feature-docs-reference.md
  • 結合テストの実装/レビュー:integration-test-reference.md
  • E2E テストの実装/レビュー:e2e-test-reference.md
  • コードレビュー/監査作業:code-review-rules.md と、変更対象のファイルに応じた上記のドメインドキュメント

すべてのドキュメントをむやみに読まないでください。まず docs-index-reference.md を確認し、タスクに関連するファイルのみを開いてください。

[IMPORTANT] 必ずプロジェクト全般に適用できる形で注意してください。評価を下す前に、ローカルの技術スタック、規約、クエリ API、インデックス定義、メトリクス、レポートのパスを特定してください。 [IMPORTANT] パフォーマンスに関する主張はすべて、計測または静的な証拠で裏付けてください。証拠には file:line、クエリのテキスト/構造、行数、クエリプラン/explain 出力、トレース、プロファイル、ログなどを用います。 [IMPORTANT] データベースのパフォーマンスは、一度に一つの観点だけをレビューしてください。対象は、過剰なデータ取得、フィルター、インデックス、N+1 の呼び出し増加、バッチ処理、集約/結合の構造、実体化、書き込み、キャッシュです。

[BLOCKING] スキルの手順は、宣言された順序で実行してください。ユーザーの明示的な承認なしに、手順を省略、並べ替え、統合してはいけません。 [BLOCKING] 各手順/サブスキルを呼び出す前に、タスク追跡を更新してください。手順の開始時に in_progress、終了時に completed を設定してください。 [BLOCKING] 完了またはスキップした各手順には、簡潔な証拠または明示的なスキップ理由を必ず記載してください。 [BLOCKING] タスク管理ツールを利用できない場合は、同等の手順別トラッカーを用意し、ステータスを同期してください。

クイックサマリー

目標: 実際のパフォーマンス上のボトルネック、特にデータベースの無駄を見つけます。対象には、行数や列数が多すぎること、インデックスの不足や未使用、ループ内クエリによる呼び出しの増大、上限のないデータの実体化、遅い結合や集計、書き込み増幅などがあります。

ワークフロー:

  1. 検出 - 対象範囲とボトルネックの種類を分類します。
  2. 調査 - ローカルコード、メトリクス、ドキュメント、クエリやインデックスの定義、類似パターンを読み取ります。
  3. 測定 - ベースラインを取得するか、静的レビューのみであるリスクを明示します。
  4. 分析 - 証拠を示しながら、各観点を順に検証します。
  5. 計画 - 動作を維持する、最小限の修正を提案します。
  6. 検証 - 再測定し、テストを実行して、別の視点からレビューします。

重要なルール:

  • 必須:必ず修正前後を測定してください。静的レビューで見つかった問題には、明示的な検証コマンドが必要です。
  • 必須:必ず行の絞り込みを、列の選択やキャッシュより前にデータソースへ適用してください。列を減らすより、行数を減らす方が優先です。
  • 必須:インデックスが存在するかどうかだけでなく、クエリの形状や順序を踏まえて、インデックスが利用可能かを必ず検証してください。
  • クエリの形状、インデックス、ページネーション、バッチ処理、データ量を把握するまでは、キャッシュを推奨しないでください。
  • パフォーマンスに関する重要な作業では、1 回のレビューだけで PASS と判断しないでください。別の視点からの検証を行ってください。

$ARGUMENTS


フェーズ 0:対象範囲の検出

分析の前に分類します。検出結果に基づいて、検証する観点、証拠、サブエージェントを決めます。

対象範囲兆候主な証拠
DB 読み取りクエリの遅延、全件スキャン、ソートのスピル、調査対象行数が多いクエリテキスト/ORM 式、行数、実行計画/explain、インデックス
DB 書き込み保存の遅延、ロック待ち、行ごとの更新、トランザクションの肥大化書き込みループ、バッチサイズ、ロック/デッドロックログ、トランザクションの範囲
N+1/呼び出し増大クエリ/API 呼び出しを含むループ、遅延読み込み、項目ごとの検索呼び出し元のトレース、クエリ数、ループのソース
API レイテンシp95/p99 の高さ、タイムアウト、エンドポイント/ジョブの遅延トレース/プロファイル/ログ、呼び出しチェーン
メモリ/OOM大量のデータの実体化、BLOB、ページネーションなし、バッファリングメモリ割り当てプロファイル、結果のサイズ、コレクションの読み込み
フロントエンドレンダリングの遅延、巨大なバンドル、繰り返されるフェッチ、DOM の頻繁な更新ブラウザープロファイル、ネットワークウォーターフォール、コンポーネント/レンダリングのトレース
分散システムメッセージの遅延、サービス間のウォーターフォール、リトライの集中トレーススパン、キューメトリクス、コンシューマー/プロデューサーの呼び出しチェーン

対象によって範囲が明示的に限定され、証拠によって特定の観点が無関係だと確認できる場合に限り、その観点をスキップできます。


フェーズ 1:ローカルコンテキストの調査

問題を指摘する前に、必ず調査します。

  • 必須:ローカルの標準やガイドを必ず検索してください。対象:performance、index、query、pagination、projection、database、profiling、contributing、style guide。
  • 必須:修正を提案する前に、ローカルにある類似のクエリ/API パターンを 3 件以上検索してください。
  • 必須:対象のコードと、クエリ対象データを制御するインデックス/マイグレーション/スキーマのファイルを読んでください。
  • 必須:利用可能なグラフ/呼び出しトレース/プロファイラーツールを使って、呼び出し元と呼び出し頻度を特定してください。利用できるツールがない場合は、grep/import/呼び出し階層を利用してください。
  • 必須:データの形状を特定してください。テナント/セキュリティフィルター、カーディナリティ、想定される最大行数、選択する列/フィールド、ソート、結合、集計/グループ化、キャッシュキーを確認してください。
  • プロジェクト名、リポジトリパス、ID の形式、DB エンジン、ORM、フレームワークのデフォルトを決め打ちしないでください。調査で見つかったファイルから判断してください。

フェーズ 2:ベースラインの根拠

可能な場合は、実行時の証拠を優先してください。実行時の証拠を得られない場合は、調査結果に static risk と明記し、検証に必要な正確なコマンド/クエリを記載してください。

DB に関する調査結果で必ず確認するベースライン:

  • クエリの出所を必ず記録してください:file:line と、取得可能な場合は生成された SQL/クエリ/ORM 式
  • データ量を必ず記録してください:入力サイズ、一致した行数、返された行数、調査/スキャンされた行数、ページサイズ/上限
  • アクセスパスを必ず記録してください:取得可能な場合は、クエリプラン/explain、使用されたインデックス、ソート/グループ化の方法、結合方式
  • 所要時間を必ず記録してください:p50/p95/p99、クエリの経過時間、クエリ数、割り当て量またはレスポンスサイズ
  • コンテキストを必ず記録してください:エンドポイント/ジョブ/コンシューマーの実行頻度と、最悪ケースのファンアウト

確信度:

確信度対応
95%+自由に修正を推奨してください。
80-94%注意事項と検証コマンドを添えて推奨してください。
60-79%まず不明点を列挙し、修正前に証拠をさらに集めてください。
<60%STOP。推奨しないでください。

フェーズ 3:次元ごとの個別調査

必ず、次元ごとに焦点を絞った調査を 1 回ずつ行ってください。すべての次元を一度に調査してはいけません。

1. クエリ形状とデータ最小化

考えること: どの行/列が読み込まれますか?フィルター、射影、ソート、上限は、データを実体化する前にデータソースで実行されていますか?

必ず次の問題を調査してください:

  • ページ、上限、カーソル、または範囲が限定されたビジネスルールがない、上限なしのリスト/全件読み込み API
  • 実体化後のフィルター処理(ToList/配列化/全件読み込みの後に Where/filter を実行)
  • 実体化後の射影。リスト/概要表示のためにエンティティ/ドキュメント全体を読み込んでいる
  • 不要な include/結合/参照データ。リストクエリで大きなテキスト/blob/json フィールドを取得している
  • クライアント側のソート/グループ化/重複排除。カーソル/キース​​を使用したページネーションが適しているのに、非常に深いページでオフセットページネーションを使用している
  • ホットパスのクエリでテナント/認証/ステータス/日付のフィルターが欠けている

修正では、述語をデータソースに渡すこと、必要なフィールドのみを選択すること、結果セットに上限を設けること、深いページの連続アクセスにカーソル/キース​​を使用すること、ローカルで特定したドメイン/クエリ所有者のレイヤー付近に再利用可能な述語を保持することを必ず優先してください。

2. インデックスとアクセスパス

考えること: 実際のクエリ順序において、既存のインデックスで等価/範囲フィルター、結合、ソート、グループ化、射影を処理できますか?

必ず次の問題を調査してください:

  • カーディナリティの高いフィルター、結合、外部キー、ソート列、または頻繁に使用されるグループ化キーにインデックスがない
  • 複合インデックスのフィールド順が、等価条件 → 範囲条件 → ソートのアクセスパターンと一致していない
  • インデックスは存在するものの、フィールドを関数で囲むクエリ、互換性のない型/照合順序、先頭ワイルドカード、広範な OR、否定述語、または選択性の低さが原因で、プランがインデックスを無視している
  • インデックスの順序がフィルター条件と order by に一致せず、ソートのスピル/ファイルソートが発生している
  • ホットな狭いクエリで、カバリング/部分/フィルター付きインデックスを活用できる
  • 書き込みコストを分析せず、あらゆるフィールドを追加したことによるインデックスの肥大化

修正では、最小限で有用なインデックスの追加/調整、クエリに合わせた複合キーの順序変更、述語の SARGable 化、修正前後のプラン/explain による検証、書き込みコストのリスクの明記を必ず優先してください。

3. N+1 とファンアウト

考えること: 作業量は、リクエスト/ジョブ数ではなく項目数に応じて増加しますか?

必ず次の問題を調査してください:

  • ループ、map、シリアライザー、リゾルバー、テンプレート/レンダリングループ、イベントハンドラーループ内でのクエリ/API/キャッシュ呼び出し
  • 項目ごとの存在確認/件数取得。項目ごとの遅延読み込みリレーション
  • ID の異なる同一検索を繰り返しており、1 回の IN/バッチ/グループ化クエリにまとめられる
  • サービス、キュー、ジョブ、リトライをまたぐネストしたファンアウト
  • 独立した呼び出しをバッチ化するか、安全なリソースを個別に使用して上限付き並列処理を行えるのに、await が逐次的に実行されている

修正では、ID を一度にまとめて処理すること、必要なフィールドのみを join/include すること、辞書を事前取得すること、1 回のクエリで件数を集計すること、並列処理に上限を設けること、順序/認可のセマンティクスを維持することを必ず優先してください。

4. 集約、結合、パイプラインの形状

考慮事項: 高コストな結合/展開/グループ化/ソート/ウィンドウ処理の前に、パイプラインでデータを絞り込んでいますか?

必ず以下を確認してください:

  • 絞り込み条件の前に結合/展開/グループ化が行われている
  • デカルト結合や重複の展開が集約されていない
  • 事前の絞り込みや対応するインデックスなしで、グループ化/ソートが行われている
  • 存在確認/件数/最小値/最大値だけが必要なのに、集約処理ですべての関連行/ドキュメントを読み込んでいる
  • データベースで安全に処理できる後処理が繰り返されている

必ず次の修正を優先してください:早い段階で絞り込む、早い段階で必要な項目だけを取得する、データの取得元で集約する、結合のカーディナリティを下げる、存在確認/件数取得のクエリを使う、配列/子要素のセマンティクス上必要な場合は、展開後にも必要な絞り込みを繰り返す。

5. 実体化とメモリ

考慮事項: 何がメモリに読み込まれますか? 読み込み量に上限があり、ストリーミングされ、読み取り専用の場合は追跡されないようになっていますか?

必ず以下を確認してください:

  • ページ分割/絞り込みの前に大きなコレクションが実体化されている
  • 読み取り専用クエリで、不要なエンティティ/オブジェクトの追跡が行われている
  • 軽量なレスポンスに大きな BLOB/ファイル/JSON フィールドが読み込まれている
  • ストリーミング/チャンク処理が可能なのに、エクスポート/レポート全体をバッファリングしている
  • 意図せず複数回列挙され、クエリが再実行されている

必ず次の修正を優先してください:ページ分割/チャンク処理/ストリーミングを行う、ローカルスタックが対応している場合は追跡なし/読み取り専用モードを使う、軽量な DTO をプロジェクションする、読み込み前に絞り込む、意図的にメモ化する。

6. 書き込み処理、ロック、トランザクション

考慮事項: 書き込み処理は安全にバッチ化され、ロック/トランザクションは小さく保たれていますか?

必ず以下を確認してください:

  • ループ内で行ごとに保存/更新/削除している
  • リモート呼び出しや負荷の高い読み取りを含む長時間のトランザクション
  • 一括検証ではなく、行ごとに不要な一意性チェックを行っている
  • ロックのエスカレーション/ホット行の競合/バッチ化されていないカウンター更新
  • 並列書き込みで、安全でないセッション/コンテキスト/ユニットオブワークを共有している

必ず次の修正を優先してください:一括書き込み、チャンク処理、トランザクションの短縮、リモート呼び出しをトランザクションの外に移す、冪等なコマンドを使う、並列ワーカーごとに新しく安全なスコープ/コンテキストを作成する。

7. キャッシュと再利用

考慮事項: 繰り返し発生する高コストな処理は安定しており、安全に再利用でき、適切に無効化されていますか?

必ず以下を確認してください:

  • 同じルックアップがリクエスト/ジョブ内で繰り返されている
  • 頻繁に使われる参照データがリクエストのたびに取得されている
  • キャッシュキーにテナント/ユーザー/認証/フィルター/バージョンの各要素が含まれていない
  • キャッシュによって、上限のないクエリや古くなったセキュリティ上重要なデータが隠れている

必ず次の修正を優先してください:まずリクエストスコープでメモ化し、次に、明示的なキー、TTL/無効化、サイズ制限、プライバシー制約、ヒット/ミスのメトリクスを備えた、上限付きの共有キャッシュを使う。

8. API、分散処理、フロントエンド

考慮事項: 遅い処理の原因は、ネットワークのウォーターフォール、ペイロードのサイズ、レンダリングの過剰な再実行、バックグラウンド処理のファンアウトのいずれですか?

必ず以下を確認してください:

  • エンドポイントが、ビューに必要な量を超えるペイロードを返している
  • バックエンドでの集約やバッチエンドポイントが適しているのに、リモート呼び出しを逐次実行している
  • メッセージコンシューマーが、バッチ化/バックプレッシャーを使わずにアイテムごとにメッセージを送信している
  • フロントエンドで、フェッチの繰り返し、リストの仮想化の欠如、コストの高いレンダリングループ、安定したキー/track-by の欠如が見られる
  • バンドルまたはアセットの読み込みが操作の大半を占めている

必ず次の修正を優先してください:API 呼び出しをバッチ化する、ペイロードを減らす、バックプレッシャーを追加する、大きなリストを仮想化する、レンダリングキーを安定させる、使用頻度の低いアセット/ルートを遅延読み込みする、ブラウザー/ネットワークのトレースを計測する。


フェーズ 4:指摘事項と重大度

指摘事項の形式:

- [Severity] [file:line] [dimension] Problem. Evidence: metric/plan/query count. Impact: user/system effect. Fix: smallest behavior-preserving change. Verify: command/query/metric.

重大度:

  • Critical:サービス停止/OOM/データ破損のリスク、上限のないホットパス、ロックの多発、制御不能なファンアウト。
  • High:p95/p99 のタイムアウトのリスク、大規模/高頻度のテーブル/コレクションに対するフルスキャン、ユーザーに表示されるリストでの N+1、ページ数の上限なし。
  • Medium:回避可能な過剰取得、最適でないインデックス、繰り返し行われるルックアップ、中程度のメモリの無駄。
  • Low:測定可能な効果が小さい整理、または将来に備えた改善。

本番環境に近い規模/頻度の根拠なしに、重大度を決して引き上げないでください。


Phase 5: 最適化計画

コードを変更する前に:

  • ベースライン、変更案、動作上の不変条件、リスク、検証コマンド、ロールバック手順を必ず提示してください。
  • 機能上の動作、認可、順序、ページネーションのセマンティクス、一貫性、冪等性を必ず維持してください。
  • 動作、SLA、公開契約、または制限が変更される場合は、影響を受けるテスト/仕様/ドキュメントを必ず確認してください。
  • ユーザーが動作の変更を承認しない限り、速度を向上させるためだけにクエリのセマンティクスを変更してはなりません。
  • 書き込みコスト、ストレージコスト、無効化、プライバシーを分析せずに、広範なインデックス/キャッシュを追加してはなりません。

サブエージェントへのルーティング

利用可能な場合は、専門的なサポートを活用してください。

検出した対象サブエージェント
DB/クエリ/N+1/メモリ/バックエンドのホットパスperformance-optimizer
認証、PII、テナント分離、機密性の高いキャッシュキーまずsecurity-auditor、次にperformance-optimizer
サービス間アーキテクチャ、キャッシュポリシー、容量/SLO のトレードオフアーキテクチャ/パフォーマンスの専門家
フロントエンドのレンダリング/バンドル/ネットワークのウォーターフォールフロントエンドまたはパフォーマンスの専門家

サブエージェントへのプロンプトには、対象、検出した範囲、ローカルコンテキストの根拠、必要な観点、レポートのパス、および「要約のみを返し、完全なレポートは逐次書き込むこと」を必ず含めてください。


フレッシュアイズ品質ループ

  1. ラウンド 1:根拠を添えて、検出結果/計画を作成します。
  2. ラウンド 2:新しいレビュアーを起用するか、記憶を持たない視点からレビューを最初からやり直し、見落としたボトルネック、誤検知、根本原因の誤認、安全でない修正案に異議を唱えます。
  3. 問題が見つかった場合:計画を修正し、新しいレビュアーによるレビューを受けます。
  4. 最大 3 ラウンドで停止し、ユーザーに判断を求めます。

重大なレビューでクリーンな PASS を出すには、フレッシュアイズによる検証、または明示的なスキップ理由が必須です。


出力

最終レポートには、次のセクションを必ず含めてください。

  • 対象範囲と検出したボトルネックの種類
  • ベースラインの根拠と不明点
  • 重大度順に並べた検出結果
  • 最適化計画と却下した代替案
  • 変更前後のメトリクスを含む検証計画
  • テスト/仕様/ドキュメントへの影響、または明示的なスキップ理由
  • 確信度と前提条件

根拠が不十分な場合は、次を出力してください:Insufficient evidence. Verified: [...]. Not verified: [...]. Next evidence needed: [...].

最後のリマインダー

必須・重要・必ず注意 プロジェクト固有の事情に沿ってください。判断を下す前に、ローカルの技術スタック、規約、クエリ API、インデックス定義、メトリクス、レポートのパスを調べてください。 必須・重要・必ず注意 パフォーマンスに関する主張はすべて、測定値または静的な証拠で裏付けてください。file:line、クエリのテキストや形状、行数、クエリプラン/EXPLAIN の出力、トレース、プロファイル、ログなどが該当します。 必須・重要・必ず注意 データベースのパフォーマンスは、一度に一つの観点から確認してください。過剰なデータ取得、フィルター、インデックス、N+1 の呼び出し増加、バッチ処理、集約/結合の形状、マテリアライズ、書き込み、キャッシュを確認します。 必須・重要・必ず注意 必ず変更前後を測定してください。静的レビューで見つかった問題には、明示的な検証コマンドが必要です。 必須・重要・必ず注意 実際のクエリ形状/順序とクエリプラン/EXPLAIN を使って、インデックスが利用可能か必ず検証してください。インデックスが存在するだけでは証明になりません。 必須・重要・必ず注意 行フィルターは、射影やキャッシュの前に必ずデータソースへ適用してください。列を絞るより、行数を減らすほうが効果的です。 重要・必ず注意 重大なパフォーマンス作業で PASS とする前に、必ず新たな視点から問題点を検証してください。 重要・必ず注意 ドキュメント/テスト/仕様の陳腐化を確認する最終レビュータスクを追加してください。

合理化を防ぐための指針:

言い逃れ反論
「ボトルネックは明らかだから、ベースラインは省略する」測定がなければ推測です。メトリクスを記録するか、静的なリスクとして示してください。
「インデックスがあるから、クエリは問題ない」クエリプラン/EXPLAIN とアクセス経路を示してください。使われていない既存インデックスは何の証明にもなりません。
「射影だけで十分」まず行数を減らしてください。行数が多すぎる状態で列を減らしても、処理が無駄になります。
「とにかくキャッシュすればいい」まずクエリ形状/インデックス/範囲を修正してください。キャッシュは古いデータ、安全でない処理、無制限の処理を隠す可能性があります。
「コード内にクエリは一つだけ」ループ、シリアライザー、リゾルバー、利用側、リトライをたどってください。呼び出しの増加は、上流に隠れていることがよくあります。

[TASK-PLANNING] 作業を始める前に、小さな追跡可能なタスクに分割し、各タスクのステータスをすぐに更新してください。

フックなしプロンプトプロトコルのミラー(自動同期)

ソース:.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] ワークフロー実行プロトコル — 必須・重要・厳守。いかなる理由があっても省略しないでください。

汎用的な移植性の境界: 再利用可能なスキルとプロトコルのテキストはプロジェクトに依存しないものとします。プロジェクト固有の規約は、docs/project-config.json と docs/project-reference/ から確認してください。shared/sdd-artifact-contract.md の共通 AI-SDD を適用します。docs/project-config.json と docs/project-reference/docs-index-reference.md を読み、そこに記載されているプロジェクト参照ドキュメントを開いてください。この共通コンテキストとローカルドキュメントを利用できる場合は、サポートされている任意の AI ツールで実行できます。

  1. 検出: プロンプトをワークフローカタログと照合します
  2. 分析: 最適なワークフローを見つけ、カスタムのステップ構成のほうが適しているかどうかも評価します
  3. 確認(必須形式): ユーザーが明示的にワークフロー/スキルを呼び出し、かつローカルプロトコルで明示的な呼び出しを確認とみなす場合を除き、次の構成でユーザーに直接質問します
    • 質問:"どのワークフローを有効にしますか?"
    • 選択肢 1:"[最適なワークフロー] を有効にする(推奨)"
    • 選択肢 2:"カスタムワークフローを有効にする:[step1 → step2 → ...]"(1 行で理由を記載)
  4. 有効化(確認後): 標準ワークフローの場合は $workflow-start <workflowId> を呼び出し、カスタムステップの場合は手動で順に実行します
  5. タスクを作成: ワークフローのすべてのステップについてタスク追跡を行います
  6. 実行: 各ステップを順番に実行します [CRITICAL-THINKING-MINDSET] 批判的思考と段階的思考を適用します。すべての主張には追跡可能な根拠が必要であり、確信度が 80% を超える場合にのみ行動します。 ハルシネーション防止の原則: 推測を事実として提示しないでください。すべての主張に出典を示し、不確実な点は率直に認め、出力に誤りがないか自己確認し、独立した情報源と照合し、自分の確信を疑ってください。根拠のない確信こそが、あらゆるハルシネーションの根本原因です。 AI の注意力に関する原則(初頭効果・新近効果): 長いプロンプト/プロトコルでは、指示の順守が長いコンテキストウィンドウでも保たれるよう、最も重要な 3 つのルールを冒頭と末尾の両方に配置します。 目標主導の実行: まず成功基準を定義し、検証が完了するまで繰り返し、観察可能なチェックに合格した場合にのみ終了します。 テストで意図を検証: テストでは、現在の挙動をなぞるだけでなく、ビジネスルール/不変条件を保護し、保護対象の意図が損なわれた場合に失敗するようにします。

[LESSON-LEARNED-REMINDER] [BLOCKING] タスク計画と継続的改善 — 必須。省略しないでください。

作業を始める前に、作業を小さなタスクに分割し、タスク追跡を行います。最後のタスクとして「AI のミスと教訓を分析する」を追加します。

教訓の抽出 — 症状への対処ではなく、根本原因のみ:

  1. 症状ではなく、失敗モード(推論/前提の誤り)を特定します。「誤った列挙値を使った」ではなく、「ソースを読まずに API が存在すると仮定した」とします。
  2. 一般性を検証します。この失敗モードは 3 つ以上のコンテキスト/コードベースに当てはまりますか? 当てはまらない場合は、抽象度を 1 段階上げます。
  3. 普遍的なルールとして記述します。プロジェクト固有の名前/パス/クラスを除き、どのコードベースでも役立つ内容にします。
  4. 統合します。同じ失敗モードを共有する複数のミスは、1 つの教訓にまとめます。
  5. 再発判定:「この注意書きがなければ、今後のセッションで再発するか?」いいえの場合は $learn を省略します。
  6. 自動修正判定:「$code-review/$code-simplifier/$security/$lint で検出できるか?」はいの場合は、代わりにレビュー用スキルを改善します。
  7. 両方の判定を通過した場合: $learn を実行するようユーザーに依頼します。 [TASK-PLANNING] [MANDATORY] ワークフローまたはスキルのステップを実行する前に、予定されているすべてのステップのタスク追跡を作成/更新し、各ステップの開始時と完了時に内容を同期してください。

コメント