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)
--- a/docs/ja-JP/tutorials/your-first-project.md
+++ b/docs/ja-JP/tutorials/your-first-project.md
@@ -0,0 +1,291 @@
+# はじめてのプロジェクト
+
+このチュートリアルでは、GSD Core をインストールし、シンプルなコマンドライン To-Do アプリをゼロから作成します。1フェーズ、1プルリクエスト、完全なループを体験します。終わる頃には、コアフェーズループのすべてのコマンドを少なくとも一度は実行し、各コマンドが生成する計画アーティファクトを確認しているはずです。
+
+---
+
+## 作るもの
+
+To-Do アイテムをローカルの JSON ファイルに保存し、追加・一覧表示・完了マークができる Node.js CLI ツールです。1セッションで完成できる小さなプロジェクトで、Node.js 標準ライブラリのみを使用するため、追加インストールは不要です。
+
+---
+
+## 前提条件
+
+- **Node.js 18 以降** — `node --version` が `v18.x.x` 以上を表示すること。
+- **Claude Code** — 使用するプロジェクトディレクトリで開いていること。
+- 初回インストール用のインターネット接続。
+
+他のツールは不要です。GSD Core 自体は次のステップでインストールします。
+
+---
+
+## ステップ 1 — GSD Core のインストール
+
+プロジェクトディレクトリでターミナルを開き、以下を実行します:
+
+```bash
+npx @opengsd/gsd-core@latest
+```
+
+インストーラーが、使用している AI コーディングランタイムとグローバルインストールかカレントプロジェクトへのインストールかを確認します。今は **Claude Code** と **local**（このプロジェクトのみ）を選択してください。
+
+以下のような出力が表示されます:
+
+```text
+✓ Installed 86 skills to .claude/commands/
+✓ Installed agents to .claude/agents/
+✓ GSD Core ready — run /gsd-new-project to start
+```
+
+プロジェクト内に `.claude/` ディレクトリが作成されます。これが GSD Core のコマンドとエージェントの格納場所です。
+
+> ローカルとグローバルの違いについて: ローカルインストールはスキルのバージョンをこのプロジェクトに固定します。グローバルインストールを行う場合は、[ランタイムへのインストール](../how-to/install-on-your-runtime.md) を参照してください。
+
+---
+
+## ステップ 2 — 権限フラグ付きで Claude Code を起動
+
+GSD Core は、ファイルの読み書きを行うサブエージェントを生成します。すべてのファイル操作に対して確認を求められないよう、権限フラグを付けて Claude Code を起動してください:
+
+```bash
+claude --dangerously-skip-permissions
+```
+
+プロジェクトディレクトリで Claude Code のプロンプトが表示されます。
+
+---
+
+## ステップ 3 — プロジェクトの作成
+
+Claude Code のプロンプトで以下のスラッシュコマンドを入力します:
+
+```text
+/gsd-new-project
+```
+
+GSD Core が会話を開始し、最初に1つの質問をします:
+
+```text
+What do you want to build?
+```
+
+以下のように入力してください:
+
+```text
+A Node.js CLI tool for managing to-do items. Users run `todo add "buy milk"`,
+`todo list`, and `todo done 1`. Items are saved to a local todos.json file.
+No external dependencies — Node built-ins only.
+```
+
+GSD Core がいくつかの確認事項について質問します。自然に答えてください。1つのプランも書く前に、あなたの意図を理解しようとしています。
+
+質問が終わると、ドメインリサーチの実行を提案します。この規模のプロジェクトであればリサーチをスキップできます。プロンプトが表示されたら **Skip research** を選択してください。
+
+次に GSD Core がワークフロー設定（モード、粒度、リサーチエージェント）を選択するよう求めます。それぞれ推奨デフォルトを選択してください。これらの設定は `.planning/config.json` に書き込まれます。
+
+最後に、ロードマッパーのサブエージェントが実行されます（「Spawning roadmapper…」という通知が表示されますが、これは正常です。約1分かかります）。完了すると、GSD Core が提案するロードマップを提示します。単一フェーズのプロジェクトでは次のようになります:
+
+```text
+Proposed Roadmap
+
+1 phase | 4 requirements mapped | All v1 requirements covered ✓
+
+| # | Phase              | Goal                                    | Requirements      |
+|---|--------------------|-----------------------------------------|-------------------|
+| 1 | Core CLI           | add / list / done commands, todos.json  | CLI-01 … CLI-04   |
+```
+
+**Approve** と入力してロードマップを承認してください。
+
+**`.planning/` に作成されるファイル:**
+
+```text
+.planning/
+  PROJECT.md          ← プロジェクトの説明と要件
+  REQUIREMENTS.md     ← すべての v1 機能の REQ-ID
+  ROADMAP.md          ← フェーズ 1、ステータス: pending
+  STATE.md            ← セッションメモリ、現在位置
+  config.json         ← ワークフロー設定
+```
+
+今すぐ `.planning/ROADMAP.md` を開いて読んでください。フェーズ 1 にはゴール、満たすべき要件のリスト、成功基準が含まれています。成功基準とは、実行によって達成すべき観測可能な動作です。
+
+---
+
+## ステップ 4 — コンテキストをクリアしてフェーズ 1 を議論
+
+GSD Core はフレッシュなコンテキストを前提に設計されています。各フェーズの前にメインセッションウィンドウをクリアしてください:
+
+```text
+/clear
+```
+
+次に、フェーズ 1 の議論を開始します:
+
+```text
+/gsd-discuss-phase 1
+```
+
+GSD Core がフェーズのゴールを読み取り、実装の方針について質問します。これは「何を」作るかではなく、「どのように」作るかを決める質問です。会話の例:
+
+```text
+> How should done items be stored — mark them in place or move them?
+  Mark them in place with a "done" flag.
+
+> Should `todo list` show completed items by default?
+  No, hide them unless --all is passed.
+
+> Error format when todos.json doesn't exist yet?
+  Create it silently on first add.
+```
+
+議論が終了すると、GSD Core が以下のファイルを書き込みます:
+
+```text
+.planning/phases/01-core-cli/CONTEXT.md
+```
+
+そのファイルを開いてください。`## Implementation Decisions` セクションに、あなたが述べた内容が正確に記録されています。プランナーはこのファイルを読み込みます。ここで行った決定はすべてのタスクプランに反映されます。
+
+---
+
+## ステップ 5 — フェーズ 1 の計画
+
+```text
+/gsd-plan-phase 1
+```
+
+4つのリサーチサブエージェントが並行して実行されます（「Spawning 4 researchers…」という通知が表示されます。1〜5分かかります。中断しないでください）。
+
+完了すると、プランナーが CONTEXT.md とリサーチ結果を読み込み、アトミックなタスクプランを作成します。次に、プランチェッカーが各プランがフェーズのゴールを達成しているか検証してから保存します。
+
+**作成されるファイル:**
+
+```text
+.planning/phases/01-core-cli/
+  RESEARCH.md         ← ドメイン調査の結果
+  01-01-PLAN.md       ← タスク: todos.json の読み書きヘルパーの作成
+  01-02-PLAN.md       ← タスク: add / list / done コマンドの実装
+```
+
+`01-01-PLAN.md` を開いてください。タスク名、対象ファイル、アクションステップ、検証コマンド、完了条件が含まれた `<task>` ブロックがあります。`<verify>` タグに注目してください。GSD Core のエグゼキューターはコードを書いた後にそのコマンドを実行します。
+
+---
+
+## ステップ 6 — フェーズ 1 の実行
+
+```text
+/gsd-execute-phase 1
+```
+
+GSD Core はプランをウェーブ（独立したプランが並行実行される単位）にグループ化し、プランごとに新しい 200k コンテキストのエグゼキューターを生成し、各タスクをアトミックにコミットします。
+
+以下のような出力が表示されます:
+
+```text
+Wave 1 (parallel):
+  [Executor A] → 01-01-PLAN.md (read/write helpers)   ✓ committed
+  [Executor B] → 01-02-PLAN.md (CLI commands)          ✓ committed
+
+[Verifier] Checking codebase against phase goals...
+  CLI-01 todo add   ✓
+  CLI-02 todo list  ✓
+  CLI-03 todo done  ✓
+  CLI-04 --all flag ✓
+  Status: PASS
+```
+
+**作成されるファイル:**
+
+```text
+.planning/phases/01-core-cli/
+  01-01-SUMMARY.md    ← Executor A がビルドしてコミットした内容
+  01-02-SUMMARY.md    ← Executor B がビルドしてコミットした内容
+  VERIFICATION.md     ← 要件カバレッジ: PASS
+```
+
+CLI を実行してみましょう:
+
+```bash
+node todo.js add "buy milk"
+node todo.js add "write tests"
+node todo.js list
+node todo.js done 1
+node todo.js list
+```
+
+アイテムが表示され、完了マークを付けた後にアイテム 1 がデフォルトリストから消えているはずです。これが GSD Core によって実現された最初の成果です。
+
+---
+
+## ステップ 7 — 成果物の検証
+
+```text
+/gsd-verify-work 1
+```
+
+GSD Core がフェーズの成功基準を抽出し、それぞれについて確認します:
+
+```text
+[1/3] Can you run `node todo.js add "buy milk"` without errors?
+> yes
+
+[2/3] Does `node todo.js list` show only incomplete items by default?
+> yes
+
+[3/3] Does `node todo.js done 1` mark item 1 complete and hide it from the default list?
+> yes
+
+All 3 checks passed. Phase 1 verified.
+```
+
+いずれかのチェックが失敗した場合、GSD Core が根本原因を診断して修正プランを作成します。`/gsd-execute-phase 1` を再度実行して修正を適用し、その後 `/gsd-verify-work 1` を再実行してください。
+
+**作成されるファイル:**
+
+```text
+.planning/phases/01-core-cli/UAT.md   ← すべてのチェックとその結果
+```
+
+---
+
+## ステップ 8 — リリース
+
+```text
+/gsd-ship 1
+```
+
+GSD Core が自動生成された本文付きのプルリクエストを作成します。PR の本文には常に Summary、Changes、Requirements Addressed、Verification、Key Decisions が含まれます。
+
+以下のような出力が表示されます:
+
+```text
+Pull request created: https://github.com/your-org/your-repo/pull/1
+
+Title: feat(phase-1): core CLI — add / list / done commands
+```
+
+これが1つのフェーズにおける完全なループです。アイデアからマージされた PR まで。
+
+---
+
+## 学んだこと
+
+- `npx @opengsd/gsd-core@latest` を使った GSD Core のインストール方法。
+- `/gsd-new-project` が会話を `.planning/` アーティファクトに裏付けられたロードマップに変換する仕組み。
+- `/gsd-discuss-phase` が計画前に実装の意思決定を記録する仕組み。
+- `/gsd-plan-phase` が並行リサーチャーを生成してアトミックなタスクプランを作成する仕組み。
+- `/gsd-execute-phase` がプランを並行ウェーブで実行し各タスクをコミットする仕組み。
+- `/gsd-verify-work` が成功基準を確認し、必要に応じて修正プランを生成する仕組み。
+- `/gsd-ship` が検証済みフェーズをプルリクエストに変換する仕組み。
+
+マルチフェーズプロジェクトの場合は、各フェーズでステップ 4〜8 を繰り返し、`/gsd-progress --next` を実行して GSD Core に次のステップを自動検出させてください。
+
+---
+
+## Related
+
+- [フェーズループ](../explanation/the-phase-loop.md) — ループがこの形状である理由
+- [ハウツーガイド](../README.md#how-to-guides) — 特定の状況に対応したタスク重視のレシピ
+- [既存コードベースのオンボーディング](onboarding-an-existing-codebase.md) — ブラウンフィールドリポジトリへの GSD Core の導入