msd-core/docs/ja-JP/tutorials/onboarding-an-existing-codebase.md

既存コードベースのオンボーディング

このチュートリアルでは、すでにコードが存在するリポジトリに GSD Core を導入します。コードベースをマッピングし、追加する内容を説明するプロジェクトを作成して、小さな変更に対して最初の議論・計画サイクルを実行します。最終的に、GSD Core の計画パイプラインがあなたのスタック、規約、懸念事項を把握し、計画するたびにその知識を活用できる状態になります。

---

作るもの

既存の Express アプリケーションに GET /health エンドポイントを1つ追加します。変更は小さく、本来のレッスン — GSD Core が計画前にコードベースを学習する仕組み — から注意がそれることはありません。

---

前提条件

• Node.js 18 以降 — node --version が v18.x.x 以上を表示すること。
• 既存のプロジェクト — コードがすでに存在する任意のリポジトリ。Express である必要はなく、手順はあらゆるスタックに適用されます。
• Claude Code — リポジトリのルートで開いていること。

---

ステップ 1 — GSD Core のインストール

リポジトリのルートで以下を実行します:

npx @opengsd/gsd-core@latest

プロンプトが表示されたら Claude Code と local を選択してください。以下が表示されます:

✓ Installed 86 skills to .claude/commands/
✓ Installed agents to .claude/agents/
✓ GSD Core ready — run /gsd-new-project to start

---

ステップ 2 — 権限フラグ付きで Claude Code を起動

claude --dangerously-skip-permissions

---

ステップ 3 — コードベースのマッピング

プロジェクトを作成する前に、GSD Core に既存のコードを学習させてください。これがブラウンフィールドの計画を正確にするステップです。

/gsd-map-codebase

GSD Core が4つの並行マッパーサブエージェントを生成します（「Spawning 4 parallel codebase mapper agents…」という通知が表示されます。1〜5分かかりますので中断しないでください）。各エージェントはそれぞれ異なる観点に注目します:

エージェント	観点
Tech mapper	スタック、フレームワーク、依存関係
Architecture mapper	パターン、レイヤー、データフロー
Quality mapper	規約、テスト慣行
Concerns mapper	技術的負債、リスクエリア

4つすべてが完了すると、以下が表示されます:

Codebase mapping complete.

Created .planning/codebase/:
- STACK.md        (47 lines) - Technologies and dependencies
- ARCHITECTURE.md (62 lines) - System design and patterns
- STRUCTURE.md    (38 lines) - Directory layout and organisation
- CONVENTIONS.md  (55 lines) - Code style and patterns
- TESTING.md      (41 lines) - Test structure and practices
- INTEGRATIONS.md (29 lines) - External services and APIs
- CONCERNS.md     (33 lines) - Technical debt and issues

.planning/codebase/STACK.md を開いてください。GSD Core が検出した言語、ランタイム、フレームワークのバージョン、主要な依存関係が表示されます。これは推測ではなく、実際に読み込んだファイルに基づいています。

.planning/codebase/CONVENTIONS.md を開いてください。ソースコードから観察した命名規則、エラーハンドリングパターン、コードスタイルのルールが表示されます。このリポジトリで GSD Core が生成するすべてのプランは、これらの規約に自動的に従います。

.planning/codebase/CONCERNS.md を開いてください。新機能の作業前に読む最も有用なファイルです。計画に影響しうる技術的負債や脆弱なエリアが表面化されています。

---

ステップ 4 — コンテキストをクリアしてプロジェクトを作成

セッションウィンドウをクリアします:

/clear

プロジェクトを作成します。前のステップで GSD Core が既存のコードを見つけているため、これがブラウンフィールドプロジェクトであることをすでに把握しています。/gsd-new-project を実行すると、既存のものを再説明するのではなく、追加する内容に焦点を当てた質問がされます:

/gsd-new-project

GSD Core が何を作りたいかを尋ねます。コードベース全体の説明ではなく、追加する機能で答えてください:

Add a GET /health endpoint to the Express app. It should return
{ "status": "ok", "uptime": <seconds> }. We'll use it for load-balancer
health checks.

GSD Core が少数の確認質問をした後、要件とロードマップの作成に進みます。すでに ARCHITECTURE.md と STACK.md を読み込んでいるため、既存の機能を PROJECT.md の Validated セクションに自動的にマッピングします。既存の API サーフェスを説明する必要はありません。

すべてのワークフロー設定は推奨デフォルトを選択してください。

ロードマッパーのサブエージェントが完了すると、提案されたロードマップが表示されます。単一の小さな変更の場合は1フェーズになります:

Proposed Roadmap

1 phase | 2 requirements mapped | All v1 requirements covered ✓

| # | Phase          | Goal                                          | Requirements |
|---|----------------|-----------------------------------------------|--------------|
| 1 | Health endpoint| GET /health returning status and uptime JSON  | HLT-01, HLT-02 |

ロードマップを承認してください。

.planning/ に作成されるファイル:

.planning/
  PROJECT.md          ← プロジェクトの説明; 「Validated」に既存機能
  REQUIREMENTS.md     ← HLT-01, HLT-02
  ROADMAP.md          ← フェーズ 1、ステータス: pending
  STATE.md            ← セッションメモリ
  config.json         ← ワークフロー設定
  codebase/           ← ステップ 3 の7つのマップファイル

.planning/codebase/ はすでにステップ 3 から存在しています。GSD Core は PROJECT.md を書く際にこれらのファイルを読み込んでいるため、あなたが説明しなくても Validated 要件を入力できたのです。

---

ステップ 5 — コンテキストをクリアしてフェーズ 1 を議論

/clear

/gsd-discuss-phase 1

GSD Core があなたの CONVENTIONS.md と ARCHITECTURE.md を読み込んでいるため、質問は汎用的なアドバイスではなく、実際のコードベースに基づいています。以下のような内容が表示される場合があります:

> Your routes are registered in src/routes/index.js. Should the health
  endpoint live there, or in a dedicated src/routes/health.js?
  A dedicated health.js — keep routes separated.

> Your existing error middleware returns { error: "message" }. Should
  /health use the same shape for error responses?
  Yes, stay consistent.

> Should uptime be calculated from process.uptime() or a stored start time?
  process.uptime() is fine.

議論が終了すると、GSD Core が以下のファイルを書き込みます:

.planning/phases/01-health-endpoint/CONTEXT.md

そのファイルを開いてください。## Implementation Decisions セクションにあなたの回答が記録されています。プランナーはタスクを1つも書く前にこのファイルを読み込みます。ファイルの配置やレスポンス形状に関するあなたの好みがプランに反映されます。

---

ステップ 6 — フェーズ 1 の計画

/gsd-plan-phase 1

4つのリサーチサブエージェントが並行して実行されます（1〜5分）。完了すると、プランナーが CONTEXT.md、リサーチ結果、コードベースマップを読み込み、あなたの規約に合ったタスクプランを作成します。

作成されるファイル:

.planning/phases/01-health-endpoint/
  RESEARCH.md         ← ヘルスエンドポイントパターンに関する調査結果
  01-01-PLAN.md       ← タスク: src/routes/health.js の作成
  01-02-PLAN.md       ← タスク: src/routes/index.js へのヘルスルートの登録

01-01-PLAN.md を開いてください。<files> タグが src/routes/health.js を参照していることに注目してください。これは議論で指定した正確なパスであり、GSD Core がコードベースマップで観察したルーティングパターンと一致しています。これがコードベースマップの効果です。

---

次のステップ

コードベースマップ、議論の意思決定記録、検証済みタスクプランが揃ったプロジェクトができました。すべてが実際のコードに基づいています。ここからのワークフローはグリーンフィールドプロジェクトと同じです:

/gsd-execute-phase 1
/gsd-verify-work 1
/gsd-ship 1

今後の機能追加ごとに、構造が大幅に変わった際は /gsd-map-codebase を再実行してコードベースマップを最新の状態に保ってください。

---

学んだこと

• /gsd-map-codebase が4つの並行エージェントを実行して .planning/codebase/ に STACK.md、ARCHITECTURE.md、CONVENTIONS.md、CONCERNS.md、STRUCTURE.md、TESTING.md、INTEGRATIONS.md を生成する仕組み。
• ブラウンフィールドリポジトリで /gsd-new-project を実行すると、追加する内容に焦点を当てた質問がされ、既存コードから Validated 要件が自動入力される仕組み。
• コードベースマップが /gsd-discuss-phase のすべての質問を形成する方法 — ファイルパス、パターン、規約が実際のコードから導出される。
• プランナーが CONTEXT.md と CONVENTIONS.md を読み込んでリポジトリのスタイルに合ったプランを生成する仕組み。

---

Related

• はじめてのプロジェクト — インストールから PR まで完全なグリーンフィールドループ
• コマンドによるコードベースマッピング — /gsd-map-codebase のすべてのフラグとサブコマンド
• ドキュメントインデックス