contextualizar-repo

リポジトリのコンテキスト化（ブラウンフィールド）

目的

既存システムをグリーンフィールドと同じ状態にします。後から参加するエージェントや人が、起動方法、構築方法、引き継がれている決定事項、踏襲すべきパターンと避けるべきパターン、技術的負債の場所、変更時に守るべきルールを見つけられるようにします。

このスキルでは技術的コンテキスト（レイヤー1、2、5）を扱います。機能的コンテキスト（機能、ビジネスルール、用語集）は、BA が contextualizar-negocio で文書化します。

このスキルはコードを変更せず、技術的負債も解消しません。 読み取り、測定、文書化、質問を行い、そこで停止します。

原則

1. 根拠のない記述はしません。 システムに関するすべての記述には ファイル:行、出力を伴うコマンドを添えるか、未検証 と明記します。
2. 既存のドキュメントは情報源であり、正解とは限りません。 README、AGENTS.md、CLAUDE.md、既存の docs を読み、再利用する各記述をコードと照合して検証します。
3. コードのあるがままを記述し、あるべき姿は記述しません。 改善案は技術的負債のマップに記載し、システムの説明に混在させません。
4. 新たなアーキテクチャ上の決定は行いません。 引き継がれている決定事項を文書化します。複数のパターンが併存する場合、どれを標準とするかは人が確認します。

入力

• リポジトリのパス（既定では現在のディレクトリ）。
• 既存のドキュメントがあれば、その内容：README*、AGENTS.md、CLAUDE.md、docs/、既存の ADR。
• 任意：チームが特に重視するシステムの部分（その部分を優先して詳しく調べます）。

ワークフロー

1. 読み解ける状態にする（レイヤー1）

1. インストール、起動、テストの方法を確認します。対象は package.json（または同等のファイル）、README、Dockerfile、docker-compose*、既存のドキュメントです。
2. 各コマンドを検証します。 ユーザーの許可があれば実行し、結果と所要時間を記録します。実行しない場合は 未検証 と明記します。
3. CodeGraph のインデックス：
   • codegraph がインストール済みの場合は、codegraph init（すでに .codegraph/ が存在する場合は codegraph index）を実行し、所要時間を記録します。
   • インストールされていない場合は、現行のドキュメントを参照してインストールを提案し、CodeGraph を使わずに続行します。その際、コードを読み取って依存関係マップを作成したことを明記します。
   • 後続のステップでは、依存関係、影響範囲、呼び出し元の確認にインデックスを使います。

2. 実際のレイヤーマップ（レイヤー2）

1. フォルダー構成を確認し、それぞれに観察された役割を割り当てます。
2. 典型的なフローをエンドツーエンドで追跡します（リクエストが入ってからデータにアクセスするまで）。その際に通過する各ファイルを記録し、この追跡を通じてマップを検証します。
3. レイヤーが2世代存在する箇所を示します（たとえば、旧フロントエンドと新フロントエンド）。

3. 引き継がれている決定事項（レイヤー2）

1. 永続化、拡張の仕組み、通信プロトコル、認証、モジュール構成、テスト戦略など、すでに採用されている構造上の決定事項を特定します。
2. assets/adr-heredado-template.md（または generar-tech-design がインストールされている場合は、そのテンプレート）を使い、各決定事項について、ステータスを 承認済み（引き継ぎ） とする ADR を作成します。adrs/ で次に使える番号から採番します。
3. 決定事項には、コードがすでに行っていることを根拠とともに記載します。影響には、その決定によって現在生じている実際のコストを少なくとも1つ含めます。

4. パターンカタログ（レイヤー 2）

各関連テーマ（エンドポイントまたはルートの追加方法、データアクセス、エラー処理、 設定、依存関係、テスト、モジュール構成、表示テキスト、拡張）について：

1. そのテーマを解決する異なる方法がいくつ共存しているかを、各方法の ファイル:行 の例とおおよその使用数とともに特定します。
2. **規範（模倣する）とレガシー（模倣しない）**のどちらに当たるかを提案し、 判断基準を明示します。基準は、プロジェクトのドキュメントで推奨されている方法、 最も新しいコードで使われている方法、または新しいコードで多数派の方法とします。
3. 明確な基準がない場合は、選択しません。人間への質問として残します。
4. 依存関係の接続方法（注入するか、直接インポートするか）と、それがコードのテストの しやすさにどのような影響を与えるかを明示的に記載します。

5. 技術的負債のマップ（レイヤー 2）

各発見事項を修正せずに、ID、説明、根拠、リスク（高・中・低）、対処するのが 望ましい時期（通常は、その箇所に機能を追加するとき）とともに記録します。

最低限、以下を調査します。

• 非常に大きいファイルや、責務が多すぎるモジュール。
• 同じ処理を行う重複した経路。
• 削除できないレガシー互換性。
• チーム自身が宣言している負債（TODO、FIXME、HACK）。
• 弱い型付け、または欠けているバリデーション。
• CodeGraph が利用可能な場合は、多数のファイルが依存することによる強い結合。

**パフォーマンス：**計測候補としてのみ記録し、計測なしにバグと断定してはいけません。

6. 構築ルール（レイヤー 5）

規範と引き継いだ ADR からルールを導き出します。各ルールには以下を含めます。

• 記述（「新しい機能はプラグインとして実装する」）。
• 出典（ADR、規範パターン、またはプロジェクトのドキュメント）。
• 確認方法：コマンド、ツール、または既存のテスト。

ルールを確認する方法がない場合は、ソフトルールとしてマークし、確認方法 （lint、テスト、または crear-guardrail によるガードレール）を提案します。ただし、 作成はしません。

7. 記述

ファイル	内容	テンプレート
docs/contexto/ARQUITECTURA.md	起動とテストの確認結果、レイヤーマップ、エンドツーエンドのフロー	assets/arquitectura-template.md
docs/contexto/PATRONES.md	規範とレガシーのカタログ	assets/patrones-template.md
docs/contexto/DEUDA.md	技術的負債のマップ	assets/deuda-template.md
adrs/NNNN-*.md	引き継いだ決定事項	assets/adr-heredado-template.md
AGENTS.md	簡潔な索引＋構築ルール	assets/agents-md-template.md

• AGENTS.md がすでに存在する場合は、上書きしません。変更案を提示し、人間が判断します。
• AGENTS.md には、用語集と機能一覧への入口として docs/contexto/ を指定します。 これらのファイルは BA が完成させる場合もあります。

8. 自己検証

提示する前に、以下を実施します。

• 引用した各 ファイル:行 を再度開き、記述内容と一致することを確認します。
• ドキュメントに記載した各コマンドが実行済みであること、または NO VERIFICADO とマークされていることを確認します。
• 改善案が説明であるかのように記述されていないことを確認します。

人間には、クリーンなセッションから、できれば別のモデルを使って audit-agent-context を実行し、コンテキストが自分自身を検証しないようにする クロスレビューを推奨します。

9. 人間によるゲート

概要と、保留中の判断事項を提示します。

• 複数のパターンがある各テーマで確認が必要な規範。
• ソフトルールと、その確認方法の提案。
• NO VERIFICADO とマークされたすべての項目。

**明示的な承認を待ちます。**人間が承認する前に、このコンテキストを使用したり、 他のエージェントに伝えたりしてはいけません。

10. BA との連携

セッションに BA がいる場合（invoke-agent を参照）、承認後に次の作業を行います。

• CONTEXTO TÉCNICO LISTO: <rutas de docs/contexto y adrs> — <puntos abiertos> を送信します。
• BA から GLOSARIO: TÉRMINOS NUEVOS が届いたら、docs/contexto/GLOSARIO.md の各用語の「Dónde vive」列に根拠を添えて記入し、GLOSARIO COMPLETO と返信します。
• 同じ意見の相違についてのやり取りは最大 2 回までです。その後は人間が判断します。

制約

• プロジェクトのコード、設定、依存関係は変更しません。
• 些細なものであっても、技術的負債は修正しません。
• 判断基準が明確でない場合、正準となるものを選ばず、質問します。
• 承認なしに既存のドキュメントを上書きしません。
• 人間によるゲートの前に、ほかのエージェントと連絡を取りません。