docs: rebrand to GSD Core and restructure docs with Diataxis (#605)

* chore: wire docs/agents config into AGENTS.md Agent skills section Add the `## Agent skills` discovery block pointing the engineering skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md files (issue tracker, triage label mapping, single-context domain docs). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rebrand to GSD Core and restructure docs with Diataxis Reorganise the root README and docs/ around the Diataxis framework (tutorials, how-to guides, reference, explanation), add new how-to guides and schema references (STATE.md / CONTEXT.md / PLAN.md / planning artifacts), and cross-link the whole set. Update the lone legacy gsd-build reference to open-gsd; keep internal get-shit-done/ filesystem paths unchanged (directory rename tracked separately in open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN localised trees to mirror the new structure. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: backfill changeset PR number (#605) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-02 08:13:09 -04:00
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions
--- a/docs/ja-JP/tutorials/onboarding-an-existing-codebase.md
+++ b/docs/ja-JP/tutorials/onboarding-an-existing-codebase.md
@@ -0,0 +1,226 @@
+# 既存コードベースのオンボーディング
+
+このチュートリアルでは、すでにコードが存在するリポジトリに GSD Core を導入します。コードベースをマッピングし、*追加する*内容を説明するプロジェクトを作成して、小さな変更に対して最初の議論・計画サイクルを実行します。最終的に、GSD Core の計画パイプラインがあなたのスタック、規約、懸念事項を把握し、計画するたびにその知識を活用できる状態になります。
+
+---
+
+## 作るもの
+
+既存の Express アプリケーションに `GET /health` エンドポイントを1つ追加します。変更は小さく、本来のレッスン — GSD Core が計画前にコードベースを学習する仕組み — から注意がそれることはありません。
+
+---
+
+## 前提条件
+
+- **Node.js 18 以降** — `node --version` が `v18.x.x` 以上を表示すること。
+- **既存のプロジェクト** — コードがすでに存在する任意のリポジトリ。Express である必要はなく、手順はあらゆるスタックに適用されます。
+- **Claude Code** — リポジトリのルートで開いていること。
+
+---
+
+## ステップ 1 — GSD Core のインストール
+
+リポジトリのルートで以下を実行します:
+
+```bash
+npx @opengsd/gsd-core@latest
+```
+
+プロンプトが表示されたら **Claude Code** と **local** を選択してください。以下が表示されます:
+
+```text
+✓ Installed 86 skills to .claude/commands/
+✓ Installed agents to .claude/agents/
+✓ GSD Core ready — run /gsd-new-project to start
+```
+
+---
+
+## ステップ 2 — 権限フラグ付きで Claude Code を起動
+
+```bash
+claude --dangerously-skip-permissions
+```
+
+---
+
+## ステップ 3 — コードベースのマッピング
+
+プロジェクトを作成する前に、GSD Core に既存のコードを学習させてください。これがブラウンフィールドの計画を正確にするステップです。
+
+```text
+/gsd-map-codebase
+```
+
+GSD Core が4つの並行マッパーサブエージェントを生成します（「Spawning 4 parallel codebase mapper agents…」という通知が表示されます。1〜5分かかりますので中断しないでください）。各エージェントはそれぞれ異なる観点に注目します:
+
+| エージェント | 観点 |
+|-------|-------|
+| Tech mapper | スタック、フレームワーク、依存関係 |
+| Architecture mapper | パターン、レイヤー、データフロー |
+| Quality mapper | 規約、テスト慣行 |
+| Concerns mapper | 技術的負債、リスクエリア |
+
+4つすべてが完了すると、以下が表示されます:
+
+```text
+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 — コンテキストをクリアしてプロジェクトを作成
+
+セッションウィンドウをクリアします:
+
+```text
+/clear
+```
+
+プロジェクトを作成します。前のステップで GSD Core が既存のコードを見つけているため、これがブラウンフィールドプロジェクトであることをすでに把握しています。`/gsd-new-project` を実行すると、既存のものを再説明するのではなく、*追加する*内容に焦点を当てた質問がされます:
+
+```text
+/gsd-new-project
+```
+
+GSD Core が何を作りたいかを尋ねます。コードベース全体の説明ではなく、追加する機能で答えてください:
+
+```text
+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フェーズになります:
+
+```text
+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/` に作成されるファイル:**
+
+```text
+.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 を議論
+
+```text
+/clear
+```
+
+```text
+/gsd-discuss-phase 1
+```
+
+GSD Core があなたの `CONVENTIONS.md` と `ARCHITECTURE.md` を読み込んでいるため、質問は汎用的なアドバイスではなく、実際のコードベースに基づいています。以下のような内容が表示される場合があります:
+
+```text
+> 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 が以下のファイルを書き込みます:
+
+```text
+.planning/phases/01-health-endpoint/CONTEXT.md
+```
+
+そのファイルを開いてください。`## Implementation Decisions` セクションにあなたの回答が記録されています。プランナーはタスクを1つも書く前にこのファイルを読み込みます。ファイルの配置やレスポンス形状に関するあなたの好みがプランに反映されます。
+
+---
+
+## ステップ 6 — フェーズ 1 の計画
+
+```text
+/gsd-plan-phase 1
+```
+
+4つのリサーチサブエージェントが並行して実行されます（1〜5分）。完了すると、プランナーが `CONTEXT.md`、リサーチ結果、コードベースマップを読み込み、あなたの規約に合ったタスクプランを作成します。
+
+**作成されるファイル:**
+
+```text
+.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 がコードベースマップで観察したルーティングパターンと一致しています。これがコードベースマップの効果です。
+
+---
+
+## 次のステップ
+
+コードベースマップ、議論の意思決定記録、検証済みタスクプランが揃ったプロジェクトができました。すべてが実際のコードに基づいています。ここからのワークフローはグリーンフィールドプロジェクトと同じです:
+
+```text
+/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
+
+- [はじめてのプロジェクト](your-first-project.md) — インストールから PR まで完全なグリーンフィールドループ
+- [コマンドによるコードベースマッピング](../COMMANDS.md) — `/gsd-map-codebase` のすべてのフラグとサブコマンド
+- [ドキュメントインデックス](../README.md)