既存コードベースの引き継ぎ

引き継ぎノートもないままスプリント途中の2年前のコードベースに飛び込むのは、アウトソーシングでは日常茶飯事です。前のチームはいなくなり、クライアントは待っています。ドキュメントといえば、もはや存在しないサーバーを参照している古くなったREADMEだけです。Sun Agent Kitはコードベースを代わりに読み込み、本当に知るべき情報を表示することで、習熟にかかる時間を数日から数時間に短縮します。

概要

目標: 1営業日以内に安全に貢献できるほど、不慣れなコードベースを理解する
所要時間: 1〜2時間（手動でのコード読解は1〜2日）
使用エージェント: scout、researcher、doc-writer
コマンド: /sk:scout、/sk:docs、/sk:graphify、/sk:ask

前提条件

• Sun Agent Kitがインストール済みで認証が完了していること
• リポジトリへの読み取りアクセス（まずローカルにクローンすること）
• ビルド検証用にNode.jsまたはプロジェクトのランタイムが利用可能であること
• 最初に担当する予定のタスクのリスト（Jira、Linear、またはプレーンテキスト）

ステップバイステップのワークフロー

ステップ1：初期スカウトを実行する

/sk:scout "I'm taking over this project. Give me a full orientation: tech stack, architecture, key modules, entry points, known issues in the code, and anything a new developer needs to know before touching anything."

処理内容: エージェントが以下を実行します：

1. リポジトリをインデックス化 — ファイル、言語の内訳、ディレクトリ構造を把握
2. エントリーポイント、サービスモジュール、外部依存関係を識別してアーキテクチャをマッピング
3. TODO/FIXMEコメント、テストカバレッジのないモジュール、バージョンの不一致などのコード健全性シグナルを検出
4. 完全なオリエンテーションレポートを plans/reports/scout-orientation.md に書き出す

ステップ2：ナレッジグラフを構築する

/sk:graphify "map how data flows from a user placing an order to the billing module and the notification emails going out"

処理内容: エージェントが以下を実行します：

1. コントローラー、サービス、統合にまたがる要求されたフローのコールグラフをトレース
2. データコントラクトを識別し、不整合（例：サービス間のフィールド型の不一致）をフラグ
3. Mermaidダイアグラムを生成し、完全なナレッジグラフレポートを plans/reports/ に保存

ステップ3：欠けているドキュメントを再生成する

/sk:docs "generate technical documentation for the auth module, the API endpoints, and the database schema — the existing README is outdated"

処理内容: エージェントが以下を実行します：

1. 要求されたモジュールとマイグレーション履歴のソースファイルを読み込む
2. ルートハンドラーを発見し、リクエスト/レスポンスの形状をドキュメント化
3. 認証フロー、APIエンドポイント、データベーススキーマのドキュメントを書き出す
4. ドキュメント化されたエンドポイントとスキーマを保存前に実際のソースファイルと照合して検証

ステップ4：不慣れな領域について的を絞った質問をする

/sk:ask "how does the billing retry logic work when a Stripe charge fails? What happens to the order status?"

処理内容: エージェントが以下を実行します：

1. 質問に関連するファイルとコールサイトのコードベースを検索
2. バックグラウンドワーカーやキューを含めたエンドツーエンドの実行パスをトレース
3. ソースファイルの引用を含む平易な言葉での回答を合成し、コードを直接掘り下げられるようにする
4. フローをトレース中に検出したエッジケースやギャップをフラグ

ステップ5：最初のタスクをコンテキストの中で理解する

/sk:ask "I need to fix a bug where users aren't receiving order confirmation emails. Walk me through the notification pipeline and where the failure is most likely to be."

処理内容: エージェントが以下を実行します：

1. トリガーイベントからキューとワーカーを通じて配信統合までの通知パイプラインをトレース
2. コードに基づいて最も可能性の高い障害ポイントを特定
3. ソース行の参照を含む調査すべき場所の優先リストを返す

完全な実例：2年前のNode.jsプロジェクトをスプリント途中で引き継ぐ

シナリオ: 月曜日です。クライアントの長期ベンダーがオフボードしました。あなたのチームはNode.js/Reactのeコマースプロジェクトを引き継ぎます。進行中の3チケットのスプリントがあり、カートモジュールにQAリグレッションがあり、クライアントは水曜日にスタンドアップを期待しています。あなたにはまったくコンテキストがありません。

月曜日の朝 — 状況を把握するための2時間:

# 全体オリエンテーション — 何よりもまずこのレポートを読む
/sk:scout "complete orientation for a new engineer taking over this project mid-sprint. Tech stack, architecture, critical modules, test coverage gaps, and any time bombs in the code."

# カートモジュールを詳細にマッピングする — そこにリグレッションがある
/sk:graphify "trace the full data flow through the cart module: add to cart, update quantity, apply coupon, checkout handoff"

# 明らかに古くなっているドキュメントを再生成する
/sk:docs "update README with current stack and setup steps, and generate API docs for the cart and checkout routes"

# 最も差し迫った質問に答える
/sk:ask "there's a regression in cart — coupon codes that previously worked are now returning 400. What changed in the cart or coupon service recently and where should I look first?"

結果: 月曜日の正午までに、詳細なオリエンテーションレポート、カートモジュールのデータフロー図、更新されたドキュメント、そしてリグレッションの有力な根本原因（スキーマ変更でカラムがリネームされたがバリデーションミドルウェアが更新されていなかった）が得られます。すでに修正を提出した状態で水曜日のスタンドアップに臨めます。

時間の比較

ベストプラクティス

1. コードに触れる前にスカウトを実行する ✅

スカウトは全体像を把握させてくれます。アーキテクチャを理解する前にコードを修正すると、見えにくいリグレッションが発生します。必ず先にオリエンテーションを行ってください。

2. /sk:graphify はコードベース全体ではなく特定のフローに使用する ✅

「アプリケーション全体のデータフロー」を求めると圧倒的なグラフが生成されます。ドメインを絞り込んでください：「カート送信から決済確認までのチェックアウトフローをトレースする」。

3. 手動でファイルを読む代わりに /sk:ask で的を絞った質問をする ✅

リトライの仕組みを理解するために12ファイルを開く代わりに、平易な言葉で質問してください。エージェントはソースの行番号を引用するので、必要なときにコードを掘り下げることができます。

4. オリエンテーションなしに「すぐ飛び込む」 ❌

オリエンテーションなしにチケットに直接取り組むと、ロジックの重複、データコントラクトに関する誤った前提、そしてトレースに何日もかかるバグが生じます。スカウトが取る時間は、その後の何時間もの時間を節約します。

5. 生成されたドキュメントを検証せずに信頼する ❌

生成されたドキュメントは正確ですが、絶対確実ではありません。最初のスプリントで最も重要なフローを1つ選び、手動でトレースしてドキュメントを検証してください。1つのフローを信頼できれば、残りも信頼できます。

トラブルシューティング

問題：スカウトレポートが非常に長くてナビゲートしづらい

解決策: 焦点を絞ったサブレポートを求めてください: /sk:scout "focus only on the auth module and the API layer, skip the frontend"。1つの大きなスカウトではなく、複数の的を絞ったスカウトを実行することができます。

問題：/sk:graphify が空または不完全な図を生成する

解決策: トレースは読み取り可能なインポートパスに依存します。プロジェクトがtsconfigで解決されていないパスエイリアス（@/services/billing など）を使用している場合は、先に /sk:ask "list all path aliases in tsconfig and their resolved paths" を実行してください。

問題：/sk:ask が自信を持って間違った回答をする

解決策: 常に回答出力のソース行の引用を確認してください。回答がおかしいと思えば、/sk:scout "re-analyze src/services/billing.ts specifically" を実行して、ファイルに焦点を当てた新鮮な読み込みを行ってください。

問題：生成されたドキュメントが実際のデータベーススキーマと一致しない

解決策: スキーマドキュメントの生成はマイグレーションファイルを読み込みます。マイグレーションが順不同で適用されたり、ローカル環境でスキップされたりした場合、ずれが生じます。/sk:ask "list all migration files and their applied status" を実行して不整合を表面化させてください。

次のステップ

• バグを体系的に修正 — オンボーディング後の最初のタスクはリグレッションやバグ修正であることが多い
• 新機能を追加 — コードベースを理解したら、自信を持って機能を追加する
• 新しいプロジェクトを開始 — ブラウンフィールドを引き継ぐ代わりにグリーンフィールドで構築する場合

重要なポイント: 他人のコードをコールドで読むのに1日以上費やすべきではありません。/sk:scout と /sk:graphify は、2日間の辛いコード考古学を2時間の構造化されたオリエンテーションに変えます。