golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
* 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>
This commit is contained in:
Tom Boucher
2026-06-02 08:13:09 -04:00
committed by GitHub
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions
Download Patch File Download Diff File Expand all files Collapse all files

337
docs/ja-JP/ARCHITECTURE.md
View File

@@ -1,30 +1,30 @@
# GSD アーキテクチャ
# GSD Core アーキテクチャ
> コントリビューターおよび上級ユーザー向けのシステムアーキテクチャ文書です。ユーザー向けドキュメントは[機能リファレンス](FEATURES.md)または[ユーザーガイド](USER-GUIDE.md)をご覧ください。
> コントリビューターおよび上級ユーザー向けのシステムアーキテクチャ文書です。ユーザー向けドキュメントは [機能リファレンス](FEATURES.md) または [ユーザーガイド](USER-GUIDE.md) をご覧ください。
---
## 目次
- [システム概要](#システム概要)
- [設計原則](#設計原則)
- [コンポーネントアーキテクチャ](#コンポーネントアーキテクチャ)
- [エージェントモデル](#エージェントモデル)
- [データフロー](#データフロー)
- [ファイルシステムレイアウト](#ファイルシステムレイアウト)
- [インストーラーアーキテクチャ](#インストーラーアーキテクチャ)
- [フックシステム](#フックシステム)
- [CLIツールレイヤー](#cliツールレイヤー)
- [ランタイム抽象化](#ランタイム抽象化)
- [システム概要](#system-overview)
- [設計原則](#design-principles)
- [コンポーネントアーキテクチャ](#component-architecture)
- [エージェントモデル](#agent-model)
- [データフロー](#data-flow)
- [ファイルシステムレイアウト](#file-system-layout)
- [インストーラーアーキテクチャ](#installer-architecture)
- [フックシステム](#hook-system)
- [CLI ツールレイヤー](#cli-tools-layer)
- [ランタイム抽象化](#runtime-abstraction)
---
## システム概要
GSDは、ユーザーとAIコーディングエージェント（Claude Code、Gemini CLI、OpenCode、Kilo、Codex、Copilot、Antigravity、Trae、Cline、Augment Code）の間に位置する**メタプロンプティングフレームワーク**です。以下の機能を提供します：
GSD Core は、ユーザーと AI コーディングエージェント（Claude Code、Gemini CLI、OpenCode、Kilo、Codex、Copilot、Antigravity、Trae、Cline、Augment Code）の間に位置する **メタプロンプティングフレームワーク** です。以下の機能を提供します：
1. **コンテキストエンジニアリング** — タスクごとにAIが必要とするすべてを提供する構造化アーティファクト
2. **マルチエージェントオーケストレーション** — 専門エージェントをフレッシュなコンテキストウィンドウで起動する軽量オーケストレーター
1. **コンテキストエンジニアリング** — タスクごとに AI が必要とするすべてを提供する構造化アーティファクト（[コンテキストエンジニアリング](explanation/context-engineering.md) 参照）
2. **マルチエージェントオーケストレーション** — フレッシュなコンテキストウィンドウで専門化されたエージェントを生成する薄いオーケストレーター（[マルチエージェントオーケストレーション](explanation/multi-agent-orchestration.md) 参照）
3. **仕様駆動開発** — 要件 → 調査 → 計画 → 実行 → 検証のパイプライン
4. **状態管理** — セッションやコンテキストリセットをまたいだ永続的なプロジェクトメモリ
@@ -106,47 +106,93 @@ GSDは、ユーザーとAIコーディングエージェント（Claude Code、G
### コマンド（`commands/gsd/*.md`）
ユーザー向けのエントリーポイントです。各ファイルにはYAMLフロントマター（name、description、allowed-tools）とワークフローをブートストラップするプロンプト本文が含まれています。コマンドは以下の形式でインストールされます：
- **Claude Code:** カスタムスラッシュコマンド（`/gsd-command-name`）
- **OpenCode / Kilo:** スラッシュコマンド（`/gsd-command-name`）
ユーザー向けのエントリーポイントです。各ファイルには YAML フロントマター（name、description、allowed-tools）とワークフローをブートストラップするプロンプト本文が含まれています。コマンドは以下の形式でインストールされます：
- **Claude Code:** カスタムスラッシュコマンド（ハイフン形式、`/gsd-command-name`）
- **OpenCode / Kilo:** スラッシュコマンド（ハイフン形式、`/gsd-command-name`）
- **Codex:** スキル（`$gsd-command-name`）
- **Copilot:** スラッシュコマンド（`/gsd-command-name`）
- **Copilot:** スラッシュコマンド（ハイフン形式、`/gsd-command-name`）
- **Gemini CLI:** `gsd:` 名前空間下のスラッシュコマンド（コロン形式、`/gsd:command-name`）——Gemini はすべてのカスタムコマンドをプラグイン ID の下で名前空間化するため、インストールパスがすべての本文テキスト参照をコロン形式に書き換える
- **Antigravity:** スキル
**コマンド総数:** 44
**コマンド総数:** 信頼できる数と完全なロスターについては [`docs/INVENTORY.md`](INVENTORY.md#commands) を参照。
#### 2 段階の階層的ルーティング（v1.40、[#2792](https://github.com/open-gsd/gsd-core/issues/2792)）
eager なスキルリストのトークンコストを低く保つため、v1.40 では 6 つの名前空間 **メタスキル**（`gsd-workflow`、`gsd-project`、`gsd-quality`、`gsd-context`、`gsd-manage`、`gsd-ideate` ——`commands/gsd/ns-*.md` から取得されるが、呼び出し可能な `name:` はここに示すベア形式）を具体的なサブスキルの上にレイヤーとして導入しています。モデルは平坦な 86 スキルリスト（約 2,150 トークン）の代わりに 6 つの名前空間ルーター（約 120 トークン）を見て名前空間を選択し、名前空間ルーターの本文に埋め込まれたルーティングテーブルを通じて具体的なサブスキルにルーティングします。名前空間スキルは **付加的** です——すべての具体的なコマンドは依然として直接呼び出し可能です。
#### MCP トークンバジェットの相互作用
eager なスキルリストはターンごとの 2 つの主要コストの一つです。もう一つは `.claude/settings.json` で有効化されている各 MCP サーバーが注入する MCP ツールスキーマです。重量級の MCP サーバー（ブラウザ/playwright、Mac ツール、Windows ツール）はそれぞれターンごとに 20k+ トークンかかる場合があり、多くの場合 `model_profile` のチューニングで節約できるものをはるかに上回ります。トグルは Claude Code ハーネスにあります（`.claude/settings.json` の `enabledMcpjsonServers` / `disabledMcpjsonServers`）で、GSD の懸念事項ではありません。
### ワークフロー（`get-shit-done/workflows/*.md`）
コマンドが参照するオーケストレーションロジックです。以下を含むステップバイステップのプロセスが記述されています：
- `gsd-tools.cjs init` によるコンテキスト読み込み
- モデル解決を伴うエージェント起動の指示
- ゲート/チェックポイントの定義
- 状態更新パターン
- エラーハンドリングとリカバリー
**ワークフロー総数:** 46
**ワークフロー総数:** 信頼できる数と完全なロスターについては [`docs/INVENTORY.md`](INVENTORY.md#workflows) を参照。
#### ワークフローのプログレッシブディスクロージャー
ワークフローファイルは、対応する `/gsd-*` コマンドが呼び出されるたびに Claude のコンテキストにそのまま読み込まれます。そのコストを制限するため、`tests/workflow-size-budget.test.cjs` で強制されるワークフローサイズバジェットは #2361 のエージェントバジェットを反映します：
| ティア | ファイルごとの行数制限 |
|-----------|--------------------|
| `XL` | 1700 — トップレベルオーケストレーター（`execute-phase`、`plan-phase`、`new-project`） |
| `LARGE` | 1500 — 複数ステップのプランナーと大きな機能ワークフロー |
| `DEFAULT` | 1000 — 集中した単一目的のワークフロー（対象ティア） |
### エージェント（`agents/*.md`）
フロントマターで以下を指定する専門エージェント定義：
フロントマターで以下を指定する専門化されたエージェント定義：
- `name` — エージェント識別子
- `description` — 役割と目的
- `tools` — 許可されたツールアクセス（Read、Write、Edit、Bash、Grep、Glob、WebSearchなど）
- `tools` — 許可されたツールアクセス（Read、Write、Edit、Bash、Grep、Glob、WebSearch など）
- `color` — 視覚的な区別のためのターミナル出力色
**エージェント総数:** 16
**エージェント総数:** 33
### リファレンス（`get-shit-done/references/*.md`）
ワークフローとエージェントが `@-reference` で参照する共有知識ドキュメント：
ワークフローとエージェントが `@-reference` で参照する共有知識ドキュメント（信頼できる数と完全なロスターについては [`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped) を参照）：
**コアリファレンス：**
- `checkpoints.md` — チェックポイントタイプの定義とインタラクションパターン
- `gates.md` — プランチェッカーと検証者に組み込まれた 4 つの正規ゲートタイプ（Confirm、Quality、Safety、Transition）
- `model-profiles.md` — エージェントごとのモデルティア割り当て
- `model-profile-resolution.md` — モデル解決アルゴリズムのドキュメント
- `verification-patterns.md` — 各種アーティファクトの検証方法
- `planning-config.md` — 設定スキーマの全体像と動作
- `git-integration.md` — gitコミット、ブランチ、履歴のパターン
- `verification-overrides.md` — アーティファクトごとの検証オーバーライドルール
- `planning-config.md` — 完全な設定スキーマと動作
- `git-integration.md` — git コミット、ブランチ、履歴のパターン
- `git-planning-commit.md` — planning ディレクトリのコミット規約
- `questioning.md` — プロジェクト初期化のためのドリーム抽出フィロソフィー
- `tdd.md` — テスト駆動開発の統合パターン
- `ui-brand.md` — 視覚的な出力フォーマットパターン
- `common-bug-patterns.md` — コードレビューと検証のための一般的なバグパターン
**ワークフローリファレンス：**
- `agent-contracts.md` — オーケストレーターとエージェント間の正式インターフェース
- `context-budget.md` — コンテキストウィンドウバジェット配分ルール
- `continuation-format.md` — セッション継続/再開フォーマット
- `domain-probes.md` — discuss-phase のためのドメイン固有プローブ質問
- `gate-prompts.md` — ゲート/チェックポイントプロンプトテンプレート
- `revision-loop.md` — 計画修正の反復パターン
- `universal-anti-patterns.md` — 検出・回避すべき一般的なアンチパターン
- `artifact-types.md` — 計画アーティファクトタイプの定義
- `phase-argument-parsing.md` — フェーズ引数解析の規約
- `decimal-phase-calculation.md` — 小数サブフェーズ番号付けのルール
- `workstream-flag.md` — ワークストリームアクティブポインターの規約
- `user-profiling.md` — ユーザー行動プロファイリングの方法論
- `thinking-partner.md` — 決定ポイントでの条件付きシンキングパートナー起動
### テンプレート（`get-shit-done/templates/`）
@@ -172,26 +218,36 @@ GSDは、ユーザーとAIコーディングエージェント（Claude Code、G
| `gsd-prompt-guard.js` | `PreToolUse` | `.planning/` への書き込みにプロンプトインジェクションパターンがないかスキャン（アドバイザリー） |
| `gsd-workflow-guard.js` | `PreToolUse` | GSDワークフローコンテキスト外でのファイル編集を検出（アドバイザリー、`hooks.workflow_guard` によるオプトイン） |
### CLIツール（`get-shit-done/bin/`）
### コマンドルーティングハブ（`get-shit-done/bin/lib/command-routing-hub.cjs`）
17のドメインモジュールを持つNode.js CLIユーティリティ（`gsd-tools.cjs`）：
CJS コマンドファミリールーターは `CommandRoutingHub` を通じてディスパッチします。ハブはノースロー純粋結果コントラクト（`hub.dispatch()` は内部例外をキャッチして `{ ok: false, kind, ...typedPayload }` を返す）とクローズドランタイムエラー分類（`UnknownCommand`、`InvalidArgs`、`HandlerRefusal`、`HandlerFailure`）を所有します。ルーターアダプターは薄い CLI トランスレーターのままです——ハブを構築し、`dispatch` を呼び出し、結果を `output()`/`error()` 呼び出しにマッピングします。`docs/adr/0174-retire-gsd-sdk-package-boundary.md` を参照。
### CLI ツール（`get-shit-done/bin/`）
`get-shit-done/bin/lib/` にドメインモジュールが分割された Node.js CLI ユーティリティ（`gsd-tools.cjs`）（信頼できるロスターについては [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) を参照）：
| モジュール | 責務 |
|--------|---------------|
| `core.cjs` | エラーハンドリング、出力フォーマット、共有ユーティリティ |
| ---------------------- | --------------------------------------------------------------------------------------------------- |
| `core.cjs` | エラーハンドリング、出力フォーマット、共有ユーティリティ；planning ヘルパーの互換性 re-export |
| `planning-workspace.cjs` | planning シーム（`planningDir`、`planningPaths`、アクティブなワークストリームルーティング、`.planning/.lock`） |
| `state.cjs` | STATE.md の解析、更新、進行、メトリクス |
| `phase.cjs` | フェーズディレクトリ操作、小数番号付け、プランインデックス |
| `roadmap.cjs` | ROADMAP.md の解析、フェーズ抽出、プラン進捗 |
| `config.cjs` | config.json の読み書き、セクション初期化 |
| `verify.cjs` | プラン構造、フェーズ完了度、リファレンス、コミット検証 |
| `template.cjs` | テンプレート選択と変数置換による穴埋め |
| `frontmatter.cjs` | YAMLフロントマターのCRUD操作 |
| `frontmatter.cjs` | YAML フロントマターの CRUD 操作 |
| `init.cjs` | ワークフロータイプごとの複合コンテキスト読み込み |
| `milestone.cjs` | マイルストーンのアーカイブ、要件マーキング |
| `commands.cjs` | その他コマンド（slug、タイムスタンプ、todos、スキャフォールディング、統計） |
| `model-profiles.cjs` | モデルプロファイル解決テーブル |
| `security.cjs` | パストラバーサル防止、プロンプトインジェクション検出、安全なJSON解析、シェル引数バリデーション |
| `uat.cjs` | UATファイル解析、検証デット追跡、audit-uatサポート |
| `security.cjs` | パストラバーサル防止、プロンプトインジェクション検出、安全な JSON 解析、シェル引数バリデーション |
| `uat.cjs` | UAT ファイル解析、検証デット追跡、audit-uat サポート |
| `docs.cjs` | ドキュメント更新ワークフロー init、Markdown スキャン、モノレポ検出 |
| `workstream.cjs` | ワークストリーム CRUD、マイグレーション、セッションスコープのアクティブポインター |
| `schema-detect.cjs` | ORM パターンのスキーマドリフト検出（Prisma、Drizzle など） |
| `profile-pipeline.cjs` | ユーザー行動プロファイリングデータパイプライン、セッションファイルスキャン |
| `profile-output.cjs` | プロファイルレンダリング、USER-PROFILE.md と dev-preferences.md の生成 |
---
@@ -219,19 +275,24 @@ Orchestrator (workflow .md)
└── Update state: gsd-tools.cjs state update/patch/advance-plan
```
### エージェント起動カテゴリ
### 主要エージェント生成カテゴリ
| カテゴリ | エージェント | 並列実行 |
|----------|--------|-------------|
| **リサーチャー** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4並列（stack、features、architecture、pitfalls）; advisorはdiscuss-phase中に起動 |
21 の主要エージェントの概念的な生成パターン分類。信頼できる 31 エージェントロスター（`gsd-pattern-mapper`、`gsd-code-reviewer`、`gsd-code-fixer`、`gsd-ai-researcher`、`gsd-domain-researcher`、`gsd-eval-planner`、`gsd-eval-auditor`、`gsd-framework-selector`、`gsd-debug-session-manager`、`gsd-intel-updater` などの 10 の高度/専門化エージェントを含む）については、[`docs/INVENTORY.md`](INVENTORY.md#agents-31-shipped) を参照。
| カテゴリ | エージェント | 並列性 |
| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **リサーチャー** | gsd-project-researcher、gsd-phase-researcher、gsd-ui-researcher、gsd-advisor-researcher | 4 並列（stack、features、architecture、pitfalls）；advisor は discuss-phase 中に起動 |
| **シンセサイザー** | gsd-research-synthesizer | 逐次（リサーチャー完了後） |
| **プランナー** | gsd-planner, gsd-roadmapper | 逐次 |
| **チェッカー** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | 逐次（検証ループ、最大3回反復） |
| **プランナー** | gsd-planner、gsd-roadmapper | 逐次 |
| **チェッカー** | gsd-plan-checker、gsd-integration-checker、gsd-ui-checker、gsd-nyquist-auditor | 逐次（検証ループ、最大 3 回反復） |
| **エグゼキューター** | gsd-executor | ウェーブ内は並列、ウェーブ間は逐次 |
| **ベリファイアー** | gsd-verifier | 逐次（全エグゼキューター完了後） |
| **マッパー** | gsd-codebase-mapper | 4並列（tech、arch、quality、concerns） |
| **マッパー** | gsd-codebase-mapper | 4 並列（tech、arch、quality、concerns） |
| **デバッガー** | gsd-debugger | 逐次（インタラクティブ） |
| **オーディター** | gsd-ui-auditor | 逐次 |
| **オーディター** | gsd-ui-auditor、gsd-security-auditor | 逐次 |
| **Doc ライター** | gsd-doc-writer、gsd-doc-verifier | 逐次（ライター後に検証者） |
| **プロファイラー** | gsd-user-profiler | 逐次 |
| **アナライザー** | gsd-assumptions-analyzer | 逐次（discuss-phase 中） |
### ウェーブ実行モデル
@@ -247,18 +308,28 @@ Wave Analysis:
```
各エグゼキューターには以下が与えられます：
- フレッシュな200Kコンテキストウィンドウ
- 実行対象の特定のPLAN.md
- フレッシュな 200K コンテキストウィンドウ（または対応モデルでは最大 1M）
- 実行対象の特定の PLAN.md
- プロジェクトコンテキスト（PROJECT.md、STATE.md）
- フェーズコンテキスト（CONTEXT.md、利用可能な場合はRESEARCH.md）
- フェーズコンテキスト（CONTEXT.md、利用可能な場合は RESEARCH.md）
### アダプティブコンテキスト拡充（1M モデル）
コンテキストウィンドウが 500K+ トークンの場合（Opus 4.6、Sonnet 4.6 などの 1M クラスモデル）、サブエージェントプロンプトは標準 200K ウィンドウには収まらない追加コンテキストで自動的に拡充されます：
- **エグゼキューターエージェント** は前のウェーブの SUMMARY.md ファイルとフェーズの CONTEXT.md/RESEARCH.md を受け取り、フェーズ内でのクロスプラン認識を可能にする
- **検証者エージェント** はすべての PLAN.md、SUMMARY.md、CONTEXT.md ファイルと REQUIREMENTS.md を受け取り、履歴を考慮した検証を可能にする
オーケストレーターは設定から `context_window` を読み取り（`gsd-tools.cjs config-get context_window`）、値が >= 500,000 の場合に条件付きでより豊富なコンテキストを含めます。標準 200K ウィンドウでは、プロンプトはコンテキスト効率を最大化するためにキャッシュフレンドリーな順序で切り詰められたバージョンを使います。
#### 並列コミットの安全性
同一ウェーブ内で複数のエグゼキューターが実行される場合、2つの仕組みで競合を防止します：
同一ウェーブ内で複数のエグゼキューターが実行される場合、2 つの仕組みで競合を防止します：
1. **`--no-verify` コミット** — 並列エージェントはpre-commitフックをスキップします（ビルドロックの競合を引き起こす可能性があるため。例：Rustプロジェクトでのcargo lockファイルの競合）。オーケストレーターは各ウェーブ完了後に `git hook run pre-commit` を1回実行します。
1. **`--no-verify` コミット** — 並列エージェントはプリコミットフックをスキップします（ビルドロックの競合を引き起こす可能性があるため。例：Rust プロジェクトでの cargo lock ファイルの競合）。オーケストレーターは各ウェーブ完了後に `git hook run pre-commit` を 1 回実行します。
2. **STATE.md ファイルロック** — すべての `writeStateMd()` 呼び出しはロックファイルベースの相互排他（`STATE.md.lock`、`O_EXCL` によるアトミック作成）を使用します。これにより、2つのエージェントがSTATE.mdを読み取り、異なるフィールドを変更し、最後の書き込みが他方の変更を上書きする読み取り-変更-書き込みの競合状態を防止します。古いロックの検出（10秒タイムアウト）とジッター付きのスピンウェイトを含みます。
2. **STATE.md ファイルロック** — すべての `writeStateMd()` 呼び出しはロックファイルベースの相互排他（`STATE.md.lock`、`O_EXCL` によるアトミック作成）を使用します。これにより、2 つのエージェントが STATE.md を読み取り、異なるフィールドを変更し、最後の書き込みが他方の変更を上書きする read-modify-write 競合状態を防止します。古いロックの検出（10 秒タイムアウト）とジッター付きのスピンウェイトを含みます。
---
@@ -302,16 +373,27 @@ ui-phase → UI-SPEC.md (design contract, optional)
│
▼
plan-phase
├── Research gate (blocks if RESEARCH.md has unresolved open questions)
├── Phase Researcher → RESEARCH.md
├── Planner → PLAN.md files
└── Plan Checker → Verify loop (max 3x)
│ └── Package Legitimacy Gate: slopcheck on every package; [SLOP] removed,
│ [SUS]/[ASSUMED] flagged; Audit table written to RESEARCH.md
├── Planner (with reachability check) → PLAN.md files
│ └── checkpoint:human-verify injected before [ASSUMED]/[SUS] installs;
│ T-{phase}-SC STRIDE row added for install-bearing plans
├── Plan Checker → Verify loop (max 3x)
├── Requirements coverage gate (REQ-IDs → plans)
└── Decision coverage gate (CONTEXT.md `<decisions>` → plans, BLOCKING — #2492)
│
▼
execute-phase
state planned-phase → STATE.md (Planned/Ready to execute)
│
▼
execute-phase (context reduction: truncated prompts, cache-friendly ordering)
├── Wave analysis (dependency grouping)
├── Executor per plan → code + atomic commits
├── SUMMARY.md per plan
└── Verifier → VERIFICATION.md
└── Decision coverage gate (CONTEXT.md decisions → shipped artifacts, NON-BLOCKING — #2492)
│
▼
verify-work → UAT.md (user acceptance testing)
@@ -344,29 +426,37 @@ UI-SPEC.md (per phase) ───────────────────
```
~/.claude/ # Claude Code (global install)
├── commands/gsd/*.md # 37 slash commands
├── skills/gsd-*/SKILL.md # Global skills (authoritative roster: docs/INVENTORY.md)
├── commands/gsd/*.md # Local Claude installs use slash commands instead of global skills
├── get-shit-done/
│ ├── bin/gsd-tools.cjs # CLI utility
│ ├── bin/lib/*.cjs # 15 domain modules
│ ├── workflows/*.md # 42 workflow definitions
│ ├── references/*.md # 13 shared reference docs
│ ├── bin/lib/*.cjs # Domain modules (authoritative roster: docs/INVENTORY.md)
│ ├── workflows/*.md # Workflow definitions (authoritative roster: docs/INVENTORY.md)
│ ├── references/*.md # Shared reference docs (authoritative roster: docs/INVENTORY.md)
│ └── templates/ # Planning artifact templates
├── agents/*.md # 15 agent definitions
├── hooks/
│ ├── gsd-statusline.js # Statusline hook
│ ├── gsd-context-monitor.js # Context warning hook
│ └── gsd-check-update.js # Update check hook
├── agents/*.md # Agent definitions (authoritative roster: docs/INVENTORY.md)
├── hooks/*.js # Node.js hooks (statusline, guards, monitors, update check)
├── hooks/*.sh # Shell hooks (session state, commit validation, phase boundary)
├── settings.json # Hook registrations
└── VERSION # Installed version number
```
他のランタイムでの同等パス：
- **OpenCode:** `~/.config/opencode/` または `~/.opencode/`
- **Kilo:** `~/.config/kilo/` または `~/.kilo/`
- **Gemini CLI:** `~/.gemini/`
- **Codex:** `~/.codex/`（コマンドの代わりにスキルを使用）
- **Copilot:** `~/.github/`
- **Antigravity:** `~/.gemini/antigravity/`（グローバル）または `./.agent/`（ローカル）
- **OpenCode:** `~/.config/opencode/` global または `./.opencode/` local
- **Kilo:** `~/.config/kilo/` global または `./.kilo/` local
- **Gemini CLI:** `~/.gemini/` global または `./.gemini/` local
- **Codex:** `~/.codex/` global または `./.codex/` local
- **Copilot:** `~/.copilot/` global または `./.github/` local
- **Antigravity:** auto-detected global root（`~/.gemini/antigravity/`、`~/.gemini/antigravity-ide/`、または `~/.gemini/antigravity-cli/`）または `./.agent/` local
- **Cursor:** `~/.cursor/` global または `./.cursor/` local
- **Windsurf:** `~/.codeium/windsurf/` global または `./.windsurf/` local
- **Augment Code:** `~/.augment/` global または `./.augment/` local
- **Trae:** `~/.trae/` global または `./.trae/` local
- **Qwen Code:** `~/.qwen/` global または `./.qwen/` local
- **Hermes Agent:** `~/.hermes/` global または `./.hermes/` local
- **CodeBuddy:** `~/.codebuddy/` global または `./.codebuddy/` local
- **Cline:** `~/.cline/` global または project-root `.clinerules` local
### プロジェクトファイル（`.planning/`）
@@ -424,29 +514,39 @@ UI-SPEC.md (per phase) ───────────────────
## インストーラーアーキテクチャ
インストーラー（`bin/install.js`、約3,000行）は以下を処理します：
インストーラー（`bin/install.js`、約 10,700 行）は以下を処理します：
1. **ランタイム検出** — インタラクティブプロンプトまたはCLIフラグ（`--claude`、`--opencode`、`--gemini`、`--kilo`、`--codex`、`--copilot`、`--antigravity`、`--all`）
1. **ランタイム検出** — インタラクティブプロンプトまたは CLI フラグ（`--claude`、`--opencode`、`--gemini`、`--kilo`、`--codex`、`--copilot`、`--antigravity`、`--cursor`、`--windsurf`、`--augment`、`--trae`、`--qwen`、`--hermes`、`--codebuddy`、`--cline`、`--all`）
2. **インストール先の選択** — グローバル（`--global`）またはローカル（`--local`）
3. **ファイルデプロイ** — コマンド、ワークフロー、リファレンス、テンプレート、エージェント、フックをコピー
3. **ファイルデプロイ** — コマンド、スキル、ワークフロー、リファレンス、テンプレート、エージェント、フックをコピー
4. **ランタイム適応** — ランタイムごとにファイル内容を変換：
- Claude Code: そのまま使用
- OpenCode: コマンド/エージェントをOpenCode互換のフラットコマンド + サブエージェント形式に変換
- Kilo: OpenCode変換パイプラインをKiloの設定パスで再利用
- Codex: コマンドからTOML設定 + スキルを生成
- Copilot: ツール名をマッピング（Read→read、Bash→executeなど）
- OpenCode: コマンド/エージェントを OpenCode 互換のフラットコマンド + サブエージェント形式に変換
- Kilo: OpenCode 変換パイプラインを Kilo の設定パスで再利用
- Codex: コマンドから TOML 設定 + スキルを生成
- Copilot: ツール名をマッピング（Read→read、Bash→execute など）
- Gemini: フックイベント名を調整（`PostToolUse` の代わりに `AfterTool`）
- Antigravity: Googleモデル同等品によるスキルファースト
- Antigravity: Google モデル同等品によるスキルファースト
- Cursor: ルール参照付きスキルファースト
- Windsurf: ルール参照付きスキルファースト
- Trae: `~/.trae` / `./.trae` へのスキルファーストインストール、`settings.json` またはフック統合なし
- Qwen Code: Qwen ブランドのパスとプロンプト書き換え付きスキルファースト
- Hermes Agent: `skills/gsd/` 下のカテゴリベーススキル
- CodeBuddy: CodeBuddy パスとプロンプト書き換え付きスキルファースト
- Cline: ルールベース統合のための `.clinerules` を書き込む
- Augment Code: スキルファースト、完全なスキル変換と設定管理
5. **パス正規化** — `~/.claude/` パスをランタイム固有のパスに置換
6. **設定統合** — ランタイムの `settings.json` にフックを登録
7. **パッチバックアップ** — v1.17以降、ローカルで変更されたファイルを `/gsd-update --reapply` 用に `gsd-local-patches/` へバックアップ
7. **パッチバックアップ** — v1.17 以降、ローカルで変更されたファイルを `/gsd-update --reapply` 用に `gsd-local-patches/` へバックアップ
8. **マニフェスト追跡** — クリーンアンインストールのために `gsd-file-manifest.json` を書き込み
9. **アンインストールモード** — `--uninstall` ですべてのGSDファイル、フック、設定を削除
9. **アンインストールモード** — `--uninstall` ですべての GSD ファイル、フック、設定を削除
インストール時のファイル移動、古いアーティファクトのクリーンアップ、設定の書き換え、ユーザーデータの保全は Installer Migration Module によって管理されます。[Installer Migrations](../installer-migrations.md) と [ADR 0008](../adr/0008-installer-migration-module.md) を参照してください。
### プラットフォーム対応
- **Windows:** 子プロセスでの `windowsHide`、保護ディレクトリへのEPERM/EACCES対策、パスセパレーターの正規化
- **WSL:** WindowsのNode.jsがWSL上で実行されていることを検出し、パスの不一致について警告
- **Windows:** 子プロセスでの `windowsHide`、保護ディレクトリへの EPERM/EACCES 対策、パスセパレーターの正規化
- **WSL:** Windows の Node.js が WSL 上で実行されていることを検出し、パスの不一致について警告
- **Docker/CI:** カスタム設定ディレクトリの場所に `CLAUDE_CONFIG_DIR` 環境変数をサポート
---
@@ -474,32 +574,48 @@ Runtime Engine (Claude Code / Gemini CLI)
### コンテキストモニターの閾値
| コンテキスト残量 | レベル | エージェントの動作 |
|-------------------|-------|----------------|
| ----------------- | -------- | --------------------------------------- |
| > 35% | Normal | 警告なし |
| ≤ 35% | WARNING | 「新しい複雑な作業の開始を避けてください」 |
| ≤ 25% | CRITICAL | 「コンテキストがほぼ枯渇、ユーザーに通知してください」 |
デバウンス：繰り返し警告の間隔は5回のツール使用。重大度のエスカレーション（WARNING→CRITICAL）はデバウンスをバイパスします。
デバウンス：繰り返し警告の間隔は 5 回のツール使用。重大度のエスカレーション（WARNING→CRITICAL）はデバウンスをバイパスします。
### 安全性の特性
- すべてのフックはtry/catchでラップされ、エラー時はサイレントに終了
- stdin タイムアウトガード（3秒）でパイプの問題によるハングを防止
- 古いメトリクス（60秒超）は無視される
- すべてのフックは try/catch でラップされ、エラー時はサイレントに終了
- stdin タイムアウトガード（3 秒）でパイプの問題によるハングを防止
- 古いメトリクス（60 秒超）は無視される
- ブリッジファイルの欠落は適切に処理される（サブエージェント、新規セッション）
- コンテキストモニターはアドバイザリーのみ — ユーザーの設定を上書きする命令的なコマンドは発行しない
### パッケージ正当性ゲート（v1.42.1）
調査者 → プランナー → エグゼキューターパイプラインには、スロップスクワッティング（AI が幻覚した悪意のあるポストインストールスクリプト付きで事前登録されたパッケージ名）に対するサプライチェーンゲートが含まれます。
**ゲートレイヤー：**
| レイヤー | コンポーネント | アクション |
|-------|-----------|--------|
| 調査 | `gsd-phase-researcher` | `slopcheck install <pkgs> --json` を実行；`## Package Legitimacy Audit` テーブルを RESEARCH.md に書き込む；RESEARCH.md が書かれる前に `[SLOP]` パッケージを除去 |
| 計画 | `gsd-planner` | 監査テーブルを読み取る；任意の `[ASSUMED]` または `[SUS]` インストールタスクの前に `checkpoint:human-verify` を挿入；`<threat_model>` に `T-{phase}-SC` STRIDE サプライチェーン行を追加 |
| 実行 | `gsd-executor` | RULE 3 はパッケージインストールを自動修正スコープから除外；失敗したインストールはチェックポイントとして表面化し、サイレントな代替なし |
セキュリティモデルの概念的な概要については [セキュリティモデル](explanation/security-model.md) を参照。
### セキュリティフック（v1.27）
**Prompt Guard**（`gsd-prompt-guard.js`）：
- `.planning/` ファイルへのWrite/Edit時にトリガー
- プロンプトインジェクションパターン（ロールオーバーライド、指示バイパス、systemタグインジェクション）をスキャン
- `.planning/` ファイルへの Write/Edit 時にトリガー
- プロンプトインジェクションパターン（ロールオーバーライド、指示バイパス、system タグインジェクション）をスキャン
- アドバイザリーのみ — 検出をログに記録するが、ブロックはしない
- フックの独立性のため、パターンはインライン化（`security.cjs` のサブセット）
**Workflow Guard**（`gsd-workflow-guard.js`）：
- `.planning/` 以外のファイルへのWrite/Edit時にトリガー
- GSDワークフローコンテキスト外での編集を検出（アクティブな `/gsd-` コマンドやTaskサブエージェントがない場合）
- `.planning/` 以外のファイルへの Write/Edit 時にトリガー
- GSD ワークフローコンテキスト外での編集を検出（アクティブな `/gsd-` コマンドや Task サブエージェントがない場合）
- 状態追跡される変更には `/gsd-quick` や `/gsd-fast` の使用をアドバイス
- `hooks.workflow_guard: true` によるオプトイン（デフォルト: false）
@@ -507,24 +623,43 @@ Runtime Engine (Claude Code / Gemini CLI)
## ランタイム抽象化
GSDは統一されたコマンド/ワークフローアーキテクチャを通じて複数のAIコーディングランタイムをサポートしています：
GSD Core は統一されたコマンド/ワークフローアーキテクチャを通じて複数の AI コーディングランタイムをサポートしています：
| ランタイム | コマンド形式 | エージェントシステム | 設定場所 |
|---------|---------------|--------------|-----------------|
| Claude Code | `/gsd-command` | Task起動 | `~/.claude/` |
| OpenCode | `/gsd-command` | サブエージェントモード | `~/.config/opencode/` |
| Kilo | `/gsd-command` | サブエージェントモード | `~/.config/kilo/` |
| Gemini CLI | `/gsd-command` | Task起動 | `~/.gemini/` |
| Codex | `$gsd-command` | スキル | `~/.codex/` |
| Copilot | `/gsd-command` | エージェント委譲 | `~/.github/` |
| Antigravity | スキル | スキル | `~/.gemini/antigravity/` |
### ランタイムインストールコントラクトマトリクス
| ランタイム | グローバルルート | ローカルルート | 呼び出し面 | エージェント面 | 設定とフック |
| --- | --- | --- | --- | --- | --- |
| Claude Code | `~/.claude` | `./.claude` | グローバル `skills/gsd-*/SKILL.md`；ローカル `commands/gsd/*.md` | `agents/gsd-*.md` | `settings.json` フックと statusLine エントリ |
| OpenCode | `~/.config/opencode` | `./.opencode` | `command/gsd-*.md` | `agents/gsd-*.md` | `opencode.json` または `opencode.jsonc`；GSD フックなし |
| Kilo | `~/.config/kilo` | `./.kilo` | `command/gsd-*.md` | `agents/gsd-*.md` | `kilo.json` または `kilo.jsonc`；GSD フックなし |
| Gemini CLI | `~/.gemini` | `./.gemini` | `commands/gsd/*.toml` | `agents/gsd-*.md` | `settings.json` フィーチャーフラグ、フック、statusline |
| Codex | `~/.codex` | `./.codex` | `skills/gsd-*/SKILL.md` | エージェントソース markdown + エージェントごとの TOML | `config.toml` `[agents.gsd-*]`、`[features].hooks`、フックテーブル |
| GitHub Copilot | `~/.copilot` | `./.github` | `skills/gsd-*/SKILL.md` と `copilot-instructions.md` | `.agent.md` ファイル | GSD フックまたは statusline なし |
| Antigravity | auto-detected：`~/.gemini/antigravity`、`~/.gemini/antigravity-ide`、または `~/.gemini/antigravity-cli` | `./.agent` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | GSD がインストールした場合の Gemini スタイル `settings.json` フックエントリ |
| Cursor | `~/.cursor` | `./.cursor` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | `rules/` 下のルール参照；GSD フックなし |
| Windsurf | `~/.codeium/windsurf` | `./.windsurf` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | `rules/` 下のルール参照；GSD フックなし |
| Augment Code | `~/.augment` | `./.augment` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | GSD フックまたは statusline なし |
| Trae | `~/.trae` | `./.trae` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | `rules/` 下のルール参照；GSD フックなし |
| Qwen Code | `~/.qwen` | `./.qwen` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | サポートされている場合の共通 GSD 設定とフックエントリ |
| Hermes Agent | `~/.hermes` | `./.hermes` | `skills/gsd/DESCRIPTION.md` と `skills/gsd/gsd-*/SKILL.md` | `agents/gsd-*.md` | サポートされている場合の共通 GSD 設定とフックエントリ |
| CodeBuddy | `~/.codebuddy` | `./.codebuddy` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | サポートされている場合の共通 GSD 設定とフックエントリ |
| Cline | `~/.cline` | project root | `.clinerules` | ルールのみ | GSD フックまたは statusline なし |
### 抽象化ポイント
1. **ツール名マッピング** — 各ランタイムは独自のツール名を持つ（例：ClaudeのBash → Copilotのexecute）
2. **フックイベント名** — Claude Codeは `PostToolUse`、Geminiは `AfterTool` を使用
1. **ツール名マッピング** — 各ランタイムは独自のツール名を持つ（例：Claude の `Bash` → Copilot の `execute`）
2. **フックイベント名** — Claude Code は `PostToolUse`、Gemini は `AfterTool` を使用
3. **エージェントフロントマター** — 各ランタイムは独自のエージェント定義形式を持つ
4. **パス規約** — 各ランタイムは異なるディレクトリに設定を保存
5. **モデル参照** — `inherit` プロファイルにより、GSDはランタイムのモデル選択に委譲
5. **モデル参照** — `inherit` プロファイルにより、GSD はランタイムのモデル選択に委譲
インストーラーはインストール時にすべての変換を処理します。ワークフローとエージェントはClaude Codeのネイティブ形式で記述され、デプロイ時に変換されます。
インストーラーはインストール時にすべての変換を処理します。ワークフローとエージェントは Claude Code のネイティブ形式で記述され、デプロイ時に変換されます。
---
## Related
- [マルチエージェントオーケストレーション](explanation/multi-agent-orchestration.md)
- [セキュリティモデル](explanation/security-model.md)
- [CLI ツール](CLI-TOOLS.md)
- [ドキュメント索引](README.md)

166
docs/ja-JP/CLI-TOOLS.md
View File

@@ -1,26 +1,36 @@
# GSD CLI ツールリファレンス
> `gsd-tools.cjs` のプログラマティック API リファレンスです。ワークフローやエージェントが内部的に使用します。ユーザー向けコマンドについては、[コマンドリファレンス](COMMANDS.md) を参照してください。
> `gsd-tools` CLI（`get-shit-done/bin/gsd-tools.cjs`）のリファレンスです。スラッシュコマンドとユーザーフローについては [コマンドリファレンス](COMMANDS.md) を参照してください。[docs インデックス](README.md) に戻る。
---
## 概要
`gsd-tools.cjs` は、GSD の約50個のコマンド、ワークフロー、エージェントファイル全体で繰り返し使われるインライン bash パターンを置き換える Node.js CLI ユーティリティです。設定の解析、モデル解決、フェーズ検索、git コミット、サマリー検証、状態管理、テンプレート操作を一元化しています。
`gsd-tools.cjs` は、設定の解析、モデル解決、フェーズ検索、git コミット、サマリー検証、状態管理、テンプレート操作を GSD コマンド・ワークフロー・エージェント全体で一元化します。
**配置場所:** `get-shit-done/bin/gsd-tools.cjs`
**モジュール:** `get-shit-done/bin/lib/` 内の15個のドメインモジュール
**使い方:**
| | |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **配置パス** | `get-shit-done/bin/gsd-tools.cjs` |
| **実装** | `get-shit-done/bin/lib/` 配下の 20 個のドメインモジュール（ディレクトリが正式） |
| **ステータス** | オーケストレーション・ワークフロー・自動化処理のための主要ランタイムコマンドサーフェス。 |
**使い方（CJS）:**
```bash
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
```
**グローバルフラグ:**
| フラグ | 説明 |
|--------|------|
| `--raw` | 機械可読な出力（JSON またはプレーンテキスト、フォーマットなし） |
| `--cwd <path>` | 作業ディレクトリの上書き（サンドボックス化されたサブエージェント向け） |
**グローバルフラグ（CJS）:**
| フラグ | 説明 |
| -------------- | ---------------------------------------------------------------------------- |
| `--raw` | 機械可読な出力（JSON またはプレーンテキスト、フォーマットなし） |
| `--cwd <path>` | 作業ディレクトリの上書き（サンドボックス化されたサブエージェント向け） |
| `--ws <name>` | `.planning/workstreams/<name>` パス用のワークストリームコンテキスト |
---
@@ -64,6 +74,13 @@ node gsd-tools.cjs state resolve-blocker --text "..."
# セッション継続性を記録
node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path]
# フェーズ開始 — 新しいフェーズの STATE.md Status/Last activity を更新
node gsd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT
# エージェント検出可能なブロッカーシグナル送信（discuss-phase / UI フローで使用）
node gsd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P
node gsd-tools.cjs state signal-resume
```
### State スナップショット
@@ -152,7 +169,9 @@ node gsd-tools.cjs config-set-model-profile <profile>
```bash
# 現在のプロファイルに基づいてエージェント用モデルを取得
node gsd-tools.cjs resolve-model <agent-name>
# 戻り値: opus | sonnet | haiku | inherit
# --raw 出力では選択されたモデル ID/ティアを返します。
# JSON 出力ではプロファイルも含み、アクティブなランタイムがサポートしている場合は
# reasoning_effort も含まれます。
```
エージェント名: `gsd-planner`, `gsd-executor`, `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-roadmapper`, `gsd-debugger`, `gsd-codebase-mapper`, `gsd-nyquist-auditor`
@@ -198,8 +217,17 @@ node gsd-tools.cjs validate consistency
# .planning/ の整合性チェック、任意で修復
node gsd-tools.cjs validate health [--repair]
# ステータスライン / フック呼び出し元向けのコンテキストウィンドウ使用率をプローブ（v1.40.0）
node gsd-tools.cjs validate context
# 型付き JSON サーフェスとしてのコンテキスト使用率（#455）
node gsd-tools.cjs validate context --json
```
`validate context` は `utilization`、`status`（60% / 70% の閾値で `ok` / `warn` / `critical`）、および `suggestion` 文字列を含む構造化エンベロープを出力します。同じデータが `/gsd-health --context` を支えます。
型付き IR を直接受け取るには `--json` を渡してください（スクリプトやテストアサーションで有用）。
---
## Template コマンド
@@ -275,9 +303,13 @@ node gsd-tools.cjs init todos [area]
node gsd-tools.cjs init milestone-op
node gsd-tools.cjs init map-codebase
node gsd-tools.cjs init progress
# ワークストリームスコープ付き init（`--ws` フラグ）
node gsd-tools.cjs init execute-phase <phase> --ws <name>
node gsd-tools.cjs init plan-phase <phase> --ws <name>
```
**大容量ペイロードの処理:** 出力が約50KBを超える場合、CLI は一時ファイルに書き出し、`@file:/tmp/gsd-init-XXXXX.json` を返します。ワークフローは `@file:` プレフィックスを確認し、ディスクから読み込みます:
**大容量ペイロードの処理:** 出力が約 50KB を超える場合、CLI は一時ファイルに書き出し、`@file:/tmp/gsd-init-XXXXX.json` を返します。ワークフローは `@file:` プレフィックスを確認し、ディスクから読み込みます:
```bash
INIT=$(node gsd-tools.cjs init execute-phase "1")
@@ -299,6 +331,38 @@ node gsd-tools.cjs requirements mark-complete <ids>
---
## エージェントスキル
指定されたエージェントタイプのスキルブロックを出力します。
```bash
# 生の XML スキルブロックを出力（デフォルト — シェル展開に安全）
node gsd-tools.cjs agent-skills <agent-type>
# 型付き JSON サーフェス（#455）を出力 — { agent_type, block, skills_count }
node gsd-tools.cjs agent-skills <agent-type> --json
```
`--json` フラグは構造化消費やテストアサーションに適した型付き IR オブジェクトを返します。デフォルト（フラグなし）はワークフローのシェル展開が依存する生の XML 出力を維持します。
---
## スキルマニフェスト
コマンド読み込みを高速化するためのスキル検出の事前計算とキャッシュ。
```bash
# スキルマニフェストを生成（.claude/skill-manifest.json に書き込む）
node gsd-tools.cjs skill-manifest
# カスタム出力パスで生成
node gsd-tools.cjs skill-manifest --output <path>
```
利用可能なすべての GSD スキルとそのメタデータ（名前、説明、ファイルパス、引数ヒント）の JSON マッピングを返します。インストーラとセッション開始フックが繰り返しのファイルシステムスキャンを避けるために使用します。
---
## ユーティリティコマンド
```bash
@@ -324,35 +388,70 @@ node gsd-tools.cjs summary-extract <path> [--fields field1,field2]
# プロジェクト統計
node gsd-tools.cjs stats [json|table]
# 進捗表示
# 進捗表示（人間が読める形式）
node gsd-tools.cjs progress [json|table|bar]
# 型付き JSON サーフェスとしての進捗（#455）
node gsd-tools.cjs progress --json
# TODO を完了にする
node gsd-tools.cjs todo complete <filename>
# UAT 監査 — 全フェーズの未解決項目をスキャン
node gsd-tools.cjs audit-uat
# クロスアーティファクト監査キュー — `.planning/` の未解決監査項目をスキャン
node gsd-tools.cjs audit-open [--json]
# GSD-2 プロジェクトを現在の構造にリバースマイグレーション（`/gsd-import --from-gsd2` のバックエンド）
node gsd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]
# 設定チェック付き git コミット
node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify]
node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify] [--respect-staged]
```
> **`--no-verify`**: プリコミットフックをスキップします。ウェーブベース実行時に並列エグゼキューターエージェントが使用し、ビルドロックの競合（例: Rust プロジェクトでの cargo ロック競合）を回避します。オーケストレーターは各ウェーブ完了後にフックを一度実行します。順次実行時には `--no-verify` を使用せず、フックを通常通り実行してください。
> `--no-verify`: プリコミットフックをスキップします。ウェーブベース実行時に並列エグゼキューターエージェントがビルドロックの競合（例: Rust プロジェクトでの cargo ロック競合）を避けるために使用します。オーケストレーターは各ウェーブ完了後にフックを一度実行します。順次実行時には `--no-verify` を使用せず、フックを通常通り実行してください。
> `--files <paths>` **ステージング動作**: デフォルトでは、`--files` はコミット前に各指定ファイルに対して `git add -- <path>` を実行します。これにより `git add -p` で設定したハンク単位のステージングが上書きされます。`git add` ステップをスキップして指定パス内のステージング済みファイルのみをコミットするには `--respect-staged` を渡してください。そのスコープ内でステージングされたファイルがない場合、コマンドはエラーなしで `{ committed: false, reason: 'nothing staged' }` を返します。コミット時の末尾 `-- <paths>` パス指定は両モードで適用されるため、`--files` スコープ外でステージングされたファイルは決して含まれません（#3061 不変条件）。
```bash
# Web 検索（Brave API キーが必要）
node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
```
---
## Graphify
`.planning/graphs/` 内のプロジェクトナレッジグラフをビルド、クエリ、検査します。`config.json` で `graphify.enabled: true` が必要です（[設定リファレンス](CONFIGURATION.md#graphify-settings) を参照）。
```bash
# ナレッジグラフをビルドまたは再ビルド
node gsd-tools.cjs graphify build
# グラフで用語を検索
node gsd-tools.cjs graphify query <term>
# グラフの鮮度と統計を表示
node gsd-tools.cjs graphify status
# 前回のビルドからの変更を表示
node gsd-tools.cjs graphify diff
# 現在のグラフの名前付きスナップショットを書き込む
node gsd-tools.cjs graphify snapshot [name]
```
ユーザー向けエントリーポイント: `/gsd-graphify`（[コマンドリファレンス](COMMANDS.md#gsd-graphify) を参照）。
---
## モジュールアーキテクチャ
| モジュール | ファイル | エクスポート |
|------------|----------|--------------|
| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, 共通ユーティリティ |
| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`、共通ユーティリティ、互換性再エクスポート |
| State | `lib/state.cjs` | すべての `state` サブコマンド、`state-snapshot` |
| Phase | `lib/phase.cjs` | フェーズ CRUD、`find-phase`、`phase-plan-index`、`phases list` |
| Planning Workspace | `lib/planning-workspace.cjs` | プランニングシーム: `planningDir`、`planningPaths`、アクティブワークストリームルーティング、`.planning/.lock` |
| Roadmap | `lib/roadmap.cjs` | ロードマップ解析、フェーズ抽出、進捗更新 |
| Config | `lib/config.cjs` | 設定の読み書き、セクション初期化 |
| Verify | `lib/verify.cjs` | すべての検証・バリデーションコマンド |
@@ -365,3 +464,36 @@ node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
| UAT | `lib/uat.cjs` | 全フェーズ横断 UAT/検証監査 |
| Profile Output | `lib/profile-output.cjs` | 開発者プロファイルのフォーマット |
| Profile Pipeline | `lib/profile-pipeline.cjs` | セッション分析パイプライン |
| Graphify | `lib/graphify.cjs` | ナレッジグラフのビルド/クエリ/ステータス/差分/スナップショット（`/gsd-graphify` のバックエンド） |
| Learnings | `lib/learnings.cjs` | フェーズ/SUMMARY アーティファクトからの学習抽出（`/gsd-extract-learnings` のバックエンド） |
| Audit | `lib/audit.cjs` | フェーズ/マイルストーン監査キューハンドラ; `audit-open` ヘルパー |
| GSD2 Import | `lib/gsd2-import.cjs` | GSD-2 プロジェクトからのリバースマイグレーションインポーター（`/gsd-import --from-gsd2` のバックエンド） |
| Intel | `lib/intel.cjs` | クエリ可能なコードベースインテリジェンスインデックス（`/gsd-map-codebase --query` のバックエンド） |
---
## レビュアー CLI ルーティング
`review.models.<cli>` はレビュアーフレーバーをコードレビューワークフローが呼び出すシェルコマンドにマッピングします。[`/gsd-config --integrations`](COMMANDS.md#gsd-config) または直接設定できます:
```bash
node gsd-tools.cjs config-set review.models.codex "codex exec --model gpt-5"
node gsd-tools.cjs config-set review.models.gemini "gemini -m gemini-2.5-pro"
node gsd-tools.cjs config-set review.models.opencode "opencode run --model claude-sonnet-4"
node gsd-tools.cjs config-set review.models.claude "" # クリア — セッションモデルにフォールバック
```
スラッグは `[a-zA-Z0-9_-]+` に対してバリデーションされます。空またはパスを含むスラッグは拒否されます。完全なフィールドリファレンスは [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing) を参照してください。
## シークレット処理
`/gsd-settings` で設定された API キー（`brave_search`、`firecrawl`、`exa_search`）は `.planning/config.json` に平文で書き込まれますが、`config-set` / `config-get` のすべての出力、確認テーブル、インタラクティブプロンプトでは（`****<last-4>` として）マスクされます。マスキングの実装は `get-shit-done/bin/lib/secrets.cjs` を参照してください。`config.json` ファイル自体がセキュリティ境界です — ファイルシステムのパーミッションで保護し、git には含めないようにしてください（`.planning/` はデフォルトで gitignore されます）。
---
## Related
- [Commands](COMMANDS.md)
- [Configuration](CONFIGURATION.md)
- [Architecture](ARCHITECTURE.md)
- [docs index](README.md)

1371
docs/ja-JP/COMMANDS.md
View File

File diff suppressed because it is too large Load Diff

1171
docs/ja-JP/FEATURES.md
View File

File diff suppressed because it is too large Load Diff

493
docs/ja-JP/INVENTORY.md Normal file
View File

@@ -0,0 +1,493 @@
# GSD 出荷済みサーフェスインベントリ
> 出荷済みのすべての GSD サーフェスの正式な一覧: コマンド、エージェント、ワークフロー、リファレンス、CLI モジュール、フック。広範なドキュメント（AGENTS.md、COMMANDS.md、ARCHITECTURE.md、CLI-TOOLS.md）とファイルシステムが乖離している場合は、このファイルとリポジトリツリー自体を正式なソースとして扱ってください。
## このファイルの使い方
- ここに記載された数値は v1.36.0 時点のファイルシステムから導出されており、リリース間で変動する可能性があります。最新の数値を確認するには、チェックアウトに対して `ls commands/gsd/*.md | wc -l`、`ls agents/gsd-*.md | wc -l` などを実行してください。
- このファイルは出荷済みのすべてのサーフェスを 6 つのファミリー（エージェント、コマンド、ワークフロー、リファレンス、CLI モジュール、フック）にわたって列挙します。広範なドキュメントはナラティブや厳選されたサブセットを提示する場合があります。ファイルシステムと異なる場合は、このファイルとディレクトリ一覧が正式です。
- v1.36.0 以降に追加された新しいサーフェスはまずここに記載し、その後広範なドキュメントに伝播させてください。`tests/inventory-counts.test.cjs`、`tests/commands-doc-parity.test.cjs`、`tests/agents-doc-parity.test.cjs`、`tests/cli-modules-doc-parity.test.cjs`、`tests/hooks-doc-parity.test.cjs`、`tests/architecture-counts.test.cjs`、`tests/command-count-sync.test.cjs` のドリフト管理テストが、ファイルシステムに対して数値とロスター内容を固定します。
これは出荷済みのすべての GSD Core サーフェスの正式な一覧です。トピック別のナビゲーションは [docs インデックス](README.md) を参照してください。
---
## エージェント (33 shipped)
完全な一覧は `agents/gsd-*.md` を参照してください。"Primary doc" 列は [`docs/AGENTS.md`](../AGENTS.md) が完全なロールカードを掲載している場合（*primary*）、"Advanced and Specialized Agents" セクションに短いスタブがある場合（*advanced stub*）、または掲載がない場合（*inventory only*）を示します。
| エージェント | 役割（一行） | 起動元 | Primary doc |
|--------------|-------------|--------|-------------|
| gsd-project-researcher | ロードマップ作成前にドメインエコシステムを調査（スタック、機能、アーキテクチャ、落とし穴）。 | `/gsd-new-project`, `/gsd-new-milestone` | primary |
| gsd-phase-researcher | 計画前に特定フェーズの実装アプローチを調査。 | `/gsd-plan-phase` | primary |
| gsd-ui-researcher | フロントエンドフェーズ向けの UI デザインコントラクトを作成。 | `/gsd-ui-phase` | primary |
| gsd-assumptions-analyzer | discuss-phase（仮定モード）向けに証拠に基づく仮定を作成。 | `discuss-phase-assumptions` workflow | primary |
| gsd-advisor-researcher | discuss-phase アドバイザーモード中に単一のグレーゾーン決定を調査。 | `discuss-phase` workflow (advisor mode) | primary |
| gsd-research-synthesizer | 並列調査エージェントの出力を統合した SUMMARY.md にまとめる。 | `/gsd-new-project` | primary |
| gsd-planner | タスク分解とゴール後退型検証を含む実行可能なフェーズプランを作成。 | `/gsd-plan-phase`, `/gsd-quick` | primary |
| gsd-roadmapper | フェーズ分解と要件マッピングを含むプロジェクトロードマップを作成。 | `/gsd-new-project` | primary |
| gsd-executor | アトミックコミットと逸脱処理を伴って GSD プランを実行。 | `/gsd-execute-phase`, `/gsd-quick` | primary |
| gsd-plan-checker | プランがフェーズ目標を達成できるか検証（8 つの検証ディメンション）。 | `/gsd-plan-phase` (verification loop) | primary |
| gsd-integration-checker | クロスフェーズ統合とエンドツーエンドフローを検証。 | `/gsd-audit-milestone` | primary |
| gsd-ui-checker | UI-SPEC.md デザインコントラクトを品質ディメンションに対して検証。 | `/gsd-ui-phase` (validation loop) | primary |
| gsd-verifier | ゴール後退型分析によってフェーズ目標の達成を検証。 | `/gsd-execute-phase` | primary |
| gsd-nyquist-auditor | テストを生成して Nyquist バリデーションのギャップを埋める。 | `/gsd-validate-phase` | primary |
| gsd-ui-auditor | 実装済みフロントエンドコードの 6 本柱ビジュアル監査を遡及的に実施。 | `/gsd-ui-review` | primary |
| gsd-codebase-mapper | コードベースを探索して構造化分析ドキュメントを作成。 | `/gsd-map-codebase` | primary |
| gsd-debugger | 永続的な状態を持つ科学的手法でバグを調査。 | `/gsd-debug`, `/gsd-verify-work` | primary |
| gsd-user-profiler | 8 つのディメンションで開発者の行動をスコアリング。 | `/gsd-profile-user` | primary |
| gsd-doc-writer | プロジェクトドキュメントを作成・更新。 | `/gsd-docs-update` | primary |
| gsd-doc-verifier | 生成されたドキュメントの事実に基づくクレームを検証。 | `/gsd-docs-update` | primary |
| gsd-security-auditor | PLAN.md の脅威モデルから脅威への対策を検証。 | `/gsd-secure-phase` | primary |
| gsd-pattern-mapper | 新しいファイルを最も近い既存の類似物にマッピングし、プランナー向けの PATTERNS.md を作成。 | `/gsd-plan-phase` (between research and planning) | advanced stub |
| gsd-debug-session-manager | メインコンテキストをスリムに保つために、完全な `/gsd-debug` チェックポイントと継続ループを独立したコンテキストで実行。 | `/gsd-debug` | advanced stub |
| gsd-code-reviewer | バグ、セキュリティ問題、コード品質の問題についてソースファイルをレビューし、REVIEW.md を作成。 | `/gsd-code-review` | advanced stub |
| gsd-code-fixer | アトミックな修正コミットで REVIEW.md の指摘を適用し、REVIEW-FIX.md を作成。 | `/gsd-code-review --fix` | advanced stub |
| gsd-ai-researcher | 選択した AI フレームワークの公式ドキュメントを実装準備済みのガイダンス（AI-SPEC.md §3–§4b）に調査。 | `/gsd-ai-integration-phase` | advanced stub |
| gsd-domain-researcher | AI システムのドメイン専門家による評価基準と失敗モードを浮き上がらせる（AI-SPEC.md §1b）。 | `/gsd-ai-integration-phase` | advanced stub |
| gsd-eval-planner | AI フェーズの構造化された評価戦略を設計（AI-SPEC.md §5–§7）。 | `/gsd-ai-integration-phase` | advanced stub |
| gsd-eval-auditor | AI フェーズの評価カバレッジを遡及監査し、EVAL-REVIEW.md（COVERED/PARTIAL/MISSING）を作成。 | `/gsd-eval-review` | advanced stub |
| gsd-framework-selector | AI/LLM フレームワークをスコアリングして推奨する 6 問以内のインタラクティブな決定マトリクス。 | `/gsd-ai-integration-phase` | advanced stub |
| gsd-intel-updater | クエリ可能なコードベースナレッジベースとして使用される構造化インテルファイル（`.planning/intel/*.json`）を作成。 | `/gsd-map-codebase --query` | advanced stub |
| gsd-doc-classifier | 単一の計画ドキュメントを ADR、PRD、SPEC、DOC、UNKNOWN に分類し、ドキュメントコーパスを並列処理するために生成。 | `/gsd-ingest-docs` | advanced stub |
| gsd-doc-synthesizer | 分類された計画ドキュメントを優先規則、サイクル検出、3 バケット競合レポートで単一の統合コンテキストに合成。 | `/gsd-ingest-docs` | advanced stub |
**カバレッジ注記。** `docs/AGENTS.md` は 21 のプライマリエージェントに完全なロールカードを、12 の上級エージェントに簡潔なスタブを提供します。同ファイルのエージェントツール権限サマリーはプライマリ 21 エージェントのみをカバーします。上級エージェントのツール一覧は `agents/gsd-*.md` の各エージェントフロントマターに記載されています。
---
## コマンド (67 shipped)
完全な一覧は `commands/gsd/*.md` を参照してください。以下のグループ分けは `docs/COMMANDS.md` のセクション順に対応しています。各行にはコマンド名、コマンドのフロントマター `description:` から導出された一行の役割、ソースファイルへのリンクが含まれます。`tests/command-count-sync.test.cjs` がこの数値をファイルシステムに対して固定します。
### 名前空間メタスキル
これら 6 つのルーターは記述子専用のエントリーで、モデルが最初に選択します。各エントリーの本体には正しい具体的なサブスキルを指すルーティングテーブルが含まれています。積極的なスキル列挙のトークンコストを低く抑えながら、完全なサーフェスに到達可能にするために存在します。根拠は [#2792](https://github.com/open-gsd/gsd-core/issues/2792) を参照してください。ルーティングテーブルは [#2790](https://github.com/open-gsd/gsd-core/issues/2790) 以降の統合サーフェスを対象とします。
| コマンド | 役割 | ソース |
|----------|------|--------|
| `/gsd-workflow` | フェーズパイプラインルーター — discuss / plan / execute / verify / phase / progress。 | [commands/gsd/ns-workflow.md](../../commands/gsd/ns-workflow.md) |
| `/gsd-project` | プロジェクトライフサイクルルーター — マイルストーン、監査、サマリー。 | [commands/gsd/ns-project.md](../../commands/gsd/ns-project.md) |
| `/gsd-quality` | 品質ゲートルーター — コードレビュー、デバッグ、監査、セキュリティ、eval、UI。 | [commands/gsd/ns-review.md](../../commands/gsd/ns-review.md) |
| `/gsd-context` | コードベースインテリジェンスルーター — map、graphify、docs、learnings。 | [commands/gsd/ns-context.md](../../commands/gsd/ns-context.md) |
| `/gsd-manage` | 管理ルーター — config、workspace、workstreams、thread、update、ship、inbox。 | [commands/gsd/ns-manage.md](../../commands/gsd/ns-manage.md) |
| `/gsd-ideate` | 探索・キャプチャルーター — explore、sketch、spike、spec、capture。 | [commands/gsd/ns-ideate.md](../../commands/gsd/ns-ideate.md) |
### コアワークフロー
| コマンド | 役割 | ソース |
|----------|------|--------|
| `/gsd-new-project` | 深いコンテキスト収集と PROJECT.md で新しいプロジェクトを初期化。 | [commands/gsd/new-project.md](../../commands/gsd/new-project.md) |
| `/gsd-workspace` | GSD ワークスペースを管理 — 独立したワークスペース環境を作成（`--new`）、一覧表示（`--list`）、削除（`--remove`）。 | [commands/gsd/workspace.md](../../commands/gsd/workspace.md) |
| `/gsd-discuss-phase` | 計画前にアダプティブな質問でフェーズコンテキストを収集。 | [commands/gsd/discuss-phase.md](../../commands/gsd/discuss-phase.md) |
| `/gsd-mvp-phase` | フェーズを垂直 MVP スライスとして計画 — ユーザーストーリー、SPIDR 分割、その後 plan-phase。 | [commands/gsd/mvp-phase.md](../../commands/gsd/mvp-phase.md) |
| `/gsd-spec-phase` | 反証可能な要件を持つ SPEC.md を生成するソクラテス的仕様精緻化。 | [commands/gsd/spec-phase.md](../../commands/gsd/spec-phase.md) |
| `/gsd-ui-phase` | フロントエンドフェーズ向けの UI デザインコントラクト（UI-SPEC.md）を生成。 | [commands/gsd/ui-phase.md](../../commands/gsd/ui-phase.md) |
| `/gsd-ai-integration-phase` | フレームワーク選択、調査、eval 計画を経て AI デザインコントラクト（AI-SPEC.md）を生成。 | [commands/gsd/ai-integration-phase.md](../../commands/gsd/ai-integration-phase.md) |
| `/gsd-plan-phase` | 検証ループ付きの詳細なフェーズプラン（PLAN.md）を作成。 | [commands/gsd/plan-phase.md](../../commands/gsd/plan-phase.md) |
| `/gsd-plan-review-convergence` | クロス AI プラン収束ループ — HIGH の懸念がなくなるまでレビューフィードバックで再計画（最大 3 サイクル）。 | [commands/gsd/plan-review-convergence.md](../../commands/gsd/plan-review-convergence.md) |
| `/gsd-ultraplan-phase` | [BETA] フェーズ計画を Claude Code の ultraplan クラウドにオフロード — リモートで下書きし、ブラウザでレビューし、`/gsd-import` 経由でインポート。Claude Code のみ。 | [commands/gsd/ultraplan-phase.md](../../commands/gsd/ultraplan-phase.md) |
| `/gsd-spike` | 使い捨ての実験でアイデアを素早くスパイク。`--wrap-up` で調査結果を永続的なスキルとしてパッケージ化。 | [commands/gsd/spike.md](../../commands/gsd/spike.md) |
| `/gsd-sketch` | 使い捨ての HTML モックアップで UI/デザインアイデアを素早くスケッチ。`--wrap-up` で調査結果をパッケージ化。 | [commands/gsd/sketch.md](../../commands/gsd/sketch.md) |
| `/gsd-execute-phase` | ウェーブベースの並列化でフェーズのすべてのプランを実行。 | [commands/gsd/execute-phase.md](../../commands/gsd/execute-phase.md) |
| `/gsd-verify-work` | 自動診断付きの会話型 UAT で構築した機能を検証。 | [commands/gsd/verify-work.md](../../commands/gsd/verify-work.md) |
| `/gsd-ship` | 検証後に PR を作成し、レビューを実行してマージ準備を行う。 | [commands/gsd/ship.md](../../commands/gsd/ship.md) |
| `/gsd-fast` | サブエージェントや計画オーバーヘッドなしに些細なタスクをインラインで実行。 | [commands/gsd/fast.md](../../commands/gsd/fast.md) |
| `/gsd-quick` | GSD の保証（アトミックコミット、状態追跡）付きでクイックタスクを実行し、オプションのエージェントをスキップ。 | [commands/gsd/quick.md](../../commands/gsd/quick.md) |
| `/gsd-ui-review` | 実装済みフロントエンドコードの 6 本柱ビジュアル監査を遡及的に実施。 | [commands/gsd/ui-review.md](../../commands/gsd/ui-review.md) |
| `/gsd-code-review` | フェーズ中に変更されたソースファイルをバグ、セキュリティ、コード品質の問題についてレビュー。`--fix` で指摘を自動適用。 | [commands/gsd/code-review.md](../../commands/gsd/code-review.md) |
| `/gsd-eval-review` | 実行済み AI フェーズの評価カバレッジを遡及監査し、EVAL-REVIEW.md を作成。 | [commands/gsd/eval-review.md](../../commands/gsd/eval-review.md) |
### フェーズ & マイルストーン管理
| コマンド | 役割 | ソース |
|----------|------|--------|
| `/gsd-phase` | フェーズの CRUD — ROADMAP.md でフェーズを追加（デフォルト）、挿入（`--insert`）、削除（`--remove`）、編集（`--edit`）。 | [commands/gsd/phase.md](../../commands/gsd/phase.md) |
| `/gsd-add-tests` | UAT 基準と実装に基づいて完了したフェーズのテストを生成。 | [commands/gsd/add-tests.md](../../commands/gsd/add-tests.md) |
| `/gsd-validate-phase` | 完了したフェーズの Nyquist バリデーションのギャップを遡及監査して埋める。 | [commands/gsd/validate-phase.md](../../commands/gsd/validate-phase.md) |
| `/gsd-secure-phase` | 完了したフェーズの脅威への対策を遡及検証。 | [commands/gsd/secure-phase.md](../../commands/gsd/secure-phase.md) |
| `/gsd-audit-milestone` | アーカイブ前に元の意図に対してマイルストーン完了を監査。 | [commands/gsd/audit-milestone.md](../../commands/gsd/audit-milestone.md) |
| `/gsd-audit-uat` | 全未解決 UAT および検証項目のクロスフェーズ監査。 | [commands/gsd/audit-uat.md](../../commands/gsd/audit-uat.md) |
| `/gsd-audit-fix` | 自律監査-修正パイプライン — 問題の発見、分類、修正、テスト、コミット。 | [commands/gsd/audit-fix.md](../../commands/gsd/audit-fix.md) |
| `/gsd-complete-milestone` | 完了したマイルストーンをアーカイブし、次のバージョンに向けて準備。 | [commands/gsd/complete-milestone.md](../../commands/gsd/complete-milestone.md) |
| `/gsd-new-milestone` | 新しいマイルストーンサイクルを開始 — PROJECT.md を更新して要件にルーティング。 | [commands/gsd/new-milestone.md](../../commands/gsd/new-milestone.md) |
| `/gsd-milestone-summary` | マイルストーンアーティファクトから包括的なプロジェクトサマリーを生成。 | [commands/gsd/milestone-summary.md](../../commands/gsd/milestone-summary.md) |
| `/gsd-cleanup` | 完了したマイルストーンから蓄積されたフェーズディレクトリをアーカイブ。 | [commands/gsd/cleanup.md](../../commands/gsd/cleanup.md) |
| `/gsd-manager` | 1 つのターミナルから複数のフェーズを管理するインタラクティブなコマンドセンター。 | [commands/gsd/manager.md](../../commands/gsd/manager.md) |
| `/gsd-workstreams` | 並列ワークストリームを管理 — list、create、switch、status、progress、complete、resume。 | [commands/gsd/workstreams.md](../../commands/gsd/workstreams.md) |
| `/gsd-autonomous` | 残りのすべてのフェーズを自律的に実行 — フェーズごとに discuss → plan → execute。 | [commands/gsd/autonomous.md](../../commands/gsd/autonomous.md) |
| `/gsd-undo` | 安全な git リバート — フェーズマニフェストを使ってフェーズまたはプランのコミットをロールバック。 | [commands/gsd/undo.md](../../commands/gsd/undo.md) |
### セッション & ナビゲーション
| コマンド | 役割 | ソース |
|----------|------|--------|
| `/gsd-progress` | プロジェクトの進捗を確認し、コンテキストを表示して次のアクションにルーティング。`--next` で自動進行、`--do` で自由形式タスクを実行。 | [commands/gsd/progress.md](../../commands/gsd/progress.md) |
| `/gsd-capture` | アイデア、タスク、メモ、シードをキャプチャ — todo（デフォルト）、`--note`、`--backlog`、`--seed`、または `--list` で保留中の TODO を一覧表示。 | [commands/gsd/capture.md](../../commands/gsd/capture.md) |
| `/gsd-stats` | プロジェクト統計を表示 — フェーズ、プラン、要件、git メトリクス、タイムライン。 | [commands/gsd/stats.md](../../commands/gsd/stats.md) |
| `/gsd-pause-work` | フェーズ途中で作業を一時停止する際にコンテキスト引き継ぎを作成。 | [commands/gsd/pause-work.md](../../commands/gsd/pause-work.md) |
| `/gsd-resume-work` | 完全なコンテキスト復元で前のセッションから作業を再開。 | [commands/gsd/resume-work.md](../../commands/gsd/resume-work.md) |
| `/gsd-explore` | コミットする前にアイデアを考え抜くためのソクラテス的アイデア創出とアイデアルーティング。 | [commands/gsd/explore.md](../../commands/gsd/explore.md) |
| `/gsd-review-backlog` | バックログアイテムをレビューしてアクティブなマイルストーンに昇格。 | [commands/gsd/review-backlog.md](../../commands/gsd/review-backlog.md) |
| `/gsd-thread` | クロスセッション作業のための永続的なコンテキストスレッドを管理。 | [commands/gsd/thread.md](../../commands/gsd/thread.md) |
### コードベースインテリジェンス
| コマンド | 役割 | ソース |
|----------|------|--------|
| `/gsd-map-codebase` | 並列マッパーエージェントでコードベースを分析。`--fast` で軽量スキャン、`--query` でインテルクエリ。 | [commands/gsd/map-codebase.md](../../commands/gsd/map-codebase.md) |
| `/gsd-graphify` | `.planning/graphs/` 内のプロジェクトナレッジグラフをビルド、クエリ、検査。 | [commands/gsd/graphify.md](../../commands/gsd/graphify.md) |
| `/gsd-extract-learnings` | 完了したフェーズのアーティファクトから決定事項、教訓、パターン、驚きを抽出。 | [commands/gsd/extract-learnings.md](../../commands/gsd/extract-learnings.md) |
### レビュー、デバッグ & リカバリー
| コマンド | 役割 | ソース |
|----------|------|--------|
| `/gsd-review` | 外部 AI CLI からフェーズプランのクロス AI ピアレビューをリクエスト。 | [commands/gsd/review.md](../../commands/gsd/review.md) |
| `/gsd-debug` | コンテキストリセット全体で永続的な状態を持つ体系的なデバッグ。 | [commands/gsd/debug.md](../../commands/gsd/debug.md) |
| `/gsd-forensics` | 失敗した GSD ワークフローのポストモーテム調査 — git、アーティファクト、状態を分析。 | [commands/gsd/forensics.md](../../commands/gsd/forensics.md) |
| `/gsd-health` | 計画ディレクトリの健全性を診断し、任意で問題を修復。 | [commands/gsd/health.md](../../commands/gsd/health.md) |
| `/gsd-import` | プロジェクト決定に対する競合検出付きで外部プランをインジェスト。 | [commands/gsd/import.md](../../commands/gsd/import.md) |
| `/gsd-inbox` | プロジェクトテンプレートに対してすべてのオープンな GitHub イシューと PR をトリアージおよびレビュー。 | [commands/gsd/inbox.md](../../commands/gsd/inbox.md) |
### ドキュメント、プロファイル & ユーティリティ
| コマンド | 役割 | ソース |
|----------|------|--------|
| `/gsd-docs-update` | コードベースに対して検証されたプロジェクトドキュメントを生成または更新。 | [commands/gsd/docs-update.md](../../commands/gsd/docs-update.md) |
| `/gsd-ingest-docs` | リポジトリで混在した ADR/PRD/SPEC/DOC をスキャンし、分類・合成・競合レポートで `.planning/` セットアップをブートストラップまたはマージ。 | [commands/gsd/ingest-docs.md](../../commands/gsd/ingest-docs.md) |
| `/gsd-profile-user` | 開発者の行動プロファイルと Claude が検出可能なアーティファクトを生成。 | [commands/gsd/profile-user.md](../../commands/gsd/profile-user.md) |
| `/gsd-settings` | GSD ワークフロートグルとモデルプロファイルを設定。 | [commands/gsd/settings.md](../../commands/gsd/settings.md) |
| `/gsd-config` | GSD 設定を構成 — ワークフロートグル（デフォルト）、高度なノブ（`--advanced`）、インテグレーション（`--integrations`）、またはモデルプロファイル（`--profile`）。 | [commands/gsd/config.md](../../commands/gsd/config.md) |
| `/gsd-pr-branch` | `.planning/` コミットをフィルタリングしてクリーンな PR ブランチを作成。 | [commands/gsd/pr-branch.md](../../commands/gsd/pr-branch.md) |
| `/gsd-surface` | サーフェスに出るスキルを切り替え — 再インストールなしでプロファイルを適用、一覧表示、またはクラスターを無効化。 | [commands/gsd/surface.md](../../commands/gsd/surface.md) |
| `/gsd-update` | GSD を最新バージョンに更新。`--sync` でランタイム間でスキルを同期、`--reapply` でローカルパッチを再適用。 | [commands/gsd/update.md](../../commands/gsd/update.md) |
| `/gsd-help` | 利用可能な GSD コマンドと使い方ガイドを表示。 | [commands/gsd/help.md](../../commands/gsd/help.md) |
---
## ワークフロー (88 shipped)
完全な一覧は `get-shit-done/workflows/*.md` を参照してください。ワークフローはコマンドが内部で参照する薄いオーケストレーターです。ほとんどはエンドユーザーが直接読むものではありません。以下の行は各ワークフローファイルをその役割（`<purpose>` ブロックから導出）と、該当する場合はそれを呼び出すコマンドにマッピングします。
| ワークフロー | 役割 | 呼び出し元 |
|-------------|------|-----------|
| `add-backlog.md` | 999.x 番号付けを使って ROADMAP.md にバックログアイテムを追加。 | `/gsd-capture --backlog` |
| `add-phase.md` | ロードマップの現在のマイルストーン末尾に新しい整数フェーズを追加。 | `/gsd-phase` (default) |
| `add-tests.md` | フェーズのアーティファクトに基づいて完了したフェーズのユニットテストと E2E テストを生成。 | `/gsd-add-tests` |
| `add-todo.md` | セッション中に浮上したアイデアやタスクを構造化された todo としてキャプチャ。 | `/gsd-capture` (default) |
| `ai-integration-phase.md` | フレームワーク選択 → AI 調査 → ドメイン調査 → eval 計画を AI-SPEC.md に統合してオーケストレーション。 | `/gsd-ai-integration-phase` |
| `analyze-dependencies.md` | ROADMAP.md のフェーズをファイル重複とセマンティックな依存関係について分析し、`Depends on` エッジを提案。 | `/gsd-manager --analyze-deps` |
| `audit-fix.md` | 自律監査-修正パイプライン — 監査実行、解析、分類、修正、テスト、コミット。 | `/gsd-audit-fix` |
| `audit-milestone.md` | フェーズ検証を集約してマイルストーンが完了の定義を満たしているか検証。 | `/gsd-audit-milestone` |
| `audit-uat.md` | UAT と検証ファイルのクロスフェーズ監査。優先順位付けされた未解決項目リストを作成。 | `/gsd-audit-uat` |
| `autonomous.md` | マイルストーンのフェーズを自律的に進行 — 残り全部、範囲指定、または単一フェーズ。 | `/gsd-autonomous` |
| `check-todos.md` | 保留中の TODO を一覧表示し、選択を許可してコンテキストを読み込み、適切なアクションにルーティング。 | `/gsd-capture --list` |
| `cleanup.md` | 完了したマイルストーンから蓄積されたフェーズディレクトリをアーカイブ。 | `/gsd-cleanup` |
| `code-review-fix.md` | gsd-code-fixer を使って REVIEW.md の問題を修正ごとのアトミックコミットで自動修正。 | `/gsd-code-review --fix` |
| `code-review.md` | gsd-code-reviewer でフェーズのソース変更をレビュー。REVIEW.md を作成。 | `/gsd-code-review` |
| `complete-milestone.md` | 出荷されたバージョンを完了としてマーク — MILESTONES.md エントリー、PROJECT.md の進化、タグ。 | `/gsd-complete-milestone` |
| `diagnose-issues.md` | 並列デバッグエージェントをオーケストレーションして UAT のギャップを調査し、根本原因を特定。 | `/gsd-verify-work` (auto-diagnosis) |
| `discovery-phase.md` | 適切な深さレベルでディスカバリーを実行。 | `/gsd-new-project` (discovery path) |
| `discuss-phase-assumptions.md` | 仮定モードの discuss — コードベースファーストの分析で実装決定を抽出。 | `/gsd-discuss-phase` (when `discuss_mode=assumptions`) |
| `discuss-phase-power.md` | パワーユーザー discuss — すべての質問を JSON 状態ファイル + HTML UI に事前生成。 | `/gsd-discuss-phase --power` |
| `discuss-phase.md` | 反復的なグレーゾーンの議論を通じて実装決定を抽出。 | `/gsd-discuss-phase` |
| `mvp-phase.md` | フェーズを垂直 MVP スライスとして計画 — ユーザーストーリー、SPIDR 分割、その後 plan-phase。 | `/gsd-mvp-phase` |
| `do.md` | ユーザーからの自由形式テキストを最も適合する GSD コマンドにルーティング。 | `/gsd-progress --do` |
| `docs-update.md` | 正規のおよび手書きのプロジェクトドキュメントを生成、更新、検証。 | `/gsd-docs-update` |
| `edit-phase.md` | ROADMAP.md の既存フェーズの任意フィールドを番号と位置を保ちながら編集。 | `/gsd-phase --edit` |
| `eval-review.md` | 実装済み AI フェーズの評価カバレッジの遡及監査。 | `/gsd-eval-review` |
| `execute-phase.md` | ウェーブベースの並列実行でフェーズのすべてのプランを実行。 | `/gsd-execute-phase` |
| `execute-plan.md` | フェーズプロンプト（PLAN.md）を実行して成果サマリー（SUMMARY.md）を作成。 | `execute-phase.md` (per-plan subagent) |
| `explore.md` | ソクラテス的アイデア創出 — 開発者を探索的な質問を通じてガイド。 | `/gsd-explore` |
| `debug.md` | 体系的なデバッグ — サブコマンドルーティング、セッション作成、gsd-debug-session-manager への委任。 | `/gsd-debug` |
| `extract-learnings.md` | 完了したフェーズのアーティファクトから決定事項、教訓、パターン、驚きを抽出。 | `/gsd-extract-learnings` |
| `fast.md` | サブエージェントのオーバーヘッドなしに些細なタスクをインラインで実行。 | `/gsd-fast` |
| `forensics.md` | 失敗したワークフローのフォレンジクス調査 — git、アーティファクト、状態分析。 | `/gsd-forensics` |
| `graduation.md` | フェーズ横断で繰り返し出現する LEARNINGS.md アイテムをクラスタリングして HITL 昇格候補を浮き上がらせる。 | `transition.md` (graduation_scan step) |
| `health.md` | `.planning/` ディレクトリの整合性を検証し、対処可能な問題を報告。 | `/gsd-health` |
| `help.md` | 完全な GSD Core コマンドリファレンスを表示。 | `/gsd-help` |
| `import.md` | 既存のプロジェクト決定に対する競合検出付きで外部プランをインジェスト。 | `/gsd-import` |
| `inbox.md` | プロジェクトのコントリビューションテンプレートに対してオープンな GitHub イシューと PR をトリアージ。 | `/gsd-inbox` |
| `ingest-docs.md` | リポジトリで混在した計画ドキュメントをスキャンし、分類・合成して `.planning/` に競合レポート付きでブートストラップまたはマージ。 | `/gsd-ingest-docs` |
| `insert-phase.md` | マイルストーン途中で発見された緊急作業のために小数フェーズを挿入。 | `/gsd-phase --insert` |
| `list-phase-assumptions.md` | 計画前にフェーズに関する Claude の仮定を浮き上がらせる。 | `/gsd-discuss-phase --assumptions` |
| `list-workspaces.md` | `~/gsd-workspaces/` 内のすべての GSD ワークスペースをステータスとともに一覧表示。 | `/gsd-workspace --list` |
| `manager.md` | インタラクティブなマイルストーンコマンドセンター — ダッシュボード、インライン discuss、バックグラウンド plan/execute。 | `/gsd-manager` |
| `map-codebase.md` | 並列コードベースマッパーエージェントをオーケストレーションして `.planning/codebase/` ドキュメントを作成。 | `/gsd-map-codebase` |
| `milestone-summary.md` | マイルストーンサマリー合成 — マイルストーンアーティファクトからオンボーディングとレビューアーティファクトを作成。 | `/gsd-milestone-summary` |
| `new-milestone.md` | 新しいマイルストーンサイクルを開始 — プロジェクトコンテキストを読み込み、目標を収集して PROJECT.md/STATE.md を更新。 | `/gsd-new-milestone` |
| `new-project.md` | 統合新プロジェクトフロー — 質問、調査（任意）、要件、ロードマップ。 | `/gsd-new-project` |
| `new-workspace.md` | リポジトリのワークツリー/クローンと独立した `.planning/` を持つ独立したワークスペースを作成。 | `/gsd-workspace --new` |
| `next.md` | 現在のプロジェクト状態を検出して次の論理的なステップに自動的に進む。 | `/gsd-progress --next` |
| `node-repair.md` | タスク検証が失敗した場合の自律修復オペレーター。`execute-plan` から呼び出し。 | `execute-plan.md` (recovery) |
| `note.md` | ゼロフリクションのアイデアキャプチャ — 1 回の Write 呼び出しと 1 行の確認。 | `/gsd-capture --note` |
| `pause-work.md` | 構造化された `.planning/HANDOFF.json` と `.continue-here.md` 引き継ぎファイルを作成。 | `/gsd-pause-work` |
| `plan-phase.md` | 統合された調査と検証ループを含む実行可能な PLAN.md ファイルを作成。 | `/gsd-plan-phase`, `/gsd-quick` |
| `plan-review-convergence.md` | クロス AI プラン収束ループ — HIGH の懸念がなくなるまでレビューフィードバックで再計画。 | `/gsd-plan-review-convergence` |
| `plant-seed.md` | 先見的なアイデアをトリガー条件付きの構造化されたシードファイルとしてキャプチャ。 | `/gsd-capture --seed` |
| `pr-branch.md` | `.planning/` コミットをフィルタリングしてプルリクエスト用のクリーンなブランチを作成。 | `/gsd-pr-branch` |
| `profile-user.md` | 完全な開発者プロファイリングフローをオーケストレーション — 同意、セッションスキャン、プロファイル生成。 | `/gsd-profile-user` |
| `progress.md` | 進捗レンダリング — プロジェクトコンテキスト、位置、次のアクションルーティング。 | `/gsd-progress` |
| `quick.md` | GSD の保証付きのクイックタスク実行（アトミックコミット、状態追跡）。 | `/gsd-quick` |
| `reapply-patches.md` | GSD 更新後にローカルの変更を再適用。 | `/gsd-update --reapply` |
| `remove-phase.md` | ロードマップから将来のフェーズを削除し、後続フェーズを振り直し。 | `/gsd-phase --remove` |
| `remove-workspace.md` | GSD ワークスペースを削除してワークツリーをクリーンアップ。 | `/gsd-workspace --remove` |
| `resume-project.md` | 作業を再開 — STATE.md、HANDOFF.json、アーティファクトから完全なコンテキストを復元。 | `/gsd-resume-work` |
| `review.md` | 外部 CLI 経由のクロス AI プランレビュー。REVIEWS.md を作成。 | `/gsd-review` |
| `scan.md` | 迅速な単一フォーカスのコードベーススキャン — map-codebase の軽量代替。 | `/gsd-map-codebase --fast` |
| `secure-phase.md` | 完了したフェーズの遡及的な脅威対策監査。 | `/gsd-secure-phase` |
| `session-report.md` | セッションレポート — トークン使用量、作業サマリー、成果。 | `/gsd-pause-work --report` |
| `settings.md` | GSD ワークフロートグルとモデルプロファイルを設定。 | `/gsd-settings`, `/gsd-config --profile` |
| `settings-advanced.md` | GSD パワーユーザーノブを設定 — プランバウンス、タイムアウト、ブランチテンプレート、クロス AI 実行、ランタイムノブ。 | `/gsd-config --advanced` |
| `settings-integrations.md` | サードパーティ API キー（Brave/Firecrawl/Exa）、`review.models.<cli>` CLI ルーティング、`agent_skills.<agent-type>` インジェクションをマスク済み（`****<last-4>`）表示で設定。 | `/gsd-config --integrations` |
| `ship.md` | 検証後に PR を作成し、レビューを実行してマージ準備を行う。 | `/gsd-ship` |
| `sketch.md` | 1 スケッチにつき 2〜3 バリアントの使い捨て HTML モックアップでデザインの方向性を探索。 | `/gsd-sketch` |
| `sketch-wrap-up.md` | スケッチの調査結果を厳選して永続的な `sketch-findings-[project]` スキルとしてパッケージ化。 | `/gsd-sketch --wrap-up` |
| `spec-phase.md` | 曖昧さスコアリング付きのソクラテス的仕様精緻化。SPEC.md を作成。 | `/gsd-spec-phase` |
| `spike.md` | 集中した使い捨ての実験によって迅速に実現可能性を検証。 | `/gsd-spike` |
| `spike-wrap-up.md` | スパイクの調査結果を厳選して永続的な `spike-findings-[project]` スキルとしてパッケージ化。 | `/gsd-spike --wrap-up` |
| `stats.md` | プロジェクト統計レンダリング — フェーズ、プラン、要件、git メトリクス。 | `/gsd-stats` |
| `sync-skills.md` | クロスランタイム GSD スキル同期 — ランタイムルート間で `gsd-*` スキルディレクトリを差分して適用。 | `/gsd-update --sync` |
| `transition.md` | フェーズ境界遷移ワークフロー — ワークストリームチェック、状態進行。 | `execute-phase.md`, `/gsd-progress --next` |
| `ui-phase.md` | gsd-ui-researcher で UI-SPEC.md デザインコントラクトを生成。 | `/gsd-ui-phase` |
| `ui-review.md` | gsd-ui-auditor による遡及的な 6 本柱ビジュアル監査。 | `/gsd-ui-review` |
| `ultraplan-phase.md` | [BETA] 計画を Claude Code の ultraplan クラウドにオフロードし、リモートで下書きして `/gsd-import` 経由でインポート。 | `/gsd-ultraplan-phase` |
| `undo.md` | 安全な git リバート — フェーズマニフェストを使ってフェーズまたはプランのコミットをロールバック。 | `/gsd-undo` |
| `thread.md` | クロスセッション作業のための永続的なコンテキストスレッドを作成、一覧表示、クローズ、または再開。 | `/gsd-thread` |
| `update.md` | 変更履歴の表示付きで GSD を最新バージョンに更新。 | `/gsd-update` |
| `validate-phase.md` | 完了したフェーズの Nyquist バリデーションのギャップを遡及監査して埋める。 | `/gsd-validate-phase` |
| `verify-phase.md` | ゴール後退型分析によってフェーズ目標の達成を検証。 | `execute-phase.md` (post-execution) |
| `verify-work.md` | 自動診断付きの会話型 UAT — UAT.md と修正プランを作成。 | `/gsd-verify-work` |
> **注記:** 一部のワークフローには直接ユーザー向けのコマンドがありません（例: `execute-plan.md`、`verify-phase.md`、`transition.md`、`node-repair.md`、`diagnose-issues.md`）— これらはオーケストレーターワークフローによって内部的に呼び出されます。`discovery-phase.md` は `/gsd-new-project` の代替エントリーポイントです。
---
## リファレンス (62 shipped)
完全な一覧は `get-shit-done/references/*.md` を参照してください。リファレンスはワークフローとエージェントが `@-reference` として参照する共有ナレッジドキュメントです。以下のグループ分けは [`docs/ARCHITECTURE.md`](../ARCHITECTURE.md#references-get-shit-donereferencesmd) に対応します — コア、ワークフロー、思考モデルクラスター、モジュラープランナー分解。
### コアリファレンス
| リファレンス | 役割 |
|-------------|------|
| `checkpoints.md` | チェックポイントタイプの定義とインタラクションパターン。 |
| `gates.md` | plan-checker と verifier に組み込まれた 4 つの標準ゲートタイプ（Confirm、Quality、Safety、Transition）。 |
| `model-profiles.md` | エージェントごとのモデルティア割り当て。 |
| `model-profile-resolution.md` | モデル解決アルゴリズムのドキュメント。 |
| `verification-patterns.md` | 異なるアーティファクトタイプの検証方法。 |
| `verification-overrides.md` | アーティファクトごとの検証オーバーライドルール。 |
| `planning-config.md` | 完全な設定スキーマと動作。 |
| `git-integration.md` | git コミット、ブランチ、履歴パターン。 |
| `git-planning-commit.md` | 計画ディレクトリのコミット規約。 |
| `questioning.md` | プロジェクト初期化のためのドリーム抽出哲学。 |
| `tdd.md` | テスト駆動開発の統合パターン。 |
| `ui-brand.md` | ビジュアル出力フォーマットパターン。 |
| `common-bug-patterns.md` | コードレビューと検証のための一般的なバグパターン。 |
| `debugger-philosophy.md` | `gsd-debugger` が読み込む常緑のデバッグ規律。 |
| `mandatory-initial-read.md` | エージェントプロンプトに注入される共有の必読ボイラープレート。 |
| `project-skills-discovery.md` | エージェントプロンプトに注入される共有のプロジェクトスキル検出ボイラープレート。 |
### ワークフローリファレンス
| リファレンス | 役割 |
|-------------|------|
| `agent-contracts.md` | オーケストレーターとエージェント間の正式なインターフェース。 |
| `context-budget.md` | コンテキストウィンドウバジェット割り当てルール。 |
| `continuation-format.md` | セッション継続/再開フォーマット。 |
| `domain-probes.md` | discuss-phase 向けのドメイン固有のプロービング質問。 |
| `gate-prompts.md` | ゲート/チェックポイントのプロンプトテンプレート。 |
| `scout-codebase.md` | discuss-phase スカウトステップ向けのフェーズタイプ→コードベースマップ選択テーブル（#2551 で抽出）。 |
| `revision-loop.md` | プラン修正の反復パターン。 |
| `universal-anti-patterns.md` | 検出して避けるべきユニバーサルアンチパターン。 |
| `worktree-path-safety.md` | ワークツリーガードスイート: HEAD アサーション、cwd ドリフトセンチネル（ステップ 0a、#3097）、絶対パスガード（ステップ 0b、#3099）— `<execution_context>` 経由でエグゼキュータースポーンプロンプトに読み込まれる。 |
| `artifact-types.md` | 計画アーティファクトタイプの定義。 |
| `phase-argument-parsing.md` | フェーズ引数の解析規約。 |
| `decimal-phase-calculation.md` | 小数サブフェーズの番号付けルール。 |
| `workstream-flag.md` | ワークストリームアクティブポインター規約（`--ws`）。 |
| `user-profiling.md` | ユーザー行動プロファイリングの検出ヒューリスティック。 |
| `thinking-partner.md` | 意思決定ポイントでの条件付き思考パートナー起動。 |
| `autonomous-smart-discuss.md` | 自律モード向けのスマート discuss ロジック。 |
| `ios-scaffold.md` | iOS アプリケーションスキャフォールディングパターン。 |
| `ai-evals.md` | `/gsd-ai-integration-phase` 向けの AI 評価設計リファレンス。 |
| `ai-frameworks.md` | `gsd-framework-selector` 向けの AI フレームワーク決定マトリクスリファレンス。 |
| `executor-examples.md` | gsd-executor エージェントの実例。 |
| `doc-conflict-engine.md` | ingest/import ワークフロー向けの共有競合検出コントラクト。 |
| `execute-mvp-tdd.md` | MVP+TDD での execute-phase のランタイムゲートセマンティクス — タスク前の失敗テスト検証、フェーズ末尾のブロッキングレビュー。 |
| `mvp-concepts.md` | 6 つの MVP 関連リファレンスファイルのクロスリファレンスインデックス。各ファイルの目的とどのワークフローが読み込むかをマッピング。 |
| `verify-mvp-mode.md` | MVP モードフェーズの UAT フレーミングルール — ユーザーフローファーストの順序、延期された技術チェック、ユーザーストーリーフォーマットガード。 |
### スケッチリファレンス
`/gsd-sketch` ワークフローとその wrap-up コンパニオンが使用するリファレンス。
| リファレンス | 役割 |
|-------------|------|
| `sketch-interactivity.md` | HTML スケッチをインタラクティブで生き生きとさせるためのルール。 |
| `sketch-theme-system.md` | クロススケッチの一貫性のための共有 CSS テーマ変数システム。 |
| `sketch-tooling.md` | すべてのスケッチに含まれるフローティングツールバーユーティリティ。 |
| `sketch-variant-patterns.md` | マルチバリアント HTML パターン（タブ、並排表示、オーバーレイ）。 |
### 思考モデルリファレンス
思考クラスモデル（o3、o4-mini、Gemini 2.5 Pro）を GSD ワークフローに統合するためのリファレンス。
| リファレンス | 役割 |
|-------------|------|
| `thinking-models-debug.md` | デバッグワークフロー向けの思考モデルパターン。 |
| `thinking-models-execution.md` | 実行エージェント向けの思考モデルパターン。 |
| `thinking-models-planning.md` | 計画エージェント向けの思考モデルパターン。 |
| `thinking-models-research.md` | 調査エージェント向けの思考モデルパターン。 |
| `thinking-models-verification.md` | 検証エージェント向けの思考モデルパターン。 |
### モジュラープランナー分解
`gsd-planner` エージェントは、ランタイムの文字数制限に収めるためにコアエージェントとリファレンスモジュールに分解されます。
| リファレンス | 役割 |
|-------------|------|
| `planner-antipatterns.md` | プランナーのアンチパターンと具体性の例。 |
| `planner-chunked.md` | チャンクモードの戻り形式（`## OUTLINE COMPLETE`、`## PLAN COMPLETE`）— Windows stdio ハングの緩和策。 |
| `planner-gap-closure.md` | ギャップクロージャーモードの動作（VERIFICATION.md を読み込み、ターゲットを絞った再計画）。 |
| `planner-reviews.md` | クロス AI レビュー統合（`/gsd-review` からの REVIEWS.md を読み込み）。 |
| `planner-revision.md` | 反復的な精緻化のためのプラン修正パターン。 |
| `planner-source-audit.md` | プランナーのソース監査と権威制限ルール。 |
| `planner-mvp-mode.md` | MVP モード向けの垂直スライス計画ルール。 |
| `planner-human-verify-mode.md` | `workflow.human_verify_mode = end-of-phase` のルール: `checkpoint:human-verify` タスク発行を抑制し、延期された項目を `<verify><human-check>` 経由でルーティング。 |
| `planner-graphify-auto-update.md` | `load_graph_context` が既存の鮮度アノテーションに加えて `.last-build-status.json` の自動更新状態（running / failed / stale head）をどのように表示するか。`graphify.auto_update` でオプトイン（#3347）。 |
| `planner-interface-context.md` | エグゼキューター向けのインターフェースコンテキストルール — 既存コードから主要なインターフェース/型/エクスポートを抽出する方法と、下流のプランが使用する新しいインターフェースのドキュメント化方法。 |
| `skeleton-template.md` | 新プロジェクトのウォーキングスケルトン（フェーズ 1 + `--mvp`）用に出力される SKELETON.md テンプレート。 |
| `user-story-template.md` | MVP 計画向けのユーザーストーリーフォーマット — "As a / I want to / So that" の構造化フィールド。 |
| `spidr-splitting.md` | MVP モードで大きなユーザーストーリーを処理するための SPIDR 分割ルール。 |
> **サブディレクトリ:** `get-shit-done/references/few-shot-examples/` には、特定のエージェントから参照される追加のフューショット例（`plan-checker.md`、`verifier.md`）が含まれます。これらは 62 のトップレベルリファレンスにはカウントされません。
---
## CLI モジュール (81 shipped)
完全な一覧: `get-shit-done/bin/lib/*.cjs`。
| モジュール | 責務 |
|-----------|------|
| `active-workstream-store.cjs` | ワークストリームソースの優先度と選択（CLI `--ws` > `GSD_WORKSTREAM` 環境変数 > 保存済みポインター）、名前のバリデーションと環境への伝播 |
| `adr-parser.cjs` | plan-phase インジェストエクスプレスパス向けの ADR 決定パーサー。セクションの同義語を正規化し、ステータス/決定/スコープフェンスを解析して、ステータス拒否ゲートを適用 |
| `agent-command-router.cjs` | `gsd-tools agent` 向けの薄い CJS サブコマンドルーターアダプター |
| `artifacts.cjs` | 標準的なアーティファクトレジストリ — 既知の `.planning/` ルートファイル名。`gsd-health` W019 リントで使用 |
| `audit.cjs` | 監査ディスパッチ、監査オープンセッション、監査ストレージヘルパー |
| `check-command-router.cjs` | `gsd-tools check` 向けの薄い CJS サブコマンドルーターアダプター |
| `cjs-command-router-adapter.cjs` | マニフェストバックの CJS コマンドファミリールーター向けの共有互換アダプター |
| `clock.cjs` | 決定論的なロックテスト向けの注入可能なクロックシーム（now/sleep） |
| `clusters.cjs` | ランタイムサーフェスモジュール向けのスキルクラスター定義（ADR-0011 フェーズ 2） |
| `code-review-flags.cjs` | `/gsd:code-review` 向けの型付きフラグパーサー。`parseCodeReviewFlags(argv)`（→ `{ fix, all, auto, depth, files }`）と `resolveCodeReviewWorkflow(flags)`（→ `'code-review.md' \| 'code-review-fix.md'`）をエクスポート。`--fix`/`--all`/`--auto` ルーティングの標準ディスパッチシーム |
| `command-aliases.cjs` | マニフェストバックのファミリールーター向けのエイリアス/サブコマンドメタデータ |
| `command-arg-projection.cjs` | コマンドファミリールーター間で共有される型付きフラグと位置引数のプロジェクションヘルパー |
| `command-routing-hub.cjs` | すべてのコマンドファミリールーターのモード決定（SDK vs CJS）、エラー分類、ノースロー契約を一元化する純粋結果ディスパッチハブ（#3788） |
| `commands.cjs` | その他の CLI コマンド（slug、タイムスタンプ、TODO、スキャフォールディング、統計） |
| `config-schema.cjs` | `VALID_CONFIG_KEYS` と動的キーパターンの単一ソース。バリデーターと config-schema-docs パリティテストの両方でインポートされる |
| `config.cjs` | `config.json` の読み書き、セクション初期化。`config-schema.cjs` からバリデーターをインポート |
| `config-types.cjs` | `model_policy` 設定ブロックの TypeScript 型定義 — `ModelPolicyConfig`、`TierEntry`、`RuntimeTiers`。発行時に `src/config-types.cts` からコンパイル（ADR-457） |
| `configuration.cjs` | 設定モジュール — 標準的な設定読み込み、レガシーキー正規化、デフォルトマージ、明示的なディスク上のマイグレーション。SDK と CJS 両方のコンシューマーの信頼できるソース |
| `context-utilization.cjs` | `gsd-health --context` 向けの純粋なクラシファイアー — （tokensUsed, contextWindow）を 60%/70% の骨折点閾値に対する `{ percent, state }` トリアージ結果に変換（#2792） |
| `core.cjs` | エラー処理、出力フォーマット、共通ユーティリティ、ランタイムフォールバック。planning-workspace ヘルパーの互換性再エクスポート |
| `decisions.cjs` | CONTEXT.md の `<decisions>` ブロックを解析。数値（D-42）と英数字（D-INFRA-01）の ID を受け付け。`{id, text, category, tags, trackable}` を返す |
| `docs.cjs` | docs-update ワークフロー初期化、Markdown スキャン、モノリポ検出 |
| `drift.cjs` | 実行後のコードベース構造ドリフト検出器（#2003）: ファイル変更を new-dir/barrel/migration/route カテゴリに分類し、`last_mapped_commit` フロントマターをラウンドトリップ |
| `fallow-runner.cjs` | `/gsd-code-review` 向けのファロー監査アダプター: バイナリ解決（`PATH` 次に `node_modules/.bin`）、アクション可能なバイナリ欠落エラー、構造的な調査結果の正規化 |
| `frontmatter.cjs` | YAML フロントマター CRUD 操作 |
| `gap-checker.cjs` | 計画後のギャップ分析（#2493）: REQUIREMENTS.md + CONTEXT.md 決定事項 vs PLAN.md カバレッジレポート（`gsd-tools gap-analysis`）の統合 |
| `graphify.cjs` | `/gsd-graphify` 向けのナレッジグラフビルド/クエリ/ステータス/差分 |
| `gsd2-import.cjs` | `/gsd-import --from-gsd2` 向けの外部プランインジェスト |
| `init-command-router.cjs` | `gsd-tools init` 向けの薄い CJS サブコマンドルーターアダプター |
| `init.cjs` | 各ワークフロータイプの複合コンテキスト読み込み |
| `install-profiles.cjs` | `--minimal` インストール向けのインストールプロファイル許可リスト + スキルステージング（#2762）。どの `gsd-*` スキル/エージェントがランタイム設定ディレクトリに配置されるかの単一ソース |
| `installer-migration-authoring.cjs` | レコードメタデータ、明示的スコープ、所有権の証拠、ランタイムコントラクト引用のインストーラーマイグレーション作成ガードレール |
| `installer-migration-report.cjs` | インストール/更新統合向けのインストーラーマイグレーションレポートプロジェクションとブロックアクションガード |
| `installer-migrations.cjs` | インストーラーマイグレーション計画、アーティファクト分類、インストール状態の永続化、ジャーナル化された適用、ロールバックヘルパー |
| `intel.cjs` | `/gsd-map-codebase --query` と `gsd-intel-updater` を支えるコードベースインテルストア |
| `learnings.cjs` | `/gsd-extract-learnings` 向けのクロスフェーズ学習抽出 |
| `milestone.cjs` | マイルストーンアーカイブ、要件マーキング |
| `model-catalog.cjs` | 共有モデルカタログ JSON の CJS アダプター。すべての CLI コンシューマーの標準ランタイムティアデフォルト、エージェントプロファイルマップ、エイリアスマップ、ルーティングメタデータをエクスポート |
| `model-profiles.cjs` | `model-catalog.cjs` から派生した後方互換プロファイルヘルパー。独自のモデルテーブルは持たない |
| `package-identity.cjs` | GSD の公開パッケージ座標（npm 名、bin 名、リポジトリスラッグ、変更履歴 URL、手動インストールコマンド）の生成された単一ソース。package.json から導出。更新ワーカー、`check-latest-version`、インストーラーが読み込む（#498） |
| `phase-command-router.cjs` | `gsd-tools phase` 向けの薄い CJS サブコマンドルーターアダプター |
| `phase-lifecycle.cjs` | フェーズライフサイクル SDK ハンドラーから抽出された純粋計算フェーズライフサイクルヘルパー |
| `phase.cjs` | フェーズディレクトリ操作、小数番号付け、プランインデックス化 |
| `phases-command-router.cjs` | `gsd-tools phases` 向けの薄い CJS サブコマンドルーターアダプター |
| `plan-scan.cjs` | フラットおよびネストされたレイアウトでプランとサマリーファイルを検出するための標準フェーズプランスキャナー（k014） |
| `planning-workspace.cjs` | 計画パス/ワークストリームシーム（`planningDir`、`planningPaths`、アクティブワークストリームルーティング、`.planning/.lock` オーケストレーション） |
| `project-root.cjs` | 4 つのヒューリスティック（独自の `.planning/` ガード、`sub_repos` 設定、`multiRepo` フラグ、`.git` ヒューリスティック）を使って開始ディレクトリからプロジェクトルートを解決 |
| `profile-output.cjs` | プロファイルレンダリング、USER-PROFILE.md と dev-preferences.md の生成 |
| `profile-pipeline.cjs` | ユーザー行動プロファイリングデータパイプライン、セッションファイルスキャン |
| `prompt-budget.cjs` | レビュープロンプト向けの純粋なトークンバジェット計算 — トークンを見積もり、決定論的なトリム優先度を適用（PROJECT.md の head 縮小、比例プラン切り捨て、コンテキスト/調査/要件の削除、ハードフェイルガード）。`review.max_prompt_tokens` 向けの構造化メタデータを返す（#3081） |
| `review-reviewer-selection.cjs` | `/gsd-review` デフォルトレビュアーポリシーと優先度向けのレビュアー選択/正規化ヘルパー |
| `roadmap-command-router.cjs` | `gsd-tools roadmap` 向けの薄い CJS サブコマンドルーターアダプター |
| `roadmap-upgrade.cjs` | レガシーの `Phase N` エントリーをマイルストーンプレフィックス付きの `Phase M-NN` 規約に変換するマイグレーションツール。`computeMigrationPlan` + `applyMigration`（デフォルトのドライランとアトミックロールバック付き） |
| `roadmap.cjs` | ROADMAP.md 解析、フェーズ抽出、プラン進捗 |
| `runtime-artifact-layout.cjs` | ランタイムアーティファクトレイアウトモジュール — サポートされている各ランタイムのアーティファクトディレクトリ形状（コマンド、エージェント、スキル）を解決。ランタイムごとのアーティファクト配置の単一ソース（#3663） |
| `runtime-name-policy.cjs` | ランタイム名正規化ポリシー — パス構築と表示に使用されるランタイム識別子の標準トークンサニタイゼーション |
| `runtime-homes.cjs` | 標準ランタイム → グローバル設定/スキルディレクトリマッピング。Hermes ネストレイアウトと Cline ルールベース除外を含む全 15 ランタイムの一流サポート（#3126） |
| `runtime-slash.cjs` | ランタイム対応スラッシュコマンドフォーマッター — ユーザー向け出力と永続化されたアーティファクトで `/gsd-<cmd>`（スキルベースのランタイム）と `$gsd-<cmd>`（codex）を出力する単一ソース（#3584） |
| `schema-detect.cjs` | ORM パターンのスキーマドリフト検出（Prisma、Drizzle、Supabase、TypeORM、Payload）。`detectSchemaFiles`、`detectSchemaOrm`、`checkSchemaDrift`、`SCHEMA_PATTERNS`、`ORM_INFO` をエクスポート |
| `secrets.cjs` | インテグレーションキー向けのシークレット設定マスキング規約（`****<last-4>`）。`SECRET_CONFIG_KEYS`、`isSecretKey`、`maskSecret`、`maskIfSecret` をエクスポート |
| `semver-compare.cjs` | 共有 semver 比較ポリシーヘルパー（`compareSemverCore`、stable-triplet バリデーション、正規化タプル解析）。更新チェックフック、statusline dev-install 検出、changeset 抽出範囲ロジックで使用（#10） |
| `security.cjs` | パストラバーサル防止、プロンプトインジェクション検出、安全な JSON/シェルヘルパー |
| `shell-command-projection.cjs` | マネージドフック直列化のためのランタイム対応シェルコマンドプロジェクション: ランタイム/プラットフォームによる PowerShell コールオペレーターの使用を決定し、Windows スクリプトパストークンを正規化 |
| `state-command-router.cjs` | `gsd-tools state` 向けの薄い CJS サブコマンドルーターアダプター |
| `state.cjs` | STATE.md 解析、更新、進行、メトリクス |
| `state-document.cjs` | 純粋な STATE.md フィールド抽出、置換、ステータス正規化、進捗計算トランスフォーム |
| `surface.cjs` | ランタイムサーフェスモジュール — インストール時プロファイルマーカーとは独立してランタイムの有効/無効サーフェス状態を管理（ADR-0011 フェーズ 2） |
| `task-command-router.cjs` | `gsd-tools task` 向けの薄い CJS サブコマンドルーターアダプター |
| `template.cjs` | 変数置換によるテンプレート選択と穴埋め |
| `uat.cjs` | UAT ファイル解析、検証負債追跡、audit-uat サポート |
| `ui-safety-gate.cjs` | シェルフリーのワード境界 UI トークン検出器（#3706、#3718）。フェーズセクションテキストを標準入力から読み込み、0（UI 発見）または 1（UI なし）で終了。GSD インストーラーが `$RUNTIME_DIR` に配布するために `get-shit-done/bin/lib/` にもデプロイ（#448） |
| `update-context.cjs` | `/gsd:update` 向けの純粋なインストールコンテキストリゾルバー — ランタイム/スコープ/設定ディレクトリ/バージョン検出（LOCAL/GLOBAL/UNKNOWN）。update.md bash からポート。`gsd-tools update-context` を支える（#498） |
| `validate-command-router.cjs` | `gsd-tools validate` 向けの薄い CJS サブコマンドルーターアダプター |
| `validate.cjs` | 純粋なフェーズバリアント正規化ヘルパー（`phaseVariants`、`buildRoadmapPhaseVariants`、`buildNotStartedPhaseVariants`）。`verify.cjs` の W006/W007 チェックで使用。I/O なし、非同期なし |
| `verify-command-router.cjs` | `gsd-tools verify` 向けの薄い CJS サブコマンドルーターアダプター |
| `verify.cjs` | プラン構造、フェーズ完全性、参照、コミットバリデーション |
| `workstream-inventory-builder.cjs` | 純粋なワークストリームインベントリプロジェクションビルダー |
| `workstream-inventory.cjs` | 共有ワークストリームインベントリプロジェクション: 状態フィールド、フェーズ/プラン/サマリーカウント、ロードマップフェーズカウント、アクティブマーカー — 純粋なプロジェクションを `workstream-inventory-builder.cjs` に委任する薄いオーケストレーター |
| `workstream-name-policy.cjs` | 標準ワークストリーム名バリデーション（`isValidActiveWorkstreamName`、`hasInvalidPathSegment`、`validateWorkstreamName`）とスラッグ正規化（`toWorkstreamSlug`） |
| `workstream.cjs` | ワークストリーム CRUD、マイグレーション、セッションスコープのアクティブポインター |
| `worktree-safety.cjs` | ワークツリールート解決と非破壊的プルーンポリシー決定。W017 ヘルスチェックロジックを所有 |
[`docs/CLI-TOOLS.md`](../CLI-TOOLS.md) はこれらのモジュールのサブセットを説明している場合があります。ファイルシステムと異なる場合は、このテーブルとディレクトリ一覧が正式です。
---
## フック (14 shipped)
完全な一覧: `hooks/`。
| フック | イベント | 目的 |
|--------|---------|------|
| `gsd-statusline.js` | `statusLine` | モデル、タスク、ディレクトリ、コンテキスト使用率を表示 |
| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | 残量 35%/25% でエージェント向けコンテキスト警告を注入 |
| `gsd-check-update.js` | `SessionStart` | 新しい GSD バージョンのバックグラウンドチェック |
| `gsd-check-update-worker.js` | (worker) | check-update のバックグラウンドワーカーヘルパー |
| `gsd-update-banner.js` | `SessionStart` | GSD statusline を使用していない場合に更新の可用性を表示するオプトインバナー（PR #2795） |
| `gsd-prompt-guard.js` | `PreToolUse` | `.planning/` への書き込みのプロンプトインジェクションパターンをスキャン（アドバイザリー） |
| `gsd-workflow-guard.js` | `PreToolUse` | GSD ワークフローコンテキスト外のファイル編集を検出（アドバイザリー、オプトイン） |
| `gsd-read-guard.js` | `PreToolUse` | 未読ファイルへの Edit/Write を防ぐアドバイザリーガード |
| `gsd-read-injection-scanner.js` | `PostToolUse` | ツール Read 結果のプロンプトインジェクションパターンをスキャン（v1.36+、PR #2201） |
| `gsd-worktree-path-guard.js` | `PreToolUse` | ワークツリールート外の絶対パスを持つ Edit/Write/MultiEdit をハードブロック（PR #579、#260） |
| `gsd-session-state.sh` | `PostToolUse` | シェルベースランタイム向けのセッション状態追跡 |
| `gsd-validate-commit.sh` | `PostToolUse` | Conventional Commit 適用のためのコミットバリデーション |
| `gsd-phase-boundary.sh` | `PostToolUse` | ワークフロー遷移のためのフェーズ境界検出 |
| `gsd-graphify-update.sh` | `PostToolUse` | メイン HEAD が進んだ後にナレッジグラフを自動再ビルド（オプトイン、デフォルトオフ — #3347） |
---
## メンテナンス
- 新しいコマンド、エージェント、ワークフロー、リファレンス、CLI モジュール、またはフックが出荷される際は、リリース前に対応するセクションをここで更新してください。
- `tests/` 配下のドリフトガードテスト（上記「このファイルの使い方」を参照）は、出荷されたすべてのファイルがこのインベントリに列挙されていることをアサートします。対応する行のない新しいファイルは CI で失敗します。
- ファイルシステムが `docs/ARCHITECTURE.md` の数値や厳選されたサブセットドキュメント（例: `docs/AGENTS.md` のプライマリロスター）と乖離した場合は、このファイルが正式なソースです。
## Related
- [Commands](COMMANDS.md) — ユーザー向けコマンドリファレンス
- [Architecture](ARCHITECTURE.md) — サーフェスがどのように組み合わさるか
- [docs index](README.md)

84
docs/ja-JP/README.md
View File

@@ -1,27 +1,69 @@
# GSD Core ドキュメント
GSD Core（Git. Ship. Done.）の包括的なドキュメントです。GSD Core は、AI コーディングエージェント向けのメタプロンプティング、コンテキストエンジニアリング、仕様駆動開発システムです。
ドキュメントは 4 つの象限で構成されています。**チュートリアル**は実践で学ぶ、**ハウツーガイド**は特定のタスクを解決する、**リファレンス**は信頼できる情報を示す、**解説**はコンセプトと設計上の決定を探求する。
## ドキュメント一覧
言語バージョン: [English](../) · [Português (pt-BR)](../pt-BR/README.md) · **日本語** · [简体中文](../zh-CN/README.md) · [한국어](../ko-KR/README.md)
| ドキュメント | 対象読者 | 説明 |
|------------|---------|------|
| [アーキテクチャ](ARCHITECTURE.md) | コントリビューター、上級ユーザー | システムアーキテクチャ、エージェントモデル、データフロー、内部設計 |
| [機能リファレンス](FEATURES.md) | 全ユーザー | 全機能の詳細ドキュメントと要件 |
| [コマンドリファレンス](COMMANDS.md) | 全ユーザー | 全コマンドの構文、フラグ、オプション、使用例 |
| [設定リファレンス](CONFIGURATION.md) | 全ユーザー | 設定スキーマ、ワークフロートグル、モデルプロファイル、Git ブランチ |
| [CLI ツールリファレンス](CLI-TOOLS.md) | コントリビューター、エージェント作成者 | CJS `gsd-tools.cjs` と `gsd-tools.cjs query` 가이드 のガイド |
| [エージェントリファレンス](AGENTS.md) | コントリビューター、上級ユーザー | 全18種の専門エージェント — 役割、ツール、スポーンパターン |
| [ユーザーガイド](USER-GUIDE.md) | 全ユーザー | ワークフローのウォークスルー、トラブルシューティング、リカバリー |
| [コンテキストモニター](context-monitor.md) | 全ユーザー | コンテキストウィンドウ監視フックのアーキテクチャ |
| [ディスカスモード](workflow-discuss-mode.md) | 全ユーザー | discuss フェーズにおける assumptions モードと interview モード |
---
## クイックリンク
## チュートリアル
- **v1.39 の新機能:** `--minimal` インストールプロファイル（≥94% コールドスタート削減）、`/gsd-phase --edit`、マージ後ビルド & テストゲート、`review.models.<cli>` ランタイム別レビューモデル、ワークストリーム設定の継承、手動カナリアリリースワークフロー、スキル統合（86 → 59）
- **はじめに:** [README](../README.md) → インストール → `/gsd-new-project`
- **ワークフロー完全ガイド:** [ユーザーガイド](USER-GUIDE.md)
- **コマンド一覧:** [コマンドリファレンス](COMMANDS.md)
- **GSD の設定:** [設定リファレンス](CONFIGURATION.md)
- **システム内部の仕組み:** [アーキテクチャ](ARCHITECTURE.md)
- **コントリビュートや拡張:** [CLI ツールリファレンス](CLI-TOOLS.md) + [エージェントリファレンス](AGENTS.md)
- [はじめてのプロジェクト](tutorials/your-first-project.md) — インストールから最初のフェーズ出荷まで、確実な一本道
- [既存コードベースのオンボーディング](tutorials/onboarding-an-existing-codebase.md) — ブラウンフィールドのリポジトリに GSD Core を導入する
---
## How-to guides
- [ランタイムへのインストール](how-to/install-on-your-runtime.md) — サポートされる全 15 ランタイムのランタイム別インストール手順
- [フェーズを議論する](how-to/discuss-a-phase.md) — 計画を始める前に実装上の決定事項を記録する
- [フェーズを計画する](how-to/plan-a-phase.md) — リサーチを実行し、作業を分解し、計画の品質を検証する
- [フェーズを実行する](how-to/execute-a-phase.md) — 新鮮なコンテキストのサブエージェントで並列ウェーブとして計画を実行する
- [検証と出荷](how-to/verify-and-ship.md) — 完成した作業を確認し、障害を診断し、PR を作成する
- [フェーズを自律的に実行する](how-to/run-phases-autonomously.md) — 無人フェーズ実行に自律モードを使用する
- [クイックおよびファストタスクを処理する](how-to/handle-quick-and-fast-tasks.md) — フェーズループ外のアドホック作業に `/gsd-quick` と `/gsd-fast` を使用する
- [モデルプロファイルを設定する](how-to/configure-model-profiles.md) — クオリティ・バランス・バジェットのモデルティア間を切り替える
- [クロス AI レビューをセットアップする](how-to/set-up-cross-ai-review.md) — プライマリエージェントが生成したコードをレビューする 2 番目の AI を設定する
- [ワークストリームで並列作業する](how-to/work-in-parallel-with-workstreams.md) — ワークストリームを使って独立した作業ラインを同時に実行する
- [ワークスペースで作業を隔離する](how-to/isolate-work-with-workspaces.md) — ワークスペースを使って実験的またはリスクのある変更をサンドボックス化する
- [失敗した実行をデバッグする](how-to/debug-a-failed-execution.md) — 壊れたまたは不完全なフェーズ実行を診断・回復する
- [スパイクとスケッチ](how-to/spike-and-sketch.md) — 計画を確定する前の探索的作業に `/gsd-spike` と `/gsd-sketch` を使用する
- [UI フェーズを設計する](how-to/design-a-ui-phase.md) — フロントエンドおよびビジュアル作業に UI フェーズループを使用する
- [トラッカーイシューから GSD を動かす](how-to/drive-gsd-from-a-tracker-issue.md) — GitHub、Linear、または Jira のイシューからフェーズを開始する
- [GSD 2 から移行する](how-to/migrate-from-gsd-2.md) — 既存の GSD 2 プロジェクトを GSD Core にアップグレードする
- [GSD をアップデートする](how-to/update-gsd.md) — インストーラーを再実行して最新リリースを取得する
- [回復とトラブルシューティング](how-to/recover-and-troubleshoot.md) — よくある問題を修正し、コンテキストを再構築し、アンインストールする
---
## リファレンス
- [コマンド](COMMANDS.md) — フラグと例を含むすべてのコマンド
- [設定](CONFIGURATION.md) — 完全な設定スキーマ、モデルプロファイル、Git ブランチ戦略
- [CLI ツール](CLI-TOOLS.md) — ワークフローとエージェント向け `gsd-tools.cjs` プログラマティック API
- [機能](FEATURES.md) — 完全な機能インデックス
- [インベントリ](INVENTORY.md) — インストール済みスキルとサーフェスマップ
- [STATE.md スキーマ](reference/state-md.md) — `.planning/STATE.md` のフィールド別リファレンス
- [CONTEXT.md スキーマ](reference/context-md.md) — `.planning/phases/<N>/CONTEXT.md` のフィールド別リファレンス
- [PLAN.md スキーマ](reference/plan-md.md) — `.planning/phases/<N>/PLAN.md` のフィールド別リファレンス
- [計画アーティファクト](reference/planning-artifacts.md) — すべての `.planning/` ファイルとその役割
---
## 解説
- [コンテキストエンジニアリング](explanation/context-engineering.md) — コンテキストの腐敗がどのように形成され、GSD Core がどのように防ぐか
- [フェーズループ](explanation/the-phase-loop.md) — Discuss → Plan → Execute → Verify → Ship サイクルの設計理念
- [マルチエージェントオーケストレーション](explanation/multi-agent-orchestration.md) — サブエージェントがどのように生成・スコープ設定・調整されるか
- [セキュリティモデル](explanation/security-model.md) — 信頼境界、パーミッション、安全な自動化
- [アーキテクチャ](ARCHITECTURE.md) — システムアーキテクチャ、エージェントモデル、データフロー
- [ディスカスモード](workflow-discuss-mode.md) — `/gsd-discuss-phase` の assumptions モードと interview モード
- [コンテキストモニタリング](context-monitor.md) — コンテキストウィンドウ監視フックのアーキテクチャ
- [イシュー駆動オーケストレーション](issue-driven-orchestration.md) — 既存のプリミティブを使ってトラッカーイシューから GSD を動かすレシピ
---
## Related
- [ルート README](../README.md) — ランディングページ、クイックスタート、ドキュメント概要
- [変更履歴](../../CHANGELOG.md) — リリース履歴

1177
docs/ja-JP/USER-GUIDE.md
View File

File diff suppressed because it is too large Load Diff

83
docs/ja-JP/context-monitor.md
View File

@@ -2,9 +2,9 @@
ツール使用後に実行されるフック（Claude Code では `PostToolUse`、Gemini CLI では `AfterTool`）で、コンテキストウィンドウの使用量が高くなった際にエージェントに警告します。
## 課題
## 問題
ステータスラインはコンテキスト使用量を**ユーザー**に表示しますが、**エージェント**自身はコンテキストの制限を認識していません。コンテキストが不足すると、エージェントは限界に達するまで作業を続行し、タスクの途中で状態を保存できないまま停止する可能性があります。
ステータスラインはコンテキスト使用量を**ユーザー**に表示しますが、**エージェント**自身はコンテキストの制限を認識していません。コンテキストが不足すると、エージェントは限界に達するまで作業を続行し、状態を保存できないままタスクの途中で止まる可能性があります。
## 仕組み
@@ -16,34 +16,34 @@
## しきい値
| レベル | 残量 | エージェントの動作 |
|--------|------|------------------|
|-------|-----------|----------------|
| Normal | > 35% | 警告なし |
| WARNING | <= 35% | 現在のタスクをまとめ、新しい複雑な作業の開始を避ける |
| CRITICAL | <= 25% | 即座に停止し、状態を保存する（`/gsd-pause-work`） |
## デバウンス
エージェントへの繰り返し警告を防ぐため:
エージェントへの繰り返し警告を防ぐため：
- 最初の警告は即座に発火
- 以降の警告は間に5回のツール使用が必要
- 以降の警告は間に 5 回のツール使用が必要
- 深刻度のエスカレーション（WARNING -> CRITICAL）はデバウンスをバイパス
## アーキテクチャ
```
ステータスラインフック (gsd-statusline.js)
| 書き込み
Statusline Hook (gsd-statusline.js)
| writes
v
/tmp/claude-ctx-{session_id}.json
^ 読み取り
^ reads
|
コンテキストモニター (gsd-context-monitor.js, PostToolUse/AfterTool)
| 注入
Context Monitor (gsd-context-monitor.js, PostToolUse/AfterTool)
| injects
v
additionalContext -> エージェントが警告を確認
additionalContext -> Agent sees warning
```
ブリッジファイルはシンプルな JSON オブジェクトです:
ブリッジファイルはシンプルな JSON オブジェクトです：
```json
{
@@ -60,56 +60,21 @@ GSD の `/gsd-pause-work` コマンドは実行状態を保存します。WARNIN
## セットアップ
両フックは `npx @opengsd/gsd-core` のインストール時に自動的に登録されます:
両フックは `npx @opengsd/gsd-core` のインストール時に自動的に登録されます——通常の状況では手動の手順は不要です。フック設定の詳細、しきい値のオーバーライド、手動登録の例については、[設定](CONFIGURATION.md) を参照してください。
- **ステータスライン**（ブリッジファイルの書き込み）: settings.json の `statusLine` として登録
- **コンテキストモニター**（ブリッジファイルの読み取り）: settings.json の `PostToolUse` フックとして登録（Gemini では `AfterTool`）
`~/.claude/settings.json`（Claude Code）への手動登録:
```json
{
"statusLine": {
"type": "command",
"command": "node ~/.claude/hooks/gsd-statusline.js"
},
"hooks": {
"PostToolUse": [
{
"hooks": [
{
"type": "command",
"command": "node ~/.claude/hooks/gsd-context-monitor.js"
}
]
}
]
}
}
```
Gemini CLI（`~/.gemini/settings.json`）の場合、`PostToolUse` の代わりに `AfterTool` を使用します:
```json
{
"hooks": {
"AfterTool": [
{
"hooks": [
{
"type": "command",
"command": "node ~/.gemini/hooks/gsd-context-monitor.js"
}
]
}
]
}
}
```
簡単な参考として：ステータスラインフックは `settings.json` に `statusLine` として登録されます；コンテキストモニター（`gsd-context-monitor.js`）は `PostToolUse` フックとして登録されます（Gemini CLI の場合は `AfterTool`）。どちらのエントリも、インストーラーを実行した Node 実行ファイルの絶対パスを使います。Windows PowerShell では、引用符付きの実行ファイルパスに `&` をプレフィックスしてください。
## 安全性
- フックは全体を try/catch で囲み、エラー時はサイレントに終了
- ツール実行をブロックしない — モニターの故障がエージェントのワークフローを壊してはならない
- 古いメトリクス（60秒以上前）は無視
- ツール実行をブロックしない — モニターが壊れてもエージェントのワークフローを壊してはならない
- 古いメトリクス（60 秒以上前）は無視
- ブリッジファイルが存在しない場合も正常に処理（サブエージェント、新規セッション）
---
## Related
- [アーキテクチャ](ARCHITECTURE.md)
- [設定](CONFIGURATION.md)
- [ドキュメント索引](README.md)

90
docs/ja-JP/explanation/context-engineering.md Normal file
View File

@@ -0,0 +1,90 @@
# コンテキストエンジニアリング
> GSD Core が存在する理由、そして解決しようとしている問題。
---
## 問題：コンテキスト腐敗
AI コーディングセッションは常に新鮮な状態から始まります。モデルは質問を読み取り、それについて推論し、返答します。しかしセッションが一度のやり取りで終わることはほとんどありません。追加の質問をし、エラーメッセージを貼り付け、コードを繰り返し修正し、モデルが脱線したときに軌道修正します。ターンを重ねるたびに、モデルが一度に「見える」有限のテキストバッファであるコンテキストウィンドウにトークンが積み重なっていきます。
そのウィンドウが満たされると、微妙なことが起きます。モデルは明らかには失敗しません。答え続けます。しかしその品質は静かに低下していきます。最初の指示はモデルが注意を向けられる範囲の端へと追いやられます。最初のやり取りで確立したニュアンス——述べた制約、合意したアーキテクチャ、指摘したエッジケース——が後から積み重なったすべてのものと注意を奪い合います。研究者たちはこれを **コンテキスト腐敗** と呼びます。
コンテキスト腐敗はいくつかの形で現れます：
- モデルが以前に認めた決定と矛盾し始める。
- セッション開始時に確立したコーディングスタイルの規約からコードが外れていく。
- 計画が、明確に述べられていたが履歴の奥深くに埋もれた要件を無視し始める。
- モデルが 20 メッセージ前に正確に把握していたファイル名や関数シグネチャを誤って出力する。
これはモデルのバグではありません。トランスフォーマーアテンションが長いシーケンスに対してどう機能するかという根本的な性質です。モデルは「忘れて」いるわけではありません——人間的な意味での「記憶」は最初からありません。有限のウィンドウ全体で関連性を重み付けしており、そのウィンドウに蓄積されたノイズが増えるにつれて、シグナル対ノイズ比が低下するのです。
単純な対応策は `/clear` してやり直すことです。しかしそれでは連続性が失われます。コンテキストを再説明し、関連ファイルを再貼り付けし、制約を再度述べなければなりません。セッションは実質的にゼロにリセットされます。
---
## GSD Core の答え：フレッシュコンテキストサブエージェント
GSD Core の核心的な洞察は、コーディングセッションの作業の *ほとんど* はメインコンテキストで行う必要がそもそもないということです。調査、計画立案、コード作成、検証はそれぞれ独立した、境界が明確なタスクです。それぞれを専門化されたサブエージェントに渡すことができます。そのエージェントはクリーンで慎重にスコープされたコンテキストウィンドウで開始し、結果をスリムなオーケストレーターに報告します。
これはコンテキスト腐敗への迂回策ではありません。構造的な解決策です。
オーケストレーター——あなたのメインセッション——はソースファイルに触れません。エージェントを生成し、その結果を収集し、共有状態を更新し、次のステップへとルーティングします。自身がほとんど何もしないため、そのコンテキストウィンドウはゆっくりと予測可能に拡大します。重い作業はそれぞれ新鮮な状態で開始し、タスクに必要なコンテキストだけを受け取り、完了したら終了するエージェントの中で行われます。
これが実際にどういう意味かを考えてみましょう。`/gsd-plan-phase` を実行すると、オーケストレーターは：
1. コンパクトな JSON コンテキストペイロード（プロジェクト概要、フェーズ目標、関連設定）を読み込む。
2. 200k トークンのクリーンなウィンドウで調査エージェントを生成する。
3. 調査出力とフェーズ要件でプランナーエージェントを生成する。
4. 実行前に計画を検証するプランチェッカーエージェントを生成する。
各エージェントはセッション履歴の蓄積に邪魔されることなく、最大限の能力で動作します。プランナーが `PLAN.md` ファイルを `.planning/phases/` に書き込むと、その出力は永続的なアーティファクト——共有コンテキストウィンドウの中の脆弱な記憶ではなく——になります。
---
## 仕様駆動開発とメタプロンプティング
コンテキストエンジニアリング単体では不十分です。エージェントが新鮮な状態で開始しても、曖昧な指示を受け取れば、曖昧な出力を生み出します。GSD Core はフレッシュコンテキストサブエージェントと 2 つの補完的な規律を組み合わせています。
**仕様駆動開発** とは、すべてのフェーズが実行開始前に構造化されたアーティファクトを生成することを意味します。`CONTEXT.md` は Discuss ステップでの実装上の決定を記録します。`RESEARCH.md` は調査エージェントが見つけたものを記録します。`PLAN.md` は作業を独立した、依存関係の順序に従ったタスクに分解し、明確な受け入れ基準を持ちます。エグゼキューターエージェントがファイルに触れる時点では、長い会話の再解釈ではなく、正確な仕様から作業します。
**メタプロンプティング** とは、エージェント定義自体が慎重に設計されたプロンプトであり、アドホックな指示ではないことを意味します。`get-shit-done/workflows/` および `agents/` 内のファイルは、タスクのスコープの決め方、何を検証するか、いつ人間のチェックポイントにエスカレートするかについての実践的な知識をエンコードしています。ユーザーはこの知識をセッションごとに再説明する必要はありません。それはシステム自身のプロンプトに組み込まれています。
この組み合わせは意図的です。フレッシュコンテキストは各エージェントが明確に推論することを保証します。仕様駆動のアーティファクトは各エージェントが *正しい* ことについて推論することを保証します。メタプロンプティングは各エージェントが *うまく* 推論する方法を知っていることを保証します。
---
## `.planning/` の役割
コンテキストエンジニアリングには、知識がコンテキストリセットを超えて生き残ることが必要です。GSD Core はこのためにファイルシステムを使用します。すべての意味のある出力は、人間が読める Markdown または JSON として `.planning/` に書き込まれます。これが意味することは：
- セッションを再起動しても（またはモデルがクラッシュしても）作業が失われない。
- 後続のエージェントは共有された会話履歴に依存せず、以前のアーティファクトを直接読み取ることができる。
- 計画アーティファクトを検査、編集、または git にコミットできる——それらはプレーンテキストであり、データベース内の不透明な状態ではない。
`STATE.md` はこのシステムの背骨です。プロジェクトの現在位置（どのマイルストーン、どのフェーズ、どの計画が完了しているか）、アクティブな決定とブロッカー、進捗メトリクスを記録します。ワークフローが開始されると、まず `STATE.md` を読み取って方向を確認します。ワークフローが意味のあるステップを完了すると、`STATE.md` に書き戻します。エージェントは記憶に頼りません。ファイルに頼ります。
---
## トレードオフ
ここではトレードオフについて正直に述べることが重要です。
**オーバーヘッド。** フェーズループには実際の摩擦があります。`/gsd-discuss-phase`、`/gsd-plan-phase`、`/gsd-execute-phase` を別々のステップとして実行することは、普通のセッションに「この機能を書いて」と入力するよりも多くの経過時間がかかります。小さくてよく理解された変更に対しては、そのオーバーヘッドは正当化されません。
**レイテンシ。** 新鮮なコンテキストで複数のサブエージェントを生成することは、単一のインコンテキスト編集より遅くなります。調査、計画立案、実行のそれぞれにラウンドトリップのコストが発生します。
**シンプルなタスクへの過剰な手続き。** 変数名を変更したり、タイポを修正したり、欠落しているインポートを追加したりする場合、フェーズループは過剰です。GSD Core は完全なフェーズを必要としないアドホックな作業のために `/gsd-quick` と `/gsd-fast` を提供します。[クイックタスクとファストタスクの処理](../how-to/handle-quick-and-fast-tasks.md) を参照してください。
フェーズループは、コンテキスト腐敗が本当のリスクになるほど作業が複雑な場合——マルチファイル機能、横断的なリファクタリング、時間やセッションをまたぐ作業——に価値を発揮します。それ以外のすべてには、より軽量なプリミティブを使ってください。
経験則として役立つのは：タスクが単一の短いプロンプトで完全に仕様化でき、さらなる明確化なしに 1 エージェントターンで完了できるなら、フェーズループをスキップしてください。タスクが調査を必要とし、最近読んでいないファイルを含むか、まだ確定していない決定に依存している場合は、フェーズループが保護してくれます。
---
## Related
- [フェーズループ](the-phase-loop.md) — Discuss → Plan → Execute → Verify → Ship サイクルがコンテキストエンジニアリングをどう実践するか
- [マルチエージェントオーケストレーション](multi-agent-orchestration.md) — サブエージェントがどのように生成、スコープ設定、調整されるか
- [アーキテクチャ](../ARCHITECTURE.md) — システムアーキテクチャ、エージェントモデル、データフロー
- [ドキュメント索引](../README.md)

146
docs/ja-JP/explanation/multi-agent-orchestration.md Normal file
View File

@@ -0,0 +1,146 @@
# GSD Core におけるマルチエージェントオーケストレーション
> **解説** — このドキュメントは、GSD Core がマルチエージェントオーケストレーションを中心に設計されている *理由* と、*各部品がどのように組み合わさるか* を説明します。ステップバイステップのガイドではありません。設定については、[モデルプロファイルの設定](../how-to/configure-model-profiles.md) と [設定リファレンス](../CONFIGURATION.md) を参照してください。完全なエージェントロスターについては、[インベントリ](../INVENTORY.md) を参照してください。
---
## この設計が解決する問題
AI コーディングエージェントは劣化します。モデルが悪くなるからではなく、*コンテキストウィンドウが満杯になる* からです。会話が大きくなるにつれて、以前の決定やコードは中間ステップのノイズによって押し出されるか薄められます。複雑なタスクで 5 番目のファイルを書く頃には、エージェントは最初のメッセージで述べた制約をすでに忘れているかもしれません。これは *コンテキスト腐敗* と呼ばれることがあります。
GSD Core のマルチエージェント設計はその問題への直接的な応答です。セッション全体を抱える一つの長期実行エージェントの代わりに、薄いオーケストレーターが短命の専門化されたエージェントを生成します。それぞれが **フレッシュな 200K トークンのコンテキストウィンドウ** と、自分の特定の仕事をするために必要な *アーティファクトだけ* を持ちます。オーケストレーターは自分では重い作業をしません。コンテキストを読み込み、適切なエージェントを生成し、結果を収集し、`.planning/` の共有状態を更新します。
---
## オーケストレーター → エージェントパターン
`get-shit-done/workflows/` のすべてのワークフローは同じ形を持ちます：
```text
Orchestrator（ワークフロー .md ファイル）
│
├── コンテキスト読み込み
│ gsd-tools.cjs init <workflow> <phase>
│ → JSON: プロジェクト情報、設定、状態、フェーズ詳細
│
├── モデル解決
│ gsd-tools.cjs resolve-model <agent-name>
│ → opus | sonnet | haiku | inherit
│
├── 専門化エージェント生成（Task/SubAgent 呼び出し）
│ ├── エージェント定義（agents/*.md）
│ ├── コンテキストペイロード（init JSON）
│ ├── モデルアサイン
│ └── ツール権限
│
├── 結果収集
│
└── 状態更新
gsd-tools.cjs state update / state patch / state advance-plan
```
オーケストレーターは意図的に薄く保たれています。ドメインについて推論せず、コードを書かず、次のステップへルーティングする以上に結果を解釈しません。この境界により各レイヤーの責任が明確になり、オーケストレーターのコンテキストにドメインノイズが蓄積するのを防ぎます。
### エージェントロスター
GSD Core のエージェントは、調査 → 計画 → 実行 → 検証パイプラインにマッピングされる機能カテゴリに分類されます：
| カテゴリ | エージェント | 典型的な並列性 |
|---|---|---|
| 調査者 | `gsd-project-researcher`、`gsd-phase-researcher`、`gsd-ui-researcher`、`gsd-advisor-researcher` | 4 並列（スタック、機能、アーキテクチャ、落とし穴） |
| 合成者 | `gsd-research-synthesizer` | 調査者完了後、順次実行 |
| プランナー | `gsd-planner`、`gsd-roadmapper` | 順次実行 |
| チェッカー | `gsd-plan-checker`、`gsd-integration-checker`、`gsd-ui-checker`、`gsd-nyquist-auditor` | 順次実行、最大 3 回の修正反復 |
| エグゼキューター | `gsd-executor` | ウェーブ内並列、ウェーブ間順次 |
| 検証者 | `gsd-verifier` | すべてのエグゼキューター完了後、順次実行 |
| マッパー | `gsd-codebase-mapper` | 4 並列サブプローブ |
| 監査者 | `gsd-ui-auditor`、`gsd-security-auditor` | 順次実行 |
各エージェント定義（`agents/*.md` 内）は、許可されたツールアクセス、目的、ターミナル出力の色を宣言します。ファイルを読み取り、単一の出力ドキュメントを書くだけでよいエージェントには、まさにその権限だけが与えられます——Bash 実行なし、より広い状態へのアクセスなし。この制約は意図的です：エージェントが予期しない動作をした場合の影響範囲を小さく保ちます。
完全な 31 エージェントロスターについては、[インベントリ](../INVENTORY.md#agents-31-shipped) を参照してください。
---
## ウェーブベースの並行実行
マルチエージェント設計の最も目に見える表れは、`/gsd-execute-phase` が互いに依存しあうことのある計画セットをどう処理するかです。
エグゼキューターを生成する前に、オーケストレーターは **ウェーブ分析** を実行します：各 `PLAN.md` ファイルの依存関係宣言を読み取り、計画をウェーブにグループ化します。宣言された依存関係がない計画がウェーブ 1 を形成し、並列に実行されます。ウェーブ 1 に依存する計画がウェーブ 2 を形成し、以下同様です。
```text
Plan 01（依存なし） ─┐
Plan 02（依存なし） ─┤─── ウェーブ 1（並列）
Plan 03（依存: 01） ─┤─── ウェーブ 2（ウェーブ 1 待ち）
Plan 04（依存: 02） ─┘
Plan 05（依存: 03, 04） ─── ウェーブ 3（ウェーブ 2 待ち）
```
ウェーブ内の各エグゼキューターは：
- フレッシュなコンテキストウィンドウ（200K トークン、または対応モデルでは最大 1M）を受け取る
- 担当する特定の `PLAN.md` を受け取る
- プロジェクトコンテキスト（`PROJECT.md`、`STATE.md`）を受け取る
- フェーズコンテキスト（`CONTEXT.md`、利用可能な場合は `RESEARCH.md`）を受け取る
- 完了時にアトミックな git コミットを生成する
- 構築したものを説明する `SUMMARY.md` を書く
ウェーブ内のすべてのエグゼキューターが完了した後、オーケストレーターはウェーブ全体のプリコミットフックを一度実行します。エグゼキューターは `--no-verify` でコミットし、複数のエージェントが並行してコミットするときのビルドロック競合（たとえば Rust プロジェクトでの Cargo ロック競合）を防ぎます。したがってフックはコミットごとに一度ではなく、ウェーブごとに一度実行されます。
### 並行コミットの安全性
複数のエグゼキューターが同時に実行される場合、2 つのメカニズムが書き込み競合を防ぎます：
1. **`STATE.md` へのアトミックロック** — `STATE.md` へのすべての書き込みはロックファイル（`STATE.md.lock`）と `O_EXCL` アトミック作成を使います。これにより、2 つのエージェントそれぞれがファイルを読み取り、異なるフィールドを変更し、後から書いた方が前の変更を上書きするという read-modify-write 競合が防止されます。古いロック（10 秒以上）は自動的にクリアされます。
2. **ウェーブごとのフック実行** — 各エグゼキューターがプリコミットフックを独立して実行する代わりに（共有ビルドアーティファクトでファイルレベルの競合を引き起こす可能性がある）、オーケストレーターは各ウェーブが完了した後に `git hook run pre-commit` を一度実行します。
---
## 大窓モデルへのアダプティブコンテキスト拡充
標準の 200K コンテキストウィンドウは、エグゼキューターが単一の集中した計画を実装するには十分です。設定された `context_window` が 500K トークン以上の場合（たとえば Opus 4.6 または Sonnet 4.6 を 1M クラスモードで使用する場合）、オーケストレーターは標準ウィンドウでは収まらない追加コンテキストでサブエージェントプロンプトを自動的に拡充します：
- **エグゼキューターエージェント** は前のウェーブの `SUMMARY.md` ファイルとフェーズの `CONTEXT.md`/`RESEARCH.md` を受け取り、フェーズ内でのクロスプラン認識を得る
- **検証者エージェント** はすべての `PLAN.md`、`SUMMARY.md`、`CONTEXT.md` ファイルと `REQUIREMENTS.md` を受け取り、履歴を考慮した検証が可能になる
この拡充は `config.json` の `context_window` の値に条件付きです。標準ウィンドウ設定では、プロンプトはトークン効率を最大化するためにキャッシュフレンドリーな順序で切り詰められたバージョンを使います。
---
## なぜこの設計か——コンテキストエンジニアリングとの関連
オーケストレーター → エージェントパターンは、*コンテキストエンジニアリング* というより広いアプローチの一部としてのみ意味を持ちます：AI エージェントがコンテキストウィンドウで受け取るものが、モデルの層やプロンプト品質と同じくらい重要だという考え方。完全な解説については [コンテキストエンジニアリング](context-engineering.md) を参照してください。
マルチエージェントオーケストレーションはコンテキストエンジニアリングを 2 つの方法で実装します：
**コンテキストの分離。** 各エージェントは必要なものだけを受け取ります。調査者はプロジェクト説明とドメイン質問を受け取ります；完全な計画履歴は受け取りません。検証者はすべての計画とサマリーを受け取ります；生の調査は受け取りません。分離により各エージェントのコンテキストは他のパイプラインステージのノイズで薄まるのではなく、シグナルで密度が高く保たれます。
**セッションをまたいだコンテキストの衛生。** すべての状態は（エージェントのコンテキストウィンドウではなく）`.planning/` に人間が読める Markdown と JSON として存在するため、GSD ワークフローはコンテキストリセット（`/clear`）、タブ切り替え、複数日のブレークを超えて生き残ります。次のエージェントは常に、長い会話の再構築された記憶からではなく、永続化され検証されたアーティファクトから開始します。
---
## トレードオフ
マルチエージェントオーケストレーションはタダではありません。
**調整オーバーヘッド。** 各エージェントの生成はラウンドトリップです：オーケストレーターがプロンプトをフォーマットし、コンテキストを渡し、サブエージェントが完了するまで待ち（通常 1〜5 分）、結果を解析する必要があります。一つのコンテキストで作業する一つの有能なエージェントは、シンプルなタスクをより速く終わらせるでしょう。GSD は依存関係が許す限りデフォルトで並列性を採用することでこれを軽減します——`plan-phase` の 4 人の調査者は順次ではなく同時に実行されます。
**実行中の不透明性。** サブエージェントの実行中は、その作業は親セッションには見えません。ライブの進捗ストリームはありません。これはフレッシュコンテキスト設計の意図的な帰結です：サブエージェントは自分自身のコンテキストウィンドウで動作しています。オーケストレーターは生成ラインに生存通知を表示します（「サブエージェントで実行中——返ってくるまで出力なし」）で期待値を設定します。
**コンテキストスティッチングコスト。** 各エージェントに適切なアーティファクトをパッケージ化するには、オーケストレーターがコンテキストペイロードを組み立てて送信するためにトークンを使う必要があります。これが分離のコストです。`gsd-tools.cjs init` ハンドラーは、完全性とトークン予算のバランスを取る JSON ペイロードを生成し、繰り返し呼び出しでキャッシュにヒットするようにペイロードの安定した部分（プロジェクト定義、設定）にキャッシュフレンドリーな順序を適用します。
**モデルコストの増幅。** Opus 層で 5 つのエージェントを並行して実行することは、1 つを実行するよりコストがかかります。モデルプロファイルシステム（`model_profiles.md`、`model-profiles.cjs` でエージェントごとに解決）により、重要度の低いエージェントに安価な層を割り当てることができます。`dynamic_routing` 機能は、すべてのエージェントを安価な層で開始し、ソフトフェイラー時にのみエスカレートすることでさらにコストを削減します。詳細なオプションについては [設定](../CONFIGURATION.md) を参照してください。
これらのコストの見返りとして、この設計は*大きなフェーズにわたる一貫した品質*を買います。400 行の計画で 10 番目のファイルを書くエグゼキューターは、コンテキストがフレッシュだから劣化しません。20 の要件を確認する検証者は、すべてを会話履歴ではなく構造化された入力として受け取ったから最初の 10 を忘れません。
---
## Related
- [コンテキストエンジニアリング](context-engineering.md) — この設計を動機づける上流の原則
- [モデルプロファイルの設定](../how-to/configure-model-profiles.md) — エージェントごとにモデル層を割り当てる方法
- [設定リファレンス](../CONFIGURATION.md) — `models`、`model_overrides`、`dynamic_routing`、`context_window` を含む完全な `config.json` スキーマ
- [インベントリ](../INVENTORY.md) — 信頼できるエージェントロスターとワークフローリスト
- [アーキテクチャ](../ARCHITECTURE.md#agent-model) — オーケストレーター → エージェントパターンとウェーブ実行モデルの実装レベルの詳細
- [ドキュメント索引](../README.md)

117
docs/ja-JP/explanation/security-model.md Normal file
View File

@@ -0,0 +1,117 @@
# GSD Core セキュリティモデル
> **解説** — このドキュメントは、GSD Core がなぜこのようなセキュリティ姿勢を持っているか、そして *各レイヤーがどのように組み合わさるか* を説明します。すべてのフックパラメーターのリファレンスではありません。`/gsd-secure-phase` コマンドとそのオプションについては、[コマンド](../COMMANDS.md) を参照してください。実装レベルのフックアーキテクチャについては、[アーキテクチャ § フックシステム](../ARCHITECTURE.md#hook-system) を参照してください。組織全体のセキュリティベースライン（スキャナー制御、インシデントチェックリスト、所有権モデル）については、[SECURITY.md](../../../SECURITY.md) を参照してください。
---
## AI 駆動開発が専用のセキュリティ姿勢を必要とする理由
従来のコードエディターはあなたに代わって任意のパッケージを実行しません。GSD Core は実行します。調査 → 計画 → 実行パイプラインは「パッケージ名を指定する」から「`npm install <package>` を実行する」まで、「計画アーティファクトを書く」から「そのアーティファクトを LLM システムプロンプトとして使う」までの完全なパスを自動化します。各自動化ステップは人間をループから外します——そして各除去は潜在的な攻撃面です。
GSD Core のセキュリティモデルは一つの組織原則の上に構築されています：**多層防御**。単一の制御が完璧だとは想定しません。複数の重複したレイヤーがそれぞれ異なるクラスのリスクを軽減し、合わせて全体を完全に排除することなく攻撃面を実質的に悪用しにくくします。このドキュメントの末尾にある正直な要約は、システムが何に対して保護できないかを説明します。
---
## レイヤー 1 — サプライチェーン保護：パッケージ正当性ゲート
### 脅威
AI モデルはパッケージ名を幻覚します。これはまれな失敗モードではありません：2025 年の研究では、AI が生成するパッケージ参照のおよそ 20% が正規のパッケージに対応しない幻覚された名前であることが記録されています。これらの幻覚された名前のサブセット——同じ研究でおよそ 43%——はプロンプトをまたいで一貫して繰り返され、攻撃者は AI ツールが一般的に生成する名前を観察し、npm、PyPI、または crates.io でそれらの名前を悪意のあるポストインストールスクリプト付きで事前登録できます。この技術は *スロップスクワッティング* と呼ばれます。
スロップスクワッティングの陰湿な点は、`npm view` を通過する幻覚された名前が *正当に見える* ことです。レジストリエントリは誰かがその名前を登録したことを証明するだけです——パッケージが AI の言う通りのことをするとも、正規のユーザーがいるとも、インストールスクリプトが安全だとも証明しません。ゲートがなければ、幻覚された名前は GSD の調査者 → プランナー → エグゼキューターパイプラインを検出されずに流れ、最終的にあなたのマシンで `npm install <attacker-package>` として実行されるでしょう。
### ゲートの仕組み
ゲートは 3 つのパイプラインステージにわたって動作します：
**調査ステージ。** `gsd-phase-researcher` が外部パッケージを推奨するとき、それぞれに対して `slopcheck install <pkgs> --json` を実行します。結果は `RESEARCH.md` の `## Package Legitimacy Audit` テーブルに書き込まれます。`[SLOP]`（高信頼度の幻覚または攻撃者登録済み）とタグ付けされたパッケージは、ファイルが保存される前に **`RESEARCH.md` から完全に除去されます**。それらはプランナーに届きません。
**計画ステージ。** `gsd-planner` は監査テーブルを読み取ります。`[SUS]`（疑わしい：新規登録、低ダウンロード数、ソースリポジトリなし、または人気パッケージに近い命名パターン）または `[ASSUMED]`（直接レジストリ検証ではなく WebSearch から取得）とタグ付けされたパッケージについて、プランナーはインストールステップの前に **`checkpoint:human-verify` タスクを挿入します**。チェックポイントにはレジストリページへの直接リンクと、確認すべき具体的な事項が含まれます：メンテナー履歴、イシュートラッカーの活動、疑わしいインストールスクリプトがないこと。
**実行ステージ。** インストールが失敗した場合、`gsd-executor` は**チェックポイントを表示して停止します**。それ自体が悪意のある可能性のある代替パッケージ名をサイレントに試みません。これはエグゼキューターの動作における明示的なルールです（エグゼキュータエージェント定義の RULE 3）。
### WebSearch パッケージが常に `[ASSUMED]` である理由
WebSearch を通じて発見されたパッケージ名は、`npm view` が成功するかどうかに関わらず `[ASSUMED]` とタグ付けされます。レジストリに存在するパッケージは、インストールしても安全なパッケージと同じではありません。`npm view` は登録を証明するだけで、正当性を証明しません。`[ASSUMED]` タグは `[SUS]` と同じ人間検証チェックポイントをトリガーし、未検証のウェブ検出推奨は常にインストール前に人間のレビューを受けることを保証します。
### エコシステムカバレッジ
調査者は単一の汎用チェックではなく、レジストリ固有の検証コマンドを使います：
- Node.js：`npm view`
- Python：`pip index versions`
- Rust：`cargo search`
これは 2025 年の USENIX 研究によると約 9% の割合で発生するクロスエコシステム幻覚をカバーします——AI が実際に使用しているエコシステムには存在しない別のエコシステムのパッケージを推奨するケース。
### グレースフルデグレデーション
`slopcheck` が利用できない場合（インストールされていない、または調査時に pip インストールが失敗した）、GSD は可能な限り厳格なフォールバックを適用します：**すべての推奨パッケージが `[ASSUMED]` とタグ付けされ**、プランナーはすべてのインストールを `checkpoint:human-verify` タスクでゲートします。調査と計画は通常どおり進行します——システムはツールの依存関係の欠落でハードフェイルすることはありません。これは通常フローより意図的に厳格です：slopcheck の利用不可は、すべてのパッケージインストールに人間のチェックポイントを付与することを意味します。
`slopcheck` ツールは MIT ライセンスで pip インストール可能です。廃止された場合でも、`[ASSUMED]` ゲートフォールバックにより、人間チェックポイントカバレッジが維持されます。
---
## レイヤー 2 — プロンプトインジェクション防御
### 脅威
GSD Core は LLM システムプロンプトになる Markdown ファイルを生成します。調査パイプラインは外部ウェブコンテンツを読み取ります；計画パイプラインはユーザー提供のテキスト（`--text-file`、`--prd`）を組み込みます；実行パイプラインは後でエージェントコンテキストとして再読み取りされる計画アーティファクトを書きます。これらのアーティファクトに流れ込む任意のユーザー制御テキストは、潜在的な **間接プロンプトインジェクション** ベクターです——一度システムプロンプトの中に入ると、エージェントの指示を上書きしたり情報を窃取しようとする攻撃者制御の文字列。
### 防御の仕組み
GSD Core はプロンプトインジェクションを 3 つのレベルで対処します。
**入力検証（`security.cjs`）。** `get-shit-done/bin/lib/security.cjs` モジュールは中心的なセキュリティユーティリティです。以下を提供します：
- パストラバーサル防止：ユーザー提供のファイルパス（`--text-file`、`--prd`）はプロジェクトディレクトリ内で解決されることを検証し、macOS の `/var` → `/private/var` シンリンク解決を明示的に処理
- プロンプトインジェクション検出：既知のインジェクションパターン（ロールオーバーライド、指示バイパス、システムタグインジェクション）が計画アーティファクトに入る前にユーザー提供テキストをスキャン
- 安全な JSON パース：クラフトされた JSON ペイロードによるプロトタイプ汚染攻撃を防ぐラッパー
- シェル引数検証：サブシェルコマンドに渡される引数の使用前検証
**ランタイムフック：`gsd-prompt-guard.js`。** このフックは `.planning/` ファイルを対象とするすべての Write または Edit 呼び出しで発火します。書き込まれるコンテンツを `security.cjs` と同じインジェクションパターンでスキャンします（サブセットがフックの独立性のために直接インライン化されています——フックはモジュールを `require()` しないため、モジュールパスが変わっても実行されます）。検出は **アドバイザリーのみ**：フックは発見をログに記録しますが書き込みをブロックしません。理由は、正当な計画書き込みでの偽陽性ブロックは、セカンダリスキャンレイヤーで見逃したインジェクションより破壊的だからです。
**ランタイムフック：`gsd-read-injection-scanner.js`。** このフックはすべての Read ツール呼び出しの出力で発火します。GSD がエージェントのコンテキストに組み込もうとしているファイルの *読み取ったばかりのコンテンツ* をスキャンし、攻撃者が命令を埋め込んでいるケースをキャッチします。
**CI スキャナー。** `prompt-injection-scan.test.cjs` はテストスイートの一部として、すべてのエージェント、ワークフロー、コマンドファイルに埋め込まれたインジェクションベクターをスキャンします。これは GSD ソース自体でのインジェクション試みをキャッチします——たとえば、ワークフローファイルにロールオーバーライド命令を追加するよう変更したサプライチェーン攻撃。
### Read Injection Scanner vs Prompt Guard
2 つのフックは補完的な面をカバーします。`gsd-prompt-guard.js` は *計画アーティファクトへの書き込み* を監視します——植え付けられているインジェクションをキャッチします。`gsd-read-injection-scanner.js` は *任意のファイルの読み取り* を監視します——外部コンテンツ（依存関係の README、サードパーティの設定ファイル、ユーザー提供のドキュメント）から取り込まれるインジェクションをキャッチします。合わせて、取り込み → 保存 → 再読み取りのライフサイクルを括ります。
---
## レイヤー 3 — リポジトリおよび依存関係の整合性
GSD のランタイム動作の上流で、`open-gsd` 組織はリポジトリおよびパッケージレベルで制御を強制しています。これらは [`docs/security/baseline.md`](../../security/baseline.md) に完全に記録されており、ここでは完全性のために要約します。
**依存関係の整合性。** すべてのサードパーティ依存関係は `package-lock.json` でピン留めされ、インストール前に公開されたチェックサムに対して検証されます。`scripts/check-npm-integrity.cjs` ゲートは CI 時に無効なバージョン、欠落パッケージ、余分なパッケージを検出します。これにより GSD 自身の依存関係に対する依存関係混同とタイポスクワッティング攻撃を軽減します。
**シークレットスキャン。** すべてのコミットと PR にはハードコードされたシークレットのスキャンが実施されます。意図的なテストフィクスチャは、プロジェクト標準の除外文法でアノテーションが必要です（アノテーション形式については `SECURITY.md` を参照）。アノテーションなしの抑制は CI を失敗させます。
**ロケールセーフなテキストスキャン。** 出力とユーザー向け文字列は、Unicode ホモグリフ、双方向オーバーライド文字、不可視の Unicode についてスキャンされます——CVE-2021-42574（「トロイの木馬ソース」）で記録された、差分に悪意のあるコンテンツを隠すことができる攻撃クラス。
---
## トレードオフと限界
ここで説明するセキュリティモデルは、AI 駆動開発の攻撃面を意味のある程度低減します。サプライチェーンリスクを排除するものではありません。
**パッケージ正当性ゲートが低減するもの：** 幻覚されたまたは攻撃者登録済みのパッケージが人間のチェックポイントなしに `npm install` に届く確率。`[SLOP]` ゲートは高信頼度の悪質なパッケージを完全に除去します；`[SUS]`/`[ASSUMED]` ゲートは実行前に人間のレビューを要求します。これによりスロップスクワッティング攻撃の成功コストが実質的に引き上げられます。
**パッケージ正当性ゲートが排除しないもの：** 後で侵害された正規パッケージ（アカウント乗っ取り、そのパッケージ自体のツリーでの依存関係混同）は、調査時に登録シグナルを確認する slopcheck ではキャッチされません。その種の攻撃に対するコントロールは、依存関係整合性レイヤーのロックファイルと `npm audit` です。
**プロンプトインジェクション防御が低減するもの：** 計画アーティファクト内のユーザー制御テキストがエージェントの指示を正常に上書きする確率。既知のインジェクション形式のパターンマッチングは一般的なケースをキャッチします；新しいジェイルブレイクや低シグナルのインジェクションは検出されない可能性があります。アドバイザリーのみの姿勢は、検出がログに記録されるがブロックされないことを意味します——検出でハード停止するコストではなく、ワークフロー継続性を保持する意図的な選択。
**プロンプトインジェクション防御が排除しないもの：** 既知のパターンにマッチしない十分に創造的なインジェクション、またはフックがカバーしないチャンネルを通じて届くインジェクション（たとえば、サブエージェントがドキュメントをブラウズする際に読み取る依存関係の公開 README にインジェクトされたコンテンツ）。多層防御は各レイヤーが攻撃を困難にすることを意味し、単一のレイヤーが不可能にすることを意味しません。
**脆弱性の報告。** `https://github.com/open-gsd/gsd-core/security/advisories/new` でプライベートな GitHub セキュリティアドバイザリを通じて報告してください。パブリックなイシューを開かないでください。対応タイムラインと開示ポリシーについては [SECURITY.md](../../../SECURITY.md) を参照してください。
---
## Related
- [コマンド](../COMMANDS.md) — セキュリティ関連フラグを含む `/gsd-secure-phase` と `/gsd-code-review`
- [アーキテクチャ § フックシステム](../ARCHITECTURE.md#hook-system) — すべてのフック、そのイベントトリガー、安全性プロパティの実装詳細
- [SECURITY.md](../../../SECURITY.md) — 脆弱性報告、組織全体のセキュリティベースライン、シークレットスキャン除外ガバナンス、依存関係整合性検証
- [ドキュメント索引](../README.md)

129
docs/ja-JP/explanation/the-phase-loop.md Normal file
View File

@@ -0,0 +1,129 @@
# フェーズループ
> GSD Core が作業を整理する方法の核心的なメンタルモデル。
---
## ループとは何か
GSD Core はすべての開発作業を繰り返すサイクルとして構造化します：
```text
Discuss → (UI デザイン) → Plan → Execute → Verify → Ship
```
**フェーズ** と呼ばれる作業の各単位は、順番にこれらのステップを経ていきます。ループは形式的なものではありません。各ステップは、前のステップだけでは防ぎきれない特定のクラスの失敗を防ぐために存在します。
このドキュメントは、ループがなぜこの形をしているかを説明します。各ステップの実行方法については、下部にリンクされた how-to ガイドを参照してください。
---
## 各ステップが存在する理由
### Discuss（議論）
計画は、*何を*作るかだけでなく、*どのように*作るかを知るまでは始められません。`ROADMAP.md` のフェーズ目標は成果を記述します。Discuss ステップは、その成果への道を形作る実装上の決定を記録します：どのライブラリを使うか、どのエラーハンドリング戦略か、機能がルートごとかグローバルか、エッジケースはどう振る舞うべきか。
Discuss ステップなしでは、プランナーがこれらの決定を自分で行わなければなりません。うまく推測することもありますが、もっともらしいが誤った推測をすることも多く——一貫性はあっても実際の好みとずれた計画を生み出します。実行が終わってエラーに気づく頃には、かなりの作業を巻き戻すことになります。
Discuss ステップは意図的に軽量です。それは仕様書を書く演習ではなく、会話です。出力はフェーズディレクトリ内の `CONTEXT.md` です：プランナー、エグゼキューター、検証者がすべて読める決定の構造化された記録です。会話には数分かかります。それが何時間もの手直しを節約できます。
### UI デザイン（任意）
視覚的なコンポーネントを持つフェーズの場合、Discuss と Plan の間にオプションの `/gsd-ui-phase` ステップがあります。これは `UI-SPEC.md` を生成します——コードが書かれる前にレイアウト、インタラクション、視覚的な振る舞いを説明するデザインコントラクトです。デザインの曖昧さが異なる実装上の選択を生む可能性があるほど UI が複雑な場合に、このステップを実行する価値があります。明確なデザインコントラクトは、再実装するよりずっと安く書けます。
### Plan（計画）
Plan ステップは、実行に必要な調査、分解、構造的な思考を行います。フレッシュコンテキストサブエージェントのシーケンスとして実行されます：エコシステムを調査して `RESEARCH.md` に発見を記録する調査エージェント、調査と `CONTEXT.md` の両方を読んで `PLAN.md` ファイルを生成するプランナー、そして計画が完全で一貫していてスコープ内にあることを検証するプランチェッカー。
計画には何が含まれるのか？各 `PLAN.md` は作業の境界が明確な単位を記述します：変更するファイル、行う特定の変更、完了を定義する受け入れ基準。計画は依存関係のウェーブ順に並べられ、並行実行が安全になります——同じウェーブ内のエグゼキューターは重複しない懸念事項を担当します。
Plan ステップは曖昧さが最もコストが高い瞬間です。曖昧な計画は仮定を立てるエグゼキューターを生み出します。同じ懸念について異なる仮定を立てる複数の並行エグゼキューターは競合を生み出します。プランチェッカーの仕事は、実行が始まった後ではなく、その前にこれらをキャッチすることです。
### Execute（実行）
実行は計画を実施します。各エグゼキューターは、必要なものだけを正確にロードしたフレッシュな 200k トークンのコンテキストウィンドウを受け取ります：プロジェクトサマリー、フェーズコンテキスト、調査結果、そして自分のタスクのための特定の `PLAN.md`。それ以上でも以下でもありません。
エグゼキューターはコードを書いてアトミックにコミットします。各コミットは計画内の完了したタスクに対応します。並行エグゼキューターのウェーブが完了すると、オーケストレーターはその状態をマージして次のウェーブを開始します。
エグゼキューターのフレッシュコンテキストは便宜のためではありません——コンテキスト腐敗を防ぐメカニズムです。180k トークンの蓄積されたセッション履歴で実行するエグゼキューターは劣化しています。クリーンな状態で開始し、計画が必要とするものだけを読み取るエグゼキューターは、最大能力で動作しています。
### Verify（検証）
すべてのエグゼキューターが完了した後、検証エージェントはフェーズ目標、`CONTEXT.md` の決定、計画、実行サマリーを読み取り、構築されたものが意図されたものと一致するかを確認します。`VERIFICATION.md` を生成し、不一致があれば対象を絞った修正計画を生成します。
検証はテストだけではありません。要件カバレッジ（すべての REQ-ID が対処されたか？）、決定カバレッジ（`CONTEXT.md` に記録された決定が実際に実装されたか？）、そして全体的なフェーズ目標との整合性を確認します。実行がエラーなく終了したからフェーズが完了なのではありません。構築されたものが計画されたものであり、計画されたものが決定されたものである場合に完了です。
### Ship（出荷）
Ship ステップはプルリクエストを作成し、フェーズアーティファクトをアーカイブします。`STATE.md` はフェーズ完了としてマークするために更新されます。その後ループは次のフェーズのために再び始まります。
---
## マイルストーンとフェーズ
**マイルストーン** はバージョンサイクルです——プロジェクトの意味のあるリリース可能な増分。名前、バージョン番号、そして何を提供しなければならないかを定義する要件のセットを持ちます。すべてのフェーズが出荷され、要件がカバーされるとマイルストーンは完了です。
**フェーズ** はマイルストーン内の一つの作業単位です。フェーズには目標、それが対処する要件のセット、それを実装する計画のセットがあります。
この関係は重要です。なぜならマイルストーンとフェーズは異なるスコープの懸念事項を持っているからです。マイルストーンは「このバージョンの製品は何をするのか、しないのか？」と問います。フェーズは「調査、計画、実行、検証ができる次の境界が明確なものは何か？」と問います。
マイルストーンの境界は自然な製品境界——デプロイ可能な API、動作する UI フロー、完全なデータモデル——に引かれます。フェーズの境界は、ループが手に負えなくなることなく一度のループで安全に実行できることの限界に引かれます。
---
## 良いフェーズスコープとは
これはループで最もよく見られる摩擦の原因なので、詳しく考える価値があります。
大きすぎるフェーズはそれ自体が調査プロジェクトになります。プランナーは独立した計画に分解するのに苦労します。後のウェーブのエグゼキューターは前のウェーブを待ちながらブロックされます。検証は対象を絞ったレビューではなく全体監査になります。フィードバックサイクルが時間から日に延びて、多くのコードが書かれた後に根本的な設計ミスを発見するリスクが急激に高まります。
小さすぎるフェーズは自然に属する作業を断片化します。数行の計画ファイル、数分で完了するフェーズ、実行コストを矮小化する計画オーバーヘッドが生じます。ループは役に立つというよりお役所的に感じられます。
良いフェーズスコープとは：
- 目標が明らかに些細でも疑わしいほど広くもない単一の文で述べられる。
- 計画するために必要な調査が境界を持つ——エコシステムの問題に、他のフェーズが先に完了することに依存しない答えがある。
- 実行が少数の非重複する計画に並行化できる（数十ではなく）。
- 検証者がコードベース全体を読まずに確認できる、明確でテスト可能な完了の定義がある。
具体的には：「HMAC-SHA256 署名検証ミドルウェアを追加する」は良いフェーズスコープです。「認証システムを構築する」は通常そうではありません——ほぼ常に、別々のフェーズの方が良い複数の独立した懸念事項が含まれています。「README のタイポを修正する」はループが価値を加えるしきい値を下回っています；代わりに `/gsd-quick` を使ってください。
迷ったら、分割してください。小さいフェーズは速く完了し、より自信を持って検証でき、設計上の決定が誤りとわかった場合に方向修正しやすくなります。
---
## `.planning/` はどのようにループをまたいで状態を維持するか
ループは単一のセッションではありません。調査、計画立案、実行は複数のセッションにわたって行われ、その間にコンテキストリセットが発生することもあります。`.planning/` ディレクトリがこれを可能にするものです。
ループの各ステップは以前のステップが生み出したアーティファクトを読み取り、後のステップのためのアーティファクトを書き出します。Discuss ステップが生成する CONTEXT.md は、プランナーが実行するときに——たとえそれが数時間後の別のセッションであっても——まだ利用可能です。プランナーが生成する PLAN.md ファイルは、エグゼキューターが実行するときに——再起動をまたいでも——まだ利用可能です。検証者が書く VERIFICATION.md は、フェーズをレビューするときにまだ利用可能です。
`STATE.md` はこれすべての上のナビゲーション層です。ループ内でプロジェクトが現在どこにいるかを正確に記録します：どのマイルストーンがアクティブか、どのフェーズが進行中か、どの計画が完了していてどれが保留中か。自分の方向を確認する必要があるエージェントやワークフローは、まず `STATE.md` を読み取ります。
これらのファイルの正確な構造については、[計画アーティファクト](../reference/planning-artifacts.md) と [STATE.md スキーマ](../reference/state-md.md) を参照してください。
---
## ループはリズムであり、制約ではない
ループを官僚主義として見たくなる誘惑があります——コードを書く許可を得る前に実行しなければならない必須ステップのセット。そのフレーミングは誤りです。
ループは、各ステップが後で修正するのが本当にコストが高い失敗を防ぐために存在します。Discuss は誤った仮定の上での計画立案を防ぎます。Plan は根本的に壊れた設計の実行を防ぎます。Verify は仕様を外れた作業の出荷を防ぎます。これらは作り上げられた問題ではありません。実際の機能規模での AI 支援開発の実際の失敗モードです。
ループがうまく機能すれば、リズムのように感じます：各ステップが前のステップが仕事をしたために明確である、集中した境界を持つ作業のカデンス。オーバーヘッドは現実ですが、前払いです——何時間もの手直しではなく数分の計画として支払われます。
ループが正当化されるしきい値を下回る作業には、GSD Core はより軽量なプリミティブを提供します。フェーズループは一つのツールであり、唯一のツールではありません。
---
## Related
- [コンテキストエンジニアリング](context-engineering.md) — フレッシュコンテキストサブエージェントがなぜループを必要にする品質低下を防ぐのか
- [フェーズの議論](../how-to/discuss-a-phase.md)
- [フェーズの計画](../how-to/plan-a-phase.md)
- [フェーズの実行](../how-to/execute-a-phase.md)
- [検証と出荷](../how-to/verify-and-ship.md)
- [計画アーティファクト](../reference/planning-artifacts.md)
- [STATE.md スキーマ](../reference/state-md.md)
- [ドキュメント索引](../README.md)

218
docs/ja-JP/how-to/configure-model-profiles.md Normal file
View File

@@ -0,0 +1,218 @@
# モデルプロファイルの設定方法
プロジェクトに適したモデルティア戦略を選び、大規模なオーバーライドブロックを書かずに個々のエージェントやフェーズタイプを調整します。このガイドは最もシンプルなレバーから始め、動的ルーティングまで段階的に説明します。
---
## 4 つのプロファイル（`adaptive` と `inherit` も含む）
`.planning/config.json` または `/gsd-config --profile <name>` で `model_profile` を設定します:
| プロファイル | プランナー | エグゼキュータ | リサーチャー | ベリファイア | 使用場面 |
|---------|---------|----------|-------------|----------|----------|
| `quality` | Opus | Opus | Opus | Sonnet | コストは二の次で本番品質の作業 |
| `balanced` | Opus | Sonnet | Sonnet | Sonnet | 通常の開発 — デフォルト |
| `budget` | Sonnet | Sonnet | Haiku | Haiku | 高速プロトタイピング、コスト重視の環境 |
| `adaptive` | Opus | Sonnet | Sonnet | Sonnet | ランタイム対応プロファイルで他のティアと同様に解決。ランタイムを頻繁に切り替える場合に使用 |
| `inherit` | （セッションモデル） | （セッションモデル） | （セッションモデル） | （セッションモデル） | Anthropic 以外のプロバイダー（OpenRouter、ローカルモデル）— すべてのエージェントが現在のセッションモデルに従う |
上の表は代表的なサブセットを示しています。出荷済みの全 33 エージェントは `sdk/shared/model-catalog.json` にプロファイルごとの明示的なティア割り当てを持っています。完全なテーブルは設定リファレンスの [モデルプロファイル](../CONFIGURATION.md#model-profiles) を参照してください。
**コマンドによるクイック切り替え:**
```bash
/gsd-config --profile balanced # 通常の開発
/gsd-config --profile budget # プロトタイピングまたはコストの高いフェーズ
/gsd-config --profile quality # 本番リリース
/gsd-config --profile inherit # OpenRouter、ローカルモデル
```
**または `.planning/config.json` を直接編集:**
```json
{
"model_profile": "balanced"
}
```
---
## エージェントごとのオーバーライド（`model_overrides`）
プロファイル全体を変えずに単一エージェントのティアを変更したい場合は `model_overrides` を使用します:
```json
{
"model_profile": "balanced",
"model_overrides": {
"gsd-executor": "opus",
"gsd-codebase-mapper": "haiku"
}
}
```
有効な値: `opus`、`sonnet`、`haiku`、`inherit`、または完全修飾のモデル ID（例: `"openai/o3"`、`"google/gemini-2.5-pro"`）。
`model_overrides` はプロジェクト単位で `.planning/config.json` に、またはグローバルに `~/.gsd/defaults.json` に設定できます。競合する場合はプロジェクト単位のエントリが優先されます。競合しないグローバルエントリは保持されます。
**Codex と OpenCode に関する重要事項:** これらのランタイムはインストール時に解決済みのモデルを各エージェントの静的設定に埋め込みます。`model_overrides` を編集した後は、変更を反映させるためにインストーラーを再実行してください:
```bash
npx @opengsd/gsd-core@latest --codex --global # または --opencode、--kilo など
```
---
## フェーズタイプごとのモデル（`models`）
33 のエージェント名をすべて覚えずに「プランニングは Opus、それ以外は Sonnet」と指定したい場合は `models` ブロックを使用します。6 つのフェーズタイプをティアエイリアスにマッピングします:
```json
{
"model_profile": "balanced",
"models": {
"planning": "opus",
"discuss": "opus",
"research": "sonnet",
"execution": "opus",
"verification": "sonnet",
"completion": "sonnet"
}
}
```
フェーズタイプとそのエージェント:
| フェーズタイプ | 対象エージェント |
|---|---|
| `planning` | `gsd-planner`、`gsd-roadmapper`、`gsd-pattern-mapper` |
| `research` | `gsd-phase-researcher`、`gsd-project-researcher`、`gsd-research-synthesizer`、`gsd-codebase-mapper`、`gsd-ui-researcher` |
| `execution` | `gsd-executor`、`gsd-debugger`、`gsd-doc-writer` |
| `verification` | `gsd-verifier`、`gsd-plan-checker`、`gsd-integration-checker`、`gsd-nyquist-auditor`、`gsd-ui-checker`、`gsd-ui-auditor`、`gsd-doc-verifier` |
| `discuss`、`completion` | 予約済み — 現在はサブエージェントなし。スキーマの前方互換性のために受け入れられます |
`models` ブロックはティアエイリアス（`opus`、`sonnet`、`haiku`、`inherit`）のみを受け入れます。特定のエージェントに完全修飾のモデル ID を指定するには `model_overrides` を使用してください。
**`models` とエージェントごとの例外を組み合わせる:**
```json
{
"model_profile": "balanced",
"models": {
"research": "sonnet"
},
"model_overrides": {
"gsd-codebase-mapper": "haiku"
}
}
```
`gsd-codebase-mapper` が `haiku` に固定されている*以外の*すべてのリサーチエージェントは `sonnet` に解決されます。
---
## 動的ルーティング — 安いものから始めて失敗時にエスカレート
デフォルトでは安価なティアを使い、エージェントが品質ゲートで失敗した場合のみエスカレートしたい場合は `dynamic_routing` を有効にします:
```json
{
"dynamic_routing": {
"enabled": true,
"tier_models": {
"light": "haiku",
"standard": "sonnet",
"heavy": "opus"
},
"escalate_on_failure": true,
"max_escalations": 1
}
}
```
各エージェントはデフォルトのティア（`light`、`standard`、または `heavy`）を持っています。最初の試行では GSD が `tier_models[default_tier]` を選びます。オーケストレータがソフト失敗（検証が不確定、プランチェックがフラグを立てた、など）を検出した場合、エージェントを 1 ティア上で再起動します。`max_escalations` は合計リトライ数の上限です。
すでに `heavy` のエージェントはこれ以上エスカレートできません。
**エスカレーションを無効にして動的解決を維持する:**
```json
{
"dynamic_routing": {
"enabled": true,
"escalate_on_failure": false
}
}
```
結果に関係なく、すべての試行で `tier_models[default_tier]` が使用されます — エスカレーション動作なしに明示的なティアとモデルのマッピングが必要な場合に役立ちます。
`dynamic_routing` は**デフォルトで無効**です。ブロックを省略するか `enabled: false` を設定すると静的解決が維持されます。
---
## Anthropic 以外のランタイムでの GSD 使用
Codex、OpenCode、Gemini CLI、または Kilo 向けに GSD をインストールした場合、インストーラーはすでに設定に `resolve_model_ids: "omit"` を設定しています。これにより GSD は Anthropic のモデル ID 解決をスキップし、ランタイムが独自のデフォルトモデルを選択できるようにします。基本的なケースでは手動設定は不要です。
**Codex でティアードモデルを使用したい場合:**
```json
{
"runtime": "codex",
"model_profile": "balanced"
}
```
GSD はランタイムのティアマップで定義された Codex ネイティブのモデルと推論エフォートに各ティアエイリアスを解決します。
**Anthropic 以外のランタイムでエージェントごとのモデル ID を使用したい場合:**
```json
{
"resolve_model_ids": "omit",
"model_overrides": {
"gsd-planner": "o3",
"gsd-executor": "o4-mini",
"gsd-debugger": "o3"
}
}
```
ランタイム対応プロファイルの完全なリファレンスと `model_policy` サーフェス（v1.42 で追加されたプロバイダー中立プリセット）については [設定リファレンス — モデルプロファイル](../CONFIGURATION.md#model-profiles) を参照してください。
---
## 解決の優先順位（高いものから低いものへ）
複数のレイヤーが適用される場合、リゾルバーは最も優先度の高いエントリを選択します:
```text
1. model_overrides[<agent>] — エージェントごと; 完全 ID; 対象を絞った例外
2. dynamic_routing.tier_models[<tier>] — 有効時; ソフト失敗でエスカレート
3. models[<phase_type>] — 粗いフェーズレベルのティア
4. model_profile（エージェントごとの列） — グローバルティア戦略
5. ランタイムのデフォルト — それ以外が適用されない場合
```
---
## 適切なレバーを選ぶ
| やりたいこと | 使うもの |
|---|---|
| すべてのエージェントに 1 つのティア戦略を適用する | `model_profile` |
| 粗いフェーズレベルの調整（「プランニングは Opus」） | `models.<phase_type>` |
| エージェントごとの細かい設定（「コードベースマッパーを強制的に Haiku に」） | `model_overrides[<agent>]` |
| 特定のエージェントに完全修飾のモデル ID を設定する | `model_overrides[<agent>]: "openai/gpt-5"` |
| 安価から始めて失敗時のみエスカレートする | `dynamic_routing` |
| すべてのエージェントがセッションモデルに従う（Anthropic 以外のプロバイダー） | `model_profile: "inherit"` |
---
## Related
- [設定リファレンス](../CONFIGURATION.md)
- [マルチエージェントオーケストレーション](../explanation/multi-agent-orchestration.md)
- [コマンドリファレンス](../COMMANDS.md)
- [ドキュメント索引](../README.md)

178
docs/ja-JP/how-to/debug-a-failed-execution.md Normal file
View File

@@ -0,0 +1,178 @@
# フェーズ実行の失敗をデバッグする方法
**目標:** フェーズ実行が失敗・停止した場合、または不完全な作業が生成された場合に回復し、すでに成功した作業を繰り返すことなく、クリーンな状態で再開する。
**前提条件:** `/gsd-execute-phase N` を実行したが、`VERIFICATION.md` が書き込まれる前に実行が停止した、または予期しない出力・ファイル不足・スピナーの停止が確認された状態であること。
---
## 実行が停止したのか失敗したのかを判断する
回復操作を行う前に、実際に何が起きたかを確認してください。
### 「Spawning…」のまま 1〜5 分間出力がない場合
これはフリーズではなく正常な動作です。GSD のサブエージェントは独立したコンテキストウィンドウで動作します。スポーン行の liveness ノートがこれを確認しています。セッションを中断しないでください。
10 分以上経っても結果が得られない場合は、Claude Code のサイドバーを確認してください。エージェントのタスクが完了と表示されているにもかかわらず出力が表示されない場合、コンテキスト切り替え時に結果が失われた可能性があります。同じコマンドを再実行してください。
```bash
/gsd-execute-phase 1
```
GSD はエグゼキューターを dispatching する前に `SUMMARY.md` ファイルを確認します。すでに `SUMMARY.md` があるプランは自動的にスキップされます。
### 実行がエラーメッセージとともにウェーブの途中で停止した場合
git 履歴を確認して、どのプランが正常にコミットされたかを調べます。
```bash
git log --oneline -20
```
作業をコミットしたプランには `feat(01-02): …` のようなエントリがあります。コミットのないプランは未完了であり、再実行時に再度実行されます。
### エグゼキューターがコードをコミットしたが SUMMARY.md を書き込まなかった場合
GSD は次回の実行時にこれを検出し、3 つの選択肢を持つ安全な再開ゲートを表示します。
- **手動でクローズアウト** — コミットを自分で確認し、`SUMMARY.md` を書いてから再実行する。
- **最初からやり直し** — 新しいエグゼキューターを dispatching する前に、部分的なコミットを revert または上書きする。
- **マーク・アンド・スキップ** — 異常を記録して続行する（明示的な確認が必要）。
---
## 根本原因を診断する
### `/gsd-debug --diagnose` を実行する
実行が誤った出力・スタブコード・検証失敗を生成した場合、修正を適用せずに診断のみを行うモードで調査します。
```bash
/gsd-debug --diagnose "Phase 2 executor produced stubs instead of real code"
```
`--diagnose` はファイルに触れることなく根本原因で停止します。後で調査を再開できるよう、セッションファイルを `.planning/debug/<slug>.md` に作成します。
修正も含む完全なデバッグセッションを開始するには：
```bash
/gsd-debug "Login middleware not handling 401 correctly after phase 3"
```
GSD は症状を収集し、科学的手法を使って体系的な調査を行い、修正案を提案します。設定で `tdd_mode: true` が有効な場合、修正を適用する前に失敗するテストが必要です。
### アクティブなデバッグセッションを確認する
```bash
/gsd-debug list
```
現在の仮説と次のアクションとともに、すべてのオープンセッションを表示します。特定のセッションを再開するには：
```bash
/gsd-debug continue <slug>
```
---
## `/gsd-forensics` でポストモーテムを実行する
エラー出力から原因が明確でない場合（例：プランが存在しないファイルを参照している、実行が予期しない結果を生成した、状態が破損しているように見える）、フォレンジック調査を実行します。
```bash
/gsd-forensics "Phase 3 execution stalled after wave 1"
```
GSD は git 履歴、`.planning/` 成果物の完全性、STATE.md の一貫性、未コミットの作業、孤立したワークツリーを分析します。構造化されたレポートを `.planning/forensics/report-<timestamp>.md` に書き込み、推奨される修復手順を提示します。
`/gsd-forensics` は読み取り専用です。プロジェクトファイルを変更することはありません。
**検出内容：**
- **スタックループ** — 短い時間ウィンドウ内に同じファイルが 3 回以上の連続コミットに現れる（コミットメッセージが類似している場合は HIGH 信頼度）
- **成果物の欠落** — フェーズにコミットはあるが `SUMMARY.md` または `VERIFICATION.md` がない
- **放棄された作業** — 未コミットの変更があり STATE.md が実行中途を示し、最終コミットが 2 時間以上前
- **クラッシュまたは中断** — 未コミットの変更とアクティブな実行状態、および孤立したワークツリーの組み合わせ
- **スコープドリフト** — 直近のコミットが現在のフェーズの想定ファイルセット外のファイルに触れている
---
## 回復後に実行を再開する
根本的な問題が解決したら、実行コマンドを再実行します。
```bash
/gsd-execute-phase 1
```
GSD はすでに `SUMMARY.md` が存在するプランをスキップし、残りのプランのみにエグゼキューターを dispatch します。
特定のウェーブだけを再実行する必要がある場合：
```bash
/gsd-execute-phase 1 --wave 2
```
dispatching 前に `.planning/` の整合性を検証したい場合：
```bash
/gsd-execute-phase 1 --validate
```
---
## `/gsd-undo` でロールバックする
実行が生成したコードを完全に破棄したい場合は、手動の `git revert` ではなくプランマニフェストを使ってロールバックします。
### 単一プランをロールバックする
```bash
/gsd-undo --plan 03-02
```
フェーズ `3` のプラン `02` に関するすべてのコミットを revert します。GSD は変更を書き込む前に確認ゲートを表示します。
### フェーズ全体をロールバックする
```bash
/gsd-undo --phase 03
```
フェーズ `3` に関するすべてのコミットを revert します。GSD は後続フェーズがこのフェーズに依存しているかどうかを確認し、続行前に警告を表示します。
### 直近のコミットからインタラクティブに選ぶ
```bash
/gsd-undo --last 5
```
最近の 5 件の GSD コミットを表示し、revert するものを選択できます。
---
## 中断後にセッションコンテキストを復元する
コンテキストリセットや新しいセッションの後にプロジェクトに戻った場合：
```bash
/gsd-resume-work
```
最後のハンドオフから完全なセッションコンテキスト（現在のフェーズ、ブロッカー、実行が停止した場所を含む）を復元します。
または、現在の位置を確認して正しい次のステップに自動的に進むには：
```bash
/gsd-progress --next
```
---
## Related
- [フェーズを実行する](execute-a-phase.md)
- [回復とトラブルシューティング](recover-and-troubleshoot.md)
- [コマンドリファレンス](../COMMANDS.md)
- [ドキュメント一覧](../README.md)

149
docs/ja-JP/how-to/design-a-ui-phase.md Normal file
View File

@@ -0,0 +1,149 @@
# UI フェーズをデザインする方法
**目標:** プランナーがタスクを書く前に、スペーシング・カラー・タイポグラフィ・コピーライティングの決定を固定したロック済みの UI デザインコントラクト（`UI-SPEC.md`）を作成し、実行中のアドホックなスタイリング選択による視覚的な一貫性の欠如を防ぐ。
**前提条件:** `.planning/ROADMAP.md` が存在すること。フェーズにフロントエンドまたは UI 作業が含まれること。事前に `/gsd-discuss-phase N` を実行することを強く推奨します。UI リサーチャーは `CONTEXT.md` を読み込んで、すでに決定済みの事項を再確認しないようにします。
---
## このフェーズに UI コントラクトが必要かどうかを判断する
すべてのフェーズで `/gsd-ui-phase` が必要なわけではありません。以下の場合に使用してください。
- フェーズが新しい UI サーフェス（ページ、フロー、レイアウト）を導入する
- 複数のコンポーネントが構築され、視覚的な一貫性が重要
- 新しいプロジェクトのフロントエンドを開始し、デザインシステムのベースラインが必要
- 既存プロジェクトに大幅な UI 作業を追加し、実行前にトークン・スペーシング・カラーを固定したい
以下の場合はスキップしてください。
- フェーズが純粋にバックエンド、インフラ、またはユーザー向け出力のないデータ作業
- 以前のフェーズの UI-SPEC.md がすでに存在し、このフェーズが新しいサーフェスを導入せず同一のビジュアルパターンで構築する
確信が持てない場合、安全ゲートが促してくれます。`workflow.ui_safety_gate` が有効（デフォルト）な場合、`/gsd-plan-phase` はフロントエンド作業を検出したが UI-SPEC.md がない場合に警告を表示し、先に `/gsd-ui-phase` を実行するかどうかを確認します。
---
## UI デザインコントラクトを実行する
```bash
/gsd-ui-phase 2
```
フェーズ番号を省略した場合、GSD Core は現在のフェーズを対象とします。
コマンドは 2 つのステージで実行されます。
1. **`gsd-ui-researcher`** — `CONTEXT.md`、`RESEARCH.md`、`REQUIREMENTS.md` を読み込んで既存の決定事項を確認し、デザインシステムの状態（shadcn の `components.json`、Tailwind 設定、既存トークン）を検出し、スペーシング・カラー・タイポグラフィ・コピーライティング・レジストリ安全性の 5 つの領域で未回答のデザイン問題のみを確認します。
2. **`gsd-ui-checker`** — 生成された `UI-SPEC.md` を 6 つの側面で検証します。問題が発見された場合、指摘された項目のみを対象に研究者が再実行されるリビジョンループが起動します（最大 2 回のイテレーション）。
**出力:** `.planning/phases/{phase-dir}/` 内の `{padded_phase}-UI-SPEC.md`。
---
## UI-SPEC がカバーする内容
リサーチャーは 5 つの領域で決定を固定します。
| 領域 | 例 |
|---|---|
| **スペーシング** | ベーススケール（4px または 8px）、グリッドの整合、コンポーネントのパディング |
| **カラー** | プライマリ・アクセント・ニュートラルパレット；60/30/10 ルール；ダークモードの考慮 |
| **タイポグラフィ** | フォントファミリー、サイズ・ウェイトスケールの制約、見出し階層 |
| **コピーライティング** | CTA ラベル、空の状態のメッセージ、エラー状態のコピー、ローディングインジケーター |
| **レジストリ安全性** | shadcn コンポーネントの検査プロトコル（以下を参照） |
チェッカーは 6 つの柱（それぞれ 1〜4 点）でスペックを検証します：コピーライティング、ビジュアル、カラー、タイポグラフィ、スペーシング、エクスペリエンスデザイン（ローディング / エラー / 空の状態のカバレッジ）。
---
## shadcn の初期化
React、Next.js、Vite プロジェクトの場合、`components.json` が見つからない場合はリサーチャーが shadcn の初期化を提案します。フローは以下の通りです。
1. `ui.shadcn.com/create` にアクセスしてプリセット（カラー、ボーダー半径、フォント）を設定する
2. プリセット文字列をコピーする
3. 以下を実行する：
```bash
npx shadcn init --preset <paste>
```
プリセット文字列は GSD Core の計画成果物として第一級の扱いを受け、フェーズとマイルストーンを通じて再現可能です。
---
## レジストリ安全ゲート
サードパーティの shadcn レジストリは任意のコードを注入できます。`workflow.ui_safety_gate` が有効（デフォルト）な場合、非公式のコンポーネントをインストールする前に以下の手順をスペックが要求します。
```bash
npx shadcn view <component> # インストール前にソースを確認する
npx shadcn diff <component> # 公式レジストリと比較する
```
レジストリ安全性が対処されていない場合、チェッカーはスペックを BLOCKED としてフラグを立てます。プロジェクトが shadcn を使用していない場合や、別の審査プロセスがある場合は、`/gsd-settings` でゲートを無効化してください。
---
## スケッチ知見をヘッドスタートとして使う
すでに `/gsd-sketch --wrap-up` を実行済みの場合、UI リサーチャーは `.claude/skills/sketch-findings-[project]/` を自動的に読み込みます。事前に検証された決定（レイアウト・パレット・タイポグラフィ・スペーシング）はロック済みとして扱われ、再確認されません。実行開始時に以下のメモが表示されます。
```text
⚡ Sketch findings detected: .claude/skills/sketch-findings-[project]/SKILL.md
Pre-validated decisions (layout, palette, typography, spacing) should be treated
as locked — not re-asked.
```
`/gsd-ui-phase` の前に `/gsd-sketch --wrap-up` を実行する主な理由はこれです。会話形式のデザイン探索がコントラクト入力として確定されます。
---
## `/gsd-ui-review` による事後的なビジュアル監査
`/gsd-ui-review` は実行前ではなく実行後に使用します。実装済みのフロントエンドを UI-SPEC（またはスペックがない場合は抽象的な 6 柱標準）に対して監査します。
```bash
/gsd-ui-review # 現在のフェーズを監査する
/gsd-ui-review 3 # フェーズ 3 を監査する
```
フロントエンドコードがあるプロジェクトであれば動作します。GSD プロジェクトの初期化は必要ありません。
**確認内容（6 柱、各 1〜4 点）：**
1. コピーライティング — CTA ラベル、空の状態、エラー状態
2. ビジュアル — フォーカルポイント、ビジュアル階層、アイコンのアクセシビリティ
3. カラー — アクセント使用の規律、60/30/10 準拠
4. タイポグラフィ — フォントサイズとウェイトの制約遵守
5. スペーシング — グリッドの整合、トークンの一貫性
6. エクスペリエンスデザイン — ローディング・エラー・空の状態のカバレッジ
**出力:** スコアと優先度の高い上位 3 件の修正点を含む `{padded_phase}-UI-REVIEW.md`。`gsd-browser` などのブラウザ MCP サーバーが設定されている場合、監査はビジュアルエビデンスとしてスクリーンショットも取得します。
**スクリーンショットの保存先:** スクリーンショットは `.planning/ui-reviews/` に保存されます。バイナリファイルが git に含まれないよう、`.gitignore` が自動的に作成されます。スクリーンショットは `/gsd-complete-milestone` 実行時にクリーンアップされます。
---
## フェーズライフサイクルにおける推奨位置
```text
/gsd-discuss-phase N ← 実装方針を固定する
/gsd-ui-phase N ← デザインコントラクトを固定する（フロントエンドフェーズ）
/gsd-plan-phase N ← リサーチ + 計画（UI-SPEC.md をコンテキストとして読み込む）
/gsd-execute-phase N ← 並行実行
/gsd-verify-work N ← 手動 UAT
/gsd-ui-review N ← 事後的なビジュアル監査（オプションだが推奨）
```
`/gsd-ui-phase` はディスカッションとプランの間に位置します。これはプランナーが `UI-SPEC.md` をデザインコンテキストとして読み込むためです。`PLAN.md` 内のタスクは、スペックが固定したスペーシングトークン・カラー変数・コピーライティング決定を参照します。
---
## Related
- [スパイクとスケッチ](spike-and-sketch.md)
- [フェーズを計画する](plan-a-phase.md)
- [コマンドリファレンス](../COMMANDS.md)
- [ドキュメント一覧](../README.md)

158
docs/ja-JP/how-to/discuss-a-phase.md Normal file
View File

@@ -0,0 +1,158 @@
# フェーズの検討方法
**目的:** プランニング開始前にフェーズが必要とする実装上の決定事項を収集します。これにより、リサーチャーとプランナーがあなたに再確認することなく作業を進められます。
**前提条件:** `.planning/ROADMAP.md` が存在すること。ない場合は先に `/gsd-new-project` を実行してください。
---
## 検討モードを選ぶ
GSD Core は 2 つのモードを提供します。コードベースへの理解度に応じて選択してください。
**実装に関する自分の方針を最初に表明したい場合**（インタビューモード、デフォルト）:
```bash
/gsd-discuss-phase 2
```
Claude はフェーズスコープのグレーゾーンを特定し、どこについて議論するかを選択させた後、各エリアについておよそ 4 つの質問に取り組みます。
**コードベースに明確なパターンがすでにあり、ほとんどの質問が自明に感じる場合**（仮定モード）:
```bash
node gsd-tools.cjs config-set workflow.discuss_mode assumptions
/gsd-discuss-phase 2
```
Claude はサブエージェント経由でコードベースの関連ファイルを 5〜15 個読み込み、証拠と確信度を添えて仮定を立て、確認または修正のために提示します。通常 2〜4 回のやり取りで済みます（インタビューモードの 15〜20 回と比較して）。
元に戻すには:
```bash
node gsd-tools.cjs config-set workflow.discuss_mode discuss
```
各モードの詳細な比較や、どちらが時間を節約しやすいかについては [検討モードの解説](../workflow-discuss-mode.md) を参照してください。
---
## 選択ステップなしで全グレーゾーンを検討する
デフォルトでは、Claude はグレーゾーンを提示し、どれをカバーするか選択を求めます。その選択プロンプトなしにすべてを順番に処理したい場合:
```bash
/gsd-discuss-phase 2 --all
```
---
## わかりやすいフェーズを高速化する
**フェーズが十分に理解されており、プロンプトなしで Claude に推奨デフォルトを選択させたい場合:**
```bash
/gsd-discuss-phase 3 --auto
```
Claude はすべての質問に対して推奨回答を選択し、その選択を記録します。決定事項のリスクが低い、または以前のフェーズから既に示唆されているフェーズで使用してください。
**リモートセッションの制約がある場合（TUI メニューが使えない）:**
```bash
/gsd-discuss-phase 2 --text
```
すべてのプロンプトはインタラクティブなセレクターではなく、プレーンテキストの番号付きリストとして表示されます。
---
## 質問をグループでまとめて処理する
一度に 1 つずつではなく、複数の質問をまとめて回答したい場合:
```bash
/gsd-discuss-phase 2 --batch
```
Claude は 1 ターンに 2〜5 問をグループにまとめます。
---
## 各質問にトレードオフ分析を追加する
確定する前にオプションの比較表を見たい場合:
```bash
/gsd-discuss-phase 2 --analyze
```
---
## 準備済みファイルから一括回答する
回答ファイルを準備済みで、すべての決定事項を一度に投入したい場合:
```bash
/gsd-discuss-phase 1 --power
```
---
## 検討前に Claude の仮定を確認する
**インタラクティブなセッションを始める前に Claude が何を仮定するかを確認したい場合** — 検討時間を投資する前にアラインメントを検証するのに役立ちます:
```bash
/gsd-discuss-phase 3 --assumptions
```
Claude は仮定（コードベースの証拠と確信度を添えて）を出力して終了します。`CONTEXT.md` は書き込まれません。出力を確認し、修正が必要な点があれば通常の discuss または仮定モードのセッションを実行してください。
---
## CONTEXT.md の内容
discuss モードと仮定モードはどちらも同じ `{phase}-CONTEXT.md` をフェーズディレクトリに生成します。下流のエージェント（リサーチャー、プランナー、プランチェッカー）は、どちらのモードで生成されたかに関係なくこのファイルを同じように読み込みます。このファイルは 6 つのセクションで構成されています:
| セクション | 目的 |
|---|---|
| `<domain>` | フェーズの境界 — このフェーズが提供するもの |
| `<decisions>` | セッションで確定した実装上の決定事項 |
| `<canonical_refs>` | 下流エージェントが必ず読むべき仕様書、ADR、ドキュメント |
| `<code_context>` | 再利用可能なアセット、パターン、統合ポイント |
| `<specifics>` | ユーザーの参照情報と設定 |
| `<deferred>` | 将来のフェーズに向けてメモされたアイデア |
`<canonical_refs>` セクションは必須です。検討中にドキュメント、仕様書、ADR を参照した場合、Claude はそれを即座に追加し、後続の質問に活用するために読み込みます。
完全なフィールドリファレンスは [CONTEXT.md スキーマ](../reference/context-md.md) を参照してください。
---
## 決定事項がプランニングにどう反映されるか
次に `/gsd-plan-phase` を実行すると、プランナーは CONTEXT.md を読み込み、どの決定事項が確定済みかを把握します。ここで既に回答された質問は再確認されません。リサーチャーも最初に CONTEXT.md を読んで調査すべき内容を把握します。
**`/gsd-plan-phase` 実行時に CONTEXT.md がない場合**、コンテキストなしで続行する（計画はあなたの設計方針なしにリサーチと要件のみを使用）か、先に `/gsd-discuss-phase` を実行するかの選択を求められます。
---
## PRD または受け入れ基準ドキュメントがある場合
discuss-phase をスキップしてプランニングに直接進んでください:
```bash
/gsd-plan-phase 1 --prd path/to/prd.md
```
プランナーは PRD から CONTEXT.md を合成し、すべての要件を確定済みの決定事項として扱います。
---
## Related
- [フェーズのプランニング](plan-a-phase.md)
- [検討モード](../workflow-discuss-mode.md)
- [CONTEXT.md スキーマ](../reference/context-md.md)
- [ドキュメント索引](../README.md)

176
docs/ja-JP/how-to/drive-gsd-from-a-tracker-issue.md Normal file
View File

@@ -0,0 +1,176 @@
# トラッカーイシューから GSD Core を操作する方法
**目標:** カスタムスクリプトやトラッカー連携なしに、GSD Core に既存のコマンドのみを使って、GitHub・Linear・Jira の単一の適切にスコープされたイシューを分離されたワークスペースからマージ済み PR まで通じたパイプラインで処理する。
**前提条件:** GSD Core がインストール済みであること。イシューは明確なスコープ、観察可能な受け入れ基準、上流のブロッカーがない状態であること。
このパターンの背景にある概念と設計理由については、[イシュー駆動オーケストレーションの説明](../issue-driven-orchestration.md)を参照してください。
---
## ステップ 1: イシューをフェーズにマッピングする
トラッカーイシューを開き、`ROADMAP.md` へのマッピングを決定します。
- **イシューが既存のフェーズと一致する** → フェーズ番号をメモしてステップ 2 に進む。
- **イシューがスタンドアロンの新しい作業** → フェーズを追加する：
```bash
/gsd-phase "Description matching the issue title"
```
- **イシューが緊急で既存フェーズの間に挿入する必要がある** → 小数フェーズを挿入する：
```bash
/gsd-phase --insert 3 "Fix: description from issue"
```
トラッカーイシューの URL をコピーします。ステップ 3 で `CONTEXT.md` に貼り付けることで、コンテキスト圧縮を経ても追跡可能性が維持されます。
---
## ステップ 2: 分離されたワークスペースを作成する
すべてのイシューには独自のワークスペース（独立した `.planning/` ディレクトリを持つ git ワークツリー）を用意します。部分的な作業、中断されたプラン、探索的なコミットを `main` の外に保ちます。
```bash
/gsd-workspace --new --name my-issue-slug --repos . --strategy worktree
```
続行する前にワークスペースディレクトリに移動します。
```bash
cd ~/gsd-workspaces/my-issue-slug
```
---
## ステップ 3: フェーズを議論する
計画が始まる前に実装上の決定を固定するために discuss-phase を実行します。セッションが開いたら、トラッカーイシューの URL を議論に貼り付けて `CONTEXT.md` に記録します。
```bash
/gsd-discuss-phase N
```
GSD はイシューのスコープにある曖昧さ（エラーハンドリング、エッジケース、インターフェースコントラクト、技術選択）について質問します。回答がその後の計画を形作ります。
すべての答えがわかっていて素早く進みたい場合：
```bash
/gsd-discuss-phase N --auto
```
---
## ステップ 4: フェーズを計画する
```bash
/gsd-plan-phase N
```
GSD はリサーチエージェントを起動し、`CONTEXT.md` の決定（イシュー URL を含む）を読み込み、アトミックな `PLAN.md` ファイルを生成します。プランチェッカーが各プランを保存前に検証します。
実行前に外部 AI CLI からのピアレビューが必要な場合（重要な変更には推奨）：
```bash
/gsd-review --phase N
/gsd-plan-phase N --reviews
```
または、HIGH の懸念事項がなくなるまでプラン・レビュー・収束ループを実行するには：
```bash
/gsd-plan-review-convergence N
```
---
## ステップ 5: フェーズを実行する
インタラクティブなフェーズ単位の実行の場合：
```bash
/gsd-execute-phase N
```
すべての残りのフェーズをハンズオフで実行する場合：
```bash
/gsd-autonomous
```
進捗を監視しながらフェーズ全体で作業を dispatch できるインタラクティブなダッシュボードの場合：
```bash
/gsd-manager
```
3 つのアプローチすべてで `STATE.md` を更新し、各タスクをアトミックにコミットし、フェーズ後の検証を実行します。
---
## ステップ 6: 作業を検証する
```bash
/gsd-verify-work N
```
GSD は（トラッカーイシューを反映した）フェーズゴールからの受け入れ基準を 1 つずつ確認します。何かが失敗した場合、GSD は根本原因を診断して修正プランを作成します。すべてのチェックが通るまで execute と verify を繰り返します。
コードが正しく見えても `verification_failed` はブロッカーとして扱ってください。失敗は通常、元のイシューからの見落とされた受け入れ基準を示しています。
---
## ステップ 7: レビューとリリース
PR を開く前にコードレビューを実行します。
```bash
/gsd-code-review N
/gsd-code-review N --fix
```
次に PR を作成します。
```bash
/gsd-ship N
```
GSD は計画成果物（フェーズゴール、変更概要、対応した要件、検証ステータス、主要な決定）から PR ボディを組み立てます。PR がマージされた時にトラッカーイシューが自動的にクローズされるよう、PR ボディに `Closes #NNN` または `Fixes #NNN` を含めます（または `/gsd-config` で設定）。
---
## ステップ 8: フォローアップ作業を記録する
イシューを進める中で関連する作業が見つかることがよくあります。コンテキストを失わずに記録します。
```bash
/gsd-capture "Follow-up: description of discovered work" # Todo として追加
/gsd-capture --seed "Idea worth a future phase" # 次のマイルストーン用に保存
/gsd-capture --backlog "Not urgent but worth tracking" # バックログに保存
```
GSD はトラッカーに自動的に投稿しません。記録されたフォローアップからトラッカーイシューを作成するのは手動の別ステップです。これにより人間のレビューをループに保ちます。
---
## 条件分岐
| 状況 | 対応 |
|-----------|-----------|
| イシューが非常に小さい（タイポ、設定変更） | ワークスペース + discuss + plan をスキップして `/gsd-quick` を使用する |
| イシューに複数の独立したサブタスクがある | `/gsd-manager` を使ってプラン全体で並行実行する |
| イシューが別のイシューにブロックされている | 上流のブロッカーが解決されるまで開始しない；GSD には自動的な依存ポーラーがない |
| 実行中にイシューのスコープが想定より大きくなった | 停止し `/gsd-phase --insert N` でサブフェーズを追加して続行する |
| インタラクティブな議論をスキップしたい | `/gsd-discuss-phase` に `--auto` フラグを使用するか、プロジェクト全体の自動化のために `workflow.skip_discuss: true` を設定する |
| 複数のイシューが一貫したリリースを形成する | `/gsd-new-milestone` でグループ化し `/gsd-autonomous` で順番に実行する |
---
## Related
- [イシュー駆動オーケストレーションの説明](../issue-driven-orchestration.md)
- [ワークスペースで作業を分離する](isolate-work-with-workspaces.md)
- [検証とリリース](verify-and-ship.md)
- [ドキュメント一覧](../README.md)

119
docs/ja-JP/how-to/execute-a-phase.md Normal file
View File

@@ -0,0 +1,119 @@
# フェーズの実行方法
**目的:** プランニング済みのフェーズをウェーブベースの並列実行で処理し、各プランをアトミックな git コミットとしてランディングさせます。
**前提条件:** フェーズに少なくとも 1 つの `PLAN.md` ファイルがあること。プランニングがまだ完了していない場合は、先に `/gsd-plan-phase N` を実行してください — [フェーズのプランニング](plan-a-phase.md) を参照。
---
## フェーズ全体を実行する
```bash
/gsd-execute-phase 1
```
GSD はフェーズのプランファイルを読み込み、依存関係ウェーブにグループ化し、プランごとに新鮮なエグゼキュータエージェントを起動します。各エグゼキュータは次のウェーブが始まる前にアトミックにコミットします。
エージェントがディスパッチされる前に、GSD はウェーブテーブルを表示します:
```
## Execution Plan
Phase 1: Core middleware — 3 plans across 2 wave(s)
| Wave | Plans | What it builds |
|------|----------------|---------------------------|
| 1 | 01-01, 01-02 | Core validation function |
| 2 | 01-03 | Express middleware wrapper |
```
ウェーブ 1 のプランは並列実行されます（それぞれ独立した git ワークツリーで）。ウェーブ 2 はウェーブ 1 のすべてのコミットがマージされるまで待機します。
基礎となるエージェント調整モデルについては [マルチエージェントオーケストレーション](../explanation/multi-agent-orchestration.md) を参照してください。
---
## 単一ウェーブのみ実行する
ウェーブ 1 の出力を確認してからウェーブ 2 に進むなど、1 つのウェーブのみを実行したい場合は `--wave N` を使用します:
```bash
/gsd-execute-phase 1 --wave 2
```
GSD はウェーブ 2 のプランのみを実行します。実行前に前のウェーブがすべて完了しているか確認します。ウェーブ 1 のプランがまだ未完了の場合は、先に前のウェーブを完了するよう指示して停止します。
---
## 実行前に状態を検証する
クラッシュや前の実行の中断後など、`.planning/` ディレクトリがファイルシステムと同期がとれていない可能性がある場合は `--validate` を指定します:
```bash
/gsd-execute-phase 1 --validate
```
GSD はエグゼキュータを起動する前に状態の一貫性チェックを実行します。検出されたずれを報告し、続行前に受け入れるか修正するかを選択できます。
---
## 停止した実行を再開する
クォータエラー、ネットワーク切断、セッションのクラッシュなどで実行が途中停止した場合、ウェーブレベルの進捗は保持されています。GSD は各プランの `SUMMARY.md` ファイルを確認し、すでに存在するプランは再実行時に自動的にスキップされます:
```bash
/gsd-execute-phase 1
```
GSD は `SUMMARY.md` がすでに存在するプランをスキップし、最初の未完了プランから再開します。
**コミットは存在するが `SUMMARY.md` がない場合**（エグゼキュータはコミットしたが、セッションが終了する前にサマリーを書き込まなかった）、GSD はセーフ再開ゲートを表示し、3 つの選択肢を提示します:
- `close out manually` — コミットを確認し、`SUMMARY.md` を書き込んで再実行する
- `re-execute from scratch` — 部分的なコミットを差し戻すか上書きしてから新しいエグゼキュータをディスパッチする
- `mark-and-skip` — 異常を記録して次に進む（明示的な確認が必要）
体系的な障害診断については [実行失敗のデバッグ](debug-a-failed-execution.md) を参照してください。
---
## 出力の場所
すべてのウェーブが完了すると、フェーズディレクトリには以下が含まれます:
```
.planning/phases/01-<name>/
01-01-SUMMARY.md # プラン 01 が構築したもの、主要ファイル、逸脱
01-02-SUMMARY.md
01-03-SUMMARY.md
VERIFICATION.md # 要件ごとの合格/不合格状態
```
`STATE.md` と `ROADMAP.md` はすべてのウェーブが完了すると自動的に更新されます。`VERIFICATION.md` はフェーズが完全に完了した時のみ書き込まれます。
Git の履歴には、各エグゼキュータからのタスクごとのコミットと、オーケストレータからのトラッキングコミットが表示されます。
---
## クロス AI 実行
`workflow.cross_ai_command` で設定された外部 AI CLI（Codex、Gemini など）に実行を委任するには:
```bash
/gsd-execute-phase 2 --cross-ai
```
設定でクロス AI が有効であってもローカル実行を強制するには:
```bash
/gsd-execute-phase 2 --no-cross-ai
```
---
## Related
- [フェーズのプランニング](plan-a-phase.md)
- [検証とシッピング](verify-and-ship.md)
- [実行失敗のデバッグ](debug-a-failed-execution.md)
- [コマンド](../COMMANDS.md)

121
docs/ja-JP/how-to/handle-quick-and-fast-tasks.md Normal file
View File

@@ -0,0 +1,121 @@
# クイックタスクと高速タスクの処理方法
すべての作業がフェーズの中に収まるわけではありません。GSD は、discuss → plan → execute → verify の完全なループを必要としない作業向けに 2 つの軽量コマンドを提供します。
フェーズパイプライン全体がそのオーバーヘッドに見合うかどうかの判断基準については [コンテキストエンジニアリング](../explanation/context-engineering.md) を参照してください。
---
## どちらのコマンドを使うかを決める
| 状況 | コマンド |
|-----------|---------|
| バグ修正、小さな機能追加、または単一の自明な編集として要約できないタスク | `/gsd-quick` |
| タイポ修正、設定値の更新、`.gitignore` へのエントリ追加など、3 ファイル以下でかつ 1 分以内の変更 | `/gsd-fast` |
| タスクに未知の要素があり、リサーチが必要、または複数のファイルに影響する場合 | `--research` 付きの `/gsd-quick` |
**目安:** タスクが自明かどうかを一瞬でも迷ったら `/gsd-quick` を使ってください。`/gsd-fast` はスコープが自明でないと判断した場合、自動的に `/gsd-quick` にリダイレクトします。
---
## `/gsd-quick` — GSD の品質保証付きアドホックタスク
`/gsd-quick` はフルフェーズと同じアトミックコミットおよび STATE.md トラッキングの保証付きでプランナーとエグゼキュータを実行しますが、フェーズのオーバーヘッドなしに動きます（ROADMAP エントリなし、discuss-phase なし、複数プランにまたがるウェーブ調整なし）。
### 基本的な使い方
```bash
/gsd-quick
```
GSD がタスクの説明を求め、プランニングと実行を行います。成果物は `.planning/quick/` に配置されます。
説明を直接渡すこともできます:
```bash
/gsd-quick "Fix the login button not responding on mobile Safari"
```
### フラグ
タスクに応じて品質パイプラインをより多く組み込むためにフラグを追加します。
| フラグ | 追加される内容 |
|------|-------------|
| `--discuss` | プランナー実行前にグレーゾーンを浮き彫りにし、決定事項を `CONTEXT.md` に記録する軽量な事前検討 |
| `--research` | 対象を絞ったリサーチエージェントがプランニング前にアプローチ、ライブラリ、潜在的な問題を調査 |
| `--validate` | プランチェック（最大 2 回の反復）と実行後の検証 |
| `--full` | 上記すべて — `--discuss --research --validate` と同等 |
フラグは自由に組み合わせられます:
```bash
/gsd-quick --research --validate # リサーチ + プランチェック + 検証（検討なし）
/gsd-quick --discuss # プランニング前にグレーゾーンのみ確認
/gsd-quick --full # 完全な品質パイプライン
```
### フラグを追加するタイミング
- タスクへのアプローチや使用するライブラリが不明な場合は `--research` を追加します。
- タスクがクリティカルなコードパスに触れており、検証エージェントに must-haves が満たされたことを確認させたい場合は `--validate` を追加します。
- タスクに設計上の選択肢があり、プランナーが実行する前に確定させたい場合（例: 適切なエラーハンドリングの挙動が明らかでない場合）は `--discuss` を追加します。
- タスクが実質的に重要でフェーズとしてプランするべきだが ROADMAP に含めたくない場合は `--full` を使います。
### クイックタスクの一覧と再開
```bash
/gsd-quick list # すべてのクイックタスクとステータスを表示
/gsd-quick status my-task-slug # 特定のタスクのステータスを表示
/gsd-quick resume my-task-slug # 中断されたタスクを再開
```
---
## `/gsd-fast` — インラインでの自明な編集
`/gsd-fast` は現在のコンテキストで直接作業を実行します。サブエージェント、`PLAN.md`、リサーチはありません。自分で 1 分以内に実行できる変更のみに適しています。
```bash
/gsd-fast "fix typo in README"
/gsd-fast "add .env to .gitignore"
```
説明を省略すると GSD が求めます。
`/gsd-fast` は続行前にタスクが実際に自明かどうかを確認します。スコープが大きすぎると判断した場合は停止してリダイレクトします:
```text
This looks like it needs planning. Use /gsd-quick instead:
/gsd-quick "your task description"
```
変更後、`/gsd-fast` はアトミックにコミットし、`.planning/STATE.md` に `Quick Tasks Completed` テーブルが存在する場合はその行を追記します。
---
## `/gsd-quick` が `/gsd-fast` にない機能
| 機能 | `/gsd-fast` | `/gsd-quick` |
|------------|------------|--------------|
| サブエージェントプランナー | なし | あり |
| サブエージェントエグゼキュータ | なし | あり |
| リサーチエージェント | なし | オプション（`--research`） |
| プランチェック | なし | オプション（`--validate`） |
| 実行後の検証 | なし | オプション（`--validate`） |
| 検討フェーズ | なし | オプション（`--discuss`） |
| ワークツリー分離 | なし | あり（デフォルト） |
| タスクごとのアトミックコミット | 単一コミット | プランタスクごとに 1 つ |
| STATE.md トラッキング | テーブルが存在すれば行を追記 | 常に更新 |
| `.planning/quick/` 成果物 | なし | あり |
主な違いはサブエージェントの分離です。`/gsd-quick` は新鮮なプランナーとエグゼキュータを別々のコンテキストウィンドウで起動するため、作業が適切にプランされ、コミットはタスクごとにアトミックになり、オーケストレータが結果を検証できます。`/gsd-fast` は現在のコンテキストウィンドウのみを使用し、それらを必要としないほど自明な変更に意図的に限定されています。
---
## Related
- [フェーズループ](../explanation/the-phase-loop.md)
- [コンテキストエンジニアリング](../explanation/context-engineering.md)
- [コマンド](../COMMANDS.md)
- [ドキュメント索引](../README.md)

291
docs/ja-JP/how-to/install-on-your-runtime.md Normal file
View File

@@ -0,0 +1,291 @@
# ランタイムへの GSD Core インストール方法
GSD Core（`@opengsd/gsd-core`）を普段使いの AI コーディングランタイムにインストールします。このガイドでは、サポートされている各ランタイム向けの標準インストール手順と、Node.js がない環境向けの手動手順を説明します。
**必要なもの:** Node.js 18 以上と npm（または npx）。Node.js がない場合は [Node.js なしでのインストール](#nodejs-なしでのインストール) へ進んでください。
---
## インストーラーが必要な理由
GSD Core は Claude Code のネイティブ frontmatter 形式でエージェントファイルとコマンドファイルを提供しています。サポートされている各ランタイムは、異なるスキーマ、ディレクトリ構成、コマンド呼び出し構文を要求します。インストーラーは必要な変換を実行します。たとえば OpenCode 向けのツールリストとカラー値の変換、Codex 向けの TOML エージェントエントリの書き込み、Gemini CLI 向けのすべてのコマンド本文をハイフン形式（`/gsd-update`）からコロン形式（`/gsd:update`）への書き換えなどです。
**`agents/` や `commands/` からファイルを直接コピーしないでください。** そうするとこれらの変換がスキップされ、スキーマ検証エラーやコマンドの欠落が発生します。
---
## 標準インストール
任意のディレクトリからインストーラーを実行します。ランタイムの選択と、グローバル（全プロジェクト）またはローカル（このプロジェクトのみ）のどちらでインストールするかを確認するプロンプトが表示されます。
```bash
npx @opengsd/gsd-core@latest
```
新規インストールやランタイムの切り替え後にインストーラーを再実行する場合も、このコマンド 1 つだけで完結します。
---
## ランタイム別のインストール手順
### Claude Code
```bash
npx @opengsd/gsd-core@latest --claude --global
```
スキルは `~/.claude/` に配置されます。次回の Claude Code セッションからコマンドが `/gsd-*` スラッシュコマンドとして表示されます。反映するには Claude Code を再起動してください。
**インストールディレクトリの上書き:**
```bash
CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global
```
---
### Gemini CLI
```bash
npx @opengsd/gsd-core@latest --gemini --global
```
スキルは `~/.gemini/` に配置されます。インストーラーはすべてのコマンド本文を Gemini のコロン名前空間（`/gsd:update`、`/gsd:config` など）に書き換えます。インストール後は Gemini CLI を再起動してください。
**インストールディレクトリの上書き:**
```bash
GEMINI_CONFIG_DIR=~/.gemini-alt npx @opengsd/gsd-core@latest --gemini --global
```
---
### OpenCode
```bash
npx @opengsd/gsd-core@latest --opencode --global
```
スキルは `~/.config/opencode/`（XDG）または `~/.opencode/` に配置されます。インストーラーはエージェントの frontmatter を OpenCode のスキーマに変換します（`tools:` フィールドの削除、カラー値の hex 変換）。変更内容の詳細は [Node.js なしでのインストール — OpenCode の変換内容](#opencode--必要な変換) を参照してください。
**インストールディレクトリの上書き:**
```bash
OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @opengsd/gsd-core@latest --opencode --global
```
---
### Kilo
```bash
npx @opengsd/gsd-core@latest --kilo --global
```
スキルは `~/.config/kilo/`（XDG）または `~/.kilo/` に配置されます。OpenCode と同じフラットな Markdown コマンド形式を使用します。
**インストールディレクトリの上書き:**
```bash
KILO_CONFIG_DIR=~/.config/kilo-alt npx @opengsd/gsd-core@latest --kilo --global
```
---
### Codex
```bash
npx @opengsd/gsd-core@latest --codex --global
```
スキルは `~/.codex/skills/gsd-*/SKILL.md` に配置されます。エージェントは `config.toml` にエージェントごとの TOML エントリとして書き込まれます。インストール後は Codex を再起動（または `codex --reload` を実行）してください。
**最低サポートバージョン:** Codex CLI 0.130.0。それより古いバージョンにはスキルルートの追加スキャン処理があり、重複リストが生じることがあります。
---
### GitHub Copilot
```bash
npx @opengsd/gsd-core@latest --copilot --global
```
スキルは `~/.copilot/` に配置されます。GSD はエージェント `.md` ファイルとリポジトリ instruction ファイルとしてインストールされます。
**インストールディレクトリの上書き:**
```bash
COPILOT_CONFIG_DIR=~/.copilot-alt npx @opengsd/gsd-core@latest --copilot --global
```
---
### Cursor
```bash
npx @opengsd/gsd-core@latest --cursor --global
```
スキルは `~/.cursor/` に配置されます。GSD はスキル、エージェント、ルールの参照をインストールします。
**インストールディレクトリの上書き:**
```bash
CURSOR_CONFIG_DIR=~/.cursor-alt npx @opengsd/gsd-core@latest --cursor --global
```
---
### Windsurf
```bash
npx @opengsd/gsd-core@latest --windsurf --global
```
スキルは `~/.codeium/windsurf/` に配置されます。GSD はスキル、エージェント、ワークスペースルールをインストールします。
**インストールディレクトリの上書き:**
```bash
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-alt npx @opengsd/gsd-core@latest --windsurf --global
```
---
### Cline
Cline はルールベースの統合方式を使用します。GSD はスラッシュコマンドではなく `.clinerules` としてインストールされます。
```bash
# グローバルインストール（全プロジェクト）
npx @opengsd/gsd-core@latest --cline --global
# ローカルインストール（このプロジェクトのみ）
npx @opengsd/gsd-core@latest --cline --local
```
グローバルインストールは `~/.cline/` に書き込みます。ローカルインストールは `./.cline/` に書き込みます。ルールは Cline によって自動的に読み込まれます。カスタムのスラッシュコマンドは登録されません。
---
### CodeBuddy
```bash
npx @opengsd/gsd-core@latest --codebuddy --global
```
スキルは `~/.codebuddy/skills/gsd-*/SKILL.md` に配置されます。
---
### Qwen Code
Qwen Code は Claude Code 2.1.88 以降と同じオープンスキル標準を使用します。
```bash
npx @opengsd/gsd-core@latest --qwen --global
```
スキルは `~/.qwen/skills/gsd-*/SKILL.md` に配置されます。
**インストールディレクトリの上書き:**
```bash
QWEN_CONFIG_DIR=~/.qwen-alt npx @opengsd/gsd-core@latest --qwen --global
```
---
### Augment Code
```bash
npx @opengsd/gsd-core@latest --augment --global
```
スキルは `~/.augment/` に配置されます。GSD はスキルとエージェントをインストールします。フックや statusline の管理は行いません。
---
### Antigravity
```bash
npx @opengsd/gsd-core@latest --antigravity --global
```
インストーラーは Antigravity の設定ディレクトリ（`~/.gemini/antigravity`、`~/.gemini/antigravity-ide`、または `~/.gemini/antigravity-cli`）を自動検出します。Gemini 互換の設定ポリシーを使用します。
**インストールディレクトリの上書き:**
```bash
ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @opengsd/gsd-core@latest --antigravity --global
```
---
### Trae
```bash
npx @opengsd/gsd-core@latest --trae --global
```
スキルは `~/.trae/` に配置されます。GSD はスキル、エージェント、ルールの参照をインストールします。
---
## ローカルインストールとグローバルインストール
上記の例はすべて `--global` を使用しており、ユーザーアカウント全体に GSD を一度インストールします。インストールを単一プロジェクトに限定するには、`--global` を `--local` に置き換えます。
```bash
npx @opengsd/gsd-core@latest --claude --local
```
ローカルインストールはプロジェクトルートの `.claude/` ディレクトリに書き込みます。両方が存在する場合、ローカルインストールの設定がグローバルの設定より優先されます。
---
## プレリリースエディション（Next / Nightly / Insiders / Preview）のインストール
ランタイムのプレリリースエディション（Windsurf Next、Cursor Nightly、VS Code Insiders、Codex preview チャンネルなど）は、隣接する設定ディレクトリから読み込みます。インストーラーを実行する前に対応する `*_CONFIG_DIR` 環境変数を設定してください。
```bash
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
```
インストーラーのプロンプトでは対応する安定版ランタイムを選択してください。GSD はプレリリースエディションを独立した名前付きランタイムとしては列挙していません。これらは環境変数によるベストエフォートの対応であり、リリース CI では個別にテストされていません。
---
## Node.js なしでのインストール
`npx` が実行できない場合（例：Node.js がない Windows マシン）、2 つの選択肢があります。
**選択肢 A — Node.js がある別のマシンを使用する。** WSL、Linux VM、CI ランナー、Docker コンテナなど、Node.js があるマシンであれば何でも使えます。そのマシンでインストーラーを実行し、出力ディレクトリをターゲットマシンにコピーします。OpenCode の場合:
```bash
npx @opengsd/gsd-core@latest --opencode --global
# その後 ~/.config/opencode/agents/ を Windows マシンにコピー
```
**選択肢 B — ソースファイルを手動で変換する。** エージェントのソースファイルは GSD Core リポジトリの `agents/` に存在し、Claude Code のネイティブ frontmatter 形式になっています。各ランタイムは異なる形式を要求します。ランタイムごとの正確なフィールド変換については、ユーザーガイドの [Manual install / no-Node.js setup](../USER-GUIDE.md#manual-install--no-nodejs-setup) を参照してください。OpenCode の変換内容が詳しく説明されており、他のランタイム向けのインストーラーの `convert*Frontmatter` 関数も案内されています。
---
## インストール後の作業
新しいコマンドとエージェントを反映するためにランタイムを再起動してください。その後、最初のプロジェクトを開始します。
```bash
/gsd-new-project
```
再起動後もコマンドが見つからない場合は、インストールディレクトリがランタイムの期待する設定パスと一致しているか確認してください。最もよくある不一致については上記のプレリリースエディションのセクションを参照してください。
---
## Related
- [最初のプロジェクト](../tutorials/your-first-project.md)
- [GSD Core の更新](update-gsd.md)
- [設定](../CONFIGURATION.md)
- [ドキュメント索引](../README.md)

144
docs/ja-JP/how-to/isolate-work-with-workspaces.md Normal file
View File

@@ -0,0 +1,144 @@
# ワークスペースで作業を分離する方法
**目標:** 独立した git ワークツリー、独自の `.planning/` ルート、そして必要に応じて複数リポジトリを持つ、完全に分離された GSD 環境をフィーチャーブランチやマルチリポジトリ作業のために作成する。
**前提条件:** `git` がインストールされており、リポジトリがワークツリーをサポートしていること。マルチリポジトリのワークスペースの場合、対象リポジトリがローカルマシン上に存在するか、パスでアクセス可能であること。
---
## ワークスペースとは
ワークスペースは、1 つ以上の git ワークツリー（またはクローン）と独自の `.planning/` ルートディレクトリを組み合わせた、自己完結型の環境です。各ワークスペースには以下が含まれます。
- ソースリポジトリの `.planning/` とは**完全に独立した**独自の `.planning/` ディレクトリ（サブディレクトリではない）
- メンバーリポジトリを追跡する独自の `WORKSPACE.md` マニフェスト
- 指定されたリポジトリの git ワークツリー（デフォルト）またはフルクローン（専用ブランチ `workspace/<name>` でチェックアウト）
ワークスペースはデフォルトで `~/gsd-workspaces/<name>/` 以下に配置されます。
```
~/gsd-workspaces/
└── feature-b/
├── WORKSPACE.md ← マニフェスト
├── .planning/ ← 完全に独立した GSD 状態
│ ├── PROJECT.md
│ ├── ROADMAP.md
│ └── ...
├── hr-ui/ ← hr-ui リポジトリのワークツリーまたはクローン
└── ZeymoAPI/ ← ZeymoAPI リポジトリのワークツリーまたはクローン
```
ワークスペースの `.planning/` はソースリポジトリとは独立しているため、ソースリポジトリ内に存在する計画状態との重複や競合は発生しません。
---
## 複数リポジトリのワークスペースを作成する
```bash
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
```
GSD は `~/gsd-workspaces/feature-b/` 内に `hr-ui` と `ZeymoAPI` のワークツリーを作成し、それぞれに `workspace/feature-b` ブランチをチェックアウトし、`WORKSPACE.md` を書き込み、`/gsd-new-project` に備えた空の `.planning/` ディレクトリを作成します。
場所をカスタマイズするには：
```bash
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI --path /projects/feature-b
```
---
## 現在のリポジトリのワークスペースを作成する
単一リポジトリでフィーチャーブランチの分離が必要な場合（独立したブランチ、独立した `.planning/`、main からの状態汚染なし）：
```bash
/gsd-workspace --new --name payments-rework --repos .
```
`.` は現在のリポジトリのワークツリーを作成するよう GSD に指示します。ワークツリーは `workspace/payments-rework` でチェックアウトされます。
ワークツリーの代わりにフルクローンを強制するには：
```bash
/gsd-workspace --new --name payments-rework --repos . --strategy clone
```
---
## ブランチを明示的に指定する
```bash
/gsd-workspace --new --name payments-rework --repos . --branch feature/payments-v2
```
`--branch` フラグはワークスペース内のすべてのリポジトリのブランチ名を設定します。デフォルトは `workspace/<name>` です。
---
## 対話的な質問をスキップする
```bash
/gsd-workspace --new --name payments-rework --repos . --auto
```
GSD はプロンプトなしですべてのデフォルト値を適用します。
---
## ワークスペース内で GSD を初期化する
ワークスペースを作成したら、その中に移動して GSD プロジェクトを初期化します。
```bash
cd ~/gsd-workspaces/feature-b
/gsd-new-project
```
ワークスペース内の `.planning/` ディレクトリは、そのディレクトリから実行されるすべての GSD コマンドのルートとなります。ソースリポジトリ内に存在する `.planning/` とは完全に独立しています。
---
## ワークスペースを一覧表示する
```bash
/gsd-workspace --list
```
アクティブなすべての GSD ワークスペースとそのステータスを表示します。
---
## ワークスペースを削除する
```bash
/gsd-workspace --remove feature-b
```
GSD は git ワークツリーを削除し、ワークスペースディレクトリをクリーンアップします。リモートのブランチは削除されません。ローカルのワークツリーとワークスペースディレクトリのみが対象です。
---
## ワークストリームではなくワークスペースを選ぶ場面
ワークスペースを選ぶべき場合：
- 1 つの GSD プロジェクトとして連携させる必要がある**複数のリポジトリ**（例：一緒にリリースする API リポジトリと UI リポジトリ）にまたがって作業している
- フィーチャーごとに独自のブランチ、ロックファイル、ビルド成果物を持つ**独立した git ワークツリー**が必要（あるビルド環境での依存関係インストールが他に影響しない）
- メインリポジトリの `.planning/` のサブディレクトリではなく、**完全に独立した `.planning/` ルート**が必要
- 各トラッカーイシューをワークスペースにマッピングするイシュー駆動ワークフローを採用している（[トラッカーイシューから GSD を操作する](drive-gsd-from-a-tracker-issue.md)を参照）
代わりに[ワークストリーム](work-in-parallel-with-workstreams.md)を選ぶべき場合：
- すべての作業が**1 つのリポジトリ**内にあり、同じ git 履歴を共有している
- API、UI、インフラなどの異なる関心領域で `/gsd-plan-phase` や `/gsd-discuss-phase` を並行して実行したいが、各領域の `STATE.md` ファイル間でのコンテキスト汚染を避けたい
- 関心領域ごとに別のワークツリーは不要で、計画コンテキストの切り替えで十分
---
## Related
- [ワークストリームを使って並行して作業する](work-in-parallel-with-workstreams.md)
- [トラッカーイシューから GSD を操作する](drive-gsd-from-a-tracker-issue.md)
- [コマンドリファレンス](../COMMANDS.md)
- [ドキュメント一覧](../README.md)

145
docs/ja-JP/how-to/migrate-from-gsd-2.md Normal file
View File

@@ -0,0 +1,145 @@
# GSD-2 から移行する方法
**目標:** 古い GSD-2 プロジェクト（`.gsd/` ディレクトリレイアウト）を GSD Core（`.planning/` レイアウト）に移行し、リポジトリ内に存在する ADR、PRD、仕様書などを新しい計画構造に取り込む。
**前提条件:** GSD Core がインストール済みであること。GSD-2 プロジェクトディレクトリがディスク上にアクセス可能な状態であること。
---
## 何が移行されるかを理解する
GSD-2 は計画ルートとして `.gsd/` ディレクトリを使用していました。GSD Core は `.planning/` を使用します。移行はこれを逆転させます。`.gsd/` の成果物を読み込み、すべての GSD Core コマンドが期待する標準的な `.planning/` 構造に書き込みます。
| GSD-2 に存在するもの | `/gsd-import --from-gsd2` が生成するもの |
|----------------------|-----------------------------------------|
| `.gsd/PROJECT.md` | `.planning/PROJECT.md` |
| `.gsd/ROADMAP.md` | `.planning/ROADMAP.md` |
| `.gsd/STATE.md` | `.planning/STATE.md` |
| `.gsd/phases/` ディレクトリ | `.planning/phases/` ディレクトリ |
| フェーズの `PLAN.md` ファイル | GSD Core の `{NN}-{MM}-PLAN.md` ファイル（名前変更を強制） |
ファイルが書き込まれる前に競合検出が実行されます。対象ディレクトリにすでに `PROJECT.md` があり、インポートするコンテンツと矛盾する場合、移行は BLOCKER ゲートで停止し、解決すべき競合を一覧表示します。
---
## 移行を実行する
### 現在のディレクトリを移行する
```bash
/gsd-import --from-gsd2
```
GSD は現在の作業ディレクトリの `.gsd/` を読み込み、移行した成果物を `.planning/` に書き込みます。
### 別のパスから移行する
```bash
/gsd-import --from-gsd2 --path ~/projects/old-project
```
GSD-2 プロジェクトが現在の作業ディレクトリでない場合は `--path` を使用します。
---
## 競合を解決する
競合検出がブロッカーを見つけた場合（例：GSD-2 の技術スタック宣言が既存の `.planning/PROJECT.md` と矛盾する）、競合レポートを表示してファイルを書き込まずに停止します。
レポートを読み、矛盾を解消（ソース文書または既存の計画成果物を編集）してから、`/gsd-import --from-gsd2` を再実行します。移行はクリーンに通過するまで安全に再実行できます。
---
## 外部プランファイルをインポートする
完全な GSD-2 プロジェクトではなく、スタンドアロンのプランドキュメント（チームの計画ドキュメント、Markdown 仕様、エクスポートされたタスクリスト）がある場合は、代わりに `--from` を使用します。
```bash
/gsd-import --from /tmp/team-plan.md
```
GSD は同じ競合検出パスを実行し、コンテンツを GSD Core の `PLAN.md` 形式に変換し、プランチェッカーで結果を検証します。検証後、対象ファイル名と次のステップが表示されます。
---
## 既存のドキュメントを取り込む
リポジトリに ADR（アーキテクチャ決定記録）、PRD、仕様ドキュメントがすでに存在する場合は、移行後に `/gsd-ingest-docs` を使って `.planning/` 構造に統合します。
### リポジトリ全体をスキャンする（モードを自動検出）
```bash
/gsd-ingest-docs
```
`.planning/` がすでに存在する場合（例：今実行した移行から）、GSD はデフォルトでマージモードになります。既存のものを上書きするのではなく、インポートしたドキュメントを既存のものと並べて統合します。
### 特定のディレクトリにスコープを絞る
```bash
/gsd-ingest-docs docs/
/gsd-ingest-docs docs/adr/
```
### 明示的な優先度マニフェストを使用する
ドキュメントのタイプが混在している場合や、競合時にどのドキュメントが優先されるかを制御したい場合：
```bash
/gsd-ingest-docs --manifest ingest.yaml
```
マニフェストはドキュメントごとに `{path, type, precedence?}` を列挙する YAML ファイルです。期待される形式については、[コマンドリファレンス](../COMMANDS.md)の `--manifest` フラグの説明を参照してください。
### 特定のモードを強制する
```bash
/gsd-ingest-docs --mode merge # 既存の .planning/ にマージする
/gsd-ingest-docs --mode new # 最初から構築する（上書き）
```
**出力:** `/gsd-ingest-docs` は常に 3 つのバケット（自動解決済み、競合バリアント、未解決ブロッカー）を含む `INGEST-CONFLICTS.md` を生成します。すべてのインポート実行後にこのファイルを確認してください。ハードストップは LOCKED 対 LOCKED の ADR 矛盾の場合のみ発生します。それ以外はすべて確認のために表示され、サイレントに破棄されることはありません。
---
## 移行したプロジェクトを検証する
移行とドキュメントの取り込みが完了したら、プロジェクト状態の一貫性を確認します。
```bash
/gsd-health
/gsd-health --repair
```
`/gsd-health` は `.planning/` ディレクトリの整合性を確認し、ドリフトを報告します。`--repair` は回復可能な問題を自動修正します。
次に、GSD Core がプロジェクト状態を読み込めることを確認します。
```bash
/gsd-progress
```
プロジェクトが正常に移行されていれば、現在のフェーズステータスと推奨される次のステップが表示されます。ここから標準的な GSD Core ワークフローが適用されます。
---
## 条件分岐：何が移行されて何がされないか
| 状況 | 対応 |
|-----------|-----------|
| `.gsd/` が現在のディレクトリにある | `/gsd-import --from-gsd2` を実行する（`--path` 不要） |
| `.gsd/` が別のディレクトリにある | `--path ~/projects/old-project` を使用する |
| 完全な GSD-2 プロジェクトではなくスタンドアロンのプランドキュメントがある | `/gsd-import --from /path/to/plan.md` を使用する |
| `docs/adr/` に ADR がある | 移行後に `/gsd-ingest-docs docs/adr/` を実行する |
| ADR、PRD、仕様の混在がある | リポジトリルートで `/gsd-ingest-docs` を実行する（自動分類） |
| 競合検出がブロッカーを報告する | 一覧表示された矛盾を解消してから再実行する；すべてのブロッカーがクリアになるまでファイルは書き込まれない |
| 移行が成功したか不明 | `/gsd-health` と `/gsd-progress` を実行して確認する |
| INGEST-CONFLICTS.md に未解決のブロッカーが残っている | 対象ドキュメントが計画に取り込まれる前に手動での解決が必要 |
---
## Related
- [初めてのプロジェクト](../tutorials/your-first-project.md)
- [コマンドリファレンス](../COMMANDS.md)
- [ドキュメント一覧](../README.md)

216
docs/ja-JP/how-to/plan-a-phase.md Normal file
View File

@@ -0,0 +1,216 @@
# フェーズのプランニング方法
**目的:** フェーズの決定事項とリサーチを、実行可能なアトミックかつ検証可能なタスクプランに変換します。
**前提条件:** `.planning/ROADMAP.md` が存在すること。`/gsd-discuss-phase` で生成した `{phase}-CONTEXT.md` を強く推奨しますが、必須ではありません。
---
## 標準的なプランニングフローを実行する
```bash
/gsd-plan-phase 2
```
これにより 3 つのステージが順番に実行されます:
1. **リサーチ** — `gsd-phase-researcher` サブエージェントがドメインを調査し、`{phase}-RESEARCH.md` を書き込みます。
2. **プラン** — `gsd-planner` サブエージェントがコンテキスト、リサーチ、要件を読み込み、1 つ以上の `{phase}-{N}-PLAN.md` ファイルを書き込みます。
3. **検証** — `gsd-plan-checker` サブエージェントが 8 つの次元でプランの品質を検証し、品質ゲートが通過するまでリビジョンループ（最大 3 回）を実行します。
フェーズ番号を指定しない場合、GSD Core はロードマップから次の未プランフェーズを対象にします。
---
## リサーチをスキップまたは強制する
**ドメインに習熟しており新規リサーチが不要な場合:**
```bash
/gsd-plan-phase 3 --skip-research
```
**RESEARCH.md がすでに存在するが強制的に更新したい場合:**
```bash
/gsd-plan-phase 3 --research
```
**リサーチのみ実行したい場合** — RESEARCH.md を書き込んでプランニング前に終了:
```bash
/gsd-plan-phase --research-phase 4
```
RESEARCH.md がすでに存在する場合、更新・表示・スキップのプロンプトが表示されます。プロンプトなしに強制更新するには:
```bash
/gsd-plan-phase --research-phase 4 --research
```
既存の RESEARCH.md をリサーチャーを起動せずに標準出力に表示するには:
```bash
/gsd-plan-phase --research-phase 4 --view
```
注意: `--research-phase <N>` は `/gsd-plan-phase` のフラグです。独立したリサーチフェーズコマンドは存在しません。以前の独立したリサーチコマンドはこのフラグに移行されました。
---
## 水平レイヤーではなく垂直フィーチャースライスでプランする
**技術レイヤー別ではなく、薄いエンドツーエンドスライス**（フィーチャーごとに UI → API → DB）でタスクを整理したい場合:
```bash
/gsd-plan-phase 1 --mvp
```
以前のフェーズサマリーがない新規プロジェクトのフェーズ 1 では、`--mvp` は `SKELETON.md` も生成します。これはプロジェクトの骨格、ルーティング、実際の DB 読み書き 1 件、実際の UI インタラクション 1 件、開発用デプロイをカバーするウォーキングスケルトンです。
フラグなしでフェーズを MVP モードに設定するには、ROADMAP.md のそのフェーズのエントリに `**Mode:** mvp` を追加します。
---
## 振る舞いを追加するタスクごとに失敗するテストを要求する
**TDD 強制**が必要な場合 — 振る舞いを追加する各タスクは実装前に失敗するテストから始まります:
```bash
/gsd-plan-phase 1 --tdd
```
`--mvp` との組み合わせ:
```bash
/gsd-plan-phase 1 --mvp --tdd
```
これにより、振る舞いを追加するすべてのタスクが RED → GREEN → REFACTOR に従う垂直スライスが生成されます。プランナーは対象タスク（ビジネスロジック、API エンドポイント、データ変換）に `type: tdd` を適用し、UI、設定、グルーコードには標準の `type: execute` を使用します。
TDD モードは設定でも永続化できます:
```bash
node gsd-tools.cjs config-set workflow.tdd_mode true
```
---
## クロス AI レビューのフィードバックを使ってリプランする
**`/gsd-review --phase N` を実行済みで `REVIEWS.md` が存在する場合:**
```bash
/gsd-plan-phase 3 --reviews
```
プランナーは `REVIEWS.md` を読み込み、フィードバックに対応するようプランを修正します。`--gaps` との組み合わせはできません。
**自動ループが必要な場合** — HIGH 懸念がなくなるまでリプランと再レビューを繰り返す:
```bash
/gsd-plan-review-convergence 3
```
コンバージェンスループは plan → review → replan → re-review サイクルを（デフォルト最大 3 回）実行します。上限を変更するには `--max-cycles N` を使用します。
---
## 検証失敗後にギャップを埋める
**`VERIFICATION.md` に未解決のギャップが存在し、そのギャップのみを対象にリプランしたい場合:**
```bash
/gsd-plan-phase 3 --gaps
```
リサーチはスキップされ、プランナーは検証ギャップを直接読み込みます。
---
## プランニング開始前にプロジェクト状態を検証する
```bash
/gsd-plan-phase 2 --validate
```
リサーチャーを起動する前に状態検証を実行します。ROADMAP.md や STATE.md がずれている可能性がある場合に使用してください。
---
## プランニング後に外部バウンス検証を実行する
**`workflow.plan_bounce_script` が設定されており、完成したプランに対して外部検証を行いたい場合:**
```bash
/gsd-plan-phase 1 --bounce
```
設定でバウンスが有効でも実行をスキップするには:
```bash
/gsd-plan-phase 1 --skip-bounce
```
---
## インタラクティブな確認を抑制する
```bash
/gsd-plan-phase --auto
```
すべてのプロンプトをスキップします。自動化パイプラインで役立ちます。設定で `research_enabled` が false の場合、リサーチはスキップされます。
---
## プランが生成するもの
成功した実行では以下が書き込まれます:
| ファイル | 目的 |
|---|---|
| `{phase}-RESEARCH.md` | ドメインリサーチ、パッケージ正当性監査、検証アーキテクチャ |
| `{phase}-VALIDATION.md` | Nyquist テストマッピング — プランが満たすべきテストケース（次元 8） |
| `{phase}-{N}-PLAN.md` | フロントマター、ウェーブ割り当て、受け入れ基準を含む実行可能タスクプラン |
| `{phase}/SKELETON.md` | ウォーキングスケルトン（MVP モード、新規プロジェクトのフェーズ 1 のみ） |
各 PLAN.md には必須の `<read_first>` と `<acceptance_criteria>` フィールドを持つタスクが含まれます。すべての `<acceptance_criteria>` エントリは、ソースアサーション、振る舞いアサーション、テストコマンド、または CLI 出力として検証可能です。主観的な表現は使用しません。
完全なフィールドリファレンスは [PLAN.md スキーマ](../reference/plan-md.md) を参照してください。
### プラン品質の次元
`gsd-plan-checker` は実行を許可する前に 8 つの次元でプランを検証します:
1. タスクのアトミック性 — 各タスクは単一の関心事
2. 依存関係の正確性 — ウェーブの順序が一貫している
3. 受け入れ基準の検証可能性 — 主観的な基準がない
4. `<read_first>` の完全性 — 変更対象のファイルが常にリストされている
5. 具体的な `<action>` 値 — 「〜と合わせる」のような曖昧な指示がない
6. フェーズ目標から導出された `must_haves`
7. 要件 ID のカバレッジ — すべてのフェーズ要件 ID が少なくとも 1 つのプランに存在する
8. Nyquist テストマッピング — プランが VALIDATION.md の検証戦略に対応している
リビジョンループは最大 3 回実行されます。3 回の反復後も品質ゲートが通過しない場合、チェッカーは残りの問題を手動レビュー用に提示します。
---
## クローズ済みフェーズのリプランニング
フェーズに `status: passed` の `VERIFICATION.md` がある場合、そのフェーズはクローズ済みと見なされます。リプランを試みるとエラーで停止します。クローズが誤っていた場合は `--force` で上書きします:
```bash
/gsd-plan-phase 2 --force
```
トランスクリプトおよびコミット済みのプランドキュメントに警告が出力されます。
---
## Related
- [フェーズの検討](discuss-a-phase.md)
- [フェーズの実行](execute-a-phase.md)
- [PLAN.md スキーマ](../reference/plan-md.md)
- [コマンド](../COMMANDS.md)

323
docs/ja-JP/how-to/recover-and-troubleshoot.md Normal file
View File

@@ -0,0 +1,323 @@
# 回復とトラブルシューティングの方法
**目標:** コンテキストの喪失や状態の破損からインストール失敗やパーミッションエラーまで、条件分岐レシピ構造を使って一般的な問題を特定して修正する。
**前提条件:** GSD Core がインストール済みであること。インストールの問題については、[ランタイムへのインストール](install-on-your-runtime.md)を参照してください。
---
## コンテキストとセッションの問題
### 現在の位置を見失った場合
```bash
/gsd-progress
```
すべての状態ファイルを読み込み、現在地と次にすべきことを正確に教えてくれます。
正しい次のステップに自動的に進むには：
```bash
/gsd-progress --next
```
### 新しいセッションを開始してコンテキストを復元する必要がある場合
```bash
/gsd-resume-work
```
最後のハンドオフから、現在のフェーズ・計画上の決定・作業が停止した場所を含む完全なセッションコンテキストを復元します。
### 長いセッションで品質が低下している場合
主要なコマンド間でコンテキストウィンドウをクリアします。
```bash
/clear
```
その後、状態を復元します。
```bash
/gsd-resume-work
```
GSD は新鮮なコンテキストを前提に設計されています。すべてのサブエージェントはすでにクリーンな 200k ウィンドウを取得します。メインセッションは時間とともに劣化します。プッシュし続けるのではなく、クリアして再開することが正しい対処法です。
### 停止前にコンテキストを保存したい場合
```bash
/gsd-pause-work
```
現在の位置を含む `.planning/HANDOFF.json` を作成します。セッション後のサマリーを `.planning/reports/` にも書き込む場合は `--report` を追加します。
```bash
/gsd-pause-work --report
```
---
## 計画整合性の問題
### `.planning/` の整合性が不確かな場合
```bash
/gsd-health
```
エラー、警告、情報ノートにわたるステータスを報告します。
| ステータス | 意味 |
|--------|---------|
| `HEALTHY` | 期待される成果物がすべて存在し、正しい形式である |
| `DEGRADED` | 対処すべき警告があるが作業は続行できる |
| `BROKEN` | 実行をブロックする重大なエラーがある |
自動修復可能な一般的な問題（エラー E004、E005；警告 W003、W008）：
```bash
/gsd-health --repair
```
これにより不足している `STATE.md` が再作成され、破損した `config.json` がデフォルトにリセットされ、不足している設定キーが追加されます。`PROJECT.md` や `ROADMAP.md` は上書きされません。
### STATE.md が存在しないフェーズを参照している場合
これは警告 `W002` を生成します。状態 CLI を使って診断と修復を行います。
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate
```
書き込まずに同期で何が変わるかをプレビューします。
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify
```
同期を適用します。
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync
```
これらのコマンドはディスク上の実際のプロジェクト状態から `STATE.md` を再構築します。手動での `STATE.md` 編集に代わるものです。
### 「Project already initialised」と表示される場合
`.planning/PROJECT.md` がすでに存在します。`/gsd-new-project` は安全チェックです。本当に最初からやり直したい場合は、まず `.planning/` ディレクトリを削除します。
```bash
rm -rf .planning/
```
その後 `/gsd-new-project` を再実行します。
### コンテキストウィンドウの使用率が高い場合
```bash
/gsd-health --context
```
コンテキストウィンドウ使用率ガードを調査します。60% で警告、70% でクリティカル。警告閾値を超えている場合は、次の主要なコマンドを開始する前に `/clear` を実行してから `/gsd-resume-work` を実行してください。
---
## 実行の問題
### エグゼキューターが Bash コマンドで「Permission denied」になる場合
GSD の `gsd-executor` サブエージェントには書き込み可能な Bash アクセスが必要です。`~/.claude/settings.json` の `permissions.allow` に必要なパターンを追加します。最低限：
```json
"Bash(git add:*)",
"Bash(git commit:*)",
"Bash(git merge:*)",
"Bash(git checkout:*)"
```
スタック固有のパターン（Rails、Python、Node、Rust）については、`docs/USER-GUIDE.md` の「Executor Subagent Gets Permission denied」の下にある完全な表を参照してください。
プロジェクト単位の代替手段：プロジェクトルートの `.claude/settings.local.json` に同じブロックを追加する。
### 実行が失敗するか、スタブが生成される場合
プランが過度に野心的でないか確認してください。プランには最大でも 2〜3 個のタスクを含めるべきです。タスクが大きすぎると、単一のコンテキストウィンドウが確実に生成できる範囲を超えます。より小さいスコープでフェーズを再計画します。
```bash
/gsd-plan-phase 1
```
何が起きたかを体系的に診断するには、[フェーズ実行の失敗をデバッグする](debug-a-failed-execution.md)を参照してください。
### 並行実行がビルドロックエラーやプリコミットフック失敗を引き起こす場合
これは複数のエージェントが同時にビルドツールをトリガーすることで発生します。GSD は v1.26 以降、これを自動的に処理します。古いバージョンを使用している場合、またはまだ競合が見られる場合は、並行実行を無効にします。
```bash
/gsd-settings
```
`parallelization.enabled` を `false` に設定します。
### サブエージェントが失敗しているように見えるがコミットが行われている場合
何かが壊れていると判断する前に git ログを確認します。
```bash
git log --oneline -10
```
Claude Code の既知の分類バグで、作業が成功したのに失敗と報告される場合があります。GSD のオーケストレーターは実際の出力をスポットチェックしますが、不一致が見られる場合はコミットが真実です。
---
## プランとフェーズの問題
### プランが意図と異なる、または整合していない場合
計画前に `/gsd-discuss-phase N` を実行します。プランの品質問題のほとんどは、`CONTEXT.md` があれば防げた前提から生じます。
```bash
/gsd-discuss-phase 1
```
完全なセッションを開始せずに GSD が現在行っている前提を確認するには：
```bash
/gsd-discuss-phase 3 --assumptions
```
### 実行後に何かを変更する必要がある場合
`/gsd-execute-phase` を再実行しないでください。対象を絞った修正には `/gsd-quick` を使用します。
```bash
/gsd-quick "Fix the login button not responding on mobile Safari"
```
または `/gsd-verify-work N` を使って UAT を通じて体系的に問題を特定・修正します。
### コマンドが「Spawning…」でフリーズしているように見える場合
待ってください。GSD サブエージェントは別のコンテキストウィンドウで動作します。その作業は進行中の間、親セッションからは見えません。スポーン行の liveness ノートがこれが期待される動作であることを確認しています。リサーチと計画エージェントは通常 1〜5 分かかります。大きなフェーズでは検証エージェントがさらに時間がかかる場合があります。
セッションを中断しないでください。セッションを終了すると進行中のサブエージェント作業が破棄されます。
10 分以上経過した場合は、Claude Code のサイドバーでエージェントタスクがまだアクティブと表示されているか確認してください。
---
## ワークフロー状態の問題
### ワークフローが破損しているか、状態が一貫していない場合
```bash
/gsd-forensics
```
または説明を添えて：
```bash
/gsd-forensics "Phase 3 execution stalled after wave 1"
```
`/gsd-forensics` はポストモーテム調査を実行します：git 履歴の異常、成果物の整合性、STATE.md の一貫性、未コミットの作業、孤立したワークツリー。レポートを `.planning/forensics/` に書き込み、推奨される修復手順を提示します。読み取り専用であり、プロジェクトファイルを変更することはありません。
### フェーズまたはプランをロールバックする必要がある場合
```bash
/gsd-undo --phase 03 # フェーズ 3 のすべてのコミットをロールバックする
/gsd-undo --plan 03-02 # フェーズ 3 のプラン 02 のコミットをロールバックする
/gsd-undo --last 5 # 最近の 5 件の GSD コミットからインタラクティブに選ぶ
```
`/gsd-undo` はロールバック前に依存するフェーズを確認し、常に確認ゲートを表示します。
---
## インストールとアップデートの問題
### インストール後に GSD が認識されない場合
ランタイムを再起動してください。GSD はランタイムのコマンドディレクトリ（例：`~/.claude/commands/gsd/`）にスラッシュコマンドをインストールします。ほとんどのランタイムは起動時にのみ新しいコマンドを検出します。
問題が続く場合はインストールを確認します。
```bash
npx @opengsd/gsd-core@latest --claude --local
```
ランタイム固有のインストールパスとトラブルシューティングについては、[ランタイムへのインストール](install-on-your-runtime.md)を参照してください。
### アップデートがローカルの変更を上書きした場合
v1.17 以降、インストーラはローカルで変更されたファイルを `gsd-local-patches/` にバックアップします。変更を再適用します。
```bash
/gsd-update --reapply
```
### npm 経由でアップデートできない場合
npm の障害やネットワーク制限のために `npx @opengsd/gsd-core` が失敗する場合は、`docs/manual-update.md` に npm アクセスなしで動作するステップバイステップの手動アップデート手順があります。
定期的なアップデートについては、[GSD のアップデート](update-gsd.md)を参照してください。
---
## コストの問題
### モデルのコストが高すぎる場合
バジェットプロファイルに切り替えます。
```bash
/gsd-config --profile budget
```
ドメインが慣れ親しんだものであれば、設定でリサーチとプランチェックのエージェントを無効にします。
```bash
/gsd-settings
```
また、有効になっている MCP サーバーを監査してください。有効な MCP サーバーはそれぞれのツールスキーマをすべてのターンに注入します。ブラウザとプラットフォーム固有のツールはそれぞれ 20,000 トークン以上かかる場合があります。現在のフェーズに不要なものは `.claude/settings.json` で無効にしてください。
```json
{
"disabledMcpjsonServers": ["playwright", "mac-tools"]
}
```
---
## 回復クイックリファレンス
| 問題 | 解決策 |
|---------|---------|
| コンテキストを失った、または新しいセッション | `/gsd-resume-work` または `/gsd-progress` |
| 次のステップがわからない | `/gsd-progress --next` |
| フェーズがうまくいかなかった | `/gsd-undo --phase NN`、その後再計画する |
| 何かが壊れた | `/gsd-debug "description"`（修正なしの分析は `--diagnose` を追加） |
| STATE.md が同期していない | `state validate` その後 `state sync` |
| `.planning/` の整合性が不確か | `/gsd-health`、その後 `/gsd-health --repair` |
| ワークフロー状態が破損しているように見える | `/gsd-forensics` |
| 対象を絞った素早い修正 | `/gsd-quick` |
| プランがビジョンと一致しない | `/gsd-discuss-phase N` その後再計画する |
| コストが高くなっている | `/gsd-config --profile budget` と `/gsd-settings` でエージェントをオフにする |
| アップデートがローカルの変更を壊した | `/gsd-update --reapply` |
| セッションのサマリーが必要 | `/gsd-pause-work --report` |
| 並行実行のビルドエラー | GSD をアップデートするか `parallelization.enabled: false` を設定する |
---
## Related
- [フェーズ実行の失敗をデバッグする](debug-a-failed-execution.md)
- [ランタイムへのインストール](install-on-your-runtime.md)
- [コマンドリファレンス](../COMMANDS.md)
- [ドキュメント一覧](../README.md)

124
docs/ja-JP/how-to/run-phases-autonomously.md Normal file
View File

@@ -0,0 +1,124 @@
# フェーズを自律的に実行する方法
残りのすべてのフェーズ、または限定した範囲のフェーズを無人で実行します。GSD がすべてのステップを自分でドライブすることなく、各フェーズの discuss → plan → execute を処理します。
自律実行中にフェーズループが何をしているかの背景については [フェーズループ](../explanation/the-phase-loop.md) を参照してください。
---
## 前提条件
- `.planning/ROADMAP.md` と `.planning/STATE.md` が存在するアクティブなプロジェクト
- 実行したいすべてのフェーズが自律モードで処理できる状態（pending または in-progress; 完了済みでない）
- 重要な設計上の決定事項は `PROJECT.md` に記載済みか、事前の `/gsd-discuss-phase` で記録済みであること。自律モードは `--interactive` を使用した場合のみグレーゾーンをインタラクティブに確認できます
---
## 残りのすべてのフェーズを実行する
```bash
/gsd-autonomous
```
GSD は `ROADMAP.md` を読み込み、数値順で未完了のすべてのフェーズを見つけ、それぞれについて discuss → plan → execute を実行します。すべてのフェーズが完了すると、マイルストーンライフサイクル（audit → complete → cleanup）を自動的に実行します。
---
## 特定の範囲のフェーズを実行する
`--from` と `--to` を使用して実行範囲を限定します。両フラグは小数のフェーズ番号（例: `3.1`）を受け入れます。
```bash
/gsd-autonomous --from 3 # フェーズ 3、4、5 …（完了済みのフェーズ 1、2 はスキップ）
/gsd-autonomous --to 5 # フェーズ 5 まで（5 を含む）
/gsd-autonomous --from 3 --to 5 # フェーズ 3、4、5 のみ
```
`--to` に達するとライフサイクルステップはスキップされます。マイルストーンのすべてのフェーズが完了していないためです。完了バナーに再開方法が表示されます:
```text
Resume with: /gsd-autonomous --from 6
```
---
## インタラクティブな検討を行いながら実行する
デフォルトでは、自律モードはスマート discuss（バッチテーブル提案）を使って検討の質問に自動的に回答します。プランと実行をメインコンテキスト外に保ちながら設計上の質問に自分で回答したい場合:
```bash
/gsd-autonomous --interactive
```
インタラクティブモードでは:
- `/gsd-discuss-phase` はインラインで実行され、あなたの回答を待機します
- プランニングと実行はバックグラウンドエージェントとしてディスパッチされるため、現在のフェーズがビルドされている間に次のフェーズについて検討できます
- メインコンテキストはリーンに保たれ — 検討の会話のみが蓄積されます
---
## 適用されるセーフティゲート
自律モードは GSD の品質パイプラインをバイパスしません。各フェーズは引き続き:
- 実行前にプランチェッカーを実行します
- 実行後に `VERIFICATION.md` を読み込み、結果に応じてルーティングします
- 検証状態が `human_needed` または `gaps_found` の場合、一時停止して対応を求めます
- いずれかのステップが失敗した場合、停止してオプション（修正して再試行、フェーズのスキップ、または停止）を提示します
手動実行との唯一の違いは、`passed` の検証が自動的に次へ進む点です — 決定が必要な場合を除き、フェーズ間でプロンプトが表示されません。
パッケージ正当性ゲートも有効です。プランに不審なパッケージの `checkpoint:human-verify` タスクが含まれている場合、エグゼキュータは停止してチェックポイントを表示します。自律モードはフラグが立ったパッケージを無言でインストールしません。
---
## 自律モードを使用しない場合
`/gsd-autonomous` を使用しないケース:
- **フェーズに未解決の設計上の決定事項がある場合。** `/gsd-discuss-phase` を実行しておらず、`PROJECT.md` にあなたの方針が記載されていない場合、スマート discuss はあなたが同意しない自律的な選択をする可能性があります。先にインタラクティブで discuss を実行するか、`--interactive` を使用してください。
- **単一フェーズを細かく制御する必要がある場合。** 1 つのフェーズであれば、`/gsd-execute-phase N` で段階的な出力を確認しながら続行前に対応できます。自律モードは大規模な無人実行向けに設計されています。
- **フェーズに新規性の高い、またはリスクの高い作業が含まれる場合。** 自律モードはブロッカーに当たらない限り一時停止をスキップします。予期しない事態が想定されるフェーズでは、手動実行でループに留まってください。
- **部分的な実行が済んでいる途中フェーズの場合。** 自律モードは未完了フェーズを引き継ぎますが、部分的に実行されたウェーブは再開しません。すでに進行中のフェーズを完了させるには `/gsd-execute-phase N` を使用してください。
実行が途中で停止した場合、何が問題だったかの診断方法については [実行失敗のデバッグ](debug-a-failed-execution.md) を参照してください。
---
## 実行中の進捗確認
自律モードは各フェーズの前に進捗バナーを表示します:
```text
GSD ► AUTONOMOUS ▸ Phase 3/7: Auth Middleware [████░░░░] 28%
```
セッション途中で実行状況を確認する必要がある場合は、別のターミナルを開いて次を実行します:
```bash
/gsd-progress
```
---
## 停止後の再開
ブロッカープロンプトで「Stop autonomous mode」を選択した場合、またはセッションが中断された場合は、停止した場所から再開します:
```bash
/gsd-autonomous --from 4 # 4 を最初の未完了フェーズ番号に置き換える
```
GSD は完了済みのフェーズを自動的にスキップするため、停止した場所が不明な場合は早めのフェーズ番号から安全に再実行できます。
---
## Related
- [フェーズの実行](execute-a-phase.md)
- [実行失敗のデバッグ](debug-a-failed-execution.md)
- [コマンド](../COMMANDS.md)
- [ドキュメント索引](../README.md)

159
docs/ja-JP/how-to/set-up-cross-ai-review.md Normal file
View File

@@ -0,0 +1,159 @@
# クロス AI レビューの設定方法
**目的:** プランレビューに参加する AI レビュアーを設定し、プランニング済みフェーズのレビューを実行し、HIGH 重大度の懸念がなくなるまでフィードバックを反映してプランを収束させます。
**前提条件:** フェーズがプランニング済みであること（`.planning/phases/` に `{phase}-PLAN.md` ファイルが存在する）。少なくとも 1 つの外部 AI CLI がインストールされ認証済みであること。
---
## 使用するレビュアーを決める
GSD Core は Gemini CLI、Claude（別セッション）、Codex CLI、CodeRabbit、OpenCode、Qwen Code、Cursor、Antigravity CLI、Ollama、LM Studio、llama.cpp の任意の組み合わせにレビューリクエストをルーティングできます。
各レビュアーは `PLAN.md` ファイルに対して同じ構造化プロンプトを独立して実行します。モデルによって盲点が異なるため、複数レビュアーのコンセンサスは単一レビュアーよりも多くの問題を検出できます。
**外部 CLI がまだインストールされていない場合**は、少なくとも 1 つをインストールしてください:
```bash
# Gemini CLI（Google 認証情報で無料）
npm install -g @google/gemini-cli
# Antigravity CLI（Google 認証情報で無料）
curl -fsSL https://antigravity.google/cli/install.sh | bash
# Codex CLI
npm install -g @openai/codex
```
---
## デフォルトレビュアーを設定する（オプション）
デフォルトでは `/gsd-review` は検出されたすべての CLI を実行します。プロジェクトのデフォルトとして特定のサブセットを固定するには:
```bash
/gsd-config --integrations
```
インテグレーションウィザードは API キー、コードレビュー CLI のルーティング、`review.default_reviewers` リストをカバーします。フラグなしのデフォルトとして使用したいレビュアーのリストを設定します。例: `["gemini","codex"]`。
または `gsd-tools` で直接設定することもできます:
```bash
gsd config-set review.default_reviewers '["gemini","codex"]'
```
インテグレーション設定スキーマの全体（API キー、レビュアーごとのモデルオーバーライド、ローカルサーバーのホストアドレス）については [設定](../CONFIGURATION.md) を参照してください。
---
## レビューを実行する
### 標準レビュー（設定済みのデフォルトまたは検出されたすべての CLI を使用）
```bash
/gsd-review --phase 3
```
GSD は各レビュアーを順番に呼び出し、構造化されたフィードバック（サマリー、強み、HIGH/MEDIUM/LOW の懸念事項、提案、リスク評価）を収集し、結合された出力を `.planning/phases/03-.../03-REVIEWS.md` に書き込みます。
### 1 回限りの実行で特定のレビュアーを選ぶ
```bash
/gsd-review --phase 3 --gemini
/gsd-review --phase 3 --codex
/gsd-review --phase 3 --cursor
```
明示的なフラグはその実行に限り `--all` のデフォルトと `review.default_reviewers` の両方を上書きします。
### 利用可能なすべてのレビュアーを並列実行する
```bash
/gsd-review --phase 3 --all
```
`--all` は設定を常に上書きし、設定済みのローカルモデルサーバー（Ollama、LM Studio、llama.cpp）を含む、検出されたすべてのセットを実行します。
### ローカルモデルサーバーのレビュアー
Ollama または LM Studio をローカルで実行している場合、サーバーに到達可能であれば `--all` で自動的に含まれます。明示的に指定することもできます:
```bash
/gsd-review --phase 3 --ollama
/gsd-review --phase 3 --lm-studio
```
デフォルト（`localhost:11434` / `localhost:1234`）が合わない場合は、`/gsd-config --integrations` で `review.*` キーの下にホストアドレスとモデル選択を設定してください。
---
## レビュー出力を読む
`{padded_phase}-REVIEWS.md` ファイルには以下が含まれます:
- 重要度別に分類された懸念事項を含む各レビュアーの個別レビュー
- 2 人以上のレビュアーが提起した懸念事項を統合した**コンセンサスサマリー**セクション — 最優先シグナルのためにここから読み始めてください
- レビュアー間で意見が分かれた箇所の**相違する見解**セクション
---
## フィードバックをプランに取り込む
出力を確認したら、フィードバックを取り込んでリプランします:
```bash
/gsd-plan-phase 3 --reviews
```
プランナーは `REVIEWS.md` を読み込み、懸念事項に対応するようプランを調整してから保存します。
---
## plan–review–replan ループを自動化する
HIGH 重大度の懸念事項がすべて解決されるまで反復したい場合はコンバージェンスループを使用します:
```bash
/gsd-plan-review-convergence 3
```
これは `plan-phase → review → replan → re-review` を最大 3 サイクル（デフォルト）実行します。HIGH 懸念事項のカウントがゼロになるとループが終了します。
### 特定のレビュアーとのコンバージェンス
```bash
/gsd-plan-review-convergence 3 --codex
/gsd-plan-review-convergence 3 --gemini
```
### すべてのレビュアーと高いサイクル上限でのコンバージェンス
```bash
/gsd-plan-review-convergence 3 --all --max-cycles 5
```
**ストール検知:** サイクルをまたいで HIGH 懸念事項のカウントが減少していない場合、GSD は警告します。サイクル上限に達しても HIGH 懸念事項が残っている場合、エスカレーションゲートが表示され、続行するか手動でレビューするかを確認します。
---
## 条件: どのレビュアーを選ぶか
| 状況 | 推奨アプローチ |
|-----------|---------------------|
| Gemini CLI がすでにインストール済み | `--gemini` は常に良い出発点のレビュアー |
| 無料のマルチレビュアーカバレッジが欲しい | `--gemini` + `--agy`（両方とも Google 認証情報を使用） |
| プロジェクトが OpenAI 中心 | OpenAI モデルの観点のために `--codex` を追加 |
| GitHub Copilot のモデルが欲しい | `--opencode` を追加 |
| API コストを完全に避けたい | Ollama にローカルモデルを設定して `--ollama` を使用 |
| リリース前に最大限のカバレッジが必要 | `/gsd-plan-review-convergence N --all` |
| 素早く反復して高速なフィードバックが欲しい | 1 つの CLI を選ぶ: `/gsd-review --phase N --gemini` |
---
## Related
- [検証とシッピング](verify-and-ship.md)
- [設定](../CONFIGURATION.md)
- [コマンド](../COMMANDS.md)
- [ドキュメント索引](../README.md)

160
docs/ja-JP/how-to/spike-and-sketch.md Normal file
View File

@@ -0,0 +1,160 @@
# コミットする前にスパイクとスケッチを行う方法
**目標:** フェーズを特定のアプローチに確定する前に、集中的な実現可能性実験（スパイク）と使い捨ての HTML モックアップによるビジュアル方向探索（スケッチ）を通じて、実装のリスクを軽減する。
**前提条件:** なし。`/gsd-spike` と `/gsd-sketch` は独自のストレージディレクトリを作成し、初期化済みの GSD プロジェクトは必要ありません。
---
## スパイク、スケッチ、またはその両方を選ぶ
| 答えたい問い | 使用するもの |
|---|---|
| 「この技術的アプローチは実際に機能するか？」 | `/gsd-spike` |
| 「このレイアウト / インタラクション / ビジュアル処理は適切か？」 | `/gsd-sketch` |
| 「適切な技術的アプローチは何で、どのように見えるべきか？」 | 両方、順番に：スパイク先行、次にスケッチ |
スパイクは実行可能なコードと VALIDATED / INVALIDATED / PARTIAL の判定で、二項対立の実現可能性問題に答えます。スケッチはブラウザで比較可能な 2〜3 種類の HTML バリアントで、ビジュアルの問いに答えます。両者は補完的です。スパイクはアプローチの構築可能性を証明し、スケッチはデザインの構築する価値を証明します。
---
## スパイクを実行する
### インタラクティブな受付（デフォルト）
```bash
/gsd-spike
```
GSD は技術的な問いについて質問し、それを **Given / When / Then** 形式の仮説として 2〜5 個の独立した実験に分解し、構築前に確認を求めます。
### アイデアを直接指定する
```bash
/gsd-spike "can we stream LLM tokens through SSE"
```
### 受付をスキップしてすぐに実行する
```bash
/gsd-spike --quick "websocket vs SSE latency"
```
`--quick` は分解の会話をスキップし、引数を単一のスパイク質問として扱います。問いがすでに精度が高く、絞り込みなしに実行できる場合に使用してください。
### 各実験が生成するもの
`.planning/spikes/NNN-descriptive-name/` 内の各スパイクには以下が含まれます。
- 動作するコード（擬似コードではない）
- コードの前に書かれた **Given / When / Then** 仮説
- エッジケース、方向転換、驚きを記録した調査トレイル
- 証拠付きの **VALIDATED**、**INVALIDATED**、または **PARTIAL** 判定
- フロントマター、実行方法の説明、結果を含む `README.md`
すべてのスパイクは `.planning/spikes/MANIFEST.md` にインデックスされます。
### 知見をパッケージ化する
シグナルが得られたら、今後のセッションで自動的に読み込まれるプロジェクトローカルスキルとして知見をまとめます。
```bash
/gsd-spike --wrap-up
```
これにより `.claude/skills/spike-findings-[project]/` が書き込まれます。このスキルは自動的に検出され、後続の `/gsd-sketch`、`/gsd-ui-phase`、`/gsd-plan-phase` の実行時に読み込まれます。明示的に参照する必要はありません。
---
## スケッチを実行する
### ムードの受付（デフォルト）
```bash
/gsd-sketch
```
GSD は、コードを書く前に、雰囲気、ビジュアルリファレンス、コアユーザーアクションを探る短い会話を開きます。一度に 1 つの質問をして、「実行してください」と言った時点でのみ構築を開始します。
### デザイン方向を直接指定する
```bash
/gsd-sketch "dashboard layout"
```
### ムードの受付をスキップしてすぐに実行する
```bash
/gsd-sketch --quick "sidebar navigation"
```
`--quick` は受付の会話を完全にスキップし、引数をデザイン方向として使用します。
### Claude 以外のランタイム（Codex、Gemini CLI など）
```bash
/gsd-sketch --text "onboarding flow"
```
`--text` はインタラクティブなプロンプトをプレーンテキストの番号付きリストに置き換えます。ランタイムが `AskUserQuestion` をサポートしていない場合に使用してください。
### 各スケッチが生成するもの
`.planning/sketches/NNN-descriptive-name/` 内の各スケッチには以下が含まれます。
- タブナビゲーションで 2〜3 種類のバリアントにアクセスできる `index.html`（ビルドステップなし、直接ブラウザで開ける）
- 機能的なインタラクティブ要素（ホバー、クリック、トランジション）
- 事前のスパイク知見からのフィールド名とデータ形状を使ったリアルなコンテンツ
- `.planning/sketches/themes/default.css` からの共有 CSS 変数
- デザインの問い、バリアント、注目ポイントを含む `README.md`
すべてのスケッチは `.planning/sketches/MANIFEST.md` にインデックスされます。
### 採用したデザイン決定をパッケージ化する
バリアントを選択したら、ビジュアル決定をプロジェクトローカルスキルとして記録します。
```bash
/gsd-sketch --wrap-up
```
これにより `.claude/skills/sketch-findings-[project]/` が書き込まれます。このスキルは `/gsd-ui-phase` によって自動的に読み込まれ、事前に検証された決定（レイアウト、カラーパレット、タイポグラフィ、スペーシング）はロック済みとして扱われ、再確認されません。
---
## 統合フロー：スパイク → スケッチ → フェーズ
技術的な実現可能性とビジュアル方向の両方が不確かな場合、以下の順序が推奨されます。
```bash
/gsd-spike "SSE vs WebSocket for real-time feed"
/gsd-spike --wrap-up
/gsd-sketch "real-time feed UI"
/gsd-sketch --wrap-up
/gsd-discuss-phase N
/gsd-plan-phase N
```
スパイク知見はスケッチに反映されます（実際のデータ形状、実際のインタラクション状態、現実的な制約）。両方の wrap-up は決定を永続化し、プランナーと UI リサーチャーが自動的に読み込みます。そのため、`/gsd-discuss-phase` や `/gsd-ui-phase` 中に選択内容を再説明する必要はありません。
---
## スパイクまたはスケッチがフェーズにどう組み込まれるか
スパイクとスケッチの成果物は手動で参照する必要はありません。GSD は 2 つのタイミングで自動的に読み込みます。
1. **`/gsd-sketch`** — モックアップ構築前に `.claude/skills/spike-findings-*/` を読み込み、バリアントが証明済みの制約（ストリーミング状態、実際のフィールド名など）を反映するようにする
2. **`/gsd-ui-phase N`** — UI デザインコントラクト生成前に `.claude/skills/sketch-findings-*/` を読み込み、事前検証済みのデザイン決定をロック済みとして扱う
プランナーも `spike-findings-*` スキルが存在する場合はスパイク知見を読み込むため、検証済みの技術的選択（ライブラリ、プロトコル、データ形式）が繰り返しの説明なしに直接タスクプランに反映されます。
---
## Related
- [UI フェーズをデザインする](design-a-ui-phase.md)
- [フェーズを計画する](plan-a-phase.md)
- [コマンドリファレンス](../COMMANDS.md)
- [ドキュメント一覧](../README.md)

120
docs/ja-JP/how-to/update-gsd.md Normal file
View File

@@ -0,0 +1,120 @@
# GSD Core をアップデートする方法
既存の GSD Core インストールを最新リリースに更新し、コミット前に変更履歴をプレビューし、アップデートによって上書きされるローカルカスタマイズを回復します。
**必要なもの:** GSD がインストールされているのと同じランタイム。アップデートコマンドは内部でインストーラを再実行するため、Node.js と npx が利用可能である必要があります（元のインストールと同じ要件）。
---
## 標準的なアップデート手順
AI ランタイム内から以下を実行します。
```bash
/gsd-update
```
GSD は以下を実行します。
1. インストール済みバージョンとインストールスコープ（グローバルまたはローカル）を検出する。
2. `@opengsd/gsd-core` の最新リリースを npm で確認する。
3. 変更履歴を取得し、インストール済みバージョンと最新バージョンの差分を表示する。
4. 何も触れる前に確認を求める。
5. GSD 管理ディレクトリ内に見つかったユーザーが追加したファイルを `gsd-user-files-backup/` にバックアップする。
6. インストーラを実行する（`npx @opengsd/gsd-core@latest --<runtime> --<scope>`）。
7. アップデートチェックキャッシュをクリアしてステータスラインのインジケーターをリセットする。
8. ローカルで変更された GSD ファイルが `gsd-local-patches/` にバックアップされたかどうかを報告する。
アップデート後にランタイムを再起動して、新しいコマンドとエージェントを読み込んでください。
---
## フラグ
| フラグ | 動作 |
|------|--------------|
| `--sync` | アップデート後に GSD レジストリからスキルを同期する |
| `--reapply` | アップデート後に `gsd-local-patches/` からローカルで変更された GSD ファイルをマージして戻す |
```bash
/gsd-update --sync # アップデートしてスキルを同期する
/gsd-update --reapply # アップデートしてローカルパッチを再適用する
```
---
## アップデート前に変更履歴を確認する
`/gsd-update` は確認を求める前に、インストール済みバージョンと最新バージョン間の変更履歴差分を常に表示します。GitHub を別途確認する必要はありません。出力は以下のようになります。
```text
## GSD Update Available
Installed: 1.39.0
Latest: 1.41.0
### What's New
────────────────────────────────────────────────────────────
[changelog entries for 1.40.0 and 1.41.0]
────────────────────────────────────────────────────────────
Proceed with update? [Yes, update now / No, cancel]
```
変更履歴を取得できない場合（ネットワークアクセスなし、npm の障害）、アップデートは確認後も続行されます。変更履歴の利用可能性でブロックされることはありません。
---
## ローカルカスタマイズの回復
### GSD 管理ディレクトリ内に追加したファイル
GSD が所有するディレクトリ内にカスタムファイルを配置した場合（例：`gsd-` プレフィックスのカスタムエージェント、`commands/gsd/` への追加ファイル）、インストーラはそれらを検出し、ディレクトリを削除する前に `gsd-user-files-backup/` にコピーします。アップデート後、そのバックアップ場所から手動で復元してください。
GSD 管理ディレクトリの外に配置したファイル（`gsd-` プレフィックスのないカスタムエージェント、`commands/gsd/` 外のカスタムコマンド、`CLAUDE.md` ファイル、カスタムフック）はインストーラによって一切変更されません。
### GSD がインストールしたファイルへの直接変更
GSD がインストールしたファイルを編集した場合（例：エージェントのシステムプロンプトの調整）、インストーラはマニフェストのハッシュ比較で変更を検出し、ファイルを `gsd-local-patches/` にバックアップしてから新しいバージョンで置き換えます。アップデート後：
```bash
/gsd-update --reapply
```
これにより、新しくインストールされたファイルに `gsd-local-patches/` からの変更がマージして戻されます。
以前のアップデート後に `--reapply` をスキップしてパッチを今すぐ適用したい場合：
```bash
/gsd-update --reapply
```
`--reapply` は新しいダウンロードをトリガーせずに単独で実行しても安全です。すでに最新バージョンであれば、GSD はインストールステップをスキップして直接パッチの再適用に進みます。
---
## npm が利用できない場合
ネットワーク制限、npm の障害、またはソースリポジトリから作業しているため `npx @opengsd/gsd-core@latest` が失敗する場合は、[docs/manual-update.md](../../manual-update.md) の手動アップデート手順を使用してください。そのドキュメントには、最新コミットの取得、フックの dist のビルド、`node bin/install.js` の直接実行が記載されています。
---
## すでに最新バージョンの場合
`/gsd-update` は確認メッセージとともに早期終了します。ダウンロード、インストール、再起動は不要です。
---
## インストーラの移行
各 GSD リリースには、管理ファイルの名前変更、移動、廃止を行うインストーラ移行が含まれる場合があります。移行レイヤーは新しいパッケージペイロードが書き込まれる前に自動的に実行されます。変更したファイルに影響する移行はサイレントに実行されず、確認が求められます。設計の詳細とランタイム設定コントラクトレジストリについては、[docs/installer-migrations.md](../../installer-migrations.md) を参照してください。
---
## Related
- [ランタイムにインストールする](install-on-your-runtime.md)
- [コマンドリファレンス](../COMMANDS.md)
- [手動アップデート](../../manual-update.md)
- [インストーラ移行](../../installer-migrations.md)
- [ドキュメント一覧](../README.md)

124
docs/ja-JP/how-to/verify-and-ship.md Normal file
View File

@@ -0,0 +1,124 @@
# フェーズの検証とシッピング方法
**目的:** 実行済みの成果物をユーザー受け入れテストに通し、失敗を診断・修正してから、自動生成された本文でプルリクエストを作成します。
**前提条件:** フェーズが実行済みで `SUMMARY.md` ファイルが存在すること。実行がまだ完了していない場合は [フェーズの実行](execute-a-phase.md) を参照してください。
---
## ユーザー受け入れテストを実行する
```bash
/gsd-verify-work 1
```
GSD はフェーズの `SUMMARY.md` ファイルを読み込み、ユーザーが観察できる成果物を抽出して、それらを一つずつ確認します。各チェックポイントで、*起こるべきこと*を提示し、実際にそうなっているかを尋ねます。
- `yes` / `y` / 空白 → 合格、次のテストへ
- それ以外 → 問題として記録され、あなたの説明から重要度が推定されます
重要度を分類する必要はありません — GSD があなたの言葉から推定します（「クラッシュする」→ ブロッカー、「動かない」→ メジャー、「見た目がおかしい」→ コスメティック）。
進捗は `.planning/phases/01-<name>/01-UAT.md` に書き込まれ、`/clear` 後も保持されます。セッションが中断された場合は `/gsd-verify-work 1` を再実行すると、最後のチェックポイントから再開するかどうか確認されます。
---
## 失敗が見つかった場合: 自動診断と修正プランニング
テストで問題が報告された場合、GSD は自動的に次を実行します:
1. **根本原因を診断** — 問題ごとに並列デバッグエージェントを起動し、`UAT.md` に根本原因を追記します。
2. **ギャップ修正をプランニング** — `gsd-planner` をギャップ修正モードで起動し、（診断を含む）`UAT.md` を読み込んで新しい `PLAN.md` ファイルを書き込みます。
3. **修正プランを検証** — `gsd-plan-checker` を起動してプランが実行可能かを確認します。問題があれば、プランナーとチェッカーが最大 3 回反復します。
4. **次のステップを提示** — プランがチェッカーを通過すると:
```
Plans verified and ready for execution.
`/clear` then `/gsd-execute-phase 1 --gaps-only`
```
提示されたコマンドを実行して修正を適用し、`/gsd-verify-work 1` を再実行してすべてが合格することを確認してください。
---
## すべてのテストが合格した場合: フェーズをシップする
すべての UAT テストが合格した場合（または最初の実行で問題が見つからなかった場合）、フェーズは `ROADMAP.md` と `STATE.md` で自動的に完了としてマークされます。
```bash
/gsd-ship 1
```
GSD はプリフライトチェック（検証状態、クリーンなワーキングツリー、ブランチ、リモート、`gh` CLI 認証）を実行し、ブランチをプッシュして PR を作成します:
```bash
/gsd-ship 1 # レビュー準備完了の PR
/gsd-ship 1 --draft # ドラフト PR — 後続フェーズが続く場合に便利
```
PR の本文はプランニング成果物から自動的に組み立てられます:
- `ROADMAP.md` からのフェーズ目標
- `SUMMARY.md` ファイルとその主要ファイルからのプランごとのサマリー
- 対応した要件（REQ-ID）
- `VERIFICATION.md` からの検証状態
- `STATE.md` からの主要な決定事項
本文を手動で書く必要はありません。
---
## オプション: シッピング前後のコードレビュー
`/gsd-ship` はコードレビューを自動的に実行しませんが、任意のタイミングで挿入できます:
**検証前**（UAT 前に問題を検出）:
```bash
/gsd-code-review 1 # 標準レビュー
/gsd-code-review 1 --fix # レビュー後に Critical + Warning の発見事項を自動修正
```
**PR オープン後**（マージ前に品質をゲート）:
```bash
/gsd-code-review 1 --depth=deep # インポートグラフを含むクロスファイル分析
```
サイクルの早い段階でのプランレビューに Gemini、Codex、その他のレビュアーを設定するには [クロス AI レビューの設定](set-up-cross-ai-review.md) を参照してください。
---
## オプション: クリーンな PR ブランチを作成する
ブランチにレビュアーに見せたくない `.planning/` のコミットが含まれている場合:
```bash
/gsd-pr-branch # main に対してフィルタリング
/gsd-pr-branch develop # develop に対してフィルタリング
```
`/gsd-pr-branch` はコードの変更のみを含む新しいブランチを作成します。プランニング成果物のコミットは除外されます。チームのレビューポリシーでプランニングのノイズを除外する場合は、`/gsd-ship` の前にこれを実行してください。
---
## マイルストーンのクローズ
これがマイルストーンの最後のフェーズだった場合は、マイルストーンの監査とアーカイブを実行します:
```bash
/gsd-audit-milestone # すべての要件がシップされたかを確認
/gsd-complete-milestone # アーカイブ、git タグの作成
```
`/gsd-complete-milestone` は PR マージ後の自然な次のステップです。検証とシッピングがプロジェクト全体のライフサイクルにどう組み込まれるかについては [フェーズループ](../explanation/the-phase-loop.md) を参照してください。
---
## Related
- [フェーズの実行](execute-a-phase.md)
- [クロス AI レビューの設定](set-up-cross-ai-review.md)
- [フェーズループ](../explanation/the-phase-loop.md)
- [コマンド](../COMMANDS.md)

157
docs/ja-JP/how-to/work-in-parallel-with-workstreams.md Normal file
View File

@@ -0,0 +1,157 @@
# ワークストリームを使って複数の領域を並行して進める方法
**目標:** バックエンド API、フロントエンドダッシュボード、インフラなど、異なるマイルストーン領域を並行して作業する際に、各領域の計画状態が互いに干渉しないようにする。
**前提条件:** GSD Core プロジェクトが有効な状態（`.planning/ROADMAP.md` が存在する）であること。存在しない場合は、まず `/gsd-new-project` を実行してください。
---
## ワークストリームとは
ワークストリームは、単一のコードベース内で独立した計画コンテキストを持つ仕組みです。各ワークストリームには専用の `.planning/workstreams/<name>/` サブツリーが作成され、独立した `STATE.md`、`ROADMAP.md`、`REQUIREMENTS.md`、`phases/` ディレクトリが含まれます。コードベース本体（ソースコード、git 履歴、ブランチ）はすべてのワークストリームで共有されます。
```
.planning/
├── PROJECT.md ← 共有
├── config.json ← 共有
├── codebase/ ← 共有
└── workstreams/
├── backend-api/
│ ├── STATE.md
│ ├── ROADMAP.md
│ ├── REQUIREMENTS.md
│ └── phases/
└── frontend-dash/
├── STATE.md
├── ROADMAP.md
├── REQUIREMENTS.md
└── phases/
```
ワークストリームがアクティブな間、すべての GSD コマンド（`/gsd-progress`、`/gsd-discuss-phase`、`/gsd-plan-phase`、`/gsd-execute-phase`）はそのワークストリームのディレクトリを読み書き対象とします。ワークストリームを切り替えると、ソースツリーに触れることなく、これらすべてのコマンドが別のサブツリーを対象とするようになります。
---
## ワークストリームを作成する
```bash
/gsd-workstreams create backend-api
```
GSD は `.planning/workstreams/backend-api/` 以下にワークストリームディレクトリを作成し、`STATE.md` と `ROADMAP.md` の雛形を生成します。ワークストリームは自動的にアクティブ化されません。明示的に切り替えを行う必要があります。
---
## ワークストリームを一覧表示する
```bash
/gsd-workstreams list
```
すべてのワークストリームと、現在のセッションでアクティブなワークストリームを表示します。
---
## ワークストリームに切り替える
```bash
/gsd-workstreams switch backend-api
```
これ以降、すべての GSD ワークフローコマンドは `backend-api` コンテキストで動作します。切り替えはセッションスコープで行われます。同じリポジトリで複数の Claude Code ターミナルが開いている場合、各セッションで異なるアクティブワークストリームを保持でき、互いに干渉しません。
切り替え後は、通常のフェーズワークフローを進めてください。
```bash
/gsd-discuss-phase 1
/gsd-plan-phase 1
/gsd-execute-phase 1
/gsd-verify-work 1
```
別の領域を作業する場合は、2 つ目のターミナルでワークストリームを切り替えます。
```bash
/gsd-workstreams switch frontend-dash
/gsd-discuss-phase 1
/gsd-plan-phase 1
```
---
## すべてのワークストリームの進捗を確認する
```bash
/gsd-workstreams progress
```
すべてのワークストリームのフェーズ状態、現在位置、残作業をクロスワークストリームでまとめて表示します。切り替えなしで確認できます。
特定のワークストリームの詳細なステータスを確認する場合は：
```bash
/gsd-workstreams status backend-api
```
---
## ワークストリームの作業を再開する
コンテキストリセットや新しいセッションの後に、作業位置を復元します。
```bash
/gsd-workstreams resume backend-api
```
このコマンドはワークストリームをアクティブ化し、最後の既知の位置を復元します。手動で切り替えてから `/gsd-resume-work` を実行するのと同等です。
---
## 完了したワークストリームをアーカイブする
ワークストリームのマイルストーン作業が完了したら：
```bash
/gsd-workstreams complete backend-api
```
GSD はワークストリームをアーカイブ済みとしてマークし、アクティブ一覧から除外します。計画成果物は監査目的のため `.planning/workstreams/backend-api/` 以下に保持されます。
---
## セッションのアクティブコンテキストを変更せずに特定のワークストリームにコマンドを実行する
セッションのアクティブコンテキストを変更せず、特定のワークストリームに対して 1 つのコマンドだけを実行したい場合は、`--ws` フラグを使用します。
```bash
/gsd-progress --ws frontend-dash
/gsd-plan-phase 2 --ws backend-api
```
`--ws` は解決順序で最高優先度を持ち、セッションスコープのポインタは変更しません。
---
## ワークスペースではなくワークストリームを選ぶ場面
ワークストリームを選ぶべき場合：
- すべての作業が**同一リポジトリ**内にあり、同じ git 履歴を共有している
- API、UI、インフラなど異なる関心領域を**並行して**計画・議論したいが、各ワークストリームの `STATE.md` が互いに上書きされないようにしたい
- 作成時にワークストリームごとの別ブランチが不要（各ワークストリームの実行中に通常どおりブランチを切ることは可能）
- 完全な git ワークツリーを作成するオーバーヘッドが、必要な分離に対して割に合わない
代わりに[ワークスペース](isolate-work-with-workspaces.md)を選ぶべき場合：
- **複数のリポジトリ**（例：`hr-ui` と `ZeymoAPI`）にまたがって作業している
- フィーチャーごとに**独立した git ワークツリー**やクローンが必要（独立したブランチ、ロックファイル、ビルド成果物）
- 各ワークスペースで `/gsd-new-project` を独立して実行し、メインリポジトリの `.planning/` のサブディレクトリではなく、完全に独立した `.planning/` ルートを持ちたい
---
## Related
- [ワークスペースで作業を分離する](isolate-work-with-workspaces.md)
- [フェーズループ](../explanation/the-phase-loop.md)
- [コマンドリファレンス](../COMMANDS.md)
- [ドキュメント一覧](../README.md)

92
docs/ja-JP/issue-driven-orchestration.md Normal file
View File

@@ -0,0 +1,92 @@
# GSD によるイシュー駆動オーケストレーション
**ステータス：** 安定したワークフローガイド
**対象：** GitHub Issues、Linear、Jira、または類似のイシュートラッカーで作業を追跡し、GSD の既存プリミティブを通じて AI 支援実装を推進したい開発者。
## このガイドについて
GSD がすでに提供するコマンドをイシュートラッカー → ワークスペース → 計画/実行 → 検証/レビュー → PR ループに組み合わせるためのレシピです。これはドキュメントのみです。新しいコマンドなし、デーモンなし、トラッカー統合なし——以下で参照するすべてのコマンドは今日の GSD に既に存在します。
この形は OpenAI のオープンソース [Symphony オーケストレーションリファレンス](https://openai.com/index/open-source-codex-orchestration-symphony/)（[リポジトリ](https://github.com/openai/symphony)）にインスパイアされています。GSD は Symphony をベンダリングまたはラッピングしません。オーケストレーションの *概念* は GSD がすでに公開しているプリミティブにきれいにマッピングされます；このガイドはグルーコードを書いたり GSD の安全ゲートを回避したりせずにパターンを採用できるようにマッピングを説明するだけです。
## なぜこれが存在するか
GSD にはイシュー駆動 AI 開発のビルディングブロックがあります——`/gsd-workspace --new`、`/gsd-manager`、`/gsd-autonomous`、`/gsd-verify-work`、`/gsd-review`、`/gsd-ship`、さらに `STATE.md` とフェーズアーティファクトスイート——しかし、カスタムオーケストレーションスクリプトを書かずに単一のトラッカーイシューから端から端まで動かす方法を説明するガイドがありませんでした。そのガイドなしでは失敗モードは：
- 過少使用：開発者が discuss/plan/execute を手動で実行し、作業パターンが合致しているときでも `/gsd-manager` や `/gsd-autonomous` に手を出さない。
- 回避策スクリプト：開発者がトラッカーと `claude` 呼び出しの間にアドホックなシェルループを配線し、`STATE.md`、フェーズマニフェスト、検証ゲートを迂回する。
このガイドは正規ループを発見しやすくします。
## 概念マッピング
各行は Symphony スタイルのオーケストレーション概念を、それをすでに提供する GSD プリミティブにマッピングします。Symphony のドキュメント、ブログ投稿、サードパーティのオーケストレーション記事を読む際の変換キーとしてこのテーブルを使ってください。
| Symphony の概念 | GSD プリミティブ |
|---|---|
| `WORKFLOW.md`（トップレベルの意図） | `ROADMAP.md`（プロジェクトの意図）、`STATE.md`（ライブステータス）、フェーズ `CONTEXT.md`（フェーズごとのスコープ）、フェーズ `PLAN.md`（実行可能なステップ） |
| タスクごとの分離されたエージェントワークスペース | `/gsd-workspace --new --strategy worktree` |
| エージェントのディスパッチと並列性 | `/gsd-manager`（インタラクティブダッシュボード）、`/gsd-autonomous`（非同期） |
| フェーズごとの計画と議論ステップ | `/gsd-discuss-phase` → `/gsd-plan-phase` → `/gsd-execute-phase` |
| 作業の証明 / テスト証拠 | `/gsd-verify-work`（`/clear` をまたいで永続する UAT.md） |
| 対立的レビュー | `/gsd-review`（計画のクロス AI ピアレビュー） |
| ヒューマンマージゲート | `/gsd-ship`（PR を作成し、オプションのコードレビュー、マージ準備） |
| フォローアップキャプチャ | `/gsd-capture`、`/gsd-capture --seed`、`/gsd-new-milestone`、または手動で開いたトラッカーイシュー |
| 並列性制御 | マネージャー / バックグラウンドエージェントのセマンティクス（常時オンのポーラーなし） |
このマッピングは一方向です：GSD が安全ゲート（検証、ヒューマンレビュー、フォローアップ作成の明示的確認）を所有します。Symphony の「継続的オーケストレーション」フレーミングは意図的に採用していません——[非目標](#non-goals) を参照してください。
## エンドツーエンドフロー
単一のトラッカーイシューから端から端まで実行できるように書かれた、正規のイシュー → PR ループ。実行前に括弧内のプレースホルダーを置き換えてください。
1. **トラッカーイシューを選ぶ。** トラッカー（GitHub、Linear など）から、自律的な実装に十分な範囲があるイシューを一つ選びます——境界が明確なスコープ、観察可能な受け入れ基準、実行をブロックする上流の依存関係なし。
2. **GSD フェーズにマッピングする。** イシューが `ROADMAP.md` の既存フェーズにマッピングされる場合はそれを選択します。そうでない場合は、関連イシューの新しいマイルストーンのために `/gsd-new-milestone` を実行するか、`/gsd-phase` / `/gsd-phase --insert` でフェーズを開きます。フェーズの `CONTEXT.md` にトラッカーイシューの URL を記録し、圧縮後もトレーサビリティが維持されるようにします。
3. **分離されたワークスペースを作成する。** `/gsd-workspace --new --strategy worktree <slug>` を実行して、独立した `.planning/` ディレクトリを持つ git ワークツリーを立ち上げます。ワークツリーは安全境界です：探索、部分的なコミット、中断された計画はすべて `main` の外に留まります。
4. **GSD を通じて discuss → plan → execute を実行する。** ワークスペース内から、`/gsd-discuss-phase` で曖昧さを明確にし、`/gsd-plan-phase` で `PLAN.md` を生成し、`/gsd-manager`（インタラクティブダッシュボード）または `/gsd-execute-phase` / `/gsd-autonomous`（非同期）で実装します。GSD の外から生の `claude` 呼び出しを直接動かすことは避けてください——それは `STATE.md` の更新とフェーズマニフェストを迂回します。
5. **作業の証明を要求する。** `/gsd-verify-work` を実行して、フェーズの受け入れ基準に対して UAT をユーザーに案内します。テスト、スクリーンショット、ログキャプチャ、設定差分はすべて `UAT.md` に記録され、`/clear` をまたいで永続し、検証でミスしたスコープが発見されたときに `/gsd-plan-phase --gaps` にフィードされます。
6. **レビューと出荷ゲートを通過する。** `/gsd-review` を実行して独立した AI CLI からの対立的ピアレビューを受け（モデルごとのブラインドスポットをキャッチ）、次に `/gsd-ship` で計画アーティファクトから組み立てたリッチなボディ付きで PR を開きます。どちらのゲートもリモートに何かが届く前に人間の決定を必要とします。
7. **フォローアップ作業を明示的にキャプチャする。** インラインメモには `/gsd-capture` を、将来のフェーズの価値があるアイデアには `/gsd-capture --seed` を、一貫したフォローアップグループには `/gsd-new-milestone` を使います。発見されたフォローアップからトラッカーイシューを作成するには、明示的なユーザー確認が必要です——GSD はリモートトラッカーに自動投稿しません。
PR がマージされると、ループが閉じます。PR ボディのオートクローズキーワード（`Closes #NNN` / `Fixes #NNN`）がマージ時にトラッカーイシューを閉じます。
## 安全境界
このループが安全なのは、4 つの不変条件が設計上成立するからです：
- **分離されたワークツリー。** すべてのイシューが `/gsd-workspace --new` ワークツリーで実行されるため、部分的な作業、中断された計画、探索的なコミットは `main` に触れません。`gsd-local-patches/` は、ワークツリーの手動編集をアップデートをまたいで持ち戻す必要がある場合の回復面です。
- **明示的な人間によるレビュー。** `/gsd-review` と `/gsd-ship` はどちらも人間の承認で停止します。オートマージはなく、実行からの自動 PR パスもありません。特定のリポジトリで人間ゲートを削除したい場合は、それはブランチ保護 / マージキューポリシーの決定であり、GSD があなたに代わってオプトインするものではありません。
- **自動公開投稿なし。** GSD は明示的なユーザー起動コマンドなしにトラッカーイシューを開いたり、コメントしたり、閉じたりしません。フォローアップキャプチャはデフォルトでローカルアーティファクト（メモ、シード、マイルストーン）になります；トラッカーに押し戻すことは別の手動ステップです。
- **出荷前の検証。** `/gsd-verify-work` の UAT.md は `/gsd-ship` が実行される前に証拠を記録しなければなりません。推奨される規律は、実装が正しく見えるときでも `verification_failed` をブロッカーとして扱うことです——失敗は通常フラキーなテストではなく、ミスした受け入れ基準を表面化します。
これらの不変条件のいずれかが迂回された場合（例：ワークツリーに直接 `claude` を実行する、`/gsd-verify-work` をスキップする、またはユーザー確認なしにトラッカー API を通じてイシュー作成をスクリプト化する）、このガイドの保証は適用されません。
## 非目標 {#non-goals}
このガイドは意図的に以下のいずれも提案しません。将来のコントリビューターがコードレビューで再論争しないように、ここにリストされています：
- **Symphony コードのベンダリングまたはコピーなし。** GSD は独自のプリミティブを再利用します。上記のマッピングは概念的です；Symphony 由来のソースはこのリポジトリに同梱されません。
- **常時実行デーモンなし。** GSD は GitHub や Linear をポーリングしません。マネージャーと自律ワークフローは、デーモンではなくバックグラウンドエージェントのセマンティクスを通じて並列性を処理します。
- **必須のトラッカー依存関係なし。** このループはトラッカー統合なしで機能します。「トラッカーイシュー」ステップは *人間の入力* です——URL は `CONTEXT.md` に入ります。GSD はあなたが使用するトラッカーについても、トラッカーを使用するかどうかについても意見を持ちません。
- **検証、レビュー、または人間の決定ゲートの迂回なし。** `/gsd-autonomous` を実行する場合でも、検証とレビューゲートは依然として発火します。「自律的」ラベルはフェーズからフェーズへの進行を指し、人間の承認をスキップすることではありません。
- **デフォルトのスキル / コマンド面の拡張なし。** このガイドで参照するすべてのコマンドはすでに存在します。このガイドはドキュメント面であり、機能面ではありません。
## 将来のフォローアップの可能性
このループでのメンテナーの経験がそれを正当化するなら、別の承認済み拡張として後で *最小限の* トラッカーブリッジを追加できます：
- 一つの GitHub または Linear イシューを GSD ワークスペース / フェーズにインポートする。
- `UAT.md` 証拠をソースイシューのコメントとしてエクスポートする。
- `/gsd-capture --seed` の出力からフォローアップトラッカーイシューを生成する。
これらはそれぞれ統合面と継続的なメンテナンス負担を追加するため、それぞれ独自の拡張提案になります。このガイドのスコープ外です。
## Related
- [フェーズループ](explanation/the-phase-loop.md) — discuss → plan → execute → verify → ship が繰り返すサイクルとしてどう組み合わさるか。
- [ワークスペース how-to](how-to/work-in-parallel-with-workstreams.md) — 並列ワークツリーの作成と管理のステップバイステップガイド。
- [ドキュメント索引](README.md) — GSD Core ドキュメントの完全な目次。
- [docs/USER-GUIDE.md](./USER-GUIDE.md) — 上で参照した個々のコマンドのタスク指向のウォークスルー。
- [docs/COMMANDS.md](COMMANDS.md) — `/gsd-*` コマンドの完全なリファレンス。
- [docs/FEATURES.md](FEATURES.md) — 機能レベルの能力マトリクス（ワークスペース、マネージャー、自律、検証、レビュー、出荷）。
- [docs/ARCHITECTURE.md](ARCHITECTURE.md) — フェーズアーティファクトのライフサイクルと `STATE.md` の仕組み。

148
docs/ja-JP/reference/context-md.md Normal file
View File

@@ -0,0 +1,148 @@
# CONTEXT.md スキーマリファレンス
フェーズごとの `CONTEXT.md` は、`/gsd:discuss-phase` 中に収集された実装上の意思決定を格納する GSD Core のキャリアファイルです。リサーチエージェントとプランニングエージェントの両方にとって主要な上流インプットです。このページではそのスキーマを説明します。[ドキュメントインデックス](../../README.md) も参照してください。
---
## 概要
ディスカッションワークフローを経たすべてのフェーズは、以下のパスに `CONTEXT.md` を1つ生成します：
```
.planning/phases/<NN>-<slug>/<NN>-CONTEXT.md
```
例: `.planning/phases/03-post-feed/03-CONTEXT.md`
このファイルは `get-shit-done/workflows/discuss-phase.md` の `write_context`（または PRD / ADR インジェストのエクスプレスパス）によって生成されます。通常の運用中は手動で編集されません — discuss-phase ワークフローが書き込み、下流エージェントが封印された信頼できる情報源として読み取ります。
---
## フロントマター
`CONTEXT.md` は YAML フロントマターを持ちません。メタデータは本文の先頭にインラインで記述されます：
```markdown
# Phase [X]: [Name] - Context
**Gathered:** [ISO date]
**Status:** Ready for planning
```
`Status` フィールドはファイル初回書き込み時に常に `Ready for planning` です。作成後は更新されません。
---
## ブロック構造
本文は名前付きの XML スタイルブロックに分割されています。ブロックは固定の順序で登場し、下流エージェントは行番号ではなくブロック名で読み取ります。
| ブロック | 用途 | 設定元 | 参照先 |
|---|---|---|---|
| `<domain>` | フェーズの境界を示します — このフェーズが何を提供し、何が明示的にスコープ外かを述べます。プランニングと実行を通じてスコープガードレールを固定します。 | `discuss-phase`（ROADMAP.md のフェーズゴールから） | `gsd-planner`、`gsd-plan-checker`（スコープ準拠） |
| `<spec_lock>` | `check_spec` ステップが `*-SPEC.md` を発見した場合のみ存在します。ロックされた要件数とスコープ境界をリストします。エージェントは完全な要件を得るために直接 `SPEC.md` を読むよう指示されます。 | `discuss-phase`（条件付き） | `gsd-planner`（要件をここで再読みせず SPEC.md を読む） |
| `<decisions>` | ディスカッションから収集された実装上の意思決定。`D-NN` 識別子でキー付け。カテゴリは固定の分類ではなく実際に議論された内容から生まれます。ユーザーが委任した領域のための `Claude's Discretion` サブセクションを含みます。 | `discuss-phase`（インタラクティブなディスカッション） | `gsd-planner`（ロックされた決定は必ず実装する）、`gsd-plan-checker`（ディメンション7準拠） |
| `<canonical_refs>` | このフェーズに関連するすべての仕様、ADR、機能ドキュメント、設計ドキュメントへの完全な相対パス。必須 — すべての CONTEXT.md にこのセクションが必要です。エージェントはプランニングまたは実装の前にリストされたファイルを読む必要があります。 | `discuss-phase`（ROADMAP.md の参照 + ディスカッション中のユーザー参照 + コードベーススカウトから集積） | `gsd-phase-researcher`、`gsd-planner` |
| `<code_context>` | `scout_codebase` ステップで発見された再利用可能なアセット、確立されたパターン、統合ポイント。エージェントを再実装ではなく既存コードに向けるためのガイダンス。 | `discuss-phase`（コードベーススカウト） | `gsd-planner`、`gsd-phase-researcher` |
| `<specifics>` | ディスカッション中に verbatim で収集された「こんな感じにしたい」という具体的な参照、製品比較、特定の例。 | `discuss-phase`（自由形式のユーザー入力） | `gsd-planner` |
| `<deferred>` | ディスカッション中に浮上したが別のフェーズに属するアイデア。失われないよう保存されます。Todos がレビューされたがスコープに含まれなかった場合は `Reviewed Todos` サブセクションを含みます。 | `discuss-phase`（スコープクリープのリダイレクト） | 自動化されたエージェントには使用されない; 人間の参照のみ |
---
## 意思決定識別子フォーマット
`<decisions>` 内のすべての意思決定は連番の `D-NN` 識別子を持ちます：
```markdown
### Layout style
- **D-01:** Card-based layout, not timeline or list
- **D-02:** Each card shows: author avatar, name, timestamp, full post content, reaction counts
```
識別子はフェーズにスコープされます。フェーズ3の `D-01` はフェーズ7の `D-01` とは無関係です。プランチェッカー（ディメンション7）は、すべての `D-NN` が生成されたプランの少なくとも1つのタスクアクションによって対処されていることを検証します。
---
## Canonical references
`<canonical_refs>` ブロックは **必須** です。不在の場合、エージェントは CONTEXT.md が不完全であるとみなし警告を表示します。エントリはトピックごとにグループ化され、完全な相対パスとファイルが決定または定義する内容の簡単な説明を含みます：
```markdown
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Feed display
- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules
- `docs/decisions/adr-012-infinite-scroll.md` — Scroll strategy decision, virtualisation requirements
### Empty states
- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines
</canonical_refs>
```
プロジェクトに外部仕様がない場合は、このセクションでそれを明示します：
```
No external specs — requirements fully captured in decisions above
```
`<decisions>` 内に散在する「ADR-019 を参照」などのインラインメンションは不十分です。エージェントには専用セクションに完全なパスが必要です。
---
## Decision Coverage Gate との関係
プランチェッカーの **ディメンション7: Context Compliance** はプランニング後にカバレッジゲートを強制します：
1. `<decisions>` 内のすべての `D-NN` 識別子は、少なくとも1つのプランタスクの `<action>` または根拠に登場する必要があります。
2. `<deferred>` にリストされているものをタスクが実装してはなりません（スコープクリープ）。
3. `Claude's Discretion` 領域はこのチェックから免除されます — プランナーは自由に選択できます。
意思決定がプランに反映されている CONTEXT.md は準拠とみなされます。意思決定が暗黙的に削除されたり部分的にしか実現されていない CONTEXT.md は **ディメンション7b: Scope Reduction Detection** をトリガーし、常に BLOCKER となります。
---
## SPEC.md との統合
フェーズをディスカッションする前に `/gsd:spec-phase` が実行された場合、`check_spec` ステップが `*-SPEC.md` ファイルを見つけ `<spec_lock>` を有効にします：
```markdown
<spec_lock>
## Requirements (locked via SPEC.md)
**12 requirements are locked.** See `03-SPEC.md` for full requirements, boundaries, and acceptance criteria.
Downstream agents MUST read `03-SPEC.md` before planning or implementing. Requirements are not duplicated here.
**In scope (from SPEC.md):** [copied from SPEC.md Boundaries]
**Out of scope (from SPEC.md):** [copied from SPEC.md Boundaries]
</spec_lock>
```
`<spec_lock>` が存在する場合、`<decisions>` にはディスカッションからの実装上の意思決定のみが含まれます — 「何を作るか」ではなく「どのように作るか」です。要件は2つのファイル間で重複しません。
---
## フッター
すべての CONTEXT.md はアイデンティティフッターで終わります：
```markdown
---
*Phase: XX-name*
*Context gathered: [date]*
```
---
## Related
- [PLAN.md スキーマ](plan-md.md)
- [Planning artifacts](planning-artifacts.md)
- [Discuss modes](../../workflow-discuss-mode.md)
- [docs index](../../README.md)

249
docs/ja-JP/reference/plan-md.md Normal file
View File

@@ -0,0 +1,249 @@
# PLAN.md スキーマリファレンス
フェーズごとの `PLAN.md` は GSD Core の実行可能な作業単位です — エグゼキューターエージェントに何を構築し、正しく構築されたことをどのように検証するかを正確に伝える構造化ドキュメントです。このページではそのスキーマを説明します。[ドキュメントインデックス](../../README.md) も参照してください。
---
## 概要
プランはフェーズディレクトリ内の以下のパスに保存されます：
```
.planning/phases/<NN>-<slug>/<NN>-<PP>-PLAN.md
```
例: `.planning/phases/03-post-feed/03-02-PLAN.md`（フェーズ3、プラン2）。
プランは `gsd-planner` エージェント（`/gsd:plan-phase` によって起動）が生成し、`execute-phase` が使用します。通常、フェーズには1〜4つのプランが含まれます。フェーズ内のプランは実行ウェーブに割り当てられ、独立した作業が並行して実行されます。
---
## YAML フロントマター
すべての PLAN.md は `---` デリミタの間にある YAML フロントマターブロックで始まります。
### 注釈付きサンプル
```yaml
---
phase: 03-post-feed
plan: 02
type: execute
wave: 2
depends_on: ["03-01"]
files_modified:
- src/components/PostFeed.tsx
- src/components/PostCard.tsx
- src/app/feed/page.tsx
autonomous: true
requirements: ["FEED-01", "FEED-03"]
user_setup: []
must_haves:
truths:
- "User can scroll through posts from followed accounts"
- "Each post shows author avatar, name, timestamp, and content"
- "Empty state appears when no posts exist"
artifacts:
- path: "src/components/PostFeed.tsx"
provides: "Scrollable post list"
min_lines: 40
- path: "src/components/PostCard.tsx"
provides: "Individual post card"
exports: ["PostCard"]
key_links:
- from: "src/components/PostFeed.tsx"
to: "/api/feed"
via: "fetch in useEffect"
pattern: "fetch.*api/feed"
---
```
### フロントマターフィールドリファレンス
| フィールド | 必須 | 型 | 用途 |
|---|---|---|---|
| `phase` | はい | string | フェーズ識別子。例: `03-post-feed`。 |
| `plan` | はい | string | フェーズ内のプラン番号。例: `02`。 |
| `type` | はい | `execute` または `tdd` | 標準プランは `execute`; テスト駆動プラン（実装前にテストを書く）は `tdd`。 |
| `wave` | はい | integer | 実行ウェーブ。ウェーブ1のプランは並行実行されます（依存なし）。ウェーブ2以降のプランは前のウェーブのすべてのプランが完了するまで待機します。`gsd-planner` がプランニング時に事前計算します。 |
| `depends_on` | はい | プラン ID の配列 | このプランが待機する必要があるプランの一覧。空配列 = ウェーブ1。例: `["03-01"]` はこのプランがフェーズ3のプラン01の後に実行されることを意味します。 |
| `files_modified` | はい | パスの配列 | このプランが作成または変更するすべてのファイル。プランチェッカーが同一ウェーブのファイル競合を検出するため、および execute-phase がマージ追跡のために使用します。 |
| `autonomous` | はい | boolean | すべてのタスクが `auto` タイプの場合に `true`。プランに人間の操作が必要な `checkpoint:*` タスクが含まれる場合は `false`。 |
| `requirements` | はい | ID の配列 | このプランが対処する ROADMAP.md の要件 ID。すべてのフェーズ要件 ID は少なくとも1つのプランの `requirements` フィールドに登場する必要があります。空配列は BLOCKER です。 |
| `user_setup` | いいえ | オブジェクトの配列 | Claude が自動化できない外部サービスのセットアップ手順（アカウント作成、シークレット取得、ダッシュボード設定など）。存在する場合、execute-phase は開発者向けに `USER-SETUP.md` チェックリストを生成します。 |
| `must_haves` | はい | object | ゴール逆引き型の検証基準。以下を参照。 |
---
## `must_haves` フィールド
`must_haves` はフェーズゴールを達成するために観察可能に真でなければならないことを記録します。プランニング中に導出され、実行後に `gsd-verifier` エージェントによって検証されます。
### サブフィールド
| サブフィールド | 型 | 用途 |
|---|---|---|
| `truths` | 文字列の配列 | ユーザーの視点からの観察可能な動作。それぞれが検証可能でなければなりません。例: `"User can send a message"`（`"WebSocket library installed"` は不可）。 |
| `artifacts` | オブジェクトの配列 | 実質的な実装（スタブではなく）で存在しなければならないファイル。 |
| `artifacts[].path` | string | プロジェクトルートからの相対ファイルパス。 |
| `artifacts[].provides` | string | このファイルが提供する機能。 |
| `artifacts[].min_lines` | integer（オプション） | スタブではないとみなす最小行数。 |
| `artifacts[].exports` | 文字列の配列（オプション） | 検証すべき期待される名前付きエクスポート。 |
| `artifacts[].contains` | string（オプション） | ファイルに存在しなければならない正規表現またはリテラルパターン。 |
| `key_links` | オブジェクトの配列 | アーティファクト間の重要な接続 — システムをエンドツーエンドで機能させる配線。 |
| `key_links[].from` | string | ソースファイルまたはコンポーネント。 |
| `key_links[].to` | string | ターゲットファイル、エンドポイント、またはモジュール。 |
| `key_links[].via` | string | 接続方法の説明（例: `fetch in useEffect`、`Prisma query`、`import`）。 |
| `key_links[].pattern` | string（オプション） | ソース内に接続が存在することを検証する正規表現。 |
---
## 本文構造
フロントマターの後、プラン本文はエグゼキューターエージェントが読み取る名前付き XML スタイルブロックを使用します。
### `<objective>`
プランが提供するものとプロジェクトにとっての重要性を述べます：
```xml
<objective>
Implement the post feed as a scrollable card list.
Purpose: Core display feature for the social feed phase.
Output: PostFeed and PostCard components wired to /api/feed.
</objective>
```
### `<execution_context>`
エグゼキューターが開始前に読むワークフローファイルの一覧。常に execute-plan ワークフローを含み、プランにチェックポイントタスクがある場合はチェックポイントリファレンスを追加します：
```xml
<execution_context>
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>
```
### `<context>`
エグゼキューターが読む必要があるソースファイルの参照。プロジェクトレベルのプランニングドキュメントと、プランが複製しなければならないパターンや型を持つすべてのソースファイルを含みます。同じフェーズの以前のプランの `SUMMARY.md` は、型や共有された意思決定への真の依存がある場合のみ含めます — 反射的には含めません：
```xml
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@src/components/UserCard.tsx
</context>
```
### `<tasks>`
1つ以上の `<task>` 要素を含みます。`type="auto"` タスクのすべてのタスク要素には `<name>`、`<files>`、`<read_first>`、`<action>`、`<verify>`、`<acceptance_criteria>`、`<done>` が必要です。
---
## タスクタイプ
| タイプ | 用途 | 自律性 |
|---|---|---|
| `auto` | エグゼキューターが独立して実行できるすべて。 | 完全自律。 |
| `checkpoint:human-verify` | 人間が実行中の UI やサービスを確認する必要があるビジュアルまたは機能的な検証。 | 実行を一時停止して開発者に提示; 承認後に再開。 |
| `checkpoint:decision` | 実行中に浮上し開発者の入力が必要な実装上の選択。 | 実行を一時停止してオプションを提示; 選択後に再開。 |
| `checkpoint:human-action` | 真に避けられない手動ステップ（アカウント作成、ハードウェア操作）。控えめに使用。 | 実行を一時停止して確認後に再開。 |
チェックポイントタスクが含まれるプランはフロントマターに `autonomous: false` を設定する必要があります。
---
## `auto` タスク構造
```xml
<task type="auto">
<name>Task 1: Create PostCard component</name>
<files>src/components/PostCard.tsx</files>
<read_first>src/components/UserCard.tsx, src/types/post.ts</read_first>
<action>Create PostCard component accepting a Post prop (id, authorId, content, createdAt,
reactionCount). Render author avatar using UserAvatar from UserCard pattern. Show timestamp
using date-fns formatDistanceToNow. Export as named export PostCard.</action>
<verify>npx tsc --noEmit</verify>
<acceptance_criteria>
- src/components/PostCard.tsx exports named export PostCard
- PostCard.tsx contains "reactionCount" prop usage
- npx tsc --noEmit exits 0
</acceptance_criteria>
<done>PostCard renders post content with author and timestamp</done>
</task>
```
### `auto` タスクの必須フィールド
| フィールド | ルール |
|---|---|
| `<files>` | タスクが作成または変更するすべてのファイル。エグゼキューターはこれらのファイルのみを書き込みます。 |
| `<read_first>` | エグゼキューターが何かに触れる前に読まなければならないファイル — 変更するファイル、信頼できる参照パターンファイル、型や規則を複製しなければならないすべてのファイル。 |
| `<action>` | 正確な識別子、ファイルパス、関数シグネチャ、期待される値を含む具体的な指示。ターゲット状態を指定せずに「X を Y に合わせる」とは言いません。フェンスされたコードブロックや完全な実装を含みません。 |
| `<verify>` | タスクが成功したことを証明する実行可能なコマンドまたはチェック。合格と不合格を区別できなければなりません — `echo "done"` は無効です。 |
| `<acceptance_criteria>` | 検証可能な条件: grep で検証可能な文字列、コマンドの終了コード、観察可能な動作。主観的な言語（「正しく見える」、「適切に設定されている」）は使用しません。 |
| `<done>` | 完了した成果の短い測定可能な説明。 |
---
## プラン品質ディメンション
`gsd-plan-checker` エージェントは実行開始前に12のディメンションにわたってすべての PLAN.md をレビューします。BLOCKER 深刻度のチェックに失敗したプランは `gsd-planner` に差し戻されます（最大3回のイテレーション）：
| ディメンション | チェック内容 |
|---|---|
| **1 — Requirement Coverage** | ROADMAP.md からのすべてのフェーズ要件 ID が少なくとも1つのプランの `requirements` フロントマターフィールドに登場し、対応するタスクがある。 |
| **2 — Task Completeness** | すべての `auto` タスクが必須フィールド（`<files>`、`<action>`、`<verify>`、`<acceptance_criteria>`、`<done>`）を持つ。曖昧なフィールドや空のフィールドがない。 |
| **3 — Dependency Correctness** | `depends_on` の参照が有効で非循環かつウェーブ番号と整合している。ウェーブ N のプランはウェーブ < N のプランのみに依存する。 |
| **4 — Key Links Planned** | `must_haves.key_links` のアーティファクトに、アーティファクトの作成だけでなく配線を実装する対応するタスクがある。 |
| **5 — Scope Sanity** | プランはコンテキスト予算内に収まる: プランあたり2〜3タスク（4 = 警告、5以上 = BLOCKER）、プランあたり8〜10ファイル以下（15以上 = BLOCKER）。 |
| **6 — Verification Derivation** | `must_haves.truths` は実装の詳細ではなくユーザー観察可能な動作。アーティファクトが truths にマッピングされる。key links が重要な配線をカバーする。 |
| **7 — Context Compliance** | CONTEXT.md のすべての `D-NN` 決定が少なくとも1つのタスクによって対処されている。`<deferred>` にあるものをタスクが実装していない。 |
| **7b — Scope Reduction Detection** | タスクアクションが、完全な決定スコープを提供せずにロックされた決定を暗黙的に「v1」、「スタブ」、または「将来の強化」に縮小していない。発見された場合は常に BLOCKER。 |
| **7c — Architectural Tier Compliance** | タスクが RESEARCH.md の Architectural Responsibility Map（存在する場合）に従って正しいティアに機能を割り当てている。誤ったティアのセキュリティ機密機能は BLOCKER。 |
| **8 — Nyquist Compliance** | `workflow.nyquist_validation` が有効で RESEARCH.md が存在する場合、すべてのタスクに `<automated>` 検証コマンドがあり、連続する3タスクのウィンドウにカバレッジがなく、VALIDATION.md が存在する。 |
| **9 — Cross-Plan Data Contracts** | プランがデータパイプラインを共有する場合、それらの変換が互換性を持つ — 別のプランが元の形式で必要とするデータをプランが削除しない。 |
| **10 — CLAUDE.md Compliance** | プランが `./CLAUDE.md` のプロジェクト固有の規則、禁止パターン、必須ツール、セキュリティ要件を遵守している。 |
| **11 — Research Resolution** | RESEARCH.md が存在する場合、プランニングを進める前にその `## Open Questions` セクションが `(RESOLVED)` とマークされている。 |
| **12 — Pattern Compliance** | PATTERNS.md が存在する場合、タスクが新規または変更される各ファイルに対して正しいアナログパターンを参照している。 |
---
## ウェーブ実行モデル
ウェーブ番号はプランニング中に事前計算されます。Execute-phase はウェーブ番号でプランをグループ化し、各ウェーブのプランを並行して実行します：
```
Wave 1: Plan 01, Plan 02, Plan 03 (すべて同時実行 — 依存なし)
Wave 2: Plan 04 (Wave 1 完了を待機)
Wave 3: Plan 05 (Wave 2 完了を待機)
```
同一ウェーブ内で重複するファイルを変更するプランは同じウェーブに入れてはなりません — プランチェッカーのディメンション3がこれを BLOCKER としてフラグします。
---
## プラン出力
プランが正常に実行された後、エグゼキューターは以下のパスに SUMMARY.md を書き込みます：
```
.planning/phases/<NN>-<slug>/<NN>-<PP>-SUMMARY.md
```
SUMMARY.md は何が構築されたかの正規の記録です。同じフェーズの後続プランは、型や意思決定への真の依存がある場合にのみそれを参照できます。
---
## Related
- [CONTEXT.md スキーマ](context-md.md)
- [Planning artifacts](planning-artifacts.md)
- [Features](../../FEATURES.md)
- [docs index](../../README.md)

225
docs/ja-JP/reference/planning-artifacts.md Normal file
View File

@@ -0,0 +1,225 @@
# プランニングアーティファクト リファレンス
`.planning/` ディレクトリはプロジェクトの GSD Core 共有メモリです。すべてのワークフローはここから読み取り、書き込み、意思決定の監査可能な証跡を残します。このページではすべてのファイル、その目的、どのコマンドが生成・使用するかをマッピングします。[ドキュメントインデックス](../../README.md) も参照してください。
---
## ディレクトリ構造
```
.planning/
├── PROJECT.md # プロジェクトのアイデンティティとコアバリュー
├── ROADMAP.md # マイルストーン + フェーズ一覧とゴール
├── REQUIREMENTS.md # 番号付きの受け入れ基準
├── STATE.md # 現在地を追跡するリビングドキュメント
├── config.json # ワークフローとモデルの設定
├── MILESTONES.md # マイルストーンアーカイブ（オプション）
├── BACKLOG.md # 延期および将来の作業（オプション）
├── LEARNINGS.md # 蓄積されたフェーズ横断の学習（オプション）
├── DECISIONS-INDEX.md # 過去の意思決定のローリングサマリー（オプション）
├── METHODOLOGY.md # 再利用可能な解釈フレームワーク（オプション）
├── HANDOFF.json # 機械可読な一時停止状態（一時的）
├── codebase/ # コードベースマップ（オプション）
│ ├── architecture.md
│ ├── stack.md
│ └── ...
├── intel/ # クエリ可能なシンボルインデックス（オプション、intel.enabled）
│ └── API-SURFACE.md
└── phases/
└── <NN>-<slug>/ # フェーズごとに1ディレクトリ
├── <NN>-CONTEXT.md # 実装上の意思決定（discuss-phase）
├── <NN>-DISCUSSION-LOG.md # 人間可読なディスカッション監査（discuss-phase）
├── <NN>-RESEARCH.md # 技術リサーチの所見（plan-phase）
├── <NN>-VALIDATION.md # Nyquist テストカバレッジ戦略（plan-phase）
├── <NN>-PATTERNS.md # コードベースアナログマップ（plan-phase、オプション）
├── <NN>-<PP>-PLAN.md # 実行可能プラン（plan-phase、プランごとに1つ）
├── <NN>-<PP>-SUMMARY.md # 実行記録（execute-phase、プランごとに1つ）
├── <NN>-VERIFICATION.md # フェーズゴール検証レポート（verify-phase）
├── <NN>-UAT.md # 永続的な UAT セッション状態（execute-phase）
└── .continue-here.md # 一時停止後の再開指示（pause-work）
```
---
## ルートレベルのアーティファクト
### `PROJECT.md`
| | |
|---|---|
| **用途** | プロジェクトの正規アイデンティティ: 概要、対象ユーザー、コアバリュー、要件、制約、主要な意思決定。プロダクトの進化に伴いプロジェクトライフサイクル全体を通じて更新されます。 |
| **生成元** | `/gsd-new-project`（初回作成）; 意思決定が検証されると `/gsd-complete-milestone` によって更新されます。 |
| **参照先** | すべてのプランニングワークフロー; `gsd-phase-researcher`、`gsd-planner`（コンテキスト）; `discuss-phase`（過去の意思決定）; `gsd-plan-checker`（プロジェクト制約）。 |
### `ROADMAP.md`
| | |
|---|---|
| **用途** | マイルストーンおよびフェーズ一覧。ゴール、要件 ID、成功基準、フェーズごとの正規リファレンスを含みます。プロジェクトが何をどの順序で構築するかに関する唯一の信頼できる情報源です。 |
| **生成元** | `/gsd-new-project`（初回作成）; `/gsd-phase --insert` および `/gsd-complete-milestone` によって更新されます。 |
| **参照先** | `/gsd-discuss-phase`、`/gsd-plan-phase`、`/gsd-execute-phase`; フェーズ情報を必要とするすべてのオーケストレーションコマンド; `gsd-planner`、`gsd-plan-checker`、`gsd-phase-researcher`。 |
### `REQUIREMENTS.md`
| | |
|---|---|
| **用途** | 番号付きのチェック可能な受け入れ基準。各要件はロードマップフェーズにマッピングされる ID（例: `AUTH-01`）を持ちます。フェーズが実行されると要件を完了済みとしてマークします。 |
| **生成元** | `/gsd-new-project`（初回作成）; `execute-phase` によって要件が完了済みとしてマークされます。 |
| **参照先** | `gsd-planner`（プランはすべてのフェーズ要件 ID に対処しなければならない）; `gsd-plan-checker` ディメンション1（要件カバレッジ）; `discuss-phase`（過去の要件）。 |
### `STATE.md`
| | |
|---|---|
| **用途** | 現在地を追跡するリビングドキュメント — 現在のフェーズとプラン、進捗指標、蓄積された意思決定、セッション継続性ノート。すべてのワークフロー実行の開始時に読み込まれます。重要なアクションのたびに更新されます。 |
| **生成元** | `/gsd-new-project`（初回作成）; すべてのフェーズワークフロー、`/gsd-pause-work`、`/gsd-resume-work` によって継続的に更新されます。 |
| **参照先** | すべてのオーケストレーションワークフロー; `/gsd-progress`; `/gsd-quick` 経由のアドホックタスク実行; `gsd-planner` および `gsd-phase-researcher`（プロジェクトの意思決定）。 |
完全なフィールドリファレンスは [STATE.md スキーマ](state-md.md) を参照してください。
### `config.json`
| | |
|---|---|
| **用途** | ワークフロー設定: モデルプロファイル、リサーチおよびプランチェッカーのトグル、Git ブランチング戦略、Nyquist バリデーション、並列化設定、エージェントごとのモデルオーバーライド。 |
| **生成元** | `/gsd-new-project`（初回作成）; `/gsd-settings`（インタラクティブ編集）。 |
| **参照先** | すべてのワークフローとサブエージェント — `gsd-tools query config-get` 経由で初期化時に読み込まれます。 |
完全なスキーマは [CONFIGURATION](../../CONFIGURATION.md) を参照してください。
### `MILESTONES.md`（オプション）
| | |
|---|---|
| **用途** | 完了したマイルストーンの履歴記録。各マイルストーンのクローズ時に追記されます。何がいつリリースされたかのアーカイブスナップショットを提供します。 |
| **生成元** | `/gsd-complete-milestone`。 |
| **参照先** | `/gsd-audit-milestone`; 人間によるレビュー。 |
### `DECISIONS-INDEX.md`（オプション）
| | |
|---|---|
| **用途** | 過去のフェーズの CONTEXT.md ファイルに記録された意思決定の有界ローリングサマリー。存在する場合、`discuss-phase` は最大3つの過去 CONTEXT.md ファイルを個別に読む代わりにこの単一ファイルを読み取り、コンテキスト予算を節約します。 |
| **生成元** | 過去フェーズの数がローリング読み取り閾値を超えたときに生成されます。 |
| **参照先** | `discuss-phase`（`load_prior_context` ステップ）。 |
### `HANDOFF.json`（一時的）
| | |
|---|---|
| **用途** | 作業が中断されたときに書き込まれる機械可読な一時停止状態。再開ポイント、進行中のコンテキスト、継続指示を含みます。再開時に一度だけ使用されます。 |
| **生成元** | `/gsd-pause-work`。 |
| **参照先** | `/gsd-resume-work`。 |
---
## フェーズごとのアーティファクト
すべてのフェーズごとのファイルは `.planning/phases/<NN>-<slug>/` 以下に配置されます。`NN` はゼロパディングされたフェーズ番号、`slug` はハイフン区切りのフェーズ名です。
### `<NN>-CONTEXT.md`
| | |
|---|---|
| **用途** | プランニング開始前に収集された実装上の意思決定。フェーズ境界（`<domain>`）、`D-NN` 識別子付きのロックされた意思決定（`<decisions>`）、正規のドキュメント参照（`<canonical_refs>`）、既存のコードのインサイト（`<code_context>`）、具体的な参考例（`<specifics>`）、延期されたアイデア（`<deferred>`）を含みます。 |
| **生成元** | `/gsd-discuss-phase`（インタラクティブなディスカッションまたは PRD/ADR エクスプレスパス）。 |
| **参照先** | `gsd-phase-researcher`（調査すべき内容）; `gsd-planner`（ロックされた意思決定）; `gsd-plan-checker` ディメンション7（コンテキスト準拠）。 |
完全なフィールドリファレンスは [CONTEXT.md スキーマ](context-md.md) を参照してください。
### `<NN>-DISCUSSION-LOG.md`
| | |
|---|---|
| **用途** | discuss-phase セッションの人間可読な監査証跡: 議論された領域、提示されたオプション、行われた選択、延期されたアイデア、Claude の裁量に任せられた項目。自動化されたワークフローには使用されません。 |
| **生成元** | `/gsd-discuss-phase`（`git_commit` ステップ）。 |
| **参照先** | 人間によるレビュー; 振り返り。 |
### `<NN>-RESEARCH.md`
| | |
|---|---|
| **用途** | プランニング前に生成される技術リサーチの所見。「このフェーズをうまくプランニングするために何を知る必要があるか？」という問いに答えます — ドメイン分析、パターン、リスク、Architectural Responsibility Map、Validation Architecture セクション（Nyquist ゲートで使用）をカバーします。 |
| **生成元** | `/gsd-plan-phase`（`gsd-phase-researcher` エージェント経由）。 |
| **参照先** | `gsd-planner`（プランニングインプット）; `gsd-plan-checker` ディメンション7c（ティア準拠）、ディメンション8（Nyquist）、ディメンション11（リサーチ解決）; `gsd-pattern-mapper`（ファイルリストのソース）。 |
### `<NN>-VALIDATION.md`
| | |
|---|---|
| **用途** | RESEARCH.md の `## Validation Architecture` セクションから導出された Nyquist インスパイアのバリデーション戦略。プランが遵守しなければならない自動テストカバレッジ要件を指定します。 |
| **生成元** | `/gsd-plan-phase`（ステップ5.5、`workflow.nyquist_validation` が有効で RESEARCH.md に Validation Architecture セクションが含まれる場合）。 |
| **参照先** | `gsd-plan-checker` ディメンション8（チェック8e ゲート — Nyquist チェック進行前に存在しなければならない）; `gsd-verifier`。 |
### `<NN>-PATTERNS.md`
| | |
|---|---|
| **用途** | `gsd-pattern-mapper` によって生成されたコードベースアナログマップ。このフェーズで作成または変更される各ファイルに対して、最も近い既存のアナログを特定し、ファイルの役割とデータフローを分類し、具体的なコード抜粋を抽出します。プランナーを一貫したパターンに向けます。 |
| **生成元** | `/gsd-plan-phase`（`gsd-pattern-mapper` エージェント経由、オプション; `workflow.pattern_mapper: false` の場合はスキップ）。 |
| **参照先** | `gsd-planner`（パターンガイダンス）; `gsd-plan-checker` ディメンション12（パターン準拠）。 |
### `<NN>-<PP>-PLAN.md`
| | |
|---|---|
| **用途** | フェーズ内の単一作業単位の実行可能プラン。YAML フロントマター（ウェーブ、依存関係、ファイル、要件、`must_haves`）、目的、コンテキスト参照、`<read_first>`、`<action>`、`<verify>`、`<acceptance_criteria>` フィールドを持つ XML 構造化タスク、検証基準を含みます。 |
| **生成元** | `/gsd-plan-phase`（`gsd-planner` エージェント経由）。プランごとに1ファイル — 例: `03-02-PLAN.md` はフェーズ3、プラン2。 |
| **参照先** | `/gsd-execute-phase`（エグゼキューターエージェントがプランを読んでタスクを実行）; `gsd-plan-checker`（実行前の品質レビュー）; `gsd-verifier`（実行後の検証のために `must_haves` を読む）。 |
完全なフィールドリファレンスは [PLAN.md スキーマ](plan-md.md) を参照してください。
### `<NN>-<PP>-SUMMARY.md`
| | |
|---|---|
| **用途** | プラン完了後に書き込まれる実行記録。構築された内容、プランからの逸脱、受け入れ基準に対するセルフチェック、フェーズの依存グラフを記録します。 |
| **生成元** | `execute-phase` エグゼキューターエージェント（各プランの実行終了時に書き込まれます）。 |
| **参照先** | `/gsd-progress`（フェーズステータス）; `gsd-planner`（後続のプランが以前のプラン出力への真の依存を持つ場合）; `milestone-summary`。 |
### `<NN>-VERIFICATION.md`
| | |
|---|---|
| **用途** | フェーズゴール検証レポート。実行後に実際のコードベースに対してすべてのプランの `must_haves.truths`、`must_haves.artifacts`、`must_haves.key_links` を確認します。`status: passed | gaps_found | human_needed` を記録します。 |
| **生成元** | `/gsd-verify-work`（または `/gsd-execute-phase` 内の検証ステップ）。 |
| **参照先** | `plan-phase` クローズドフェーズゲート（`status: passed` の VERIFICATION.md はフェーズを `Complete` としてマークし、`--force` なしの再プランニングをブロックする）; `/gsd-progress`; 人間によるレビュー。 |
### `<NN>-UAT.md`
| | |
|---|---|
| **用途** | 永続的な UAT セッション追跡。ライブ UAT セッション全体を通じて各テストケース、期待される観察可能な動作、結果、開発者のレスポンスを記録します。YAML フロントマター（`status`、`phase`、`source`、タイムスタンプ）を持ちます。 |
| **生成元** | `/gsd-audit-uat`（インタラクティブな UAT セッション）。 |
| **参照先** | `/gsd-audit-uat`（以前の UAT セッションの再開）。 |
### `.continue-here.md`
| | |
|---|---|
| **用途** | フェーズの作業が一時停止されたときに書き込まれる人間可読な再開指示。再開エージェントのためのコンテキストを含みます: 重要なアンチパターン、ブロッキング問題、必要な参照、再開するための正確なコマンド。 |
| **生成元** | `/gsd-pause-work`。 |
| **参照先** | フェーズで開始するすべてのワークフロー — `discuss-phase` と `plan-phase` は両方ともエントリ時にこのファイルを確認し、処理を進める前にエージェントが `blocking` アンチパターンへの理解を示すことを要求します。 |
---
## 命名規則
| セグメント | フォーマット | 例 |
|---|---|---|
| フェーズディレクトリ | `<NN>-<slug>` | `03-post-feed` |
| フェーズレベルファイル | `<NN>-<ARTIFACT>.md` | `03-CONTEXT.md` |
| プランレベルファイル | `<NN>-<PP>-<ARTIFACT>.md` | `03-02-PLAN.md` |
| `NN` | ゼロパディングされたフェーズ番号 | フェーズ3は `03` |
| `PP` | フェーズ内のゼロパディングされたプラン番号 | プラン2は `02` |
`config.json` に `project_code` が設定されている場合、フェーズディレクトリはプロジェクトコードをプレフィックスとして使用します: プロジェクトコード `CK`、フェーズ3の場合は `CK-03-post-feed`。
---
## Related
- [STATE.md スキーマ](state-md.md)
- [CONTEXT.md スキーマ](context-md.md)
- [PLAN.md スキーマ](plan-md.md)
- [docs index](../../README.md)

201
docs/ja-JP/reference/state-md.md Normal file
View File

@@ -0,0 +1,201 @@
# STATE.md スキーマリファレンス
`STATE.md` は GSD Core のプロジェクト記憶ファイルです — プロジェクトの現在地、直近の作業内容、次に実行すべきコマンドを記録する単一の Markdown ドキュメントです。このページではそのスキーマを説明します。[ドキュメントインデックス](../../README.md) も参照してください。
---
## 概要
GSD Core で管理するプロジェクトはすべて `.planning/STATE.md` に `STATE.md` を1つ保持します。このファイルはすべてのワークフロー開始時に読み込まれ、重要なアクションのたびに書き込まれます。ファイルは以下を組み合わせた構成です：
- **YAML フロントマター** — ステータスラインフック（`parseStateMd`）および `gsd-tools state` コマンドが読み取る機械可読フィールド。
- **Markdown 本文** — 現在の進捗、蓄積されたコンテキスト、セッション継続性、パフォーマンス指標を記述する人間可読なセクション。
ファイルは意図的にコンパクトに保たれています（目標: 100行以内）。プロジェクト状態のダイジェストであり、アーカイブではありません。
---
## YAML フロントマター
フロントマターはファイルの先頭にある `---` デリミタの間に記述します。`gsd_state_version` と `status` 以外のフィールドはすべてオプションで、データが未取得の場合は省略できます。
### 注釈付きサンプル
```yaml
---
gsd_state_version: '1.0'
milestone: v2.0
milestone_name: Code Quality
status: executing
# フェーズライフサイクルフィールド — すべてオプション (v1.40.0, issue #2833 で追加)
active_phase: "4.5"
next_action: execute-phase
next_phases: ["4.5"]
progress:
total_phases: 17
completed_phases: 10
total_plans: 84
completed_plans: 47
percent: 59
# syncStateFrontmatter が書き込む追加フィールド
current_phase: "4"
current_phase_name: Observability
current_plan: "3"
last_updated: "2026-06-01T12:34:56.789Z"
last_activity: "2026-06-01"
stopped_at: "Phase 4 P3 execution complete"
paused_at: null
---
```
### フィールドリファレンス
| フィールド | 型 | 設定タイミング | 用途 |
|---|---|---|---|
| `gsd_state_version` | string (`'1.0'`) | 常時 | スキーマバージョン。`syncStateFrontmatter` が最初の `state.*` 呼び出し時に書き込む。 |
| `milestone` | string (例: `v2.0`) | マイルストーン設定時 | 現在のマイルストーンバージョン。プロジェクト設定から読み取る。 |
| `milestone_name` | string | マイルストーン設定時 | 人間可読なマイルストーンラベル (例: `Code Quality`)。 |
| `status` | string | 常時 | 現在のライフサイクルステージ。`normalizeStateStatus()` によって正規化される — [ステータス値](#ステータス値) 参照。 |
| `active_phase` | string (例: `"4.5"`) | このフェーズでオーケストレーターコマンドが実行中の場合 | 現在処理中のフェーズ番号。フェーズ間は `null` に設定。 |
| `next_action` | string | アイドル中で推奨コマンドがある場合 | 次に実行するスラッシュコマンド: `discuss-phase`、`plan-phase`、`execute-phase`、`verify-phase`。オーケストレーターが実行中または推奨なしの場合は `null` に設定。 |
| `next_phases` | YAML フロー配列 (例: `["4.5"]`) | `next_action` と対応して | `next_action` が適用されるフェーズ ID（通常1〜2件）。`next_action` と同条件で `null` に設定。 |
| `progress.total_phases` | integer | フェーズデータ取得済みの場合 | 現在のマイルストーンにおける総フェーズ数。ROADMAP.md とフェーズディレクトリから算出。 |
| `progress.completed_phases` | integer | フェーズデータ取得済みの場合 | すべてのプランサマリーがディスク上に存在するフェーズ数（すなわちすべてのプランが完了したもの）。 |
| `progress.total_plans` | integer | プランファイルが存在する場合 | 現在のマイルストーンの全フェーズにわたるプランファイルの合計数。 |
| `progress.completed_plans` | integer | サマリーファイルが存在する場合 | 完了したプランサマリーの合計数（実行済みプランごとに1つの SUMMARY.md）。 |
| `progress.percent` | integer 0–100 | 進捗データ取得済みの場合 | **フェーズ次元** でのマイルストーン進捗（`min(completed_plans/total_plans, completed_phases/total_phases)`）。このフィールドが存在するときのみステータスラインの進捗バーが描画されます — 不在の場合はバーが非表示になります。 |
| `current_phase` | string | フェーズ実行中 | 本文の `Current Phase:` フィールドから抽出したフェーズ番号。 |
| `current_phase_name` | string | フェーズに名前がある場合 | 本文の `Current Phase Name:` フィールドから抽出したフェーズ名。 |
| `current_plan` | string | プランが進行中の場合 | 本文の `Current Plan:` フィールドから抽出したプラン番号。 |
| `last_updated` | ISO-8601 タイムスタンプ | 書き込み時に常時 | 最後の `syncStateFrontmatter` 呼び出しのタイムスタンプ。`realClock.nowIso()` によって書き込まれる。 |
| `last_activity` | string | 本文に設定されている場合 | 本文の `Last Activity:` フィールドから抽出した最終活動日。 |
| `stopped_at` | string | 停止ポイントが記録された場合 | 最後に完了したアクションの説明。アーカイブの文章とのマッチを避けるため `## Session` 本文セクションにスコープを限定。 |
| `paused_at` | string | プロジェクトが一時停止中の場合 | 一時停止ポイントの自由形式の説明。一時停止していない場合は省略または `null`。 |
### ステータス値
`get-shit-done/bin/lib/state-document.cjs` の `normalizeStateStatus()` が本文の生テキストを以下の正規値にマッピングします：
| 正規値 | マッチするテキスト（大文字小文字不問） |
|---|---|
| `discussing` | `discussing` を含む |
| `planning` | `planning` または `ready to plan` を含む |
| `executing` | `executing`、`in progress`、または `ready to execute` を含む |
| `verifying` | `verif` を含む |
| `completed` | `complete` または `done` を含む |
| `paused` | `paused` または `stopped` を含む、または `paused_at` が存在する |
| `unknown` | 上記のいずれにも該当しない |
オーケストレーターコマンドが実行中の場合、慣例（issue #2833）として `status` にライフサイクルステージを直接書き込みます：
| コマンド | 実行中の `status` |
|---|---|
| `/gsd-discuss-phase` | `discussing` |
| `/gsd-plan-phase` | `planning` |
| `/gsd-execute-phase` | `executing` |
| `/gsd-verify-work` | `verifying` |
---
## ステータスライン描画シーン
`hooks/gsd-statusline.js` の `formatGsdState()` がパース済みフロントマターを読み取り、**最初にマッチしたシーン** を出力します。新しいライフサイクルフィールドが適用されない場合は、v1.38.x から一切変更なくオリジナルのフォーマットにフォールスルーします。
| シーン | トリガー | 表示例 |
|---|---|---|
| **1. フェーズアクティブ** | `active_phase` が設定されている | `v2.0 [██░░░░░░░░] 20% · Phase 4.5 executing` |
| **2. アイドル・次のアクション推奨** | `active_phase` が null かつ `next_action` と `next_phases` の両方が設定されている | `v2.0 [██░░░░░░░░] 20% · next execute-phase 4.5` |
| **3. マイルストーン完了** | `percent` が `100` または `completed_phases == total_phases` | `v2.0 [██████████] 100% · milestone complete` |
| **4. デフォルトフォールバック** | 上記のいずれにも該当しない | `v1.9 Code Quality · executing · ph 1/5`（既存フォーマット） |
**シーン優先度:** `active_phase` と `next_action` が両方設定されている場合、シーン1が優先されます — オーケストレーターが実行中であるため「次の推奨」は誤解を招くためです。この優先度は `formatGsdState()` のチェック順序によって強制され、`tests/enh-2833-phase-lifecycle-statusline.test.cjs` の `"scene priority"` スイートでカバーされています。
進捗バー（`[██░░░░░░░░] 20%`）はフロントマターに `progress.percent` が存在する場合のみマイルストーンセグメントに追加されます。不在の場合はバーは表示されません。
---
## フロントマターパースの制約
ステータスラインフックは正規表現ベースのパース（完全な YAML ライブラリを使用しない）を使用するため、以下の制約が適用されます。これらは `tests/enh-2833-phase-lifecycle-statusline.test.cjs` でテストされています。
1. **フロントマターはファイルの先頭文字から始まる必要があります。** コメントを含む何かが開始 `---` の前にあると、マッチが無効になります。開始 `---` 行は末尾のスペースなしで正確にそれだけである必要があります。
2. **ネストされたブロック内のコメントはサポートされていません。** `progress:` ブロックパーサーは次の行が `[ \t]+\w+:` であることを要求します。`progress:` と最初のキーの間に `# comment` を挿入するとマッチが壊れてバーが消えます。ドキュメントはフロントマターブロック内ではなく `STATE.md` 本文に記載してください。
3. **`next_phases` の主形式は単一行フローです。** パーサーは最初に `next_phases: ["4.5", "4.6"]` を試みます。ブロックシーケンス（`- 4.5\n- 4.6`）もパースされますが、ステータスライン描画の信頼性は低下します。正規表現ベースのパーサーを予測可能に保つため、`next_phases` には単一行フローを使用してください。多数の候補フェーズをドキュメント目的で記録する必要がある場合は `STATE.md` 本文に格納してください。
将来的に正規表現パーサーを完全な YAML ライブラリに置き換えた場合は、これらの制約を緩和しテストを更新できます。
---
## Markdown 本文セクション
本文（末尾の `---` 以降のすべて）は `get-shit-done/templates/state.md` のテンプレートに従います。標準セクションは以下の通りです：
### Project Reference
`.planning/PROJECT.md` へのポインタです。以下を含みます：
- **Core value** — `PROJECT.md` の Core Value セクションの一行説明。
- **Current focus** — アクティブなフェーズ。
### Current Position
プロジェクトの現在の状況：
| フィールド | フォーマット |
|---|---|
| `Phase:` | `X of Y (Phase name)` |
| `Plan:` | `A of B in current phase` |
| `Status:` | 自由テキスト。例: `Ready to execute`、`Executing Phase 4`、`Phase complete — ready for verification` |
| `Last activity:` | ハンドラー書き込み時は ISO 日付（`YYYY-MM-DD`）; エグゼキューター作成時はナラティブ文章 |
| `Progress:` | ビジュアルバー。例: `[████░░░░░░] 40%` |
このセクションの `Status:` および `Last activity:` フィールドは、既存の値が既知のテンプレートデフォルト値の場合に GSD ハンドラーによって更新されます（クヌース不変式: エグゼキューター作成値は保存されます）。既知のハンドラーデフォルト値の完全なリストは `get-shit-done/bin/lib/state-document.cjs` の `KNOWN_TEMPLATE_DEFAULTS` に記載されています。
### Performance Metrics
実行速度の追跡：
- 完了した総プラン数、プランあたりの平均所要時間。
- フェーズごとの内訳テーブル（`Phase | Plans | Total | Avg/Plan`）。
- 最近のトレンド: Improving / Stable / Degrading。
各プラン完了後に更新されます。
### Accumulated Context
**Decisions** — 現在の作業に影響する最近の意思決定のサマリー（完全なログは `PROJECT.md` に保存）。`gsd-tools state add-decision` で追加。
**Pending Todos** — 件数と `.planning/todos/pending/` への参照。`/gsd-capture` で取得。
**Blockers/Concerns** — 今後の作業に影響する課題。起点フェーズのプレフィックス付き。`gsd-tools state add-blocker` で追加し、`gsd-tools state resolve-blocker` で解決。
### Session Continuity
即座のセッション再開を可能にします：
- `Last session:` — 最後のセッションの ISO-8601 タイムスタンプ。
- `Stopped at:` — 最後に完了したアクションの説明。
- `Resume file:` — `.continue-here*.md` ファイルが存在する場合はそのパス、存在しない場合は `None`。
---
## 後方互換性
フェーズライフサイクルフィールド（`active_phase`、`next_action`、`next_phases`、バー用の `progress.percent`）は **追加式でプロジェクトごとにオプトイン** です：
- ライフサイクルフィールドが一切設定されていない `STATE.md` は v1.38.x 以前と **バイト単位で同一** に描画されます。
- ライフサイクルフィールドの追加はオプトインです — フィールドが不在の場合レンダラーはグレースフルに縮退します。
- 進捗バーは `progress` ブロックが存在する場合でもオプトインです: バーをトリガーするのは `progress.percent` のみで、`total_phases` と `completed_phases` だけではトリガーされません。
`tests/enh-2833-phase-lifecycle-statusline.test.cjs` の `formatGsdState #2833 backward compatibility` テストスイートがこの保証を固定しています。レガシー `STATE.md` 描画を壊す変更があればスイートが失敗します。
---
## Related
- [Planning artifacts](planning-artifacts.md)
- [Configuration](../../CONFIGURATION.md)
- [The phase loop](../../explanation/the-phase-loop.md)
- [docs index](../../README.md)

226
docs/ja-JP/tutorials/onboarding-an-existing-codebase.md Normal file
View File

@@ -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)

291
docs/ja-JP/tutorials/your-first-project.md Normal file
View File

@@ -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 の導入

78
docs/ja-JP/workflow-discuss-mode.md
View File

@@ -1,65 +1,75 @@
# ディスカスモード: Assumptions vs Interview
# ディスカッションモード：仮定 vs インタビュー
GSD の discuss フェーズには、プランニング前に実装コンテキストを収集するための2つのモードがあります。
GSD Core のディスカッションフェーズは、計画を開始する前に実装コンテキストを収集するための 2 つのモードを提供します。どちらを使用するかを理解することで、質疑応答から確定した `CONTEXT.md` へとより少ない往復でたどり着けます。
どちらのモードを実行するかのステップバイステップの手順については、[フェーズ議論の how-to](how-to/discuss-a-phase.md) を参照してください。
## モード
### `discuss`（デフォルト）
従来のインタビュー形式のフローです。Claude がフェーズ内の不明瞭な領域を特定し、選択肢として提示した後、各領域について約4つの質問を行います。以下のケースに適しています:
オリジナルのインタビュースタイルのフロー。Claude がフェーズのグレーエリアを特定し、選択のために提示し、エリアごとに約 4 つの質問をします。以下の場合に適しています：
- コードベースが初めてで、初期フェーズの場合
- ユーザーが積極的に意見を表明したい場合
- ガイド付きの対話的なコンテキスト収集を好むユーザー
- コードベースが新しい初期フェーズ
- ユーザーが積極的に表明したい強い意見を持っているフェーズ
- ガイドされた会話形式のコンテキスト収集を好むユーザー
### `assumptions`
コードベース優先のフローです。Claude がサブエージェントを通じてコードベースを深く分析し（関連ファイルを5〜15個読み取り）、根拠付きの仮説を立てて確認・修正を求めます。以下のケースに適しています:
コードベースファーストのフロー。Claude はサブエージェント経由でコードベースを深く分析し（関連ファイルを 5〜15 件読み取り）、証拠付きで仮定を形成し、確認または修正のために提示します。以下の場合に適しています：
- 明確なパターンが確立されたコードベース
- インタビューの質問が自明と感じるユーザー
- より高速なコンテキスト収集（約2〜4回のやり取り vs 約15〜20回）
- 明確なパターンを持つ確立されたコードベース
- インタビューの質問が明らかに思えるユーザー
- より速いコンテキスト収集（約 2〜4 回のやり取り vs 約 15〜20 回）
## 設定
```bash
# assumptions モードを有効にする
gsd-tools config-set workflow.discuss_mode assumptions
node gsd-tools.cjs config-set workflow.discuss_mode assumptions
# interview モードに戻す
gsd-tools config-set workflow.discuss_mode discuss
# インタビューモードに戻す
node gsd-tools.cjs config-set workflow.discuss_mode discuss
```
この設定はプロジェクト単位です（`.planning/config.json` に保存されます）。
この設定はプロジェクトごとです（`.planning/config.json` に保存されます）。両方のモードが生成するファイルの完全な構造については、[CONTEXT.md スキーマ](reference/context-md.md) を参照してください。
## Assumptions モードの仕組み
1. **初期化** — discuss モードと同様（前回のコンテキスト読み込み、コードベース調査、TODO チェック）
2. **深層分析** — Explore サブエージェントがフェーズに関連するコードベースファイルを5〜15個読み取る
3. **仮説の提示** — 各仮説には以下が含まれる:
1. **Init** — discuss モードと同じ（以前のコンテキストを読み込み、コードベースを偵察し、todo を確認）
2. **深い分析** — Explore サブエージェントがフェーズに関連する 5〜15 のコードベースファイルを読み取る
3. **仮定の表示** — 各仮定には以下が含まれる：
- Claude が何をどのような理由で行うか（ファイルパスを引用）
- 仮説が間違っていた場合のリスク
- 確信度レベル（Confident / Likely / Unclear）
4. **確認または修正** — ユーザーが仮説をレビューし、変更が必要なものを選択
5. **CONTEXT.md の生成** — discuss モードと同一の出力フォーマット
- 仮定が誤っている場合に何が問題になるか
- 信頼レベル（Confident / Likely / Unclear）
4. **確認または修正** — ユーザーが仮定を確認し、変更が必要なものを選択
5. **CONTEXT.md の書き込み** — discuss モードと同一の出力フォーマット
## フラグの互換性
| フラグ | `discuss` モード | `assumptions` モード |
|--------|-----------------|---------------------|
| `--auto` | 推奨回答を自動選択 | 確認ゲートをスキップし、Unclear 項目を自動解決 |
| `--batch` | 質問をバッチでグループ化 | N/A（修正は既にバッチ化済み） |
| `--text` | プレーンテキスト形式の質問（リモートセッション向け） | プレーンテキスト形式の質問（リモートセッション向け） |
| `--analyze` | 質問ごとにトレードオフ表を表示 | N/A（仮説に根拠が含まれる） |
|------|----------------|-------------------|
| `--auto` | 推奨される答えを自動選択 | 確認ゲートをスキップし、Unclear 項目を自動解決 |
| `--batch` | 質問をバッチでグループ化 | N/A（修正はすでにバッチ化） |
| `--text` | プレーンテキストの質問（リモートセッション） | プレーンテキストの質問（リモートセッション） |
| `--analyze` | 質問ごとにトレードオフテーブルを表示 | N/A（仮定には証拠が含まれる） |
## 出力
両モードとも、同じ6セクション構成の CONTEXT.md を生成します:
- `<domain>` — フェーズの境界
- `<decisions>` — 確定した実装上の決定事項
- `<canonical_refs>` — 下流エージェントが読むべき仕様・ドキュメント
- `<code_context>` — 再利用可能なアセット、パターン、統合ポイント
- `<specifics>` — ユーザーの参照情報と好み
- `<deferred>` — 将来のフェーズに先送りするアイデア
両方のモードが同じ 6 つのセクションを持つ同一の `CONTEXT.md` を生成します：
下流エージェント（researcher、planner、checker）は、モードに関係なくこの出力を同一に消費します。
- `<domain>` — フェーズ境界
- `<decisions>` — ロックされた実装上の決定
- `<canonical_refs>` — 下流エージェントが必ず読むべき仕様/ドキュメント
- `<code_context>` — 再利用可能なアセット、パターン、統合ポイント
- `<specifics>` — ユーザーの参照と好み
- `<deferred>` — 将来のフェーズのために記録されたアイデア
下流エージェント（researcher、planner、checker）は、どちらのモードで生成されたかに関わらず、このファイルを同様に消費します。完全なフィールドリファレンスについては [CONTEXT.md スキーマ](reference/context-md.md) を参照してください。
## Related
- [フェーズの議論](how-to/discuss-a-phase.md) — どちらのモードでも `/gsd-discuss-phase` を実行するためのステップバイステップの how-to。
- [CONTEXT.md スキーマ](reference/context-md.md) — 両方のモードが生成するファイルの完全なフィールドリファレンス。
- [フェーズループ](explanation/the-phase-loop.md) — discuss がより広い discuss → plan → execute → verify → ship サイクルにどう組み込まれるか。
- [ドキュメント索引](README.md) — GSD Core ドキュメントの完全な目次。