claude-code

Codex 互換性に関する注意：

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

Codex のプロジェクト参照の読み込み（フックなし）

Codex では、実行時にプロジェクト文書を注入する代わりに、静的なプロジェクト参照を読み込みます。 コーディング、計画、デバッグ、テスト、レビューを行う際は、以下の経路に従ってプロジェクト文書を明示的に開いてください。

必ず読むもの：

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

コンテキストがない、または古い場合の経路： docs/project-config.json、ドキュメントのインデックス、lessons.md、CLAUDE.md、AGENTS.md、またはタスクに必要な参照文書が存在しないか古い場合は、プロジェクト固有の通常作業を始める前に、$project-init または限定的なセットアップ経路（$project-config、$docs-init、$scan-all、$scan --target=<key>、$claude-md-init）を自動的に実行してください。Codex のミラーまたは AGENTS.md が存在しないか古い場合は、ユーザーに $sync-codex の実行を依頼してください。自動実行はしないでください。

状況に応じて読む文書：

• プロジェクトの構造／アーキテクチャ／技術スタック／デプロイ／セットアップ（バックエンド、フロントエンド、インフラのいずれの層でも）：project-structure-reference.md
• バックエンド／CQRS／API／ドメイン／エンティティの変更：backend-patterns-reference.md、domain-entities-reference.md
• フロントエンド／UI／スタイリング／デザインシステム：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 仕様書の作成、docs/specs/ のパス指定、または TC 形式：feature-spec-reference.md、spec-system-reference.md、spec-principles.md
• 振る舞い／公開契約の変更、または仕様書・テスト・コード間の同期：workflow-spec-test-code-cycle-reference.md と上記の仕様書関連文書
• 派生仕様インデックス／ERD／再実装ガイド：spec-system-reference.md および docs/specs/ 内の元となる Feature Specs
• 統合テストの実装／レビュー：integration-test-reference.md
• E2E テストの実装／レビュー：e2e-test-reference.md
• コードレビュー／監査：code-review-rules.md と、変更対象のファイルに応じたドメイン文書

すべての文書を無差別に読まないでください。まず docs-index-reference.md を確認し、そこからタスクに関連するファイルだけを開いてください。

クイックサマリー

目標： Claude Code CLI のインストール、設定、トラブルシューティング、拡張（フック、MCP、スキル、コマンド）をユーザーに支援します。

ワークフロー：

1. 分類 — 問題の種類を特定します（セットアップ、フック、MCP、コンテキスト、拡張性、設定）
2. 診断 — カテゴリー別の診断手順に従います
3. 修正と検証 — 解決策を適用し、問題が解決したことを確認します

主なルール：

• アプリケーションコードの作成には使用しません。代わりに、feature ワークフロー、fix、または refactoring スキルを使用してください
• 設定を変更する前に、ユーザーから明示的な承認を得てください。独断で変更してはいけません
• フックについては、イベントタイプ、スクリプトの実行可能性、JSON 出力形式を確認してください

懐疑的な姿勢を保ってください。批判的思考と段階的な思考を適用してください。すべての主張には追跡可能な根拠と確信度の割合が必要です（アイデアは 80% 超である必要があります）。

Claude Code

目的

スキル、フック、MCP サーバー、スラッシュコマンドを備えた Anthropic のエージェント型コーディングツールである Claude Code CLI のインストール、設定、トラブルシューティング、拡張をユーザーに支援します。

使用する場面

• Claude Code を初めてセットアップするとき（インストール、認証）
• 起動しない、またはエラーを出すフックのトラブルシューティング
• MCP サーバーの接続失敗の診断
• コンテキストウィンドウの上限を理解、または解決するとき
• スラッシュコマンドやエージェントスキルを作成、または変更するとき
• 設定（モデル、許可するツール、出力スタイル）を構成するとき

使用しない場面

• アプリケーションコードの作成 — 代わりに workflow-feature ワークフロー、fix、または refactoring スキルを使用してください
• MCP サーバーの作成、または管理 — MCP のドキュメントとプロジェクトの MCP 設定を直接使用してください
• AI プロンプトエンジニアリング — 一般的なプロンプトエンジニアリングのガイダンスを直接使用してください

前提条件

• プロジェクトルートの .claude/ ディレクトリにアクセスできること
• フックの場合：.claude/hooks/ ディレクトリの構造を確認すること
• スキルの場合：.claude/skills/ ディレクトリの構造を確認すること

ワークフロー

ステップ 1：問題のカテゴリーを特定する

ユーザーの発言	カテゴリー	移動先
"install", "set up", "authenticate"	セットアップ	ステップ 2A
"hook not firing", "hook error"	フックの問題	ステップ 2B
"MCP not connecting", "MCP error"	MCP の問題	ステップ 2C
"context too long", "compaction", "token limit"	コンテキストの問題	ステップ 2D
"create skill", "create command"	拡張性	ステップ 2E
"configure", "settings", "model"	設定	ステップ 2F

ステップ 2A：セットアップ

1. 前提条件を確認します：Node.js 18+、npm
2. 認証を確認します：claude auth status
3. 認証に失敗する場合：claude auth login を使ってログインするよう案内します
4. プロジェクトの検出を確認します：プロジェクトルートに CLAUDE.md があるか確認します

ステップ 2B：フックの問題

1. 問題の原因となっているフックファイルを読みます
2. フックのイベントタイプが想定されるトリガーと一致するか確認します（PreToolUse、PostToolUse、SessionStart、Stop、SubagentStop）
3. フックスクリプトが実行可能で、正しいシバンがあることを確認します
4. .claude/settings.json にフックが登録されているか確認します
5. モック入力を使ってスクリプトを直接実行し、フックを単独でテストします
6. フックの出力に構文エラーがないか確認します（PreToolUse/PostToolUse では有効な JSON である必要があります）

よくある修正：

• フックが起動しない：イベント名またはツールマッチャーパターンが間違っています
• フックエラー：スクリプトが依存関係を見つけられていません（相対パスを確認してください）
• フックが予期せず処理をブロックする：PreToolUse が誤って { "decision": "block" } を返しています

ステップ 2C：MCP の問題

1. .claude/settings.json の MCP サーバー設定を確認します
2. MCP サーバーのプロセスを起動できることを確認します：コマンドを手動で実行します
3. 環境変数（API キー、トークン）が設定されているか確認します
4. 接続をテストします：claude mcp list を実行して登録済みサーバーを確認します
5. タイムアウトする場合：設定のタイムアウト値を増やすか、ネットワークを確認します

よくある修正：

• "Connection refused"：MCP サーバーが起動していないか、ポートが間違っています
• "Authentication failed"：API トークンの期限が切れているか、トークンがありません
• "Tool not found"：MCP サーバーは登録されていますが、ツール名が一致していません

Step 2D: コンテキストに関する問題

1. 現在のコンテキスト使用量を確認します（上限が近づくとClaudeが通知します）
2. 上限に近づいている場合：$compact コマンドを提案します
3. 大きなファイルを不必要に読み込んでいないか確認します
4. 圧縮後、CLAUDE.md を再読み込みして、プロトコルとワークフローカタログを再確認します（各プロンプトで再挿入されます）
5. $recover を実行し、ディスク上の状態（アクティブな計画、ToDo）から再開します。復旧はスキル主導であり、フックではありません

Step 2E: 拡張性

1. スキルについては、references/agent-skills.md を読み、構成を確認します
2. カスタムスラッシュコマンドについては、.claude/skills/{name}/SKILL.md にスキルを作成します
3. SKILL.md のフロントマターに必須項目（name、version、description）があることを確認します
4. テストとして、スキル／コマンドを呼び出し、読み込まれることを確認します

Step 2F: 設定

1. 設定の階層については、references/configuration.md を読みます
2. 設定の場所：.claude/settings.json（プロジェクト）、~/.claude/settings.json（ユーザー）
3. 重要：設定を変更する前に、必ずユーザーの明示的な承認を得てください。独断で変更してはいけません
4. 一般的な設定：モデルの選択、許可するツール、出力の詳細度

Step 3: 検証

• 修正によってユーザーの問題が解決することを確認します
• 行った設定変更を記録します
• 変更がほかのチームメンバーに影響する場合は警告します（プロジェクトレベルの設定）

出力形式

## Claude Code: [Issue/Task Summary]

### Problem

[What was wrong or what was requested]

### Solution

[Step-by-step fix or setup instructions]

### Files Changed

[List any config files modified, with before/after]

### Verification

[How to confirm the fix works]

例

例 1: フックが実行されない

ユーザー：「大きなファイルの読み込みをブロックする PreToolUse フックが実行されません」

診断：

1. .claude/settings.json を読みます。hooks.PreToolUse にフックが登録されています
2. ツールのマッチャーを確認します："matcher": "Read" — 正しく設定されています
3. スクリプトを直接実行します：node .claude/hooks/block-large-reads.cjs — 動作します
4. 原因の特定：フックのコマンドで %CLAUDE_PROJECT_DIR% を使用していますが、誤った CWD から実行されています

修正：フックのコマンドを絶対パスに変更するか、%CLAUDE_PROJECT_DIR% が正しく解決されることを確認します。設定内のフックエントリで、OS／シェルに適した変数構文が使われていることも確認してください（Windows と Unix では異なります）。

例 2: 新しいスラッシュコマンドの設定

ユーザー：「ステージング環境へのデプロイを実行する /deploy コマンドを作りたいです」

手順：

1. .claude/skills/deploy/SKILL.md を作成します：

Deploy to staging environment.

Run the following steps:

1. Verify all tests pass: `npm test`
2. Build the project: `npm run build`
3. Deploy: `npm run deploy:staging`
4. Report deployment status

2. テストとして、Claude Code CLI で /deploy と入力します
3. 検証として、コマンドがオートコンプリートに表示され、ワークフローを実行することを確認します

参照ファイル

特定のトピックについて詳しく確認するには、以下のファイルを読み込みます。

トピック	ファイル
インストール	references/getting-started.md
スラッシュコマンド	references/slash-commands.md
スキルの作成	references/agent-skills.md
MCP サーバー	references/mcp-integration.md
フックシステム	references/hooks-comprehensive.md
設定	references/configuration.md
トラブルシューティング	references/troubleshooting.md
エンタープライズ	references/enterprise-features.md

関連スキル

• skill-creator — ベストプラクティスに沿って新しいエージェントスキルを作成するためのスキル

---

[IMPORTANT] 作業を始める前に、タスク追跡を使って、ファイルの読み込みも含め、すべての作業を小さなタスクに分割してください。これにより、長いファイルによるコンテキストの消失を防げます。簡単なタスクの場合、AIはスキップしてよいか必ずユーザーに確認してください。 AI のミス防止 — あらゆるタスクで避けるべき失敗パターン：

コンテキストが変わったらファイルを読み直してください。 コンテキストの圧縮や再開、長時間にわたる作業によって記憶が古くなることがあります。作業に取りかかる前に、現在のファイルを確認してください。 生成した内容をソースの根拠と照合してください。 AI は API、名前、主張、ドキュメントの事実を幻覚することがあります。記述または参照する前に、該当するソースを確認してください。 削除や名前変更の前に、後続の参照を確認してください。 成果物を削除すると、ドキュメント、生成されたミラー、設定、呼び出し元に古い参照が残る可能性があります。まず参照関係を洗い出してください。 編集後は影響の連鎖全体を追跡してください。 定義を変更しても、派生出力や利用側への影響を見落とすことがあります。完了を宣言する前に、影響を受ける連鎖をたどってください。 最初の出力だけでなく、影響を受けるすべての出力を検証してください。 チェックが 1 つ成功しても、すべてが成功したことにはなりません。変更が影響し得るすべての出力面を検証してください。 既存の値は意図的なものと考え、変更したり不具合として指摘したりする前に、その理由を確認してください。 定数、上限、フラグ、しきい値、文言、パターンを変更または報告する前に、周辺のコンテキストと履歴、呼び出し元の順序、および同じ規則を使う 2 つ以上の同種の呼び出し箇所を確認してください。理由を示さず WHAT だけを記したドキュメントは、根拠のないガードが存在しない証拠ではなく、根拠が欠けているということです。 行動する前に曖昧さを明らかにしてください。黙って解釈を決めないでください。 複数の妥当な解釈がある場合は、明確な質問をするか、リスクを添えて前提を明示してください。 インフラストラクチャーが管理する中間状態ではなく、システムが管理する結果を検証してください。 非同期処理を検証するときは、最終的なビジネス状態を確認してください。共有インフラストラクチャー内で並行実行中のあらゆるプロセスが書き込める、配信や再試行の記録を確認してはいけません。そのようなチェックは単独実行では通過しても、同じインフラストラクチャーをほかの処理が共有した途端に不安定になります。 共有ガイダンスは、それを受け取る役割に関係する内容にしてください。 普遍的なガイダンスは、それを受け取るすべてのスキルやエージェントに役立つものでなければなりません。コード固有の義務は、コード固有のプロトコルにのみ記載してください。

批判的思考の姿勢 — 批判的思考と逐次的思考を適用してください。すべての主張には追跡可能な証拠が必要です。行動するには確信度が 80% を超えていなければなりません。 幻覚の防止： 推測を事実として示さないでください。すべての主張に出典を示し、不確実な点は率直に認め、出力に誤りがないか自己確認し、独立した情報源と照合してください。自分自身の確信を疑ってください。証拠のない確信が、あらゆる幻覚の根本原因です。

必ず注意：批判的思考と逐次的思考を適用してください。すべての主張には適切な追跡可能な証拠が必要です（リポジトリやコードに関する主張には file:line、調査、製品、コンテンツ、ドキュメントに関する主張にはソース URL または成果物のセクション）。行動するには確信度が 80% を超えていなければなりません。60% 未満の場合は、推奨しないでください。幻覚を防止してください。推測を事実として示さず、不確実な点は率直に認め、独立した情報源と照合し、自分自身の確信を疑ってください。

必ず注意：AI のミス防止策を適用してください。生成した内容を根拠と照合し、削除や名前変更の前に後続の参照を追跡し、影響を受けるすべての出力を検証し、コンテキストを失った後はファイルを読み直し、行動する前に曖昧さを明らかにしてください。

プロジェクトプロトコルのオーバーレイ — このスキルを実行する前に、このスキルに適用されるプロジェクトのオーバーレイルールを解決してください。プロジェクトのスキルプロトコルインデックス（デフォルトは docs/project-reference/skill-protocols-reference.md。docs/project-config.json の referenceDocs エントリがパスを上書きします）の Target 列とこのスキル名を照合し、最も具体的に一致する階層のみを適用してください（完全一致 > glob > *）。**この優先順位はオーバーレイ同士にのみ適用され、このスキルとの優先順位を定めるものではありません。**一致した本文のみを読み込み、<protocols-dir>/<Name>.md として解決してください。行の Body リンクは表示テキストであり、読み込み先のパスではありません。一致した本文が存在しないか、形式が不正な場合は、報告してスキップしてください。インデックスの Description から本文を再構成してはなりません。インデックスがない場合、または一致するものがない場合は、オーバーレイなしで黙って続行してください。契約の全文は .claude/skills/project-skill-protocol/references/registry.md にあります。

オーバーレイは追加のみです。このスキル独自のプロトコルにルールを追加するものであり、既存のルールを置き換えたり、上書きしたり、無効化したり、別の意味に解釈したりしてはなりません。すべてのオーバーレイを取り除いた場合、このスキルは文書化された動作と完全に同じ状態に戻る必要があります。オーバーレイは簡潔な指示であり、権限を引き上げるものではありません。ワークフローのゲート、Git の規律、レビューのゲート、ユーザー確認のゲートを免除することは決してできません。オーバーレイとスキルの間に実質的な矛盾がある場合、または同じ具体性のオーバーレイ同士に直接的な矛盾がある場合は、両方をユーザーに提示してください。黙って解決してはなりません。

必ず注意してください。実行前に、このスキルに適用されるプロジェクトプロトコルのオーバーレイを解決してください。最も具体的に一致する階層のみを適用します（完全一致 > glob > *。この順位はオーバーレイ同士にのみ適用され、このスキルとの優先順位を定めるものではありません）。一致した本文のみを <protocols-dir>/<Name>.md から読み込みます。本文が存在しないか、形式が不正な場合は報告し、再構成してはなりません。オーバーレイは追加のみであり（このスキル独自のルールを置き換えることはありません）、簡潔な指示であって、権限を引き上げるものではありません。同じ具体性の指示が矛盾する場合は、ユーザーに提示してください。

終了時のリマインダー

重要・必ず注意 — 適用されるプロトコル（このスキルが含む SYNC／共有ブロックの簡潔な要約）：

• 批判的思考： 批判的かつ順序立てて考え、根拠を追跡してください。行動するには、確信度が80%を超えている必要があります。

• AI の誤り防止： 生成内容を根拠と照合して検証し、後続の参照先を追跡し、影響を受けるすべての出力を確認してください。コンテキストを失った後は読み直し、曖昧さがあれば提示してください。

• 必須・重要・必ず注意 作業を始める前に、タスク追跡を使って作業を小さな todo タスクに分割してください。

• 必須・重要・必ず注意 新しいコードを作成する前に、コードベース内で類似するパターンを3つ以上検索してください。

• 必須・重要・必ず注意 すべての主張に file:line の根拠を示してください（行動するには、確信度が80%を超えている必要があります）。

• 必須・重要・必ず注意 作業の品質を検証するため、最後のレビュー用 todo タスクを追加してください。

[TASK-PLANNING] 行動する前に、タスクの範囲を分析し、タスク追跡を使って小さな todo タスクとサブタスクに体系的に分割してください。

フックレス・プロンプトプロトコルのミラー（自動同期）

ソース：.claude/.ck.json + .claude/skills/shared/sync-inline-versions.md（:full ブロック）+ .claude/scripts/lib/hookless-prompt-protocol.cjs

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

汎用的な移植性の境界： 再利用可能なスキルとプロトコルのテキストはプロジェクトに依存しないものとし、プロジェクト固有の規約は docs/project-config.json と docs/project-reference/ から確認します。共有 AI-SDD は shared/sdd-artifact-contract.md に従って適用します。docs/project-config.json と docs/project-reference/docs-index-reference.md を読み、そこに記載されているプロジェクトリファレンスドキュメントを開いてください。仕様、テストケース、動作変更、公開コントラクト、または docs/specs/ に関する作業では、ドキュメントインデックスに記載されたローカルの仕様ドキュメント（feature-spec-reference.md、spec-system-reference.md、spec-principles.md、および仕様・テスト・コードの同期が必要な場合は workflow-spec-test-code-cycle-reference.md）を経由してください。いずれかのファイル、または必須のリファレンスドキュメントが見つからないか古くなっている場合は、通常のプロジェクト固有の作業に進む前に $project-init（または $project-config、$docs-init、$scan-all、$scan --target=<key> などの限定的な下位ルート）を自動実行してください。この共有コンテキストとローカルドキュメントが利用可能であれば、サポート対象の任意の AI ツールで実行できます。

1. 検出： プロンプトが明示的なスラッシュ形式のスキル／ワークフローコマンドで始まる場合は、それを直接実行します。それ以外の場合は、プロンプトをワークフローカタログとスキルリストに照らし合わせます。
2. 分析： 最適な方法を選択します。直接実行、スキルの呼び出し、標準ワークフローの開始、またはカスタムのステップ構成です。
3. 自動選択： 最適な方法を自分で選択します。直接実行、スキル、標準ワークフロー、カスタムワークフローのどれにするか、ユーザーに選択を求めてはいけません。
4. 開始： 選択したワークフローでは $start-workflow <workflowId> を呼び出します。選択したスキルではそのスキルを呼び出します。カスタムワークフローではカスタムステップを順に実行します。直接実行ではタスクに進みます。
5. タスクの作成： 選択した経路に複数のステップがある場合、実行前にすべてのワークフロー／スキル／カスタムステップについてタスクを追跡します。
6. 並列化： タスクリストの実行前に、各タスクに PAR（入力が独立しており、書き込み対象が他のすべての PAR タスクと重複しない）または SEQ（ブロックする依存関係を明記）を付け、PAR タスクをウェーブにグループ化し、ウェーブ計画を宣言して、各ウェーブのサブエージェントを1つのメッセージで起動します。各ウェーブでは全員の完了を待ち、サブエージェント自身の定義でさらなる並列化が認められている場合を除き、ファンアウトは1階層までとします。独立したタスクを逐次処理するのは不備です。共有の書き込み対象、出力を利用するタスク、単純な単一ファイルの作業、スキルやワークフローで順序が明示されている作業、ユーザー承認が必要な段階は並列化しないでください。
7. 実行： コンテキスト指示にある Workflow Step Advancement & Parallel Phases のルールに従って進めます。ステップの進行はモデル主導です。サブエージェントの完了はインライン呼び出しと同様にステップを進めます。並列フェーズのグループは全員の完了を待つバリアです（すべてのメンバーが完了した後にのみ進み、決して逐次化しません）。

共有 AI-SDD プロトコルマーカー

ソース：.claude/skills/shared/sync-inline-versions.md

SYNC:ai-sdd-artifact-contract

AI-SDD 成果物契約 — 共有する仕様駆動開発のルールは、移植可能な状態に保ち、ソース側で管理します。

1. 再利用可能な AI-SDD の原則は .claude に置き、リポジトリ固有のパス、コマンド、担当者、製品、形式はプロジェクト設定または参照ドキュメントに記載します。
2. サイクルを維持します：spec -> plan -> tasks -> implement -> verify -> update spec/docs。
3. すべての要件または不変条件を、判断、タスク、TC／テスト、ソースの根拠、ドキュメント／仕様の更新まで追跡します。
4. コードから仕様への抽出は、正規の仕様オーナーが承認するまでは参照専用として扱います。
5. 同期されたコンテキストがあれば、サポート対象の AI ツールで計画、実装、レビュー、検証を行えます。複数のツールを使うかどうかは任意です。
6. まず .claude のソースを更新してから、生成されたミラーを同期します。.agents、.codex、AGENTS.md を手動で編集しないでください。— 理由：ミラーは生成された成果物であり、次回の同期時に手動編集内容が上書きされます
7. docs/project-config.json、ルートの指示ファイル、または必須のプロジェクト参照ドキュメントが欠落しているか古い場合は、通常のプロジェクト固有の作業を行う前に、$project-init または適切な下位レベルの手順を自動実行します。

有効な参照先： アクティブなスキルルート内の shared/sdd-artifact-contract.md。

---

SYNC:ai-sdd-artifact-contract:reminder

• 必須 shared/sdd-artifact-contract.md を適用し、再利用可能な AI-SDD は .claude に、ローカルルールはプロジェクトのドキュメントに保持します。
• 必須 コードから仕様への抽出は、正規の承認を得るまで参照専用です。サポート対象の AI ツールであれば、同期されたコンテキストを使って実行できます。
• 必須 生成されたミラーを同期する前に .claude のソースを更新します。.agents、.codex、AGENTS.md を手動で編集しないでください。
• 必須 プロジェクト設定、ルートの指示ファイル、または必須の参照ドキュメントが欠落しているか古い場合は、プロジェクト固有の作業を $project-init または適切なセットアップ手順に自動的に振り分けます。 [TASK-PLANNING] [必須] ワークフローまたはスキルの手順を実行する前に、計画したすべての手順についてタスク追跡を作成／更新し、各手順の開始時と完了時に同期してください。

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

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

教訓の抽出 — 症状への対処ではなく、根本原因のみを扱います：

1. 症状ではなく、失敗モード（推論や前提の誤り）を特定します。「間違った enum 値を使った」ではなく、「ソースを読まずに API が存在すると仮定した」とします。
2. 一般性を確認します。この失敗モードは 3 つ以上の状況／コードベースに当てはまりますか？当てはまらない場合は、もう一段階抽象化します。
3. 普遍的なルールとして記述します。プロジェクト固有の名前、パス、クラスを取り除きます。どのコードベースでも役立つ内容にします。
4. 統合します。同じ失敗モードに起因する複数のミスは、1 つの教訓にまとめます。
5. 再発ゲート：「このリマインダーがなければ、今後のセッションで再発するか？」いいえ → $learn は省略します。
6. 自動修正ゲート：「$code-review／$code-simplifier／$security-review／$lint で検出できるか？」はい → 代わりにレビュー用スキルを改善します。
7. 両方のゲートを通過した場合は、ユーザーに $learn の実行を依頼します。 [CRITICAL-THINKING-MINDSET] 批判的思考と段階的思考を適用します。あらゆる主張に追跡可能な証拠を求め、行動する際は確信度を 80% 超とします。 ハルシネーション防止の原則： 推測を事実として提示しないでください。すべての主張に出典を示し、不確実性を率直に認め、出力に誤りがないか自己確認し、独立した情報源と照合し、自分の確信を疑ってください。証拠のない確信が、あらゆるハルシネーションの根本原因です。 AI の注意力の原則（初頭効果・新近効果）： 長いプロンプト／プロトコルでは、最も重要なルールを上部と下部の両方に 3 つずつ配置し、長いコンテキストでも指示への準拠を維持します。 目標主導の実行： まず成功基準を定め、検証できるまで繰り返し、観察可能なチェックに合格した場合にのみ終了します。 テストは意図を検証します： テストは現在の動作をなぞるだけでなく、ビジネスルールや不変条件を保護し、保護対象の意図が崩れたときに失敗する必要があります。

よくある AI のミスを防ぐ（システムの教訓）

• コンテキスト圧縮後はファイルを再読込してください。 編集するには、同じコンテキスト内で事前に Read している必要があります。圧縮によって読込状態は消去されます。編集前に再読込してください。
• 一括置換後は古い用語を grep してください。 AI は検索・置換の完全性を過信します。一括編集後はリポジトリ全体を grep し、ドキュメント／設定／カタログに参照漏れがないか確認してください。
• 削除前に下流の参照を確認してください。 削除の影響は、ドキュメントやコードの陳腐化へ連鎖します。削除前に参照元ファイルを洗い出してください。
• 記憶を失った後、新しく作成する前に既存の状態を確認してください。 圧縮によってこれまでの作業の記憶が消去されます。作業を再開するときは現在の状態を確認し、決してむやみに重複作成しないでください。
• AI 生成コンテンツは実際のコードと照合してください。 AI は API、クラス名、メソッドシグネチャを幻覚することがあります。ドキュメントへの記載や参照の前に、grep して実在を確認してください。
• 編集後は依存関係を最後までたどってください。 定義を変更しても、その下流の利用箇所を見落とすことがあります。依存関係をすべてたどってください。
• 名前を変更するときは、利用側の全ファイル形式を grep してください。 ファイル形式によっては、参照先が見つからなくてもエラーなしで無視されます。コード、テンプレート、設定、生成ファイルを検索してください。
• 正しさを検証するときは、すべてのコードパスをたどってください。 コードが存在することと、実行されることは同じではありません。正常系だけでなく、早期リターン、エラー分岐、条件によるスキップもたどってください。
• ソースが変わったら、正規データを埋め込んでいるドキュメントも更新してください。 派生データ（ワークフロー、スキーマ、設定など）を直接記載しているドキュメントは、気づかないうちに古くなります。ソースと合わせて、該当する埋め込みドキュメントをすべて更新してください。
• コンテキスト復旧後は、サブエージェントの結果を検証してください。 親エージェントが圧縮されている間にバックグラウンドエージェントが完了している場合があります。完了したはずだと信じず、出力を grep して確認してください。
• 対象の全一覧とサブエージェントへの割り当てを照合してください。 カテゴリごとにサブエージェントを並行実行すると、境界上の項目を見落とすことがあります。作業を進める前に、割り当ての和集合を対象一覧と照合してください。
• サブエージェントが引き継ぐ知識は、そのエージェントの .md 定義に書かれた内容だけです。組み込みの Explore ではなく、カスタムエージェント種別を使用してください。 ツールの採用には、権限＋知識＋適用（番号付きワークフロー手順）が必要です。
• サブエージェントの調査結果は最後にまとめてではなく、随時保存してください。 長時間実行されるサブエージェントは、最終書き込み前に打ち切られることがあり、調査結果が失われます。報告ファイルにセクションごとに追記するよう指示してください。
• デバッグ時は修正する前に「どちらの責任か」を確認してください。 呼び出し元（データが誤っている）と呼び出し先（処理が誤っている）をたどり、責任のある層を修正してください。症状が表れる箇所だけを修正してはいけません。
• テスト失敗時は、追跡や編集の前に暫定判定を記録してから調査してください。 次の 5 つの分類をすべて使ってください。SOURCE-WRONG（本番コードが意図に反している）、TEST-WRONG（アサーション／セットアップが古くなっている）、TEST-NOT-OPTIMAL（妥当だが脆弱、または情報量の少ないテスト）、ENVIRONMENT-BLOCKED（外部状態のため判定できない）、AMBIGUOUS（意図や証拠から安全に選べない）。その後、根本原因をたどり、適用される仕様（存在する場合は docs/specs/**）とソースの両方に照らして検証してください。成功を無理に得るために、アサーションを弱めたり、スキップを追加したり、タイムアウトを緩めたり、ソースを変更したりしてはいけません。
• 抽出／リファクタリング後は、削除した名前をすべて grep してください。 主要ファイルの作業完了は、他のファイルもクリーンであることを意味しません。完了を宣言する前に、対象範囲全体で削除したシンボルを一つずつ grep してください。
• 既存の値には意図があると考え、変更したり不具合だと指摘したりする前に、必ず理由を確認してください。 パターンマッチで「誤り」と決めつけると、背景を見落とします。定数／上限／フラグ／しきい値を変更または報告する前に、コメント、git blame、呼び出し元の処理順序（値を正しくする保証は、通常、該当行の直前に実行されるコードにあります）、同じ規約を使っている 2 つ以上の類似した呼び出し箇所を確認してください。理由なしに WHAT（何をするか）だけを記したドキュメントは、根拠が欠けているのではなく、WHY（なぜそうするか）の説明が不足しているということです。検証作業でも、正確な file:line の引用が証明するのは転記が正確であることだけであり、不具合の存在ではありません。
• 最初の出力だけでなく、影響を受けるすべての出力を検証してください。 一つのビルドが成功しても、すべてが成功したとは限りません。複数のスタックにまたがる変更（バックエンド／フロントエンド／テスト／ドキュメント）では、すべての出力を検証してください。
• 近くにあるパターンをコピーする前に、適合性を評価してください。 最も近い例が適合するとは限りません。新しいコンテキストが同じ制約、基底クラス、スコープ、ライフタイムを共有するか確認してください。
• デバッグでは全体を優先し、目についた箇所に飛びつかないでください。 最初に思いついた原因へすぐ飛びつかないでください。前提条件（設定、環境変数、パス、DB、エンドポイント、認証情報、バージョン、DI、データ）をすべて列挙し、それぞれを証拠（推論ではなく grep／クエリ）に照らして検証してください。「何があればこの仮説は否定されるか？」と問い、何も答えられないなら、それは仮説ではありません。最もコストの高い失敗は、バグが一度も疑われていない層にあるのに、「明らか」だと思い込んだ層をさらに深掘りすることです。
• 変更は最小限にし、差分テストを適用してください（コンテキストに合わせて判断）。 2 つのモードがあります。（1）バグ修正 → すべての行がバグに直接関係するようにし、スタイル変更はしないでください。不要になったインポートを削除してよいのは、あなたの変更によって不要になったものだけです。（2）レビュー／機能強化 → 改善を実装し、「主な依頼を超える機能強化：[内容]」と明示してください。黙ってスコープを拡大しないでください。差分テスト：「X を依頼されていなかったとしても、この行は存在していたか？」いいえなら、削除するか明示してください。
• 実装前に曖昧さを明らかにし、黙って解釈を選ばないでください。 複数の妥当な解釈がある場合は、それぞれの工数とともに提示してください。「[依頼] は（1）[N 時間]、（2）[N 時間]のいずれかと解釈できます。どちらが重要ですか？」まずスコープ／形式／量／制約に関する前提を列挙してください。より簡単な方法がある場合は、そのことも伝えてください。黙って選ばないでください。
• [必須の最初のアクション] 応答する前に、必ず適切なスキルまたはワークフローを有効にしてください。 ワークフローカタログとスキル一覧に照らしてタスクを確認し、スキルの呼び出し、または $start-workflow <workflowId> で実行してください。確認する前に回答やコード作成をしてはいけません。省略はプロトコル違反です。
• Why-Review の敵対的な視点は、計画、判断、設計をレビューするときに適用してください。 基本姿勢は VALIDATOR（妥当性を確認する側）ではなく SKEPTIC（懐疑的な側）です。却下された代替案の最も強い論拠を組み立て、述べられた理由を一つずつ逆転させて「何を犠牲にするのか」を問い、上位 2～3 個の前提をストレステストし、プレモーテム（「リリースしたが 3 か月後に失敗した。何が壊れたのか？」）を行い、作成者が見落とした代替案を 1～2 個提示してください。セクションがあるだけでは十分ではありません。重要なのは、因果関係に基づく推論、具体的な軽減策、証拠です。「より良い」や「注意深く監視する」だけでは不十分です。
• 大規模なレビューでは、サブエージェントへのプロンプトで報告書の書き込みを最初に行わせてください。 多数のファイルを扱うサブエージェントは、最終書き込みの前に予算を使い切り、調査結果を失うことがあります。プロンプトは、（1）報告書の書き込みを最初に明示する成果物とする、（2）まとめてではなくファイル／セクションごとに追記する、（3）読み込みで予算を使い切らないようスコープを限定する、という構成にしてください。報告ファイルを残さず文の途中で打ち切られた場合は、同じプロンプトを再試行せず、より狭いスコープで再実行してください。
• コンテキスト圧縮後は、続行する前に以前の各フェーズの結果をすべて再検証してください。 要約が示すのは意図であり、環境の状態（git のインデックス、ファイルシステム、プロセス）ではありません。再開時はまず git status を確認し、変更したファイルを再読込し、ファイルシステムを検証してください。証拠で確認されるまでは、「完了した」という主張もすべて未検証の仮説です。
• OOM／メモリ：行サイズより先に行数を確認してください。 次の順にトリアージします。（1）上限のないクエリ — 条件を設定するトリガーとなる DB フィルターがありませんか？ DB 側にフィルターを移せば、OOM を解消できます。（2）行サイズが大きいですか？ プロジェクションを使えば比例して減らせます。費用対効果では、プロジェクションより行数削減が優先です。
• システムが担う最終結果をアサートし、インフラストラクチャが担う中間状態をアサートしないでください。 非同期処理（キュー／ブローカーへの配信、再試行、バックグラウンドジョブ、キャッシュ、レプリケーション）をテストする場合は、最終的なビジネス／エンティティの状態をアサートしてください。配信の記録、つまり消費／送信ステータス、試行回数、最終エラー、ブローカー、スケジューラー、outbox／inbox テーブル内の行の有無や件数をアサートしてはいけません。この記録は共有インフラストラクチャに存在し、並行して動く任意のプロセス（別のワーカー、2 つ目のレプリカ、残っているローカルコンテナー）から書き込めるうえ、通常は決定的な共有キーが使われます。そのため、こうしたアサーションは気づかないうちにシステムではなく開発者の環境をテストします。単独実行では成功しても、同じブローカー＋データベースをほかの何かが共有した途端に不安定になります。すべてのアサーションで、次の判定の問いを使ってください。「どのプロセスが処理しても、この結果は成り立つか？」いいえなら、代わりに収束後のデータ状態をアサートしてください。系として、プロセスローカルな障害注入やプロセス内テレメトリーを、任意のプロセスが実行する処理のゲートとして使うことはできません。負荷増幅に使ってください（有効化 → 範囲を限定した時間枠 → 無効化 → 収束をアサート）。前提条件として使ってはいけません。
• ドメイン概念を汎用／共有／インフラストラクチャ層に持ち込まないでください。 再利用可能な層（共有ライブラリ、フレームワーク、インフラモジュール）は、利用側に固有のドメイン概念（テナント／顧客／製品 ID、ビジネスエンティティ、機能ルール）を一切参照してはいけません。漏れがコンパイルされ、実行されると、再利用可能なはずの層が一つの利用側と結合していても、レビューで気づかれずに通過してしまいます。共有型からドメイン情報を排除し、サブクラス化／コンポジションを通じて、ドメインフィールド／ロジックを利用側へ移してください。理由：一つの利用側のドメインに結合した層は、もはや再利用可能ではありません。