Deep Code Reader

コードベースを体系的に読み込んで理解し、深い知識（モジュール機能、設計ロジック、データ構造、状態フロー、および修正ガイド）をキャプチャする検証済みの認知スキルセットを生成します。

コア機構：クローズドブック試験の検証ループにより、生成されたスキルが浅い要約ではなく、真に包括的であることを保証します。

1. チームロール

このプロセスを堅牢で概念的に明確にするため、システムはソフトウェアエンジニアリングチームをモデルにした3つの異なるエージェントを採用しています：

• エージェント A（テックライター）：深いリーダー。ソースコードを読み込み、包括的なスキル文書を作成します。
• エージェント B（QAエンジニア）：試験官。ソースコードを読み込み、検証可能なファクトを抽出し、テスト問題を生成します。
• エージェント C（ジュニア開発者）：受験者。エージェント Aが作成した文書のみを読んでエージェント Bの質問に答える新しいチームメンバーとして機能します。

2. 使用方法

Deep Code Readワークフローをトリガーするための CLI コマンドは以下の通りです：

/deep-code-read <source> <output-dir>

• source：ローカルパス（例：./path/to/repo）または GitHub URL（例：https://github.com/org/repo）
• output-dir：生成されたスキルが書き込まれる場所（例：プラットフォームのスキルディレクトリ）

3. 全フロー

これらのフェーズを順番に従う必要があります。プラットフォームのタスク/TODO トラッキング機構を使用してモジュール全体の進捗を追跡してください。

3.1 フェーズ 1：準備

この初期フェーズは、ターゲットソースコードベースの解決と準備を処理します。

1. プロジェクト名を決定します：
   • ローカルパス → ディレクトリ名
   • GitHub URL → リポジトリ名
2. ソースが URL の場合：
   • {output-dir}/{project-name}/ にクローンします
   • ディレクトリが既に存在する場合は、クローンをスキップして使用します
3. ソースがローカルパスの場合：
   • パスが存在し、git リポジトリであることを確認します
   • 直接使用します（読み取り専用 — ソースリポジトリ内のファイルを修正しないでください）
4. バージョンを検出します：
   • ソースリポジトリで git tag --list を実行します
   • タグが存在する場合は、semver対応の順序でソートし（v プレフィックスを処理）、最新を推奨します
   • 適切なタグがない場合は、main または master ブランチを推奨します
5. 一時停止 — ユーザーに推奨事項を提示します：

   「以下のタグ/ブランチが検出されました：[リスト]。{recommended} の追跡をお勧めします。確認するか、別のターゲットを指定してください。」

6. 確認された ref をチェックアウトします

3.2 フェーズ 2：スキャン

このフェーズはリポジトリ構造をスキャンして、境界と依存関係を識別します。

1. ソースリポジトリディレクトリ構造をスキャンします
2. ヒューリスティックを使用してモジュール境界を識別します：
   • src/、lib/、pkg/、packages/ またはプロジェクトルート直下のトップレベルディレクトリ
   • 言語固有のパターン：Python パッケージ（__init__.py）、Go パッケージ、Node パッケージ（package.json）など
   • 既存のモジュールドキュメントまたはマニフェストファイルを探します
3. モジュール間のインポート/依存関係を分析します
4. 一時停止 — モジュールリストと依存関係グラフをユーザーに提示します：

   「以下のモジュールが見つかりました：[1行説明付きリスト]。深く読むモジュールを選択してください（または「all」）。」

5. ユーザーの選択を記録します — 選択されたモジュールごとに1つのタスク

3.3 フェーズ 3：深い読み込み（エージェント A — テックライター）

このフェーズは基礎となるスキル文書を生成します。

各選択されたモジュールに対して、tech-writer-prompt.md のプロンプトテンプレートを使用してサブエージェントをディスパッチします。

サブエージェントディスパッチパラメータ：

• prompt：変数が埋め込まれた tech-writer-prompt.md をレンダリング
• description：「Deep read {module-name}」

プロンプトに埋め込む変数：

• {source-dir}：ソースリポジトリへのパス
• {module-dir}：ソースリポジトリ内の特定モジュールへのパス
• {output-dir}：スキル出力ディレクトリ
• {project-name}：抽出されたプロジェクト名
• {module-name}：モジュール名
• {ref}：追跡されたタグ/ブランチ

テックライターが完了した後、{output-dir}/{project-name}-fj-{module-name}/ にスキルファイルが書き込まれたことを確認します。モジュールのタスク状態を更新します。

3.4 フェーズ 4：検証（ABC ループ）

このフェーズは、生成されたスキルが正確で完全であることを確認するコア検証ループを実行します。

スキルが生成された各モジュールに対して、検証サイクルを実行します：

ステップ 1 — エージェント B / QA エンジニア（質問生成）：

qa-engineer-prompt.md を使用してサブエージェントをディスパッチします。軽量/より小さいモデル（例：Haiku クラス）を使用してください。

サブエージェントディスパッチパラメータ：

• prompt：レンダリングされた qa-engineer-prompt.md
• model：より小さく、より安価なモデル — 弱いほど良い（ギャップを検出できれば、そのギャップは実在するもの）
• description：「Generate questions for {module-name}」

変数：

• {source-dir}、{module-dir}、{module-name}
• {previous_questions}：最初のラウンドは空文字列

QA エンジニアは2つのセットを返します：

• 回答キー付きの検証質問（JSON 配列）
• ユーザー向けの推奨質問（JSON 配列）

推奨質問を保存します（フェーズ 6 のコンテキストに保つ）。ラウンド全体にわたって尋ねられたすべての検証質問を蓄積します。

ステップ 2 — エージェント C / ジュニア開発者（クローズドブック回答）：

junior-dev-prompt.md を使用してサブエージェントをディスパッチします。

サブエージェントディスパッチパラメータ：

• prompt：検証質問が埋め込まれたレンダリングされた junior-dev-prompt.md
• description：「Verify skills for {module-name}」

変数：

• {skill-dir}：{output-dir}/{project-name}-dr-{module-name}/
• {questions}：QA エンジニアからの検証質問（回答キーなし）

ジュニア開発者は各質問への回答を返します。

ステップ 3 — 評価：

独自の推論（メインオーケストレーターとして）を使用してジュニア開発者の回答を評価します： 各質問について、ジュニア開発者の回答をQAエンジニアの required_facts リストと比較します：

• 回答が ALL 必須ファクトをカバーしている場合は PASS（完全一致またはセマンティック同等）
• 必須ファクトを逃している場合は FAIL
• これは主観的な判断ではなく、客観的なチェックです。QA エンジニアとジュニア開発者から JSON 出力を慎重に抽出し、マークダウン形式（json など）は無視してください。

ステップ 4 — ループまたは進む：

厳格なルール：検証質問の 100% が合格するか、正確に 3 ラウンド完了するまで、ループを続ける必要があります。早期終了はありません。合格率 99% はまだ失敗です — 再度ループしてください。

• 100% 合格 → モジュール検証済み、タスク更新、次のモジュールへ
• いずれかの質問が失敗（1つでも）→ 次のラウンドに進む必要があります：
  1. 失敗した質問を収集します：質問、QA エンジニアの回答キー、ジュニア開発者の失敗した回答
  2. テックライターに返します：失敗した質問、QA エンジニアの予想される回答キー、および特定されたギャップを含む {feedback} 変数で再度ディスパッチします。
  3. QA エンジニアとジュニア開発者を再実行し、すべての前のラウンドからのすべての前の質問（{previous_questions} として）を渡すため、QA エンジニアは古い質問を繰り返す代わりに新しい質問を生成します
  4. 再度評価 — 100% または 3 ラウンド完了まで繰り返す
• 正確に 3 ラウンド後に失敗が残っている場合 → 未解決の質問と合格率をユーザーに表示して判断を求めます。静かに進まないでください。

早期停止を正当化しないでください。 「十分」「ほとんどの質問が合格」「収穫逓減」はラウンドをスキップする有効な理由ではありません。ループはギャップをキャッチするために存在します — 必要に応じてすべての 3 ラウンドを使用してください。

3.5 フェーズ 5：グローバルインデックス生成

このフェーズは検証済みのモジュールスキルをグローバルインデックスファイルに統合します。

すべてのモジュールが検証された後、{output-dir}/{project-name}-dr/SKILL.md を生成します：

---
name: {project-name}-dr
description: {project-name} コードベースで作業するときに使用 — 包括的なモジュール知識、設計ロジック、および修正ガイドを提供します（{ref} から生成）
---

コンテンツは以下を含む必要があります：

• リポジトリソース（該当する場合は GitHub URL、またはローカルパス）
• バージョン：タグまたはコミットハッシュ
• 追跡されたブランチ
• 生成タイムスタンプ
• 各モジュールの 1 行説明（モジュールスキルから）
• モジュール間の依存関係（フェーズ 2 スキャンから）
• クロスモジュールシナリオエントリガイド：複数モジュールにまたがる一般的な操作については、関係するモジュールと実行順序を説明します

クロスモジュールシナリオを生成するには、ALL モジュールスキルを読み込み、典型的なユーザーワークフローを合成します。

3.6 フェーズ 6：ユーザー受け入れ

このフェーズは、最終的な検証のためにユーザーに結果を提示します。

フェーズ 4 から収集した推奨質問を提示します：

「スキルが生成および検証されました。テストしたいかもしれない質問は以下の通りです： [推奨質問のリスト]

{project-name} について自由に質問してください。生成されたスキルのみを使用して回答します。」

このフェーズでユーザーの質問に回答する場合：

• {output-dir}/{project-name}-fj*/ の生成されたスキルファイルのみを読み込みます
• ソースコードを読まないでください
• スキルだけから質問に答えられない場合は、正直に言ってください — これはギャップを示します

ユーザーが満足するか、セッションを終了することを決定するまで続けます。

3.7 フェーズ 7：クリーンアップ

この最終フェーズは、必要に応じて一時ファイルのクリーンアップを処理します。

ソースが URL からクローンされた場合（つまり、{output-dir}/{project-name}/ がフェーズ 1 で作成された場合）：

「スキルの準備ができました。クローンされたソースコードは {output-dir}/{project-name}/ にあります。ディスク容量を節約するために削除しますか、それとも参照用に保持しますか？」

• ユーザーが削除と言う → クローンされたディレクトリを削除します
• ユーザーが保持と言う → そのまま残します

ソースがローカルパスの場合はこのフェーズをスキップしてください（クローンは行いませんでした）。

4. 重要なルール

実行プロセス全体を通して以下のルールを厳密に守ってください：

• ソースコードを修正しないでください — ソースリポジトリは全体を通して読み取り専用です
• エージェント分離が重要です — 各エージェントのプロンプトは読み込める内容を厳密に定義します
• スキルは自己完結している必要があります — 検証ループはこれを保証するために存在します
• 進捗を追跡してください — すべてのモジュールはタスクであり、フェーズ全体で更新されます
• ライティングスキル経由でフォーマットしてください — テックライターは superpowers:writing-skills フォーマット規約（frontmatter、CSO 説明、ディレクトリ構造）に従いますが、完全な writing-skills TDD サイクルは実行しません