learn

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 がセッションをまたいで教訓を保持できるよう、各教訓をその失敗モードに一般化し、次のセッションで実際に読まれる保存先に保存します。最適な文章形式のリファレンスドキュメント、または機械可読なプロジェクト情報を扱う場合は docs/project-config.json が保存先です。

要約： ほかを読まなくてもわかる、主な手順のダイジェストです。

• 何よりも先に一般化する — インシデントから、再利用可能な失敗モードへと掘り下げます。このチケット固有のファイル／サービス／ツールを挙げるだけでは、まだ教訓とはいえません。
• ルーティングの前にトリアージする（再発性＋自動修正） — レビュースキルですでに検出できる教訓はノイズです。
• 文章形式を既定にせず、保存先を分類する： プロジェクトの事実（パス、実行コマンド、モジュールマップ、規約、ツールの選択）を示す教訓は、すべてのスキルが最初に読む機械可読なマップ docs/project-config.json に記載します。ルールやパターンを示す教訓は、対応する docs/project-reference/ ドキュメントに記載します。両方に当てはまる場合もあります。その場合は、事実を設定ファイルに、ルールを文章形式のドキュメントに記載します。設定ファイルの内容や正確なフィールド名を確認するには、ファイルを読むか、$project-config を使ってください（--describe を実行します）。
• 予防の深さを評価する — ドキュメント／設定の更新、プロンプトルール、静的プロトコルの教訓、フック、テスト、スキルの更新のいずれかを選びます。
• ユーザーに保存先を確認してから保存し、必須の終了タスクを3つ実行する — Learn Review → $why-review → $prompt-enhance

ワークフロー：

1. 取得 -- ユーザーの指示または経験から教訓を特定します
2. 振り分け -- 教訓の内容を Reference Doc Catalog と docs/project-config.json に照らして分析し、最適な保存先（文章形式のドキュメント、設定フィールド、または両方）を選びます
3. 保存 -- 選択したファイルに教訓を追記します
4. 確認 -- 保存した内容と保存先を伝えます
5. Learn Review -- 必須の2段階の終了ゲート（Learn Review ＋ $why-review）を実行します
6. 強化 -- 変更したファイルに対して $prompt-enhance を実行し、AI の注意を適切に引き付けるよう最適化します

主なルール：

• 最初に一般化する（最重要のプロトコル）： 多くの事例に適用できる一般的な教訓を抽出します。具体的な事例をそのまま保存してはいけません。ユーザーの言葉は1つのインシデントを表しています。そのインシデントから、再利用可能なルールへと掘り下げるのがあなたの役割です。プロジェクト／ファイル／ツール／分野の名前をすべて取り除きます。保存した内容がこのチケットにしか役立たないなら、抽象化のレベルが足りません。（以下の Lesson Quality Gate でチェックされます。）
• 「これを覚えておいて」「常にXする」「Yは絶対にしない」などをトリガーとします
• まずトリアージする： 振り分けや保存の前に、再発性ゲートと自動修正ゲートの両方を通過させます
• 常に docs/project-reference/lessons.md を選ぶのではなく、最も関連性の高いファイルに適切に振り分けます
• 振り分けを判断するたびに docs/project-config.json を検討する — 実際にはプロジェクトの事実（パス、実行コマンド、モジュールマップ、ツールの選択）に関する教訓は、文章形式のドキュメントではなく機械可読なマップに記載します。判断する前に、スキーマを確認するためファイルを読むか、$project-config を使います
• 正確な設定スキーマのフィールド名（node .claude/hooks/lib/project-config-schema.cjs --describe）を使用し、既存のフィールドを優先します。キーを新たに作ってはいけません。また、設定への書き込みには $project-config を使用します
• 重複を作成する前に、既存の項目を確認します
• 書き込む前に、対象ファイルをユーザーに確認します

懐疑的に考え、批判的思考と順序立てた思考を適用してください。すべての主張には、追跡可能な証拠と確信度（Idea は80％超）が必要です。

使い方

教訓を追加する

$learn always use the validation framework fluent API instead of throwing ValidationException
$learn never call external APIs in command handlers - use Entity Event Handlers
$learn prefer async/await over .then() chains

教訓を一覧表示する

$learn list

教訓を削除する

$learn remove 3

すべての教訓を消去する

$learn clear

リファレンスドキュメント一覧（ルーティング前に必ず読む）

各 docs/project-reference/ ファイルは、session-init-docs.cjs フックによって自動的に初期化され、/scan-* スキルによって内容が追加されます。それぞれの役割を理解することは、適切なルーティングに不可欠です。ルーティングは静的です。タスクに一致する Read Trigger のドキュメントを読んでください。

ファイル	役割と内容	Read Trigger（静的）	Scan Skill
project-structure-reference.md	アーキテクチャ、ディレクトリツリー、技術スタック、モジュールレジストリ、サービスマップ	新しい領域／アーキテクチャに関する作業	$scan --target=project-structure
backend-patterns-reference.md	バックエンド／フックのパターン：CJS モジュール、CQRS、リポジトリ、バリデーション、メッセージバス、バックグラウンドジョブ	バックエンド／CQRS／API ファイルの編集	$scan --target=backend-patterns
seed-test-data-reference.md	シード／開発データのパターン：環境ゲート、冪等性ループ、DI スコープの安全性、コマンドディスパッチ	Seeder／DataSeeder ファイルの編集	$scan --target=seed-test-data
frontend-patterns-reference.md	フロントエンドのパターン：コンポーネント、状態管理、API サービス、スタイル規約、ディレクティブ	フロントエンド／UI ファイルの編集	$scan --target=frontend-patterns
integration-test-reference.md	テストアーキテクチャ：基底クラス、フィクスチャ、ヘルパー、サービス固有のセットアップ、テストランナー	統合テストファイルの編集	$scan --target=integration-tests
feature-spec-reference.md	機能ドキュメントのテンプレート、アプリとサービスの対応関係、ドキュメント構成の規約	機能仕様書の作成／参照	$scan --target=feature-spec
code-review-rules.md	レビュールール、規約、アンチパターン、判断ツリー、チェックリスト	あらゆるレビュースキルの実行	$scan --target=code-review-rules
lessons.md	一般的な教訓 — フォールバック用の包括的なドキュメント。すべてのタスクで読む（project-reference-docs ゲートに従う）	すべてのタスク	$learn が管理
scss-styling-guide.md	SCSS/CSS：BEM 手法、ミックスイン、変数、テーマ設定、レスポンシブパターン	スタイリング／SCSS ファイルの編集	$scan --target=scss-styling
design-system/README.md	デザインシステム：トークンの概要、コンポーネント一覧、アプリとドキュメントの対応関係	デザイン／UI ファイルの編集	$scan --target=design-system
e2e-test-reference.md	E2E テストのパターン：フレームワーク、ページオブジェクト、設定、ベストプラクティス	E2E ファイルの編集	$scan --target=e2e-tests
domain-entities-reference.md	ドメインエンティティ、データモデル、DTO、集約境界、ER 図、サービス間同期	バックエンド／フロントエンドのドメイン作業	$scan --target=domain-entities
docs-index-reference.md	ドキュメントツリー、ファイル数、ドキュメント間の関連性、キーワードからドキュメントを検索する方法	ドキュメントの検索／ナビゲーション	$scan --target=docs-index

重要なポイント： lessons.md と code-review-rules.md は、最も頻繁にルーティング対象となるドキュメントです。関連するタスクでは毎回読んでください。頻繁に参照する教訓は、一致する Read Trigger によって今後のセッションで確実に開かれる場所に記載してください。

ルーティング先としても使用：docs/project-config.json（機械可読であり、説明文ではありません）

上記のカタログは説明文です。docs/project-config.json はプロジェクトの機械可読なマップであり、モジュール／パス、フレームワーク＋検索キーワード、テスト／E2E／統合テストの実行コマンド、デザインシステム、アーキテクチャルール、ワークフローパターンが記載されています。また、CLAUDE.md と docs/project-reference/** のドキュメントは、このファイルをもとに生成されます。すべてのスキルに、調査、計画、コーディングを始める前にこのファイルを読むよう指示されています。そのため、ここに記録された情報は、説明文書に書かれた同じ情報よりも多くのセッションに伝わります。

読み込みのタイミング： 説明文書を読む前に、すべてのタスクで読み込みます。管理者： $project-config。

ここに情報をルーティングする前に、ファイルの構成を把握してください。docs/project-config.json を直接読むか、スキーマと正確なフィールド名を把握している $project-config を呼び出します。

node .claude/hooks/lib/project-config-schema.cjs --describe   # exact field names + per-field derivation notes

情報の内容…	記載先
スキーマのフィールドですでに表現されているプロジェクトの事実 — パス、glob、実行コマンド、モジュール／サービスのマップ、フレームワークやツールの選択、ドキュメントのルート、テスト／E2E／統合テストの設定、起動コマンドやヘルスチェックコマンド	docs/project-config.json（$project-config 経由）
エージェントが考慮すべきルール、パターン、またはアンチパターン	該当する docs/project-reference/ ドキュメント
両方 — 新しい事実と、その事実の使用ルール	事実を設定ファイルに、ルールを説明文に記載します

ルール：

• ルーティングの判断をするたびに、必ず docs/project-config.json を候補として確認します。理由：説明文にしか書かれていないプロジェクトの事実は、設定ファイルを読むツールから見えず、生成されたドキュメントが設定ファイルから再生成される際に、何も通知されず上書きされます。
• 正確なスキーマのフィールド名を必ず使用し（--describe で確認し、そのままコピーします）、新しいフィールドより既存のフィールドを優先します。理由：未知のキーは警告として受け入れられるため（project-config-schema.cjs:618,688）、独自に作ったキーは機能したように見えても、実際にはどの利用側も読み取りません。
• 該当する既存のフィールドがない場合は、トップレベルのキーを黙って追加してはいけません。情報を説明文に記載し、スキーマへの追加案として不足をユーザーに伝えます。理由：スキーマの変更はフレームワークに関する判断であり、$learn の副次的な作用で行うものではありません。
• JSON を手作業で編集するよりも、$project-config を通じて設定を書き込む方法（Plan → Review → Execute ＋ 検証）を優先します。理由：各フェーズの後に検証され、このスキルが推測することになるフィールド名も把握しています。
• 設定ファイルには事実のみを記載し、説明文の教訓は決して記載しません。設定文字列フィールドに、物語形式の教訓を決して貼り付けてはいけません。理由：設定ファイルはツールと各スキルの事前読み込み処理で使用されます。説明文を記載すると、すべてのセッションが肥大化し、リファレンスドキュメントに記載すべき内容が混在します。

---

スマートファイルルーティング（重要）

レッスンの振り分けゲート（必須 — ルーティングまたは保存の前に最初に実行）

ゲート	質問	合格	不合格 → 対応
再発性	「このリマインダーがなくても、今後のセッションでこのミスは再発しますか？」	はい → 続行	いいえ → $learn をスキップ。状況依存のミスです
自動修正	「$code-review、$code-simplifier、$security-review、または $lint で自動検出できますか？」	いいえ → 続行	はい → $learn をスキップし、レビュー用スキルを更新

両方のゲートに合格する必要があります。 レビュースキルですでに検出できる教訓を追加すると、価値がないままノイズが増えます。一度きりの状況依存のミスは、永続化されたルールでは防げません。

---

ルーティング表

教訓の内容に基づいて、最も関連性の高いファイルに振り分けます。

レッスンの内容	振り分け先	セクションの目安
コードレビューのルール、アンチパターン、レビュー用チェックリスト、YAGNI／KISS／DRY、命名規則、レビューのプロセス	docs/project-reference/code-review-rules.md	最も関連性の高いセクション（アンチパターン、ルール、チェックリスト）に追加
バックエンド／フックのパターン：モジュール、CQRS、リポジトリ、エンティティ、バリデーション、メッセージバス、バックグラウンドジョブ、マイグレーション、設定済みの永続化	docs/project-reference/backend-patterns-reference.md	関連するセクションまたはアンチパターンのセクションに追加
フロントエンドのパターン：コンポーネント、状態ストア、フォーム、API サービス、スタイル規則、ディレクティブ、パイプ	docs/project-reference/frontend-patterns-reference.md	関連するセクションまたはアンチパターンのセクションに追加
統合テスト／ユニットテスト：テストの基底クラス、フィクスチャ、テストヘルパー、テストパターン、アサーション、テストランナー	docs/project-reference/integration-test-reference.md	関連するセクションに追加
E2E テスト：Playwright、Cypress、Selenium、ページオブジェクト、E2E の設定、ブラウザーの自動化、ビジュアルリグレッション	docs/project-reference/e2e-test-reference.md	関連するセクションに追加
ドメインエンティティ、データモデル、DTO、集約、エンティティの関係、サービス間のデータ同期、ER 図	docs/project-reference/domain-entities-reference.md	エンティティカタログまたは関係のセクションに追加
プロジェクト構造、ディレクトリ構成、モジュール境界、技術スタックの選択、サービスアーキテクチャ	docs/project-reference/project-structure-reference.md	関連するアーキテクチャセクションに追加
SCSS／CSS のスタイリング、BEM 手法、ミックスイン、変数、テーマ設定、レスポンシブデザイン、CSS の規則	docs/project-reference/scss-styling-guide.md	関連するスタイリングセクションに追加
デザインシステム、デザイントークン、コンポーネントライブラリ、UI キットの規則、Figma からコードへの変換パターン	docs/project-reference/design-system/README.md	関連するデザインセクションに追加
機能のドキュメント、ドキュメントのテンプレート、ドキュメント構成の規則、アプリとサービスのドキュメント対応付け	docs/project-reference/feature-spec-reference.md	関連する規則のセクションに追加
ドキュメントのインデックス作成、ドキュメントの整理、ドキュメントとコードの関係、ドキュメントの検索パターン	docs/project-reference/docs-index-reference.md	関連するセクションに追加
**設定でモデル化されるプロジェクトの事実：**ソース／モジュールのパス、グロブ、サービスまたはアプリのマップ、フレームワークと検索キーワード、テスト／E2E／統合テストの実行コマンド、システム起動またはヘルスチェックのコマンド、ドキュメントのルート、デザインシステムまたはスタイリングの場所、ツールの選択	$project-config 経由で docs/project-config.json へ	既存のスキーマフィールド。--describe にある正確な名前を使うこと。キーを決して作成しない
一般的なレッスン、ワークフローのヒント、ツール、AI の振る舞い、プロジェクトの規則、上記に該当しない内容	docs/project-reference/lessons.md	日付付きリスト項目として末尾に追加

---

防止策の深さの評価（保存前に必須）

教訓を保存する前に、ドキュメントの更新だけで十分か、それともより深い防止策が必要かを慎重に評価してください。

防止策のレイヤー	使用する場面	例
ドキュメントの更新のみ	一度限りの注意喚起、まれなエッジケース、チームの規約	「常に fluent validation API を使用する」→ docs/project-reference/backend-patterns-reference.md
プロジェクト設定フィールド（docs/project-config.json）	各スキルが行動前に参照すべき、機械可読なプロジェクトの事実が教訓である場合	「統合テストの前にシステムを起動する必要がある」→ $project-config 経由で integrationTestVerify.startupScript / systemCheckCommand
プロンプトルール（development-rules.md）	すべてのタスクで全エージェントが従うべきルール	「一括編集後に Grep を実行する」→ .claude/docs/development-rules.md
静的プロトコルの教訓（sync-inline-versions.md）	あらゆるプロジェクトで共通する、発生頻度が高く、気づかれないまま失敗する AI のミス	「コンテキスト圧縮後にファイルを読み直す」→ .claude/skills/shared/sync-inline-versions.md
フック（.claude/hooks/）	自動的に適用し、絶対に忘れてはならないルール	「重複排除マーカーを一致させる」→ lib/dedup-constants.cjs ＋整合性テスト
テスト（.claude/hooks/tests/）	回帰を防止する、検証可能な不変条件	「すべてのフックが共有モジュールからインポートする」→ test-all-hooks.cjs 内のテスト
スキルの更新（.claude/skills/）	常にこの確認を含めるべきワークフローの手順	「変更のレビューではドキュメントの陳腐化を確認する」→ スキルの SKILL.md を更新

判断フロー：

1. 記録する：教訓を記録します
2. 確認する：「AI がこの教訓を忘れた場合、同じミスが再発する可能性はありますか？」はいの場合 → ドキュメントの更新だけでは不十分です
3. 確認する：「テストまたはフックで自動的に検出できますか？」はいの場合 → フック／テストを推奨します
4. 静的プロトコルの教訓への昇格を評価する（下記を参照）
5. ユーザーに選択肢を提示し、直接尋ねる：
   • 「ドキュメントの更新のみ」— 最も適したリファレンスファイルに保存します（ほとんどの教訓に対するデフォルト）
   • 「ドキュメント＋プロンプトルール」— すべてのエージェントが確認できるよう、development-rules.md にも追加します
   • 「ドキュメント＋静的プロトコルの教訓」— 共有プロトコルの教訓にも追加します（基準は下記を参照）
   • 「完全な防止策」— 自動的に適用するフック、テスト、または共有モジュールを計画します
6. 選択した方法を実行する。「完全な防止策」の場合は、保存するだけでなく、$plan を使って計画を作成します。

静的プロトコルレッスンへの追加（評価必須）

レッスンを一般化した後、.claude/skills/shared/sync-inline-versions.md の 静的プロトコルレッスン に該当するかを評価します。静的プロトコルレッスンは CLAUDE.md に組み込まれ、AGENTS.md に反映され、プロジェクト初期化／同期ツールを通じて Codex の格納先にも同期されます。

該当基準（すべて満たすこと）：

1. 普遍的 — このコードベースだけでなく、あらゆる AI コーディングプロジェクトに適用できる
2. 高頻度で再発する — 注意喚起がなければ、AI エージェントが複数のセッションにわたって繰り返し同じ誤りを犯す
3. 失敗が表面化しない — 誤りによってエラーや警告が発生せず、出力品質がひそかに低下する
4. 既存のルールで未対応 — 同じ根本原因を扱う既存の静的プロトコルレッスンがない

静的プロトコルレッスン — 静的な格納先に組み込まれた、普遍的な AI の誤りを防ぐルールです。.claude/skills/shared/sync-inline-versions.md の ai-mistake-prevention および ai-mistake-prevention:full の SYNC ブロックに保存されています。それぞれ普遍的で、高頻度で再発し、失敗が表面化しないものである必要があります。 追加する前に、.claude/skills/shared/sync-inline-versions.md を読み、重複がないか確認してください。

該当する場合： 「ドキュメント＋静的プロトコルレッスン」案を推奨します。ユーザーの承認後、該当する共有 SYNC ブロックに新しい箇条書きとしてレッスンを追加し、プロジェクト初期化／同期パイプラインを実行して、共有元から CLAUDE.md、AGENTS.md、Codex の格納先を再生成します。

該当しない場合： 理由を説明します（例：「プロジェクト固有すぎる」「X に関する既存の静的プロトコルレッスンですでに対応済み」「発生頻度が低い — まれなエッジケースでしか起きない」）。ドキュメントのみ、またはプロンプトルールの案に進みます。

レッスンの品質ゲート（ブロッキング — 保存する前に一般化する）

コアプロトコル — 必ず実行してください： $learn リクエストは常に、具体的な事例として届きます（「バス経由で移行せず、Elasticsearch に大量のリクエストを送らない」など）。それをそのまま保存するのは、よくある失敗パターンです。書き込む前に、具体的な内容を必ず一般化してください。つまり、根底にある誤りの種類を特定し、その事例に固有の名詞を取り除いて、多くの将来の事例に当てはまるルールを書きます（「移行処理ではメッセージバス経由ではなく、DB に直接書き込む — すべての移行処理に適用」）。このチケットのファイル、サービス、ツールの名前を挙げずに教訓を述べられないなら、まだ一般化できていません。もう一段階抽象度を上げてください。迷ったときは、より一般的な形で保存してください。具体的すぎる教訓は、すべてのプロンプトに注入される無用の長物です。

すべての教訓は、根本原因のレベルにあり、どのコードベースにも通用する一般的な内容でなければなりません。保存する前に、次の3段階で抽出してください。

ステップ 1 — 症状ではなく、失敗パターンに名前を付ける：

失敗パターンとは、破綻の原因となった推論や前提のことです。出力がどう見えたかではありません。

症状（NG — 却下する）	失敗パターン（OK — 保存する）
「誤った列挙型の値を使った」	「ソースに存在するか確認せず、想定した API を使ってコードを生成した」
「名前空間／インポートが間違っていた」	「プロジェクト固有の設定ファイルを先に読まず、慣習からプロジェクトの設定を推測した」
「CI でハッピーパスのテストが失敗した」	「コードパスに必要な実行時インフラを追跡せずにアサーションを書いた」
「存在しないプロパティを設定した」	「基底クラスを読まずに、階層内のすべての型が同じインターフェイスを共有すると想定した」
「Y の前に必ずファイル X を読む」	「担当レイヤーの契約を読まずに実行コンテキストを推測し、原因ではなく症状の発生箇所を修正した」

ステップ 2 — 一般化できているか確認する：

この失敗パターンは、3つ以上の異なる状況やコードベースに当てはまりますか？ファイルが1つだけ、または特定の事例だけに当てはまるなら、抽象度を一段階上げてください。優れた教訓は、ある種類の誤り全体を防ぎます。

ステップ 3 — 普遍的なルールとして書く：

• プロジェクト固有の名前、ファイルパス、クラス名、ツール名をすべて取り除く
• どのコードベース、どの言語、どの種類のタスクでも役立つ内容にする
• 複数の誤りが同じ失敗パターンを共有するなら、たくさんの教訓ではなく、1つに統合する
• 確認：「別のプロジェクトで Java、Go、Python を使って作業する AI にも役立つか？」はいなら適切です。いいえなら書き直してください。

アンチパターンの例：

• NG：「マーカー文字列は常に lib/dedup-constants.cjs で確認する」→ プロジェクト固有のパス
• OK：「モジュールを統合するときは、共有定数を単一の信頼できる情報源からインポートし、インラインで重複定義しない。」
• NG：「フックを削除したら .claude/docs/hooks/README.md を更新する」→ プロジェクト固有のファイル
• OK：「コンポーネントを削除するとドキュメントが連鎖的に古くなるため、削除前に参照しているドキュメントをすべて洗い出す。」
• NG：「*.IntegrationTests で using を追加する前に GlobalUsings.cs を読む」→ プロジェクト固有のファイル
• OK：「プロジェクトの規約（インポート、名前空間、アノテーションなど）を使うコードを生成する前に、そのレイヤーのプロジェクトのブートストラップ／設定ファイルを読む。規約ファイルは、フレームワークのデフォルト設定を黙って上書きする。」

終了時の学習レビューゲート（完了とする前に必ず実施）

すべての$learn操作の最後に、次の2つのタスクを実行します。

タスク1 — 学習レビュー（価値＋汎用性＋再発性）：

• 明確な予防効果がある教訓だけを残します。
• 教訓は次のいずれかを満たす必要があります。
  • 多くのプロジェクト／コードベースに共通する
  • プロジェクト全体に適用される安定した原則である（アーキテクチャ上の不変条件、命名上の不変条件、ワークフロー上の不変条件）
• 次の教訓は対象外とします。
  • 現在のチケット／変更／ファイルに固有のもの
  • 発生頻度が低い、まれなエッジケース
  • 既存の教訓やレビュー用スキルですでに扱われているもの
• 対象がdocs/project-reference/lessons.md（すべてのプロンプトに挿入されるファイル）の場合、基準をさらに厳しくし、影響が大きく再発性の高いものだけを残します。

タスク2 — $why-reviewを実行する（反証的な検討）：

• $why-reviewを使って、この教訓を永続的なメモリーとして残す価値があるか検討します。
• 次の点を確認します。
  • この教訓が、同じ誤りの再発をどう防ぐのか
  • 一度限りのメモではなく、教訓として残すべき理由
  • 自動チェック（$code-review、$code-simplifier、$security-review、$lint、フック／テスト）では不十分な理由
• 根拠が弱い場合は、より抽象度の高い形に書き直すか、$learnをスキップします。

振り分けの判断手順

1. トリアージゲートを実行する — 再発性と自動修正のフィルターを確認します。いずれかを満たさない場合はここで終了します
2. 教訓の本文を読む — キーワードと分野を特定します
3. 教訓の品質ゲートを適用する — 根本原因を分析し、一般化して、普遍性を確認します
4. 格納先の種別を分類する — FACT 対 RULE（ルーティングテーブルの確認前に実施します）。 次のように判断します。「これは機械可読なプロジェクトの事実か、それともエージェントが推論して適用するルールか？」 事実 → docs/project-config.json、ルール → 説明文のリファレンスドキュメント、両方 → 両方。判断にあたっては設定ファイルを読むか、$project-config（--describe）を使い、設定に含まれる情報を推測するのではなく、実際のスキーマに基づいて判断します。 — 理由：この手順を省くと、プロジェクトの事実がツールに読み取られない説明文として記録され、次回の再生成時に矛盾が生じるためです。
5. 予防の深度を評価する — ドキュメント／設定だけでよいか、さらに踏み込んだ予防策が必要かを判断します
6. ルーティングテーブルと照合する — 最も適したファイル（または設定フィールド）を選びます
7. ユーザーに伝える：「この教訓はdocs/{file}に記載するのが最適です。確認しますか？ [Y/n]」
8. 承認された場合 — 対象ファイルを読み、適切なセクションを見つけて教訓を追記します（設定ファイルが対象の場合は$project-config経由で処理します）
9. 却下された場合 — 代わりに使用するファイルをユーザーに尋ねます

対象ファイルごとの形式

docs/project-reference/lessons.md（一般的な教訓）の場合：

- [YYYY-MM-DD] <lesson text>

パターン／ルール用ファイル（code-review-rules、backend-patterns、frontend-patterns、integration-test）の場合：

• ファイル内で最も関連性の高い既存のセクションを見つけます
• 教訓をルール、アンチパターン項目、またはコード例として追記します
• ファイルで既に使われている形式（テーブル、コードブロック、箇条書き）を使用します
• 該当するセクションがない場合は、アンチパターンまたは一般的なルールのセクションに追記します

予算の適用（docs/project-reference/lessons.mdでは必須）

docs/project-reference/lessons.mdは、プロジェクト作業中に読み込まれる静的なプロジェクトリファレンス用ファイルです。トークン予算を管理する必要があります。

厳格な上限： 20000文字（約6666トークン）。新しい教訓を保存する前に確認してください。

docs/project-reference/lessons.mdに追加する場合の手順：

1. ファイルを読み込み、文字数を数えます（wc -c docs/project-reference/lessons.md）
2. 現在の文字数 + 新しい教訓が20000文字を超える場合 → 保存前に予算のトリミングを実行します
3. 予算内の場合 → 通常どおり保存します

予算のトリミング手順：

1. 現在の教訓をすべて、それぞれの文字数とともに表示します
2. 各教訓を次の2つの観点で評価します。
   • 汎用性 — どの程度の頻度で当てはまるか（毎回のセッションか、まれな例外か）
   • 再発リスク — 注意喚起がなければ、AIが同じ間違いを繰り返す可能性はどの程度か
3. それぞれを評価します。HIGH（そのまま残す）、MEDIUM（簡潔にする候補）、LOW（削除候補）
4. 次のようにユーザーに直接尋ねます。「予算を超過しています。次のLOW/MEDIUM項目の削除または簡潔化をおすすめします：[リスト]。承認しますか？」
5. 承認された場合：MEDIUM項目を簡潔にし（表現を短くする）、LOW項目を削除してから、新しい教訓を保存します
6. 拒否された場合：どの項目を削除または簡潔にするか、ユーザーに尋ねます

簡潔化のルール：

• 例を削除し、ルールを残します。"XのようなパターンはYの構文を壊す" → ルールだけを記述します
• 同じ根本原因に由来する教訓は、関連するもの同士でまとめます
• 目標：各教訓を250文字以下にします（簡潔な1文＋太字のタイトル）

対象外： その他のルーティング先（backend-patterns-reference.md、code-review-rules.mdなど）。これらのファイルにはそれぞれ独自のサイズ制限があり、毎回のプロンプトではなく、コンテキストに応じて読み込まれます。

動作

1. $learn <text> — 最適なファイルに教訓を振り分けて追加します（対象がlessons.mdの場合は予算を確認します）
2. $learn list — 12個すべての対象ファイルから教訓を読み込んで表示します（ファイルごとに分類し、lessons.mdは文字数も表示します）
3. $learn remove <N> — 行番号を指定してdocs/project-reference/lessons.mdから教訓を削除します
4. $learn clear — docs/project-reference/lessons.mdの教訓だけをすべて消去します（先に確認します）
5. $learn trim — docs/project-reference/lessons.mdの予算のトリミングを手動で実行します
6. ファイルの作成 — 対象ファイルが存在しない場合は、ヘッダーのみで作成します

自動推定による有効化

Claudeが会話中に修正を示す表現（例：「常にXを使う」「これを覚えておいて」「Yは絶対にしない」「今後は」）を検出すると、このスキルが自動的に有効になります。明示的な$learnではなく自動推定で有効になった場合は、保存前にユーザーに確認します：「これを教訓として保存しますか？ [Y/n]」

教訓がAIに届く仕組み

教訓とパターンのリファレンスは、CLAUDE.mdのプロジェクトリファレンス文書ゲートに従って静的に読み込まれます。

• docs/project-reference/lessons.md — すべてのタスクで読み込まれます（ゲートに常に含まれます）。
• パターン／ルールのリファレンス（backend-patterns-reference.md、code-review-rules.mdなど）— 対応するトリガーに応じて読み込まれます（上記のリファレンス文書カタログ表を参照）。

ルーティングは静的な文章に基づくため、フックのないハーネス（Codex）でもClaude Codeと同じ教訓とパターンが読み込まれます。

プロンプトの強化（最後の手順として必須）

いずれかの対象ファイルに教訓を保存した後、変更したファイルに対して$prompt-enhanceを実行し、AIの注意喚起のアンカリングとトークンの品質を最適化します。

実行するタイミング：

• 教訓の保存が成功するたび（対象ファイルを問わず）
• 変更した特定のファイルパスを指定します

実行内容：

• 新しい教訓が、既存の先頭／末尾の要約アンカリングに統合されるようにします
• トークン使用量を最適化し、文章を引き締め、重複する内容をまとめます
• 保存による内容の欠落がないことを確認します

実行方法：

$prompt-enhance docs/project-reference/<modified-file>.md

スキップ条件（prompt-enhanceを実行しない場合）：

• 保存先がlessons.mdで、かつファイルが1500文字未満の場合（最適化の効果が小さいため）
• ユーザーが「保存のみ、強化は不要」と明示的に依頼した場合

---

[IMPORTANT] 作業を開始する前に、タスク管理を使ってすべての作業を小さなタスクに分割してください。各ファイルを読むタスクも含めてください。長いファイルによるコンテキストの喪失を防げます。簡単なタスクの場合は、スキップしてよいかを AI が必ずユーザーに確認してください。

必須の最後のタスクは、常に次の順序で実行します：

1. 「Learn Review（学びの価値＋汎用性＋再発性の判定）を実行する。」
2. 「その学びを永続的なメモリに残す価値があるかを検討するため、$why-review を実行する。」
3. 「AI の注意を引き付けるために学びの内容を最適化するため、$prompt-enhance <modified-file> を実行する。」

3 つすべてのタスクを実行するまで、スキルを完了としてマークしないでください。

AI のミス防止 — すべてのタスクで、次の失敗パターンを避けてください：

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

批判的思考の姿勢 — 批判的思考と順序立てた思考を実践してください。行動に移すには、すべての主張に追跡可能な根拠があり、確信度が 80% を超えている必要があります。 幻覚の防止： 推測を事実として提示しないでください。すべての主張の情報源を示し、不確実さを率直に認め、出力に誤りがないか自分で確認し、独立した情報源とも照合し、自分の確信を過信しないでください。根拠のない確信こそ、あらゆる幻覚の根本原因です。

MUST ATTENTION 批判的思考と順序立てた思考を実践してください。すべての主張には、適切で追跡可能な根拠が必要です（リポジトリ／コードに関する主張は file:line、調査、製品、コンテンツ、ドキュメントに関する主張は情報源の URL またはアーティファクト内のセクション）。行動に移すには確信度が 80% を超えている必要があり、60% 未満の場合は推奨してはいけません。幻覚を防いでください。推測を事実として提示せず、不確実さを率直に認め、独立して照合し、自分の確信を過信しないでください。

MUST ATTENTION AI のミス防止を実践してください。生成した内容を根拠と照合し、削除や名前の変更を行う前に後続の参照先を追跡し、影響を受けるすべての出力を検証し、コンテキストを失った後はファイルを再読し、作業を始める前に曖昧さを明らかにしてください。

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

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

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

最後の確認事項

重要・必ず注意： まず一般化してください。多くのケースに適用できる汎用ルールを抽出し、個別の事例をそのまま保存してはなりません。保存前に、チケット名、ファイル名、サービス名、ツール名をすべて削除してください。

必ず注意： 適用中のプロトコル（このスキルに含まれる SYNC／共有ブロックの要約。本文は上記が正本です）：

• AI のミス防止： 生成した内容を根拠と照合し、後続の参照先をたどり、影響を受けるすべての出力を検証し、コンテキストを失った後に再読し、曖昧さを明らかにしてください。
• クリティカルシンキング： 批判的かつ順序立てて考え、証拠をたどり、確信度を 80％より高く保ち、事実として決して推測してはなりません。

重要・必ず注意：目標： 各教訓を失敗モードのレベルで、将来のセッションが実際に読む保存先に記録してください。最適な保存先は、内容に最も適した文章形式のリファレンスドキュメント、または機械可読なプロジェクト情報の場合は docs/project-config.json です。 重要：必ず注意 主な手順は順番どおりに実行します：一般化 → Triage Gate → Lesson Quality Gate → 記録先を分類（FACT → config・RULE → prose・両方 → 両方） → Prevention Depth Assessment → Routing Table → ユーザーに確認 → 保存 → Learn Review → $why-review → $prompt-enhance。 重要：必ず注意 まず Triage Gate を実行します。再発の可能性が低い、またはレビュー用スキルで検出できる場合は、$learn を完全にスキップします。 重要：必ず注意 Reference Doc Catalog を確認して最適な保存先ファイルを見つけます。保存先は常に lessons.md とは限りません。 重要：必ず注意 ルーティングを決めるたびに、prose ドキュメントとあわせて docs/project-config.json も記録先の候補として検討します。まず直接読み込むか、$project-config を使ってセクションと正確なフィールド名を確認します。理由：prose のみに書かれたプロジェクトの事実は、config を読み込むツールからは見えず、次に生成ドキュメントが config から再生成されたときに矛盾します。 重要：必ず注意 config に記録する場合は、node .claude/hooks/lib/project-config-schema.cjs --describe からフィールド名をそのままコピーし、既存のフィールドを優先して、書き込みには $project-config を使います。適合するフィールドがない場合は、キーを勝手に作らず、スキーマへの追加案をユーザーに提示します。理由：未知のキーは警告が出るだけです（project-config-schema.cjs:618,688）。そのため、勝手に作ったキーは適用されたように見えても、読み込むコンシューマーがありません。 重要：必ず注意 config に記録するのは FACT のみです。ナラティブ形式の教訓を config の文字列フィールドに貼り付けてはいけません。そのルールは対応する prose リファレンスドキュメントに記載します。 重要：必ず注意 必須の最後のタスクは常に次の順番です：Learn Review → $why-review → $prompt-enhance <modified-file> 重要：必ず注意 作業を始める前にタスク管理を使って、作業を小さな todo タスクに分割します。 重要：必ず注意 再発頻度の高い教訓には、自動挿入されるファイルを優先します（可視性が高いため）。

合理化の防止：

言い逃れ	反論
「教訓だから、lessons ドキュメントに入れる」	まず FACT と RULE を分類します。パス、実行コマンド、モジュールマップは config データです。prose に記載すると、config を読み込むコンシューマーから見えません。
「config に何があるか、おおよそ分かっている」	読み込むか、$project-config（--describe）を実行します。推測したスキーマに基づくルーティングでは、誰も読み込まないフィールドに書き込むことになります。
「適合するフィールドがないので、妥当なキーを追加する」	未知のキーは警告が出るだけです。スキーマへの追加案をユーザーに提示し、決して黙って追加しないでください。
「ユーザーの言葉をそのまま保存するのが最も忠実だ」	逐語的な記録は、よくある失敗です。失敗の原因まで掘り下げ、このチケット固有の名詞を取り除いてください。
「小さな教訓なので、最後のゲートは省略する」	保存するたびに、例外なく Learn Review → $why-review → $prompt-enhance を実行します。

[TASK-PLANNING] 作業を始める前に、タスクの範囲を分析し、タスク管理を使って体系的に小さな todo タスクとサブタスクに分割します。

Hookless Prompt Protocol Mirror（自動同期）

ソース：.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、ビジネスエンティティ、機能ルール）を一切参照してはいけません。漏れがコンパイルされ、実行されると、再利用可能なはずの層が一つの利用側と結合していても、レビューで気づかれずに通過してしまいます。共有型からドメイン情報を排除し、サブクラス化／コンポジションを通じて、ドメインフィールド／ロジックを利用側へ移してください。理由：一つの利用側のドメインに結合した層は、もはや再利用可能ではありません。