Codex 互換性に関する注意:

• Codex でリポジトリスキルを $skill-name で呼び出してください。このミラーコピーはレガシーの Claude /skill-name 参照を書き換えます。
• Codex ミラーの計画ガイダンスには plan-hard スキルを優先してください。
• タスクトラッカー義務: ワークフローやスキルステップを実行する前に、すべてのステップのタスク追跡を作成・更新し、進捗の変化に応じて同期を保つこと。
• ユーザー質問プロンプトは Codex でユーザーに直接質問することを意味します。
• Claude 固有のモード切り替え指示が現れた場合は無視してください。
• 厳密な実行契約: ユーザーがスキルを明示的に呼び出す場合、そのスキルプロトコルを記述通りに実行すること。
• サブエージェント認可: スキルがユーザー呼び出しまたは AI 検出され、そのプロトコルがサブエージェントを必要とする場合、そのスキル起動は必要な spawn_agent サブエージェントをそのタスクに使用することを認可します。
• ユーザーが明示的に偏差を承認しない限り、プロトコルステップをスキップ、並べ替え、またはマージしないこと。
• ワークフロースキルの場合、リストされた各子スキルステップを明示的に実行し、段階的な証拠を報告すること。
• 必要なステップ/ツールがこの環境で実行できない場合は、適応する前に停止してユーザーに確認すること。

<!-- CODEX:PROJECT-REFERENCE-LOADING:START -->

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 から始めて、タスクに関連するファイルのみを開いてください。

<!-- CODEX:PROJECT-REFERENCE-LOADING:END -->

クイックサマリー

目標: PDF ファイルを適切にフォーマットされた Markdown に変換し、ネイティブテキスト vs スキャン文書を自動検出します。

ワークフロー:

1. 自動検出 — PDF にネイティブテキストがあるか OCR が必要かを判定
2. 変換 — scripts/convert.cjs を入力パスとオプションのモード/出力フラグで実行
3. 出力 — 成功ステータス、ページ数、出力パスを含む JSON を返す

重要なルール:

• --mode auto (デフォルト) を使用して、ツールにネイティブ vs OCR の判定を任せる
• スキャン PDF の OCR には追加の tesseract.js セットアップが必要
• 複雑な複数列レイアウトは構造を完全には保持できない場合がある

懐疑的になること。批判的思考、段階的思考を適用。すべての主張には追跡可能な証拠が必要です。信頼度は 80% 以上である必要があります。

pdf-to-markdown

ネイティブテキスト vs スキャン文書を自動検出する機能付きで、PDF ファイルを Markdown 形式に変換します。

インストールが必須

このスキルは npm 依存関係が必須です。 以下のいずれかを実行してください:

# オプション 1: ClaudeKit CLI 経由でのインストール (推奨)
ck init  # すべてのスキルを処理する install.sh を実行

# オプション 2: 手動インストール
cd .claude/skills/pdf-to-markdown
npm install

依存関係: @opendocsg/pdf2md (ネイティブ PDF), pdfjs-dist (PDF パース)

注: スキャン PDF の OCR には追加セットアップが必要です (OCR セクションを参照)。

クイックスタート

# 基本的な変換 (ネイティブ vs スキャンを自動検出)
node .claude/skills/pdf-to-markdown/scripts/convert.cjs --input ./document.pdf

# 出力パスを指定
node .claude/skills/pdf-to-markdown/scripts/convert.cjs -i ./doc.pdf -o ./output.md

# ネイティブモードを強制 (OCR 検出をスキップ)
node .claude/skills/pdf-to-markdown/scripts/convert.cjs -i ./doc.pdf --mode native

CLI オプション

オプション	短形	説明	デフォルト
--input	-i	入力 PDF ファイルパス	(必須)
--output	-o	出力 Markdown ファイルパス	{input}.md
--mode	-m	変換モード: auto, native, ocr	auto
--help	-h	ヘルプメッセージを表示

機能

• 自動検出: PDF にネイティブテキストがあるか、OCR が必要かを自動判定
• ネイティブ PDF: @opendocsg/pdf2md を使用した高速抽出
• テーブル: 基本的なテーブル構造の保持
• クロスプラットフォーム: Windows、macOS、Linux で動作
• システム依存なし: 純粋な JavaScript 実装

変換モード

Auto (デフォルト)

最初のページで抽出可能なテキストがあるかチェック。テキストが見つかった場合はネイティブ抽出を使用、それ以外の場合は OCR 警告にフォールバック。

Native

高速直接テキスト抽出。選択可能なテキストを持つ PDF (スキャン画像ではない) に最適。

OCR (スキャン PDF) - 近日公開予定

スキャン文書用。現在は未実装 - PDF がスキャンに見える場合、スキルが通知します。

出力

成功時に JSON を返す:

{
    "success": true,
    "input": "/path/to/input.pdf",
    "output": "/path/to/output.md",
    "stats": {
        "pages": 5,
        "mode": "native"
    }
}

制限事項

• 複雑な複数列レイアウトは構造を保持しない場合がある
• スキャン PDF の OCR 精度は画像品質に依存
• 数式は完全には変換されない場合がある
• 初回実行時の OCR は言語データをダウンロード (~15MB)

OCR セットアップ (オプション)

スキャン PDF サポートのため、追加の依存関係をインストール:

npm install tesseract.js pdfjs-dist canvas

注: canvas パッケージは一部のシステムでビルドツールが必要な場合があります。

---

[重要] タスク追跡を使用して、開始前にすべての作業を小さなタスクに分割してください — 各ファイル読み込みのタスクを含めて。これは長いファイルからのコンテキスト喪失を防ぎます。単純なタスクの場合、AI はスキップするかどうかをユーザーに確認する必要があります。

<!-- SYNC:ai-mistake-prevention -->

AI 誤り防止 — すべてのタスクで避けるべき障害モード: 削除する前に下流の参照をチェック。 コンポーネント削除はドキュメントとコードの陳腐化カスケードを引き起こします。削除前にすべての参照ファイルをマップしてください。 AI 生成コンテンツを実際のコードと照合して検証。 AI は API、クラス名、メソッドシグネチャを幻想します。ドキュメント化や参照する前に grep で存在を確認してください。 編集後は依存関係チェーン全体を追跡。 定義の変更はそこから派生した下流変数とコンシューマーを見落とします。常にチェーン全体を追跡してください。 正確性を検証する際は ALL コードパスを追跡。 コード存在を確認することは実行を確認することではありません。常に早期終了、エラーブランチ、条件スキップを追跡してください — ハッピーパスだけではなく。 デバッグする際は「誰の責任?」を聞く。 バグが呼び出し元 (データ違い) か呼び出し先 (処理違い) かを追跡。責任レイヤーで修正してください — 症状サイトをパッチしないでください。 既存の値は意図的だと仮定 — 変更前に「なぜ?」を聞く。 定数、制限、フラグ、パターンを変更する前に: コメントを読み、git blame をチェック、周辺コードを確認してください。 すべての影響を受ける出力を検証、最初だけではなく。 複数スタックに影響する変更は EVERY 出力を検証する必要があります。1 つの緑チェックはすべての緑チェックではありません。 全体的なデバッグ — 最も近い注意トラップに抵抗。 障害を調査するとき、最初にすべての前提条件をリスト (設定、環境変数、DB 名、エンドポイント、DI 登録、データ前提条件)、その後コード層仮説を立てる前に各々を証拠と照合。 外科的変更 — diff テストを適用。 バグ修正: 変更されたすべての行は必ずバグに直結するもの。隣接コードのリスタイルや改善をしないでください。拡張タスク: 改善を実装して明示的に発表してください。 コーディング前に曖昧さを表面化 — 静かに選ばないでください。 リクエストに複数の解釈がある場合、各々の労力推定を示して提示し質問。すべてのレコード、ファイルベース、またはより複雑なパスを仮定しないでください。

<!-- /SYNC:ai-mistake-prevention --> <!-- SYNC:critical-thinking-mindset -->

批判的思考マインドセット — 批判的思考、段階的思考を適用。すべての主張には追跡可能な証拠が必要で、80% 以上の信頼度が必要です。 幻想回避: 推測を事実として提示しないでください — すべての主張に対して出典を引用、不確実性を自由に認める、出力をエラーについて自己チェック、独立して相互参照、自信に懐疑的でいてください — 証拠根拠のない確実性はすべての幻想の根です。

<!-- /SYNC:critical-thinking-mindset --> <!-- SYNC:critical-thinking-mindset:reminder -->

必須注意 批判的思考を適用してください — すべての主張には追跡可能な証拠が必要で、80% 以上の信頼度で行動。幻想回避: 推測を事実として提示しないでください。

<!-- /SYNC:critical-thinking-mindset:reminder --> <!-- SYNC:ai-mistake-prevention:reminder -->

必須注意 AI 誤り防止を適用してください — 全体的なデバッグ、責任レイヤーで修正、コーディング前に曖昧さを表面化、圧縮後にファイルを再読み。

<!-- /SYNC:ai-mistake-prevention:reminder -->

最終的なリマインダー

重要 必須注意 タスク追跡を使用して小さなtodo タスクに作業を分割してから開始 重要 必須注意 コードベースで 3 つ以上の類似パターンを検索してから新しいコードを作成 重要 必須注意 すべての主張に対して file:line 証拠を引用 (80% 以上の信頼度で行動) 重要 必須注意 最終レビュー todo タスクを追加して作業品質を検証

[タスク計画] 行動する前に、タスク追跡を使用してタスクスコープを分析し、小さな todo タスクとサブタスクに体系的に分割。

<!-- CODEX:SYNC-PROMPT-PROTOCOLS:START -->

フックレスプロンプトプロトコルミラー (自動同期)

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

[ワークフロー実行プロトコル] [ブロッキング] ワークフロー実行プロトコル — 必須 重要 必須 重大。理由の如何を問わずスキップしないこと。

1. 検出: プロンプトをワークフローカタログに照合
2. 分析: 最適一致ワークフローを見つけて、カスタムステップの組み合わせがより適していないかを評価
3. 質問 (必須形式): この構造を使用した直接的なユーザー質問を使用:
   • 質問: 「どのワークフローをアクティブ化しますか?」
   • オプション 1: 「[最適一致ワークフロー] をアクティブ化 (推奨)」
   • オプション 2: 「カスタムワークフローをアクティブ化: [step1 → step2 → ...]」 (1 行の根拠を含める)
4. アクティブ化 (確認時): 標準で $workflow-start <workflowId> を呼び出し、カスタムステップを手動でシーケンス
5. タスク作成: すべてのワークフローステップのタスク追跡
6. 実行: 順番に各ステップに従う [批判的思考マインドセット] 批判的思考、段階的思考を適用。すべての主張には追跡可能な証拠が必要で、80% 以上の信頼度が必要です。 幻想回避原則: 推測を事実として提示しないでください — すべての主張に対して出典を引用、不確実性を自由に認める、出力をエラーについて自己チェック、独立して相互参照、自信に懐疑的でいてください — 証拠根拠のない確実性はすべての幻想の根です。 AI 注意原則 (初期性-最近性): 長いプロンプト/プロトコルの上下に 3 つの最も重大なルールを配置して、長いコンテキストウィンドウ内で指示遵守が生き残ることを保証

学習教訓

学習教訓

[重大] 苦労して獲得したプロジェクトデバッグ/アーキテクチャルール。 仮説を立てたりコードを書いたりする前に必須注意で適用してください。

クイックサマリー

目標: 既知の障害パターンの再発を防止 — デバッグ、アーキテクチャ、命名、AI オーケストレーション、環境。

トップルール (常に適用):

• 必須注意 すべての前提条件を検証 (設定、環境、DB 名、DI 登録) コード層仮説の前に
• 必須注意 責任レイヤーで修正 — 呼び出し元固有の防御的コードで症状サイトをパッチしないこと
• 必須注意 並列非同期 + リポジトリ/UoW には ExecuteInjectScopedAsync を使用 — ExecuteUowTask を決して使わないこと
• 必須注意 コンテンツではなく目的で命名 — メンバー追加により強制的な名前変更 = 壊れた抽象化
• 必須注意 サブエージェント検査結果を各ファイル後に増分的に保持 — 終了時に一括処理しないこと
• 必須注意 Windows bash: Python エイリアスを検証 (where python/where py) — python/python3 が解決するのを仮定しないこと

---

デバッグと根本原因推論

• [2026-04-11] 全体的: コード前に環境を検証。 障害 → すべての前提条件をリスト (設定、環境変数、DB 名、エンドポイント、DI 登録、認証情報、権限、データ前提条件) → コード層仮説の前に各々を証拠で検証 (grep/cat/クエリ)。最悪のウサギの穴: 最も近いレイヤーをダイビングしながらバグが他の場所 — 例えば、「同期タイムアウト」をデバッグするのに何時間も、実際の原因: テスト appsettings が間違った DB を指している。常に最も安い チェックを最初に実行。
• [2026-04-01] 修正する前に「誰の責任?」を聞く。 トレース: バグは呼び出し元 (データ違い) か呼び出し先 (処理違い)? 責任レイヤーで修正 — 症状サイトをパッチしないこと。
• [2026-04-01] エラーサイトではなくデータライフサイクルをトレース。 データをフォロー: 作成 → 変換 → 消費。バグは通常データが作成時に違う場所で、消費時ではありません。
• [2026-04-01] 呼び出し元に依存しないコード。 関数/ハンドラー/コンシューマーは誰が呼び出すかを知りません。コメント/ガード/メッセージはビジネス意図を説明 — 特定の呼び出し元を参照しないでください (テスト、シーダー、スクリプト)。

アーキテクチャ不変式

• [2026-05-09] ユーザー名マテリアライゼーション 必須注意 User.UpdateName(firstName, middleName, lastName) を通過する必要があります。 ドメインメソッド (src/Services/bravoTALENTS/Employee.Domain/AggregatesModel/User.cs:202-209) は単一の真実のソースとして FullName を再計算。3 つのサイト依然として名前フィールド割り当て後に手動で user.FullName = user.GetFullName() をパッチ — src/Services/bravoTALENTS/Employee.Application/Factories/UserFactory.cs:50, src/Services/bravoSURVEYS/LearningPlatform.Application/ApplyPlatform/MessageBus/Consumers/AccountUserDeletedEventBusConsumer.cs:102, src/Services/bravoINSIGHTS/Analyze/Analyze.Application/MessageBus/Consumers/AccountUserDeletedEventBusConsumer.cs:66。次に触れるときは手動パッチを user.UpdateName(...) に置き換えて不変式を維持。
• [2026-03-31] 並列非同期 + リポジトリ/UoW 必須注意 ExecuteInjectScopedAsync を使用、決して ExecuteUowTask ではない。 ExecuteUowTask は新規 UoW を作成しますが外部 DI スコープを再利用 (同じ DbContext) — 並列イテレーション非スレッドセーフ DbContext を共有し静かにデータを破損。ExecuteInjectScopedAsync は新規 UoW + 新規 DI スコープを作成 (反復ごとの新規リポジトリ)。
• [2026-03-31] バスメッセージ命名 必須注意 サービス名プレフィックスを含める — コアサービスは決して機能イベントを消費しません。 プレフィックスはスキーマ所有権を宣言 (AccountUserEntityEventBusMessage = Accounts 所有)。コアサービス (Accounts, Communication) リーダー。機能サービス (Growth, Talents) コアに送信 必須注意 {CoreServiceName}...RequestBusMessage を使用 — コアが消費するための独自のイベントを定義しないこと。

命名と抽象化

• [2026-04-12] 目的ではなくコンテンツで命名 — 「OrXxx」アンチパターン。 HrManagerOrHrOrPayrollHrOperationsPolicy はセットメンバーを命名し、何がガードするかではありません。ロール追加 → 名前変更 = 壊れた抽象化。ルール: 名前は DOES/GUARDS を表現、CONTAINS ではありません。テスト: メンバー追加/削除により強制的な名前変更? YES = コンテンツ駆動 = 不良 → 目的に名前変更 (例: HrOperationsAccessPolicy)。微妙: 「Or」はよい動作イディオム (FirstOrDefault, SuccessOrThrow) — HAPPENS を表現、メンバーシップではありません。

環境とツール

• [2026-04-20] Windows bash: python/python3 が解決するのを仮定しないこと — エイリアスを最初に検証。 Python は bash PATH の下でこれらの名前にない可能性があります。チェック: where python / where py。常に py (Windows Python ランチャー) ワンライナー、JS 代替がある場合 node を優先。

テスト固有の教訓 → docs/project-reference/integration-test-reference.md 学習教訓セクション。本番コードアンチパターン → docs/project-reference/backend-patterns-reference.md アンチパターンセクション。一般的なデバッグ/リファクタリングリマインダー → システム教訓 .claude/hooks/lib/prompt-injections.cjs。

---

最終的なリマインダー

• 重要 必須注意 全体的: すべての前提条件を検証 (設定、環境、DB 名、エンドポイント、DI 登録) コード層仮説の前に — 最も安いチェックを最初に実行
• 重要 必須注意 責任レイヤーで修正 — 症状サイトをパッチしないこと; トレース呼び出し元 (データ違い) vs 呼び出し先 (処理違い)、根本所有者を修正
• 重要 必須注意 並列非同期 + リポジトリ/UoW → 常に ExecuteInjectScopedAsync、決して ExecuteUowTask (共有 DbContext = 静かなデータ破損)
• 重要 必須注意 バスメッセージプレフィックス = スキーマ所有権; 機能サービスは決してコアサービスのイベントを定義しないこと — {CoreServiceName}...RequestBusMessage を使用
• 重要 必須注意 目的で命名 — メンバー追加/削除により強制的な名前変更 = 壊れた抽象化
• 重要 必須注意 サブエージェント 必須 各ファイル/セクション後に検査結果を書く — 最終書き込みにすべての検査結果をバッチしないこと
• 重要 必須注意 Windows bash: python/python3 が解決するのを仮定しないこと — 最初に where python/where py を実行、py ランチャーまたは node を使用
• 重要 必須注意 すべての主張に対して file:line 証拠が必要 — 80% 以上の信頼度で行動、 決して推測しないこと

[教訓学習リマインダー] [ブロッキング] タスク計画と継続的改善 — 必須。スキップしないこと。

開始前に作業を小さなタスク (タスク追跡) に分割。最終タスクを追加: 「AI 誤りと学習教訓を分析」。

教訓を抽出 — 根本原因のみ、症状修正ではなく:

1. 症状ではなく障害モード に名前を付ける — 「ソースを読まずに API が存在すると仮定」「間違った enum 値を使用」ではなく。
2. 一般性テスト: この障害モードは ≥3 コンテキスト/コードベースに適用? いいえ → 1 レベル上に抽象化。
3. 普遍ルールとして書く — プロジェクト固有の名前/パス/クラスを削除。あらゆるコードベースで有用。
4. 統合: 複数の誤りが同じ障害モードを共有 → 1 つの教訓。
5. 再発ゲート: 「この再発は将来セッションで「このリマインダーなしで再発? いいえ → $learn をスキップ。
6. 自動修正ゲート: 「$code-review/$code-simplifier/$security/$lint がこれをキャッチできる?」— はい → レビュースキル改善。
7. 両方のゲートパス → ユーザーに $learn を実行するよう促す。 [タスク計画] [必須] ワークフローやスキルステップを実行する前に、計画されたすべてのステップのタスク追跡を作成/更新し、その後各ステップの開始/完了時に同期を保つ。

<!-- CODEX:SYNC-PROMPT-PROTOCOLS:END -->