docs: rebrand to GSD Core and restructure docs with Diataxis (#605)
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
5
.changeset/lucid-docs-rebrand.md
Normal file
5
.changeset/lucid-docs-rebrand.md
Normal file
@@ -0,0 +1,5 @@
|
|||||||
|
---
|
||||||
|
type: Changed
|
||||||
|
pr: 605
|
||||||
|
---
|
||||||
|
**Public documentation rebranded to GSD Core and restructured around Diataxis** — the root README and `docs/` are reorganised into tutorials, how-to guides, reference, and explanation, with new how-to guides, schema references (STATE.md / CONTEXT.md / PLAN.md / planning artifacts), and full cross-linking; legacy `gsd-build` references are updated to `open-gsd`, and the localised doc trees (ja-JP, ko-KR, pt-BR, zh-CN) are regenerated to match. Internal filesystem paths are unchanged. (#605)
|
||||||
836
README.ja-JP.md
836
README.ja-JP.md
@@ -1,16 +1,12 @@
|
|||||||
> ⚠️ This is an active fork. See the [English README](README.md) for the full notice about the original repo.
|
|
||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
# GSD Core
|
# GSD Core
|
||||||
|
|
||||||
**Git. Ship. Done.**
|
**Git. Ship. Done.**
|
||||||
|
|
||||||
[English](README.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md) · **日本語**
|
[English](README.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md) · **日本語** · [한국어](README.ko-KR.md)
|
||||||
|
|
||||||
**Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、Cline向けの軽量かつ強力なメタプロンプティング、コンテキストエンジニアリング、仕様駆動開発システム。**
|
**Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf などに対応した、軽量なメタプロンプティング・コンテキストエンジニアリング・仕様駆動開発システムです。**
|
||||||
|
|
||||||
**コンテキストロット（Claudeがコンテキストウィンドウを消費するにつれ品質が劣化する現象）を解決します。**
|
|
||||||
|
|
||||||
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
||||||
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
||||||
@@ -19,830 +15,88 @@
|
|||||||
[](https://github.com/open-gsd/gsd-core)
|
[](https://github.com/open-gsd/gsd-core)
|
||||||
[](LICENSE)
|
[](LICENSE)
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
**Mac、Windows、Linuxで動作します。**
|
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
*「自分が何を作りたいか明確に分かっていれば、これが確実に作ってくれる。嘘じゃない。」*
|
|
||||||
|
|
||||||
*「SpecKit、OpenSpec、Taskmasterを試してきたが、これが一番良い結果を出してくれた。」*
|
|
||||||
|
|
||||||
*「Claude Codeへの最強の追加ツール。過剰な設計は一切なし。文字通り、やるべきことをやってくれる。」*
|
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
**Amazon、Google、Shopify、Webflowのエンジニアに信頼されています。**
|
|
||||||
|
|
||||||
[なぜ作ったのか](#なぜ作ったのか) · [仕組み](#仕組み) · [コマンド](#コマンド) · [なぜ効果的なのか](#なぜ効果的なのか) · [ユーザーガイド](docs/ja-JP/USER-GUIDE.md)
|
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## なぜ作ったのか
|
## GSD Core とは
|
||||||
|
|
||||||
私はソロ開発者です。コードは自分で書きません — Claude Codeが書きます。
|
GSD Core は、コンテキストエンジニアリングと仕様駆動開発のフレームワークです。AI コーディングエージェント（Claude Code、Codex、Gemini CLI、Copilot、Cursor など）を規律あるフェーズループで動かします。[コンテキストの腐敗](docs/ja-JP/explanation/context-engineering.md)—AI がコンテキストウィンドウを埋めるにつれて出力品質が低下する問題—を解決するために、重いリサーチ・計画・実行作業をすべて新鮮なコンテキストのサブエージェントで実行し、メインセッションをスリムに保ちます。
|
||||||
|
|
||||||
仕様駆動開発ツールは他にもあります。BMAD、Spekkitなど。しかしどれも必要以上に複雑にしているように見えます（スプリントセレモニー、ストーリーポイント、ステークホルダーとの同期、振り返り、Jiraワークフローなど）。あるいは、何を作ろうとしているのかの全体像を本当には理解していません。私は50人規模のソフトウェア会社ではありません。エンタープライズごっこをしたいわけではありません。ただ、うまく動く素晴らしいものを作りたいクリエイティブな人間です。
|
|
||||||
|
|
||||||
だからGSDを作りました。複雑さはシステムの中にあり、ワークフローの中にはありません。裏側では、コンテキストエンジニアリング、XMLプロンプトフォーマッティング、サブエージェントのオーケストレーション、状態管理が動いています。あなたが目にするのは、ただ動くいくつかのコマンドだけです。
|
|
||||||
|
|
||||||
このシステムは、Claudeが仕事をし、*かつ*検証するために必要なすべてを提供します。私はこのワークフローを信頼しています。ちゃんといい仕事をしてくれます。
|
|
||||||
|
|
||||||
これがGSDです。エンタープライズごっこは一切なし。Claude Codeを使って一貫してクールなものを作るための、非常に効果的なシステムです。
|
|
||||||
|
|
||||||
— **TÂCHES**
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
バイブコーディングは評判が悪い。やりたいことを説明し、AIがコードを生成し、スケールすると崩壊する一貫性のないゴミが出来上がる。
|
## 動作原理
|
||||||
|
|
||||||
GSDはそれを解決します。Claude Codeを信頼性の高いものにするコンテキストエンジニアリングレイヤーです。アイデアを説明し、システムに必要なすべてを抽出させ、Claude Codeに仕事をさせましょう。
|
各マイルストーンは同じ 5 ステップのループを、1 フェーズずつ繰り返します。
|
||||||
|
|
||||||
|
1. **Discuss（議論）** — 計画を立てる前に実装上の決定事項を記録する
|
||||||
|
2. **Plan（計画）** — リサーチし、タスクを分解し、計画が新鮮なコンテキストウィンドウに収まることを確認する
|
||||||
|
3. **Execute（実行）** — 並列ウェーブで計画を実行する。各エグゼキューターはクリーンな 200k トークンのコンテキストから開始する
|
||||||
|
4. **Verify（検証）** — 構築されたものを確認し、完了を宣言する前に診断・修正する
|
||||||
|
5. **Ship（出荷）** — PR を作成し、フェーズをアーカイブし、次のフェーズに進む
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## こんな人のために
|
## クイックスタート
|
||||||
|
|
||||||
やりたいことを説明するだけで正しく構築してほしい人 — 50人のエンジニア組織を運営しているふりをせずに。
|
|
||||||
|
|
||||||
ビルトインの品質ゲートが本当の問題を検出します：スキーマドリフト検出はマイグレーション漏れのORM変更をフラグし、セキュリティ強制は検証を脅威モデルに紐付け、スコープ削減検出はプランナーが要件を暗黙的に落とすのを防止します。
|
|
||||||
|
|
||||||
### 機能ハイライト
|
|
||||||
|
|
||||||
正規のバージョンは npm に公開された `@opengsd/gsd-core` のバージョンと `package.json` です。`docs/` の古いリリースノートは継続性の履歴として残しているだけで、現在の GSD Core パッケージバージョンではありません。
|
|
||||||
|
|
||||||
- **`--minimal` インストールプロファイル** — エイリアス `--core-only`。メインループの6スキル（`new-project`、`discuss-phase`、`plan-phase`、`execute-phase`、`help`、`update`）のみをインストールし、`gsd-*` サブエージェントはゼロ。コールドスタート時のシステムプロンプトのオーバーヘッドを ~12kトークンから ~700トークンへ削減（≥94%減）。32K〜128Kコンテキストのローカル LLM やトークン課金 API に有効。
|
|
||||||
- **`/gsd-phase --edit`** — `ROADMAP.md` 上の既存フェーズの任意フィールドをその場で編集（番号や位置は変更されない）。`--force` で確認 diff をスキップ、`depends_on` の参照を検証し、書き込み時に `STATE.md` も更新。
|
|
||||||
- **マージ後ビルド & テストゲート** — `execute-phase` のステップ 5.6 が `workflow.build_command` の設定を自動検出し、無ければ Xcode（`.xcodeproj`）、Makefile、Justfile、Cargo、Go、Python、npm の順にフォールバック。Xcode/iOS プロジェクトでは `xcodebuild build` と `xcodebuild test` を自動実行。並列・直列両モードで動作。
|
|
||||||
- **ランタイム別レビューモデル選択** — `review.models.<cli>` で各外部レビュー CLI（codex、gemini など）が使うモデルをプランナー/実行プロファイルとは独立に指定可能。
|
|
||||||
- **ワークストリーム設定の継承** — `GSD_WORKSTREAM` が設定されている場合、ルートの `.planning/config.json` を先に読み込み、ワークストリーム設定をディープマージ（衝突時はワークストリーム側が優先）。ワークストリーム設定で明示的に `null` を指定するとルート値を上書き可能。
|
|
||||||
- **スキルの統合：86 → 59** — 4つの新しいグループ化スキル（`capture`、`phase`、`config`、`workspace`）が31のマイクロスキルを吸収。既存の親スキル6つはラップアップやサブ操作をフラグ化：`update --sync/--reapply`、`sketch --wrap-up`、`spike --wrap-up`、`map-codebase --fast/--query`、`code-review --fix`、`progress --do/--next`。機能の欠損なし。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## はじめに
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx @opengsd/gsd-core@latest
|
npx @opengsd/gsd-core@latest
|
||||||
```
|
```
|
||||||
|
|
||||||
インストーラーが以下の選択を求めます：
|
インストーラーはランタイム（Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf など）とグローバルインストールかローカルインストールかを尋ねます。クロスランタイム互換性のためにインストーラーが必要です。`agents/` や `commands/` からファイルを直接コピーしないでください。
|
||||||
1. **ランタイム** — Claude Code、OpenCode、Gemini、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、Cline、またはすべて（インタラクティブ複数選択 — 1回のインストールセッションで複数のランタイムを選択可能）
|
|
||||||
2. **インストール先** — グローバル（全プロジェクト）またはローカル（現在のプロジェクトのみ）
|
|
||||||
|
|
||||||
確認方法：
|
別のランタイムをお使いの場合や Node.js がない場合は [ランタイムへのインストール](docs/ja-JP/how-to/install-on-your-runtime.md) を参照してください。
|
||||||
- Claude Code / Gemini / Copilot / Antigravity: `/gsd-help`
|
|
||||||
- OpenCode / Kilo / Augment / Trae: `/gsd-help`
|
|
||||||
- Codex: `$gsd-help`
|
|
||||||
- Cline: GSDは`.clinerules`経由でインストール — `.clinerules`の存在を確認
|
|
||||||
|
|
||||||
> [!NOTE]
|
インストール後、最初のプロジェクトを開始します。
|
||||||
> Claude Code 2.1.88+とCodexはスキル（`skills/gsd-*/SKILL.md`）としてインストールされます。Clineは`.clinerules`を使用します。インストーラーがすべての形式を自動的に処理します。
|
|
||||||
|
|
||||||
> [!TIP]
|
|
||||||
> ソースベースのインストールやnpmが利用できない環境については、**[docs/manual-update.md](docs/manual-update.md)**を参照してください。
|
|
||||||
|
|
||||||
### 最新の状態を保つ
|
|
||||||
|
|
||||||
GSDは急速に進化しています。定期的にアップデートしてください：
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary><strong>非インタラクティブインストール（Docker、CI、スクリプト）</strong></summary>
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Claude Code
|
|
||||||
npx @opengsd/gsd-core --claude --global # ~/.claude/ にインストール
|
|
||||||
npx @opengsd/gsd-core --claude --local # ./.claude/ にインストール
|
|
||||||
|
|
||||||
# OpenCode
|
|
||||||
npx @opengsd/gsd-core --opencode --global # ~/.config/opencode/ にインストール
|
|
||||||
|
|
||||||
# Gemini CLI
|
|
||||||
npx @opengsd/gsd-core --gemini --global # ~/.gemini/ にインストール
|
|
||||||
|
|
||||||
# Kilo
|
|
||||||
npx @opengsd/gsd-core --kilo --global # ~/.config/kilo/ にインストール
|
|
||||||
npx @opengsd/gsd-core --kilo --local # ./.kilo/ にインストール
|
|
||||||
|
|
||||||
# Codex
|
|
||||||
npx @opengsd/gsd-core --codex --global # ~/.codex/ にインストール
|
|
||||||
npx @opengsd/gsd-core --codex --local # ./.codex/ にインストール
|
|
||||||
|
|
||||||
# Copilot
|
|
||||||
npx @opengsd/gsd-core --copilot --global # ~/.github/ にインストール
|
|
||||||
npx @opengsd/gsd-core --copilot --local # ./.github/ にインストール
|
|
||||||
|
|
||||||
# Cursor CLI
|
|
||||||
npx @opengsd/gsd-core --cursor --global # ~/.cursor/ にインストール
|
|
||||||
npx @opengsd/gsd-core --cursor --local # ./.cursor/ にインストール
|
|
||||||
|
|
||||||
# Antigravity
|
|
||||||
npx @opengsd/gsd-core --antigravity --global # ~/.gemini/antigravity/ にインストール
|
|
||||||
npx @opengsd/gsd-core --antigravity --local # ./.agent/ にインストール
|
|
||||||
|
|
||||||
# Augment
|
|
||||||
npx @opengsd/gsd-core --augment --global # ~/.augment/ にインストール
|
|
||||||
npx @opengsd/gsd-core --augment --local # ./.augment/ にインストール
|
|
||||||
|
|
||||||
# Trae
|
|
||||||
npx @opengsd/gsd-core --trae --global # ~/.trae/ にインストール
|
|
||||||
npx @opengsd/gsd-core --trae --local # ./.trae/ にインストール
|
|
||||||
|
|
||||||
# Cline
|
|
||||||
npx @opengsd/gsd-core --cline --global # ~/.cline/ にインストール
|
|
||||||
npx @opengsd/gsd-core --cline --local # ./.clinerules にインストール
|
|
||||||
|
|
||||||
# 全ランタイム
|
|
||||||
npx @opengsd/gsd-core --all --global # すべてのディレクトリにインストール
|
|
||||||
```
|
|
||||||
|
|
||||||
`--global`（`-g`）または `--local`（`-l`）でインストール先の質問をスキップできます。
|
|
||||||
`--claude`、`--opencode`、`--gemini`、`--kilo`、`--codex`、`--copilot`、`--cursor`、`--windsurf`、`--antigravity`、`--augment`、`--trae`、`--cline`、または `--all` でランタイムの質問をスキップできます。
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary><strong>開発用インストール</strong></summary>
|
|
||||||
|
|
||||||
リポジトリをクローンしてインストーラーをローカルで実行します：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone https://github.com/open-gsd/gsd-core.git
|
|
||||||
cd gsd-core
|
|
||||||
node bin/install.js --claude --local
|
|
||||||
```
|
|
||||||
|
|
||||||
コントリビュートする前に変更をテストするため、`./.claude/` にインストールされます。
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
### 推奨：パーミッションスキップモード
|
|
||||||
|
|
||||||
GSDは摩擦のない自動化のために設計されています。Claude Codeを以下のように実行してください：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
claude --dangerously-skip-permissions
|
|
||||||
```
|
|
||||||
|
|
||||||
> [!TIP]
|
|
||||||
> これがGSDの意図された使い方です — `date` や `git commit` を50回も承認するために止まっていては目的が台無しです。
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary><strong>代替案：詳細なパーミッション設定</strong></summary>
|
|
||||||
|
|
||||||
このフラグを使いたくない場合は、プロジェクトの `.claude/settings.json` に以下を追加してください：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"permissions": {
|
|
||||||
"allow": [
|
|
||||||
"Bash(date:*)",
|
|
||||||
"Bash(echo:*)",
|
|
||||||
"Bash(cat:*)",
|
|
||||||
"Bash(ls:*)",
|
|
||||||
"Bash(mkdir:*)",
|
|
||||||
"Bash(wc:*)",
|
|
||||||
"Bash(head:*)",
|
|
||||||
"Bash(tail:*)",
|
|
||||||
"Bash(sort:*)",
|
|
||||||
"Bash(grep:*)",
|
|
||||||
"Bash(tr:*)",
|
|
||||||
"Bash(git add:*)",
|
|
||||||
"Bash(git commit:*)",
|
|
||||||
"Bash(git status:*)",
|
|
||||||
"Bash(git log:*)",
|
|
||||||
"Bash(git diff:*)",
|
|
||||||
"Bash(git tag:*)"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 仕組み
|
|
||||||
|
|
||||||
> **既存のコードがある場合は？** まず `/gsd-map-codebase` を実行してください。並列エージェントが起動し、スタック、アーキテクチャ、規約、懸念点を分析します。その後 `/gsd-new-project` がコードベースを把握した状態で動作し、質問は追加する内容に焦点を当て、計画時にはパターンが自動的に読み込まれます。
|
|
||||||
|
|
||||||
### 1. プロジェクトの初期化
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-new-project
|
/gsd-new-project
|
||||||
```
|
```
|
||||||
|
|
||||||
1つのコマンド、1つのフロー。システムが以下を行います：
|
初めての方は [はじめてのプロジェクト](docs/ja-JP/tutorials/your-first-project.md) で、インストールから最初のフェーズ出荷までのガイド付きチュートリアルをご覧ください。
|
||||||
|
|
||||||
1. **質問** — アイデアを完全に理解するまで質問します（目標、制約、技術的な好み、エッジケース）
|
|
||||||
2. **リサーチ** — 並列エージェントが起動しドメインを調査します（オプションですが推奨）
|
|
||||||
3. **要件定義** — v1、v2、スコープ外を抽出します
|
|
||||||
4. **ロードマップ** — 要件に紐づくフェーズを作成します
|
|
||||||
|
|
||||||
ロードマップを承認します。これでビルドの準備が整いました。
|
|
||||||
|
|
||||||
**作成されるファイル：** `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md`、`.planning/research/`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 2. フェーズの議論
|
## ドキュメント
|
||||||
|
|
||||||
```
|
**チュートリアル** — 実践で学ぶ:
|
||||||
/gsd-discuss-phase 1
|
- [はじめてのプロジェクト](docs/ja-JP/tutorials/your-first-project.md)
|
||||||
```
|
- [既存コードベースのオンボーディング](docs/ja-JP/tutorials/onboarding-an-existing-codebase.md)
|
||||||
|
|
||||||
**ここで実装の方向性を決めます。**
|
**ハウツーガイド** — タスク別レシピ:
|
||||||
|
- [ランタイムへのインストール](docs/ja-JP/how-to/install-on-your-runtime.md)
|
||||||
|
- [フェーズを計画する](docs/ja-JP/how-to/plan-a-phase.md)
|
||||||
|
- [検証と出荷](docs/ja-JP/how-to/verify-and-ship.md)
|
||||||
|
- … [すべてのハウツーガイドを見る](docs/ja-JP/README.md#how-to-guides)
|
||||||
|
|
||||||
ロードマップには各フェーズにつき1〜2文しかありません。あなたが*想像する*通りに構築するには十分なコンテキストではありません。このステップでは、リサーチや計画の前にあなたの好みを記録します。
|
**リファレンス** — 信頼できる情報:
|
||||||
|
- [コマンド](docs/ja-JP/COMMANDS.md)
|
||||||
|
- [設定](docs/ja-JP/CONFIGURATION.md)
|
||||||
|
- [CLI ツール](docs/ja-JP/CLI-TOOLS.md)
|
||||||
|
|
||||||
システムがフェーズを分析し、構築内容に基づいてグレーゾーンを特定します：
|
**解説** — コンセプトと設計上の決定:
|
||||||
|
- [コンテキストエンジニアリング](docs/ja-JP/explanation/context-engineering.md)
|
||||||
|
- [フェーズループ](docs/ja-JP/explanation/the-phase-loop.md)
|
||||||
|
- [アーキテクチャ](docs/ja-JP/ARCHITECTURE.md)
|
||||||
|
|
||||||
- **ビジュアル機能** → レイアウト、密度、インタラクション、空状態
|
全インデックス: [docs/ja-JP/README.md](docs/ja-JP/README.md)。他の言語: [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md)。
|
||||||
- **API/CLI** → レスポンス形式、フラグ、エラーハンドリング、詳細度
|
|
||||||
- **コンテンツシステム** → 構造、トーン、深さ、フロー
|
|
||||||
- **整理タスク** → グルーピング基準、命名、重複、例外
|
|
||||||
|
|
||||||
選択した各領域について、あなたが満足するまで質問します。出力される `CONTEXT.md` は、次の2つのステップに直接反映されます：
|
|
||||||
|
|
||||||
1. **リサーチャーが読む** — どんなパターンを調査すべきかを把握（「ユーザーはカードレイアウトを希望」→ カードコンポーネントライブラリを調査）
|
|
||||||
2. **プランナーが読む** — どの決定が確定済みかを把握（「無限スクロールに決定」→ スクロール処理を計画に含める）
|
|
||||||
|
|
||||||
ここで深く掘り下げるほど、システムはあなたが本当に望むものを構築します。スキップすれば妥当なデフォルトが使われます。活用すれば*あなたのビジョン*が反映されます。
|
|
||||||
|
|
||||||
**作成されるファイル：** `{phase_num}-CONTEXT.md`
|
|
||||||
|
|
||||||
> **前提モード：** 質問よりもコードベース分析を優先したい場合は、`/gsd-settings` で `workflow.discuss_mode` を `assumptions` に設定してください。システムがコードを読み、何をなぜそうするかを提示し、間違っている部分だけ修正を求めます。詳しくは[ディスカスモード](docs/ja-JP/workflow-discuss-mode.md)をご覧ください。
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 3. フェーズの計画
|
## なぜ機能するのか
|
||||||
|
|
||||||
```
|
多くの AI コーディング環境は、コンテキストの膨張が出力品質を静かに低下させ、セッション間に共有メモリがなく、コードが実際に動作するかを検証するものがないため、大規模では失敗します。GSD Core はこの 3 つすべてを解決します。重い作業は新鮮なサブエージェントで実行され、`STATE.md` や `CONTEXT.md` などの構造化アーティファクトがセッション境界を越えて保存され、検証ステップが構築されたものを確認してフェーズを完了と宣言する前に修正計画を生成します。詳細な理由については [docs/ja-JP/explanation/context-engineering.md](docs/ja-JP/explanation/context-engineering.md) を参照してください。
|
||||||
/gsd-plan-phase 1
|
|
||||||
```
|
|
||||||
|
|
||||||
システムが以下を行います：
|
トラブルシューティングは [docs/ja-JP/how-to/recover-and-troubleshoot.md](docs/ja-JP/how-to/recover-and-troubleshoot.md) を参照してください。
|
||||||
|
|
||||||
1. **リサーチ** — CONTEXT.mdの決定事項をもとに、このフェーズの実装方法を調査します
|
|
||||||
2. **計画** — XML構造で2〜3個のアトミックなタスクプランを作成します
|
|
||||||
3. **検証** — プランを要件と照合し、合格するまでループします
|
|
||||||
|
|
||||||
各プランは新しいコンテキストウィンドウで実行できるほど小さくなっています。品質の劣化も「もっと簡潔にしますね」もありません。
|
|
||||||
|
|
||||||
**作成されるファイル：** `{phase_num}-RESEARCH.md`、`{phase_num}-{N}-PLAN.md`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 4. フェーズの実行
|
## コミュニティ
|
||||||
|
|
||||||
```
|
| プロジェクト | プラットフォーム |
|
||||||
/gsd-execute-phase 1
|
|---------|----------|
|
||||||
```
|
| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | オリジナル OpenCode ポート |
|
||||||
|
| [Discord](https://discord.gg/mYgfVNfA2r) | コミュニティサポート |
|
||||||
システムが以下を行います：
|
|
||||||
|
|
||||||
1. **ウェーブでプランを実行** — 可能な限り並列、依存関係がある場合は逐次
|
|
||||||
2. **プランごとにフレッシュなコンテキスト** — 実装に200kトークンをフル活用、蓄積されたゴミはゼロ
|
|
||||||
3. **タスクごとにコミット** — 各タスクが独自のアトミックコミットを取得
|
|
||||||
4. **目標に対して検証** — コードベースがフェーズの約束を果たしているか確認
|
|
||||||
|
|
||||||
席を離れて、戻ってきたらクリーンなgit履歴とともに完了した作業が待っています。
|
|
||||||
|
|
||||||
**ウェーブ実行の仕組み：**
|
|
||||||
|
|
||||||
プランは依存関係に基づいて「ウェーブ」にグループ化されます。各ウェーブ内のプランは並列実行されます。ウェーブは逐次実行されます。
|
|
||||||
|
|
||||||
```
|
|
||||||
┌────────────────────────────────────────────────────────────────────┐
|
|
||||||
│ PHASE EXECUTION │
|
|
||||||
├────────────────────────────────────────────────────────────────────┤
|
|
||||||
│ │
|
|
||||||
│ WAVE 1 (parallel) WAVE 2 (parallel) WAVE 3 │
|
|
||||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
|
||||||
│ │ Plan 01 │ │ Plan 02 │ → │ Plan 03 │ │ Plan 04 │ → │ Plan 05 │ │
|
|
||||||
│ │ │ │ │ │ │ │ │ │ │ │
|
|
||||||
│ │ User │ │ Product │ │ Orders │ │ Cart │ │ Checkout│ │
|
|
||||||
│ │ Model │ │ Model │ │ API │ │ API │ │ UI │ │
|
|
||||||
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
|
|
||||||
│ │ │ ↑ ↑ ↑ │
|
|
||||||
│ └───────────┴──────────────┴───────────┘ │ │
|
|
||||||
│ Dependencies: Plan 03 needs Plan 01 │ │
|
|
||||||
│ Plan 04 needs Plan 02 │ │
|
|
||||||
│ Plan 05 needs Plans 03 + 04 │ │
|
|
||||||
│ │
|
|
||||||
└────────────────────────────────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
**ウェーブが重要な理由：**
|
|
||||||
- 独立したプラン → 同じウェーブ → 並列実行
|
|
||||||
- 依存するプラン → 後のウェーブ → 依存関係を待つ
|
|
||||||
- ファイル競合 → 逐次プランまたは同一プラン内
|
|
||||||
|
|
||||||
これが「バーティカルスライス」（Plan 01: ユーザー機能をエンドツーエンド）が「ホリゾンタルレイヤー」（Plan 01: 全モデル、Plan 02: 全API）より並列化に適している理由です。
|
|
||||||
|
|
||||||
**作成されるファイル：** `{phase_num}-{N}-SUMMARY.md`、`{phase_num}-VERIFICATION.md`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 5. 作業の検証
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-verify-work 1
|
|
||||||
```
|
|
||||||
|
|
||||||
**ここで実際に動作するか確認します。**
|
|
||||||
|
|
||||||
自動検証はコードの存在とテストの合格を確認します。しかし、その機能は*期待通りに*動作していますか？ここはあなたが実際に使ってみる場です。
|
|
||||||
|
|
||||||
システムが以下を行います：
|
|
||||||
|
|
||||||
1. **テスト可能な成果物を抽出** — 今できるようになっているはずのこと
|
|
||||||
2. **1つずつ案内** — 「メールでログインできますか？」はい/いいえ、または何が問題かを説明
|
|
||||||
3. **障害を自動診断** — デバッグエージェントが起動し根本原因を特定
|
|
||||||
4. **検証済みの修正プランを作成** — 即座に再実行可能
|
|
||||||
|
|
||||||
すべてパスすれば次に進みます。何か壊れていれば、手動でデバッグする必要はありません — 作成された修正プランで `/gsd-execute-phase` を再度実行するだけです。
|
|
||||||
|
|
||||||
**作成されるファイル：** `{phase_num}-UAT.md`、問題が見つかった場合は修正プラン
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 6. 繰り返し → シップ → 完了 → 次のマイルストーン
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-discuss-phase 2
|
|
||||||
/gsd-plan-phase 2
|
|
||||||
/gsd-execute-phase 2
|
|
||||||
/gsd-verify-work 2
|
|
||||||
/gsd-ship 2 # 検証済みの作業からPRを作成
|
|
||||||
...
|
|
||||||
/gsd-complete-milestone
|
|
||||||
/gsd-new-milestone
|
|
||||||
```
|
|
||||||
|
|
||||||
またはGSDに次のステップを自動判定させます：
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-progress --next # 次のステップを自動検出して実行
|
|
||||||
```
|
|
||||||
|
|
||||||
**discuss → plan → execute → verify → ship** のループをマイルストーン完了まで繰り返します。
|
|
||||||
|
|
||||||
ディスカッション中のインプットを速くしたい場合は、`/gsd-discuss-phase <n> --batch` で1つずつではなく小さなグループにまとめた質問に一括で回答できます。`--chain` を使うと、ディスカッションからプラン+実行まで途中で止まらずに自動チェインできます。
|
|
||||||
|
|
||||||
各フェーズであなたのインプット（discuss）、適切なリサーチ（plan）、クリーンな実行（execute）、人間による検証（verify）が行われます。コンテキストは常にフレッシュ。品質は常に高い。
|
|
||||||
|
|
||||||
すべてのフェーズが完了したら、`/gsd-complete-milestone` でマイルストーンをアーカイブしリリースをタグ付けします。
|
|
||||||
|
|
||||||
次に `/gsd-new-milestone` で次のバージョンを開始します — `new-project` と同じフローですが既存のコードベース向けです。次に構築したいものを説明し、システムがドメインを調査し、要件をスコーピングし、新しいロードマップを作成します。各マイルストーンはクリーンなサイクルです：定義 → 構築 → シップ。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### クイックモード
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-quick
|
|
||||||
```
|
|
||||||
|
|
||||||
**フル計画が不要なアドホックタスク向け。**
|
|
||||||
|
|
||||||
クイックモードはGSDの保証（アトミックコミット、状態トラッキング）をより速いパスで提供します：
|
|
||||||
|
|
||||||
- **同じエージェント** — プランナー + エグゼキューター、同じ品質
|
|
||||||
- **オプションステップをスキップ** — デフォルトではリサーチ、プランチェッカー、ベリファイアなし
|
|
||||||
- **別トラッキング** — `.planning/quick/` に保存、フェーズとは別管理
|
|
||||||
|
|
||||||
**`--discuss` フラグ：** 計画前にグレーゾーンを洗い出す軽量ディスカッション。
|
|
||||||
|
|
||||||
**`--research` フラグ：** 計画前にフォーカスされたリサーチャーを起動。実装アプローチ、ライブラリの選択肢、落とし穴を調査します。タスクへのアプローチが不明な場合に使用してください。
|
|
||||||
|
|
||||||
**`--full` フラグ：** 全フェーズを有効化 — ディスカッション + リサーチ + プランチェック + 検証。クイックタスク形式のフルGSDパイプライン。
|
|
||||||
|
|
||||||
**`--validate` フラグ：** プランチェック + 実行後の検証のみを有効化（以前の `--full` の動作）。
|
|
||||||
|
|
||||||
フラグは組み合わせ可能：`--discuss --research --validate` でディスカッション + リサーチ + プランチェック + 検証が行われます。
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-quick
|
|
||||||
> What do you want to do? "Add dark mode toggle to settings"
|
|
||||||
```
|
|
||||||
|
|
||||||
**作成されるファイル：** `.planning/quick/001-add-dark-mode-toggle/PLAN.md`、`SUMMARY.md`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## なぜ効果的なのか
|
|
||||||
|
|
||||||
### コンテキストエンジニアリング
|
|
||||||
|
|
||||||
Claude Codeは必要なコンテキストを与えれば非常に強力です。ほとんどの人はそれをしていません。
|
|
||||||
|
|
||||||
GSDがそれを代わりに処理します：
|
|
||||||
|
|
||||||
| ファイル | 役割 |
|
|
||||||
|------|--------------|
|
|
||||||
| `PROJECT.md` | プロジェクトビジョン、常に読み込まれる |
|
|
||||||
| `research/` | エコシステムの知識（スタック、機能、アーキテクチャ、落とし穴） |
|
|
||||||
| `REQUIREMENTS.md` | フェーズとのトレーサビリティを持つスコープ済みv1/v2要件 |
|
|
||||||
| `ROADMAP.md` | 進む方向、完了済みの作業 |
|
|
||||||
| `STATE.md` | 決定事項、ブロッカー、現在地 — セッション間のメモリ |
|
|
||||||
| `PLAN.md` | XML構造のアトミックタスク、検証ステップ付き |
|
|
||||||
| `SUMMARY.md` | 何が起きたか、何が変わったか、履歴にコミット |
|
|
||||||
| `todos/` | 後で取り組むアイデアやタスクのキャプチャ |
|
|
||||||
| `threads/` | セッションをまたぐ作業のための永続コンテキストスレッド |
|
|
||||||
| `seeds/` | 適切なマイルストーンで浮上する将来志向のアイデア |
|
|
||||||
|
|
||||||
サイズ制限はClaudeの品質が劣化するポイントに基づいています。制限内に収まれば、一貫した高品質が得られます。
|
|
||||||
|
|
||||||
### XMLプロンプトフォーマッティング
|
|
||||||
|
|
||||||
すべてのプランはClaude向けに最適化された構造化XMLです：
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<task type="auto">
|
|
||||||
<name>Create login endpoint</name>
|
|
||||||
<files>src/app/api/auth/login/route.ts</files>
|
|
||||||
<action>
|
|
||||||
<!-- CommonJSの問題があるため、jsonwebtokenではなくjoseをJWTに使用。 -->
|
|
||||||
<!-- usersテーブルに対して認証情報を検証。 -->
|
|
||||||
<!-- 成功時にhttpOnly cookieを返す。 -->
|
|
||||||
Use jose for JWT (not jsonwebtoken - CommonJS issues).
|
|
||||||
Validate credentials against users table.
|
|
||||||
Return httpOnly cookie on success.
|
|
||||||
</action>
|
|
||||||
<verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
|
|
||||||
<done>Valid credentials return cookie, invalid return 401</done>
|
|
||||||
</task>
|
|
||||||
```
|
|
||||||
|
|
||||||
正確な指示。推測なし。検証が組み込み済み。
|
|
||||||
|
|
||||||
### マルチエージェントオーケストレーション
|
|
||||||
|
|
||||||
すべてのステージで同じパターンを使用します：薄いオーケストレーターが専門エージェントを起動し、結果を収集し、次のステップにルーティングします。
|
|
||||||
|
|
||||||
| ステージ | オーケストレーターの役割 | エージェントの役割 |
|
|
||||||
|-------|------------------|-----------|
|
|
||||||
| リサーチ | 調整し、発見事項を提示 | 4つの並列リサーチャーがスタック、機能、アーキテクチャ、落とし穴を調査 |
|
|
||||||
| プランニング | 検証し、イテレーションを管理 | プランナーがプランを作成、チェッカーが検証、合格するまでループ |
|
|
||||||
| 実行 | ウェーブにグループ化し、進捗を追跡 | エグゼキューターがフレッシュな200kコンテキストで並列実装 |
|
|
||||||
| 検証 | 結果を提示し、次にルーティング | ベリファイアがコードベースを目標と照合、デバッガーが障害を診断 |
|
|
||||||
|
|
||||||
オーケストレーターは重い処理を行いません。エージェントを起動し、待機し、結果を統合します。
|
|
||||||
|
|
||||||
**結果：** フェーズ全体を実行できます — 深いリサーチ、複数のプランの作成と検証、並列エグゼキューターによる数千行のコード記述、目標に対する自動検証 — そしてメインのコンテキストウィンドウは30〜40%に留まります。処理はフレッシュなサブエージェントコンテキストで行われます。セッションは高速でレスポンシブなままです。
|
|
||||||
|
|
||||||
### アトミックGitコミット
|
|
||||||
|
|
||||||
各タスクは完了直後に独自のコミットを取得します：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
abc123f docs(08-02): complete user registration plan
|
|
||||||
def456g feat(08-02): add email confirmation flow
|
|
||||||
hij789k feat(08-02): implement password hashing
|
|
||||||
lmn012o feat(08-02): create registration endpoint
|
|
||||||
```
|
|
||||||
|
|
||||||
> [!NOTE]
|
|
||||||
> **メリット：** git bisectで問題のある正確なタスクを特定可能。各タスクを個別にリバート可能。将来のセッションでClaudeに明確な履歴を提供。AI自動化ワークフローにおけるオブザーバビリティの向上。
|
|
||||||
|
|
||||||
すべてのコミットは的確で、追跡可能で、意味があります。
|
|
||||||
|
|
||||||
### モジュラー設計
|
|
||||||
|
|
||||||
- 現在のマイルストーンにフェーズを追加
|
|
||||||
- フェーズ間に緊急作業を挿入
|
|
||||||
- マイルストーンを完了して新しく開始
|
|
||||||
- すべてを再構築せずにプランを調整
|
|
||||||
|
|
||||||
ロックインされることはありません。システムが適応します。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## コマンド
|
|
||||||
|
|
||||||
### コアワークフロー
|
|
||||||
|
|
||||||
| コマンド | 説明 |
|
|
||||||
|---------|--------------|
|
|
||||||
| `/gsd-new-project [--auto]` | フル初期化：質問 → リサーチ → 要件定義 → ロードマップ |
|
|
||||||
| `/gsd-discuss-phase [N] [--auto] [--analyze] [--chain]` | 計画前に実装の決定事項をキャプチャ（`--analyze` でトレードオフ分析を追加、`--chain` でプラン+実行へ自動チェイン） |
|
|
||||||
| `/gsd-plan-phase [N] [--auto] [--reviews]` | フェーズのリサーチ + プラン + 検証（`--reviews` でコードベースレビューの発見事項を読み込み） |
|
|
||||||
| `/gsd-execute-phase <N>` | 全プランを並列ウェーブで実行し、完了時に検証 |
|
|
||||||
| `/gsd-verify-work [N]` | 手動ユーザー受入テスト ¹ |
|
|
||||||
| `/gsd-ship [N] [--draft]` | 検証済みのフェーズ作業から自動生成された本文付きのPRを作成 |
|
|
||||||
| `/gsd-progress --next` | 次の論理的なワークフローステップに自動的に進む |
|
|
||||||
| `/gsd-fast <text>` | インラインの軽微タスク — 計画を完全にスキップし即座に実行 |
|
|
||||||
| `/gsd-audit-milestone` | マイルストーンが完了の定義を達成したか検証 |
|
|
||||||
| `/gsd-complete-milestone` | マイルストーンをアーカイブし、リリースをタグ付け |
|
|
||||||
| `/gsd-new-milestone [name]` | 次のバージョンを開始：質問 → リサーチ → 要件定義 → ロードマップ |
|
|
||||||
| `/gsd-forensics [desc]` | 失敗したワークフロー実行の事後分析（停止ループ、欠落成果物、git異常の診断） |
|
|
||||||
| `/gsd-milestone-summary [version]` | チームオンボーディングとレビュー向けの包括的なプロジェクトサマリーを生成 |
|
|
||||||
|
|
||||||
### ワークストリーム
|
|
||||||
|
|
||||||
| コマンド | 説明 |
|
|
||||||
|---------|--------------|
|
|
||||||
| `/gsd-workstreams list` | 全ワークストリームとそのステータスを表示 |
|
|
||||||
| `/gsd-workstreams create <name>` | 並列マイルストーン作業用の名前空間付きワークストリームを作成 |
|
|
||||||
| `/gsd-workstreams switch <name>` | アクティブなワークストリームを切り替え |
|
|
||||||
| `/gsd-workstreams complete <name>` | ワークストリームを完了しマージ |
|
|
||||||
|
|
||||||
### マルチプロジェクトワークスペース
|
|
||||||
|
|
||||||
| コマンド | 説明 |
|
|
||||||
|---------|--------------|
|
|
||||||
| `/gsd-workspace --new` | リポジトリのコピー（worktreeまたはクローン）で隔離されたワークスペースを作成 |
|
|
||||||
| `/gsd-workspace --list` | すべてのGSDワークスペースとそのステータスを表示 |
|
|
||||||
| `/gsd-workspace --remove` | ワークスペースを削除しworktreeをクリーンアップ |
|
|
||||||
|
|
||||||
### UIデザイン
|
|
||||||
|
|
||||||
| コマンド | 説明 |
|
|
||||||
|---------|--------------|
|
|
||||||
| `/gsd-ui-phase [N]` | フロントエンドフェーズ用のUIデザイン契約（UI-SPEC.md）を生成 |
|
|
||||||
| `/gsd-ui-review [N]` | 実装済みフロントエンドコードの6つの柱によるビジュアル監査（遡及的） |
|
|
||||||
|
|
||||||
### ナビゲーション
|
|
||||||
|
|
||||||
| コマンド | 説明 |
|
|
||||||
|---------|--------------|
|
|
||||||
| `/gsd-progress` | 今どこにいる？次は何？ |
|
|
||||||
| `/gsd-progress --next` | 状態を自動検出し次のステップを実行 |
|
|
||||||
| `/gsd-help` | 全コマンドと使い方ガイドを表示 |
|
|
||||||
| `/gsd-update` | チェンジログプレビュー付きでGSDをアップデート |
|
|
||||||
| `/gsd-manager` | 複数フェーズ管理用のインタラクティブコマンドセンター |
|
|
||||||
|
|
||||||
### ブラウンフィールド
|
|
||||||
|
|
||||||
| コマンド | 説明 |
|
|
||||||
|---------|--------------|
|
|
||||||
| `/gsd-map-codebase [area]` | new-project前に既存のコードベースを分析 |
|
|
||||||
|
|
||||||
### フェーズ管理
|
|
||||||
|
|
||||||
| コマンド | 説明 |
|
|
||||||
|---------|--------------|
|
|
||||||
| `/gsd-phase` | ロードマップにフェーズを追加 |
|
|
||||||
| `/gsd-phase --insert [N]` | フェーズ間に緊急作業を挿入 |
|
|
||||||
| `/gsd-phase --edit [N] [--force]` | 既存フェーズの任意フィールドをその場で編集 — 番号と位置は変更されない |
|
|
||||||
| `/gsd-phase --remove [N]` | 将来のフェーズを削除し番号を振り直し |
|
|
||||||
| `/gsd-discuss-phase --assumptions [N]` | 計画前にClaudeの意図するアプローチを確認 |
|
|
||||||
| `/gsd-audit-milestone --fix` | 監査で見つかったギャップを埋めるフェーズを作成 |
|
|
||||||
|
|
||||||
### セッション
|
|
||||||
|
|
||||||
| コマンド | 説明 |
|
|
||||||
|---------|--------------|
|
|
||||||
| `/gsd-pause-work` | フェーズ途中で停止する際の引き継ぎを作成（HANDOFF.jsonを書き込み） |
|
|
||||||
| `/gsd-resume-work` | 前回のセッションから復元 |
|
|
||||||
| `/gsd-pause-work --report` | 実行した作業と結果のセッションサマリーを生成 |
|
|
||||||
|
|
||||||
### ワークストリーム
|
|
||||||
|
|
||||||
| コマンド | 説明 |
|
|
||||||
|---------|--------------|
|
|
||||||
| `/gsd-workstreams` | 並列ワークストリームを管理（list、create、switch、status、progress、complete） |
|
|
||||||
|
|
||||||
### コード品質
|
|
||||||
|
|
||||||
| コマンド | 説明 |
|
|
||||||
|---------|--------------|
|
|
||||||
| `/gsd-review` | 現在のフェーズまたはブランチのクロスAIピアレビュー |
|
|
||||||
| `/gsd-pr-branch` | `.planning/` コミットをフィルタリングしたクリーンなPRブランチを作成 |
|
|
||||||
| `/gsd-audit-uat` | 検証負債を監査 — UATが未実施のフェーズを検出 |
|
|
||||||
|
|
||||||
### バックログ & スレッド
|
|
||||||
|
|
||||||
| コマンド | 説明 |
|
|
||||||
|---------|--------------|
|
|
||||||
| `/gsd-capture --seed <idea>` | トリガー条件付きの将来志向のアイデアをキャプチャ — 適切なマイルストーンで浮上 |
|
|
||||||
| `/gsd-capture --backlog <desc>` | バックログのパーキングロットにアイデアを追加（999.xナンバリング、アクティブシーケンス外） |
|
|
||||||
| `/gsd-review-backlog` | バックログ項目をレビューし、アクティブマイルストーンに昇格またはstaleエントリを削除 |
|
|
||||||
| `/gsd-thread [name]` | 永続コンテキストスレッド — 複数セッションにまたがる作業用の軽量クロスセッション知識 |
|
|
||||||
|
|
||||||
### ユーティリティ
|
|
||||||
|
|
||||||
| コマンド | 説明 |
|
|
||||||
|---------|--------------|
|
|
||||||
| `/gsd-settings` | モデルプロファイルとワークフローエージェントを設定 |
|
|
||||||
| `/gsd-config --profile <profile>` | モデルプロファイルを切り替え（quality/balanced/budget/inherit） |
|
|
||||||
| `/gsd-capture [desc]` | 後で取り組むアイデアをキャプチャ |
|
|
||||||
| `/gsd-capture --list` | 保留中のtodoを一覧表示 |
|
|
||||||
| `/gsd-debug [desc]` | 永続状態を持つ体系的デバッグ |
|
|
||||||
| `/gsd-do <text>` | フリーフォームテキストを適切なGSDコマンドに自動ルーティング |
|
|
||||||
| `/gsd-note <text>` | ゼロフリクションのアイデアキャプチャ — ノートの追加、一覧、todoへの昇格 |
|
|
||||||
| `/gsd-quick [--full] [--discuss] [--research]` | GSDの保証付きでアドホックタスクを実行（`--full` で全フェーズを有効化、`--discuss` で事前にコンテキストを収集、`--research` で計画前にアプローチを調査） |
|
|
||||||
| `/gsd-health [--repair]` | `.planning/` ディレクトリの整合性を検証、`--repair` で自動修復 |
|
|
||||||
| `/gsd-stats` | プロジェクト統計を表示 — フェーズ、プラン、要件、gitメトリクス |
|
|
||||||
| `/gsd-profile-user [--questionnaire] [--refresh]` | セッション分析から開発者行動プロファイルを生成し、パーソナライズされた応答を提供 |
|
|
||||||
|
|
||||||
<sup>¹ Redditユーザー OracleGreyBeard による貢献</sup>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 設定
|
|
||||||
|
|
||||||
GSDはプロジェクト設定を `.planning/config.json` に保存します。`/gsd-new-project` 実行時に設定するか、後から `/gsd-settings` で更新できます。完全な設定スキーマ、ワークフロートグル、gitブランチオプション、エージェントごとのモデル内訳については、[ユーザーガイド](docs/ja-JP/USER-GUIDE.md#configuration-reference)をご覧ください。
|
|
||||||
|
|
||||||
### コア設定
|
|
||||||
|
|
||||||
| 設定 | オプション | デフォルト | 制御内容 |
|
|
||||||
|---------|---------|---------|------------------|
|
|
||||||
| `mode` | `yolo`, `interactive` | `interactive` | 自動承認 vs 各ステップで確認 |
|
|
||||||
| `granularity` | `coarse`, `standard`, `fine` | `standard` | フェーズの粒度 — スコープをどれだけ細かく分割するか（フェーズ × プラン） |
|
|
||||||
|
|
||||||
### モデルプロファイル
|
|
||||||
|
|
||||||
各エージェントが使用するClaudeモデルを制御します。品質とトークン消費のバランスを取ります。
|
|
||||||
|
|
||||||
| プロファイル | プランニング | 実行 | 検証 |
|
|
||||||
|---------|----------|-----------|--------------|
|
|
||||||
| `quality` | Opus | Opus | Sonnet |
|
|
||||||
| `balanced`（デフォルト） | Opus | Sonnet | Sonnet |
|
|
||||||
| `budget` | Sonnet | Sonnet | Haiku |
|
|
||||||
| `inherit` | Inherit | Inherit | Inherit |
|
|
||||||
|
|
||||||
プロファイルの切り替え：
|
|
||||||
```
|
|
||||||
/gsd-config --profile budget
|
|
||||||
```
|
|
||||||
|
|
||||||
非Anthropicプロバイダー（OpenRouter、ローカルモデル）を使用する場合や、現在のランタイムのモデル選択に従う場合（例：OpenCode `/model`）は `inherit` を使用してください。
|
|
||||||
|
|
||||||
または `/gsd-settings` で設定できます。
|
|
||||||
|
|
||||||
### ワークフローエージェント
|
|
||||||
|
|
||||||
プランニング/実行時に追加のエージェントを起動します。品質は向上しますが、トークンと時間が追加されます。
|
|
||||||
|
|
||||||
| 設定 | デフォルト | 説明 |
|
|
||||||
|---------|---------|--------------|
|
|
||||||
| `workflow.research` | `true` | 各フェーズの計画前にドメインを調査 |
|
|
||||||
| `workflow.plan_check` | `true` | 実行前にプランがフェーズ目標を達成しているか検証 |
|
|
||||||
| `workflow.verifier` | `true` | 実行後に必須項目が提供されたか確認 |
|
|
||||||
| `workflow.auto_advance` | `false` | discuss → plan → execute を停止せずに自動チェーン |
|
|
||||||
| `workflow.research_before_questions` | `false` | ディスカッション質問の後ではなく前にリサーチを実行 |
|
|
||||||
| `workflow.discuss_mode` | `'discuss'` | ディスカッションモード：`discuss`（インタビュー）、`assumptions`（コードベースファースト） |
|
|
||||||
| `workflow.skip_discuss` | `false` | 自律モードでdiscuss-phaseをスキップ |
|
|
||||||
| `workflow.text_mode` | `false` | リモートセッション用のテキスト専用モード（TUIメニューなし） |
|
|
||||||
|
|
||||||
これらのトグルには `/gsd-settings` を使用するか、呼び出し時にオーバーライドできます：
|
|
||||||
- `/gsd-plan-phase --skip-research`
|
|
||||||
- `/gsd-plan-phase --skip-verify`
|
|
||||||
|
|
||||||
### 実行
|
|
||||||
|
|
||||||
| 設定 | デフォルト | 制御内容 |
|
|
||||||
|---------|---------|------------------|
|
|
||||||
| `parallelization.enabled` | `true` | 独立したプランを同時に実行 |
|
|
||||||
| `planning.commit_docs` | `true` | `.planning/` をgitで追跡 |
|
|
||||||
| `hooks.context_warnings` | `true` | コンテキストウィンドウの使用量警告を表示 |
|
|
||||||
|
|
||||||
### Gitブランチ
|
|
||||||
|
|
||||||
GSDが実行中にブランチをどう扱うかを制御します。
|
|
||||||
|
|
||||||
| 設定 | オプション | デフォルト | 説明 |
|
|
||||||
|---------|---------|---------|--------------|
|
|
||||||
| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | ブランチ作成戦略 |
|
|
||||||
| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | フェーズブランチのテンプレート |
|
|
||||||
| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | マイルストーンブランチのテンプレート |
|
|
||||||
|
|
||||||
**戦略：**
|
|
||||||
- **`none`** — 現在のブランチにコミット（デフォルトのGSD動作）
|
|
||||||
- **`phase`** — フェーズごとにブランチを作成し、フェーズ完了時にマージ
|
|
||||||
- **`milestone`** — マイルストーン全体で1つのブランチを作成し、完了時にマージ
|
|
||||||
|
|
||||||
マイルストーン完了時、GSDはスカッシュマージ（推奨）または履歴付きマージを提案します。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## セキュリティ
|
|
||||||
|
|
||||||
### 組み込みセキュリティハードニング
|
|
||||||
|
|
||||||
GSDはv1.27以降、多層防御セキュリティを備えています：
|
|
||||||
|
|
||||||
- **パストラバーサル防止** — ユーザー提供のすべてのファイルパス（`--text-file`、`--prd`）がプロジェクトディレクトリ内に解決されるか検証
|
|
||||||
- **プロンプトインジェクション検出** — 集中型 `security.cjs` モジュールが計画成果物に入る前にユーザー提供テキストのインジェクションパターンをスキャン
|
|
||||||
- **PreToolUseプロンプトガードフック** — `gsd-prompt-guard` が `.planning/` への書き込みに埋め込まれたインジェクションベクトルをスキャン（アドバイザリー、ブロッキングではない）
|
|
||||||
- **安全なJSON解析** — 不正な `--fields` 引数が状態を破損する前にキャッチ
|
|
||||||
- **シェル引数バリデーション** — シェル補間前にユーザーテキストをサニタイズ
|
|
||||||
- **CI対応インジェクションスキャナー** — `prompt-injection-scan.test.cjs` が全エージェント/ワークフロー/コマンドファイルの埋め込みインジェクションベクトルをスキャン
|
|
||||||
|
|
||||||
> [!NOTE]
|
|
||||||
> GSDはLLMシステムプロンプトとなるマークダウンファイルを生成するため、計画成果物に流入するユーザー制御テキストは潜在的な間接プロンプトインジェクションベクトルとなります。これらの保護は、そのようなベクトルを複数のレイヤーで捕捉するように設計されています。
|
|
||||||
|
|
||||||
### 機密ファイルの保護
|
|
||||||
|
|
||||||
GSDのコードベースマッピングおよび分析コマンドは、プロジェクトを理解するためにファイルを読み取ります。**シークレットを含むファイルを保護する**には、Claude Codeの拒否リストに追加してください：
|
|
||||||
|
|
||||||
1. Claude Code設定（`.claude/settings.json` またはグローバル）を開きます
|
|
||||||
2. 機密ファイルパターンを拒否リストに追加します：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"permissions": {
|
|
||||||
"deny": [
|
|
||||||
"Read(.env)",
|
|
||||||
"Read(.env.*)",
|
|
||||||
"Read(**/secrets/*)",
|
|
||||||
"Read(**/*credential*)",
|
|
||||||
"Read(**/*.pem)",
|
|
||||||
"Read(**/*.key)"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
これにより、どのコマンドを実行しても、Claudeがこれらのファイルを完全に読み取ることを防ぎます。
|
|
||||||
|
|
||||||
> [!IMPORTANT]
|
|
||||||
> GSDにはシークレットのコミットに対する組み込み保護がありますが、多層防御がベストプラクティスです。防御の第一線として、機密ファイルへの読み取りアクセスを拒否してください。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## トラブルシューティング
|
|
||||||
|
|
||||||
**インストール後にコマンドが見つからない？**
|
|
||||||
- ランタイムを再起動してコマンド/スキルを再読み込みしてください
|
|
||||||
- `~/.claude/commands/gsd/`（グローバル）または `./.claude/commands/gsd/`（ローカル）にファイルが存在するか確認してください
|
|
||||||
- Codexの場合、`~/.codex/skills/gsd-*/SKILL.md`（グローバル）または `./.codex/skills/gsd-*/SKILL.md`（ローカル）にスキルが存在するか確認してください
|
|
||||||
|
|
||||||
**コマンドが期待通りに動作しない？**
|
|
||||||
- `/gsd-help` を実行してインストールを確認してください
|
|
||||||
- `npx @opengsd/gsd-core` を再実行して再インストールしてください
|
|
||||||
|
|
||||||
**最新バージョンへのアップデート？**
|
|
||||||
```bash
|
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
**Dockerまたはコンテナ化環境を使用している？**
|
|
||||||
|
|
||||||
チルダパス（`~/.claude/...`）でファイル読み取りが失敗する場合、インストール前に `CLAUDE_CONFIG_DIR` を設定してください：
|
|
||||||
```bash
|
|
||||||
CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @opengsd/gsd-core --global
|
|
||||||
```
|
|
||||||
これにより、コンテナ内で正しく展開されない可能性がある `~` の代わりに絶対パスが使用されます。
|
|
||||||
|
|
||||||
### アンインストール
|
|
||||||
|
|
||||||
GSDを完全に削除するには：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# グローバルインストール
|
|
||||||
npx @opengsd/gsd-core --claude --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --opencode --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --gemini --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --kilo --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --codex --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --copilot --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --cursor --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --antigravity --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --trae --global --uninstall
|
|
||||||
|
|
||||||
# ローカルインストール（現在のプロジェクト）
|
|
||||||
npx @opengsd/gsd-core --claude --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --opencode --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --gemini --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --kilo --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --codex --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --copilot --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --cursor --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --antigravity --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --trae --local --uninstall
|
|
||||||
```
|
|
||||||
|
|
||||||
これにより、他の設定を保持しながら、すべてのGSDコマンド、エージェント、フック、設定が削除されます。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## コミュニティポート
|
|
||||||
|
|
||||||
OpenCode、Gemini CLI、Kilo、Codexは `npx @opengsd/gsd-core` でネイティブサポートされています。
|
|
||||||
|
|
||||||
以下のコミュニティポートがマルチランタイムサポートの先駆けとなりました：
|
|
||||||
|
|
||||||
| プロジェクト | プラットフォーム | 説明 |
|
|
||||||
|---------|----------|-------------|
|
|
||||||
| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | オリジナルのOpenCode対応版 |
|
|
||||||
| gsd-gemini（アーカイブ済み） | Gemini CLI | uberfuzzyによるオリジナルのGemini対応版 |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -860,12 +114,12 @@ OpenCode、Gemini CLI、Kilo、Codexは `npx @opengsd/gsd-core` でネイティ
|
|||||||
|
|
||||||
## ライセンス
|
## ライセンス
|
||||||
|
|
||||||
MITライセンス。詳細は [LICENSE](LICENSE) をご覧ください。
|
MIT ライセンス。詳細は [LICENSE](LICENSE) を参照してください。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
**Claude Codeは強力です。GSDはそれを信頼性の高いものにします。**
|
**Claude Code は強力です。GSD Core はそれを信頼できるものにします。**
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|||||||
837
README.ko-KR.md
837
README.ko-KR.md
@@ -1,5 +1,3 @@
|
|||||||
> ⚠️ This is an active fork. See the [English README](README.md) for the full notice about the original repo.
|
|
||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
# GSD Core
|
# GSD Core
|
||||||
@@ -8,9 +6,7 @@
|
|||||||
|
|
||||||
[English](README.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md) · **한국어**
|
[English](README.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md) · **한국어**
|
||||||
|
|
||||||
**Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Cline을 위한 가볍고 강력한 메타 프롬프팅, 컨텍스트 엔지니어링, 스펙 기반 개발 시스템.**
|
**Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf 등을 위한 경량 메타 프롬프팅, 컨텍스트 엔지니어링, 스펙 기반 개발 시스템.**
|
||||||
|
|
||||||
**컨텍스트 rot를 해결합니다 — Claude의 컨텍스트 창이 채워질수록 품질이 저하되는 문제.**
|
|
||||||
|
|
||||||
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
||||||
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
||||||
@@ -19,821 +15,88 @@
|
|||||||
[](https://github.com/open-gsd/gsd-core)
|
[](https://github.com/open-gsd/gsd-core)
|
||||||
[](LICENSE)
|
[](LICENSE)
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
**Mac, Windows, Linux 모두 지원.**
|
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
*"원하는 게 뭔지 명확하게 알고 있다면, 이게 진짜로 만들어줍니다. 과장 없이."*
|
|
||||||
|
|
||||||
*"SpecKit, OpenSpec, Taskmaster 다 써봤는데 — 지금까지 이게 제일 결과가 좋았어요."*
|
|
||||||
|
|
||||||
*"Claude Code에 추가한 것 중 단연 가장 강력합니다. 과하게 엔지니어링하지 않고, 말 그대로 그냥 해냅니다."*
|
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
**Amazon, Google, Shopify, Webflow 엔지니어들이 신뢰합니다.**
|
|
||||||
|
|
||||||
[왜 만들었나](#왜-만들었나) · [작동 방식](#작동-방식) · [명령어](#명령어) · [왜 효과적인가](#왜-효과적인가) · [사용자 가이드](docs/ko-KR/USER-GUIDE.md)
|
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 왜 만들었나
|
## GSD Core란
|
||||||
|
|
||||||
저는 솔로 개발자입니다. 코드는 제가 아니라 Claude Code가 씁니다.
|
GSD Core는 컨텍스트 엔지니어링 및 스펙 기반 개발 프레임워크로, AI 코딩 에이전트(Claude Code, Codex, Gemini CLI, Copilot, Cursor 등)를 엄격한 단계 루프로 운용합니다. AI가 컨텍스트 창을 채워 나가면서 발생하는 품질 저하인 [컨텍스트 rot](docs/ko-KR/explanation/context-engineering.md) 문제를 해결합니다. 무거운 리서치, 기획, 실행 작업은 새로운 컨텍스트의 서브에이전트에서 처리하고, 메인 세션은 가볍게 유지됩니다.
|
||||||
|
|
||||||
스펙 기반 개발 도구가 없는 건 아닙니다. BMAD, Speckit 같은 것들이 있죠. 근데 다들 필요 이상으로 복잡합니다 — 스프린트 세리머니, 스토리 포인트, 이해관계자 싱크, 회고, 지라 워크플로우. 저는 50인 규모 소프트웨어 회사가 아니에요. 기업 연극을 하고 싶지 않습니다. 그냥 좋은 걸 만들고 싶은 사람입니다.
|
|
||||||
|
|
||||||
그래서 GSD를 만들었습니다. 복잡함은 시스템 안에 있습니다. 워크플로우에 있는 게 아니라. 뒤에서 컨텍스트 엔지니어링, XML 프롬프트 포맷팅, 서브에이전트 오케스트레이션, 상태 관리가 돌아갑니다. 겉에서 보이는 건 그냥 몇 가지 명령어뿐입니다.
|
|
||||||
|
|
||||||
시스템이 Claude한테 작업하는 데 필요한 것과 검증하는 데 필요한 것을 모두 줍니다. 저는 이 워크플로우를 믿습니다. 그냥 잘 됩니다.
|
|
||||||
|
|
||||||
이게 전부입니다. 기업 역할극 같은 건 없습니다. Claude Code를 일관성 있게 쓰기 위한, 진짜로 잘 되는 시스템입니다.
|
|
||||||
|
|
||||||
— **TÂCHES**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
바이브코딩은 평판이 안 좋습니다. 원하는 걸 설명하면 AI가 코드를 생성하는데, 규모가 커지면 엉망이 되는 일관성 없는 쓰레기가 나옵니다.
|
|
||||||
|
|
||||||
GSD가 그걸 고칩니다. Claude Code를 신뢰할 수 있게 만드는 컨텍스트 엔지니어링 레이어입니다. 아이디어를 설명하면 시스템이 필요한 걸 다 뽑아내고, Claude Code가 일을 시작합니다.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 이게 누구를 위한 건가
|
|
||||||
|
|
||||||
원하는 걸 설명하면 제대로 만들어지길 바라는 사람들 — 50인 규모 엔지니어링 조직인 척하지 않아도 되는.
|
|
||||||
|
|
||||||
내장 품질 게이트가 실제 문제를 잡아냅니다: 스키마 드리프트 감지는 마이그레이션 누락된 ORM 변경을 플래그하고, 보안 강제는 검증을 위협 모델에 고정시키고, 스코프 축소 감지는 플래너가 요구사항을 몰래 빠뜨리는 걸 방지합니다.
|
|
||||||
|
|
||||||
### 기능 하이라이트
|
|
||||||
|
|
||||||
정식 버전은 npm에 게시된 `@opengsd/gsd-core` 버전과 `package.json`을 기준으로 합니다. `docs/`의 예전 릴리스 노트는 연속성 기록으로만 보관되며, 현재 GSD Core 패키지 버전으로 사용하지 않습니다.
|
|
||||||
|
|
||||||
- **`--minimal` 설치 프로파일** — 별칭 `--core-only`. 메인 루프 6개 스킬(`new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, `help`, `update`)만 설치하고 `gsd-*` 서브에이전트는 설치하지 않음. 콜드 스타트 시스템 프롬프트 오버헤드를 ~12k 토큰에서 ~700 토큰으로 축소(≥94% 감소). 32K–128K 컨텍스트의 로컬 LLM이나 토큰 과금 API에 유용.
|
|
||||||
- **`/gsd-phase --edit`** — `ROADMAP.md`에 있는 기존 단계의 임의 필드를 그 자리에서 수정(번호와 위치는 변경되지 않음). `--force`는 확인 diff를 건너뛰고, `depends_on` 참조를 검증하며 쓰기 시 `STATE.md`도 갱신.
|
|
||||||
- **머지 후 빌드 & 테스트 게이트** — `execute-phase` 5.6 단계가 `workflow.build_command` 설정을 우선 자동 감지하고, 없으면 Xcode(`.xcodeproj`), Makefile, Justfile, Cargo, Go, Python, npm 순으로 폴백. Xcode/iOS 프로젝트는 `xcodebuild build` 및 `xcodebuild test`를 자동 실행. 병렬·직렬 모드 모두에서 동작.
|
|
||||||
- **런타임별 리뷰 모델 선택** — `review.models.<cli>`로 각 외부 리뷰 CLI(codex, gemini 등)가 플래너/실행 프로파일과 독립적으로 자체 모델을 선택할 수 있음.
|
|
||||||
- **워크스트림 설정 상속** — `GSD_WORKSTREAM`이 설정되면 루트 `.planning/config.json`을 먼저 로드한 뒤 워크스트림 설정을 딥 머지(충돌 시 워크스트림 우선). 워크스트림 설정에서 명시적 `null`은 루트 값을 덮어씀.
|
|
||||||
- **스킬 통합: 86 → 59** — 4개의 새로운 그룹 스킬(`capture`, `phase`, `config`, `workspace`)이 31개의 마이크로 스킬을 흡수. 기존 6개의 부모 스킬은 래퍼업/하위 동작을 플래그로 흡수: `update --sync/--reapply`, `sketch --wrap-up`, `spike --wrap-up`, `map-codebase --fast/--query`, `code-review --fix`, `progress --do/--next`. 기능 손실 없음.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 시작하기
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
설치 중에 다음을 선택합니다:
|
|
||||||
1. **런타임** — Claude Code, OpenCode, Gemini, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Cline, 또는 전체 (대화형 다중 선택 — 한 번에 여러 런타임 선택 가능)
|
|
||||||
2. **위치** — 전역 (모든 프로젝트) 또는 로컬 (현재 프로젝트만)
|
|
||||||
|
|
||||||
설치가 됐는지 확인하려면:
|
|
||||||
- Claude Code / Gemini / Copilot / Antigravity: `/gsd-help`
|
|
||||||
- OpenCode / Kilo / Augment / Trae: `/gsd-help`
|
|
||||||
- Codex: `$gsd-help`
|
|
||||||
- Cline: GSD는 `.clinerules`를 통해 설치 — `.clinerules` 존재 여부 확인
|
|
||||||
|
|
||||||
> [!NOTE]
|
|
||||||
> Claude Code 2.1.88+와 Codex는 스킬(`skills/gsd-*/SKILL.md`)로 설치됩니다. Cline은 `.clinerules`를 사용합니다. 설치 프로그램이 모든 형식을 자동으로 처리합니다.
|
|
||||||
|
|
||||||
> [!TIP]
|
|
||||||
> 소스 기반 설치 또는 npm을 사용할 수 없는 환경은 **[docs/manual-update.md](docs/manual-update.md)**를 참조하세요.
|
|
||||||
|
|
||||||
### 업데이트 유지
|
|
||||||
|
|
||||||
GSD는 빠르게 발전합니다. 주기적으로 업데이트하세요:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary><strong>비대화형 설치 (Docker, CI, 스크립트)</strong></summary>
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Claude Code
|
|
||||||
npx @opengsd/gsd-core --claude --global # ~/.claude/에 설치
|
|
||||||
npx @opengsd/gsd-core --claude --local # ./.claude/에 설치
|
|
||||||
|
|
||||||
# OpenCode
|
|
||||||
npx @opengsd/gsd-core --opencode --global # ~/.config/opencode/에 설치
|
|
||||||
|
|
||||||
# Gemini CLI
|
|
||||||
npx @opengsd/gsd-core --gemini --global # ~/.gemini/에 설치
|
|
||||||
|
|
||||||
# Kilo
|
|
||||||
npx @opengsd/gsd-core --kilo --global # ~/.config/kilo/에 설치
|
|
||||||
npx @opengsd/gsd-core --kilo --local # ./.kilo/에 설치
|
|
||||||
|
|
||||||
# Codex
|
|
||||||
npx @opengsd/gsd-core --codex --global # ~/.codex/에 설치
|
|
||||||
npx @opengsd/gsd-core --codex --local # ./.codex/에 설치
|
|
||||||
|
|
||||||
# Copilot
|
|
||||||
npx @opengsd/gsd-core --copilot --global # ~/.github/에 설치
|
|
||||||
npx @opengsd/gsd-core --copilot --local # ./.github/에 설치
|
|
||||||
|
|
||||||
# Cursor CLI
|
|
||||||
npx @opengsd/gsd-core --cursor --global # ~/.cursor/에 설치
|
|
||||||
npx @opengsd/gsd-core --cursor --local # ./.cursor/에 설치
|
|
||||||
|
|
||||||
# Antigravity
|
|
||||||
npx @opengsd/gsd-core --antigravity --global # ~/.gemini/antigravity/에 설치
|
|
||||||
npx @opengsd/gsd-core --antigravity --local # ./.agent/에 설치
|
|
||||||
|
|
||||||
# Augment
|
|
||||||
npx @opengsd/gsd-core --augment --global # ~/.augment/에 설치
|
|
||||||
npx @opengsd/gsd-core --augment --local # ./.augment/에 설치
|
|
||||||
|
|
||||||
# Trae
|
|
||||||
npx @opengsd/gsd-core --trae --global # ~/.trae/에 설치
|
|
||||||
npx @opengsd/gsd-core --trae --local # ./.trae/에 설치
|
|
||||||
|
|
||||||
# Cline
|
|
||||||
npx @opengsd/gsd-core --cline --global # ~/.cline/에 설치
|
|
||||||
npx @opengsd/gsd-core --cline --local # ./.clinerules에 설치
|
|
||||||
|
|
||||||
# 전체 런타임
|
|
||||||
npx @opengsd/gsd-core --all --global # 모든 디렉터리에 설치
|
|
||||||
```
|
|
||||||
|
|
||||||
위치 프롬프트 건너뛰기: `--global` (`-g`) 또는 `--local` (`-l`).
|
|
||||||
런타임 프롬프트 건너뛰기: `--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--cursor`, `--windsurf`, `--antigravity`, `--augment`, `--trae`, `--cline`, 또는 `--all`.
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary><strong>개발 설치</strong></summary>
|
|
||||||
|
|
||||||
저장소를 클론하고 설치 프로그램을 로컬에서 실행합니다:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone https://github.com/open-gsd/gsd-core.git
|
|
||||||
cd gsd-core
|
|
||||||
node bin/install.js --claude --local
|
|
||||||
```
|
|
||||||
|
|
||||||
기여 전 수정사항 테스트를 위해 `./.claude/`에 설치됩니다.
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
### 권장: 권한 확인 건너뛰기 모드
|
|
||||||
|
|
||||||
GSD는 마찰 없는 자동화를 위해 설계되었습니다. Claude Code를 다음과 같이 실행하세요:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
claude --dangerously-skip-permissions
|
|
||||||
```
|
|
||||||
|
|
||||||
> [!TIP]
|
|
||||||
> 이게 GSD를 사용하는 방법입니다 — `date`와 `git commit` 50번을 승인하러 멈추면 의미가 없습니다.
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary><strong>대안: 세분화된 권한</strong></summary>
|
|
||||||
|
|
||||||
해당 플래그를 쓰지 않으려면 프로젝트의 `.claude/settings.json`에 다음을 추가하세요:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"permissions": {
|
|
||||||
"allow": [
|
|
||||||
"Bash(date:*)",
|
|
||||||
"Bash(echo:*)",
|
|
||||||
"Bash(cat:*)",
|
|
||||||
"Bash(ls:*)",
|
|
||||||
"Bash(mkdir:*)",
|
|
||||||
"Bash(wc:*)",
|
|
||||||
"Bash(head:*)",
|
|
||||||
"Bash(tail:*)",
|
|
||||||
"Bash(sort:*)",
|
|
||||||
"Bash(grep:*)",
|
|
||||||
"Bash(tr:*)",
|
|
||||||
"Bash(git add:*)",
|
|
||||||
"Bash(git commit:*)",
|
|
||||||
"Bash(git status:*)",
|
|
||||||
"Bash(git log:*)",
|
|
||||||
"Bash(git diff:*)",
|
|
||||||
"Bash(git tag:*)"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 작동 방식
|
## 작동 방식
|
||||||
|
|
||||||
> **이미 코드가 있나요?** 먼저 `/gsd-map-codebase`를 실행하세요. 병렬 에이전트를 생성해 스택, 아키텍처, 컨벤션, 고려사항을 분석합니다. 그러면 `/gsd-new-project`가 코드베이스를 파악한 상태에서 시작되고 — 질문은 추가하는 것에 집중되고, 기획 시 자동으로 기존 패턴을 불러옵니다.
|
각 마일스톤은 동일한 다섯 단계 루프를 반복합니다:
|
||||||
|
|
||||||
### 1. 프로젝트 초기화
|
1. **논의(Discuss)** — 기획 전에 구현 결정 사항을 미리 정리
|
||||||
|
2. **기획(Plan)** — 리서치, 분해, 그리고 플랜이 새 컨텍스트 창에 맞는지 검증
|
||||||
|
3. **실행(Execute)** — 병렬 웨이브로 플랜 실행; 각 실행기는 20만 토큰의 깨끗한 컨텍스트로 시작
|
||||||
|
4. **검증(Verify)** — 구현 결과를 검토하고, 완료 선언 전 문제 진단 및 수정
|
||||||
|
5. **출시(Ship)** — PR 생성, 단계 아카이브, 다음 단계 반복
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 빠른 시작
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest
|
||||||
```
|
```
|
||||||
|
|
||||||
|
설치 프로그램이 런타임(Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf 등)과 전역/로컬 설치 여부를 묻습니다. 크로스 런타임 호환성을 위해 설치 프로그램을 사용해야 합니다 — `agents/` 또는 `commands/`에서 파일을 직접 복사하지 마세요.
|
||||||
|
|
||||||
|
다른 런타임이나 Node.js가 없는 환경은 [런타임에 설치하기](docs/ko-KR/how-to/install-on-your-runtime.md)를 참조하세요.
|
||||||
|
|
||||||
|
설치 후 첫 번째 프로젝트를 시작합니다:
|
||||||
|
|
||||||
|
```bash
|
||||||
/gsd-new-project
|
/gsd-new-project
|
||||||
```
|
```
|
||||||
|
|
||||||
명령어 하나, 플로우 하나. 시스템이:
|
처음 사용하시나요? [첫 번째 프로젝트](docs/ko-KR/tutorials/your-first-project.md)를 따라 설치부터 첫 단계 출시까지 안내받으세요.
|
||||||
|
|
||||||
1. **질문** — 아이디어를 완전히 이해할 때까지 물어봅니다 (목표, 제약사항, 기술 선호도, 엣지 케이스)
|
|
||||||
2. **리서치** — 도메인 조사를 위해 병렬 에이전트를 생성합니다 (선택사항이지만 권장)
|
|
||||||
3. **요구사항** — v1, v2, 스코프 밖을 추출합니다
|
|
||||||
4. **로드맵** — 요구사항에 매핑된 단계를 생성합니다
|
|
||||||
|
|
||||||
로드맵을 승인하면 이제 만들 준비가 됩니다.
|
|
||||||
|
|
||||||
**생성 파일:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `.planning/research/`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 2. 단계 논의
|
## 문서
|
||||||
|
|
||||||
```
|
**튜토리얼** — 직접 해보며 배우기:
|
||||||
/gsd-discuss-phase 1
|
- [첫 번째 프로젝트](docs/ko-KR/tutorials/your-first-project.md)
|
||||||
```
|
- [기존 코드베이스 온보딩](docs/ko-KR/tutorials/onboarding-an-existing-codebase.md)
|
||||||
|
|
||||||
**여기서 구현을 직접 설계합니다.**
|
**How-to 가이드** — 작업별 레시피:
|
||||||
|
- [런타임에 설치하기](docs/ko-KR/how-to/install-on-your-runtime.md)
|
||||||
|
- [단계 기획하기](docs/ko-KR/how-to/plan-a-phase.md)
|
||||||
|
- [검증 및 출시](docs/ko-KR/how-to/verify-and-ship.md)
|
||||||
|
- … [모든 how-to 가이드 보기](docs/ko-KR/README.md#how-to-guides)
|
||||||
|
|
||||||
로드맵에는 단계당 한두 문장이 있습니다. 그건 *당신이 상상하는 방식*으로 뭔가를 만들기에 충분한 컨텍스트가 아닙니다. 리서치나 기획이 시작되기 전에 원하는 방향을 미리 잡아두는 단계입니다.
|
**레퍼런스** — 권위 있는 사실:
|
||||||
|
- [명령어](docs/ko-KR/COMMANDS.md)
|
||||||
|
- [설정](docs/ko-KR/CONFIGURATION.md)
|
||||||
|
- [CLI 도구](docs/ko-KR/CLI-TOOLS.md)
|
||||||
|
|
||||||
시스템이 단계를 분석하고 만들어지는 것에 기반한 회색 지대를 식별합니다:
|
**설명** — 개념 및 설계 결정:
|
||||||
|
- [컨텍스트 엔지니어링](docs/ko-KR/explanation/context-engineering.md)
|
||||||
|
- [단계 루프](docs/ko-KR/explanation/the-phase-loop.md)
|
||||||
|
- [아키텍처](docs/ko-KR/ARCHITECTURE.md)
|
||||||
|
|
||||||
- **시각적 기능** → 레이아웃, 밀도, 인터랙션, 빈 상태
|
전체 색인: [docs/ko-KR/README.md](docs/ko-KR/README.md). 다른 언어: [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md).
|
||||||
- **API/CLI** → 응답 형식, 플래그, 오류 처리, 상세도
|
|
||||||
- **콘텐츠 시스템** → 구조, 톤, 깊이, 흐름
|
|
||||||
- **조직 작업** → 그룹화 기준, 이름 지정, 중복, 예외
|
|
||||||
|
|
||||||
선택한 각 영역에 대해 만족할 때까지 물어봅니다. 결과물인 `CONTEXT.md`는 다음 두 단계에 바로 쓰입니다.
|
|
||||||
|
|
||||||
1. **리서처가 읽습니다** — 어떤 패턴을 조사할지 파악합니다 ("카드 레이아웃 원함" → 카드 컴포넌트 라이브러리 리서치)
|
|
||||||
2. **플래너가 읽습니다** — 어떤 결정이 확정됐는지 파악합니다 ("무한 스크롤 결정됨" → 플랜에 스크롤 처리 포함)
|
|
||||||
|
|
||||||
여기서 깊이 들어갈수록 시스템이 실제로 원하는 것에 더 가깝게 만듭니다. 건너뛰면 합리적인 기본값을 얻습니다. 사용하면 *당신의* 비전을 얻습니다.
|
|
||||||
|
|
||||||
**생성 파일:** `{phase_num}-CONTEXT.md`
|
|
||||||
|
|
||||||
> **가정 모드:** 질문보다 코드베이스 분석을 선호하나요? `/gsd-settings`에서 `workflow.discuss_mode`를 `assumptions`로 설정하세요. 시스템이 코드를 읽고 하려는 것과 이유를 제시한 다음 틀린 부분만 수정을 요청합니다. [논의 모드](docs/ko-KR/workflow-discuss-mode.md) 참조.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3. 단계 기획
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-plan-phase 1
|
|
||||||
```
|
|
||||||
|
|
||||||
시스템이:
|
|
||||||
|
|
||||||
1. **리서치** — CONTEXT.md 결정사항을 기반으로 구현 방법을 조사합니다
|
|
||||||
2. **기획** — XML 구조로 2~3개의 원자적 작업 계획을 생성합니다
|
|
||||||
3. **검증** — 요구사항 대비 계획을 확인하고, 통과할 때까지 반복합니다
|
|
||||||
|
|
||||||
각 계획은 새로운 컨텍스트 창에서 실행할 수 있을 만큼 작습니다. 저하 없이, "이제 더 간결하게 하겠습니다" 같은 말도 없습니다.
|
|
||||||
|
|
||||||
**생성 파일:** `{phase_num}-RESEARCH.md`, `{phase_num}-{N}-PLAN.md`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 4. 단계 실행
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-execute-phase 1
|
|
||||||
```
|
|
||||||
|
|
||||||
시스템이:
|
|
||||||
|
|
||||||
1. **웨이브로 계획 실행** — 가능한 경우 병렬, 의존성 있으면 순차
|
|
||||||
2. **계획당 새로운 컨텍스트** — 20만 토큰이 순수하게 구현을 위해, 쌓인 쓰레기 없음
|
|
||||||
3. **작업당 커밋** — 모든 작업이 고유한 원자적 커밋을 가짐
|
|
||||||
4. **목표 대비 검증** — 코드베이스가 단계에서 약속한 것을 전달했는지 확인
|
|
||||||
|
|
||||||
자리를 비우고 돌아오면 깔끔한 git 이력과 함께 완성된 작업이 기다립니다.
|
|
||||||
|
|
||||||
**웨이브 실행 방식:**
|
|
||||||
|
|
||||||
계획은 의존성에 따라 "웨이브"로 그룹화됩니다. 각 웨이브 안에서 계획이 병렬로 실행됩니다. 웨이브는 순차적으로 실행됩니다.
|
|
||||||
|
|
||||||
```
|
|
||||||
┌────────────────────────────────────────────────────────────────────┐
|
|
||||||
│ 단계 실행 │
|
|
||||||
├────────────────────────────────────────────────────────────────────┤
|
|
||||||
│ │
|
|
||||||
│ 웨이브 1 (병렬) 웨이브 2 (병렬) 웨이브 3 │
|
|
||||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
|
||||||
│ │ 플랜 01 │ │ 플랜 02 │ → │ 플랜 03 │ │ 플랜 04 │ → │ 플랜 05 │ │
|
|
||||||
│ │ │ │ │ │ │ │ │ │ │ │
|
|
||||||
│ │ 유저 │ │ 제품 │ │ 주문 │ │ 장바구니│ │ 결제 │ │
|
|
||||||
│ │ 모델 │ │ 모델 │ │ API │ │ API │ │ UI │ │
|
|
||||||
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
|
|
||||||
│ │ │ ↑ ↑ ↑ │
|
|
||||||
│ └───────────┴──────────────┴───────────┘ │ │
|
|
||||||
│ 의존성: 플랜 03은 플랜 01 필요 │ │
|
|
||||||
│ 플랜 04는 플랜 02 필요 │
|
|
||||||
│ 플랜 05는 플랜 03 + 04 필요 │
|
|
||||||
│ │
|
|
||||||
└────────────────────────────────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
**웨이브가 중요한 이유:**
|
|
||||||
- 독립 계획 → 같은 웨이브 → 병렬 실행
|
|
||||||
- 의존 계획 → 이후 웨이브 → 의존성 대기
|
|
||||||
- 파일 충돌 → 순차 계획 또는 같은 계획
|
|
||||||
|
|
||||||
그래서 "수직 슬라이스" (플랜 01: 유저 기능 엔드투엔드)가 "수평 레이어" (플랜 01: 모든 모델, 플랜 02: 모든 API)보다 더 잘 병렬화됩니다.
|
|
||||||
|
|
||||||
**생성 파일:** `{phase_num}-{N}-SUMMARY.md`, `{phase_num}-VERIFICATION.md`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 5. 작업 검증
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-verify-work 1
|
|
||||||
```
|
|
||||||
|
|
||||||
**여기서 실제로 작동하는지 확인합니다.**
|
|
||||||
|
|
||||||
자동화된 검증은 코드가 존재하고 테스트가 통과하는지 확인합니다. 하지만 기능이 *당신이 기대하는 방식*으로 작동하나요? 직접 사용해볼 기회입니다.
|
|
||||||
|
|
||||||
시스템이:
|
|
||||||
|
|
||||||
1. **테스트 가능한 결과물 추출** — 지금 뭘 할 수 있어야 하는지
|
|
||||||
2. **하나씩 안내** — "이메일로 로그인할 수 있나요?" 예/아니오, 또는 뭐가 잘못됐는지 설명
|
|
||||||
3. **실패 자동 진단** — 근본 원인을 찾기 위해 디버그 에이전트 생성
|
|
||||||
4. **검증된 수정 계획 생성** — 즉시 재실행 준비 완료
|
|
||||||
|
|
||||||
모든 게 통과하면 다음으로 넘어갑니다. 뭔가 깨졌으면 직접 디버그하지 않아도 됩니다 — 생성된 수정 계획으로 `/gsd-execute-phase`만 다시 실행하면 됩니다.
|
|
||||||
|
|
||||||
**생성 파일:** `{phase_num}-UAT.md`, 문제 발견 시 수정 계획
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 6. 반복 → 출시 → 완료 → 다음 마일스톤
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-discuss-phase 2
|
|
||||||
/gsd-plan-phase 2
|
|
||||||
/gsd-execute-phase 2
|
|
||||||
/gsd-verify-work 2
|
|
||||||
/gsd-ship 2 # 검증된 작업으로 PR 생성
|
|
||||||
...
|
|
||||||
/gsd-complete-milestone
|
|
||||||
/gsd-new-milestone
|
|
||||||
```
|
|
||||||
|
|
||||||
또는 GSD가 다음 단계를 자동으로 파악하게 합니다:
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-progress --next # 다음 단계 자동 감지 및 실행
|
|
||||||
```
|
|
||||||
|
|
||||||
마일스톤이 완료될 때까지 **논의 → 기획 → 실행 → 검증 → 출시** 반복.
|
|
||||||
|
|
||||||
논의 중에 더 빠르게 진행하고 싶다면 `/gsd-discuss-phase <n> --batch`를 사용해 하나씩이 아닌 소그룹으로 한 번에 답할 수 있습니다. `--chain`을 사용하면 논의에서 기획+실행까지 중간에 멈추지 않고 자동 체이닝됩니다.
|
|
||||||
|
|
||||||
각 단계는 사용자 입력(논의), 적절한 리서치(기획), 깔끔한 실행(실행), 사람의 검증(검증)을 거칩니다. 컨텍스트는 새롭게 유지됩니다. 품질도 높게 유지됩니다.
|
|
||||||
|
|
||||||
모든 단계가 끝나면 `/gsd-complete-milestone`이 마일스톤을 아카이브하고 릴리스에 태그를 답니다.
|
|
||||||
|
|
||||||
그다음 `/gsd-new-milestone`으로 다음 버전을 시작합니다 — `new-project`와 같은 흐름이지만 기존 코드베이스를 위한 것입니다. 다음에 만들 것을 설명하면 시스템이 도메인을 리서치하고, 요구사항을 스코핑하고, 새 로드맵을 만듭니다. 각 마일스톤은 깔끔한 사이클입니다: 정의 → 구축 → 출시.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 빠른 모드
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-quick
|
|
||||||
```
|
|
||||||
|
|
||||||
**전체 기획이 필요 없는 임시 작업용.**
|
|
||||||
|
|
||||||
빠른 모드는 GSD 보장 (원자적 커밋, 상태 추적)을 더 빠른 경로로 제공합니다:
|
|
||||||
|
|
||||||
- **같은 에이전트** — 플래너 + 실행기, 같은 품질
|
|
||||||
- **선택적 단계 건너뛰기** — 기본적으로 리서치, 계획 확인기, 검증기 없음
|
|
||||||
- **별도 추적** — `.planning/quick/`에 위치, 단계와 별개
|
|
||||||
|
|
||||||
**`--discuss` 플래그:** 기획 전 회색 지대를 파악하기 위한 가벼운 논의.
|
|
||||||
|
|
||||||
**`--research` 플래그:** 기획 전 집중 리서처를 생성합니다. 구현 접근법, 라이브러리 옵션, 주의사항을 조사합니다. 접근 방식이 불확실할 때 사용하세요.
|
|
||||||
|
|
||||||
**`--full` 플래그:** 모든 단계를 활성화 — 논의 + 리서치 + 계획 확인 + 검증. 빠른 작업 형태의 전체 GSD 파이프라인.
|
|
||||||
|
|
||||||
**`--validate` 플래그:** 계획 확인 + 실행 후 검증만 활성화 (이전 `--full`의 동작).
|
|
||||||
|
|
||||||
플래그는 조합 가능합니다: `--discuss --research --validate`은 논의 + 리서치 + 계획 확인 + 검증을 제공합니다.
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-quick
|
|
||||||
> 뭘 하고 싶으신가요? "설정에 다크 모드 토글 추가"
|
|
||||||
```
|
|
||||||
|
|
||||||
**생성 파일:** `.planning/quick/001-add-dark-mode-toggle/PLAN.md`, `SUMMARY.md`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 왜 효과적인가
|
## 왜 효과적인가
|
||||||
|
|
||||||
### 컨텍스트 엔지니어링
|
대부분의 AI 코딩 환경은 규모가 커지면 실패합니다. 컨텍스트 비대화로 출력 품질이 조용히 저하되고, 세션 간 공유 메모리가 없으며, 코드가 실제로 동작하는지 검증하는 것이 없기 때문입니다. GSD Core는 이 세 가지를 모두 해결합니다. 무거운 작업은 새 서브에이전트에서 실행되고, `STATE.md`와 `CONTEXT.md` 같은 구조화된 아티팩트가 세션 경계를 넘어 유지되며, 검증 단계가 구현 결과를 검토하고 단계 완료 선언 전 수정 계획을 생성합니다. 자세한 내용은 [docs/ko-KR/explanation/context-engineering.md](docs/ko-KR/explanation/context-engineering.md)를 참조하세요.
|
||||||
|
|
||||||
Claude Code는 컨텍스트만 제대로 주면 정말 강력합니다. 근데 대부분은 그걸 안 하죠.
|
문제가 발생했나요? [docs/ko-KR/how-to/recover-and-troubleshoot.md](docs/ko-KR/how-to/recover-and-troubleshoot.md)를 확인하세요.
|
||||||
|
|
||||||
GSD가 대신 해줍니다.
|
|
||||||
|
|
||||||
| 파일 | 역할 |
|
|
||||||
|------|--------------|
|
|
||||||
| `PROJECT.md` | 프로젝트 비전, 항상 로드 |
|
|
||||||
| `research/` | 생태계 지식 (스택, 기능, 아키텍처, 주의사항) |
|
|
||||||
| `REQUIREMENTS.md` | 단계 추적성이 있는 스코핑된 v1/v2 요구사항 |
|
|
||||||
| `ROADMAP.md` | 방향과 완료된 것 |
|
|
||||||
| `STATE.md` | 결정사항, 블로커, 위치 — 세션 간 메모리 |
|
|
||||||
| `PLAN.md` | XML 구조와 검증 단계가 있는 원자적 작업 |
|
|
||||||
| `SUMMARY.md` | 무슨 일이 있었는지, 무엇이 바뀌었는지, 이력에 커밋됨 |
|
|
||||||
| `todos/` | 나중 작업을 위해 캡처된 아이디어와 작업 |
|
|
||||||
| `threads/` | 여러 세션에 걸친 작업을 위한 지속적 컨텍스트 스레드 |
|
|
||||||
| `seeds/` | 때가 되면 자연스럽게 떠오르는 미래 아이디어 저장소 |
|
|
||||||
|
|
||||||
파일 크기는 Claude 품질이 떨어지기 시작하는 지점에 맞춰 설정했습니다. 그 안에 머물면 일관된 결과가 나옵니다.
|
|
||||||
|
|
||||||
### XML 프롬프트 포맷팅
|
|
||||||
|
|
||||||
모든 계획은 Claude에 최적화된 구조화된 XML입니다:
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<task type="auto">
|
|
||||||
<name>로그인 엔드포인트 생성</name>
|
|
||||||
<files>src/app/api/auth/login/route.ts</files>
|
|
||||||
<action>
|
|
||||||
JWT에는 jose 사용 (jsonwebtoken 아님 - CommonJS 이슈).
|
|
||||||
users 테이블 대비 자격증명 검증.
|
|
||||||
성공 시 httpOnly 쿠키 반환.
|
|
||||||
</action>
|
|
||||||
<verify>curl -X POST localhost:3000/api/auth/login이 200 + Set-Cookie 반환</verify>
|
|
||||||
<done>유효한 자격증명은 쿠키 반환, 무효는 401 반환</done>
|
|
||||||
</task>
|
|
||||||
```
|
|
||||||
|
|
||||||
정확한 지시사항. 추측 없음. 검증 내장.
|
|
||||||
|
|
||||||
### 멀티 에이전트 오케스트레이션
|
|
||||||
|
|
||||||
모든 단계는 같은 패턴입니다. 얇은 오케스트레이터가 전문화된 에이전트를 띄우고 결과를 모아 다음 단계로 넘깁니다.
|
|
||||||
|
|
||||||
| 단계 | 오케스트레이터가 하는 일 | 에이전트가 하는 일 |
|
|
||||||
|-------|------------------|-----------|
|
|
||||||
| 리서치 | 조율, 결과 제시 | 병렬로 4개의 리서처가 스택, 기능, 아키텍처, 주의사항 조사 |
|
|
||||||
| 기획 | 검증, 반복 관리 | 플래너가 계획 생성, 확인기가 검증, 통과할 때까지 반복 |
|
|
||||||
| 실행 | 웨이브 그룹화, 진행 추적 | 실행기가 병렬로 구현, 각각 새로운 20만 컨텍스트 |
|
|
||||||
| 검증 | 결과 제시, 다음 라우팅 | 검증기가 코드베이스를 목표 대비 확인, 디버거가 실패 진단 |
|
|
||||||
|
|
||||||
오케스트레이터는 무거운 작업을 직접 하지 않습니다. 에이전트를 띄우고 기다렸다가 결과를 합칩니다.
|
|
||||||
|
|
||||||
**결과:** 전체 단계를 다 돌릴 수 있습니다 — 깊은 리서치, 계획 생성과 검증, 병렬 실행기가 수천 줄 코드 작성, 자동화된 검증 — 근데 메인 컨텍스트 창은 30~40%에 머뭅니다. 실제 작업은 새 서브에이전트 컨텍스트에서 이루어지거든요. 세션이 끝까지 빠르고 반응적으로 유지되는 이유입니다.
|
|
||||||
|
|
||||||
### 원자적 Git 커밋
|
|
||||||
|
|
||||||
각 작업은 완료 직후 자체 커밋을 받습니다:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
abc123f docs(08-02): complete user registration plan
|
|
||||||
def456g feat(08-02): add email confirmation flow
|
|
||||||
hij789k feat(08-02): implement password hashing
|
|
||||||
lmn012o feat(08-02): create registration endpoint
|
|
||||||
```
|
|
||||||
|
|
||||||
> [!NOTE]
|
|
||||||
> **장점:** Git bisect로 어느 작업에서 깨졌는지 정확히 찍어낼 수 있습니다. 작업 단위로 독립 revert가 됩니다. 다음 세션 Claude가 읽을 명확한 이력이 남습니다. AI 자동화 워크플로우를 한눈에 파악하기 좋습니다.
|
|
||||||
|
|
||||||
커밋 하나하나가 외과적이고 추적 가능하며 의미를 담고 있습니다.
|
|
||||||
|
|
||||||
### 모듈식 설계
|
|
||||||
|
|
||||||
- 현재 마일스톤에 단계 추가
|
|
||||||
- 단계 사이에 긴급 작업 삽입
|
|
||||||
- 마일스톤 완료 후 새로 시작
|
|
||||||
- 전부 다시 만들지 않고 계획 조정
|
|
||||||
|
|
||||||
절대 갇히지 않습니다. 시스템이 적응합니다.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 명령어
|
## 커뮤니티
|
||||||
|
|
||||||
### 핵심 워크플로우
|
| 프로젝트 | 플랫폼 |
|
||||||
|
|---------|----------|
|
||||||
| 명령어 | 역할 |
|
| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | 최초 OpenCode 포트 |
|
||||||
|---------|------------|
|
| [Discord](https://discord.gg/mYgfVNfA2r) | 커뮤니티 지원 |
|
||||||
| `/gsd-new-project [--auto]` | 전체 초기화: 질문 → 리서치 → 요구사항 → 로드맵 |
|
|
||||||
| `/gsd-discuss-phase [N] [--auto] [--analyze] [--chain]` | 기획 전 구현 결정 캡처 (`--analyze`는 트레이드오프 분석 추가, `--chain`은 기획+실행으로 자동 체이닝) |
|
|
||||||
| `/gsd-plan-phase [N] [--auto] [--reviews]` | 단계에 대한 리서치 + 기획 + 검증 (`--reviews`는 코드베이스 리뷰 결과 로드) |
|
|
||||||
| `/gsd-execute-phase <N>` | 병렬 웨이브로 모든 계획 실행, 완료 시 검증 |
|
|
||||||
| `/gsd-verify-work [N]` | 수동 사용자 인수 테스트 ¹ |
|
|
||||||
| `/gsd-ship [N] [--draft]` | 자동 생성된 본문으로 검증된 단계 작업에서 PR 생성 |
|
|
||||||
| `/gsd-progress --next` | 다음 논리적 워크플로우 단계로 자동 진행 |
|
|
||||||
| `/gsd-fast <text>` | 인라인 사소한 작업 — 기획 완전 건너뛰고 즉시 실행 |
|
|
||||||
| `/gsd-audit-milestone` | 마일스톤이 완료 정의를 달성했는지 검증 |
|
|
||||||
| `/gsd-complete-milestone` | 마일스톤 아카이브, 릴리스 태그 |
|
|
||||||
| `/gsd-new-milestone [name]` | 다음 버전 시작: 질문 → 리서치 → 요구사항 → 로드맵 |
|
|
||||||
| `/gsd-forensics [desc]` | 실패한 워크플로우 실행의 사후 조사 (막힌 루프, 누락된 아티팩트, git 이상 진단) |
|
|
||||||
| `/gsd-milestone-summary [version]` | 팀 온보딩 및 리뷰를 위한 종합 프로젝트 요약 생성 |
|
|
||||||
|
|
||||||
### 워크스트림
|
|
||||||
|
|
||||||
| 명령어 | 역할 |
|
|
||||||
|---------|------------|
|
|
||||||
| `/gsd-workstreams list` | 모든 워크스트림과 상태 표시 |
|
|
||||||
| `/gsd-workstreams create <name>` | 병렬 마일스톤 작업을 위한 네임스페이스 워크스트림 생성 |
|
|
||||||
| `/gsd-workstreams switch <name>` | 활성 워크스트림 전환 |
|
|
||||||
| `/gsd-workstreams complete <name>` | 워크스트림 완료 및 병합 |
|
|
||||||
|
|
||||||
### 멀티 프로젝트 워크스페이스
|
|
||||||
|
|
||||||
| 명령어 | 역할 |
|
|
||||||
|---------|------------|
|
|
||||||
| `/gsd-workspace --new` | 저장소 복사본으로 격리된 워크스페이스 생성 (worktrees 또는 clones) |
|
|
||||||
| `/gsd-workspace --list` | 모든 GSD 워크스페이스와 상태 표시 |
|
|
||||||
| `/gsd-workspace --remove` | 워크스페이스 제거 및 worktree 정리 |
|
|
||||||
|
|
||||||
### UI 디자인
|
|
||||||
|
|
||||||
| 명령어 | 역할 |
|
|
||||||
|---------|------------|
|
|
||||||
| `/gsd-ui-phase [N]` | 프론트엔드 단계를 위한 UI 디자인 계약 (UI-SPEC.md) 생성 |
|
|
||||||
| `/gsd-ui-review [N]` | 구현된 프론트엔드 코드의 소급적 6가지 기준 시각 감사 |
|
|
||||||
|
|
||||||
### 탐색
|
|
||||||
|
|
||||||
| 명령어 | 역할 |
|
|
||||||
|---------|------------|
|
|
||||||
| `/gsd-progress` | 지금 어디에 있나? 다음은? |
|
|
||||||
| `/gsd-progress --next` | 상태 자동 감지 및 다음 단계 실행 |
|
|
||||||
| `/gsd-help` | 모든 명령어와 사용 가이드 표시 |
|
|
||||||
| `/gsd-update` | 변경 로그 미리보기와 함께 GSD 업데이트 |
|
|
||||||
| `/gsd-manager` | 여러 단계 관리를 위한 대화형 커맨드 센터 |
|
|
||||||
|
|
||||||
### 브라운필드
|
|
||||||
|
|
||||||
| 명령어 | 역할 |
|
|
||||||
|---------|------------|
|
|
||||||
| `/gsd-map-codebase [area]` | new-project 전 기존 코드베이스 분석 |
|
|
||||||
|
|
||||||
### 단계 관리
|
|
||||||
|
|
||||||
| 명령어 | 역할 |
|
|
||||||
|---------|------------|
|
|
||||||
| `/gsd-phase` | 로드맵에 단계 추가 |
|
|
||||||
| `/gsd-phase --insert [N]` | 단계 사이에 긴급 작업 삽입 |
|
|
||||||
| `/gsd-phase --edit [N] [--force]` | 기존 단계의 임의 필드를 그 자리에서 수정 — 번호와 위치는 그대로 |
|
|
||||||
| `/gsd-phase --remove [N]` | 미래 단계 제거, 번호 재정렬 |
|
|
||||||
| `/gsd-discuss-phase --assumptions [N]` | 기획 전 Claude의 의도된 접근 방식 확인 |
|
|
||||||
| `/gsd-audit-milestone --fix` | 감사에서 발견된 갭을 해소하기 위한 단계 생성 |
|
|
||||||
|
|
||||||
### 세션
|
|
||||||
|
|
||||||
| 명령어 | 역할 |
|
|
||||||
|---------|------------|
|
|
||||||
| `/gsd-pause-work` | 단계 중간에 멈출 때 핸드오프 생성 (HANDOFF.json 작성) |
|
|
||||||
| `/gsd-resume-work` | 마지막 세션에서 복원 |
|
|
||||||
| `/gsd-pause-work --report` | 수행한 작업과 결과가 담긴 세션 요약 생성 |
|
|
||||||
|
|
||||||
### 코드 품질
|
|
||||||
|
|
||||||
| 명령어 | 역할 |
|
|
||||||
|---------|------------|
|
|
||||||
| `/gsd-review` | 현재 단계 또는 브랜치의 Cross-AI 피어 리뷰 |
|
|
||||||
| `/gsd-pr-branch` | `.planning/` 커밋을 필터링한 깔끔한 PR 브랜치 생성 |
|
|
||||||
| `/gsd-audit-uat` | 검증 부채 감사 — UAT가 누락된 단계 찾기 |
|
|
||||||
|
|
||||||
### 백로그 및 스레드
|
|
||||||
|
|
||||||
| 명령어 | 역할 |
|
|
||||||
|---------|------------|
|
|
||||||
| `/gsd-capture --seed <idea>` | 트리거 조건이 있는 아이디어 저장 — 때가 되면 알아서 올라옴 |
|
|
||||||
| `/gsd-capture --backlog <desc>` | 백로그 파킹 롯에 아이디어 추가 (999.x 번호 지정, 활성 시퀀스 외부) |
|
|
||||||
| `/gsd-review-backlog` | 백로그 항목 리뷰 및 활성 마일스톤으로 승격하거나 오래된 항목 제거 |
|
|
||||||
| `/gsd-thread [name]` | 지속적 컨텍스트 스레드 — 여러 세션에 걸친 작업을 위한 가벼운 크로스 세션 지식 |
|
|
||||||
|
|
||||||
### 유틸리티
|
|
||||||
|
|
||||||
| 명령어 | 역할 |
|
|
||||||
|---------|------------|
|
|
||||||
| `/gsd-settings` | 모델 프로필 및 워크플로우 에이전트 설정 |
|
|
||||||
| `/gsd-config --profile <profile>` | 모델 프로필 전환 (quality/balanced/budget/inherit) |
|
|
||||||
| `/gsd-capture [desc]` | 나중을 위한 아이디어 캡처 |
|
|
||||||
| `/gsd-capture --list` | 대기 중인 할 일 목록 |
|
|
||||||
| `/gsd-debug [desc]` | 지속적 상태를 이용한 체계적 디버깅 |
|
|
||||||
| `/gsd-do <text>` | 자유 형식 텍스트를 적절한 GSD 명령어로 자동 라우팅 |
|
|
||||||
| `/gsd-note <text>` | 마찰 없는 아이디어 캡처 — 추가, 목록, 또는 할 일로 승격 |
|
|
||||||
| `/gsd-quick [--full] [--discuss] [--research]` | GSD 보장과 함께 임시 작업 실행 (`--full`은 전체 단계 활성화, `--discuss`는 먼저 컨텍스트 수집, `--research`는 기획 전 접근법 조사) |
|
|
||||||
| `/gsd-health [--repair]` | `.planning/` 디렉터리 무결성 검증, `--repair`로 자동 복구 |
|
|
||||||
| `/gsd-stats` | 프로젝트 통계 표시 — 단계, 계획, 요구사항, git 지표 |
|
|
||||||
| `/gsd-profile-user [--questionnaire] [--refresh]` | 개인화된 응답을 위해 세션 분석에서 개발자 행동 프로필 생성 |
|
|
||||||
|
|
||||||
<sup>¹ reddit 유저 OracleGreyBeard 기여</sup>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 설정
|
|
||||||
|
|
||||||
GSD는 프로젝트 설정을 `.planning/config.json`에 저장합니다. `/gsd-new-project` 중에 설정하거나 나중에 `/gsd-settings`로 업데이트할 수 있습니다. 전체 config 스키마, 워크플로우 토글, git 브랜칭 옵션, 에이전트별 모델 분석은 [사용자 가이드](docs/ko-KR/USER-GUIDE.md#configuration-reference)를 참조하세요.
|
|
||||||
|
|
||||||
### 핵심 설정
|
|
||||||
|
|
||||||
| 설정 | 옵션 | 기본값 | 역할 |
|
|
||||||
|---------|---------|---------|------------------|
|
|
||||||
| `mode` | `yolo`, `interactive` | `interactive` | 각 단계 자동 승인 vs 확인 |
|
|
||||||
| `granularity` | `coarse`, `standard`, `fine` | `standard` | 단계 세분성 — 스코프를 얼마나 세밀하게 나눌지 (단계 × 계획) |
|
|
||||||
|
|
||||||
### 모델 프로필
|
|
||||||
|
|
||||||
각 에이전트가 사용하는 Claude 모델을 제어합니다. 품질 대비 토큰 사용을 균형 잡습니다.
|
|
||||||
|
|
||||||
| 프로필 | 기획 | 실행 | 검증 |
|
|
||||||
|---------|----------|-----------|--------------|
|
|
||||||
| `quality` | Opus | Opus | Sonnet |
|
|
||||||
| `balanced` (기본값) | Opus | Sonnet | Sonnet |
|
|
||||||
| `budget` | Sonnet | Sonnet | Haiku |
|
|
||||||
| `inherit` | 상속 | 상속 | 상속 |
|
|
||||||
|
|
||||||
프로필 전환:
|
|
||||||
```
|
|
||||||
/gsd-config --profile budget
|
|
||||||
```
|
|
||||||
|
|
||||||
비-Anthropic 제공업체 (OpenRouter, 로컬 모델) 사용 시 또는 현재 런타임 모델 선택을 따를 때 (예: OpenCode `/model`) `inherit`를 사용하세요.
|
|
||||||
|
|
||||||
또는 `/gsd-settings`를 통해 설정하세요.
|
|
||||||
|
|
||||||
### 워크플로우 에이전트
|
|
||||||
|
|
||||||
기획/실행 중에 추가 에이전트를 생성합니다. 품질을 향상시키지만 토큰과 시간이 더 필요합니다.
|
|
||||||
|
|
||||||
| 설정 | 기본값 | 역할 |
|
|
||||||
|---------|---------|--------------|
|
|
||||||
| `workflow.research` | `true` | 각 단계 기획 전 도메인 리서치 |
|
|
||||||
| `workflow.plan_check` | `true` | 실행 전 계획이 단계 목표를 달성하는지 확인 |
|
|
||||||
| `workflow.verifier` | `true` | 실행 후 필수 사항이 전달됐는지 확인 |
|
|
||||||
| `workflow.auto_advance` | `false` | 멈추지 않고 논의 → 기획 → 실행 자동 연결 |
|
|
||||||
| `workflow.research_before_questions` | `false` | 논의 질문 대신 리서치 먼저 실행 |
|
|
||||||
| `workflow.discuss_mode` | `'discuss'` | 논의 모드: `discuss` (인터뷰), `assumptions` (코드베이스 우선) |
|
|
||||||
| `workflow.skip_discuss` | `false` | 자율 모드에서 discuss-phase 건너뛰기 |
|
|
||||||
| `workflow.text_mode` | `false` | 원격 세션을 위한 텍스트 전용 모드 (TUI 메뉴 없음) |
|
|
||||||
|
|
||||||
`/gsd-settings`로 토글하거나 호출별로 재정의하세요:
|
|
||||||
- `/gsd-plan-phase --skip-research`
|
|
||||||
- `/gsd-plan-phase --skip-verify`
|
|
||||||
|
|
||||||
### 실행
|
|
||||||
|
|
||||||
| 설정 | 기본값 | 역할 |
|
|
||||||
|---------|---------|------------------|
|
|
||||||
| `parallelization.enabled` | `true` | 독립 계획 동시 실행 |
|
|
||||||
| `planning.commit_docs` | `true` | git에서 `.planning/` 추적 |
|
|
||||||
| `hooks.context_warnings` | `true` | 컨텍스트 창 사용 경고 표시 |
|
|
||||||
|
|
||||||
### Git 브랜칭
|
|
||||||
|
|
||||||
실행 중 GSD의 브랜치 처리 방식을 제어합니다.
|
|
||||||
|
|
||||||
| 설정 | 옵션 | 기본값 | 역할 |
|
|
||||||
|---------|---------|---------|--------------|
|
|
||||||
| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | 브랜치 생성 전략 |
|
|
||||||
| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | 단계 브랜치 템플릿 |
|
|
||||||
| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | 마일스톤 브랜치 템플릿 |
|
|
||||||
|
|
||||||
**전략:**
|
|
||||||
- **`none`** — 현재 브랜치에 커밋 (기본 GSD 동작)
|
|
||||||
- **`phase`** — 단계당 브랜치 생성, 단계 완료 시 병합
|
|
||||||
- **`milestone`** — 전체 마일스톤을 위한 하나의 브랜치 생성, 완료 시 병합
|
|
||||||
|
|
||||||
마일스톤 완료 시 GSD가 스쿼시 병합 (권장) 또는 이력과 함께 병합을 제안합니다.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 보안
|
|
||||||
|
|
||||||
### 내장 보안 강화
|
|
||||||
|
|
||||||
GSD는 v1.27부터 심층 방어 보안을 포함합니다:
|
|
||||||
|
|
||||||
- **경로 순회 방지** — 모든 사용자 제공 파일 경로(`--text-file`, `--prd`)가 프로젝트 디렉터리 내에서 해석되도록 검증
|
|
||||||
- **프롬프트 인젝션 감지** — 중앙화된 `security.cjs` 모듈이 사용자 제공 텍스트가 기획 아티팩트에 들어가기 전 인젝션 패턴 스캔
|
|
||||||
- **PreToolUse 프롬프트 가드 훅** — `gsd-prompt-guard`가 `.planning/`에 대한 쓰기에서 내장된 인젝션 벡터 스캔 (권고적, 차단하지 않음)
|
|
||||||
- **안전한 JSON 파싱** — 잘못된 형식의 `--fields` 인수가 상태를 손상시키기 전에 캐치
|
|
||||||
- **셸 인수 검증** — 사용자 텍스트가 셸 보간 전에 살균됨
|
|
||||||
- **CI 준비 인젝션 스캐너** — `prompt-injection-scan.test.cjs`가 모든 에이전트/워크플로우/명령어 파일에서 내장된 인젝션 벡터 스캔
|
|
||||||
|
|
||||||
> [!NOTE]
|
|
||||||
> GSD는 LLM 시스템 프롬프트가 되는 마크다운 파일을 생성하기 때문에, 기획 아티팩트에 들어가는 사용자 제어 텍스트는 잠재적인 간접 프롬프트 인젝션 벡터가 됩니다. 이 보호 장치들은 여러 레이어에서 그런 벡터를 잡도록 설계되었습니다.
|
|
||||||
|
|
||||||
### 민감한 파일 보호
|
|
||||||
|
|
||||||
GSD의 코드베이스 매핑 및 분석 명령어는 프로젝트를 이해하기 위해 파일을 읽습니다. **비밀이 담긴 파일**을 Claude Code의 거부 목록에 추가해 보호하세요:
|
|
||||||
|
|
||||||
1. Claude Code 설정 열기 (`.claude/settings.json` 또는 전역)
|
|
||||||
2. 민감한 파일 패턴을 거부 목록에 추가:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"permissions": {
|
|
||||||
"deny": [
|
|
||||||
"Read(.env)",
|
|
||||||
"Read(.env.*)",
|
|
||||||
"Read(**/secrets/*)",
|
|
||||||
"Read(**/*credential*)",
|
|
||||||
"Read(**/*.pem)",
|
|
||||||
"Read(**/*.key)"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
이렇게 하면 실행하는 명령어와 관계없이 Claude가 이 파일들을 완전히 읽지 못합니다.
|
|
||||||
|
|
||||||
> [!IMPORTANT]
|
|
||||||
> GSD에는 비밀 커밋에 대한 내장 보호 장치가 있지만, 심층 방어가 모범 사례입니다. 민감한 파일에 대한 읽기 접근을 거부하는 것을 첫 번째 방어선으로 삼으세요.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 문제 해결
|
|
||||||
|
|
||||||
**설치 후 명령어를 찾을 수 없나요?**
|
|
||||||
- 런타임을 재시작해 명령어/스킬을 다시 로드하세요
|
|
||||||
- `~/.claude/commands/gsd/` (전역) 또는 `./.claude/commands/gsd/` (로컬)에 파일이 있는지 확인하세요
|
|
||||||
- Codex의 경우 `~/.codex/skills/gsd-*/SKILL.md` (전역) 또는 `./.codex/skills/gsd-*/SKILL.md` (로컬)에 스킬이 있는지 확인하세요
|
|
||||||
|
|
||||||
**명령어가 예상대로 작동하지 않나요?**
|
|
||||||
- `/gsd-help`를 실행해 설치 확인
|
|
||||||
- `npx @opengsd/gsd-core`를 다시 실행해 재설치
|
|
||||||
|
|
||||||
**최신 버전으로 업데이트하나요?**
|
|
||||||
```bash
|
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
**Docker 또는 컨테이너 환경을 사용하나요?**
|
|
||||||
|
|
||||||
파일 읽기가 틸드 경로(`~/.claude/...`)로 실패하면 설치 전에 `CLAUDE_CONFIG_DIR`를 설정하세요:
|
|
||||||
```bash
|
|
||||||
CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @opengsd/gsd-core --global
|
|
||||||
```
|
|
||||||
컨테이너에서 올바르게 확장되지 않을 수 있는 `~` 대신 절대 경로가 사용됩니다.
|
|
||||||
|
|
||||||
### 제거
|
|
||||||
|
|
||||||
GSD를 완전히 제거하려면:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 전역 설치
|
|
||||||
npx @opengsd/gsd-core --claude --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --opencode --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --gemini --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --kilo --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --codex --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --copilot --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --cursor --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --antigravity --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --trae --global --uninstall
|
|
||||||
|
|
||||||
# 로컬 설치 (현재 프로젝트)
|
|
||||||
npx @opengsd/gsd-core --claude --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --opencode --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --gemini --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --kilo --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --codex --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --copilot --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --cursor --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --antigravity --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --trae --local --uninstall
|
|
||||||
```
|
|
||||||
|
|
||||||
다른 설정은 그대로 유지하면서 GSD의 모든 명령어, 에이전트, 훅, 설정을 제거합니다.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 커뮤니티 포트
|
|
||||||
|
|
||||||
OpenCode, Gemini CLI, Kilo, Codex는 이제 `npx @opengsd/gsd-core`를 통해 기본 지원됩니다.
|
|
||||||
|
|
||||||
이 커뮤니티 포트들이 멀티 런타임 지원의 선구자였습니다:
|
|
||||||
|
|
||||||
| 프로젝트 | 플랫폼 | 설명 |
|
|
||||||
|---------|----------|-------------|
|
|
||||||
| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | 최초 OpenCode 적응 |
|
|
||||||
| gsd-gemini (아카이브됨) | Gemini CLI | uberfuzzy의 최초 Gemini 적응 |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -857,6 +120,6 @@ MIT 라이선스. 자세한 내용은 [LICENSE](LICENSE)를 참조하세요.
|
|||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
**Claude Code는 강력합니다. GSD가 그걸 신뢰할 수 있게 만듭니다.**
|
**Claude Code는 강력합니다. GSD Core가 그걸 신뢰할 수 있게 만듭니다.**
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|||||||
243
README.md
243
README.md
@@ -8,8 +8,6 @@
|
|||||||
|
|
||||||
**A light-weight meta-prompting, context engineering, and spec-driven development system for Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, and more.**
|
**A light-weight meta-prompting, context engineering, and spec-driven development system for Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, and more.**
|
||||||
|
|
||||||
**Solves context rot — the quality degradation that happens as your AI fills its context window.**
|
|
||||||
|
|
||||||
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
||||||
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
||||||
[](https://github.com/open-gsd/gsd-core/actions/workflows/test.yml)
|
[](https://github.com/open-gsd/gsd-core/actions/workflows/test.yml)
|
||||||
@@ -17,218 +15,79 @@
|
|||||||
[](https://github.com/open-gsd/gsd-core)
|
[](https://github.com/open-gsd/gsd-core)
|
||||||
[](LICENSE)
|
[](LICENSE)
|
||||||
|
|
||||||
<br>
|
</div>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What is GSD Core
|
||||||
|
|
||||||
|
GSD Core is a context-engineering and spec-driven development framework that drives AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, and more) through a disciplined phase loop. It solves [context rot](docs/explanation/context-engineering.md) — the quality degradation that accumulates as an AI fills its context window — by running all heavy research, planning, and execution work in fresh-context subagents while keeping your main session lean.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How it works
|
||||||
|
|
||||||
|
Each milestone repeats the same five-step loop, one phase at a time:
|
||||||
|
|
||||||
|
1. **Discuss** — capture implementation decisions before anything is planned
|
||||||
|
2. **Plan** — research, decompose, and verify the plan fits a fresh context window
|
||||||
|
3. **Execute** — run plans in parallel waves; each executor starts with a clean 200k-token context
|
||||||
|
4. **Verify** — walk through what was built; diagnose and fix before declaring done
|
||||||
|
5. **Ship** — create the PR, archive the phase, repeat for the next one
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quickstart
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx @opengsd/gsd-core@latest
|
npx @opengsd/gsd-core@latest
|
||||||
```
|
```
|
||||||
|
|
||||||
**Works on Mac, Windows, and Linux.**
|
The installer prompts for your runtime (Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, and more) and whether to install globally or locally. The installer is required for cross-runtime compatibility — do not copy files from `agents/` or `commands/` directly.
|
||||||
|
|
||||||
<br>
|
On another runtime or without Node.js? See [Install on your runtime](docs/how-to/install-on-your-runtime.md).
|
||||||
|
|
||||||
|
Once installed, start your first project:
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
*"If you know clearly what you want, this WILL build it for you. No bs."*
|
|
||||||
|
|
||||||
*"I've done SpecKit, OpenSpec and Taskmaster — this has produced the best results for me."*
|
|
||||||
|
|
||||||
*"By far the most powerful addition to my Claude Code. Nothing over-engineered. It just helps me ship."*
|
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
**Trusted by engineers at Amazon, Google, Shopify, and Webflow.**
|
|
||||||
|
|
||||||
</div>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
> [!IMPORTANT]
|
|
||||||
> **Returning to GSD Core?**
|
|
||||||
>
|
|
||||||
> Run `/gsd-map-codebase` to re-index your codebase, then `/gsd-new-project` to rebuild GSD's planning context. Your code is fine — GSD just needs its context rebuilt. Use `@opengsd/gsd-core@latest` for the current package line.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## How It Works
|
|
||||||
|
|
||||||
The loop is six commands. Each one does exactly one thing.
|
|
||||||
|
|
||||||
### 1. Initialize
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
/gsd-new-project
|
/gsd-new-project
|
||||||
```
|
```
|
||||||
|
|
||||||
Questions → research → requirements → roadmap. You approve it, then you're ready to build.
|
New here? Follow [Your first project](docs/tutorials/your-first-project.md) for a guided walkthrough from install to first shipped phase.
|
||||||
|
|
||||||
> **Already have code?** Run `/gsd-map-codebase` first. It analyzes your stack, architecture, and conventions so `/gsd-new-project` asks the right questions.
|
|
||||||
|
|
||||||
### 2. Discuss
|
|
||||||
|
|
||||||
```bash
|
|
||||||
/gsd-discuss-phase 1
|
|
||||||
```
|
|
||||||
|
|
||||||
Your roadmap has a sentence per phase. That's not enough to build it the way *you* imagine it. Discuss captures your decisions before anything gets planned: layouts, API shapes, error handling, data structures — whatever gray areas exist for this specific phase.
|
|
||||||
|
|
||||||
The output feeds directly into research and planning. Skip it, get reasonable defaults. Use it, get your vision.
|
|
||||||
|
|
||||||
### 3. Plan
|
|
||||||
|
|
||||||
```bash
|
|
||||||
/gsd-plan-phase 1
|
|
||||||
```
|
|
||||||
|
|
||||||
Research → plan → verify, in a loop until the plans pass. Each plan is small enough to execute in a fresh context window.
|
|
||||||
|
|
||||||
### 4. Execute
|
|
||||||
|
|
||||||
```bash
|
|
||||||
/gsd-execute-phase 1
|
|
||||||
```
|
|
||||||
|
|
||||||
Plans run in parallel waves. Each executor gets a fresh 200k-token context. Each task gets its own atomic commit. Walk away, come back to completed work with a clean git history.
|
|
||||||
|
|
||||||
Your main context window stays at 30–40%. The work happens in the subagents.
|
|
||||||
|
|
||||||
### 5. Verify
|
|
||||||
|
|
||||||
```bash
|
|
||||||
/gsd-verify-work 1
|
|
||||||
```
|
|
||||||
|
|
||||||
Walk through what was built. Anything broken gets a diagnosed fix plan — ready for immediate re-execution. You don't debug manually; you just run execute again.
|
|
||||||
|
|
||||||
### 6. Repeat → Ship
|
|
||||||
|
|
||||||
```bash
|
|
||||||
/gsd-ship 1
|
|
||||||
/gsd-complete-milestone
|
|
||||||
/gsd-new-milestone
|
|
||||||
```
|
|
||||||
|
|
||||||
Loop discuss → plan → execute → verify → ship until the milestone is done. Then archive, tag, and start the next one fresh.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Getting Started
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
The installer prompts for your runtime (Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, and more) and whether to install globally or locally.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
claude --dangerously-skip-permissions
|
|
||||||
```
|
|
||||||
|
|
||||||
GSD Core is built for frictionless automation. Skip-permissions is how it's intended to run.
|
|
||||||
|
|
||||||
Install only the skills you need with `--profile=core` (six core-loop skills), `--profile=standard` (core + phase management), or the default full install. Profiles compose: `--profile=core,audit`. `--minimal` is an alias for `--profile=core`. See **[docs/USER-GUIDE.md](docs/USER-GUIDE.md)** for the full walkthrough, non-interactive install flags for all 15 runtimes, and permissions configuration. See [ADR-0011](docs/adr/0011-skill-surface-budget-module.md) for the profile model and runtime surface control.
|
|
||||||
|
|
||||||
The canonical release version is the `@opengsd/gsd-core` version published on npm and mirrored in `package.json`. Older release-note files under `docs/` are retained as legacy continuity notes; do not use archived release-note numbers as the current GSD Core package version.
|
|
||||||
|
|
||||||
### Cross-runtime compatibility: installer required
|
|
||||||
|
|
||||||
The `agents/` and `commands/` directories in this repository are Claude Code-format source files. The installer (`npx @opengsd/gsd-core@latest`) transforms them per target runtime — stripping or converting frontmatter fields that Claude Code uses but other runtimes reject. For example, OpenCode requires `color` as a hex or semantic value from a fixed set, and does not accept a `tools:` frontmatter field; the installer function `convertClaudeToOpencodeFrontmatter` (`bin/install.js`) handles this automatically.
|
|
||||||
|
|
||||||
**Manually copying files** from `agents/` or `commands/` directly into a non-Claude-Code runtime config directory (e.g., `~/.config/opencode/agents`) skips the conversion step and will produce schema validation errors in that runtime.
|
|
||||||
|
|
||||||
If you are on a system without Node.js or npm (Windows + OpenCode is the most common case), see **[docs/USER-GUIDE.md — Manual install / no-Node.js setup](docs/USER-GUIDE.md#manual-install--no-nodejs-setup)** for the per-runtime conversion summary and alternative install paths.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Commands
|
|
||||||
|
|
||||||
The main loop:
|
|
||||||
|
|
||||||
| Command | What it does |
|
|
||||||
|---------|--------------|
|
|
||||||
| `/gsd-new-project` | Questions → research → requirements → roadmap |
|
|
||||||
| `/gsd-discuss-phase [N]` | Capture implementation decisions before planning |
|
|
||||||
| `/gsd-plan-phase [N]` | Research + plan + verify |
|
|
||||||
| `/gsd-execute-phase <N>` | Execute plans in parallel waves |
|
|
||||||
| `/gsd-verify-work [N]` | Manual acceptance testing |
|
|
||||||
| `/gsd-ship [N]` | Create PR from verified phase work |
|
|
||||||
| `/gsd-progress --next` | Auto-detect and run the next step |
|
|
||||||
| `/gsd-complete-milestone` | Archive milestone and tag release |
|
|
||||||
| `/gsd-new-milestone` | Start next version |
|
|
||||||
| `/gsd:surface` | Enable/disable skill clusters at runtime without reinstall |
|
|
||||||
|
|
||||||
For ad-hoc tasks, autonomous mode, codebase analysis, forensics, and the full command surface — see **[docs/COMMANDS.md](docs/COMMANDS.md)**.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Why It Works
|
|
||||||
|
|
||||||
Three things most AI-coding setups get wrong:
|
|
||||||
|
|
||||||
**1. Context bloat.** As a session grows, quality degrades. GSD keeps your main context clean by doing the heavy work in fresh subagent contexts. Researchers, planners, and executors each start fresh with exactly what they need.
|
|
||||||
|
|
||||||
**2. No shared memory.** GSD maintains structured artifacts that survive session boundaries: `PROJECT.md` (vision), `REQUIREMENTS.md` (scope), `ROADMAP.md` (where you're going), `STATE.md` (current position and decisions), `CONTEXT.md` (per-phase implementation decisions). Every new session loads these and knows exactly where things stand.
|
|
||||||
|
|
||||||
**3. No verification.** Code that "runs" isn't code that "works." GSD's verify step walks you through what was built, diagnoses failures with dedicated debug agents, and generates fix plans before you declare a phase done.
|
|
||||||
|
|
||||||
See **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** for how the multi-agent orchestration and context engineering work in detail.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
Settings live in `.planning/config.json`. Configure during `/gsd-new-project` or update with `/gsd-settings`.
|
|
||||||
|
|
||||||
Key dials:
|
|
||||||
|
|
||||||
| Setting | What it controls |
|
|
||||||
|---------|-----------------|
|
|
||||||
| `mode` | `interactive` (confirm each step) or `yolo` (auto-approve) |
|
|
||||||
| Model profiles | `quality` / `balanced` / `budget` — controls which model each agent uses |
|
|
||||||
| `workflow.research` / `plan_check` / `verifier` | Toggle the quality agents that add tokens and time |
|
|
||||||
| `parallelization.enabled` | Run independent plans simultaneously |
|
|
||||||
|
|
||||||
Optional structural review: set `code_quality.fallow.enabled` to `true` to add a fallow pre-pass to `/gsd-code-review`. GSD writes `.planning/phases/<phase>/FALLOW.json` and surfaces a `Structural Findings (fallow)` section in `REVIEW.md`. Install with `npm install -D fallow@^2.70.0` (or system-wide via `cargo install fallow`; note that the Rust binary's JSON schema must match the documented v2.70+ contract — older versions may produce silent zero-finding output).
|
|
||||||
|
|
||||||
Package legitimacy checks are built into the research, planning, and execution path: recommended dependencies get audited, unverified packages require a human checkpoint, and failed installs stop instead of trying similarly named alternatives.
|
|
||||||
|
|
||||||
For the full configuration reference — all settings, git branching strategies, per-runtime model overrides, workstream config inheritance, agent skills injection — see **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)**.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Documentation
|
## Documentation
|
||||||
|
|
||||||
| Doc | What's in it |
|
**Tutorials** — learning by doing:
|
||||||
|-----|-------------|
|
- [Your first project](docs/tutorials/your-first-project.md)
|
||||||
| [User Guide](docs/USER-GUIDE.md) | End-to-end walkthrough, install options, all runtime flags, configuration reference |
|
- [Onboarding an existing codebase](docs/tutorials/onboarding-an-existing-codebase.md)
|
||||||
| [Commands](docs/COMMANDS.md) | Every command with flags and examples |
|
|
||||||
| [Configuration](docs/CONFIGURATION.md) | Full config schema, model profiles, git branching |
|
**How-to guides** — task-focused recipes:
|
||||||
| [Architecture](docs/ARCHITECTURE.md) | How the multi-agent orchestration works |
|
- [Install on your runtime](docs/how-to/install-on-your-runtime.md)
|
||||||
| [CLI Tools](docs/CLI-TOOLS.md) | `gsd-sdk query` and programmatic SDK dispatch seams |
|
- [Plan a phase](docs/how-to/plan-a-phase.md)
|
||||||
| [Features](docs/FEATURES.md) | Complete feature index |
|
- [Verify and ship](docs/how-to/verify-and-ship.md)
|
||||||
| [Changelog](CHANGELOG.md) | Release history, including archived legacy continuity notes |
|
- … [see all how-to guides](docs/README.md#how-to-guides)
|
||||||
|
|
||||||
|
**Reference** — authoritative facts:
|
||||||
|
- [Commands](docs/COMMANDS.md)
|
||||||
|
- [Configuration](docs/CONFIGURATION.md)
|
||||||
|
- [CLI tools](docs/CLI-TOOLS.md)
|
||||||
|
|
||||||
|
**Explanation** — concepts and design decisions:
|
||||||
|
- [Context engineering](docs/explanation/context-engineering.md)
|
||||||
|
- [The phase loop](docs/explanation/the-phase-loop.md)
|
||||||
|
- [Architecture](docs/ARCHITECTURE.md)
|
||||||
|
|
||||||
|
Full index: [docs/README.md](docs/README.md). Other languages: [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Troubleshooting
|
## Why it works
|
||||||
|
|
||||||
**Commands not showing up?** Restart your runtime after install. GSD installs to `~/.claude/skills/gsd-*/` (Claude Code), `~/.codex/skills/gsd-*/` (Codex), or the equivalent for your runtime.
|
Most AI-coding setups fail at scale because context bloat silently degrades output quality, there is no shared memory between sessions, and nothing verifies that code actually works. GSD Core solves all three: heavy work runs in fresh subagents, structured artifacts like `STATE.md` and `CONTEXT.md` survive session boundaries, and the verify step walks through what was built and generates fix plans before a phase is declared done. See [docs/explanation/context-engineering.md](docs/explanation/context-engineering.md) for the full reasoning.
|
||||||
|
|
||||||
**Codex users — minimum supported CLI version is `0.130.0`.** Codex CLI 0.130.0 ([release notes](https://github.com/openai/codex/releases/tag/rust-v0.130.0)) removed extra-skill-roots discovery via [openai/codex#21485](https://github.com/openai/codex/pull/21485); from that version onward Codex discovers skills from standard roots (including `~/.codex/skills/<name>/SKILL.md`). GSD installs there directly. Earlier Codex CLI versions may still discover additional roots, which can surface duplicate `gsd-*` entries (one from extra-roots discovery, one from `~/.codex/skills/`); restart Codex after install and either upgrade or accept the duplicate listing.
|
Troubleshooting? See [docs/how-to/recover-and-troubleshoot.md](docs/how-to/recover-and-troubleshoot.md).
|
||||||
|
|
||||||
**Something broken?** Re-run the installer — it's idempotent:
|
|
||||||
```bash
|
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
**Containers or Docker?** Set `CLAUDE_CONFIG_DIR` before installing to avoid tilde-expansion issues:
|
|
||||||
```bash
|
|
||||||
CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @opengsd/gsd-core --global
|
|
||||||
```
|
|
||||||
|
|
||||||
Full troubleshooting and uninstall instructions in **[docs/USER-GUIDE.md](docs/USER-GUIDE.md#troubleshooting)**.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
476
README.pt-BR.md
476
README.pt-BR.md
@@ -1,16 +1,12 @@
|
|||||||
> ⚠️ This is an active fork. See the [English README](README.md) for the full notice about the original repo.
|
|
||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
# GSD Core
|
# GSD Core
|
||||||
|
|
||||||
**Git. Ship. Done.**
|
**Git. Ship. Done.**
|
||||||
|
|
||||||
[English](README.md) · **Português** · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md)
|
[English](README.md) · **Português** · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md)
|
||||||
|
|
||||||
**Um sistema leve e poderoso de meta-prompting, engenharia de contexto e desenvolvimento orientado a especificação para Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae e Cline.**
|
**Um sistema leve de meta-prompting, engenharia de contexto e desenvolvimento orientado a especificações para Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf e muito mais.**
|
||||||
|
|
||||||
**Resolve context rot — a degradação de qualidade que acontece conforme o Claude enche a janela de contexto.**
|
|
||||||
|
|
||||||
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
||||||
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
||||||
@@ -19,456 +15,92 @@
|
|||||||
[](https://github.com/open-gsd/gsd-core)
|
[](https://github.com/open-gsd/gsd-core)
|
||||||
[](LICENSE)
|
[](LICENSE)
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
**Funciona em Mac, Windows e Linux.**
|
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
*"Se você sabe claramente o que quer, isso VAI construir para você. Sem enrolação."*
|
|
||||||
|
|
||||||
*"Eu já usei SpecKit, OpenSpec e Taskmaster — este me deu os melhores resultados."*
|
|
||||||
|
|
||||||
*"De longe a adição mais poderosa ao meu Claude Code. Nada superengenheirado. Simplesmente faz o trabalho."*
|
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
**Confiado por engenheiros da Amazon, Google, Shopify e Webflow.**
|
|
||||||
|
|
||||||
[Por que eu criei isso](#por-que-eu-criei-isso) · [Como funciona](#como-funciona) · [Comandos](#comandos) · [Por que funciona](#por-que-funciona) · [Guia do usuário](docs/pt-BR/USER-GUIDE.md)
|
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Por que eu criei isso
|
## O que é o GSD Core
|
||||||
|
|
||||||
Sou desenvolvedor solo. Eu não escrevo código — o Claude Code escreve.
|
GSD Core é um framework de engenharia de contexto e desenvolvimento orientado a especificações que conduz agentes de codificação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor e mais) por meio de um ciclo de fases disciplinado. Ele resolve o [context rot](docs/pt-BR/explanation/context-engineering.md) — a degradação de qualidade que se acumula à medida que uma IA preenche sua janela de contexto — executando todo o trabalho pesado de pesquisa, planejamento e execução em subagentes com contexto limpo, mantendo sua sessão principal enxuta.
|
||||||
|
|
||||||
Existem outras ferramentas de desenvolvimento orientado por especificação. BMAD, Speckit... Mas quase todas parecem mais complexas do que o necessário (cerimônias de sprint, story points, sync com stakeholders, retrospectivas, fluxos Jira) ou não entendem de verdade o panorama do que você está construindo. Eu não sou uma empresa de software com 50 pessoas. Não quero teatro corporativo. Só quero construir coisas boas que funcionem.
|
|
||||||
|
|
||||||
Então eu criei o GSD. A complexidade fica no sistema, não no seu fluxo. Por trás: engenharia de contexto, formatação XML de prompts, orquestração de subagentes, gerenciamento de estado. O que você vê: alguns comandos que simplesmente funcionam.
|
|
||||||
|
|
||||||
O sistema dá ao Claude tudo que ele precisa para fazer o trabalho *e* validar o resultado. Eu confio no fluxo. Ele entrega.
|
|
||||||
|
|
||||||
— **TÂCHES**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Vibe coding ganhou má fama. Você descreve algo, a IA gera código, e sai um resultado inconsistente que quebra em escala.
|
|
||||||
|
|
||||||
O GSD corrige isso. É a camada de engenharia de contexto que torna o Claude Code confiável.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Para quem é
|
|
||||||
|
|
||||||
Para quem quer descrever o que precisa e receber isso construído do jeito certo — sem fingir que está rodando uma engenharia de 50 pessoas.
|
|
||||||
|
|
||||||
Quality gates embutidos capturam problemas reais: detecção de schema drift sinaliza mudanças ORM sem migrations, segurança ancora verificação a modelos de ameaça, e detecção de redução de escopo impede o planner de descartar requisitos silenciosamente.
|
|
||||||
|
|
||||||
### Destaques de recursos
|
|
||||||
|
|
||||||
A versão canônica é a versão de `@opengsd/gsd-core` publicada no npm e espelhada em `package.json`. Arquivos antigos de release notes em `docs/` ficam apenas como histórico de continuidade; não use números arquivados como a versão atual do GSD Core.
|
|
||||||
|
|
||||||
- **Perfil de instalação `--minimal`** — alias `--core-only`. Instala apenas os 6 skills do loop principal (`new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, `help`, `update`) e nenhum subagente `gsd-*`. Reduz o overhead do system prompt no cold-start de ~12k para ~700 tokens (≥94% de redução). Útil para LLMs locais com contexto de 32K–128K e APIs cobradas por token.
|
|
||||||
- **`/gsd-phase --edit`** — edita qualquer campo de uma fase existente em `ROADMAP.md` no lugar, sem alterar o número ou a posição. `--force` pula o diff de confirmação; referências em `depends_on` são validadas e o `STATE.md` é atualizado na escrita.
|
|
||||||
- **Build & test gate pós-merge** — o passo 5.6 de `execute-phase` agora detecta automaticamente o comando de build em `workflow.build_command`, com fallback para Xcode (`.xcodeproj`), Makefile, Justfile, Cargo, Go, Python ou npm. Projetos Xcode/iOS rodam `xcodebuild build` e `xcodebuild test` automaticamente. Funciona em modo paralelo e serial.
|
|
||||||
- **Modelo de review por runtime** — `review.models.<cli>` permite que cada CLI externa de review (codex, gemini, etc.) escolha seu próprio modelo, independente do perfil de planner/executor.
|
|
||||||
- **Herança de configuração de workstream** — quando `GSD_WORKSTREAM` está definido, o `.planning/config.json` raiz é carregado primeiro e merge-deep com o config da workstream (workstream vence em conflito). Um `null` explícito no config da workstream sobrescreve corretamente o valor raiz.
|
|
||||||
- **Consolidação de skills: 86 → 59** — 4 novos skills agrupados (`capture`, `phase`, `config`, `workspace`) absorvem 31 micro-skills. 6 skills pais existentes absorvem wrap-up e sub-operações como flags: `update --sync/--reapply`, `sketch --wrap-up`, `spike --wrap-up`, `map-codebase --fast/--query`, `code-review --fix`, `progress --do/--next`. Sem perda funcional.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Primeiros passos
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
O instalador pede:
|
|
||||||
1. **Runtime** — Claude Code, OpenCode, Gemini, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Cline, ou todos
|
|
||||||
2. **Local** — Global (todos os projetos) ou local (apenas projeto atual)
|
|
||||||
|
|
||||||
Verifique com:
|
|
||||||
- Claude Code / Gemini / Copilot / Antigravity: `/gsd-help`
|
|
||||||
- OpenCode / Kilo / Augment / Trae: `/gsd-help`
|
|
||||||
- Codex: `$gsd-help`
|
|
||||||
- Cline: GSD instala via `.clinerules` — verifique se `.clinerules` existe
|
|
||||||
|
|
||||||
> [!NOTE]
|
|
||||||
> Claude Code 2.1.88+ e Codex instalam como skills (`skills/gsd-*/SKILL.md`). Cline usa `.clinerules`. O instalador lida com todos os formatos automaticamente.
|
|
||||||
|
|
||||||
> [!TIP]
|
|
||||||
> Para instalação a partir do código-fonte ou ambientes sem npm, consulte **[docs/manual-update.md](docs/manual-update.md)**.
|
|
||||||
|
|
||||||
### Mantendo atualizado
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary><strong>Instalação não interativa (Docker, CI, Scripts)</strong></summary>
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Claude Code
|
|
||||||
npx @opengsd/gsd-core --claude --global
|
|
||||||
npx @opengsd/gsd-core --claude --local
|
|
||||||
|
|
||||||
# OpenCode
|
|
||||||
npx @opengsd/gsd-core --opencode --global
|
|
||||||
|
|
||||||
# Gemini CLI
|
|
||||||
npx @opengsd/gsd-core --gemini --global
|
|
||||||
|
|
||||||
# Kilo
|
|
||||||
npx @opengsd/gsd-core --kilo --global
|
|
||||||
npx @opengsd/gsd-core --kilo --local
|
|
||||||
|
|
||||||
# Codex
|
|
||||||
npx @opengsd/gsd-core --codex --global
|
|
||||||
npx @opengsd/gsd-core --codex --local
|
|
||||||
|
|
||||||
# Copilot
|
|
||||||
npx @opengsd/gsd-core --copilot --global
|
|
||||||
npx @opengsd/gsd-core --copilot --local
|
|
||||||
|
|
||||||
# Cursor
|
|
||||||
npx @opengsd/gsd-core --cursor --global
|
|
||||||
npx @opengsd/gsd-core --cursor --local
|
|
||||||
|
|
||||||
# Antigravity
|
|
||||||
npx @opengsd/gsd-core --antigravity --global
|
|
||||||
npx @opengsd/gsd-core --antigravity --local
|
|
||||||
|
|
||||||
# Augment
|
|
||||||
npx @opengsd/gsd-core --augment --global # Install to ~/.augment/
|
|
||||||
npx @opengsd/gsd-core --augment --local # Install to ./.augment/
|
|
||||||
|
|
||||||
# Trae
|
|
||||||
npx @opengsd/gsd-core --trae --global # Install to ~/.trae/
|
|
||||||
npx @opengsd/gsd-core --trae --local # Install to ./.trae/
|
|
||||||
|
|
||||||
# Cline
|
|
||||||
npx @opengsd/gsd-core --cline --global # Install to ~/.cline/
|
|
||||||
npx @opengsd/gsd-core --cline --local # Install to ./.clinerules
|
|
||||||
|
|
||||||
# Todos
|
|
||||||
npx @opengsd/gsd-core --all --global
|
|
||||||
```
|
|
||||||
|
|
||||||
Use `--global` (`-g`) ou `--local` (`-l`) para pular a pergunta de local.
|
|
||||||
Use `--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--cursor`, `--windsurf`, `--antigravity`, `--augment`, `--trae`, `--cline` ou `--all` para pular a pergunta de runtime.
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
### Recomendado: modo sem permissões
|
|
||||||
|
|
||||||
```bash
|
|
||||||
claude --dangerously-skip-permissions
|
|
||||||
```
|
|
||||||
|
|
||||||
> [!TIP]
|
|
||||||
> Esse é o modo pensado para o GSD: aprovar `date` e `git commit` 50 vezes mata a produtividade.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Como funciona
|
## Como funciona
|
||||||
|
|
||||||
> **Já tem código?** Rode `/gsd-map-codebase` primeiro para analisar stack, arquitetura, convenções e riscos.
|
Cada marco repete o mesmo ciclo de cinco etapas, uma fase por vez:
|
||||||
|
|
||||||
### 1. Inicializar projeto
|
1. **Discuss** — capturar decisões de implementação antes de qualquer planejamento
|
||||||
|
2. **Plan** — pesquisar, decompor e verificar se o plano cabe em uma janela de contexto limpa
|
||||||
|
3. **Execute** — executar planos em ondas paralelas; cada executor começa com um contexto limpo de 200k tokens
|
||||||
|
4. **Verify** — percorrer o que foi construído; diagnosticar e corrigir antes de declarar conclusão
|
||||||
|
5. **Ship** — criar o PR, arquivar a fase e repetir para a próxima
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Início rápido
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest
|
||||||
```
|
```
|
||||||
|
|
||||||
|
O instalador solicita seu ambiente de execução (Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf e mais) e se deseja instalar globalmente ou localmente. O instalador é necessário para compatibilidade entre runtimes — não copie arquivos diretamente de `agents/` ou `commands/`.
|
||||||
|
|
||||||
|
Em outro runtime ou sem Node.js? Consulte [Instalar no seu runtime](docs/pt-BR/how-to/install-on-your-runtime.md).
|
||||||
|
|
||||||
|
Após a instalação, inicie seu primeiro projeto:
|
||||||
|
|
||||||
|
```bash
|
||||||
/gsd-new-project
|
/gsd-new-project
|
||||||
```
|
```
|
||||||
|
|
||||||
O sistema:
|
É a primeira vez? Siga [Seu primeiro projeto](docs/pt-BR/tutorials/your-first-project.md) para um passo a passo guiado, desde a instalação até a primeira fase entregue.
|
||||||
1. **Pergunta** até entender seu objetivo
|
|
||||||
2. **Pesquisa** o domínio com agentes em paralelo
|
|
||||||
3. **Extrai requisitos** (v1, v2 e fora de escopo)
|
|
||||||
4. **Monta roadmap** por fases
|
|
||||||
|
|
||||||
**Cria:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `.planning/research/`
|
---
|
||||||
|
|
||||||
### 2. Discutir fase
|
## Documentação
|
||||||
|
|
||||||
```
|
**Tutoriais** — aprendendo na prática:
|
||||||
/gsd-discuss-phase 1
|
- [Seu primeiro projeto](docs/pt-BR/tutorials/your-first-project.md)
|
||||||
```
|
- [Integrar uma base de código existente](docs/pt-BR/tutorials/onboarding-an-existing-codebase.md)
|
||||||
|
|
||||||
Captura suas preferências de implementação antes do planejamento.
|
**Guias práticos** — receitas orientadas a tarefas:
|
||||||
|
- [Instalar no seu runtime](docs/pt-BR/how-to/install-on-your-runtime.md)
|
||||||
|
- [Planejar uma fase](docs/pt-BR/how-to/plan-a-phase.md)
|
||||||
|
- [Verificar e entregar](docs/pt-BR/how-to/verify-and-ship.md)
|
||||||
|
- … [ver todos os guias práticos](docs/pt-BR/README.md#how-to-guides)
|
||||||
|
|
||||||
**Cria:** `{phase_num}-CONTEXT.md`
|
**Referência** — informações autoritativas:
|
||||||
|
- [Comandos](docs/pt-BR/COMMANDS.md)
|
||||||
|
- [Configuração](docs/pt-BR/CONFIGURATION.md)
|
||||||
|
- [Ferramentas CLI](docs/pt-BR/CLI-TOOLS.md)
|
||||||
|
|
||||||
### 3. Planejar fase
|
**Explicação** — conceitos e decisões de design:
|
||||||
|
- [Engenharia de contexto](docs/pt-BR/explanation/context-engineering.md)
|
||||||
|
- [O ciclo de fases](docs/pt-BR/explanation/the-phase-loop.md)
|
||||||
|
- [Arquitetura](docs/pt-BR/ARCHITECTURE.md)
|
||||||
|
|
||||||
```
|
Índice completo: [docs/pt-BR/README.md](docs/pt-BR/README.md). Outros idiomas: [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md).
|
||||||
/gsd-plan-phase 1
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Pesquisa abordagens
|
|
||||||
2. Cria 2-3 planos atômicos em XML
|
|
||||||
3. Verifica contra os requisitos
|
|
||||||
|
|
||||||
**Cria:** `{phase_num}-RESEARCH.md`, `{phase_num}-{N}-PLAN.md`
|
|
||||||
|
|
||||||
### 4. Executar fase
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-execute-phase 1
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Executa planos em ondas
|
|
||||||
2. Contexto novo por plano
|
|
||||||
3. Commit atômico por tarefa
|
|
||||||
4. Verifica contra objetivos
|
|
||||||
|
|
||||||
**Cria:** `{phase_num}-{N}-SUMMARY.md`, `{phase_num}-VERIFICATION.md`
|
|
||||||
|
|
||||||
### 5. Verificar trabalho
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-verify-work 1
|
|
||||||
```
|
|
||||||
|
|
||||||
Validação manual orientada para confirmar que a feature realmente funciona como esperado.
|
|
||||||
|
|
||||||
**Cria:** `{phase_num}-UAT.md` e planos de correção se necessário
|
|
||||||
|
|
||||||
### 6. Repetir -> Entregar -> Completar
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-discuss-phase 2
|
|
||||||
/gsd-plan-phase 2
|
|
||||||
/gsd-execute-phase 2
|
|
||||||
/gsd-verify-work 2
|
|
||||||
/gsd-ship 2
|
|
||||||
/gsd-complete-milestone
|
|
||||||
/gsd-new-milestone
|
|
||||||
```
|
|
||||||
|
|
||||||
Ou deixe o GSD decidir:
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-progress --next
|
|
||||||
```
|
|
||||||
|
|
||||||
### Modo rápido
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-quick
|
|
||||||
```
|
|
||||||
|
|
||||||
Para tarefas ad-hoc sem ciclo completo de planejamento.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Por que funciona
|
## Por que funciona
|
||||||
|
|
||||||
### Engenharia de contexto
|
A maioria das configurações de codificação com IA falha em escala porque o inchaço de contexto degrada silenciosamente a qualidade da saída, não há memória compartilhada entre sessões e nada verifica se o código realmente funciona. O GSD Core resolve os três problemas: o trabalho pesado é executado em subagentes com contexto limpo, artefatos estruturados como `STATE.md` e `CONTEXT.md` sobrevivem às fronteiras de sessão, e a etapa de verificação percorre o que foi construído e gera planos de correção antes de uma fase ser declarada concluída. Consulte [docs/pt-BR/explanation/context-engineering.md](docs/pt-BR/explanation/context-engineering.md) para o raciocínio completo.
|
||||||
|
|
||||||
| Arquivo | Papel |
|
Problemas? Consulte [docs/pt-BR/how-to/recover-and-troubleshoot.md](docs/pt-BR/how-to/recover-and-troubleshoot.md).
|
||||||
|---------|-------|
|
|
||||||
| `PROJECT.md` | Visão do projeto |
|
|
||||||
| `research/` | Conhecimento do ecossistema |
|
|
||||||
| `REQUIREMENTS.md` | Escopo v1/v2 |
|
|
||||||
| `ROADMAP.md` | Direção e progresso |
|
|
||||||
| `STATE.md` | Memória entre sessões |
|
|
||||||
| `PLAN.md` | Tarefa atômica com XML |
|
|
||||||
| `SUMMARY.md` | O que mudou |
|
|
||||||
| `todos/` | Ideias para depois |
|
|
||||||
| `threads/` | Contexto persistente |
|
|
||||||
| `seeds/` | Ideias para próximos marcos |
|
|
||||||
|
|
||||||
### Formato XML de prompt
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<task type="auto">
|
|
||||||
<name>Create login endpoint</name>
|
|
||||||
<files>src/app/api/auth/login/route.ts</files>
|
|
||||||
<action>
|
|
||||||
Use jose for JWT (not jsonwebtoken - CommonJS issues).
|
|
||||||
Validate credentials against users table.
|
|
||||||
Return httpOnly cookie on success.
|
|
||||||
</action>
|
|
||||||
<verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
|
|
||||||
<done>Valid credentials return cookie, invalid return 401</done>
|
|
||||||
</task>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Orquestração multiagente
|
|
||||||
|
|
||||||
Um orquestrador leve chama agentes especializados para pesquisa, planejamento, execução e verificação.
|
|
||||||
|
|
||||||
### Commits atômicos
|
|
||||||
|
|
||||||
Cada tarefa gera commit próprio, facilitando `git bisect`, rollback e rastreabilidade.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Comandos
|
## Comunidade
|
||||||
|
|
||||||
### Fluxo principal
|
| Projeto | Plataforma |
|
||||||
|
|---------|----------|
|
||||||
| Comando | O que faz |
|
| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | Port original para OpenCode |
|
||||||
|---------|-----------|
|
| [Discord](https://discord.gg/mYgfVNfA2r) | Suporte da comunidade |
|
||||||
| `/gsd-new-project [--auto]` | Inicializa projeto completo |
|
|
||||||
| `/gsd-discuss-phase [N] [--auto] [--analyze] [--chain]` | Captura decisões antes do plano (`--chain` encadeia automaticamente em plan+execute) |
|
|
||||||
| `/gsd-plan-phase [N] [--auto] [--reviews]` | Pesquisa + plano + validação |
|
|
||||||
| `/gsd-execute-phase <N>` | Executa planos em ondas paralelas |
|
|
||||||
| `/gsd-verify-work [N]` | UAT manual |
|
|
||||||
| `/gsd-ship [N] [--draft]` | Cria PR da fase validada |
|
|
||||||
| `/gsd-progress --next` | Avança automaticamente para o próximo passo |
|
|
||||||
| `/gsd-fast <text>` | Tarefas triviais sem planejamento |
|
|
||||||
| `/gsd-complete-milestone` | Fecha o marco e marca release |
|
|
||||||
| `/gsd-new-milestone [name]` | Inicia próximo marco |
|
|
||||||
|
|
||||||
### Qualidade e utilidades
|
|
||||||
|
|
||||||
| Comando | O que faz |
|
|
||||||
|---------|-----------|
|
|
||||||
| `/gsd-review` | Peer review com múltiplas IAs |
|
|
||||||
| `/gsd-pr-branch` | Cria branch limpa para PR |
|
|
||||||
| `/gsd-settings` | Configura perfis e agentes |
|
|
||||||
| `/gsd-config --profile <profile>` | Troca perfil (quality/balanced/budget/inherit) |
|
|
||||||
| `/gsd-quick [--full] [--discuss] [--research]` | Execução rápida com garantias do GSD (`--full` ativa todas as etapas, `--validate` ativa apenas verificação) |
|
|
||||||
| `/gsd-health [--repair]` | Verifica e repara `.planning/` |
|
|
||||||
|
|
||||||
> Para a lista completa de comandos e opções, use `/gsd-help`.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Configuração
|
## Histórico de estrelas
|
||||||
|
|
||||||
As configurações do projeto ficam em `.planning/config.json`.
|
|
||||||
Você pode configurar no `/gsd-new-project` ou ajustar depois com `/gsd-settings`.
|
|
||||||
|
|
||||||
### Ajustes principais
|
|
||||||
|
|
||||||
| Configuração | Opções | Padrão | Controle |
|
|
||||||
|--------------|--------|--------|----------|
|
|
||||||
| `mode` | `yolo`, `interactive` | `interactive` | Autoaprovar vs confirmar etapas |
|
|
||||||
| `granularity` | `coarse`, `standard`, `fine` | `standard` | Granularidade de fases/planos |
|
|
||||||
|
|
||||||
### Perfis de modelo
|
|
||||||
|
|
||||||
| Perfil | Planejamento | Execução | Verificação |
|
|
||||||
|--------|--------------|----------|-------------|
|
|
||||||
| `quality` | Opus | Opus | Sonnet |
|
|
||||||
| `balanced` | Opus | Sonnet | Sonnet |
|
|
||||||
| `budget` | Sonnet | Sonnet | Haiku |
|
|
||||||
| `inherit` | Inherit | Inherit | Inherit |
|
|
||||||
|
|
||||||
Troca rápida:
|
|
||||||
```
|
|
||||||
/gsd-config --profile budget
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Segurança
|
|
||||||
|
|
||||||
### Endurecimento embutido
|
|
||||||
|
|
||||||
O GSD inclui proteções como:
|
|
||||||
- prevenção de path traversal
|
|
||||||
- detecção de prompt injection
|
|
||||||
- validação de argumentos de shell
|
|
||||||
- parsing seguro de JSON
|
|
||||||
- scanner de injeção para CI
|
|
||||||
|
|
||||||
### Protegendo arquivos sensíveis
|
|
||||||
|
|
||||||
Adicione padrões sensíveis ao deny list do Claude Code:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"permissions": {
|
|
||||||
"deny": [
|
|
||||||
"Read(.env)",
|
|
||||||
"Read(.env.*)",
|
|
||||||
"Read(**/secrets/*)",
|
|
||||||
"Read(**/*credential*)",
|
|
||||||
"Read(**/*.pem)",
|
|
||||||
"Read(**/*.key)"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Solução de problemas
|
|
||||||
|
|
||||||
**Comandos não apareceram após instalar?**
|
|
||||||
- Reinicie o runtime
|
|
||||||
- Verifique se os arquivos foram instalados no diretório correto
|
|
||||||
|
|
||||||
**Comandos não funcionam como esperado?**
|
|
||||||
- Rode `/gsd-help`
|
|
||||||
- Reinstale com `npx @opengsd/gsd-core@latest`
|
|
||||||
|
|
||||||
**Em Docker/container?**
|
|
||||||
- Defina `CLAUDE_CONFIG_DIR` antes da instalação:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @opengsd/gsd-core --global
|
|
||||||
```
|
|
||||||
|
|
||||||
### Desinstalar
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Instalações globais
|
|
||||||
npx @opengsd/gsd-core --claude --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --opencode --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --gemini --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --kilo --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --codex --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --copilot --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --cursor --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --antigravity --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --augment --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --trae --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --cline --global --uninstall
|
|
||||||
|
|
||||||
# Instalações locais (projeto atual)
|
|
||||||
npx @opengsd/gsd-core --claude --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --opencode --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --gemini --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --kilo --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --codex --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --copilot --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --cursor --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --antigravity --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --augment --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --trae --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --cline --local --uninstall
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Community Ports
|
|
||||||
|
|
||||||
OpenCode, Gemini CLI, Kilo e Codex agora são suportados nativamente via `npx @opengsd/gsd-core`.
|
|
||||||
|
|
||||||
| Projeto | Plataforma | Descrição |
|
|
||||||
|---------|------------|-----------|
|
|
||||||
| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | Adaptação original para OpenCode |
|
|
||||||
| gsd-gemini (archived) | Gemini CLI | Adaptação original para Gemini por uberfuzzy |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Star History
|
|
||||||
|
|
||||||
<a href="https://star-history.com/#open-gsd/gsd-core&Date">
|
<a href="https://star-history.com/#open-gsd/gsd-core&Date">
|
||||||
<picture>
|
<picture>
|
||||||
@@ -482,12 +114,12 @@ OpenCode, Gemini CLI, Kilo e Codex agora são suportados nativamente via `npx @o
|
|||||||
|
|
||||||
## Licença
|
## Licença
|
||||||
|
|
||||||
Licença MIT. Veja [LICENSE](LICENSE).
|
Licença MIT. Consulte [LICENSE](LICENSE) para detalhes.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
**Claude Code é poderoso. O GSD o torna confiável.**
|
**Claude Code é poderoso. GSD Core o torna confiável.**
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|||||||
804
README.zh-CN.md
804
README.zh-CN.md
@@ -1,5 +1,3 @@
|
|||||||
> ⚠️ This is an active fork. See the [English README](README.md) for the full notice about the original repo.
|
|
||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
# GSD Core
|
# GSD Core
|
||||||
@@ -8,9 +6,7 @@
|
|||||||
|
|
||||||
[English](README.md) · [Português](README.pt-BR.md) · **简体中文** · [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md)
|
[English](README.md) · [Português](README.pt-BR.md) · **简体中文** · [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md)
|
||||||
|
|
||||||
**一个轻量但强大的元提示、上下文工程与规格驱动开发系统，适用于 Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、CodeBuddy 和 Cline。**
|
**一套轻量级的元提示、上下文工程与规范驱动开发系统，适用于 Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf 等 AI 编程工具。**
|
||||||
|
|
||||||
**它解决的是 context rot：随着 Claude 的上下文窗口被填满，输出质量逐步劣化的问题。**
|
|
||||||
|
|
||||||
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
||||||
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
[](https://www.npmjs.com/package/@opengsd/gsd-core)
|
||||||
@@ -19,72 +15,25 @@
|
|||||||
[](https://github.com/open-gsd/gsd-core)
|
[](https://github.com/open-gsd/gsd-core)
|
||||||
[](LICENSE)
|
[](LICENSE)
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
**支持 Mac、Windows 和 Linux。**
|
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
*"只要你清楚自己想要什么，它就真的能给你做出来。不扯淡。"*
|
|
||||||
|
|
||||||
*"我试过 SpecKit、OpenSpec 和 Taskmaster，这套东西目前给我的结果最好。"*
|
|
||||||
|
|
||||||
*"这是我给 Claude Code 加过最强的增强。没有过度设计，是真的把事做完。"*
|
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
**已被 Amazon、Google、Shopify 和 Webflow 的工程师采用。**
|
|
||||||
|
|
||||||
[我为什么做这个](#我为什么做这个) · [它是怎么工作的](#它是怎么工作的) · [命令](#命令) · [为什么它有效](#为什么它有效) · [用户指南](docs/USER-GUIDE.md)
|
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 我为什么做这个
|
## 什么是 GSD Core
|
||||||
|
|
||||||
我是独立开发者。我不写代码，Claude Code 写。
|
GSD Core 是一套上下文工程与规范驱动开发框架，能够引导 AI 编程智能体（Claude Code、Codex、Gemini CLI、Copilot、Cursor 等）按照严格的阶段循环推进工作。它解决了[上下文腐化](docs/zh-CN/explanation/context-engineering.md)问题——即随着 AI 填满上下文窗口而逐渐累积的质量下降——通过在全新上下文的子智能体中运行所有繁重的研究、规划和执行工作，同时保持主会话的精简。
|
||||||
|
|
||||||
市面上已经有其他规格驱动开发工具，比如 BMAD、Speckit……但它们要么把事情搞得比必要的复杂得多了些（冲刺仪式、故事点、利益相关方同步、复盘、Jira 流程），要么根本缺少对你到底在构建什么的整体理解。我不是一家 50 人的软件公司。我不想演企业流程。我只是个想把好东西真正做出来的创作者。
|
|
||||||
|
|
||||||
所以我做了 GSD。复杂性在系统内部，不在你的工作流里。幕后是上下文工程、XML 提示格式、子代理编排、状态管理；你看到的是几个真能工作的命令。
|
|
||||||
|
|
||||||
这套系统会把 Claude 完成工作 *以及* 验证结果所需的一切上下文都准备好。我信任这个工作流，因为它确实能把事情做好。
|
|
||||||
|
|
||||||
这就是它。没有企业角色扮演式的废话，只有一套非常有效、能让你持续用 Claude Code 构建酷东西的系统。
|
|
||||||
|
|
||||||
— **TÂCHES**
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
Vibecoding 的名声不算好。你描述需求，AI 生成代码，结果往往是质量不稳定、规模一上来就散架的垃圾。
|
## 工作原理
|
||||||
|
|
||||||
GSD 解决的就是这个问题。它是让 Claude Code 变得可靠的上下文工程层。你只要描述想法，系统会自动提取它需要知道的一切，然后让 Claude Code 去干活。
|
每个里程碑重复相同的五步循环，每次推进一个阶段：
|
||||||
|
|
||||||
---
|
1. **讨论（Discuss）** — 在规划任何内容之前，先捕获实现决策
|
||||||
|
2. **规划（Plan）** — 研究、分解，并验证计划能够适配全新的上下文窗口
|
||||||
## 适合谁用
|
3. **执行（Execute）** — 以并行波次运行计划；每个执行器以干净的 20 万 token 上下文启动
|
||||||
|
4. **验证（Verify）** — 检查已构建的内容；在宣告完成前诊断并修复问题
|
||||||
适合那些想把自己的需求说明白，然后让系统正确构建出来的人，而不是假装自己在运营一个 50 人工程组织的人。
|
5. **交付（Ship）** — 创建 PR，归档阶段，对下一个阶段重复上述流程
|
||||||
|
|
||||||
### 功能亮点
|
|
||||||
|
|
||||||
规范版本以 npm 上发布的 `@opengsd/gsd-core` 版本以及 `package.json` 为准。`docs/` 中旧的发行说明文件仅作为连续性历史保留；不要把归档编号当作当前 GSD Core 包版本。
|
|
||||||
|
|
||||||
- **`--minimal` 安装档** — 别名 `--core-only`。仅安装主循环的 6 个核心技能（`new-project`、`discuss-phase`、`plan-phase`、`execute-phase`、`help`、`update`），不安装任何 `gsd-*` 子代理。将冷启动系统提示开销从 ~12k token 降至 ~700 token（≥94% 减少）。适合 32K–128K 上下文的本地 LLM 和按 token 计费的 API。
|
|
||||||
- **`/gsd-phase --edit`** — 就地修改 `ROADMAP.md` 中已有阶段的任意字段，不改变其编号或位置。`--force` 跳过确认 diff，验证 `depends_on` 引用，并在写入时更新 `STATE.md`。
|
|
||||||
- **合并后构建与测试门** — `execute-phase` 步骤 5.6 优先自动检测 `workflow.build_command` 配置，否则按 Xcode（`.xcodeproj`）、Makefile、Justfile、Cargo、Go、Python、npm 顺序回退。Xcode/iOS 项目自动运行 `xcodebuild build` 和 `xcodebuild test`。在并行与串行模式下均生效。
|
|
||||||
- **每运行时评审模型选择** — `review.models.<cli>` 让每个外部评审 CLI（codex、gemini 等）独立于规划/执行档选择自己的模型。
|
|
||||||
- **工作流设置继承** — 设置 `GSD_WORKSTREAM` 后，先加载根 `.planning/config.json`，再与该工作流的配置进行深合并（冲突时工作流优先）。工作流配置中显式 `null` 会覆盖根值。
|
|
||||||
- **技能整合：86 → 59** — 4 个新分组技能（`capture`、`phase`、`config`、`workspace`）吸收了 31 个微技能。6 个已有父技能将收尾与子操作合并为标志：`update --sync/--reapply`、`sketch --wrap-up`、`spike --wrap-up`、`map-codebase --fast/--query`、`code-review --fix`、`progress --do/--next`。功能无损失。
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -94,727 +43,60 @@ GSD 解决的就是这个问题。它是让 Claude Code 变得可靠的上下文
|
|||||||
npx @opengsd/gsd-core@latest
|
npx @opengsd/gsd-core@latest
|
||||||
```
|
```
|
||||||
|
|
||||||
安装器会提示你选择：
|
安装程序会提示选择运行时（Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf 等）以及是全局安装还是本地安装。跨运行时兼容性需要使用安装程序——请勿直接从 `agents/` 或 `commands/` 目录复制文件。
|
||||||
1. **运行时**：Claude Code、OpenCode、Gemini、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、CodeBuddy、Cline，或全部
|
|
||||||
2. **安装位置**：全局（所有项目）或本地（仅当前项目）
|
|
||||||
|
|
||||||
安装后可这样验证：
|
使用其他运行时或没有 Node.js？请参阅[在你的运行时上安装](docs/zh-CN/how-to/install-on-your-runtime.md)。
|
||||||
- Claude Code / Gemini / Copilot / Antigravity：`/gsd-help`
|
|
||||||
- OpenCode / Kilo / Augment / Trae / CodeBuddy：`/gsd-help`
|
|
||||||
- Codex：`$gsd-help`
|
|
||||||
- Cline：GSD 通过 `.clinerules` 安装 — 检查 `.clinerules` 是否存在
|
|
||||||
|
|
||||||
> [!NOTE]
|
安装完成后，启动你的第一个项目：
|
||||||
> Claude Code 2.1.88+ 和 Codex 以 skill 形式安装（`skills/gsd-*/SKILL.md`）。Cline 使用 `.clinerules`。安装器会自动处理所有格式。
|
|
||||||
|
|
||||||
> [!TIP]
|
|
||||||
> 基于源码安装或无法使用 npm 的环境，请参阅 **[docs/manual-update.md](docs/manual-update.md)**。
|
|
||||||
|
|
||||||
### 保持更新
|
|
||||||
|
|
||||||
GSD 迭代很快，建议定期更新：
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary><strong>非交互式安装（Docker、CI、脚本）</strong></summary>
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Claude Code
|
|
||||||
npx @opengsd/gsd-core --claude --global # 安装到 ~/.claude/
|
|
||||||
npx @opengsd/gsd-core --claude --local # 安装到 ./.claude/
|
|
||||||
|
|
||||||
# OpenCode
|
|
||||||
npx @opengsd/gsd-core --opencode --global # 安装到 ~/.config/opencode/
|
|
||||||
|
|
||||||
# Gemini CLI
|
|
||||||
npx @opengsd/gsd-core --gemini --global # 安装到 ~/.gemini/
|
|
||||||
|
|
||||||
# Kilo
|
|
||||||
npx @opengsd/gsd-core --kilo --global # 安装到 ~/.config/kilo/
|
|
||||||
npx @opengsd/gsd-core --kilo --local # 安装到 ./.kilo/
|
|
||||||
|
|
||||||
# Codex
|
|
||||||
npx @opengsd/gsd-core --codex --global # 安装到 ~/.codex/
|
|
||||||
npx @opengsd/gsd-core --codex --local # 安装到 ./.codex/
|
|
||||||
|
|
||||||
# Copilot
|
|
||||||
npx @opengsd/gsd-core --copilot --global # 安装到 ~/.github/
|
|
||||||
npx @opengsd/gsd-core --copilot --local # 安装到 ./.github/
|
|
||||||
|
|
||||||
# Cursor CLI
|
|
||||||
npx @opengsd/gsd-core --cursor --global # 安装到 ~/.cursor/
|
|
||||||
npx @opengsd/gsd-core --cursor --local # 安装到 ./.cursor/
|
|
||||||
|
|
||||||
# Antigravity
|
|
||||||
npx @opengsd/gsd-core --antigravity --global # 安装到 ~/.gemini/antigravity/
|
|
||||||
npx @opengsd/gsd-core --antigravity --local # 安装到 ./.agent/
|
|
||||||
|
|
||||||
# Augment
|
|
||||||
npx @opengsd/gsd-core --augment --global # 安装到 ~/.augment/
|
|
||||||
npx @opengsd/gsd-core --augment --local # 安装到 ./.augment/
|
|
||||||
|
|
||||||
# Trae
|
|
||||||
npx @opengsd/gsd-core --trae --global # 安装到 ~/.trae/
|
|
||||||
npx @opengsd/gsd-core --trae --local # 安装到 ./.trae/
|
|
||||||
|
|
||||||
# CodeBuddy
|
|
||||||
npx @opengsd/gsd-core --codebuddy --global # 安装到 ~/.codebuddy/
|
|
||||||
npx @opengsd/gsd-core --codebuddy --local # 安装到 ./.codebuddy/
|
|
||||||
|
|
||||||
# Cline
|
|
||||||
npx @opengsd/gsd-core --cline --global # 安装到 ~/.cline/
|
|
||||||
npx @opengsd/gsd-core --cline --local # 安装到 ./.clinerules
|
|
||||||
|
|
||||||
# 所有运行时
|
|
||||||
npx @opengsd/gsd-core --all --global # 安装到所有目录
|
|
||||||
```
|
|
||||||
|
|
||||||
使用 `--global`（`-g`）或 `--local`（`-l`）可以跳过安装位置提示。
|
|
||||||
使用 `--claude`、`--opencode`、`--gemini`、`--kilo`、`--codex`、`--copilot`、`--cursor`、`--windsurf`、`--antigravity`、`--augment`、`--trae`、`--codebuddy`、`--cline` 或 `--all` 可以跳过运行时提示。
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary><strong>开发安装</strong></summary>
|
|
||||||
|
|
||||||
克隆仓库并在本地运行安装器：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone https://github.com/open-gsd/gsd-core.git
|
|
||||||
cd gsd-core
|
|
||||||
node bin/install.js --claude --local
|
|
||||||
```
|
|
||||||
|
|
||||||
这样会安装到 `./.claude/`，方便你在贡献代码前测试自己的改动。
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
### 推荐：跳过权限确认模式
|
|
||||||
|
|
||||||
GSD 的设计目标是无摩擦自动化。运行 Claude Code 时建议使用：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
claude --dangerously-skip-permissions
|
|
||||||
```
|
|
||||||
|
|
||||||
> [!TIP]
|
|
||||||
> 这才是 GSD 的预期用法。连 `date` 和 `git commit` 都要来回确认 50 次，整个体验就废了。
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary><strong>替代方案：细粒度权限</strong></summary>
|
|
||||||
|
|
||||||
如果你不想使用这个 flag，可以在项目的 `.claude/settings.json` 中加入：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"permissions": {
|
|
||||||
"allow": [
|
|
||||||
"Bash(date:*)",
|
|
||||||
"Bash(echo:*)",
|
|
||||||
"Bash(cat:*)",
|
|
||||||
"Bash(ls:*)",
|
|
||||||
"Bash(mkdir:*)",
|
|
||||||
"Bash(wc:*)",
|
|
||||||
"Bash(head:*)",
|
|
||||||
"Bash(tail:*)",
|
|
||||||
"Bash(sort:*)",
|
|
||||||
"Bash(grep:*)",
|
|
||||||
"Bash(tr:*)",
|
|
||||||
"Bash(git add:*)",
|
|
||||||
"Bash(git commit:*)",
|
|
||||||
"Bash(git status:*)",
|
|
||||||
"Bash(git log:*)",
|
|
||||||
"Bash(git diff:*)",
|
|
||||||
"Bash(git tag:*)"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 它是怎么工作的
|
|
||||||
|
|
||||||
> **已经有现成代码库？** 先运行 `/gsd-map-codebase`。它会并行拉起多个代理分析你的技术栈、架构、约定和风险点。之后 `/gsd-new-project` 就会真正“理解”你的代码库，提问会聚焦在你打算新增的部分，规划时也会自动加载你的现有模式。
|
|
||||||
|
|
||||||
### 1. 初始化项目
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-new-project
|
/gsd-new-project
|
||||||
```
|
```
|
||||||
|
|
||||||
一个命令，一条完整流程。系统会：
|
初次使用？请按照[你的第一个项目](docs/zh-CN/tutorials/your-first-project.md)进行引导式操作，从安装到完成第一个交付阶段。
|
||||||
|
|
||||||
1. **提问**：一直问到它彻底理解你的想法（目标、约束、技术偏好、边界情况）
|
|
||||||
2. **研究**：并行拉起代理调研领域知识（可选，但强烈建议）
|
|
||||||
3. **需求梳理**：提取哪些属于 v1、v2，哪些不在范围内
|
|
||||||
4. **路线图**：创建与需求映射的阶段规划
|
|
||||||
|
|
||||||
你审核并批准路线图后，就可以开始构建。
|
|
||||||
|
|
||||||
**生成：** `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md`、`.planning/research/`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 2. 讨论阶段
|
## 文档
|
||||||
|
|
||||||
```
|
**教程** — 边做边学：
|
||||||
/gsd-discuss-phase 1
|
- [你的第一个项目](docs/zh-CN/tutorials/your-first-project.md)
|
||||||
```
|
- [接入现有代码库](docs/zh-CN/tutorials/onboarding-an-existing-codebase.md)
|
||||||
|
|
||||||
**这是你塑造实现方式的地方。**
|
**操作指南** — 面向任务的实用方法：
|
||||||
|
- [在你的运行时上安装](docs/zh-CN/how-to/install-on-your-runtime.md)
|
||||||
|
- [规划一个阶段](docs/zh-CN/how-to/plan-a-phase.md)
|
||||||
|
- [验证与交付](docs/zh-CN/how-to/verify-and-ship.md)
|
||||||
|
- … [查看所有操作指南](docs/zh-CN/README.md#how-to-guides)
|
||||||
|
|
||||||
你的路线图里，每个阶段通常只有一两句话。这点信息不足以让系统按 *你脑中的样子* 把东西做出来。这一步的作用，就是在研究和规划之前，把你的偏好先收进去。
|
**参考文档** — 权威信息：
|
||||||
|
- [命令](docs/zh-CN/COMMANDS.md)
|
||||||
|
- [配置](docs/zh-CN/CONFIGURATION.md)
|
||||||
|
- [CLI 工具](docs/zh-CN/CLI-TOOLS.md)
|
||||||
|
|
||||||
系统会分析该阶段，并根据要构建的内容识别灰区：
|
**概念说明** — 设计理念与决策：
|
||||||
|
- [上下文工程](docs/zh-CN/explanation/context-engineering.md)
|
||||||
|
- [阶段循环](docs/zh-CN/explanation/the-phase-loop.md)
|
||||||
|
- [架构](docs/zh-CN/ARCHITECTURE.md)
|
||||||
|
|
||||||
- **视觉功能**：布局、信息密度、交互、空状态
|
完整索引：[docs/zh-CN/README.md](docs/zh-CN/README.md)。其他语言：[日本語](README.ja-JP.md) · [한국어](README.ko-KR.md) · [Português](README.pt-BR.md) · [English](README.md)。
|
||||||
- **API / CLI**：返回格式、flags、错误处理、详细程度
|
|
||||||
- **内容系统**：结构、语气、深度、流转方式
|
|
||||||
- **组织型任务**：分组标准、命名、去重、例外情况
|
|
||||||
|
|
||||||
对每个你选择的区域，系统都会持续追问，直到你满意为止。最终产物 `CONTEXT.md` 会直接喂给后续两个步骤：
|
|
||||||
|
|
||||||
1. **研究代理会读取它**：知道该研究哪些模式（例如“用户想要卡片布局” → 去研究卡片组件库）
|
|
||||||
2. **规划代理会读取它**：知道哪些决策已经锁定（例如“已决定使用无限滚动” → 计划里就会包含滚动处理）
|
|
||||||
|
|
||||||
你在这里给出的信息越具体，系统越能构建出你真正想要的东西。跳过它，你拿到的是合理默认值；用好它，你拿到的是 *你的* 方案。
|
|
||||||
|
|
||||||
**生成：** `{phase_num}-CONTEXT.md`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 3. 规划阶段
|
## 为什么有效
|
||||||
|
|
||||||
```
|
大多数 AI 编程方案在规模化时都会失败，原因在于上下文膨胀会悄无声息地降低输出质量，各会话之间没有共享记忆，也没有任何机制来验证代码是否真正可用。GSD Core 解决了这三个问题：繁重的工作在全新的子智能体中运行，`STATE.md` 和 `CONTEXT.md` 等结构化工件能够跨越会话边界保持存续，验证步骤会检查已构建的内容并在宣告阶段完成前生成修复计划。完整的设计思路请参阅 [docs/zh-CN/explanation/context-engineering.md](docs/zh-CN/explanation/context-engineering.md)。
|
||||||
/gsd-plan-phase 1
|
|
||||||
```
|
|
||||||
|
|
||||||
系统会：
|
遇到问题？请参阅 [docs/zh-CN/how-to/recover-and-troubleshoot.md](docs/zh-CN/how-to/recover-and-troubleshoot.md)。
|
||||||
|
|
||||||
1. **研究**：结合你的 `CONTEXT.md` 决策，调研这一阶段该怎么实现
|
|
||||||
2. **制定计划**：创建 2-3 份原子化任务计划，使用 XML 结构
|
|
||||||
3. **验证**：将计划与需求对照检查，直到通过为止
|
|
||||||
|
|
||||||
每份计划都足够小，可以在一个全新的上下文窗口里执行。没有质量衰减，也不会出现“我接下来会更简洁一些”的退化状态。
|
|
||||||
|
|
||||||
**生成：** `{phase_num}-RESEARCH.md`、`{phase_num}-{N}-PLAN.md`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 4. 执行阶段
|
## 社区
|
||||||
|
|
||||||
```
|
| 项目 | 平台 |
|
||||||
/gsd-execute-phase 1
|
|---------|----------|
|
||||||
```
|
| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | 原始 OpenCode 移植版 |
|
||||||
|
| [Discord](https://discord.gg/mYgfVNfA2r) | 社区支持 |
|
||||||
系统会：
|
|
||||||
|
|
||||||
1. **按 wave 执行计划**：能并行的并行，有依赖的顺序执行
|
|
||||||
2. **每个计划使用新上下文**：20 万 token 纯用于实现，零历史垃圾
|
|
||||||
3. **每个任务单独提交**：每项任务都有自己的原子提交
|
|
||||||
4. **对照目标验证**：检查代码库是否真的交付了该阶段承诺的内容
|
|
||||||
|
|
||||||
你可以离开，回来时看到的是已经完成的工作和干净的 git 历史。
|
|
||||||
|
|
||||||
**Wave 执行方式：**
|
|
||||||
|
|
||||||
计划会根据依赖关系被分组为不同的 “wave”。同一 wave 内并行执行，不同 wave 之间顺序推进。
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────────────────────────────────────────────┐
|
|
||||||
│ PHASE EXECUTION │
|
|
||||||
├─────────────────────────────────────────────────────────────────────┤
|
|
||||||
│ │
|
|
||||||
│ WAVE 1 (parallel) WAVE 2 (parallel) WAVE 3 │
|
|
||||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
|
||||||
│ │ Plan 01 │ │ Plan 02 │ → │ Plan 03 │ │ Plan 04 │ → │ Plan 05 │ │
|
|
||||||
│ │ │ │ │ │ │ │ │ │ │ │
|
|
||||||
│ │ User │ │ Product │ │ Orders │ │ Cart │ │ Checkout│ │
|
|
||||||
│ │ Model │ │ Model │ │ API │ │ API │ │ UI │ │
|
|
||||||
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
|
|
||||||
│ │ │ ↑ ↑ ↑ │
|
|
||||||
│ └───────────┴──────────────┴───────────┘ │ │
|
|
||||||
│ Dependencies: Plan 03 needs Plan 01 │ │
|
|
||||||
│ Plan 04 needs Plan 02 │ │
|
|
||||||
│ Plan 05 needs Plans 03 + 04 │ │
|
|
||||||
│ │
|
|
||||||
└─────────────────────────────────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
**为什么 wave 很重要：**
|
|
||||||
- 独立计划 → 同一 wave → 并行执行
|
|
||||||
- 依赖计划 → 更晚的 wave → 等依赖完成
|
|
||||||
- 文件冲突 → 顺序执行，或合并到同一个计划里
|
|
||||||
|
|
||||||
这也是为什么“垂直切片”（Plan 01：端到端完成用户功能）比“水平分层”（Plan 01：所有 model，Plan 02：所有 API）更容易并行化。
|
|
||||||
|
|
||||||
**生成：** `{phase_num}-{N}-SUMMARY.md`、`{phase_num}-VERIFICATION.md`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 5. 验证工作
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-verify-work 1
|
|
||||||
```
|
|
||||||
|
|
||||||
**这是你确认它是否真的可用的地方。**
|
|
||||||
|
|
||||||
自动化验证能检查代码存在、测试通过。但这个功能是否真的按你的预期工作？这一步就是让你亲自用。
|
|
||||||
|
|
||||||
系统会：
|
|
||||||
|
|
||||||
1. **提取可测试的交付项**：你现在应该能做到什么
|
|
||||||
2. **逐项带你验证**：“能否用邮箱登录？” 可以 / 不可以，或者描述哪里不对
|
|
||||||
3. **自动诊断失败**：拉起 debug 代理定位根因
|
|
||||||
4. **创建验证过的修复计划**：可立刻重新执行
|
|
||||||
|
|
||||||
如果一切通过，就进入下一步；如果哪里坏了，你不需要手动 debug，只要重新运行 `/gsd-execute-phase`，执行它自动生成的修复计划即可。
|
|
||||||
|
|
||||||
**生成：** `{phase_num}-UAT.md`，以及发现问题时的修复计划
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 6. 重复 → 发布 → 完成 → 下一个里程碑
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-discuss-phase 2
|
|
||||||
/gsd-plan-phase 2
|
|
||||||
/gsd-execute-phase 2
|
|
||||||
/gsd-verify-work 2
|
|
||||||
/gsd-ship 2 # 从已验证的工作创建 PR
|
|
||||||
...
|
|
||||||
/gsd-complete-milestone
|
|
||||||
/gsd-new-milestone
|
|
||||||
```
|
|
||||||
|
|
||||||
或者让 GSD 自动判断下一步：
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-progress --next # 自动检测并执行下一步
|
|
||||||
```
|
|
||||||
|
|
||||||
循环执行 **讨论 → 规划 → 执行 → 验证 → 发布**，直到整个里程碑完成。
|
|
||||||
|
|
||||||
如果你希望在讨论阶段更快收集信息，可以用 `/gsd-discuss-phase <n> --batch`，一次回答一小组问题，而不是逐个问答。
|
|
||||||
|
|
||||||
每个阶段都会得到你的输入（discuss）、充分研究（plan）、干净执行（execute）和人工验证（verify）。上下文始终保持新鲜，质量也能持续稳定。
|
|
||||||
|
|
||||||
当所有阶段完成后，`/gsd-complete-milestone` 会归档当前里程碑并打 release tag。
|
|
||||||
|
|
||||||
接着用 `/gsd-new-milestone` 开启下一个版本。它和 `new-project` 流程相同，只是面向你现有的代码库。你描述下一步想构建什么，系统研究领域、梳理需求，再产出新的路线图。每个里程碑都是一个干净周期：定义 → 构建 → 发布。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 快速模式
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-quick
|
|
||||||
```
|
|
||||||
|
|
||||||
**适用于不需要完整规划的临时任务。**
|
|
||||||
|
|
||||||
快速模式保留 GSD 的核心保障（原子提交、状态跟踪），但路径更短：
|
|
||||||
|
|
||||||
- **相同的代理体系**：同样是 planner + executor，质量不降
|
|
||||||
- **跳过可选步骤**：默认不启用 research、plan checker、verifier
|
|
||||||
- **独立跟踪**：数据存放在 `.planning/quick/`，不和 phase 混在一起
|
|
||||||
|
|
||||||
**`--discuss` 参数：** 在规划前先进行轻量讨论，理清灰区。
|
|
||||||
|
|
||||||
**`--research` 参数：** 在规划前拉起研究代理。调查实现方式、库选型和潜在坑点。适合你不确定怎么下手的场景。
|
|
||||||
|
|
||||||
**`--full` 参数：** 启用计划检查（最多 2 轮迭代）和执行后验证。
|
|
||||||
|
|
||||||
参数可组合使用：`--discuss --research --full` 可同时获得讨论 + 研究 + 计划检查 + 验证。
|
|
||||||
|
|
||||||
```
|
|
||||||
/gsd-quick
|
|
||||||
> What do you want to do? "Add dark mode toggle to settings"
|
|
||||||
```
|
|
||||||
|
|
||||||
**生成：** `.planning/quick/001-add-dark-mode-toggle/PLAN.md`、`SUMMARY.md`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 为什么它有效
|
|
||||||
|
|
||||||
### 上下文工程
|
|
||||||
|
|
||||||
Claude Code 非常强大，前提是你把它需要的上下文给对。大多数人做不到。
|
|
||||||
|
|
||||||
GSD 会替你处理：
|
|
||||||
|
|
||||||
| 文件 | 作用 |
|
|
||||||
|------|------|
|
|
||||||
| `PROJECT.md` | 项目愿景，始终加载 |
|
|
||||||
| `research/` | 生态知识（技术栈、功能、架构、坑点） |
|
|
||||||
| `REQUIREMENTS.md` | 带 phase 可追踪性的 v1/v2 范围定义 |
|
|
||||||
| `ROADMAP.md` | 你要去哪里、哪些已经完成 |
|
|
||||||
| `STATE.md` | 决策、阻塞、当前位置，跨会话记忆 |
|
|
||||||
| `PLAN.md` | 带 XML 结构和验证步骤的原子任务 |
|
|
||||||
| `SUMMARY.md` | 做了什么、改了什么、已写入历史 |
|
|
||||||
| `todos/` | 留待后续处理的想法和任务 |
|
|
||||||
|
|
||||||
这些尺寸限制都是基于 Claude 在何处开始质量退化得出的。控制在阈值内，输出才能持续稳定。
|
|
||||||
|
|
||||||
### XML 提示格式
|
|
||||||
|
|
||||||
每个计划都会使用为 Claude 优化过的结构化 XML：
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<task type="auto">
|
|
||||||
<name>Create login endpoint</name>
|
|
||||||
<files>src/app/api/auth/login/route.ts</files>
|
|
||||||
<action>
|
|
||||||
Use jose for JWT (not jsonwebtoken - CommonJS issues).
|
|
||||||
Validate credentials against users table.
|
|
||||||
Return httpOnly cookie on success.
|
|
||||||
</action>
|
|
||||||
<verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
|
|
||||||
<done>Valid credentials return cookie, invalid return 401</done>
|
|
||||||
</task>
|
|
||||||
```
|
|
||||||
|
|
||||||
指令足够精确，不需要猜。验证也内建在计划里。
|
|
||||||
|
|
||||||
### 多代理编排
|
|
||||||
|
|
||||||
每个阶段都遵循同一种模式：一个轻量 orchestrator 拉起专用代理、汇总结果，再路由到下一步。
|
|
||||||
|
|
||||||
| 阶段 | Orchestrator 做什么 | Agents 做什么 |
|
|
||||||
|------|---------------------|---------------|
|
|
||||||
| 研究 | 协调与展示研究结果 | 4 个并行研究代理分别调查技术栈、功能、架构、坑点 |
|
|
||||||
| 规划 | 校验并管理迭代 | Planner 生成计划，checker 验证，循环直到通过 |
|
|
||||||
| 执行 | 按 wave 分组并跟踪进度 | Executors 并行实现，每个都有全新的 20 万上下文 |
|
|
||||||
| 验证 | 呈现结果并决定下一步 | Verifier 对照目标检查代码库，debuggers 诊断失败 |
|
|
||||||
|
|
||||||
Orchestrator 本身不做重活，只负责拉代理、等待、整合结果。
|
|
||||||
|
|
||||||
**最终效果：** 你可以在一个阶段里完成深度研究、生成并验证多个计划、让多个执行代理并行写下成千上万行代码，再自动对照目标验证，而主上下文窗口依然能维持在 30-40% 左右。真正的工作都发生在新鲜的子代理上下文里，所以你的主会话始终保持快速、响应稳定。
|
|
||||||
|
|
||||||
### 原子 Git 提交
|
|
||||||
|
|
||||||
每个任务完成后都会立刻生成独立提交：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
abc123f docs(08-02): complete user registration plan
|
|
||||||
def456g feat(08-02): add email confirmation flow
|
|
||||||
hij789k feat(08-02): implement password hashing
|
|
||||||
lmn012o feat(08-02): create registration endpoint
|
|
||||||
```
|
|
||||||
|
|
||||||
> [!NOTE]
|
|
||||||
> **好处：** `git bisect` 能精准定位是哪项任务引入故障；每个任务都可单独回滚；未来 Claude 读取历史时也更清晰；整个 AI 自动化工作流的可观测性更好。
|
|
||||||
|
|
||||||
每个 commit 都是外科手术式的：精确、可追踪、有意义。
|
|
||||||
|
|
||||||
### 模块化设计
|
|
||||||
|
|
||||||
- 给当前里程碑追加 phase
|
|
||||||
- 在 phase 之间插入紧急工作
|
|
||||||
- 完成当前里程碑后开启新的周期
|
|
||||||
- 在不推倒重来的前提下调整计划
|
|
||||||
|
|
||||||
你不会被这套系统绑死，它会随着项目变化而调整。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 命令
|
|
||||||
|
|
||||||
### 核心工作流
|
|
||||||
|
|
||||||
| 命令 | 作用 |
|
|
||||||
|------|------|
|
|
||||||
| `/gsd-new-project [--auto]` | 完整初始化：提问 → 研究 → 需求 → 路线图 |
|
|
||||||
| `/gsd-discuss-phase [N] [--auto] [--analyze]` | 在规划前收集实现决策（`--analyze` 增加权衡分析） |
|
|
||||||
| `/gsd-plan-phase [N] [--auto] [--reviews]` | 为某个阶段执行研究 + 规划 + 验证（`--reviews` 加载代码库审查结果） |
|
|
||||||
| `/gsd-execute-phase <N>` | 以并行 wave 执行全部计划，完成后验证 |
|
|
||||||
| `/gsd-verify-work [N]` | 人工用户验收测试 ¹ |
|
|
||||||
| `/gsd-ship [N] [--draft]` | 从已验证的阶段工作创建 PR，自动生成 PR 描述 |
|
|
||||||
| `/gsd-fast <text>` | 内联处理琐碎任务——完全跳过规划，立即执行 |
|
|
||||||
| `/gsd-progress --next` | 自动推进到下一个逻辑工作流步骤 |
|
|
||||||
| `/gsd-audit-milestone` | 验证里程碑是否达到完成定义 |
|
|
||||||
| `/gsd-complete-milestone` | 归档里程碑并打 release tag |
|
|
||||||
| `/gsd-new-milestone [name]` | 开始下一个版本：提问 → 研究 → 需求 → 路线图 |
|
|
||||||
| `/gsd-milestone-summary` | 从已完成的里程碑产物生成项目概览，用于团队上手 |
|
|
||||||
| `/gsd-forensics` | 对失败或卡住的工作流进行事后调查 |
|
|
||||||
|
|
||||||
### 工作流（Workstreams）
|
|
||||||
|
|
||||||
| 命令 | 作用 |
|
|
||||||
|------|------|
|
|
||||||
| `/gsd-workstreams list` | 显示所有工作流及其状态 |
|
|
||||||
| `/gsd-workstreams create <name>` | 创建命名空间工作流，用于并行里程碑工作 |
|
|
||||||
| `/gsd-workstreams switch <name>` | 切换当前活跃工作流 |
|
|
||||||
| `/gsd-workstreams complete <name>` | 完成并合并工作流 |
|
|
||||||
|
|
||||||
### 多项目工作区
|
|
||||||
|
|
||||||
| 命令 | 作用 |
|
|
||||||
|------|------|
|
|
||||||
| `/gsd-workspace --new` | 创建隔离工作区，包含仓库副本（worktree 或 clone） |
|
|
||||||
| `/gsd-workspace --list` | 显示所有 GSD 工作区及其状态 |
|
|
||||||
| `/gsd-workspace --remove` | 移除工作区并清理 worktree |
|
|
||||||
|
|
||||||
### UI 设计
|
|
||||||
|
|
||||||
| 命令 | 作用 |
|
|
||||||
|------|------|
|
|
||||||
| `/gsd-ui-phase [N]` | 为前端阶段生成 UI 设计合约（UI-SPEC.md） |
|
|
||||||
| `/gsd-ui-review [N]` | 对已实现前端代码进行 6 维视觉审计 |
|
|
||||||
|
|
||||||
### 导航
|
|
||||||
|
|
||||||
| 命令 | 作用 |
|
|
||||||
|------|------|
|
|
||||||
| `/gsd-progress` | 我现在在哪？下一步是什么？ |
|
|
||||||
| `/gsd-progress --next` | 自动检测状态并执行下一步 |
|
|
||||||
| `/gsd-help` | 显示全部命令和使用指南 |
|
|
||||||
| `/gsd-update` | 更新 GSD，并预览变更日志 |
|
|
||||||
|
|
||||||
### Brownfield
|
|
||||||
|
|
||||||
| 命令 | 作用 |
|
|
||||||
|------|------|
|
|
||||||
| `/gsd-map-codebase` | 在 `new-project` 前分析现有代码库 |
|
|
||||||
|
|
||||||
### 阶段管理
|
|
||||||
|
|
||||||
| 命令 | 作用 |
|
|
||||||
|------|------|
|
|
||||||
| `/gsd-phase` | 在路线图末尾追加 phase |
|
|
||||||
| `/gsd-phase --insert [N]` | 在 phase 之间插入紧急工作 |
|
|
||||||
| `/gsd-phase --edit [N] [--force]` | 就地修改已有 phase 的任意字段 — 编号与位置保持不变 |
|
|
||||||
| `/gsd-phase --remove [N]` | 删除未来 phase，并重编号 |
|
|
||||||
| `/gsd-discuss-phase --assumptions [N]` | 在规划前查看 Claude 打算采用的方案 |
|
|
||||||
| `/gsd-audit-milestone --fix` | 为 audit 发现的缺口创建 phase |
|
|
||||||
|
|
||||||
### 代码质量
|
|
||||||
|
|
||||||
| 命令 | 作用 |
|
|
||||||
|------|------|
|
|
||||||
| `/gsd-review` | 对当前阶段或分支进行跨 AI 同行评审 |
|
|
||||||
| `/gsd-pr-branch` | 创建过滤 `.planning/` 提交的干净 PR 分支 |
|
|
||||||
| `/gsd-audit-uat` | 审计验证债务——找出缺少 UAT 的阶段 |
|
|
||||||
|
|
||||||
### 积压
|
|
||||||
|
|
||||||
| 命令 | 作用 |
|
|
||||||
|------|------|
|
|
||||||
| `/gsd-capture --seed <idea>` | 将想法存入积压停车场，留待未来里程碑 |
|
|
||||||
|
|
||||||
### 会话
|
|
||||||
|
|
||||||
| 命令 | 作用 |
|
|
||||||
|------|------|
|
|
||||||
| `/gsd-pause-work` | 在中途暂停时创建交接上下文（写入 HANDOFF.json） |
|
|
||||||
| `/gsd-resume-work` | 从上一次会话恢复 |
|
|
||||||
| `/gsd-pause-work --report` | 生成会话摘要，包含已完成工作和结果 |
|
|
||||||
|
|
||||||
### 工具
|
|
||||||
|
|
||||||
| 命令 | 作用 |
|
|
||||||
|------|------|
|
|
||||||
| `/gsd-settings` | 配置模型 profile 和工作流代理 |
|
|
||||||
| `/gsd-config --profile <profile>` | 切换模型 profile（quality / balanced / budget / inherit） |
|
|
||||||
| `/gsd-capture [desc]` | 记录一个待办想法 |
|
|
||||||
| `/gsd-capture --list` | 查看待办列表 |
|
|
||||||
| `/gsd-debug [desc]` | 使用持久状态进行系统化调试 |
|
|
||||||
| `/gsd-do <text>` | 将自由文本自动路由到正确的 GSD 命令 |
|
|
||||||
| `/gsd-note <text>` | 零摩擦想法捕捉——追加、列出或提升为待办 |
|
|
||||||
| `/gsd-quick [--full] [--discuss] [--research]` | 以 GSD 保障执行临时任务（`--full` 增加计划检查和验证，`--discuss` 先补上下文，`--research` 在规划前先调研） |
|
|
||||||
| `/gsd-health [--repair]` | 校验 `.planning/` 目录完整性，带 `--repair` 时自动修复 |
|
|
||||||
| `/gsd-stats` | 显示项目统计——阶段、计划、需求、git 指标 |
|
|
||||||
| `/gsd-profile-user [--questionnaire] [--refresh]` | 从会话分析生成开发者行为档案，用于个性化响应 |
|
|
||||||
|
|
||||||
<sup>¹ 由 reddit 用户 OracleGreyBeard 贡献</sup>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 配置
|
|
||||||
|
|
||||||
GSD 将项目设置保存在 `.planning/config.json`。你可以在 `/gsd-new-project` 时配置，也可以稍后通过 `/gsd-settings` 修改。完整的配置 schema、工作流开关、git branching 选项以及各代理的模型分配，请查看[用户指南](docs/USER-GUIDE.md#configuration-reference)。
|
|
||||||
|
|
||||||
### 核心设置
|
|
||||||
|
|
||||||
| Setting | Options | Default | 作用 |
|
|
||||||
|---------|---------|---------|------|
|
|
||||||
| `mode` | `yolo`, `interactive` | `interactive` | 自动批准，还是每一步确认 |
|
|
||||||
| `granularity` | `coarse`, `standard`, `fine` | `standard` | phase 粒度，也就是范围切分得多细 |
|
|
||||||
|
|
||||||
### 模型 Profile
|
|
||||||
|
|
||||||
控制各代理使用哪种 Claude 模型，在质量和 token 成本之间平衡。
|
|
||||||
|
|
||||||
| Profile | Planning | Execution | Verification |
|
|
||||||
|---------|----------|-----------|--------------|
|
|
||||||
| `quality` | Opus | Opus | Sonnet |
|
|
||||||
| `balanced`（默认） | Opus | Sonnet | Sonnet |
|
|
||||||
| `budget` | Sonnet | Sonnet | Haiku |
|
|
||||||
| `inherit` | Inherit | Inherit | Inherit |
|
|
||||||
|
|
||||||
切换方式：
|
|
||||||
```
|
|
||||||
/gsd-config --profile budget
|
|
||||||
```
|
|
||||||
|
|
||||||
使用非 Anthropic 提供商（OpenRouter、本地模型）时，或想跟随当前运行时的模型选择时（如 OpenCode 的 `/model`），可用 `inherit`。
|
|
||||||
|
|
||||||
也可以通过 `/gsd-settings` 配置。
|
|
||||||
|
|
||||||
### 工作流代理
|
|
||||||
|
|
||||||
这些设置会在规划或执行时拉起额外代理。它们能提升质量，但也会增加 token 消耗和耗时。
|
|
||||||
|
|
||||||
| Setting | Default | 作用 |
|
|
||||||
|---------|---------|------|
|
|
||||||
| `workflow.research` | `true` | 每个 phase 规划前先调研领域知识 |
|
|
||||||
| `workflow.plan_check` | `true` | 执行前验证计划是否真能达成阶段目标 |
|
|
||||||
| `workflow.verifier` | `true` | 执行后确认“必须交付项”是否已经落地 |
|
|
||||||
| `workflow.auto_advance` | `false` | 自动串联 discuss → plan → execute，不中途停下 |
|
|
||||||
| `workflow.research_before_questions` | `false` | 在讨论提问前先运行研究，而非之后 |
|
|
||||||
| `workflow.skip_discuss` | `false` | 在自主模式下完全跳过讨论阶段 |
|
|
||||||
| `workflow.discuss_mode` | `null` | 控制讨论阶段行为（`assumptions` 使用推断默认值） |
|
|
||||||
|
|
||||||
可以用 `/gsd-settings` 开关这些项，也可以在单次命令里覆盖：
|
|
||||||
- `/gsd-plan-phase --skip-research`
|
|
||||||
- `/gsd-plan-phase --skip-verify`
|
|
||||||
|
|
||||||
### 执行
|
|
||||||
|
|
||||||
| Setting | Default | 作用 |
|
|
||||||
|---------|---------|------|
|
|
||||||
| `parallelization.enabled` | `true` | 是否并行执行独立计划 |
|
|
||||||
| `planning.commit_docs` | `true` | 是否将 `.planning/` 纳入 git 跟踪 |
|
|
||||||
| `hooks.context_warnings` | `true` | 显示上下文窗口使用量警告 |
|
|
||||||
|
|
||||||
### Git 分支策略
|
|
||||||
|
|
||||||
控制 GSD 在执行过程中如何处理分支。
|
|
||||||
|
|
||||||
| Setting | Options | Default | 作用 |
|
|
||||||
|---------|---------|---------|------|
|
|
||||||
| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | 分支创建策略 |
|
|
||||||
| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | phase 分支模板 |
|
|
||||||
| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | milestone 分支模板 |
|
|
||||||
|
|
||||||
**策略说明：**
|
|
||||||
- **`none`**：直接提交到当前分支（GSD 默认行为）
|
|
||||||
- **`phase`**：每个 phase 创建一个分支，在 phase 完成时合并
|
|
||||||
- **`milestone`**：整个里程碑只用一个分支，在里程碑完成时合并
|
|
||||||
|
|
||||||
在里程碑完成时，GSD 会提供 squash merge（推荐）或保留历史的 merge 选项。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 安全
|
|
||||||
|
|
||||||
### 保护敏感文件
|
|
||||||
|
|
||||||
GSD 的代码库映射和分析命令会读取文件来理解你的项目。**包含机密信息的文件应当加入 Claude Code 的 deny list**：
|
|
||||||
|
|
||||||
1. 打开 Claude Code 设置（项目级 `.claude/settings.json` 或全局设置）
|
|
||||||
2. 把敏感文件模式加入 deny list：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"permissions": {
|
|
||||||
"deny": [
|
|
||||||
"Read(.env)",
|
|
||||||
"Read(.env.*)",
|
|
||||||
"Read(**/secrets/*)",
|
|
||||||
"Read(**/*credential*)",
|
|
||||||
"Read(**/*.pem)",
|
|
||||||
"Read(**/*.key)"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
这样无论你运行什么命令，Claude 都无法读取这些文件。
|
|
||||||
|
|
||||||
> [!IMPORTANT]
|
|
||||||
> GSD 内建了防止提交 secrets 的保护，但纵深防御依然是最佳实践。第一道防线应该是直接禁止读取敏感文件。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 故障排查
|
|
||||||
|
|
||||||
**安装后找不到命令？**
|
|
||||||
- 重启你的运行时，让命令或 skills 重新加载
|
|
||||||
- 检查文件是否存在于 `~/.claude/commands/gsd/`（全局）或 `./.claude/commands/gsd/`（本地）
|
|
||||||
- 对 Codex，检查 skills 是否存在于 `~/.codex/skills/gsd-*/SKILL.md`（全局）或 `./.codex/skills/gsd-*/SKILL.md`（本地）
|
|
||||||
|
|
||||||
**命令行为不符合预期？**
|
|
||||||
- 运行 `/gsd-help` 确认安装成功
|
|
||||||
- 重新执行 `npx @opengsd/gsd-core` 进行重装
|
|
||||||
|
|
||||||
**想更新到最新版本？**
|
|
||||||
```bash
|
|
||||||
npx @opengsd/gsd-core@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
**在 Docker 或容器环境中使用？**
|
|
||||||
|
|
||||||
如果使用波浪线路径（`~/.claude/...`）时读取失败，请在安装前设置 `CLAUDE_CONFIG_DIR`：
|
|
||||||
```bash
|
|
||||||
CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @opengsd/gsd-core --global
|
|
||||||
```
|
|
||||||
这样可以确保使用绝对路径，而不是在容器里可能无法正确展开的 `~`。
|
|
||||||
|
|
||||||
### 卸载
|
|
||||||
|
|
||||||
如果你想彻底移除 GSD：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 全局安装
|
|
||||||
npx @opengsd/gsd-core --claude --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --opencode --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --gemini --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --kilo --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --codex --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --copilot --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --cursor --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --antigravity --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --augment --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --trae --global --uninstall
|
|
||||||
npx @opengsd/gsd-core --cline --global --uninstall
|
|
||||||
|
|
||||||
# 本地安装（当前项目）
|
|
||||||
npx @opengsd/gsd-core --claude --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --opencode --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --gemini --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --kilo --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --codex --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --copilot --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --cursor --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --antigravity --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --augment --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --trae --local --uninstall
|
|
||||||
npx @opengsd/gsd-core --cline --local --uninstall
|
|
||||||
```
|
|
||||||
|
|
||||||
这会移除所有 GSD 命令、代理、hooks 和设置，但会保留你其他配置。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 社区移植版本
|
|
||||||
|
|
||||||
OpenCode、Gemini CLI、Kilo 和 Codex 现在都已经通过 `npx @opengsd/gsd-core` 获得原生支持。
|
|
||||||
|
|
||||||
这些社区移植版本曾率先探索多运行时支持：
|
|
||||||
|
|
||||||
| Project | Platform | Description |
|
|
||||||
|---------|----------|-------------|
|
|
||||||
| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | 最初的 OpenCode 适配版本 |
|
|
||||||
| gsd-gemini (archived) | Gemini CLI | uberfuzzy 制作的最初 Gemini 适配版本 |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -830,14 +112,14 @@ OpenCode、Gemini CLI、Kilo 和 Codex 现在都已经通过 `npx @opengsd/gsd-c
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## License
|
## 许可证
|
||||||
|
|
||||||
MIT License。详情见 [LICENSE](LICENSE)。
|
MIT 许可证。详情请参阅 [LICENSE](LICENSE)。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
**Claude Code 很强，GSD 让它变得可靠。**
|
**Claude Code 功能强大。GSD Core 让它更可靠。**
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|||||||
@@ -23,8 +23,8 @@
|
|||||||
|
|
||||||
GSD Core is a **meta-prompting framework** that sits between the user and AI coding agents (Claude Code, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code). It provides:
|
GSD Core is a **meta-prompting framework** that sits between the user and AI coding agents (Claude Code, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code). It provides:
|
||||||
|
|
||||||
1. **Context engineering** — Structured artifacts that give the AI everything it needs per task
|
1. **Context engineering** — Structured artifacts that give the AI everything it needs per task (see [Context engineering](explanation/context-engineering.md))
|
||||||
2. **Multi-agent orchestration** — Thin orchestrators that spawn specialized agents with fresh context windows
|
2. **Multi-agent orchestration** — Thin orchestrators that spawn specialized agents with fresh context windows (see [Multi-agent orchestration](explanation/multi-agent-orchestration.md))
|
||||||
3. **Spec-driven development** — Requirements → research → plans → execution → verification pipeline
|
3. **Spec-driven development** — Requirements → research → plans → execution → verification pipeline
|
||||||
4. **State management** — Persistent project memory across sessions and context resets
|
4. **State management** — Persistent project memory across sessions and context resets
|
||||||
|
|
||||||
@@ -700,6 +700,8 @@ The researcher → planner → executor pipeline includes a supply-chain gate ag
|
|||||||
|
|
||||||
### Security Hooks (v1.27)
|
### Security Hooks (v1.27)
|
||||||
|
|
||||||
|
For a conceptual overview of how the hook and guard layers fit into the broader security approach, see [Security model](explanation/security-model.md).
|
||||||
|
|
||||||
**Prompt Guard** (`gsd-prompt-guard.js`):
|
**Prompt Guard** (`gsd-prompt-guard.js`):
|
||||||
|
|
||||||
- Triggers on Write/Edit to `.planning/` files
|
- Triggers on Write/Edit to `.planning/` files
|
||||||
@@ -770,3 +772,12 @@ available. The current source snapshot is 2026-05-11:
|
|||||||
5. **Model references** — `inherit` profile lets GSD defer to runtime's model selection
|
5. **Model references** — `inherit` profile lets GSD defer to runtime's model selection
|
||||||
|
|
||||||
The installer handles all translation at install time. Workflows and agents are written in Claude Code's native format and transformed during deployment.
|
The installer handles all translation at install time. Workflows and agents are written in Claude Code's native format and transformed during deployment.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Multi-agent orchestration](explanation/multi-agent-orchestration.md)
|
||||||
|
- [Security model](explanation/security-model.md)
|
||||||
|
- [CLI tools](CLI-TOOLS.md)
|
||||||
|
- [docs index](README.md)
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# GSD CLI Tools Reference
|
# GSD CLI Tools Reference
|
||||||
|
|
||||||
> Surface-area reference for `get-shit-done/bin/gsd-tools.cjs` (Node CLI). For slash commands and user flows, see [Command Reference](COMMANDS.md).
|
> Reference for the `gsd-tools` CLI (`get-shit-done/bin/gsd-tools.cjs`). For slash commands and user flows, see [Command Reference](COMMANDS.md). Return to [docs index](README.md).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -493,7 +493,9 @@ API keys configured via `/gsd-settings` (`brave_search`, `firecrawl`, `exa_searc
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## See also
|
## Related
|
||||||
|
|
||||||
- [Architecture](ARCHITECTURE.md) — orchestration and runtime layering
|
- [Commands](COMMANDS.md)
|
||||||
- [Command Reference](COMMANDS.md) — user-facing `/gsd-` commands
|
- [Configuration](CONFIGURATION.md)
|
||||||
|
- [Architecture](ARCHITECTURE.md)
|
||||||
|
- [docs index](README.md)
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# GSD Core Command Reference
|
# GSD Core Command Reference
|
||||||
|
|
||||||
> Command syntax, flags, options, and examples for stable commands. For feature details, see [Feature Reference](FEATURES.md). For workflow walkthroughs, see [User Guide](USER-GUIDE.md).
|
> Command reference for GSD Core — syntax, flags, options, and examples for every stable command. For feature details see [Feature Reference](FEATURES.md); for workflow walkthroughs see [User Guide](USER-GUIDE.md); for the docs index see [README](README.md).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -144,7 +144,7 @@ Research, plan, and verify a phase.
|
|||||||
| `--auto` | Skip interactive confirmations |
|
| `--auto` | Skip interactive confirmations |
|
||||||
| `--research` | Force re-research even if RESEARCH.md exists |
|
| `--research` | Force re-research even if RESEARCH.md exists |
|
||||||
| `--skip-research` | Skip domain research step |
|
| `--skip-research` | Skip domain research step |
|
||||||
| `--research-phase <N>` | Research-only mode: spawn researcher for phase `<N>`, write RESEARCH.md, exit before planner. Replaces the deleted `gsd-research-phase` standalone command (#3042). |
|
| `--research-phase <N>` | Research-only mode: spawn researcher for phase `<N>`, write RESEARCH.md, exit before planner. Supersedes the deleted standalone research command (#3042). |
|
||||||
| `--view` | Research-only modifier: when used with `--research-phase`, print existing RESEARCH.md to stdout and exit (no spawn). |
|
| `--view` | Research-only modifier: when used with `--research-phase`, print existing RESEARCH.md to stdout and exit (no spawn). |
|
||||||
| `--gaps` | Gap closure mode (reads VERIFICATION.md, skips research) |
|
| `--gaps` | Gap closure mode (reads VERIFICATION.md, skips research) |
|
||||||
| `--skip-verify` | Skip plan checker verification loop |
|
| `--skip-verify` | Skip plan checker verification loop |
|
||||||
@@ -453,12 +453,7 @@ Guided MVP planning for a phase — prompts for a user story, runs SPIDR splitti
|
|||||||
|
|
||||||
**Prerequisites:** Phase must already exist in ROADMAP.md (created via `/gsd-new-project`, `/gsd-phase`, or `/gsd-phase --insert`). The command does not create new phases — it converts an existing phase.
|
**Prerequisites:** Phase must already exist in ROADMAP.md (created via `/gsd-new-project`, `/gsd-phase`, or `/gsd-phase --insert`). The command does not create new phases — it converts an existing phase.
|
||||||
|
|
||||||
**Process:**
|
**Behaviour:** Collects a structured user story, validates format, runs a SPIDR splitting check, writes `**Goal:**` and `**Mode:** mvp` to the phase's ROADMAP.md section, then delegates to `/gsd-plan-phase <N>`. See [How to plan an MVP phase](USER-GUIDE.md#mvp-phase-planning) for a walkthrough.
|
||||||
1. Prompts for "As a / I want to / So that" user story (three structured questions)
|
|
||||||
2. Validates story format against the canonical regex
|
|
||||||
3. Runs SPIDR splitting check — if the story is too large, walks through Spike/Paths/Interfaces/Data/Rules axes and offers to split into multiple phases
|
|
||||||
4. Writes `**Goal:** <user-story>` and `**Mode:** mvp` to the phase's ROADMAP.md section (with confirmation gate)
|
|
||||||
5. Delegates to `/gsd-plan-phase <N>`, which detects MVP mode automatically
|
|
||||||
|
|
||||||
**Walking Skeleton:** Auto-triggered when `--mvp` (or `mode: mvp`) is used on Phase 1 of a new project with no prior phase summaries. The planner produces `SKELETON.md` alongside `PLAN.md`.
|
**Walking Skeleton:** Auto-triggered when `--mvp` (or `mode: mvp`) is used on Phase 1 of a new project with no prior phase summaries. The planner produces `SKELETON.md` alongside `PLAN.md`.
|
||||||
|
|
||||||
@@ -815,17 +810,12 @@ v1.40.0, [#2792](https://github.com/open-gsd/gsd-core/issues/2792)).
|
|||||||
|
|
||||||
Archive accumulated phase directories from completed milestones and prune local branches whose upstream has been deleted.
|
Archive accumulated phase directories from completed milestones and prune local branches whose upstream has been deleted.
|
||||||
|
|
||||||
|
**Behaviour:** Presents a dry-run summary of phase directories to archive (moved from `.planning/phases/` into `.planning/milestones/v{X.Y}-phases/`) and local branches whose upstream is gone (pruned via `git fetch --prune`). Requires confirmation before writing any changes. The currently checked-out branch is never pruned.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
/gsd-cleanup
|
/gsd-cleanup
|
||||||
```
|
```
|
||||||
|
|
||||||
On confirmation, the workflow performs two actions:
|
|
||||||
|
|
||||||
1. **Phase archival** — moves phase directories from `.planning/phases/` into milestone archive directories under `.planning/milestones/v{X.Y}-phases/`, using archived ROADMAP snapshots to determine phase membership.
|
|
||||||
2. **Branch pruning** — runs `git fetch --prune` to update remote-tracking refs, then identifies and force-deletes local branches whose upstream is marked gone. The currently checked-out branch is always skipped.
|
|
||||||
|
|
||||||
The dry-run summary shows both phase directories to archive and candidate local branches for deletion before confirmation.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Spiking & Sketching Commands
|
## Spiking & Sketching Commands
|
||||||
@@ -1529,3 +1519,12 @@ npm run lint:descriptions
|
|||||||
```
|
```
|
||||||
|
|
||||||
The check is also run as part of `npm test` via `tests/enh-2789-description-budget.test.cjs`.
|
The check is also run as part of `npm test` via `tests/enh-2789-description-budget.test.cjs`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Configuration Reference](CONFIGURATION.md)
|
||||||
|
- [CLI Tools Reference](CLI-TOOLS.md)
|
||||||
|
- [Feature Reference](FEATURES.md)
|
||||||
|
- [Docs index](README.md)
|
||||||
|
|||||||
@@ -1,5 +1,7 @@
|
|||||||
# GSD Configuration Reference
|
# GSD Configuration Reference
|
||||||
|
|
||||||
|
Complete schema reference for `.planning/config.json`. For setup walkthroughs and task-oriented guides see the [docs index](README.md).
|
||||||
|
|
||||||
> Full configuration schema, workflow toggles, model profiles, and git branching options. For feature context, see [Feature Reference](FEATURES.md).
|
> Full configuration schema, workflow toggles, model profiles, and git branching options. For feature context, see [Feature Reference](FEATURES.md).
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -332,7 +334,9 @@ Example:
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Recommended Presets
|
### Common Setting Combinations
|
||||||
|
|
||||||
|
The following combinations of `mode`, `granularity`, `model_profile`, and workflow toggles are commonly used together. See [Configure model profiles](how-to/configure-model-profiles.md) for setup guidance.
|
||||||
|
|
||||||
| Scenario | mode | granularity | profile | research | plan_check | verifier |
|
| Scenario | mode | granularity | profile | research | plan_check | verifier |
|
||||||
|----------|------|-------------|---------|----------|------------|----------|
|
|----------|------|-------------|---------|----------|------------|----------|
|
||||||
@@ -380,11 +384,7 @@ The prompt injection guard hook (`gsd-prompt-guard.js`) is always active and can
|
|||||||
|
|
||||||
### Private Planning Setup
|
### Private Planning Setup
|
||||||
|
|
||||||
To keep planning artifacts out of git:
|
When `planning.commit_docs` is `false` and `.planning/` is listed in `.gitignore`, GSD treats planning artefacts as local-only. `planning.search_gitignored: true` ensures broad searches still include the `.planning/` directory in this configuration. See [Configure private planning](how-to/configure-model-profiles.md) for setup steps.
|
||||||
|
|
||||||
1. Set `planning.commit_docs: false` and `planning.search_gitignored: true`
|
|
||||||
2. Add `.planning/` to `.gitignore`
|
|
||||||
3. If previously tracked: `git rm -r --cached .planning/ && git commit -m "chore: stop tracking planning docs"`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -486,19 +486,7 @@ The `plan_review.*` namespace controls the plan drift guard, which verifies that
|
|||||||
|
|
||||||
#### Multi-developer setup
|
#### Multi-developer setup
|
||||||
|
|
||||||
If multiple developers will rebuild the graph in the same repo, run once per
|
When multiple developers rebuild the graph in the same repository, `graphify hook install` (run once per clone) installs a git merge driver that union-merges concurrent `graph.json` writes, eliminating conflict markers. It also registers the post-commit rebuild hook, writes `.gitattributes`, and adds `graphify merge-driver` to `.git/config`. Solo projects may skip this step. Introduced upstream in graphify v0.7.0 alongside the `built_at_commit` freshness signal surfaced by `/gsd-graphify status`.
|
||||||
clone after enabling graphify:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
graphify hook install
|
|
||||||
```
|
|
||||||
|
|
||||||
This installs a git merge driver that union-merges concurrent `graph.json`
|
|
||||||
writes (no conflict markers in the knowledge graph), plus the post-commit
|
|
||||||
rebuild hook. It writes `.gitattributes` and registers `graphify
|
|
||||||
merge-driver` in `.git/config`. Solo projects can skip this step; running it
|
|
||||||
anyway is harmless. Introduced upstream in graphify v0.7.0 alongside the
|
|
||||||
`built_at_commit` freshness signal that `/gsd-graphify status` surfaces.
|
|
||||||
|
|
||||||
#### Commit-based staleness
|
#### Commit-based staleness
|
||||||
|
|
||||||
@@ -557,7 +545,7 @@ The `features.*` namespace is a dynamic key pattern — new feature flags can be
|
|||||||
| `next_phases` | YAML flow array | Phases the `next_action` applies to (e.g. `["4.5"]`) |
|
| `next_phases` | YAML flow array | Phases the `next_action` applies to (e.g. `["4.5"]`) |
|
||||||
| `progress` | block | Nested `total_phases` / `completed_phases` / `percent` for the milestone progress bar |
|
| `progress` | block | Nested `total_phases` / `completed_phases` / `percent` for the milestone progress bar |
|
||||||
|
|
||||||
All four fields are **optional and additive** — STATE.md files without them keep rendering exactly as in v1.38.x. See [`STATE-MD-LIFECYCLE.md`](STATE-MD-LIFECYCLE.md) for the full field reference, parser constraints, and rendering scenes.
|
All four fields are **optional and additive** — STATE.md files without them keep rendering exactly as in v1.38.x. See [STATE.md schema](reference/state-md.md) for the full field reference, parser constraints, and rendering scenes.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -1372,3 +1360,12 @@ GSD_AUDIT_ARGS=1 GSD_AUDIT=1 gsd plan --tdd
|
|||||||
```
|
```
|
||||||
|
|
||||||
`GSD_AUDIT_ARGS` applies to both the stderr error line and the audit file simultaneously.
|
`GSD_AUDIT_ARGS` applies to both the stderr error line and the audit file simultaneously.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Commands](COMMANDS.md)
|
||||||
|
- [Configure model profiles](how-to/configure-model-profiles.md)
|
||||||
|
- [STATE.md schema](reference/state-md.md)
|
||||||
|
- [Docs index](README.md)
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# GSD Feature Reference
|
# GSD Feature Reference
|
||||||
|
|
||||||
> Complete feature and function documentation with requirements. For architecture details, see [Architecture](ARCHITECTURE.md). For command syntax, see [Command Reference](COMMANDS.md).
|
> Feature index and reference for GSD Core. For architecture details, see [Architecture](ARCHITECTURE.md). For command syntax, see [Command Reference](COMMANDS.md). Return to [docs index](README.md).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -2667,7 +2667,7 @@ Users who run a memory / knowledge-base MCP server (for example, ExoCortex-style
|
|||||||
- REQ-LIFECYCLE-02: `formatGsdState()` checks the lifecycle fields in priority order and emits the first matching scene (Phase active → Idle next-recommended → Milestone complete → Default fallback).
|
- REQ-LIFECYCLE-02: `formatGsdState()` checks the lifecycle fields in priority order and emits the first matching scene (Phase active → Idle next-recommended → Milestone complete → Default fallback).
|
||||||
- REQ-LIFECYCLE-03: All four fields default to undefined; existing STATE.md files render byte-for-byte identically.
|
- REQ-LIFECYCLE-03: All four fields default to undefined; existing STATE.md files render byte-for-byte identically.
|
||||||
|
|
||||||
**Reference issue:** [#2833](https://github.com/open-gsd/gsd-core/issues/2833) — see [`docs/STATE-MD-LIFECYCLE.md`](STATE-MD-LIFECYCLE.md) for the full field reference and rendering rules.
|
**Reference issue:** [#2833](https://github.com/open-gsd/gsd-core/issues/2833) — see [`docs/STATE-MD-LIFECYCLE.md`](reference/state-md.md) for the full field reference and rendering rules.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -3009,4 +3009,12 @@ explicit reviewer flags -> --all -> review.default_reviewers -> all detected rev
|
|||||||
- REQ-JSON-ERRORS-02: CLI exit code mapping MUST remain stable for automation callers.
|
- REQ-JSON-ERRORS-02: CLI exit code mapping MUST remain stable for automation callers.
|
||||||
- REQ-JSON-ERRORS-03: Human-readable output MUST remain the default when `--json-errors` is absent.
|
- REQ-JSON-ERRORS-03: Human-readable output MUST remain the default when `--json-errors` is absent.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Commands](COMMANDS.md)
|
||||||
|
- [Configuration](CONFIGURATION.md)
|
||||||
|
- [docs index](README.md)
|
||||||
|
|
||||||
**Reference:** [JSON Error Mode](json-errors.md)
|
**Reference:** [JSON Error Mode](json-errors.md)
|
||||||
|
|||||||
@@ -8,6 +8,8 @@
|
|||||||
- This file enumerates every shipped surface across all six families (agents, commands, workflows, references, CLI modules, hooks). Broad docs may render narrative or curated subsets; when they disagree with the filesystem, this file and the directory listings are authoritative.
|
- This file enumerates every shipped surface across all six families (agents, commands, workflows, references, CLI modules, hooks). Broad docs may render narrative or curated subsets; when they disagree with the filesystem, this file and the directory listings are authoritative.
|
||||||
- New surfaces added after v1.36.0 should land here first, then propagate to the broad docs. The drift-control tests in `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`, and `tests/command-count-sync.test.cjs` anchor the counts and roster contents against the filesystem.
|
- New surfaces added after v1.36.0 should land here first, then propagate to the broad docs. The drift-control tests in `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`, and `tests/command-count-sync.test.cjs` anchor the counts and roster contents against the filesystem.
|
||||||
|
|
||||||
|
This is the authoritative roster of every shipped GSD Core surface. See the [docs index](README.md) to navigate by topic.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Agents (33 shipped)
|
## Agents (33 shipped)
|
||||||
@@ -484,3 +486,9 @@ Full listing: `hooks/`.
|
|||||||
- When a new command, agent, workflow, reference, CLI module, or hook ships, update the corresponding section here before the release is cut.
|
- When a new command, agent, workflow, reference, CLI module, or hook ships, update the corresponding section here before the release is cut.
|
||||||
- The drift-guard tests under `tests/` (see "How To Use This File" above) assert that every shipped file is enumerated in this inventory. A new file without a matching row here will fail CI.
|
- The drift-guard tests under `tests/` (see "How To Use This File" above) assert that every shipped file is enumerated in this inventory. A new file without a matching row here will fail CI.
|
||||||
- When the filesystem diverges from `docs/ARCHITECTURE.md` counts or from curated-subset docs (e.g. `docs/AGENTS.md`'s primary roster), this file is the source of truth.
|
- When the filesystem diverges from `docs/ARCHITECTURE.md` counts or from curated-subset docs (e.g. `docs/AGENTS.md`'s primary roster), this file is the source of truth.
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Commands](COMMANDS.md) — user-facing command reference
|
||||||
|
- [Architecture](ARCHITECTURE.md) — how the surfaces fit together
|
||||||
|
- [docs index](README.md)
|
||||||
|
|||||||
@@ -1,36 +1,69 @@
|
|||||||
# GSD Core Documentation
|
# GSD Core documentation
|
||||||
|
|
||||||
Comprehensive documentation for GSD Core (Git. Ship. Done.) — a meta-prompting, context engineering, and spec-driven development system for AI coding agents.
|
Documentation is organised into four quadrants: **tutorials** help you learn by doing, **how-to guides** solve specific tasks, **reference** states authoritative facts, and **explanation** explores concepts and design decisions.
|
||||||
|
|
||||||
Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) · [日本語](ja-JP/README.md) · [简体中文](zh-CN/README.md)
|
Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) · [日本語](ja-JP/README.md) · [简体中文](zh-CN/README.md)
|
||||||
|
|
||||||
## Documentation Index
|
---
|
||||||
|
|
||||||
| Document | Audience | Description |
|
## Tutorials
|
||||||
|----------|----------|-------------|
|
|
||||||
| [Architecture](ARCHITECTURE.md) | Contributors, advanced users | System architecture, agent model, data flow, and internal design |
|
|
||||||
| [Installer Migrations](installer-migrations.md) | Contributors | Architecture for safe install-time migrations, cleanup, preservation, dry-run planning, and rollback |
|
|
||||||
| [Feature Reference](FEATURES.md) | All users | Feature narratives and requirements for released features |
|
|
||||||
| [Command Reference](COMMANDS.md) | All users | Stable commands with syntax, flags, options, and examples |
|
|
||||||
| [Configuration Reference](CONFIGURATION.md) | All users | Full config schema, workflow toggles, model profiles, git branching |
|
|
||||||
| [Custom PR Body Sections](ship-pr-body-sections.md) | All users | How to append project-specific PRD sections to `/gsd-ship` PR bodies |
|
|
||||||
| [CLI Tools Reference](CLI-TOOLS.md) | Contributors, agent authors | `gsd-tools.cjs` programmatic API for workflows and agents |
|
|
||||||
| [JSON Error Mode](json-errors.md) | Contributors, agent authors | Machine-readable `gsd-tools --json-errors` failure envelopes |
|
|
||||||
| [Agent Reference](AGENTS.md) | Contributors, advanced users | Role cards for primary agents — roles, tools, spawn patterns (the `agents/` filesystem is authoritative) |
|
|
||||||
| [User Guide](USER-GUIDE.md) | All users | Workflow walkthroughs, troubleshooting, and recovery |
|
|
||||||
| [Issue-Driven Orchestration](issue-driven-orchestration.md) | All users | Recipe for driving GSD from a tracker issue (GitHub / Linear / Jira) using existing primitives — no new commands or daemon |
|
|
||||||
| [Context Monitor](context-monitor.md) | All users | Context window monitoring hook architecture |
|
|
||||||
| [Discuss Mode](workflow-discuss-mode.md) | All users | Assumptions vs interview mode for discuss-phase |
|
|
||||||
| [Canary Stream](CANARY.md) | Maintainers | Archived stream notes; current public npm tags are `latest` and `next` |
|
|
||||||
|
|
||||||
## Quick Links
|
- [Your first project](tutorials/your-first-project.md) — install to first shipped phase, one guaranteed path
|
||||||
|
- [Onboarding an existing codebase](tutorials/onboarding-an-existing-codebase.md) — bring GSD Core to a brownfield repo
|
||||||
|
|
||||||
- **What's new:** install `@opengsd/gsd-core@latest` and use the npm/package version as the current source of truth; older release-note files are archived continuity notes
|
---
|
||||||
- **Preview streams:** current public npm tags are `latest` and `next`; older canary notes are archived in [Canary Stream](CANARY.md)
|
|
||||||
- **Getting started:** [README](../README.md) → install → `/gsd-new-project`
|
## How-to guides
|
||||||
- **Full workflow walkthrough:** [User Guide](USER-GUIDE.md)
|
|
||||||
- **All commands at a glance:** [Command Reference](COMMANDS.md)
|
- [Install on your runtime](how-to/install-on-your-runtime.md) — runtime-specific install steps for all 15 supported runtimes
|
||||||
- **Configuring GSD:** [Configuration Reference](CONFIGURATION.md)
|
- [Discuss a phase](how-to/discuss-a-phase.md) — capture implementation decisions before planning begins
|
||||||
- **Customizing ship PR bodies:** [Custom PR Body Sections](ship-pr-body-sections.md)
|
- [Plan a phase](how-to/plan-a-phase.md) — run research, decompose work, and verify plan quality
|
||||||
- **How the system works internally:** [Architecture](ARCHITECTURE.md)
|
- [Execute a phase](how-to/execute-a-phase.md) — run plans in parallel waves with fresh-context subagents
|
||||||
- **Contributing or extending:** [CLI Tools Reference](CLI-TOOLS.md) + [Agent Reference](AGENTS.md)
|
- [Verify and ship](how-to/verify-and-ship.md) — walk through completed work, diagnose failures, and create the PR
|
||||||
|
- [Run phases autonomously](how-to/run-phases-autonomously.md) — use autonomous mode for unattended phase execution
|
||||||
|
- [Handle quick and fast tasks](how-to/handle-quick-and-fast-tasks.md) — use `/gsd-quick` and `/gsd-fast` for ad-hoc work outside the phase loop
|
||||||
|
- [Configure model profiles](how-to/configure-model-profiles.md) — switch between quality, balanced, and budget model tiers
|
||||||
|
- [Set up cross-AI review](how-to/set-up-cross-ai-review.md) — configure a second AI to review code produced by the primary agent
|
||||||
|
- [Work in parallel with workstreams](how-to/work-in-parallel-with-workstreams.md) — run independent lines of work simultaneously using workstreams
|
||||||
|
- [Isolate work with workspaces](how-to/isolate-work-with-workspaces.md) — use workspaces to sandbox experimental or risky changes
|
||||||
|
- [Debug a failed execution](how-to/debug-a-failed-execution.md) — diagnose and recover from broken or incomplete phase execution
|
||||||
|
- [Spike and sketch](how-to/spike-and-sketch.md) — use `/gsd-spike` and `/gsd-sketch` for exploratory work before committing to a plan
|
||||||
|
- [Design a UI phase](how-to/design-a-ui-phase.md) — use the UI phase loop for frontend and visual work
|
||||||
|
- [Drive GSD from a tracker issue](how-to/drive-gsd-from-a-tracker-issue.md) — start a phase from a GitHub, Linear, or Jira issue
|
||||||
|
- [Migrate from GSD 2](how-to/migrate-from-gsd-2.md) — upgrade an existing GSD 2 project to GSD Core
|
||||||
|
- [Update GSD](how-to/update-gsd.md) — re-run the installer to pick up the latest release
|
||||||
|
- [Recover and troubleshoot](how-to/recover-and-troubleshoot.md) — fix common problems, rebuild context, and uninstall
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Reference
|
||||||
|
|
||||||
|
- [Commands](COMMANDS.md) — every command with flags and examples
|
||||||
|
- [Configuration](CONFIGURATION.md) — full config schema, model profiles, git branching strategies
|
||||||
|
- [CLI tools](CLI-TOOLS.md) — `gsd-tools.cjs` programmatic API for workflows and agents
|
||||||
|
- [Features](FEATURES.md) — complete feature index
|
||||||
|
- [Inventory](INVENTORY.md) — installed skills and surface map
|
||||||
|
- [STATE.md schema](reference/state-md.md) — field-by-field reference for `.planning/STATE.md`
|
||||||
|
- [CONTEXT.md schema](reference/context-md.md) — field-by-field reference for `.planning/phases/<N>/CONTEXT.md`
|
||||||
|
- [PLAN.md schema](reference/plan-md.md) — field-by-field reference for `.planning/phases/<N>/PLAN.md`
|
||||||
|
- [Planning artifacts](reference/planning-artifacts.md) — all `.planning/` files and their roles
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Explanation
|
||||||
|
|
||||||
|
- [Context engineering](explanation/context-engineering.md) — how context rot forms and how GSD Core prevents it
|
||||||
|
- [The phase loop](explanation/the-phase-loop.md) — design rationale for the Discuss → Plan → Execute → Verify → Ship cycle
|
||||||
|
- [Multi-agent orchestration](explanation/multi-agent-orchestration.md) — how subagents are spawned, scoped, and coordinated
|
||||||
|
- [Security model](explanation/security-model.md) — trust boundaries, permissions, and safe automation
|
||||||
|
- [Architecture](ARCHITECTURE.md) — system architecture, agent model, and data flow
|
||||||
|
- [Discuss modes](workflow-discuss-mode.md) — assumptions mode vs interview mode for `/gsd-discuss-phase`
|
||||||
|
- [Context monitoring](context-monitor.md) — context window monitoring hook architecture
|
||||||
|
- [Issue-driven orchestration](issue-driven-orchestration.md) — recipe for driving GSD from a tracker issue using existing primitives
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Root README](../README.md) — landing page, quickstart, and documentation overview
|
||||||
|
- [Changelog](../CHANGELOG.md) — release history
|
||||||
|
|||||||
@@ -1,179 +0,0 @@
|
|||||||
# STATE.md Phase Lifecycle Frontmatter
|
|
||||||
|
|
||||||
> **Status:** Read-side shipped in v1.40.0 (issue
|
|
||||||
> [#2833](https://github.com/open-gsd/gsd-core/issues/2833)).
|
|
||||||
> `parseStateMd()` reads the four frontmatter fields below and
|
|
||||||
> `formatGsdState()` renders the in-flight / idle / progress scenes.
|
|
||||||
> SDK write-side support to maintain the fields automatically is tracked
|
|
||||||
> separately.
|
|
||||||
|
|
||||||
GSD's `STATE.md` carries YAML frontmatter that the status-line hook reads on
|
|
||||||
every render. This document describes the **phase-lifecycle fields** and the
|
|
||||||
rendering scenes they trigger.
|
|
||||||
|
|
||||||
All four lifecycle fields are **optional and additive**. Existing `STATE.md`
|
|
||||||
files (without these fields) keep rendering exactly as they did before — no
|
|
||||||
visual change, no migration required.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Frontmatter fields
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
gsd_state_version: 1.0
|
|
||||||
milestone: v2.0 # existing
|
|
||||||
milestone_name: Code Quality # existing
|
|
||||||
status: in_progress # existing — see "status semantics" below
|
|
||||||
|
|
||||||
# Phase-lifecycle additions (issue #2833) — all optional
|
|
||||||
active_phase: null # phase number when an orchestrator is in flight
|
|
||||||
next_action: execute-phase # next recommended command when idle
|
|
||||||
next_phases: ["4.5"] # phases that next_action applies to (1-2 ids)
|
|
||||||
|
|
||||||
progress: # nested block (existing key, percent now opt-in for the bar)
|
|
||||||
total_phases: 17
|
|
||||||
completed_phases: 10
|
|
||||||
percent: 59
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
### Field reference
|
|
||||||
|
|
||||||
| Field | Type | When populated | When null/absent |
|
|
||||||
|---|---|---|---|
|
|
||||||
| `active_phase` | string (e.g. `"4.5"`) | An orchestrator command is in flight on this phase | Idle between phases |
|
|
||||||
| `next_action` | string | Idle, with a recommended command (`discuss-phase` / `plan-phase` / `execute-phase` / `verify-phase`) | An orchestrator is in flight, OR no recommendation available |
|
|
||||||
| `next_phases` | YAML flow array (e.g. `["4.5"]`) | Goes with `next_action` — phases the action applies to | Same as above |
|
|
||||||
| `progress.percent` | integer 0-100 | Milestone progress in **phase dimension** (`completed_phases / total_phases`) | Bar rendering is opt-in — absent → no bar |
|
|
||||||
|
|
||||||
### `next_phases` parser scope
|
|
||||||
|
|
||||||
Only **single-line YAML flow** is parsed: `next_phases: ["4.5", "4.6"]`.
|
|
||||||
|
|
||||||
Block sequences over multiple lines (`- 4.5\n - 4.6`) are intentionally
|
|
||||||
**not parsed** — the status-line only needs the primary recommendation, and a
|
|
||||||
single-line array keeps the regex-based parser predictable. If a project needs
|
|
||||||
to track many candidate next phases for documentation purposes, store the
|
|
||||||
extra ones in the `STATE.md` body.
|
|
||||||
|
|
||||||
### `progress.percent` dimension
|
|
||||||
|
|
||||||
The bar rendered next to the milestone version reflects **phase completion**
|
|
||||||
(`completed_phases / total_phases`), not plan completion.
|
|
||||||
|
|
||||||
Plan dimension (`completed_plans / total_plans`) trends optimistic for any
|
|
||||||
project where future phases haven't been planned yet — `total_plans` only
|
|
||||||
counts plans inside *already-planned* phases, so the denominator is
|
|
||||||
structurally smaller than reality. Reporting that number to stakeholders
|
|
||||||
overstates progress.
|
|
||||||
|
|
||||||
If a project wants to show plan-level progress somewhere, store it elsewhere
|
|
||||||
in frontmatter or the body — the status-line bar is reserved for the
|
|
||||||
phase-dimension number that matches `ROADMAP.md` progress tables and
|
|
||||||
`MILESTONES.md`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Status-line rendering scenes
|
|
||||||
|
|
||||||
`formatGsdState()` checks the lifecycle fields in the order below and emits
|
|
||||||
the **first matching scene**. If none match, the renderer falls through to
|
|
||||||
the original `<status> · <phase>` format (byte-for-byte unchanged from
|
|
||||||
v1.38.x).
|
|
||||||
|
|
||||||
| Scene | Trigger | Display |
|
|
||||||
|---|---|---|
|
|
||||||
| **1. Phase active** | `active_phase` populated | `v2.0 [██░░░] X% · Phase 4.5 executing` |
|
|
||||||
| **2. Idle, next recommended** | `active_phase` null AND `next_action` + `next_phases` populated | `v2.0 [██░░░] X% · next execute-phase 4.5` |
|
|
||||||
| **3. Milestone complete** | `percent: 100` OR `completed_phases == total_phases` | `v2.0 [██████████] 100% · milestone complete` |
|
|
||||||
| **4. Default fallback** | None of the above | `v1.9 Code Quality · executing · ph (1/5)` (existing format) |
|
|
||||||
|
|
||||||
### Scene priority example
|
|
||||||
|
|
||||||
When both `active_phase` and `next_action` are populated, **Scene 1 wins** —
|
|
||||||
an orchestrator is in flight, so any "next recommendation" would be misleading.
|
|
||||||
This is enforced by check order in `formatGsdState()` and by tests in
|
|
||||||
`tests/enh-2833-phase-lifecycle-statusline.test.cjs` (suite *"scene priority"*).
|
|
||||||
|
|
||||||
### Stage labels in Scene 1
|
|
||||||
|
|
||||||
In Scene 1, the second part of `Phase 4.5 <stage>` is whichever value is in
|
|
||||||
the `status` field at that moment. The convention proposed in issue #2833
|
|
||||||
is to use the lifecycle stage:
|
|
||||||
|
|
||||||
| Command | `status` value while in flight |
|
|
||||||
|---|---|
|
|
||||||
| `/gsd-discuss-phase` | `discussing` |
|
|
||||||
| `/gsd-plan-phase` | `planning` |
|
|
||||||
| `/gsd-execute-phase` | `executing` |
|
|
||||||
| `/gsd-verify-work` | `verifying` |
|
|
||||||
|
|
||||||
If `status` is left at `in_progress` (the milestone-level value), Scene 1
|
|
||||||
renders just `Phase 4.5` without the stage suffix.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Frontmatter parsing constraints
|
|
||||||
|
|
||||||
The status-line hook uses regex-based parsing (no full YAML library), so a
|
|
||||||
few constraints apply:
|
|
||||||
|
|
||||||
1. **Frontmatter must start at the very first character of the file.**
|
|
||||||
Anything (including comments) above the opening `---` invalidates the
|
|
||||||
match. The opening `---` line must be exactly that — no trailing spaces.
|
|
||||||
|
|
||||||
2. **Comments inside nested blocks are not supported.**
|
|
||||||
The parser for `progress:` requires the next line to be `[ \t]+\w+:` —
|
|
||||||
inserting `# comment` between `progress:` and the first key breaks the
|
|
||||||
match and the bar disappears. Put any documentation in the body of
|
|
||||||
`STATE.md`, not inside frontmatter blocks.
|
|
||||||
|
|
||||||
3. **`next_phases` accepts only single-line flow format.**
|
|
||||||
See the parser scope note above.
|
|
||||||
|
|
||||||
These constraints are tested in
|
|
||||||
`tests/enh-2833-phase-lifecycle-statusline.test.cjs`. If a future change
|
|
||||||
swaps the regex parser for a real YAML library, the constraints can be
|
|
||||||
relaxed and the tests updated accordingly.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Backward compatibility
|
|
||||||
|
|
||||||
This document describes additive fields. The promise is:
|
|
||||||
|
|
||||||
- A `STATE.md` file with **none** of the lifecycle fields populated renders
|
|
||||||
**byte-for-byte identically** to v1.38.x and earlier.
|
|
||||||
- Adding any lifecycle field is **opt-in per project** — the renderer falls
|
|
||||||
through to the existing format when fields are absent.
|
|
||||||
- The progress bar is opt-in even when `progress` block exists — only
|
|
||||||
`progress.percent` triggers the bar; `total_phases` / `completed_phases`
|
|
||||||
alone don't.
|
|
||||||
|
|
||||||
The `formatGsdState #2833 backward compatibility` test suite locks this
|
|
||||||
guarantee in: any change that breaks legacy `STATE.md` rendering will fail
|
|
||||||
the suite.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Related issues / PRs
|
|
||||||
|
|
||||||
- **#1989** — *enhancement: surface GSD state in statusline.* The foundation
|
|
||||||
this proposal extends. Established that `STATE.md` frontmatter drives the
|
|
||||||
status-line.
|
|
||||||
- **#2833** — *enhancement: phase-lifecycle status-line — auto-rotate
|
|
||||||
STATE.md frontmatter as phase orchestrators progress.* This document
|
|
||||||
describes the read-side spec from that issue. Write-side SDK / workflow
|
|
||||||
changes to auto-maintain the fields are tracked separately so each piece
|
|
||||||
can be reviewed independently.
|
|
||||||
|
|
||||||
Companion read-side issues this proposal also helps close (each fixed a
|
|
||||||
specific symptom of the same gap):
|
|
||||||
|
|
||||||
- #1102 — STATE.md frontmatter plan counts only update on plan completion
|
|
||||||
- #1103 — STATE.md status / last_activity not updated when a phase starts
|
|
||||||
- #1446 / #1572 — phase complete doesn't update Plans column
|
|
||||||
- #612 — ROADMAP.md not updating
|
|
||||||
- #956 — planning document drift across core workflows
|
|
||||||
- #2018 — verify-work doesn't auto-transition (fixed for verify only)
|
|
||||||
1260
docs/USER-GUIDE.md
1260
docs/USER-GUIDE.md
File diff suppressed because it is too large
Load Diff
@@ -74,7 +74,7 @@ Locked sub-decisions:
|
|||||||
- **Hard-block on any MISSING (as originally proposed).** Rejected for rung 0–1: false positives from dynamic/re-exported/generated symbols would block valid plans and get the default-on guard switched off. Retained only for rung >=3.
|
- **Hard-block on any MISSING (as originally proposed).** Rejected for rung 0–1: false positives from dynamic/re-exported/generated symbols would block valid plans and get the default-on guard switched off. Retained only for rung >=3.
|
||||||
|
|
||||||
## References
|
## References
|
||||||
- Issue: open-gsd/gsd-core#22 (migrated from gsd-build/get-shit-done#3813)
|
- Issue: open-gsd/gsd-core#22 (migrated from open-gsd/gsd-core#3813)
|
||||||
- Relates to #3802 (GitNexus first-class code intelligence) — rung 4 backend
|
- Relates to #3802 (GitNexus first-class code intelligence) — rung 4 backend
|
||||||
- arXiv:2409.20550 — hallucination taxonomy + RAG mitigation (modest gains)
|
- arXiv:2409.20550 — hallucination taxonomy + RAG mitigation (modest gains)
|
||||||
- arXiv:2502.05111 — grammar-constrained decoding (soft vs hard constraints)
|
- arXiv:2502.05111 — grammar-constrained decoding (soft vs hard constraints)
|
||||||
|
|||||||
@@ -60,54 +60,9 @@ GSD's `/gsd-pause-work` command saves execution state. The WARNING message sugge
|
|||||||
|
|
||||||
## Setup
|
## Setup
|
||||||
|
|
||||||
Both hooks are automatically registered during `npx @opengsd/gsd-core` installation:
|
Both hooks are registered automatically during `npx @opengsd/gsd-core` installation — no manual steps are needed under normal circumstances. For hook configuration details, threshold overrides, and manual registration examples, see [Configuration](CONFIGURATION.md).
|
||||||
|
|
||||||
- **Statusline** (writes bridge file): Registered as `statusLine` in settings.json
|
As a brief reference: the statusline hook registers as `statusLine` in `settings.json`; the context monitor (`gsd-context-monitor.js`) registers as a `PostToolUse` hook (or `AfterTool` for Gemini CLI). Both entries use the absolute Node executable path that ran the installer. On Windows PowerShell, prefix quoted executable paths with `&`.
|
||||||
- **Context Monitor** (reads bridge file): Registered as `PostToolUse` hook in settings.json (`AfterTool` for Gemini)
|
|
||||||
|
|
||||||
Manual registration should use the absolute Node executable path that ran the installer. On Windows PowerShell, prefix the command with `&` when that executable path is quoted.
|
|
||||||
|
|
||||||
Manual registration in `~/.claude/settings.json` (Claude Code):
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"statusLine": {
|
|
||||||
"type": "command",
|
|
||||||
"command": "\"/usr/local/bin/node\" \"/Users/me/.claude/hooks/gsd-statusline.js\""
|
|
||||||
},
|
|
||||||
"hooks": {
|
|
||||||
"PostToolUse": [
|
|
||||||
{
|
|
||||||
"hooks": [
|
|
||||||
{
|
|
||||||
"type": "command",
|
|
||||||
"command": "\"/usr/local/bin/node\" \"/Users/me/.claude/hooks/gsd-context-monitor.js\""
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
For Gemini CLI (`~/.gemini/settings.json`), use `AfterTool` instead of `PostToolUse`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"hooks": {
|
|
||||||
"AfterTool": [
|
|
||||||
{
|
|
||||||
"hooks": [
|
|
||||||
{
|
|
||||||
"type": "command",
|
|
||||||
"command": "& \"C:/Program Files/nodejs/node.exe\" \"C:/Users/me/.gemini/hooks/gsd-context-monitor.js\""
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Safety
|
## Safety
|
||||||
|
|
||||||
@@ -115,3 +70,11 @@ For Gemini CLI (`~/.gemini/settings.json`), use `AfterTool` instead of `PostTool
|
|||||||
- It never blocks tool execution — a broken monitor should not break the agent's workflow
|
- It never blocks tool execution — a broken monitor should not break the agent's workflow
|
||||||
- Stale metrics (older than 60s) are ignored
|
- Stale metrics (older than 60s) are ignored
|
||||||
- Missing bridge files are handled gracefully (subagents, fresh sessions)
|
- Missing bridge files are handled gracefully (subagents, fresh sessions)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Architecture](ARCHITECTURE.md)
|
||||||
|
- [Configuration](CONFIGURATION.md)
|
||||||
|
- [docs index](README.md)
|
||||||
|
|||||||
90
docs/explanation/context-engineering.md
Normal file
90
docs/explanation/context-engineering.md
Normal file
@@ -0,0 +1,90 @@
|
|||||||
|
# Context engineering
|
||||||
|
|
||||||
|
> Why GSD Core exists, and the problem it is designed to solve.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The problem: context rot
|
||||||
|
|
||||||
|
Every AI coding session starts fresh. The model reads your question, reasons over it, and replies. But a session is rarely one exchange. You ask follow-up questions, paste error messages, iterate on code, redirect the model when it drifts. Each turn adds tokens to the context window — the finite buffer of text the model can "see" at once.
|
||||||
|
|
||||||
|
As that window fills, something subtle happens. The model does not fail loudly. It keeps answering. But the quality of its answers quietly degrades. Early instructions get pushed towards the edge of what it can attend to. Nuance from the first few exchanges — the constraints you stated, the architecture you agreed on, the edge cases you flagged — competes for attention against everything that came later. Researchers call this **context rot**.
|
||||||
|
|
||||||
|
Context rot manifests in several ways:
|
||||||
|
|
||||||
|
- The model starts contradicting earlier decisions it acknowledged.
|
||||||
|
- Code style drifts away from the conventions established at session start.
|
||||||
|
- Plans begin to ignore requirements that were clearly stated but are now buried deep in the history.
|
||||||
|
- The model hallucinates file names or function signatures it had correct twenty messages ago.
|
||||||
|
|
||||||
|
None of this is a model bug. It is a fundamental property of how transformer attention works over long sequences. The model is not forgetting — it never "remembered" in the human sense. It is weighting relevance across a finite window, and as that window fills with accumulated noise, signal-to-noise degrades.
|
||||||
|
|
||||||
|
The naive response is to `/clear` and start over. But that loses continuity. You have to re-explain context, re-paste relevant files, re-state constraints. The session essentially resets to zero.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## GSD Core's answer: fresh-context subagents
|
||||||
|
|
||||||
|
GSD Core's central insight is that *most* of the work in a coding session does not need to happen in the main context at all. Research, planning, code writing, and verification are each discrete, bounded tasks. Each can be handed to a specialised subagent that starts with a clean, carefully scoped context window — and reports its result back to a thin orchestrator that stays lean.
|
||||||
|
|
||||||
|
This is not a workaround for context rot. It is a structural solution.
|
||||||
|
|
||||||
|
The orchestrator — your main session — never touches source files. It spawns agents, collects their results, updates shared state, and routes to the next step. Because it does very little itself, its context window grows slowly and predictably. The heavy work happens in agents that each start fresh, receive exactly the context they need for their task, and terminate when done.
|
||||||
|
|
||||||
|
Consider what this means in practice. When you run `/gsd-plan-phase`, the orchestrator:
|
||||||
|
|
||||||
|
1. Loads a compact JSON context payload (project summary, phase goal, relevant config).
|
||||||
|
2. Spawns a researcher agent with a 200k-token clean window.
|
||||||
|
3. Spawns a planner agent with the research output and phase requirements.
|
||||||
|
4. Spawns a plan-checker agent to verify the plan before execution.
|
||||||
|
|
||||||
|
Each agent operates at full capacity, unencumbered by the accumulated history of your session. When the planner writes its `PLAN.md` files to `.planning/phases/`, that output becomes a durable artefact — not a fragile memory in a shared context window.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Spec-driven development and meta-prompting
|
||||||
|
|
||||||
|
Context engineering alone is not enough. If an agent starts fresh but receives vague instructions, it will produce vague output. GSD Core pairs fresh-context subagents with two complementary disciplines:
|
||||||
|
|
||||||
|
**Spec-driven development** means that every phase produces structured artefacts before execution begins. A `CONTEXT.md` captures implementation decisions from the Discuss step. A `RESEARCH.md` records what the researcher found. A `PLAN.md` breaks work into discrete, dependency-ordered tasks with explicit acceptance criteria. By the time an executor agent touches a file, it has a precise specification to work from — not a re-interpretation of a long conversation.
|
||||||
|
|
||||||
|
**Meta-prompting** means the agent definitions themselves are carefully engineered prompts, not ad-hoc instructions. The files in `get-shit-done/workflows/` and `agents/` encode hard-won knowledge about how to scope tasks, what to verify, and when to escalate to a human checkpoint. The user does not need to re-explain this knowledge in every session; it is baked into the system's own prompts.
|
||||||
|
|
||||||
|
The combination is deliberate. Fresh context ensures each agent reasons clearly. Spec-driven artefacts ensure each agent reasons about the *right* thing. Meta-prompting ensures each agent knows *how* to reason about it well.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The role of `.planning/`
|
||||||
|
|
||||||
|
Context engineering requires that knowledge survive context resets. GSD Core uses the file system for this. Every meaningful output is written to `.planning/` as human-readable Markdown or JSON. This means:
|
||||||
|
|
||||||
|
- Restarting your session (or the model crashing) does not lose work.
|
||||||
|
- Any subsequent agent can read prior artefacts directly, without depending on a shared conversation history.
|
||||||
|
- You can inspect, edit, or commit planning artefacts to git — they are plain text, not opaque state in a database.
|
||||||
|
|
||||||
|
`STATE.md` is the spine of this system. It records the project's current position (which milestone, which phase, which plans are complete), active decisions and blockers, and progress metrics. When any workflow starts, it reads `STATE.md` to orient itself. When any workflow finishes a meaningful step, it writes back to `STATE.md`. Agents do not rely on memory; they rely on the file.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Trade-offs
|
||||||
|
|
||||||
|
Honesty about trade-offs matters here.
|
||||||
|
|
||||||
|
**Overhead.** The phase loop introduces real friction. Running `/gsd-discuss-phase`, `/gsd-plan-phase`, and `/gsd-execute-phase` as separate steps takes more elapsed time than typing "write this feature" into a plain session. For a small, well-understood change, that overhead is not justified.
|
||||||
|
|
||||||
|
**Latency.** Spawning multiple subagents with fresh context is slower than a single in-context edit. Research, planning, and execution each incur round-trip costs.
|
||||||
|
|
||||||
|
**Ceremony for simple tasks.** If you need to rename a variable, fix a typo, or add a missing import, the phase loop is overkill. GSD Core provides `/gsd-quick` and `/gsd-fast` for ad-hoc work that does not warrant a full phase. See [Handle quick and fast tasks](../how-to/handle-quick-and-fast-tasks.md).
|
||||||
|
|
||||||
|
The phase loop pays for itself when the work is complex enough that context rot is a real risk — multi-file features, cross-cutting refactors, work that spans hours or sessions. For everything else, reach for the lighter primitive.
|
||||||
|
|
||||||
|
A useful rule of thumb: if the task could be fully specified in a single, short prompt and completed in one agent turn without further clarification, skip the phase loop. If the task requires research, involves files you have not read recently, or depends on decisions that are not yet settled, the phase loop protects you.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [The phase loop](the-phase-loop.md) — how the Discuss → Plan → Execute → Verify → Ship cycle puts context engineering into practice
|
||||||
|
- [Multi-agent orchestration](multi-agent-orchestration.md) — how subagents are spawned, scoped, and coordinated
|
||||||
|
- [Architecture](../ARCHITECTURE.md) — system architecture, agent model, and data flow
|
||||||
|
- [docs index](../README.md)
|
||||||
234
docs/explanation/multi-agent-orchestration.md
Normal file
234
docs/explanation/multi-agent-orchestration.md
Normal file
@@ -0,0 +1,234 @@
|
|||||||
|
# Multi-agent orchestration in GSD Core
|
||||||
|
|
||||||
|
> **Explanation** — This document describes *why* GSD Core is designed around
|
||||||
|
> multi-agent orchestration and *how the pieces fit together*. It is not a
|
||||||
|
> step-by-step guide. For configuration, see
|
||||||
|
> [Configure model profiles](../how-to/configure-model-profiles.md) and the
|
||||||
|
> [Configuration reference](../CONFIGURATION.md). For the full agent roster,
|
||||||
|
> see [Inventory](../INVENTORY.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The problem this design solves
|
||||||
|
|
||||||
|
AI coding agents degrade. Not because the model gets worse, but because the
|
||||||
|
*context window fills up*. As a conversation grows, earlier decisions and code
|
||||||
|
get pushed out or diluted by the noise of intermediate steps. By the time an
|
||||||
|
agent writes the fifth file in a complex task, it may have already forgotten
|
||||||
|
the constraint stated in the first message. This is sometimes called *context
|
||||||
|
rot*.
|
||||||
|
|
||||||
|
GSD Core's multi-agent design is a direct response to that problem. Instead of
|
||||||
|
one long-running agent carrying the whole session, a thin orchestrator spawns
|
||||||
|
short-lived specialised agents, each with a **fresh 200 K-token context window**
|
||||||
|
and *only the artifacts it needs* to do its specific job. The orchestrator
|
||||||
|
never does heavy lifting itself; it loads context, spawns the right agent,
|
||||||
|
collects the result, and updates shared state in `.planning/`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The orchestrator → agent pattern
|
||||||
|
|
||||||
|
Every workflow in `get-shit-done/workflows/` follows the same shape:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Orchestrator (workflow .md file)
|
||||||
|
│
|
||||||
|
├── Load context
|
||||||
|
│ gsd-tools.cjs init <workflow> <phase>
|
||||||
|
│ → JSON: project info, config, state, phase details
|
||||||
|
│
|
||||||
|
├── Resolve model
|
||||||
|
│ gsd-tools.cjs resolve-model <agent-name>
|
||||||
|
│ → opus | sonnet | haiku | inherit
|
||||||
|
│
|
||||||
|
├── Spawn specialised agent (Task/SubAgent call)
|
||||||
|
│ ├── Agent definition (agents/*.md)
|
||||||
|
│ ├── Context payload (init JSON)
|
||||||
|
│ ├── Model assignment
|
||||||
|
│ └── Tool permissions
|
||||||
|
│
|
||||||
|
├── Collect result
|
||||||
|
│
|
||||||
|
└── Update state
|
||||||
|
gsd-tools.cjs state update / state patch / state advance-plan
|
||||||
|
```
|
||||||
|
|
||||||
|
The orchestrator is deliberately thin. It does not reason about the domain,
|
||||||
|
does not write code, and does not interpret results beyond routing them to the
|
||||||
|
next step. That boundary keeps each layer's responsibility clear and prevents
|
||||||
|
the orchestrator's context from accumulating domain noise.
|
||||||
|
|
||||||
|
### The agent roster
|
||||||
|
|
||||||
|
GSD Core's agents fall into functional categories that map onto the
|
||||||
|
research → plan → execute → verify pipeline:
|
||||||
|
|
||||||
|
| Category | Agents | Typical parallelism |
|
||||||
|
|---|---|---|
|
||||||
|
| Researchers | `gsd-project-researcher`, `gsd-phase-researcher`, `gsd-ui-researcher`, `gsd-advisor-researcher` | 4 parallel (stack, features, architecture, pitfalls) |
|
||||||
|
| Synthesisers | `gsd-research-synthesizer` | Sequential, after researchers complete |
|
||||||
|
| Planners | `gsd-planner`, `gsd-roadmapper` | Sequential |
|
||||||
|
| Checkers | `gsd-plan-checker`, `gsd-integration-checker`, `gsd-ui-checker`, `gsd-nyquist-auditor` | Sequential, up to 3 revision iterations |
|
||||||
|
| Executors | `gsd-executor` | Parallel within a wave, sequential across waves |
|
||||||
|
| Verifiers | `gsd-verifier` | Sequential, after all executors complete |
|
||||||
|
| Mappers | `gsd-codebase-mapper` | 4 parallel sub-probes |
|
||||||
|
| Auditors | `gsd-ui-auditor`, `gsd-security-auditor` | Sequential |
|
||||||
|
|
||||||
|
Each agent definition (in `agents/*.md`) declares its allowed tool access,
|
||||||
|
purpose, and colour for terminal output. An agent that only needs to read files
|
||||||
|
and write a single output document gets exactly those permissions — no Bash
|
||||||
|
execution, no access to broader state. That constraint is intentional: it
|
||||||
|
keeps the blast radius small if an agent behaves unexpectedly.
|
||||||
|
|
||||||
|
For the complete 31-agent roster, see [Inventory](../INVENTORY.md#agents-31-shipped).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Wave-based parallel execution
|
||||||
|
|
||||||
|
The most visible expression of multi-agent design is how `/gsd-execute-phase`
|
||||||
|
handles a set of plans that may depend on one another.
|
||||||
|
|
||||||
|
Before spawning any executor, the orchestrator performs a **wave analysis**:
|
||||||
|
it reads the dependency declarations in each `PLAN.md` file and groups plans
|
||||||
|
into waves. Plans with no declared dependencies form Wave 1 and run in
|
||||||
|
parallel. Plans that depend on Wave 1 form Wave 2, and so on.
|
||||||
|
|
||||||
|
```text
|
||||||
|
Plan 01 (no deps) ─┐
|
||||||
|
Plan 02 (no deps) ─┤─── Wave 1 (parallel)
|
||||||
|
Plan 03 (depends: 01) ─┤─── Wave 2 (waits for Wave 1)
|
||||||
|
Plan 04 (depends: 02) ─┘
|
||||||
|
Plan 05 (depends: 03, 04) ─── Wave 3 (waits for Wave 2)
|
||||||
|
```
|
||||||
|
|
||||||
|
Each executor within a wave:
|
||||||
|
|
||||||
|
- receives a fresh context window (200 K tokens, or up to 1 M on capable models)
|
||||||
|
- receives the specific `PLAN.md` it is responsible for
|
||||||
|
- receives project context (`PROJECT.md`, `STATE.md`)
|
||||||
|
- receives phase context (`CONTEXT.md`, `RESEARCH.md` if available)
|
||||||
|
- produces atomic git commits on completion
|
||||||
|
- writes a `SUMMARY.md` describing what was built
|
||||||
|
|
||||||
|
After all executors in a wave finish, the orchestrator runs the pre-commit
|
||||||
|
hook once for the wave as a whole. Executors commit with `--no-verify` to
|
||||||
|
prevent build-lock contention (for example, Cargo lock fights in Rust
|
||||||
|
projects) when multiple agents commit in parallel. The hook therefore runs
|
||||||
|
once per wave rather than once per commit.
|
||||||
|
|
||||||
|
### Parallel commit safety
|
||||||
|
|
||||||
|
Two mechanisms prevent write conflicts when multiple executors run
|
||||||
|
simultaneously:
|
||||||
|
|
||||||
|
1. **Atomic lock on `STATE.md`** — Every write to `STATE.md` uses a
|
||||||
|
lockfile (`STATE.md.lock`) with `O_EXCL` atomic creation. This prevents
|
||||||
|
the read-modify-write race where two agents each read the file, modify
|
||||||
|
different fields, and the later writer overwrites the earlier one's
|
||||||
|
changes. Stale locks (older than 10 seconds) are automatically cleared.
|
||||||
|
|
||||||
|
2. **Per-wave hook run** — Rather than each executor running pre-commit hooks
|
||||||
|
independently (which can cause file-level contention on shared build
|
||||||
|
artefacts), the orchestrator runs `git hook run pre-commit` once after
|
||||||
|
every wave completes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Adaptive context enrichment for large-window models
|
||||||
|
|
||||||
|
Standard 200 K context windows are enough for an executor to implement a
|
||||||
|
single focused plan. When the configured `context_window` is 500 K tokens or
|
||||||
|
larger (for example, when using Opus 4.6 or Sonnet 4.6 in 1 M-class mode),
|
||||||
|
the orchestrator automatically enriches subagent prompts with additional
|
||||||
|
context that would not fit in a standard window:
|
||||||
|
|
||||||
|
- **Executor agents** receive prior-wave `SUMMARY.md` files and the phase
|
||||||
|
`CONTEXT.md`/`RESEARCH.md`, giving them cross-plan awareness within the
|
||||||
|
phase
|
||||||
|
- **Verifier agents** receive all `PLAN.md`, `SUMMARY.md`, and `CONTEXT.md`
|
||||||
|
files plus `REQUIREMENTS.md`, enabling history-aware verification
|
||||||
|
|
||||||
|
This enrichment is conditional on the `context_window` value in
|
||||||
|
`config.json`. On standard-window configurations, prompts use truncated
|
||||||
|
versions with cache-friendly ordering to maximise token efficiency.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Why this design — the connection to context engineering
|
||||||
|
|
||||||
|
The orchestrator → agent pattern only makes sense as part of a broader
|
||||||
|
approach to *context engineering*: the idea that what an AI agent gets in its
|
||||||
|
context window matters as much as the model tier or prompt quality. See
|
||||||
|
[Context engineering](context-engineering.md) for the full treatment.
|
||||||
|
|
||||||
|
Multi-agent orchestration operationalises context engineering in two ways:
|
||||||
|
|
||||||
|
**Context isolation.** Each agent receives only what it needs. A researcher
|
||||||
|
gets the project description and domain questions; it does not get the full
|
||||||
|
planning history. A verifier gets every plan and summary; it does not get the
|
||||||
|
raw research. Isolation keeps each agent's context dense with signal rather
|
||||||
|
than diluted by noise from other pipeline stages.
|
||||||
|
|
||||||
|
**Context hygiene across sessions.** Because all state lives in
|
||||||
|
`.planning/` as human-readable Markdown and JSON (not in any agent's context
|
||||||
|
window), GSD workflows survive context resets (`/clear`), tab switches, and
|
||||||
|
multi-day breaks. The next agent always starts from persisted, verified
|
||||||
|
artifacts rather than from a reconstructed memory of a long conversation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Trade-offs
|
||||||
|
|
||||||
|
Multi-agent orchestration is not free.
|
||||||
|
|
||||||
|
**Coordination overhead.** Each agent spawn is a round-trip: the orchestrator
|
||||||
|
must format a prompt, hand off context, wait for the subagent to complete
|
||||||
|
(typically 1–5 minutes), and then parse the result. A single capable agent
|
||||||
|
working in one context would finish faster for simple tasks. GSD mitigates
|
||||||
|
this by making parallelism the default wherever dependencies permit — the
|
||||||
|
four researchers in a `plan-phase` run simultaneously, not sequentially.
|
||||||
|
|
||||||
|
**Opacity during execution.** While a subagent is running, its work is
|
||||||
|
invisible to the parent session. There is no live progress stream. This is a
|
||||||
|
deliberate consequence of the fresh-context design: the subagent is operating
|
||||||
|
in its own context window. The orchestrator shows a liveness note on the
|
||||||
|
spawn line ("runs in a subagent — no output until it returns") to set
|
||||||
|
expectations.
|
||||||
|
|
||||||
|
**Context stitching cost.** Packaging the right artifacts for each agent
|
||||||
|
requires the orchestrator to spend tokens assembling and transmitting context
|
||||||
|
payloads. This is the cost of isolation. The `gsd-tools.cjs init` handler
|
||||||
|
produces a JSON payload that balances completeness with token budget, applying
|
||||||
|
cache-friendly ordering so that the stable parts of the payload (project
|
||||||
|
definition, config) hit the cache on repeat invocations.
|
||||||
|
|
||||||
|
**Model cost amplification.** Running five agents in parallel at Opus tier
|
||||||
|
costs more than running one. The model profile system (`model_profiles.md`,
|
||||||
|
resolved per agent by `model-profiles.cjs`) lets you assign cheaper tiers to
|
||||||
|
less critical agents. The `dynamic_routing` feature further reduces cost by
|
||||||
|
starting every agent on a cheaper tier and escalating only on a soft failure.
|
||||||
|
See [Configuration](../CONFIGURATION.md) for the full options.
|
||||||
|
|
||||||
|
In return for these costs, the design buys *consistent quality across large
|
||||||
|
phases*. An executor writing the tenth file in a 400-line plan does not
|
||||||
|
degrade because its context is fresh. A verifier checking twenty requirements
|
||||||
|
does not forget the first ten because it received all of them as structured
|
||||||
|
input rather than conversation history.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Context engineering](context-engineering.md) — the upstream principle that
|
||||||
|
motivates this design
|
||||||
|
- [Configure model profiles](../how-to/configure-model-profiles.md) — how to
|
||||||
|
assign model tiers per agent
|
||||||
|
- [Configuration reference](../CONFIGURATION.md) — full `config.json` schema
|
||||||
|
including `models`, `model_overrides`, `dynamic_routing`, and
|
||||||
|
`context_window`
|
||||||
|
- [Inventory](../INVENTORY.md) — authoritative agent roster and workflow list
|
||||||
|
- [Architecture](../ARCHITECTURE.md#agent-model) — implementation-level detail
|
||||||
|
on the orchestrator → agent pattern and wave execution model
|
||||||
|
- [Docs index](../README.md)
|
||||||
252
docs/explanation/security-model.md
Normal file
252
docs/explanation/security-model.md
Normal file
@@ -0,0 +1,252 @@
|
|||||||
|
# GSD Core security model
|
||||||
|
|
||||||
|
> **Explanation** — This document describes *why* GSD Core has the security
|
||||||
|
> posture it does and *how the layers fit together*. It is not a reference for
|
||||||
|
> every hook parameter. For the `/gsd-secure-phase` command and its options,
|
||||||
|
> see [Commands](../COMMANDS.md). For the implementation-level hook
|
||||||
|
> architecture, see [Architecture § Hook System](../ARCHITECTURE.md#hook-system).
|
||||||
|
> For the org-wide security baseline (scanner controls, incident checklists,
|
||||||
|
> ownership model), see [SECURITY.md](../../SECURITY.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Why AI-driven development needs a dedicated security posture
|
||||||
|
|
||||||
|
A conventional code editor does not execute arbitrary packages on your behalf.
|
||||||
|
GSD Core does. The research → plan → execute pipeline automates the full path
|
||||||
|
from "name a package" to "run `npm install <package>`", from "write a
|
||||||
|
planning artifact" to "use that artifact as an LLM system prompt". Each
|
||||||
|
automation step removes a human from the loop — and each removal is a
|
||||||
|
potential attack surface.
|
||||||
|
|
||||||
|
GSD Core's security model is built around one organising principle:
|
||||||
|
**defence in depth**. No single control is assumed to be perfect. Several
|
||||||
|
overlapping layers each reduce a distinct class of risk, and together they
|
||||||
|
make the attack surface substantially harder to exploit without eliminating
|
||||||
|
it entirely. The honest summary at the end of this document explains what the
|
||||||
|
system cannot protect against.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Layer 1 — Supply-chain protection: the Package Legitimacy Gate
|
||||||
|
|
||||||
|
### The threat
|
||||||
|
|
||||||
|
AI models hallucinate package names. This is not a fringe failure mode: 2025
|
||||||
|
research documents roughly 20 % of AI-generated package references as
|
||||||
|
hallucinated names that do not correspond to legitimate packages. A subset of
|
||||||
|
those hallucinated names — approximately 43 % in the same research — recur
|
||||||
|
consistently across prompts, meaning an attacker can observe which names AI
|
||||||
|
tools commonly produce and pre-register those names on npm, PyPI, or
|
||||||
|
crates.io with malicious post-install scripts. The technique is called
|
||||||
|
*slopsquatting*.
|
||||||
|
|
||||||
|
The insidious quality of slopsquatting is that a hallucinated name that passes
|
||||||
|
`npm view` *looks legitimate*. The registry entry proves only that someone
|
||||||
|
registered the name — not that the package does what the AI said it does, not
|
||||||
|
that it has any legitimate users, and not that its install scripts are safe.
|
||||||
|
Without a gate, a hallucinated name would flow undetected through GSD's
|
||||||
|
researcher → planner → executor pipeline and eventually run as
|
||||||
|
`npm install <attacker-package>` on your machine.
|
||||||
|
|
||||||
|
### How the gate works
|
||||||
|
|
||||||
|
The gate operates across three pipeline stages:
|
||||||
|
|
||||||
|
**Research stage.** When `gsd-phase-researcher` recommends external packages,
|
||||||
|
it runs `slopcheck install <pkgs> --json` against each one. The results are
|
||||||
|
written to a `## Package Legitimacy Audit` table in `RESEARCH.md`. Packages
|
||||||
|
tagged `[SLOP]` (high-confidence hallucination or attacker-registered) are
|
||||||
|
**stripped from `RESEARCH.md` entirely** before the file is saved. They never
|
||||||
|
reach the planner.
|
||||||
|
|
||||||
|
**Planning stage.** `gsd-planner` reads the Audit table. For any package
|
||||||
|
tagged `[SUS]` (suspicious: newly registered, low download count, no source
|
||||||
|
repository, or naming pattern close to a popular package) or `[ASSUMED]`
|
||||||
|
(sourced from WebSearch rather than direct registry verification), the planner
|
||||||
|
**inserts a `checkpoint:human-verify` task** before the install step. The
|
||||||
|
checkpoint includes a direct link to the registry page and specific things to
|
||||||
|
look for: maintainer history, issue-tracker activity, absence of suspicious
|
||||||
|
install scripts.
|
||||||
|
|
||||||
|
**Execution stage.** If an install fails, `gsd-executor` **surfaces a
|
||||||
|
checkpoint and stops**. It does not silently try an alternative package name —
|
||||||
|
which could itself be malicious. This is an explicit rule in the executor's
|
||||||
|
behaviour (RULE 3 in the executor agent definition).
|
||||||
|
|
||||||
|
### Why WebSearch packages are always `[ASSUMED]`
|
||||||
|
|
||||||
|
Package names discovered through WebSearch are tagged `[ASSUMED]` regardless
|
||||||
|
of whether `npm view` succeeds. A package that exists on the registry is not
|
||||||
|
the same as a package that is safe to install. `npm view` proves registration,
|
||||||
|
not legitimacy. The `[ASSUMED]` tag triggers the same human-verify checkpoint
|
||||||
|
as `[SUS]`, ensuring that any unverified web-discovered recommendation always
|
||||||
|
gets a human review before installation.
|
||||||
|
|
||||||
|
### Ecosystem coverage
|
||||||
|
|
||||||
|
The researcher uses registry-specific verification commands rather than a
|
||||||
|
single generic check:
|
||||||
|
|
||||||
|
- Node.js: `npm view`
|
||||||
|
- Python: `pip index versions`
|
||||||
|
- Rust: `cargo search`
|
||||||
|
|
||||||
|
This covers cross-ecosystem hallucination, which occurs at roughly 9 %
|
||||||
|
according to 2025 USENIX research — cases where an AI recommends a package
|
||||||
|
that exists in one ecosystem but not the one actually in use.
|
||||||
|
|
||||||
|
### Graceful degradation
|
||||||
|
|
||||||
|
If `slopcheck` is unavailable (not installed, or the pip install fails at
|
||||||
|
research time), GSD applies the strictest possible fallback: **every
|
||||||
|
recommended package is tagged `[ASSUMED]`**, and the planner gates every
|
||||||
|
install with a `checkpoint:human-verify` task. Research and planning proceed
|
||||||
|
normally — the system never hard-fails on a missing tool dependency. This
|
||||||
|
is intentionally stricter than the normal flow: slopcheck unavailability means
|
||||||
|
every package install gets a human checkpoint.
|
||||||
|
|
||||||
|
The `slopcheck` tool is MIT-licensed and pip-installable. If it is ever
|
||||||
|
abandoned, the `[ASSUMED]`-gate fallback ensures human-checkpoint coverage is
|
||||||
|
maintained regardless.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Layer 2 — Prompt injection defences
|
||||||
|
|
||||||
|
### The threat
|
||||||
|
|
||||||
|
GSD Core generates Markdown files that become LLM system prompts. The
|
||||||
|
research pipeline reads external web content; the planning pipeline
|
||||||
|
incorporates user-supplied text (`--text-file`, `--prd`); the execution
|
||||||
|
pipeline writes planning artifacts that are later re-read as agent context.
|
||||||
|
Any user-controlled text flowing into these artifacts is a potential
|
||||||
|
**indirect prompt injection** vector — an attacker-controlled string that,
|
||||||
|
once inside a system prompt, attempts to override the agent's instructions or
|
||||||
|
exfiltrate information.
|
||||||
|
|
||||||
|
### How the defences work
|
||||||
|
|
||||||
|
GSD Core addresses prompt injection at three levels.
|
||||||
|
|
||||||
|
**Input validation (`security.cjs`).** The `get-shit-done/bin/lib/security.cjs`
|
||||||
|
module is the central security utility. It provides:
|
||||||
|
|
||||||
|
- Path traversal prevention: user-supplied file paths (`--text-file`, `--prd`)
|
||||||
|
are validated to resolve within the project directory, with macOS
|
||||||
|
`/var` → `/private/var` symlink resolution handled explicitly
|
||||||
|
- Prompt injection detection: known injection patterns (role overrides,
|
||||||
|
instruction bypasses, system tag injections) are scanned in user-supplied
|
||||||
|
text before it enters any planning artifact
|
||||||
|
- Safe JSON parsing: a wrapper that prevents prototype-pollution attacks via
|
||||||
|
crafted JSON payloads
|
||||||
|
- Shell argument validation: arguments passed to subshell commands are
|
||||||
|
validated before use
|
||||||
|
|
||||||
|
**Runtime hook: `gsd-prompt-guard.js`.** This hook fires on every Write or
|
||||||
|
Edit call that targets `.planning/` files. It scans the content being written
|
||||||
|
for the same injection patterns as `security.cjs` (a subset inlined directly
|
||||||
|
into the hook for independence — the hook does not `require()` the module, so
|
||||||
|
it runs even if the module path changes). Detection is **advisory-only**: the
|
||||||
|
hook logs the finding but does not block the write. The rationale is that a
|
||||||
|
false-positive block on a legitimate planning write would be more disruptive
|
||||||
|
than a missed injection in a secondary scan layer.
|
||||||
|
|
||||||
|
**Runtime hook: `gsd-read-injection-scanner.js`.** This hook fires on the
|
||||||
|
output of every Read tool call. It scans the *content that was just read* for
|
||||||
|
injected instructions in untrusted content — catching cases where an attacker
|
||||||
|
has embedded instructions in a file that GSD is about to incorporate into an
|
||||||
|
agent's context.
|
||||||
|
|
||||||
|
**CI scanner.** `prompt-injection-scan.test.cjs` scans all agent, workflow,
|
||||||
|
and command files for embedded injection vectors as part of the test suite.
|
||||||
|
This catches injection attempts in the GSD source itself — for example, a
|
||||||
|
supply-chain attack that modified a workflow file to add a role-override
|
||||||
|
instruction.
|
||||||
|
|
||||||
|
### Read Injection Scanner vs Prompt Guard
|
||||||
|
|
||||||
|
The two hooks cover complementary surfaces. `gsd-prompt-guard.js` watches
|
||||||
|
*writes to planning artifacts* — it catches injection being planted.
|
||||||
|
`gsd-read-injection-scanner.js` watches *reads of any file* — it catches
|
||||||
|
injection being ingested from external content (a dependency's README, a
|
||||||
|
third-party config file, a user-provided document). Together they bracket
|
||||||
|
the ingest → store → re-read lifecycle.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Layer 3 — Repository and dependency integrity
|
||||||
|
|
||||||
|
Upstream of GSD's runtime behaviour, the `open-gsd` organisation enforces
|
||||||
|
controls at the repository and package level. These are documented in full in
|
||||||
|
[`docs/security/baseline.md`](../security/baseline.md) and are summarised
|
||||||
|
here for completeness.
|
||||||
|
|
||||||
|
**Dependency integrity.** All third-party dependencies are pinned via
|
||||||
|
`package-lock.json` and verified against published checksums before install.
|
||||||
|
A `scripts/check-npm-integrity.cjs` gate detects invalid versions, missing
|
||||||
|
packages, and extraneous packages at CI time. This mitigates dependency
|
||||||
|
confusion and typosquatting attacks against GSD's own dependencies.
|
||||||
|
|
||||||
|
**Secret scanning.** Every commit and PR is scanned for hardcoded secrets.
|
||||||
|
Intentional test fixtures must be annotated with the project-standard
|
||||||
|
exclusion grammar (see `SECURITY.md` for the annotation format). Un-annotated
|
||||||
|
suppressions fail CI.
|
||||||
|
|
||||||
|
**Locale-safe text scanning.** Output and user-facing strings are scanned for
|
||||||
|
Unicode homoglyphs, bidirectional override characters, and invisible Unicode —
|
||||||
|
the class of attacks documented in CVE-2021-42574 ("Trojan Source") that can
|
||||||
|
hide malicious content in diffs.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Trade-offs and limits
|
||||||
|
|
||||||
|
The security model described here meaningfully reduces the attack surface for
|
||||||
|
AI-driven development. It does not eliminate supply-chain risk.
|
||||||
|
|
||||||
|
**What the Package Legitimacy Gate reduces:** The probability that a
|
||||||
|
hallucinated or attacker-registered package reaches `npm install` without
|
||||||
|
a human checkpoint. The `[SLOP]` gate removes high-confidence bad packages
|
||||||
|
entirely; the `[SUS]` / `[ASSUMED]` gates require human review before
|
||||||
|
execution. This substantially raises the cost of a successful slopsquatting
|
||||||
|
attack.
|
||||||
|
|
||||||
|
**What the Package Legitimacy Gate does not eliminate:** A legitimate package
|
||||||
|
that is later compromised (account takeover, dependency confusion in its own
|
||||||
|
tree) is not caught by slopcheck, which checks registration signals at
|
||||||
|
research time. Lock files and `npm audit` at the dependency-integrity layer
|
||||||
|
are the controls for that class of attack.
|
||||||
|
|
||||||
|
**What the prompt injection defences reduce:** The probability that
|
||||||
|
user-controlled text in planning artifacts successfully overrides agent
|
||||||
|
instructions. Pattern-matching on known injection forms catches the
|
||||||
|
common cases; novel jailbreaks or low-signal injections may pass undetected.
|
||||||
|
The advisory-only posture means detection is logged but not blocked — a
|
||||||
|
deliberate choice that preserves workflow continuity at the cost of
|
||||||
|
not hard-stopping on a detection.
|
||||||
|
|
||||||
|
**What the prompt injection defences do not eliminate:** A sufficiently
|
||||||
|
creative injection that does not match known patterns, or an injection that
|
||||||
|
arrives through a channel the hooks do not cover (for example, content injected
|
||||||
|
into a dependency's published README that is read by a subagent browsing
|
||||||
|
documentation). Defence in depth means each layer makes the attack harder,
|
||||||
|
not that any single layer makes it impossible.
|
||||||
|
|
||||||
|
**Reporting vulnerabilities.** Report via private GitHub security advisory at
|
||||||
|
`https://github.com/open-gsd/gsd-core/security/advisories/new`. Do not open
|
||||||
|
public issues. See [SECURITY.md](../../SECURITY.md) for the response timeline
|
||||||
|
and disclosure policy.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Commands](../COMMANDS.md) — includes `/gsd-secure-phase` and
|
||||||
|
`/gsd-code-review` with security-relevant flags
|
||||||
|
- [Architecture § Hook System](../ARCHITECTURE.md#hook-system) —
|
||||||
|
implementation detail on every hook, its event trigger, and safety properties
|
||||||
|
- [SECURITY.md](../../SECURITY.md) — vulnerability reporting, org-wide
|
||||||
|
security baseline, secret-scan exclusion governance, and dependency
|
||||||
|
integrity verification
|
||||||
|
- [Docs index](../README.md)
|
||||||
129
docs/explanation/the-phase-loop.md
Normal file
129
docs/explanation/the-phase-loop.md
Normal file
@@ -0,0 +1,129 @@
|
|||||||
|
# The phase loop
|
||||||
|
|
||||||
|
> The central mental model for how GSD Core organises work.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What the loop is
|
||||||
|
|
||||||
|
GSD Core structures all development work as a repeating cycle:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Discuss → (UI design) → Plan → Execute → Verify → Ship
|
||||||
|
```
|
||||||
|
|
||||||
|
Every unit of work — called a **phase** — moves through these steps in order. The loop is not a formality. Each step exists because it guards against a specific class of failure that the previous step alone cannot prevent.
|
||||||
|
|
||||||
|
This document explains *why* the loop is shaped the way it is. For instructions on running each step, see the how-to guides linked at the bottom.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Why each step exists
|
||||||
|
|
||||||
|
### Discuss
|
||||||
|
|
||||||
|
Planning cannot begin until you know *how* to build the thing, not just *what* to build. The phase goal in `ROADMAP.md` describes the outcome. The Discuss step captures the implementation decisions that shape the path to that outcome: which libraries, which error-handling strategy, whether a feature is per-route or global, how edge cases should behave.
|
||||||
|
|
||||||
|
Without a Discuss step, the planner must make these calls itself. Sometimes it guesses right. Often it guesses plausibly but wrongly — producing a plan that is coherent but misaligned with your actual preferences. By the time execution is done and you realise the error, you are unwinding significant work.
|
||||||
|
|
||||||
|
The Discuss step is deliberately lightweight. It is a conversation, not a specification exercise. The output is a `CONTEXT.md` in the phase directory: a structured record of decisions that the planner, executor, and verifier can all read. The conversation takes a few minutes; it can save hours of rework.
|
||||||
|
|
||||||
|
### UI design (optional)
|
||||||
|
|
||||||
|
For phases with a visual component, there is an optional `/gsd-ui-phase` step between Discuss and Plan. It produces a `UI-SPEC.md` — a design contract that describes layout, interaction, and visual behaviour before any code is written. This step is worth running when the UI is complex enough that ambiguity in the design would produce divergent implementation choices. A clear design contract is far cheaper to write than to re-implement.
|
||||||
|
|
||||||
|
### Plan
|
||||||
|
|
||||||
|
The Plan step does the research, decomposition, and structural thinking that execution requires. It runs as a sequence of fresh-context subagents: a researcher that investigates the ecosystem and records findings in `RESEARCH.md`, a planner that reads both the research and the `CONTEXT.md` to produce `PLAN.md` files, and a plan-checker that verifies the plans are complete, consistent, and within scope.
|
||||||
|
|
||||||
|
What does a plan contain? Each `PLAN.md` describes a bounded unit of work: the files to touch, the specific changes to make, the acceptance criteria that define done. Plans are ordered into dependency waves so that parallel execution is safe — executors in the same wave touch non-overlapping concerns.
|
||||||
|
|
||||||
|
The Plan step is the moment when ambiguity is most expensive. An ambiguous plan produces an executor that makes assumptions. Multiple parallel executors making different assumptions about the same concern produce conflicts. The plan-checker's job is to catch these before execution begins, not after.
|
||||||
|
|
||||||
|
### Execute
|
||||||
|
|
||||||
|
Execution runs the plans. Each executor gets a fresh 200k-token context window loaded with exactly what it needs: the project summary, the phase context, the research, and the specific `PLAN.md` for its task. Nothing more.
|
||||||
|
|
||||||
|
Executors write code and commit atomically. Each commit corresponds to a completed task in a plan. When a wave of parallel executors finishes, the orchestrator merges their state and starts the next wave.
|
||||||
|
|
||||||
|
The executor's fresh context is not a convenience — it is the mechanism by which context rot is prevented. An executor that runs with 180k tokens of accumulated session history is a degraded executor. An executor that starts clean and reads only what its plan requires is an executor operating at full capacity.
|
||||||
|
|
||||||
|
### Verify
|
||||||
|
|
||||||
|
After all executors have completed, a verifier agent reads the phase goal, the `CONTEXT.md` decisions, the plans, and the execution summaries — and checks that what was built matches what was intended. It produces a `VERIFICATION.md` and, if there are discrepancies, generates targeted fix plans.
|
||||||
|
|
||||||
|
Verification is not just testing. It checks requirement coverage (were all the REQ-IDs addressed?), decision coverage (were the decisions captured in `CONTEXT.md` actually implemented?), and overall phase goal alignment. A phase is not done because execution finished without errors. It is done because what was built is what was planned, and what was planned is what was decided.
|
||||||
|
|
||||||
|
### Ship
|
||||||
|
|
||||||
|
The Ship step creates the pull request and archives the phase artefacts. `STATE.md` is updated to mark the phase complete. The loop then begins again for the next phase.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Milestones and phases
|
||||||
|
|
||||||
|
A **milestone** is a version cycle — a meaningful, releasable increment of the project. It has a name, a version number, and a set of requirements that define what it must deliver. A milestone is complete when all its phases are shipped and its requirements are covered.
|
||||||
|
|
||||||
|
A **phase** is one unit of work within a milestone. A phase has a goal, a set of requirements it addresses, and a set of plans that implement it.
|
||||||
|
|
||||||
|
The relationship matters because milestones and phases have different scopes of concern. A milestone asks: "What does this version of the product do, and what does it not do?" A phase asks: "What is the next bounded thing we can research, plan, execute, and verify?"
|
||||||
|
|
||||||
|
Milestone boundaries are drawn at natural product boundaries — a deployable API, a working UI flow, a complete data model. Phase boundaries are drawn at the limits of what can be safely executed in one loop without the loop becoming unwieldy.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What makes a good phase scope
|
||||||
|
|
||||||
|
This is worth dwelling on because it is the most common source of friction with the loop.
|
||||||
|
|
||||||
|
A phase that is too large becomes a research project unto itself. The planner struggles to decompose it into independent plans. Executors in later waves are blocked waiting for earlier waves. Verification becomes a full audit rather than a targeted review. The feedback cycle stretches from hours to days, and the risk of discovering a fundamental design mistake late — after much code has been written — rises sharply.
|
||||||
|
|
||||||
|
A phase that is too small fragments work that naturally belongs together. You end up with plan files that are half a dozen lines, phases that complete in minutes, and a planning overhead that dwarfs the execution cost. The loop feels bureaucratic rather than helpful.
|
||||||
|
|
||||||
|
A good phase scope is one where:
|
||||||
|
|
||||||
|
- The goal can be stated in a single sentence that is neither obviously trivial nor suspiciously broad.
|
||||||
|
- The research needed to plan it is bounded — the ecosystem questions have answers that do not depend on other phases completing first.
|
||||||
|
- The execution can be parallelised into a handful of non-overlapping plans, not dozens.
|
||||||
|
- There is a clear, testable definition of done that a verifier can check without reading the entire codebase.
|
||||||
|
|
||||||
|
Concretely: "Add HMAC-SHA256 signature validation middleware" is a good phase scope. "Build the authentication system" usually is not — it almost always contains multiple independent concerns that would be better as separate phases. "Fix the typo in the README" is below the threshold where the loop adds value; use `/gsd-quick` instead.
|
||||||
|
|
||||||
|
When in doubt, split. A smaller phase completes faster, verifies more confidently, and makes it easier to course-correct if a design decision turns out to be wrong.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How `.planning/` carries state across the loop
|
||||||
|
|
||||||
|
The loop is not a single session. Research, planning, and execution may happen across multiple sessions, with context resets in between. The `.planning/` directory is what makes this possible.
|
||||||
|
|
||||||
|
Every step of the loop reads artefacts produced by earlier steps and writes artefacts for later steps. The CONTEXT.md that the Discuss step produces is still available when the Planner runs — even if that is in a different session hours later. The PLAN.md files that the Planner produces are still available when the Executor runs — even across a restart. The VERIFICATION.md that the Verifier writes is still available when you review the phase.
|
||||||
|
|
||||||
|
`STATE.md` is the navigation layer above all of this. It records exactly where in the loop the project currently sits: which milestone is active, which phase is in progress, which plans are complete and which are pending. Any agent or workflow that needs to orient itself reads `STATE.md` first.
|
||||||
|
|
||||||
|
For the precise structure of these files, see [Planning artifacts](../reference/planning-artifacts.md) and the [STATE.md schema](../reference/state-md.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The loop is a rhythm, not a constraint
|
||||||
|
|
||||||
|
It is tempting to see the loop as bureaucracy — a set of required steps that you have to perform before you are allowed to write code. That framing is wrong.
|
||||||
|
|
||||||
|
The loop exists because each step prevents failures that are genuinely expensive to fix later. Discuss prevents planning on wrong assumptions. Plan prevents executing a design that is fundamentally broken. Verify prevents shipping work that missed the brief. These are not invented problems. They are the actual failure modes of AI-assisted development at the scale of real features.
|
||||||
|
|
||||||
|
When the loop works well, it feels like a rhythm: a cadence of focused, bounded work where each step is clear because the previous step did its job. The overhead is real, but it is front-loaded — paid in minutes of planning rather than hours of rework.
|
||||||
|
|
||||||
|
For work that falls below the threshold where the loop is warranted, GSD Core provides lighter primitives. The phase loop is one tool, not the only tool.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Context engineering](context-engineering.md) — why fresh-context subagents prevent the quality degradation that makes the loop necessary
|
||||||
|
- [Discuss a phase](../how-to/discuss-a-phase.md)
|
||||||
|
- [Plan a phase](../how-to/plan-a-phase.md)
|
||||||
|
- [Execute a phase](../how-to/execute-a-phase.md)
|
||||||
|
- [Verify and ship](../how-to/verify-and-ship.md)
|
||||||
|
- [Planning artifacts](../reference/planning-artifacts.md)
|
||||||
|
- [STATE.md schema](../reference/state-md.md)
|
||||||
|
- [docs index](../README.md)
|
||||||
218
docs/how-to/configure-model-profiles.md
Normal file
218
docs/how-to/configure-model-profiles.md
Normal file
@@ -0,0 +1,218 @@
|
|||||||
|
# How to configure model profiles
|
||||||
|
|
||||||
|
Choose the right model tier strategy for your project, then tune individual agents or entire phase types without writing a large override block. This guide starts with the simplest lever and works up to dynamic routing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The four profiles (plus `adaptive` and `inherit`)
|
||||||
|
|
||||||
|
Set `model_profile` in `.planning/config.json` or via `/gsd-config --profile <name>`:
|
||||||
|
|
||||||
|
| Profile | Planner | Executor | Researchers | Verifier | Use when |
|
||||||
|
|---------|---------|----------|-------------|----------|----------|
|
||||||
|
| `quality` | Opus | Opus | Opus | Sonnet | Production-quality work where cost is secondary |
|
||||||
|
| `balanced` | Opus | Sonnet | Sonnet | Sonnet | Normal development — the default |
|
||||||
|
| `budget` | Sonnet | Sonnet | Haiku | Haiku | Rapid prototyping, cost-sensitive contexts |
|
||||||
|
| `adaptive` | Opus | Sonnet | Sonnet | Sonnet | Resolves the same way as the other tiers under runtime-aware profiles; use when switching between runtimes frequently |
|
||||||
|
| `inherit` | (session model) | (session model) | (session model) | (session model) | Non-Anthropic providers (OpenRouter, local models) — all agents follow your current session model |
|
||||||
|
|
||||||
|
The table above shows a representative subset. All 33 shipped agents have explicit per-profile tier assignments in `sdk/shared/model-catalog.json`. For the full table see [Model Profiles](../CONFIGURATION.md#model-profiles) in the configuration reference.
|
||||||
|
|
||||||
|
**Quick switch via command:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-config --profile balanced # Normal development
|
||||||
|
/gsd-config --profile budget # Prototyping or high-cost phases
|
||||||
|
/gsd-config --profile quality # Production release
|
||||||
|
/gsd-config --profile inherit # OpenRouter, local models
|
||||||
|
```
|
||||||
|
|
||||||
|
**Or edit `.planning/config.json` directly:**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"model_profile": "balanced"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Per-agent overrides (`model_overrides`)
|
||||||
|
|
||||||
|
If a single agent needs a different tier without changing the whole profile, use `model_overrides`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"model_profile": "balanced",
|
||||||
|
"model_overrides": {
|
||||||
|
"gsd-executor": "opus",
|
||||||
|
"gsd-codebase-mapper": "haiku"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Valid values: `opus`, `sonnet`, `haiku`, `inherit`, or any fully-qualified model ID (e.g. `"openai/o3"`, `"google/gemini-2.5-pro"`).
|
||||||
|
|
||||||
|
`model_overrides` can be set per-project in `.planning/config.json` or globally in `~/.gsd/defaults.json`. Per-project entries win on conflict; non-conflicting global entries are preserved.
|
||||||
|
|
||||||
|
**Important for Codex and OpenCode:** Those runtimes embed the resolved model into each agent's static config at install time. After editing `model_overrides`, re-run the installer for the change to take effect:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --codex --global # or --opencode, --kilo, etc.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Per-phase-type models (`models`)
|
||||||
|
|
||||||
|
If you want to say "Opus for planning, Sonnet for everything else" without learning all 33 agent names, use the `models` block. It maps six phase types to tier aliases:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"model_profile": "balanced",
|
||||||
|
"models": {
|
||||||
|
"planning": "opus",
|
||||||
|
"discuss": "opus",
|
||||||
|
"research": "sonnet",
|
||||||
|
"execution": "opus",
|
||||||
|
"verification": "sonnet",
|
||||||
|
"completion": "sonnet"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Phase types and their agents:
|
||||||
|
|
||||||
|
| Phase type | Agents covered |
|
||||||
|
|---|---|
|
||||||
|
| `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` | Reserved — no subagent today; accepted by schema for forward compatibility |
|
||||||
|
|
||||||
|
The `models` block accepts tier aliases only (`opus`, `sonnet`, `haiku`, `inherit`). For a fully-qualified model ID, use `model_overrides` per agent instead.
|
||||||
|
|
||||||
|
**Combining `models` with a per-agent exception:**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"model_profile": "balanced",
|
||||||
|
"models": {
|
||||||
|
"research": "sonnet"
|
||||||
|
},
|
||||||
|
"model_overrides": {
|
||||||
|
"gsd-codebase-mapper": "haiku"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
All five research agents resolve to `sonnet` *except* `gsd-codebase-mapper`, which is pinned to `haiku`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dynamic routing — start cheap, escalate on failure
|
||||||
|
|
||||||
|
If you want to pay for cheaper tiers by default and only escalate when an agent fails a quality gate, enable `dynamic_routing`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"dynamic_routing": {
|
||||||
|
"enabled": true,
|
||||||
|
"tier_models": {
|
||||||
|
"light": "haiku",
|
||||||
|
"standard": "sonnet",
|
||||||
|
"heavy": "opus"
|
||||||
|
},
|
||||||
|
"escalate_on_failure": true,
|
||||||
|
"max_escalations": 1
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Each agent has a default tier (`light`, `standard`, or `heavy`). On the first attempt, GSD picks `tier_models[default_tier]`. If the orchestrator detects a soft failure (verification inconclusive, plan-check flagged, etc.), it re-spawns the agent one tier up. `max_escalations` caps the total retries.
|
||||||
|
|
||||||
|
Agents that already sit at `heavy` cannot escalate further.
|
||||||
|
|
||||||
|
**Turning off escalation while keeping dynamic resolution:**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"dynamic_routing": {
|
||||||
|
"enabled": true,
|
||||||
|
"escalate_on_failure": false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Every attempt uses `tier_models[default_tier]` regardless of outcome — useful when you want explicit tier-to-model mapping without the escalation behaviour.
|
||||||
|
|
||||||
|
`dynamic_routing` is **disabled by default**. Omitting the block or setting `enabled: false` preserves static resolution.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Using GSD on non-Anthropic runtimes
|
||||||
|
|
||||||
|
If you installed GSD for Codex, OpenCode, Gemini CLI, or Kilo, the installer already set `resolve_model_ids: "omit"` in your config. This tells GSD to skip Anthropic model ID resolution and let the runtime choose its own default model. No manual setup is needed for the basic case.
|
||||||
|
|
||||||
|
**If you want tiered models on Codex:**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"runtime": "codex",
|
||||||
|
"model_profile": "balanced"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD resolves each tier alias to the Codex-native model and reasoning effort defined in the runtime tier map.
|
||||||
|
|
||||||
|
**If you want per-agent model IDs on any non-Claude runtime:**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"resolve_model_ids": "omit",
|
||||||
|
"model_overrides": {
|
||||||
|
"gsd-planner": "o3",
|
||||||
|
"gsd-executor": "o4-mini",
|
||||||
|
"gsd-debugger": "o3"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
For the full runtime-aware profiles reference and the `model_policy` surface (provider-neutral presets added in v1.42), see [Configuration reference — Model Profiles](../CONFIGURATION.md#model-profiles).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resolution precedence (highest to lowest)
|
||||||
|
|
||||||
|
When multiple layers apply, the resolver picks the highest-priority entry:
|
||||||
|
|
||||||
|
```text
|
||||||
|
1. model_overrides[<agent>] — per-agent; full IDs; targeted exception
|
||||||
|
2. dynamic_routing.tier_models[<tier>] — when enabled; escalates on soft failure
|
||||||
|
3. models[<phase_type>] — coarse phase-level tier
|
||||||
|
4. model_profile (per-agent column) — global tier strategy
|
||||||
|
5. Runtime default — when nothing else applies
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Choosing the right lever
|
||||||
|
|
||||||
|
| You want | Use |
|
||||||
|
|---|---|
|
||||||
|
| One tier strategy for all agents | `model_profile` |
|
||||||
|
| Coarse phase-level tuning ("Opus for planning") | `models.<phase_type>` |
|
||||||
|
| Per-agent precision ("force Haiku on the codebase mapper") | `model_overrides[<agent>]` |
|
||||||
|
| A fully-qualified model ID for a specific agent | `model_overrides[<agent>]: "openai/gpt-5"` |
|
||||||
|
| Start cheap, escalate only on failure | `dynamic_routing` |
|
||||||
|
| All agents follow the session model (non-Anthropic provider) | `model_profile: "inherit"` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Configuration reference](../CONFIGURATION.md)
|
||||||
|
- [Multi-agent orchestration](../explanation/multi-agent-orchestration.md)
|
||||||
|
- [Commands reference](../COMMANDS.md)
|
||||||
|
- [Docs index](../README.md)
|
||||||
178
docs/how-to/debug-a-failed-execution.md
Normal file
178
docs/how-to/debug-a-failed-execution.md
Normal file
@@ -0,0 +1,178 @@
|
|||||||
|
# How to debug a failed execution
|
||||||
|
|
||||||
|
**Goal:** Recover when a phase execution fails, stalls, or produces incomplete work — and resume cleanly without losing progress or repeating work that already succeeded.
|
||||||
|
|
||||||
|
**Prerequisites:** You have run `/gsd-execute-phase N` and the execution stopped before writing `VERIFICATION.md`, or you see unexpected output, missing files, or a stalled spinner.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Detect whether the execution stalled or failed
|
||||||
|
|
||||||
|
Before taking any recovery action, determine what actually happened.
|
||||||
|
|
||||||
|
### If you see "Spawning…" with no output after 1–5 minutes
|
||||||
|
|
||||||
|
This is normal, not a freeze. GSD subagents run in an isolated context window. The liveness note on the spawn line confirms this. Do not interrupt the session.
|
||||||
|
|
||||||
|
If it has been more than 10 minutes with no result, check the Claude Code sidebar. If the agent task shows as completed but no output appeared, the result may have been lost in a context switch — re-run the same command:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase 1
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD checks for `SUMMARY.md` files before dispatching executors. Plans that already have one are skipped automatically.
|
||||||
|
|
||||||
|
### If execution stopped mid-wave with an error message
|
||||||
|
|
||||||
|
Check git history to see which plans committed successfully:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git log --oneline -20
|
||||||
|
```
|
||||||
|
|
||||||
|
Plans that committed their work will have an entry such as `feat(01-02): …`. Plans without a commit are incomplete and will be re-executed when you re-run.
|
||||||
|
|
||||||
|
### If the executor committed code but did not write SUMMARY.md
|
||||||
|
|
||||||
|
GSD detects this at the next run and surfaces a safe-resume gate with three options:
|
||||||
|
|
||||||
|
- **Close out manually** — inspect the commits yourself, write `SUMMARY.md`, then re-run.
|
||||||
|
- **Re-execute from scratch** — revert or supersede the partial commits before dispatching a new executor.
|
||||||
|
- **Mark-and-skip** — record the anomaly and continue, only with your explicit confirmation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Diagnose the root cause
|
||||||
|
|
||||||
|
### Run `/gsd-debug --diagnose`
|
||||||
|
|
||||||
|
If execution produced wrong output, stubbed code, or a verification failure, use the diagnosis-only mode to investigate without applying any fixes:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-debug --diagnose "Phase 2 executor produced stubs instead of real code"
|
||||||
|
```
|
||||||
|
|
||||||
|
`--diagnose` stops at root cause without touching your files. It creates a session file at `.planning/debug/<slug>.md` so you can pick up the investigation later if needed.
|
||||||
|
|
||||||
|
To start a full debug session that also applies a fix:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-debug "Login middleware not handling 401 correctly after phase 3"
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD gathers symptoms, runs a structured investigation using the scientific method, and proposes a fix. If `tdd_mode: true` is set in your config, it requires a failing test before applying any fix.
|
||||||
|
|
||||||
|
### Check active debug sessions
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-debug list
|
||||||
|
```
|
||||||
|
|
||||||
|
Shows all open sessions with their current hypothesis and next action. To resume a specific session:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-debug continue <slug>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Run a post-mortem with `/gsd-forensics`
|
||||||
|
|
||||||
|
If the cause is not clear from the error output — for example, plans reference nonexistent files, execution produced unexpected results, or state seems corrupted — run a forensic investigation:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-forensics "Phase 3 execution stalled after wave 1"
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD analyses git history, `.planning/` artifact completeness, STATE.md consistency, uncommitted work, and orphaned worktrees. It writes a structured report to `.planning/forensics/report-<timestamp>.md` and surfaces recommended remediation steps.
|
||||||
|
|
||||||
|
`/gsd-forensics` is read-only — it never modifies your project files.
|
||||||
|
|
||||||
|
**What it detects:**
|
||||||
|
|
||||||
|
- **Stuck loop** — the same file appears in three or more consecutive commits within a short time window (HIGH confidence if commit messages are similar)
|
||||||
|
- **Missing artefacts** — a phase has commits but no `SUMMARY.md` or `VERIFICATION.md`
|
||||||
|
- **Abandoned work** — uncommitted changes with STATE.md showing mid-execution and the last commit more than two hours old
|
||||||
|
- **Crash or interruption** — uncommitted changes combined with an active execution state and orphaned worktrees
|
||||||
|
- **Scope drift** — recent commits touch files outside the current phase's expected file set
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resume execution after recovery
|
||||||
|
|
||||||
|
Once the underlying issue is resolved, re-run the execute command:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase 1
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD skips plans whose `SUMMARY.md` already exists and dispatches executors only for the remaining plans.
|
||||||
|
|
||||||
|
If you need to re-execute only a specific wave:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase 1 --wave 2
|
||||||
|
```
|
||||||
|
|
||||||
|
If you want to validate `.planning/` integrity before dispatching:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase 1 --validate
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Roll back with `/gsd-undo`
|
||||||
|
|
||||||
|
If execution produced code you want to discard entirely, roll back using the plan manifest rather than manual `git revert`:
|
||||||
|
|
||||||
|
### Roll back a single plan
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-undo --plan 03-02
|
||||||
|
```
|
||||||
|
|
||||||
|
Reverts all commits for plan `02` of phase `3`. GSD shows a confirmation gate before writing any change.
|
||||||
|
|
||||||
|
### Roll back an entire phase
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-undo --phase 03
|
||||||
|
```
|
||||||
|
|
||||||
|
Reverts all commits for phase `3`. GSD checks whether any subsequent phases depend on this phase and warns you before proceeding.
|
||||||
|
|
||||||
|
### Pick interactively from recent commits
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-undo --last 5
|
||||||
|
```
|
||||||
|
|
||||||
|
Shows the five most recent GSD commits and lets you select which to revert.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Restore session context after a break
|
||||||
|
|
||||||
|
If you have returned to the project after a context reset or a new session:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-resume-work
|
||||||
|
```
|
||||||
|
|
||||||
|
Restores your full session context from the last handoff, including the current phase, blockers, and where execution stopped.
|
||||||
|
|
||||||
|
Alternatively, to see your current position and auto-advance to the correct next step:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-progress --next
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Execute a phase](execute-a-phase.md)
|
||||||
|
- [Recover and troubleshoot](recover-and-troubleshoot.md)
|
||||||
|
- [Commands](../COMMANDS.md)
|
||||||
|
- [docs index](../README.md)
|
||||||
149
docs/how-to/design-a-ui-phase.md
Normal file
149
docs/how-to/design-a-ui-phase.md
Normal file
@@ -0,0 +1,149 @@
|
|||||||
|
# How to design a UI phase
|
||||||
|
|
||||||
|
**Goal:** Produce a locked UI design contract (`UI-SPEC.md`) that fixes spacing, colour, typography, and copywriting decisions before the planner writes tasks, preventing visual inconsistency caused by ad-hoc styling choices during execution.
|
||||||
|
|
||||||
|
**Prerequisites:** `.planning/ROADMAP.md` exists. The phase must have frontend or UI work. Running `/gsd-discuss-phase N` first is strongly recommended — the UI researcher reads `CONTEXT.md` to avoid re-asking decisions you have already made.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decide whether this phase needs a UI contract
|
||||||
|
|
||||||
|
Not all phases need `/gsd-ui-phase`. Use it when:
|
||||||
|
|
||||||
|
- The phase introduces new UI surfaces (pages, flows, layouts)
|
||||||
|
- Multiple components will be built and visual consistency matters
|
||||||
|
- You are starting a new project's frontend and need a design system baseline
|
||||||
|
- You are adding significant UI work to an existing project and want to lock tokens, spacing, and colour before execution
|
||||||
|
|
||||||
|
Skip it when:
|
||||||
|
|
||||||
|
- The phase is purely backend, infrastructure, or data work with no user-facing output
|
||||||
|
- A UI-SPEC.md already exists for an earlier phase and this phase builds on identical visual patterns without introducing new surfaces
|
||||||
|
|
||||||
|
If you are unsure, the safety gate will prompt you: when `workflow.ui_safety_gate` is enabled (default), `/gsd-plan-phase` warns when it detects frontend work but no UI-SPEC.md and asks whether to run `/gsd-ui-phase` first.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Run the UI design contract
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-ui-phase 2
|
||||||
|
```
|
||||||
|
|
||||||
|
If no phase number is given, GSD Core targets the current phase.
|
||||||
|
|
||||||
|
The command runs in two stages:
|
||||||
|
|
||||||
|
1. **`gsd-ui-researcher`** — reads `CONTEXT.md`, `RESEARCH.md`, and `REQUIREMENTS.md` for existing decisions, detects the design system state (shadcn `components.json`, Tailwind config, existing tokens), and asks only the unanswered design questions across five areas: spacing, colour, typography, copywriting, and registry safety.
|
||||||
|
2. **`gsd-ui-checker`** — validates the resulting `UI-SPEC.md` across six dimensions. If issues are found, a revision loop reruns the researcher (up to two iterations) targeting only the flagged items.
|
||||||
|
|
||||||
|
**Output:** `{padded_phase}-UI-SPEC.md` in `.planning/phases/{phase-dir}/`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What the UI-SPEC covers
|
||||||
|
|
||||||
|
The researcher locks decisions across five areas:
|
||||||
|
|
||||||
|
| Area | Examples |
|
||||||
|
|---|---|
|
||||||
|
| **Spacing** | Base scale (4px or 8px), grid alignment, component padding |
|
||||||
|
| **Colour** | Primary, accent, neutral palette; 60/30/10 rule; dark-mode considerations |
|
||||||
|
| **Typography** | Font families, size/weight scale constraints, heading hierarchy |
|
||||||
|
| **Copywriting** | CTA labels, empty state messages, error state copy, loading indicators |
|
||||||
|
| **Registry safety** | shadcn component inspection protocol (see below) |
|
||||||
|
|
||||||
|
The checker validates the spec against six pillars, scored 1–4 each: Copywriting, Visuals, Colour, Typography, Spacing, and Experience Design (loading / error / empty state coverage).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## shadcn initialisation
|
||||||
|
|
||||||
|
For React, Next.js, and Vite projects, the researcher offers to initialise shadcn if no `components.json` is found. The flow:
|
||||||
|
|
||||||
|
1. Visit `ui.shadcn.com/create` and configure your preset (colours, border radius, fonts)
|
||||||
|
2. Copy the preset string
|
||||||
|
3. Run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx shadcn init --preset <paste>
|
||||||
|
```
|
||||||
|
|
||||||
|
The preset string becomes a first-class GSD Core planning artefact that is reproducible across phases and milestones.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Registry safety gate
|
||||||
|
|
||||||
|
Third-party shadcn registries can inject arbitrary code. When `workflow.ui_safety_gate` is enabled (default), the spec requires these steps before installing any non-official component:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx shadcn view <component> # inspect source before installing
|
||||||
|
npx shadcn diff <component> # compare against the official registry
|
||||||
|
```
|
||||||
|
|
||||||
|
The checker will flag the spec as BLOCKED if registry safety is not addressed. Disable the gate via `/gsd-settings` if your project does not use shadcn or you have an alternative vetting process.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Use sketch findings as a head start
|
||||||
|
|
||||||
|
If you have already run `/gsd-sketch --wrap-up`, the UI researcher loads `.claude/skills/sketch-findings-[project]/` automatically. Pre-validated decisions (layout, palette, typography, spacing) are treated as locked — the researcher does not re-ask them. You see a note at the start of the run:
|
||||||
|
|
||||||
|
```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.
|
||||||
|
```
|
||||||
|
|
||||||
|
This is the main reason to run `/gsd-sketch --wrap-up` before `/gsd-ui-phase`: it turns the conversational design exploration into binding contract input.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Retroactive visual audit with `/gsd-ui-review`
|
||||||
|
|
||||||
|
`/gsd-ui-review` runs after execution, not before. Use it to audit the implemented frontend against the UI-SPEC (or against abstract 6-pillar standards when no spec exists).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-ui-review # audit the current phase
|
||||||
|
/gsd-ui-review 3 # audit phase 3 specifically
|
||||||
|
```
|
||||||
|
|
||||||
|
It works on any project with frontend code — GSD project initialisation is not required.
|
||||||
|
|
||||||
|
**What it checks (6 pillars, scored 1–4 each):**
|
||||||
|
|
||||||
|
1. Copywriting — CTA labels, empty states, error states
|
||||||
|
2. Visuals — focal points, visual hierarchy, icon accessibility
|
||||||
|
3. Colour — accent usage discipline, 60/30/10 compliance
|
||||||
|
4. Typography — font size and weight constraint adherence
|
||||||
|
5. Spacing — grid alignment, token consistency
|
||||||
|
6. Experience Design — loading, error, and empty state coverage
|
||||||
|
|
||||||
|
**Output:** `{padded_phase}-UI-REVIEW.md` with scores and top three priority fixes. When a browser MCP server such as `gsd-browser` is configured, the audit also captures screenshots with visual evidence.
|
||||||
|
|
||||||
|
**Screenshot storage:** Screenshots are saved to `.planning/ui-reviews/`. A `.gitignore` is created automatically to prevent binary files from reaching git. Screenshots are cleaned up during `/gsd-complete-milestone`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Recommended position in the phase lifecycle
|
||||||
|
|
||||||
|
```text
|
||||||
|
/gsd-discuss-phase N ← lock implementation preferences
|
||||||
|
/gsd-ui-phase N ← lock design contract (frontend phases)
|
||||||
|
/gsd-plan-phase N ← research + plan (reads UI-SPEC.md as context)
|
||||||
|
/gsd-execute-phase N ← parallel execution
|
||||||
|
/gsd-verify-work N ← manual UAT
|
||||||
|
/gsd-ui-review N ← retroactive visual audit (optional but recommended)
|
||||||
|
```
|
||||||
|
|
||||||
|
`/gsd-ui-phase` sits between discuss and plan because the planner reads `UI-SPEC.md` as design context — tasks in `PLAN.md` reference spacing tokens, colour variables, and copywriting decisions that the spec locked.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Spike and sketch](spike-and-sketch.md)
|
||||||
|
- [Plan a phase](plan-a-phase.md)
|
||||||
|
- [Commands](../COMMANDS.md)
|
||||||
|
- [Docs index](../README.md)
|
||||||
158
docs/how-to/discuss-a-phase.md
Normal file
158
docs/how-to/discuss-a-phase.md
Normal file
@@ -0,0 +1,158 @@
|
|||||||
|
# How to discuss a phase
|
||||||
|
|
||||||
|
**Goal:** Gather the implementation decisions a phase needs before planning begins — so the researcher and planner can act without asking you again.
|
||||||
|
|
||||||
|
**Prerequisites:** `.planning/ROADMAP.md` exists. If not, run `/gsd-new-project` first.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Choose your discuss mode
|
||||||
|
|
||||||
|
GSD Core offers two modes. Choose based on how well-understood the codebase is.
|
||||||
|
|
||||||
|
**If you want to express your own implementation preferences upfront** (interview mode, the default):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-discuss-phase 2
|
||||||
|
```
|
||||||
|
|
||||||
|
Claude identifies grey areas in the phase scope, lets you select which to discuss, then works through approximately four questions per area.
|
||||||
|
|
||||||
|
**If the codebase already has clear patterns and you find most questions obvious** (assumptions mode):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node gsd-tools.cjs config-set workflow.discuss_mode assumptions
|
||||||
|
/gsd-discuss-phase 2
|
||||||
|
```
|
||||||
|
|
||||||
|
Claude reads 5–15 relevant codebase files via a subagent, forms assumptions with evidence and confidence levels, and presents them for confirmation or correction. Typically 2–4 interactions rather than 15–20.
|
||||||
|
|
||||||
|
To switch back:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node gsd-tools.cjs config-set workflow.discuss_mode discuss
|
||||||
|
```
|
||||||
|
|
||||||
|
See [Discuss modes explained](../workflow-discuss-mode.md) for a full comparison, including when each mode is likely to save time.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Discuss all grey areas without the selection step
|
||||||
|
|
||||||
|
By default, Claude presents grey areas and asks which you want to cover. If you want to work through all of them without that selection prompt:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-discuss-phase 2 --all
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Speed up a straightforward phase
|
||||||
|
|
||||||
|
**If the phase is well-understood and you want Claude to pick the recommended defaults without prompting you:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-discuss-phase 3 --auto
|
||||||
|
```
|
||||||
|
|
||||||
|
Claude selects the recommended answer for every question and logs the choices. Use this for phases where the decisions are low-stakes or already implied by prior phases.
|
||||||
|
|
||||||
|
**If you have remote-session constraints (no TUI menus):**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-discuss-phase 2 --text
|
||||||
|
```
|
||||||
|
|
||||||
|
All prompts are rendered as plain-text numbered lists instead of interactive selectors.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Work through questions in groups
|
||||||
|
|
||||||
|
If you prefer to answer several questions at once rather than one at a time:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-discuss-phase 2 --batch
|
||||||
|
```
|
||||||
|
|
||||||
|
Claude groups 2–5 questions per turn.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Add trade-off analysis to each question
|
||||||
|
|
||||||
|
If you want a comparison table of the options before committing:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-discuss-phase 2 --analyze
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Bulk-answer from a prepared file
|
||||||
|
|
||||||
|
If you have a prepared answers file and want to push all decisions in one pass:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-discuss-phase 1 --power
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Surface Claude's assumptions before discussing
|
||||||
|
|
||||||
|
**If you want to see what Claude would assume and do before any interactive session** — useful for validating alignment before investing discussion time:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-discuss-phase 3 --assumptions
|
||||||
|
```
|
||||||
|
|
||||||
|
Claude outputs its assumptions (with codebase evidence and confidence levels) and exits. No CONTEXT.md is written. Review the output, then run a normal discuss or assumptions-mode session if anything needs correcting.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What CONTEXT.md contains
|
||||||
|
|
||||||
|
Both discuss and assumptions mode produce the same `{phase}-CONTEXT.md` in the phase directory. Downstream agents (researcher, planner, plan-checker) read this file identically regardless of which mode produced it. It contains six sections:
|
||||||
|
|
||||||
|
| Section | Purpose |
|
||||||
|
|---|---|
|
||||||
|
| `<domain>` | Phase boundary — what this phase delivers |
|
||||||
|
| `<decisions>` | Locked implementation decisions from the session |
|
||||||
|
| `<canonical_refs>` | Specs, ADRs, and docs downstream agents must read |
|
||||||
|
| `<code_context>` | Reusable assets, patterns, and integration points |
|
||||||
|
| `<specifics>` | User references and preferences |
|
||||||
|
| `<deferred>` | Ideas noted for future phases |
|
||||||
|
|
||||||
|
The `<canonical_refs>` section is mandatory. If you reference a doc, spec, or ADR during the discussion, Claude adds it immediately and reads it to inform subsequent questions.
|
||||||
|
|
||||||
|
See [CONTEXT.md schema](../reference/context-md.md) for the full field reference.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How decisions feed into planning
|
||||||
|
|
||||||
|
When you run `/gsd-plan-phase` next, the planner reads CONTEXT.md to know which decisions are locked. It will not re-ask questions already answered here. The researcher reads it first to know what to investigate.
|
||||||
|
|
||||||
|
**If CONTEXT.md is missing when you run `/gsd-plan-phase`**, you will be offered the choice to continue without context (plans use research and requirements only, without your design preferences) or to run `/gsd-discuss-phase` first.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## If you have a PRD or acceptance-criteria document
|
||||||
|
|
||||||
|
Skip discuss-phase entirely and go straight to planning:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 1 --prd path/to/prd.md
|
||||||
|
```
|
||||||
|
|
||||||
|
The planner synthesises CONTEXT.md from the PRD and treats all requirements as locked decisions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Plan a phase](plan-a-phase.md)
|
||||||
|
- [Discuss modes](../workflow-discuss-mode.md)
|
||||||
|
- [CONTEXT.md schema](../reference/context-md.md)
|
||||||
|
- [docs index](../README.md)
|
||||||
176
docs/how-to/drive-gsd-from-a-tracker-issue.md
Normal file
176
docs/how-to/drive-gsd-from-a-tracker-issue.md
Normal file
@@ -0,0 +1,176 @@
|
|||||||
|
# How to drive GSD Core from a tracker issue
|
||||||
|
|
||||||
|
**Goal:** Take a single well-scoped GitHub, Linear, or Jira issue through the full GSD pipeline — from isolated workspace to merged PR — using only commands that already exist in GSD Core, with no custom scripts or tracker integrations.
|
||||||
|
|
||||||
|
**Prerequisites:** GSD Core is installed. The issue has bounded scope, observable acceptance criteria, and no upstream blockers.
|
||||||
|
|
||||||
|
For the concepts and design rationale behind this pattern, see [Issue-driven orchestration explained](../issue-driven-orchestration.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 1: Map the issue to a phase
|
||||||
|
|
||||||
|
Open your tracker issue and decide how it maps onto `ROADMAP.md`:
|
||||||
|
|
||||||
|
- **Issue matches an existing phase** → note the phase number and move to Step 2.
|
||||||
|
- **Issue is standalone new work** → add a phase:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-phase "Description matching the issue title"
|
||||||
|
```
|
||||||
|
|
||||||
|
- **Issue is urgent and must slot between existing phases** → insert a decimal phase:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-phase --insert 3 "Fix: description from issue"
|
||||||
|
```
|
||||||
|
|
||||||
|
Copy the tracker issue URL. You will paste it into `CONTEXT.md` in Step 3 so traceability survives context compaction.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 2: Create an isolated workspace
|
||||||
|
|
||||||
|
Every issue gets its own workspace — a git worktree with an independent `.planning/` directory. Partial work, aborted plans, and exploratory commits stay outside `main`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workspace --new --name my-issue-slug --repos . --strategy worktree
|
||||||
|
```
|
||||||
|
|
||||||
|
Switch into the workspace directory before continuing:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd ~/gsd-workspaces/my-issue-slug
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 3: Discuss the phase
|
||||||
|
|
||||||
|
Run discuss-phase to lock in implementation decisions before any planning happens. When the session opens, paste the tracker issue URL into the discussion so it is captured in `CONTEXT.md`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-discuss-phase N
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD asks about ambiguities in the issue scope — error handling, edge cases, interface contracts, technology choices. Your answers shape the plan that follows.
|
||||||
|
|
||||||
|
If you already know all the answers and want to move quickly:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-discuss-phase N --auto
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 4: Plan the phase
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase N
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD spawns research agents, reads your `CONTEXT.md` decisions (including the issue URL), and produces atomic `PLAN.md` files. A plan-checker validates each plan before saving.
|
||||||
|
|
||||||
|
If you want peer review from external AI CLIs before execution (recommended for significant changes):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-review --phase N
|
||||||
|
/gsd-plan-phase N --reviews
|
||||||
|
```
|
||||||
|
|
||||||
|
Or run the full plan–review–converge loop until no HIGH concerns remain:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-review-convergence N
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 5: Execute the phase
|
||||||
|
|
||||||
|
For interactive, phase-at-a-time execution:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase N
|
||||||
|
```
|
||||||
|
|
||||||
|
For a hands-off run through all remaining phases:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-autonomous
|
||||||
|
```
|
||||||
|
|
||||||
|
For an interactive dashboard where you can watch progress and dispatch work across phases:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-manager
|
||||||
|
```
|
||||||
|
|
||||||
|
All three approaches update `STATE.md`, commit each task atomically, and run the post-phase verifier.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 6: Verify the work
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-verify-work N
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD walks you through the acceptance criteria from the phase goal (which reflects your tracker issue) one at a time. If anything fails, GSD diagnoses the root cause and creates a fix plan. Re-run execute and re-verify until all checks pass.
|
||||||
|
|
||||||
|
Treat `verification_failed` as a blocker even when the code looks correct — the failure usually surfaces a missed acceptance criterion from the original issue.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 7: Review and ship
|
||||||
|
|
||||||
|
Run a code review before opening the PR:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-code-review N
|
||||||
|
/gsd-code-review N --fix
|
||||||
|
```
|
||||||
|
|
||||||
|
Then create the PR:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-ship N
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD assembles the PR body from your planning artifacts: phase goal, changes summary, requirements addressed, verification status, and key decisions. Include `Closes #NNN` or `Fixes #NNN` in the PR body (or set it via `/gsd-config`) so the tracker issue closes automatically when the PR merges.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 8: Capture follow-up work
|
||||||
|
|
||||||
|
As you work through the issue you will often discover related work. Capture it without losing context:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-capture "Follow-up: description of discovered work" # Add as a todo
|
||||||
|
/gsd-capture --seed "Idea worth a future phase" # Preserve for the next milestone
|
||||||
|
/gsd-capture --backlog "Not urgent but worth tracking" # Park in the backlog
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD does not post to your tracker automatically. Creating a tracker issue from captured follow-ups is a separate manual step — this keeps human review in the loop.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Conditionals
|
||||||
|
|
||||||
|
| Situation | What to do |
|
||||||
|
|-----------|-----------|
|
||||||
|
| Issue is very small (typo, config change) | Skip workspace + discuss + plan; use `/gsd-quick` instead |
|
||||||
|
| Issue has multiple independent sub-tasks | Use `/gsd-manager` to parallelise execution across plans |
|
||||||
|
| Issue is blocked on another issue | Do not start until the upstream blocker is resolved; GSD has no automatic dependency poller |
|
||||||
|
| Issue scope turns out larger than expected mid-execution | Stop, run `/gsd-phase --insert N` to add sub-phases, continue |
|
||||||
|
| You want to skip the interactive discussion | Use `--auto` flag with `/gsd-discuss-phase`, or set `workflow.skip_discuss: true` for project-wide automation |
|
||||||
|
| Multiple issues form a coherent release | Run `/gsd-new-milestone` to group them and `/gsd-autonomous` to execute in sequence |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Issue-driven orchestration explained](../issue-driven-orchestration.md)
|
||||||
|
- [Isolate work with workspaces](isolate-work-with-workspaces.md)
|
||||||
|
- [Verify and ship](verify-and-ship.md)
|
||||||
|
- [docs index](../README.md)
|
||||||
119
docs/how-to/execute-a-phase.md
Normal file
119
docs/how-to/execute-a-phase.md
Normal file
@@ -0,0 +1,119 @@
|
|||||||
|
# How to execute a phase
|
||||||
|
|
||||||
|
**Goal:** Run a planned phase through wave-based parallel execution and land every plan as an atomic git commit.
|
||||||
|
|
||||||
|
**Prerequisites:** The phase has at least one `PLAN.md` file. If planning is not yet done, run `/gsd-plan-phase N` first — see [Plan a phase](plan-a-phase.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Run the full phase
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase 1
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD reads the phase's plan files, groups them into dependency waves, and spawns a fresh executor agent per plan. Each executor commits its work atomically before the next wave begins.
|
||||||
|
|
||||||
|
Before any agents are dispatched, GSD prints a wave table:
|
||||||
|
|
||||||
|
```
|
||||||
|
## 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 |
|
||||||
|
```
|
||||||
|
|
||||||
|
Wave 1 plans run in parallel (each in an isolated git worktree). Wave 2 waits until all Wave 1 commits are merged.
|
||||||
|
|
||||||
|
For the underlying agent coordination model, see [Multi-agent orchestration](../explanation/multi-agent-orchestration.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Run a single wave
|
||||||
|
|
||||||
|
If you want to execute only one wave — for example, to inspect Wave 1 output before committing to Wave 2 — use `--wave N`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase 1 --wave 2
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD executes only Wave 2 plans. It first checks that all earlier waves are complete; if any Wave 1 plan is still marked incomplete, it stops and tells you to finish earlier waves first.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Validate state before execution
|
||||||
|
|
||||||
|
If you suspect the `.planning/` directory is out of sync with the filesystem — for example after a crash or an interrupted previous run — pass `--validate`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase 1 --validate
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD runs a state consistency check before spawning any executors. Detected drift is reported and you can accept or correct it before proceeding.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resume a stalled execution
|
||||||
|
|
||||||
|
If execution stops partway through — a quota error, a network drop, or a crashed session — the wave-level progress is preserved. GSD checks for a `SUMMARY.md` file for each plan; plans that have one are skipped automatically when you re-run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase 1
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD will skip plans where `SUMMARY.md` already exists and pick up from the first incomplete plan.
|
||||||
|
|
||||||
|
**If commits exist but `SUMMARY.md` is missing** (the executor committed but did not write its summary before the session died), GSD surfaces a safe-resume gate and offers three options:
|
||||||
|
|
||||||
|
- `close out manually` — inspect the commits, write `SUMMARY.md`, then re-run.
|
||||||
|
- `re-execute from scratch` — revert or supersede the partial commits before dispatching a new executor.
|
||||||
|
- `mark-and-skip` — record the anomaly and move on, only with explicit confirmation.
|
||||||
|
|
||||||
|
For systematic failure diagnosis, see [Debug a failed execution](debug-a-failed-execution.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Where output lands
|
||||||
|
|
||||||
|
After all waves complete, the phase directory contains:
|
||||||
|
|
||||||
|
```
|
||||||
|
.planning/phases/01-<name>/
|
||||||
|
01-01-SUMMARY.md # What plan 01 built, key files, deviations
|
||||||
|
01-02-SUMMARY.md
|
||||||
|
01-03-SUMMARY.md
|
||||||
|
VERIFICATION.md # Requirement-by-requirement pass/fail status
|
||||||
|
```
|
||||||
|
|
||||||
|
`STATE.md` and `ROADMAP.md` are updated automatically once all waves are done. `VERIFICATION.md` is written only when the phase is fully complete.
|
||||||
|
|
||||||
|
Git history will show one commit per task (from each executor), followed by tracking commits from the orchestrator.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Cross-AI execution
|
||||||
|
|
||||||
|
To delegate execution to an external AI CLI (Codex, Gemini, etc.) configured in `workflow.cross_ai_command`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase 2 --cross-ai
|
||||||
|
```
|
||||||
|
|
||||||
|
To force local execution even when cross-AI is enabled in config:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase 2 --no-cross-ai
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Plan a phase](plan-a-phase.md)
|
||||||
|
- [Verify and ship](verify-and-ship.md)
|
||||||
|
- [Debug a failed execution](debug-a-failed-execution.md)
|
||||||
|
- [Commands](../COMMANDS.md)
|
||||||
121
docs/how-to/handle-quick-and-fast-tasks.md
Normal file
121
docs/how-to/handle-quick-and-fast-tasks.md
Normal file
@@ -0,0 +1,121 @@
|
|||||||
|
# How to handle quick and fast tasks
|
||||||
|
|
||||||
|
Not every piece of work fits inside a phase. GSD provides two lightweight commands for work that does not need the full discuss → plan → execute → verify loop.
|
||||||
|
|
||||||
|
For context on when the full phase pipeline is worth its overhead, see [Context engineering](../explanation/context-engineering.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Deciding which command to use
|
||||||
|
|
||||||
|
| Situation | Command |
|
||||||
|
|-----------|---------|
|
||||||
|
| Fixing a bug, adding a small feature, or any task you cannot summarise as a single trivial edit | `/gsd-quick` |
|
||||||
|
| Fixing a typo, updating a config value, adding a `.gitignore` entry, or any change that touches ≤ 3 files and takes under a minute | `/gsd-fast` |
|
||||||
|
| The task has unknowns, needs research, or will touch more than a handful of files | `/gsd-quick` with `--research` |
|
||||||
|
|
||||||
|
**The rule of thumb:** if you hesitate for even a moment about whether the task is trivial, use `/gsd-quick`. `/gsd-fast` redirects you to `/gsd-quick` automatically if the scope looks non-trivial.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## `/gsd-quick` — ad-hoc tasks with GSD guarantees
|
||||||
|
|
||||||
|
`/gsd-quick` runs a planner and executor with the same atomic-commit and STATE.md tracking guarantees as a full phase, but without the phase overhead (no ROADMAP entry, no discuss-phase, no wave coordination across multiple plans).
|
||||||
|
|
||||||
|
### Basic use
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-quick
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD prompts you for a task description, then plans and executes it. Artifacts land in `.planning/quick/`.
|
||||||
|
|
||||||
|
You can also pass the description directly:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-quick "Fix the login button not responding on mobile Safari"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Flags
|
||||||
|
|
||||||
|
Add flags to bring in more of the quality pipeline when the task warrants it.
|
||||||
|
|
||||||
|
| Flag | What it adds |
|
||||||
|
|------|-------------|
|
||||||
|
| `--discuss` | A lightweight pre-planning discussion that surfaces grey areas and captures your decisions in a `CONTEXT.md` before the planner runs |
|
||||||
|
| `--research` | A focused research agent investigates approaches, libraries, and pitfalls before planning |
|
||||||
|
| `--validate` | Plan-checking (up to 2 iterations) plus post-execution verification |
|
||||||
|
| `--full` | All of the above — equivalent to `--discuss --research --validate` |
|
||||||
|
|
||||||
|
Flags compose freely:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-quick --research --validate # research + plan-checking + verification, no discuss
|
||||||
|
/gsd-quick --discuss # just surface grey areas before planning
|
||||||
|
/gsd-quick --full # the complete quality pipeline
|
||||||
|
```
|
||||||
|
|
||||||
|
### When to add flags
|
||||||
|
|
||||||
|
- Add `--research` when you are unsure how to approach a task or which library to use.
|
||||||
|
- Add `--validate` when the task touches critical code paths and you want a verifier agent to confirm the must-haves were met.
|
||||||
|
- Add `--discuss` when the task has design choices you want to lock in before the planner runs — for example, when the right error-handling behaviour is not obvious.
|
||||||
|
- Use `--full` when a task is genuinely significant and you would normally plan it as a phase but it does not belong in the ROADMAP.
|
||||||
|
|
||||||
|
### Listing and resuming quick tasks
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-quick list # show all quick tasks with status
|
||||||
|
/gsd-quick status my-task-slug # show status of a specific task
|
||||||
|
/gsd-quick resume my-task-slug # resume an interrupted task
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## `/gsd-fast` — inline trivial edits
|
||||||
|
|
||||||
|
`/gsd-fast` does the work directly in the current context. There are no subagents, no `PLAN.md`, and no research. It is suitable only for changes you could make yourself in under a minute.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-fast "fix typo in README"
|
||||||
|
/gsd-fast "add .env to .gitignore"
|
||||||
|
```
|
||||||
|
|
||||||
|
If you omit the description, GSD prompts you for it.
|
||||||
|
|
||||||
|
`/gsd-fast` checks whether the task is actually trivial before proceeding. If it judges the scope too large it stops and redirects you:
|
||||||
|
|
||||||
|
```text
|
||||||
|
This looks like it needs planning. Use /gsd-quick instead:
|
||||||
|
/gsd-quick "your task description"
|
||||||
|
```
|
||||||
|
|
||||||
|
After making the change, `/gsd-fast` commits atomically and, if a `Quick Tasks Completed` table exists in `.planning/STATE.md`, appends a row to it.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What `/gsd-quick` does that `/gsd-fast` does not
|
||||||
|
|
||||||
|
| Capability | `/gsd-fast` | `/gsd-quick` |
|
||||||
|
|------------|------------|--------------|
|
||||||
|
| Subagent planner | No | Yes |
|
||||||
|
| Subagent executor | No | Yes |
|
||||||
|
| Research agent | No | Optional (`--research`) |
|
||||||
|
| Plan-checking | No | Optional (`--validate`) |
|
||||||
|
| Post-execution verification | No | Optional (`--validate`) |
|
||||||
|
| Discussion phase | No | Optional (`--discuss`) |
|
||||||
|
| Worktree isolation | No | Yes (default) |
|
||||||
|
| Atomic commits per task | Single commit | One per plan task |
|
||||||
|
| STATE.md tracking | Row appended if table exists | Always updated |
|
||||||
|
| `.planning/quick/` artifacts | No | Yes |
|
||||||
|
|
||||||
|
The key distinction is subagent isolation. `/gsd-quick` spawns a fresh planner and executor in separate context windows, which means the work is planned properly, commits are atomic per task, and the orchestrator can verify results. `/gsd-fast` uses only the current context window and is intentionally limited to changes trivial enough not to need any of that.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [The phase loop](../explanation/the-phase-loop.md)
|
||||||
|
- [Context engineering](../explanation/context-engineering.md)
|
||||||
|
- [Commands](../COMMANDS.md)
|
||||||
|
- [Docs index](../README.md)
|
||||||
291
docs/how-to/install-on-your-runtime.md
Normal file
291
docs/how-to/install-on-your-runtime.md
Normal file
@@ -0,0 +1,291 @@
|
|||||||
|
# How to install GSD Core on your runtime
|
||||||
|
|
||||||
|
Install GSD Core (`@opengsd/gsd-core`) into the AI coding runtime you use every day. This guide gives you the standard installer path for each supported runtime, then covers the manual path for machines without Node.js.
|
||||||
|
|
||||||
|
**What you need:** Node.js 18+ and npm (or npx). If you do not have Node.js, jump to [Installing without Node.js](#installing-without-nodejs).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Why the installer is required
|
||||||
|
|
||||||
|
GSD Core ships agent and command files in Claude Code's native frontmatter format. Each supported runtime expects a different schema, directory layout, and command-invocation syntax. The installer performs the necessary transformations — for example, converting tool lists and colour values for OpenCode, writing TOML agent entries for Codex, and rewriting every command body from hyphen form (`/gsd-update`) to colon form (`/gsd:update`) for Gemini CLI.
|
||||||
|
|
||||||
|
**Do not copy files from `agents/` or `commands/` directly.** Doing so bypasses the transformations and produces schema-validation errors or missing commands.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Standard install
|
||||||
|
|
||||||
|
Run the installer from any directory. It prompts for your runtime and whether to install globally (all projects) or locally (this project only).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest
|
||||||
|
```
|
||||||
|
|
||||||
|
That is the only command you need for a fresh install or to re-run the installer after switching runtimes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Per-runtime instructions
|
||||||
|
|
||||||
|
### Claude Code
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --claude --global
|
||||||
|
```
|
||||||
|
|
||||||
|
Skills land in `~/.claude/`. Commands appear as `/gsd-*` slash commands in your next Claude Code session. Restart Claude Code to pick them up.
|
||||||
|
|
||||||
|
**Override the install directory:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Gemini CLI
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --gemini --global
|
||||||
|
```
|
||||||
|
|
||||||
|
Skills land in `~/.gemini/`. The installer rewrites all command bodies to Gemini's colon namespace (`/gsd:update`, `/gsd:config`, etc.). Restart Gemini CLI after install.
|
||||||
|
|
||||||
|
**Override the install directory:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
GEMINI_CONFIG_DIR=~/.gemini-alt npx @opengsd/gsd-core@latest --gemini --global
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### OpenCode
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --opencode --global
|
||||||
|
```
|
||||||
|
|
||||||
|
Skills land in `~/.config/opencode/` (XDG) or `~/.opencode/`. The installer converts agent frontmatter to OpenCode's schema — removing the `tools:` field and converting colour values to hex. See [Installing without Node.js — OpenCode transformations](#opencode--required-transformations) if you need to understand what changes.
|
||||||
|
|
||||||
|
**Override the install directory:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @opengsd/gsd-core@latest --opencode --global
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Kilo
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --kilo --global
|
||||||
|
```
|
||||||
|
|
||||||
|
Skills land in `~/.config/kilo/` (XDG) or `~/.kilo/`. Uses the same OpenCode-style flat markdown command format.
|
||||||
|
|
||||||
|
**Override the install directory:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
KILO_CONFIG_DIR=~/.config/kilo-alt npx @opengsd/gsd-core@latest --kilo --global
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Codex
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --codex --global
|
||||||
|
```
|
||||||
|
|
||||||
|
Skills land in `~/.codex/skills/gsd-*/SKILL.md`. Agents are written with per-agent TOML entries in `config.toml`. Restart Codex (or run `codex --reload`) after install.
|
||||||
|
|
||||||
|
**Minimum supported version:** Codex CLI 0.130.0. Earlier versions had additional skill-root scanning that can produce duplicate listings.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### GitHub Copilot
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --copilot --global
|
||||||
|
```
|
||||||
|
|
||||||
|
Skills land in `~/.copilot/`. GSD installs as agent `.md` files and repository instruction files.
|
||||||
|
|
||||||
|
**Override the install directory:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
COPILOT_CONFIG_DIR=~/.copilot-alt npx @opengsd/gsd-core@latest --copilot --global
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Cursor
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --cursor --global
|
||||||
|
```
|
||||||
|
|
||||||
|
Skills land in `~/.cursor/`. GSD installs skills, agents, and rule references.
|
||||||
|
|
||||||
|
**Override the install directory:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
CURSOR_CONFIG_DIR=~/.cursor-alt npx @opengsd/gsd-core@latest --cursor --global
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Windsurf
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --windsurf --global
|
||||||
|
```
|
||||||
|
|
||||||
|
Skills land in `~/.codeium/windsurf/`. GSD installs skills, agents, and workspace rules.
|
||||||
|
|
||||||
|
**Override the install directory:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-alt npx @opengsd/gsd-core@latest --windsurf --global
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Cline
|
||||||
|
|
||||||
|
Cline uses a rules-based integration — GSD installs as `.clinerules` rather than slash commands.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Global install (all projects)
|
||||||
|
npx @opengsd/gsd-core@latest --cline --global
|
||||||
|
|
||||||
|
# Local install (this project only)
|
||||||
|
npx @opengsd/gsd-core@latest --cline --local
|
||||||
|
```
|
||||||
|
|
||||||
|
Global installs write to `~/.cline/`. Local installs write to `./.cline/`. Rules are loaded automatically by Cline — no custom slash commands are registered.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### CodeBuddy
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --codebuddy --global
|
||||||
|
```
|
||||||
|
|
||||||
|
Skills land in `~/.codebuddy/skills/gsd-*/SKILL.md`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Qwen Code
|
||||||
|
|
||||||
|
Qwen Code uses the same open skills standard as Claude Code 2.1.88+.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --qwen --global
|
||||||
|
```
|
||||||
|
|
||||||
|
Skills land in `~/.qwen/skills/gsd-*/SKILL.md`.
|
||||||
|
|
||||||
|
**Override the install directory:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
QWEN_CONFIG_DIR=~/.qwen-alt npx @opengsd/gsd-core@latest --qwen --global
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Augment Code
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --augment --global
|
||||||
|
```
|
||||||
|
|
||||||
|
Skills land in `~/.augment/`. GSD installs skills and agents. No hook or statusline ownership.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Antigravity
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --antigravity --global
|
||||||
|
```
|
||||||
|
|
||||||
|
The installer auto-detects the Antigravity config directory (`~/.gemini/antigravity`, `~/.gemini/antigravity-ide`, or `~/.gemini/antigravity-cli`). Uses Gemini-compatible settings policy.
|
||||||
|
|
||||||
|
**Override the install directory:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @opengsd/gsd-core@latest --antigravity --global
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Trae
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --trae --global
|
||||||
|
```
|
||||||
|
|
||||||
|
Skills land in `~/.trae/`. GSD installs skills, agents, and rule references.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Local vs global install
|
||||||
|
|
||||||
|
All examples above use `--global`, which installs GSD once for your user account. To scope an install to a single project, replace `--global` with `--local`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --claude --local
|
||||||
|
```
|
||||||
|
|
||||||
|
A local install writes into the `.claude/` directory at your project root. Local install settings take precedence over global ones when both exist.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Installing prerelease editions (Next / Nightly / Insiders / Preview)
|
||||||
|
|
||||||
|
Prerelease editions of runtimes (Windsurf Next, Cursor Nightly, VS Code Insiders, Codex preview channels, etc.) read from a sibling config directory. Set the matching `*_CONFIG_DIR` env var before running the installer:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
|
||||||
|
```
|
||||||
|
|
||||||
|
Select the corresponding stable runtime in the installer prompt. GSD does not enumerate prerelease editions as separate named runtimes — they are best-effort via this env-var mechanism and are not separately tested in release CI.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Installing without Node.js
|
||||||
|
|
||||||
|
If you cannot run `npx` (for example, on a Windows machine without Node.js), you have two options.
|
||||||
|
|
||||||
|
**Option A — Use a machine that has Node.js.** Any machine with Node.js will do: WSL, a Linux VM, a CI runner, or a Docker container. Run the installer there, then copy the output directory to your target machine. For OpenCode:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --opencode --global
|
||||||
|
# Then copy ~/.config/opencode/agents/ to the Windows machine
|
||||||
|
```
|
||||||
|
|
||||||
|
**Option B — Manually transform the source files.** The agent source files live in `agents/` in the GSD Core repository and are in Claude Code's native frontmatter format. Each runtime expects a different shape. For the exact field transformations per runtime, see [Manual install / no-Node.js setup](../USER-GUIDE.md#manual-install--no-nodejs-setup) in the User Guide, which covers the OpenCode transformations in full detail and points to the installer's `convert*Frontmatter` functions for other runtimes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## After install
|
||||||
|
|
||||||
|
Restart your runtime to pick up new commands and agents. Then start your first project:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-new-project
|
||||||
|
```
|
||||||
|
|
||||||
|
If the command is not found after restart, verify the install directory matches the runtime's expected config path. The prerelease-editions section above covers the most common mismatch.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Your first project](../tutorials/your-first-project.md)
|
||||||
|
- [Update GSD Core](update-gsd.md)
|
||||||
|
- [Configuration](../CONFIGURATION.md)
|
||||||
|
- [Docs index](../README.md)
|
||||||
144
docs/how-to/isolate-work-with-workspaces.md
Normal file
144
docs/how-to/isolate-work-with-workspaces.md
Normal file
@@ -0,0 +1,144 @@
|
|||||||
|
# How to isolate work with workspaces
|
||||||
|
|
||||||
|
**Goal:** Create a fully isolated GSD environment — separate git worktree, independent `.planning/` root, and optionally multiple repositories — for feature branches or multi-repo work.
|
||||||
|
|
||||||
|
**Prerequisites:** `git` is installed and the repository supports worktrees. For multi-repo workspaces, the target repos exist on your local machine or are accessible by path.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What workspaces are
|
||||||
|
|
||||||
|
A workspace is a self-contained environment that pairs one or more git worktrees (or clones) with its own `.planning/` root directory. Each workspace has:
|
||||||
|
|
||||||
|
- Its own `.planning/` directory that is **completely independent** from the source repo's `.planning/` — not a subdirectory of it
|
||||||
|
- Its own `WORKSPACE.md` manifest tracking member repos
|
||||||
|
- Git worktrees (default) or full clones of the specified repos, checked out on a dedicated branch (default: `workspace/<name>`)
|
||||||
|
|
||||||
|
Workspaces live under `~/gsd-workspaces/<name>/` by default.
|
||||||
|
|
||||||
|
```
|
||||||
|
~/gsd-workspaces/
|
||||||
|
└── feature-b/
|
||||||
|
├── WORKSPACE.md ← manifest
|
||||||
|
├── .planning/ ← fully independent GSD state
|
||||||
|
│ ├── PROJECT.md
|
||||||
|
│ ├── ROADMAP.md
|
||||||
|
│ └── ...
|
||||||
|
├── hr-ui/ ← worktree or clone of hr-ui repo
|
||||||
|
└── ZeymoAPI/ ← worktree or clone of ZeymoAPI repo
|
||||||
|
```
|
||||||
|
|
||||||
|
Because the workspace's `.planning/` is separate from the source repos, there is no overlap or conflict with planning state that exists in the source repos themselves.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Create a workspace for multiple repos
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD creates worktrees of `hr-ui` and `ZeymoAPI` inside `~/gsd-workspaces/feature-b/`, checks out a `workspace/feature-b` branch in each, writes `WORKSPACE.md`, and creates an empty `.planning/` directory ready for `/gsd-new-project`.
|
||||||
|
|
||||||
|
To customise the location:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI --path /projects/feature-b
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Create a workspace for the current repo
|
||||||
|
|
||||||
|
When you want feature-branch isolation on a single repo — independent branch, independent `.planning/`, no state bleed from main:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workspace --new --name payments-rework --repos .
|
||||||
|
```
|
||||||
|
|
||||||
|
The `.` tells GSD to create a worktree of the current repo. The worktree is checked out on `workspace/payments-rework`.
|
||||||
|
|
||||||
|
To force a full clone instead of a worktree:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workspace --new --name payments-rework --repos . --strategy clone
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Specify a branch explicitly
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workspace --new --name payments-rework --repos . --branch feature/payments-v2
|
||||||
|
```
|
||||||
|
|
||||||
|
The `--branch` flag sets the branch name for all repos in the workspace. Defaults to `workspace/<name>`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Skip interactive questions
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workspace --new --name payments-rework --repos . --auto
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD accepts all defaults without prompting.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Initialise GSD inside the workspace
|
||||||
|
|
||||||
|
After creating a workspace, move into it and initialise a GSD project:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd ~/gsd-workspaces/feature-b
|
||||||
|
/gsd-new-project
|
||||||
|
```
|
||||||
|
|
||||||
|
The `.planning/` directory inside the workspace is the root for all subsequent GSD commands run from that directory. It is entirely separate from any `.planning/` that exists in the source repos.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## List workspaces
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workspace --list
|
||||||
|
```
|
||||||
|
|
||||||
|
Prints all active GSD workspaces and their status.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Remove a workspace
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workspace --remove feature-b
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD removes the git worktrees and cleans up the workspace directory. This does not delete the branches from the origin remote — only the local worktrees and workspace directory.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## When to use workspaces instead of workstreams
|
||||||
|
|
||||||
|
Choose workspaces when:
|
||||||
|
|
||||||
|
- You are working across **multiple repositories** that need to be co-ordinated under one GSD project (e.g., an API repo and a UI repo that ship together)
|
||||||
|
- You need a **separate git worktree** with its own branch, lock files, and build artefacts per feature — so builds and dependency installs in one environment cannot affect another
|
||||||
|
- You want a **wholly independent `.planning/` root** rather than a subdirectory of the main repo's `.planning/`
|
||||||
|
- You are following an issue-driven workflow where each tracker issue maps to a workspace (see [Drive GSD from a tracker issue](drive-gsd-from-a-tracker-issue.md))
|
||||||
|
|
||||||
|
Choose [workstreams](work-in-parallel-with-workstreams.md) instead when:
|
||||||
|
|
||||||
|
- All the work lives in **one repository** and shares the same git history
|
||||||
|
- You want to run `/gsd-plan-phase` or `/gsd-discuss-phase` on different concern areas concurrently — API, UI, infra — without context bleed between their `STATE.md` files
|
||||||
|
- You do not need a separate worktree per concern; switching planning context is sufficient
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Work in parallel with workstreams](work-in-parallel-with-workstreams.md)
|
||||||
|
- [Drive GSD from a tracker issue](drive-gsd-from-a-tracker-issue.md)
|
||||||
|
- [Commands](../COMMANDS.md)
|
||||||
|
- [docs index](../README.md)
|
||||||
145
docs/how-to/migrate-from-gsd-2.md
Normal file
145
docs/how-to/migrate-from-gsd-2.md
Normal file
@@ -0,0 +1,145 @@
|
|||||||
|
# How to migrate from GSD-2
|
||||||
|
|
||||||
|
**Goal:** Bring an older GSD-2 project (`.gsd/` directory layout) forward into GSD Core (`.planning/` layout), and optionally absorb any existing ADRs, PRDs, or specs that live in the repository into the new planning structure.
|
||||||
|
|
||||||
|
**Prerequisites:** GSD Core is installed. The GSD-2 project directory is available on disk.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Understand what migrates
|
||||||
|
|
||||||
|
GSD-2 used a `.gsd/` directory as its planning root. GSD Core uses `.planning/`. The migration reverses this: it reads `.gsd/` artifacts and writes them into the standard `.planning/` structure that all GSD Core commands expect.
|
||||||
|
|
||||||
|
| What exists in GSD-2 | What `/gsd-import --from-gsd2` produces |
|
||||||
|
|----------------------|-----------------------------------------|
|
||||||
|
| `.gsd/PROJECT.md` | `.planning/PROJECT.md` |
|
||||||
|
| `.gsd/ROADMAP.md` | `.planning/ROADMAP.md` |
|
||||||
|
| `.gsd/STATE.md` | `.planning/STATE.md` |
|
||||||
|
| `.gsd/phases/` directories | `.planning/phases/` directories |
|
||||||
|
| Phase `PLAN.md` files | GSD Core `{NN}-{MM}-PLAN.md` files (renaming enforced) |
|
||||||
|
|
||||||
|
Conflict detection runs before any files are written. If the target directory already has a `PROJECT.md` and the imported content contradicts it, the migration stops at the BLOCKER gate and lists the conflicts for you to resolve.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Run the migration
|
||||||
|
|
||||||
|
### Migrate the current directory
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-import --from-gsd2
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD reads `.gsd/` in the current working directory and writes the migrated artifacts into `.planning/`.
|
||||||
|
|
||||||
|
### Migrate from a different path
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-import --from-gsd2 --path ~/projects/old-project
|
||||||
|
```
|
||||||
|
|
||||||
|
Use `--path` when the GSD-2 project is not your current working directory.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resolve conflicts
|
||||||
|
|
||||||
|
If conflict detection finds blockers — for example, a GSD-2 tech-stack declaration that contradicts an existing `.planning/PROJECT.md` — it prints a conflict report and stops without writing any files.
|
||||||
|
|
||||||
|
Read the report, resolve the contradiction (edit the source document or the existing planning artifact), then re-run `/gsd-import --from-gsd2`. The migration is safe to re-run until it passes cleanly.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Import an external plan file
|
||||||
|
|
||||||
|
If you have a standalone plan document (a team planning document, a Markdown spec, an exported task list) rather than a full GSD-2 project, use `--from` instead:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-import --from /tmp/team-plan.md
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD performs the same conflict-detection pass, converts the content to GSD Core `PLAN.md` format, and validates the result with the plan-checker. After validation you will see the target filename and next steps.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Absorb existing documentation
|
||||||
|
|
||||||
|
If your repository already contains ADRs (Architecture Decision Records), PRDs, or specification documents, use `/gsd-ingest-docs` to synthesise them into the `.planning/` structure after migration:
|
||||||
|
|
||||||
|
### Scan the whole repository (auto-detects mode)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-ingest-docs
|
||||||
|
```
|
||||||
|
|
||||||
|
If `.planning/` is already present (for example, from the migration you just ran), GSD defaults to merge mode — it synthesises the ingested documents alongside what is already there rather than overwriting it.
|
||||||
|
|
||||||
|
### Scope to a specific directory
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-ingest-docs docs/
|
||||||
|
/gsd-ingest-docs docs/adr/
|
||||||
|
```
|
||||||
|
|
||||||
|
### Use an explicit precedence manifest
|
||||||
|
|
||||||
|
When documents have mixed types or you want to control which document wins on conflicts:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-ingest-docs --manifest ingest.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
The manifest is a YAML file listing `{path, type, precedence?}` per document. See the `--manifest` flag description in [Commands](../COMMANDS.md) for the expected shape.
|
||||||
|
|
||||||
|
### Force a specific mode
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-ingest-docs --mode merge # Merge into existing .planning/
|
||||||
|
/gsd-ingest-docs --mode new # Bootstrap from scratch (overwrites)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output:** `/gsd-ingest-docs` always produces an `INGEST-CONFLICTS.md` with three buckets — auto-resolved, competing-variants, and unresolved-blockers. Review this file after every ingest run. Hard-stops only occur on LOCKED-vs-LOCKED ADR contradictions; everything else is surfaced for your review, not silently discarded.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Verify the migrated project
|
||||||
|
|
||||||
|
Once migration and any doc ingestion are complete, confirm the project state is consistent:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-health
|
||||||
|
/gsd-health --repair
|
||||||
|
```
|
||||||
|
|
||||||
|
`/gsd-health` checks `.planning/` directory integrity and reports any drift. `--repair` auto-fixes recoverable issues.
|
||||||
|
|
||||||
|
Then check that GSD Core can read your project state:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-progress
|
||||||
|
```
|
||||||
|
|
||||||
|
If the project came across cleanly you will see the current phase status and the recommended next step. From here the standard GSD Core workflow applies.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Conditionals: what migrates and what does not
|
||||||
|
|
||||||
|
| Situation | What to do |
|
||||||
|
|-----------|-----------|
|
||||||
|
| `.gsd/` exists in the current directory | Run `/gsd-import --from-gsd2` (no `--path` needed) |
|
||||||
|
| `.gsd/` is in a different directory | Use `--path ~/projects/old-project` |
|
||||||
|
| You have a standalone plan document, not a full GSD-2 project | Use `/gsd-import --from /path/to/plan.md` |
|
||||||
|
| You have ADRs in `docs/adr/` | Run `/gsd-ingest-docs docs/adr/` after migration |
|
||||||
|
| You have a mix of ADRs, PRDs, and specs | Run `/gsd-ingest-docs` at repo root; it classifies automatically |
|
||||||
|
| Conflict detection reports blockers | Resolve the listed contradictions then re-run; no files are written until all blockers clear |
|
||||||
|
| You are not sure whether migration worked | Run `/gsd-health` and `/gsd-progress` to confirm |
|
||||||
|
| INGEST-CONFLICTS.md lists unresolved blockers | These require manual resolution before affected documents are incorporated into planning |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Your first project](../tutorials/your-first-project.md)
|
||||||
|
- [Commands](../COMMANDS.md)
|
||||||
|
- [docs index](../README.md)
|
||||||
216
docs/how-to/plan-a-phase.md
Normal file
216
docs/how-to/plan-a-phase.md
Normal file
@@ -0,0 +1,216 @@
|
|||||||
|
# How to plan a phase
|
||||||
|
|
||||||
|
**Goal:** Turn phase decisions and research into an atomic, verifiable task plan ready for execution.
|
||||||
|
|
||||||
|
**Prerequisites:** `.planning/ROADMAP.md` exists. A `{phase}-CONTEXT.md` from `/gsd-discuss-phase` is strongly recommended but not required.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Run the standard planning flow
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 2
|
||||||
|
```
|
||||||
|
|
||||||
|
This runs three stages in sequence:
|
||||||
|
|
||||||
|
1. **Research** — A `gsd-phase-researcher` subagent investigates the domain and writes `{phase}-RESEARCH.md`.
|
||||||
|
2. **Plan** — A `gsd-planner` subagent reads context, research, and requirements, then writes one or more `{phase}-{N}-PLAN.md` files.
|
||||||
|
3. **Verify** — A `gsd-plan-checker` subagent validates plan quality across eight dimensions and triggers a revision loop (up to three iterations) until quality gates pass.
|
||||||
|
|
||||||
|
If no phase number is given, GSD Core targets the next unplanned phase from the roadmap.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Skip or force research
|
||||||
|
|
||||||
|
**If the domain is familiar and you do not need new research:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 3 --skip-research
|
||||||
|
```
|
||||||
|
|
||||||
|
**If RESEARCH.md already exists but you want to force a refresh:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 3 --research
|
||||||
|
```
|
||||||
|
|
||||||
|
**If you want to run research only** — write RESEARCH.md and exit before planning:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase --research-phase 4
|
||||||
|
```
|
||||||
|
|
||||||
|
If RESEARCH.md already exists, you are prompted to update, view, or skip. To force-refresh without the prompt:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase --research-phase 4 --research
|
||||||
|
```
|
||||||
|
|
||||||
|
To print existing RESEARCH.md to stdout without spawning the researcher:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase --research-phase 4 --view
|
||||||
|
```
|
||||||
|
|
||||||
|
Note: `--research-phase <N>` is a flag on `/gsd-plan-phase`. There is no standalone research-phase command — the removed standalone research command was retired in favour of this flag.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Plan vertical feature slices instead of horizontal layers
|
||||||
|
|
||||||
|
**If you want tasks organised as thin end-to-end slices** (UI → API → DB per feature) rather than by technical layer:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 1 --mvp
|
||||||
|
```
|
||||||
|
|
||||||
|
On Phase 1 of a new project with no prior phase summaries, `--mvp` also produces `SKELETON.md` — a Walking Skeleton covering project scaffold, routing, one real DB read/write, one real UI interaction, and dev deployment.
|
||||||
|
|
||||||
|
You can persist MVP mode for a phase without the flag by adding `**Mode:** mvp` to that phase's entry in ROADMAP.md.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Require a failing test per behaviour-adding task
|
||||||
|
|
||||||
|
**If you want TDD enforcement** — each behaviour-adding task begins with a failing test before implementation:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 1 --tdd
|
||||||
|
```
|
||||||
|
|
||||||
|
Composable with `--mvp`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 1 --mvp --tdd
|
||||||
|
```
|
||||||
|
|
||||||
|
This produces vertical slices where every behaviour-adding task follows RED → GREEN → REFACTOR. The planner applies `type: tdd` to eligible tasks (business logic, API endpoints, data transformations) and uses standard `type: execute` for UI, configuration, and glue code.
|
||||||
|
|
||||||
|
TDD mode can also be persisted in config:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node gsd-tools.cjs config-set workflow.tdd_mode true
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Replan using cross-AI review feedback
|
||||||
|
|
||||||
|
**If you have run `/gsd-review --phase N` and a `REVIEWS.md` exists:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 3 --reviews
|
||||||
|
```
|
||||||
|
|
||||||
|
The planner reads `REVIEWS.md` and revises plans to address the feedback. Cannot be combined with `--gaps`.
|
||||||
|
|
||||||
|
**If you want an automated loop** — replan and re-review until no HIGH concerns remain:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-review-convergence 3
|
||||||
|
```
|
||||||
|
|
||||||
|
The convergence loop runs plan → review → replan → re-review cycles (up to three by default). Use `--max-cycles N` to override the cap.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Close gaps after a failed verification
|
||||||
|
|
||||||
|
**If `VERIFICATION.md` exists with unresolved gaps and you want to replan against those gaps only:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 3 --gaps
|
||||||
|
```
|
||||||
|
|
||||||
|
Research is skipped; the planner reads the verification gaps directly.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Validate project state before planning begins
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 2 --validate
|
||||||
|
```
|
||||||
|
|
||||||
|
Runs state validation before spawning the researcher. Use this if you suspect ROADMAP.md or STATE.md has drifted.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Run an external bounce validation after planning
|
||||||
|
|
||||||
|
**If `workflow.plan_bounce_script` is configured and you want external validation of the finished plan:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 1 --bounce
|
||||||
|
```
|
||||||
|
|
||||||
|
To skip bounce even if it is enabled in config:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 1 --skip-bounce
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Suppress interactive confirmations
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase --auto
|
||||||
|
```
|
||||||
|
|
||||||
|
Skips all prompts. Useful in automated pipelines. Research is skipped if `research_enabled` is false in config.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What the plan produces
|
||||||
|
|
||||||
|
A successful run writes:
|
||||||
|
|
||||||
|
| File | Purpose |
|
||||||
|
|---|---|
|
||||||
|
| `{phase}-RESEARCH.md` | Domain research, package legitimacy audit, validation architecture |
|
||||||
|
| `{phase}-VALIDATION.md` | Nyquist test-mapping — the test cases the plan must satisfy (Dimension 8) |
|
||||||
|
| `{phase}-{N}-PLAN.md` | Executable task plan with frontmatter, wave assignments, and acceptance criteria |
|
||||||
|
| `{phase}/SKELETON.md` | Walking Skeleton (MVP mode, Phase 1 of new project only) |
|
||||||
|
|
||||||
|
Each PLAN.md contains tasks with mandatory `<read_first>` and `<acceptance_criteria>` fields. Every `<acceptance_criteria>` entry is verifiable as a source assertion, behaviour assertion, test command, or CLI output — never subjective language.
|
||||||
|
|
||||||
|
For the full field reference see [PLAN.md schema](../reference/plan-md.md).
|
||||||
|
|
||||||
|
### Plan quality dimensions
|
||||||
|
|
||||||
|
The `gsd-plan-checker` validates plans across eight dimensions before allowing execution:
|
||||||
|
|
||||||
|
1. Task atomicity — each task is a single concern
|
||||||
|
2. Dependency correctness — wave ordering is consistent
|
||||||
|
3. Acceptance criteria verifiability — no subjective criteria
|
||||||
|
4. `<read_first>` completeness — the file being modified is always listed
|
||||||
|
5. Concrete `<action>` values — no vague "align with" instructions
|
||||||
|
6. `must_haves` derived from phase goal
|
||||||
|
7. Requirement ID coverage — every phase requirement ID appears in at least one plan
|
||||||
|
8. Nyquist test mapping — plans address the validation strategy in VALIDATION.md
|
||||||
|
|
||||||
|
The revision loop runs up to three times. If quality gates have not passed after three iterations, the checker surfaces remaining issues for manual review.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Replanning a closed phase
|
||||||
|
|
||||||
|
If a phase has `VERIFICATION.md` with `status: passed`, it is considered closed. Attempting to replan it stops with an error. If the closeout was incorrect, override with `--force`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 2 --force
|
||||||
|
```
|
||||||
|
|
||||||
|
A warning is emitted into the transcript and any committed plan docs.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Discuss a phase](discuss-a-phase.md)
|
||||||
|
- [Execute a phase](execute-a-phase.md)
|
||||||
|
- [PLAN.md schema](../reference/plan-md.md)
|
||||||
|
- [Commands](../COMMANDS.md)
|
||||||
323
docs/how-to/recover-and-troubleshoot.md
Normal file
323
docs/how-to/recover-and-troubleshoot.md
Normal file
@@ -0,0 +1,323 @@
|
|||||||
|
# How to recover and troubleshoot
|
||||||
|
|
||||||
|
**Goal:** Identify and fix common problems — from lost context and corrupted state to installation failures and permission errors — using a conditional recipe structure.
|
||||||
|
|
||||||
|
**Prerequisites:** GSD Core is installed. For install problems specifically, see [Install on your runtime](install-on-your-runtime.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context and session problems
|
||||||
|
|
||||||
|
### If you have lost track of where you are
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-progress
|
||||||
|
```
|
||||||
|
|
||||||
|
Reads all state files and tells you exactly where you are and what to do next.
|
||||||
|
|
||||||
|
To automatically advance to the correct next step:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-progress --next
|
||||||
|
```
|
||||||
|
|
||||||
|
### If you are starting a new session and need to restore context
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-resume-work
|
||||||
|
```
|
||||||
|
|
||||||
|
Restores your full session context from the last handoff, including current phase, planning decisions, and where work stopped.
|
||||||
|
|
||||||
|
### If quality is dropping during a long session
|
||||||
|
|
||||||
|
Clear your context window between major commands:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/clear
|
||||||
|
```
|
||||||
|
|
||||||
|
Then restore state:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-resume-work
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD is designed around fresh contexts. Every subagent already gets a clean 200k window. The main session degrades over time — clearing it and resuming is the correct remedy, not pushing on.
|
||||||
|
|
||||||
|
### If you want to save context before stopping
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-pause-work
|
||||||
|
```
|
||||||
|
|
||||||
|
Creates `.planning/HANDOFF.json` with your current position. Add `--report` to also write a post-session summary to `.planning/reports/`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-pause-work --report
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Planning integrity problems
|
||||||
|
|
||||||
|
### If `.planning/` integrity is uncertain
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-health
|
||||||
|
```
|
||||||
|
|
||||||
|
Reports status across errors, warnings, and informational notes:
|
||||||
|
|
||||||
|
| Status | Meaning |
|
||||||
|
|--------|---------|
|
||||||
|
| `HEALTHY` | All expected artefacts present and well-formed |
|
||||||
|
| `DEGRADED` | Warnings that should be addressed but work can continue |
|
||||||
|
| `BROKEN` | Critical errors that will block execution |
|
||||||
|
|
||||||
|
Common auto-repairable issues (errors E004, E005; warnings W003, W008):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-health --repair
|
||||||
|
```
|
||||||
|
|
||||||
|
This recreates missing `STATE.md`, resets a corrupt `config.json` to defaults, and adds any missing configuration keys. It will not overwrite `PROJECT.md` or `ROADMAP.md`.
|
||||||
|
|
||||||
|
### If STATE.md references a phase that does not exist
|
||||||
|
|
||||||
|
This produces warning `W002`. Use the state CLI to diagnose and repair:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate
|
||||||
|
```
|
||||||
|
|
||||||
|
Preview what a sync would change without writing:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify
|
||||||
|
```
|
||||||
|
|
||||||
|
Apply the sync:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync
|
||||||
|
```
|
||||||
|
|
||||||
|
These commands reconstruct `STATE.md` from actual project state on disk. They replace manual `STATE.md` editing.
|
||||||
|
|
||||||
|
### If you see "Project already initialised"
|
||||||
|
|
||||||
|
`.planning/PROJECT.md` already exists. `/gsd-new-project` is a safety check. If you genuinely want to start over, delete the `.planning/` directory first:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
rm -rf .planning/
|
||||||
|
```
|
||||||
|
|
||||||
|
Then re-run `/gsd-new-project`.
|
||||||
|
|
||||||
|
### If context-window utilisation is high
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-health --context
|
||||||
|
```
|
||||||
|
|
||||||
|
Probes the context-window utilisation guard. Warns at 60 %, critical at 70 %. If you are above the warning threshold, run `/clear` followed by `/gsd-resume-work` before starting the next major command.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Execution problems
|
||||||
|
|
||||||
|
### If an executor gets "Permission denied" on Bash commands
|
||||||
|
|
||||||
|
GSD's `gsd-executor` subagents need write-capable Bash access. Add the required patterns to `~/.claude/settings.json` under `permissions.allow`. At minimum:
|
||||||
|
|
||||||
|
```json
|
||||||
|
"Bash(git add:*)",
|
||||||
|
"Bash(git commit:*)",
|
||||||
|
"Bash(git merge:*)",
|
||||||
|
"Bash(git checkout:*)"
|
||||||
|
```
|
||||||
|
|
||||||
|
For stack-specific patterns (Rails, Python, Node, Rust), see the full table in `docs/USER-GUIDE.md` under "Executor Subagent Gets Permission denied".
|
||||||
|
|
||||||
|
Per-project alternative: add the same block to `.claude/settings.local.json` in your project root.
|
||||||
|
|
||||||
|
### If execution fails or produces stubs
|
||||||
|
|
||||||
|
Check whether the plan is too ambitious. Plans should have two or three tasks at most. If tasks are too large they exceed what a single context window can produce reliably. Re-plan the phase with smaller scope:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 1
|
||||||
|
```
|
||||||
|
|
||||||
|
For systematic diagnosis of what went wrong, see [Debug a failed execution](debug-a-failed-execution.md).
|
||||||
|
|
||||||
|
### If parallel execution causes build lock errors or pre-commit hook failures
|
||||||
|
|
||||||
|
This is caused by multiple agents triggering build tools simultaneously. GSD handles this automatically since v1.26. If you are on an older version, or still seeing contention, disable parallel execution:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-settings
|
||||||
|
```
|
||||||
|
|
||||||
|
Set `parallelization.enabled` to `false`.
|
||||||
|
|
||||||
|
### If a subagent appears to fail but commits were made
|
||||||
|
|
||||||
|
Check git log before concluding something broke:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git log --oneline -10
|
||||||
|
```
|
||||||
|
|
||||||
|
A known Claude Code classification bug can report failure while work succeeded. GSD's orchestrators spot-check actual output, but if you see a mismatch, the commits are the ground truth.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Plan and phase problems
|
||||||
|
|
||||||
|
### If plans seem wrong or misaligned with your intent
|
||||||
|
|
||||||
|
Run `/gsd-discuss-phase N` before planning. Most plan quality issues come from assumptions that `CONTEXT.md` would have prevented:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-discuss-phase 1
|
||||||
|
```
|
||||||
|
|
||||||
|
To see what assumptions GSD is currently making without starting a full session:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-discuss-phase 3 --assumptions
|
||||||
|
```
|
||||||
|
|
||||||
|
### If you need to change something after execution
|
||||||
|
|
||||||
|
Do not re-run `/gsd-execute-phase`. Use `/gsd-quick` for targeted fixes:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-quick "Fix the login button not responding on mobile Safari"
|
||||||
|
```
|
||||||
|
|
||||||
|
Or use `/gsd-verify-work N` to systematically identify and fix issues through UAT.
|
||||||
|
|
||||||
|
### If a command appears frozen at "Spawning…"
|
||||||
|
|
||||||
|
Wait. GSD subagents run in a separate context window. Their work is invisible to the parent session while in progress. The liveness note on the spawn line confirms this is expected. Research and planning agents routinely take 1–5 minutes; verification agents can take longer on large phases.
|
||||||
|
|
||||||
|
Do not interrupt the session. Killing it discards in-progress subagent work.
|
||||||
|
|
||||||
|
If it has been more than 10 minutes, check whether the agent task still shows as active in the Claude Code sidebar.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workflow state problems
|
||||||
|
|
||||||
|
### If the workflow seems corrupted or state is inconsistent
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-forensics
|
||||||
|
```
|
||||||
|
|
||||||
|
Or with a description:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-forensics "Phase 3 execution stalled after wave 1"
|
||||||
|
```
|
||||||
|
|
||||||
|
`/gsd-forensics` runs a post-mortem investigation: git history anomalies, artefact integrity, STATE.md consistency, uncommitted work, and orphaned worktrees. It writes a report to `.planning/forensics/` and surfaces recommended remediation steps. It is read-only and never modifies your project files.
|
||||||
|
|
||||||
|
### If you need to roll back a phase or plan
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-undo --phase 03 # Roll back all commits for phase 3
|
||||||
|
/gsd-undo --plan 03-02 # Roll back commits for plan 02 of phase 3
|
||||||
|
/gsd-undo --last 5 # Pick interactively from the 5 most recent GSD commits
|
||||||
|
```
|
||||||
|
|
||||||
|
`/gsd-undo` checks dependent phases before reverting and always shows a confirmation gate.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Install and update problems
|
||||||
|
|
||||||
|
### If GSD is not recognised after install
|
||||||
|
|
||||||
|
Restart your runtime. GSD installs slash commands into your runtime's command directory (for example `~/.claude/commands/gsd/`). Most runtimes discover new commands only at startup.
|
||||||
|
|
||||||
|
If the problem persists, verify the install:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --claude --local
|
||||||
|
```
|
||||||
|
|
||||||
|
For runtime-specific install paths and troubleshooting, see [Install on your runtime](install-on-your-runtime.md).
|
||||||
|
|
||||||
|
### If an update overwrote your local changes
|
||||||
|
|
||||||
|
Since v1.17, the installer backs up locally modified files to `gsd-local-patches/`. Reapply your changes:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-update --reapply
|
||||||
|
```
|
||||||
|
|
||||||
|
### If you cannot update via npm
|
||||||
|
|
||||||
|
If `npx @opengsd/gsd-core` fails due to npm outages or network restrictions, see `docs/manual-update.md` for a step-by-step manual update procedure that works without npm access.
|
||||||
|
|
||||||
|
For routine updates, see [Update GSD](update-gsd.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Cost problems
|
||||||
|
|
||||||
|
### If model costs are too high
|
||||||
|
|
||||||
|
Switch to the budget profile:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-config --profile budget
|
||||||
|
```
|
||||||
|
|
||||||
|
Disable research and plan-check agents via settings if the domain is familiar:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-settings
|
||||||
|
```
|
||||||
|
|
||||||
|
Also audit which MCP servers are enabled. Every enabled MCP server injects its tool schema into every turn. Browser and platform-specific tools can cost 20k+ tokens each. Disable any that the current phase does not need in `.claude/settings.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"disabledMcpjsonServers": ["playwright", "mac-tools"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Recovery quick reference
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
|---------|---------|
|
||||||
|
| Lost context or new session | `/gsd-resume-work` or `/gsd-progress` |
|
||||||
|
| Don't know what step is next | `/gsd-progress --next` |
|
||||||
|
| Phase went wrong | `/gsd-undo --phase NN`, then re-plan |
|
||||||
|
| Something broke | `/gsd-debug "description"` (add `--diagnose` for analysis without fixes) |
|
||||||
|
| STATE.md out of sync | `state validate` then `state sync` |
|
||||||
|
| `.planning/` integrity uncertain | `/gsd-health`, then `/gsd-health --repair` |
|
||||||
|
| Workflow state seems corrupted | `/gsd-forensics` |
|
||||||
|
| Quick targeted fix | `/gsd-quick` |
|
||||||
|
| Plan doesn't match your vision | `/gsd-discuss-phase N` then re-plan |
|
||||||
|
| Costs running high | `/gsd-config --profile budget` and `/gsd-settings` to toggle agents off |
|
||||||
|
| Update broke local changes | `/gsd-update --reapply` |
|
||||||
|
| Want session summary | `/gsd-pause-work --report` |
|
||||||
|
| Parallel execution build errors | Update GSD or set `parallelization.enabled: false` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Debug a failed execution](debug-a-failed-execution.md)
|
||||||
|
- [Install on your runtime](install-on-your-runtime.md)
|
||||||
|
- [Commands](../COMMANDS.md)
|
||||||
|
- [docs index](../README.md)
|
||||||
124
docs/how-to/run-phases-autonomously.md
Normal file
124
docs/how-to/run-phases-autonomously.md
Normal file
@@ -0,0 +1,124 @@
|
|||||||
|
# How to run phases autonomously
|
||||||
|
|
||||||
|
Run all remaining phases — or a bounded range of them — unattended, so GSD moves through discuss → plan → execute for each phase without you driving every step.
|
||||||
|
|
||||||
|
For background on what the phase loop is doing during an autonomous run, see [The phase loop](../explanation/the-phase-loop.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- An active project with `.planning/ROADMAP.md` and `.planning/STATE.md`
|
||||||
|
- All phases you want to run must be in a state that autonomous mode can drive (pending or in-progress; not already complete)
|
||||||
|
- Any design decisions you care about should already be in `PROJECT.md` or captured via a prior `/gsd-discuss-phase` — autonomous mode can surface grey areas interactively only when you use `--interactive`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Run all remaining phases
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-autonomous
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD reads `ROADMAP.md`, discovers every incomplete phase in numeric order, and runs discuss → plan → execute on each one. After all phases complete it automatically runs the milestone lifecycle: audit → complete → cleanup.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Run a specific range of phases
|
||||||
|
|
||||||
|
Use `--from` and `--to` to bound the run. Both flags accept decimal phase numbers (e.g. `3.1`).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-autonomous --from 3 # phases 3, 4, 5 … (skip already-done phases 1 and 2)
|
||||||
|
/gsd-autonomous --to 5 # phases up to and including 5
|
||||||
|
/gsd-autonomous --from 3 --to 5 # exactly phases 3, 4, and 5
|
||||||
|
```
|
||||||
|
|
||||||
|
When `--to` is reached the lifecycle step is skipped, because not all milestone phases are done. The completion banner tells you how to resume:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Resume with: /gsd-autonomous --from 6
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Run with interactive discuss
|
||||||
|
|
||||||
|
By default, autonomous mode answers discuss questions automatically using smart discuss (batch table proposals). If you want to answer design questions yourself while keeping plan and execute out of the main context:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-autonomous --interactive
|
||||||
|
```
|
||||||
|
|
||||||
|
In interactive mode:
|
||||||
|
- `/gsd-discuss-phase` runs inline and waits for your answers
|
||||||
|
- Planning and execution are dispatched as background agents so you can discuss the next phase while the current one builds
|
||||||
|
- The main context stays lean — only discuss conversations accumulate
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What safety gates still apply
|
||||||
|
|
||||||
|
Autonomous mode does not bypass GSD's quality pipeline. Each phase still:
|
||||||
|
|
||||||
|
- Runs the plan-checker before execution
|
||||||
|
- Reads `VERIFICATION.md` after execution and routes on the result
|
||||||
|
- Pauses and asks you what to do when verification status is `human_needed` or `gaps_found`
|
||||||
|
- Stops and presents options (fix and retry, skip phase, or stop) if any step fails
|
||||||
|
|
||||||
|
The only difference from manual execution is that `passed` verification advances automatically — you are not prompted between phases unless a decision is required.
|
||||||
|
|
||||||
|
The package legitimacy gate also remains active. If a plan includes a `checkpoint:human-verify` task for a suspicious package, the executor will stop and surface the checkpoint. Autonomous mode will not silently install flagged packages.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## When not to use autonomous mode
|
||||||
|
|
||||||
|
Do not use `/gsd-autonomous` when:
|
||||||
|
|
||||||
|
- **Phases have unsettled design decisions.** If you have not run `/gsd-discuss-phase` and your `PROJECT.md` does not capture your preferences, smart discuss will make autonomous choices you may not agree with. Run discuss interactively first, or use `--interactive`.
|
||||||
|
|
||||||
|
- **You need fine-grained control over a single phase.** For one phase, `/gsd-execute-phase N` gives you step-by-step output and lets you react before continuing. Autonomous mode is designed for bulk unattended runs.
|
||||||
|
|
||||||
|
- **The phase has novel or high-risk work.** Autonomous mode skips pauses unless it hits a blocker. On a phase where you expect surprises, stay in the loop with manual execution.
|
||||||
|
|
||||||
|
- **You are mid-phase with partial execution.** Autonomous mode picks up incomplete phases but it does not resume a partially-executed wave. Use `/gsd-execute-phase N` to finish a phase that is already in progress.
|
||||||
|
|
||||||
|
If a run stops partway through, see [Debug a failed execution](debug-a-failed-execution.md) for how to diagnose what went wrong.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Checking progress during a run
|
||||||
|
|
||||||
|
Autonomous mode prints a progress banner before each phase:
|
||||||
|
|
||||||
|
```text
|
||||||
|
GSD ► AUTONOMOUS ▸ Phase 3/7: Auth Middleware [████░░░░] 28%
|
||||||
|
```
|
||||||
|
|
||||||
|
If you need to check where the run stands mid-session, open another terminal and run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-progress
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resuming after a stop
|
||||||
|
|
||||||
|
If autonomous mode stops — whether you chose "Stop autonomous mode" from the blocker prompt, or the session was interrupted — resume from where it left off:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-autonomous --from 4 # replace 4 with the first incomplete phase number
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD skips already-complete phases automatically, so it is safe to re-run from an earlier phase number if you are not sure where the run stopped.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Execute a phase](execute-a-phase.md)
|
||||||
|
- [Debug a failed execution](debug-a-failed-execution.md)
|
||||||
|
- [Commands](../COMMANDS.md)
|
||||||
|
- [Docs index](../README.md)
|
||||||
159
docs/how-to/set-up-cross-ai-review.md
Normal file
159
docs/how-to/set-up-cross-ai-review.md
Normal file
@@ -0,0 +1,159 @@
|
|||||||
|
# How to set up cross-AI review
|
||||||
|
|
||||||
|
**Goal:** Configure which AI reviewers participate in plan review, run a review of a planned phase, and use the feedback to converge on a plan with no HIGH-severity concerns.
|
||||||
|
|
||||||
|
**Prerequisites:** The phase has been planned (`{phase}-PLAN.md` files exist in `.planning/phases/`). At least one external AI CLI is installed and authenticated.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decide which reviewers to use
|
||||||
|
|
||||||
|
GSD Core can route review requests to any combination of: Gemini CLI, Claude (separate session), Codex CLI, CodeRabbit, OpenCode, Qwen Code, Cursor, Antigravity CLI, Ollama, LM Studio, and llama.cpp.
|
||||||
|
|
||||||
|
Each reviewer runs the same structured prompt against your `PLAN.md` files independently. Because different models have different blind spots, multi-reviewer consensus catches more issues than any single reviewer.
|
||||||
|
|
||||||
|
**If you have no external CLIs installed yet**, install at least one:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Gemini CLI (free with Google credentials)
|
||||||
|
npm install -g @google/gemini-cli
|
||||||
|
|
||||||
|
# Antigravity CLI (free with Google credentials)
|
||||||
|
curl -fsSL https://antigravity.google/cli/install.sh | bash
|
||||||
|
|
||||||
|
# Codex CLI
|
||||||
|
npm install -g @openai/codex
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Set default reviewers (optional)
|
||||||
|
|
||||||
|
By default, `/gsd-review` runs all detected CLIs. To pin a subset as project defaults:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-config --integrations
|
||||||
|
```
|
||||||
|
|
||||||
|
The integrations wizard covers API keys, code-review CLI routing, and the `review.default_reviewers` list. Set the list to the reviewers you want as the no-flag default — for example `["gemini","codex"]`.
|
||||||
|
|
||||||
|
Alternatively, set it directly with `gsd-tools`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
gsd config-set review.default_reviewers '["gemini","codex"]'
|
||||||
|
```
|
||||||
|
|
||||||
|
For the full integration settings schema (API keys, model overrides per reviewer, local server host addresses), see [Configuration](../CONFIGURATION.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Run a review
|
||||||
|
|
||||||
|
### Standard review (uses your configured defaults or all detected CLIs)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-review --phase 3
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD invokes each reviewer in sequence, collects structured feedback (Summary, Strengths, Concerns at HIGH/MEDIUM/LOW, Suggestions, Risk Assessment), and writes the combined output to `.planning/phases/03-.../03-REVIEWS.md`.
|
||||||
|
|
||||||
|
### Select a single reviewer for a one-off run
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-review --phase 3 --gemini
|
||||||
|
/gsd-review --phase 3 --codex
|
||||||
|
/gsd-review --phase 3 --cursor
|
||||||
|
```
|
||||||
|
|
||||||
|
Any explicit flag overrides both the `--all` default and `review.default_reviewers` for that run.
|
||||||
|
|
||||||
|
### Run every available reviewer in parallel
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-review --phase 3 --all
|
||||||
|
```
|
||||||
|
|
||||||
|
`--all` always overrides config and runs the full detected set, including any configured local model servers (Ollama, LM Studio, llama.cpp).
|
||||||
|
|
||||||
|
### Local model server reviewers
|
||||||
|
|
||||||
|
If you run Ollama or LM Studio locally, they are included automatically with `--all` when the server is reachable. You can also target them explicitly:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-review --phase 3 --ollama
|
||||||
|
/gsd-review --phase 3 --lm-studio
|
||||||
|
```
|
||||||
|
|
||||||
|
Configure the host addresses and model selection under `review.*` keys via `/gsd-config --integrations` if the defaults (`localhost:11434` / `localhost:1234`) do not apply.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Read the review output
|
||||||
|
|
||||||
|
The `{padded_phase}-REVIEWS.md` file contains:
|
||||||
|
|
||||||
|
- Individual reviews from each reviewer with severity-classified concerns
|
||||||
|
- A **Consensus Summary** section that synthesises concerns raised by two or more reviewers — start here for the highest-priority signal
|
||||||
|
- A **Divergent Views** section for areas where reviewers disagreed
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Incorporate feedback into the plan
|
||||||
|
|
||||||
|
Once you have reviewed the output, replan incorporating the feedback:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 3 --reviews
|
||||||
|
```
|
||||||
|
|
||||||
|
The planner reads `REVIEWS.md` and adjusts the plans to address the concerns before saving.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Automate the plan–review–replan loop
|
||||||
|
|
||||||
|
For phases where you want to iterate until all HIGH-severity concerns are resolved, use the convergence loop:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-review-convergence 3
|
||||||
|
```
|
||||||
|
|
||||||
|
This runs `plan-phase → review → replan → re-review` up to three cycles (default). The loop exits when the HIGH-concern count reaches zero.
|
||||||
|
|
||||||
|
### Convergence with a specific reviewer
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-review-convergence 3 --codex
|
||||||
|
/gsd-plan-review-convergence 3 --gemini
|
||||||
|
```
|
||||||
|
|
||||||
|
### Convergence with all reviewers and a higher cycle cap
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-review-convergence 3 --all --max-cycles 5
|
||||||
|
```
|
||||||
|
|
||||||
|
**Stall detection:** if the HIGH-concern count is not decreasing across cycles, GSD warns you. When the cycle cap is reached with open HIGH concerns, an escalation gate asks whether to proceed or review manually.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Conditionals: which reviewers to choose
|
||||||
|
|
||||||
|
| Situation | Recommended approach |
|
||||||
|
|-----------|---------------------|
|
||||||
|
| You have Gemini CLI already installed | `--gemini` is always a good starting reviewer |
|
||||||
|
| You want free multi-reviewer coverage | `--gemini` + `--agy` (both use Google credentials) |
|
||||||
|
| Your project is OpenAI-heavy | add `--codex` for an OpenAI-model perspective |
|
||||||
|
| You want GitHub Copilot's model | add `--opencode` |
|
||||||
|
| You want to avoid API costs entirely | configure Ollama with a local model and use `--ollama` |
|
||||||
|
| You need maximum coverage before a release | `/gsd-plan-review-convergence N --all` |
|
||||||
|
| You're iterating quickly and want fast feedback | pick one CLI: `/gsd-review --phase N --gemini` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Verify and ship](verify-and-ship.md)
|
||||||
|
- [Configuration](../CONFIGURATION.md)
|
||||||
|
- [Commands](../COMMANDS.md)
|
||||||
|
- [docs index](../README.md)
|
||||||
160
docs/how-to/spike-and-sketch.md
Normal file
160
docs/how-to/spike-and-sketch.md
Normal file
@@ -0,0 +1,160 @@
|
|||||||
|
# How to spike and sketch before committing
|
||||||
|
|
||||||
|
**Goal:** De-risk an implementation by running focused feasibility experiments (spikes) and exploring visual directions through throwaway HTML mockups (sketches) before committing a phase to any specific approach.
|
||||||
|
|
||||||
|
**Prerequisites:** None. `/gsd-spike` and `/gsd-sketch` create their own storage directories and do not require an initialised GSD project.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decide: spike, sketch, or both
|
||||||
|
|
||||||
|
| You want to answer… | Use |
|
||||||
|
|---|---|
|
||||||
|
| "Will this technical approach actually work?" | `/gsd-spike` |
|
||||||
|
| "Does this layout / interaction / visual treatment feel right?" | `/gsd-sketch` |
|
||||||
|
| "What's the right technical approach, and what should it look like?" | Both, in order: spike first, then sketch |
|
||||||
|
|
||||||
|
Spikes answer binary feasibility questions with executable code and a VALIDATED / INVALIDATED / PARTIAL verdict. Sketches answer visual questions with 2–3 browser-comparable HTML variants. They are complementary — a spike proves the approach is buildable, a sketch proves the design is worth building.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Run a spike
|
||||||
|
|
||||||
|
### Interactive intake (default)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-spike
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD asks about the technical question, decomposes it into 2–5 independent experiments framed as **Given / When / Then** hypotheses, and asks for confirmation before building.
|
||||||
|
|
||||||
|
### Provide the idea directly
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-spike "can we stream LLM tokens through SSE"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Skip intake and run immediately
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-spike --quick "websocket vs SSE latency"
|
||||||
|
```
|
||||||
|
|
||||||
|
`--quick` skips the decomposition conversation and treats the argument as a single spike question. Use this when the question is already specific enough to run without refinement.
|
||||||
|
|
||||||
|
### What each experiment produces
|
||||||
|
|
||||||
|
Each spike in `.planning/spikes/NNN-descriptive-name/` includes:
|
||||||
|
|
||||||
|
- Working code (not pseudocode)
|
||||||
|
- A **Given / When / Then** hypothesis written before any code
|
||||||
|
- An investigation trail documenting edge cases, pivots, and surprises
|
||||||
|
- A **VALIDATED**, **INVALIDATED**, or **PARTIAL** verdict with evidence
|
||||||
|
- A `README.md` with frontmatter, how-to-run instructions, and results
|
||||||
|
|
||||||
|
All spikes are indexed in `.planning/spikes/MANIFEST.md`.
|
||||||
|
|
||||||
|
### Package the findings
|
||||||
|
|
||||||
|
When you have signal, wrap the findings into a project-local skill so future sessions load them automatically:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-spike --wrap-up
|
||||||
|
```
|
||||||
|
|
||||||
|
This writes `.claude/skills/spike-findings-[project]/`. The skill is discovered automatically and loaded by subsequent `/gsd-sketch`, `/gsd-ui-phase`, and `/gsd-plan-phase` runs — you do not need to reference it explicitly.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Run a sketch
|
||||||
|
|
||||||
|
### Mood intake (default)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-sketch
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD opens a short conversation to explore feel, visual references, and the core user action before any code is written. It asks one question at a time and only starts building when you say go.
|
||||||
|
|
||||||
|
### Provide a design direction directly
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-sketch "dashboard layout"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Skip mood intake and run immediately
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-sketch --quick "sidebar navigation"
|
||||||
|
```
|
||||||
|
|
||||||
|
`--quick` skips the intake conversation entirely and uses the argument as the design direction.
|
||||||
|
|
||||||
|
### Non-Claude runtimes (Codex, Gemini CLI, etc.)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-sketch --text "onboarding flow"
|
||||||
|
```
|
||||||
|
|
||||||
|
`--text` replaces interactive prompts with plain-text numbered lists. Use this when your runtime does not support `AskUserQuestion`.
|
||||||
|
|
||||||
|
### What each sketch produces
|
||||||
|
|
||||||
|
Each sketch in `.planning/sketches/NNN-descriptive-name/` includes:
|
||||||
|
|
||||||
|
- `index.html` with 2–3 variants accessible via tab navigation — open directly in a browser, no build step
|
||||||
|
- Functional interactive elements (hover, click, transitions)
|
||||||
|
- Real-ish content using field names and data shapes from any prior spike findings
|
||||||
|
- Shared CSS variables from `.planning/sketches/themes/default.css`
|
||||||
|
- A `README.md` with the design question, variants, and what to look for
|
||||||
|
|
||||||
|
All sketches are indexed in `.planning/sketches/MANIFEST.md`.
|
||||||
|
|
||||||
|
### Package the winning design decisions
|
||||||
|
|
||||||
|
After picking a variant, capture the visual decisions into a project-local skill:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-sketch --wrap-up
|
||||||
|
```
|
||||||
|
|
||||||
|
This writes `.claude/skills/sketch-findings-[project]/`. The skill is picked up automatically by `/gsd-ui-phase` — pre-validated decisions (layout, colour palette, typography, spacing) are treated as locked and are not re-asked.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Combined flow: spike → sketch → phase
|
||||||
|
|
||||||
|
This is the recommended sequence when you are uncertain about both technical feasibility and visual direction:
|
||||||
|
|
||||||
|
```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
|
||||||
|
```
|
||||||
|
|
||||||
|
The spike findings inform the sketch (real data shapes, real interaction states, realistic constraints). Both wrap-ups persist decisions that the planner and UI researcher load automatically, so you do not need to re-explain choices during `/gsd-discuss-phase` or `/gsd-ui-phase`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How a spike or sketch feeds into a phase
|
||||||
|
|
||||||
|
Spike and sketch artifacts do not need to be manually referenced. GSD reads them automatically at two points:
|
||||||
|
|
||||||
|
1. **`/gsd-sketch`** — loads `.claude/skills/spike-findings-*/` before building mockups, so variants reflect proven constraints (streaming states, real field names, etc.)
|
||||||
|
2. **`/gsd-ui-phase N`** — loads `.claude/skills/sketch-findings-*/` before generating the UI design contract; pre-validated design decisions are treated as locked
|
||||||
|
|
||||||
|
The planner also reads spike findings when a `spike-findings-*` skill is present, so validated technical choices (which library, which protocol, which data format) flow directly into task plans without repeated explanation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Design a UI phase](design-a-ui-phase.md)
|
||||||
|
- [Plan a phase](plan-a-phase.md)
|
||||||
|
- [Commands](../COMMANDS.md)
|
||||||
|
- [Docs index](../README.md)
|
||||||
120
docs/how-to/update-gsd.md
Normal file
120
docs/how-to/update-gsd.md
Normal file
@@ -0,0 +1,120 @@
|
|||||||
|
# How to update GSD Core
|
||||||
|
|
||||||
|
Update an existing GSD Core install to the latest release, preview the changelog before committing, and recover any local customisations that the update would overwrite.
|
||||||
|
|
||||||
|
**What you need:** The same runtime GSD is installed for. The update command re-runs the installer under the hood, so it needs Node.js and npx available (same requirement as the original install).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The standard update path
|
||||||
|
|
||||||
|
From inside your AI runtime, run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-update
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD will:
|
||||||
|
|
||||||
|
1. Detect the installed version and install scope (global or local).
|
||||||
|
2. Check npm for the latest release of `@opengsd/gsd-core`.
|
||||||
|
3. Fetch the changelog and show you what changed between your installed version and the latest.
|
||||||
|
4. Ask for confirmation before touching anything.
|
||||||
|
5. Back up any user-added files found inside GSD-managed directories to `gsd-user-files-backup/`.
|
||||||
|
6. Run the installer (`npx @opengsd/gsd-core@latest --<runtime> --<scope>`).
|
||||||
|
7. Clear the update-check cache so the statusline indicator resets.
|
||||||
|
8. Report whether locally modified GSD files were backed up to `gsd-local-patches/`.
|
||||||
|
|
||||||
|
Restart your runtime after the update to pick up new commands and agents.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Flags
|
||||||
|
|
||||||
|
| Flag | What it does |
|
||||||
|
|------|--------------|
|
||||||
|
| `--sync` | After updating, sync skills from the GSD registry |
|
||||||
|
| `--reapply` | After updating, merge locally modified GSD files back in from `gsd-local-patches/` |
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-update --sync # Update and sync skills
|
||||||
|
/gsd-update --reapply # Update and reapply local patches
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Reviewing the changelog before updating
|
||||||
|
|
||||||
|
`/gsd-update` always shows the changelog diff between your installed version and the latest *before* it asks for confirmation. You do not need to visit GitHub separately. The output looks like:
|
||||||
|
|
||||||
|
```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]
|
||||||
|
```
|
||||||
|
|
||||||
|
If the changelog cannot be fetched (no network access, npm outage), the update still proceeds after confirmation — it does not block on changelog availability.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Recovering local customisations
|
||||||
|
|
||||||
|
### Files you added inside GSD-managed directories
|
||||||
|
|
||||||
|
If you placed custom files inside directories that GSD owns (for example, custom agents prefixed with `gsd-` or extra files in `commands/gsd/`), the installer will detect them and copy them to `gsd-user-files-backup/` before wiping those directories. After the update, restore them manually from that backup location.
|
||||||
|
|
||||||
|
Files you placed outside GSD-managed directories — custom agents not prefixed with `gsd-`, custom commands outside `commands/gsd/`, your `CLAUDE.md` files, and custom hooks — are never touched by the installer.
|
||||||
|
|
||||||
|
### GSD files you modified directly
|
||||||
|
|
||||||
|
If you edited a file that GSD installed (for example, tweaking an agent's system prompt), the installer detects the modification via a hash comparison against its manifest, backs the file up to `gsd-local-patches/`, and then replaces it with the new version. After the update:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-update --reapply
|
||||||
|
```
|
||||||
|
|
||||||
|
This merges your modifications from `gsd-local-patches/` back into the newly installed files.
|
||||||
|
|
||||||
|
If you skipped `--reapply` after a previous update and want to apply patches now:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-update --reapply
|
||||||
|
```
|
||||||
|
|
||||||
|
It is safe to run `--reapply` on its own without triggering a new download — if you are already on the latest version, GSD skips the install step and goes straight to reapplying patches.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## When npm is unavailable
|
||||||
|
|
||||||
|
If `npx @opengsd/gsd-core@latest` fails due to an npm outage, network restrictions, or because you are working from the source repository, use the manual update procedure in [docs/manual-update.md](../manual-update.md). That document covers pulling the latest commit, building the hooks dist, and running `node bin/install.js` directly.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## If you are already on the latest version
|
||||||
|
|
||||||
|
`/gsd-update` exits early with a confirmation message — no download, no install, no restart needed.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Installer migrations
|
||||||
|
|
||||||
|
Each GSD release may include installer migrations that rename, move, or retire managed files. The migration layer runs automatically before the new package payload is written. Migrations that would affect files you have modified prompt for confirmation rather than acting silently. For the full design and runtime-configuration contract registry, see [docs/installer-migrations.md](../installer-migrations.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Install on your runtime](install-on-your-runtime.md)
|
||||||
|
- [Commands reference](../COMMANDS.md)
|
||||||
|
- [Manual update](../manual-update.md)
|
||||||
|
- [Installer migrations](../installer-migrations.md)
|
||||||
|
- [Docs index](../README.md)
|
||||||
124
docs/how-to/verify-and-ship.md
Normal file
124
docs/how-to/verify-and-ship.md
Normal file
@@ -0,0 +1,124 @@
|
|||||||
|
# How to verify and ship a phase
|
||||||
|
|
||||||
|
**Goal:** Walk executed work through user acceptance testing, diagnose and fix any failures, then open a pull request with an auto-generated body.
|
||||||
|
|
||||||
|
**Prerequisites:** The phase has been executed and has `SUMMARY.md` files. If execution is not yet done, see [Execute a phase](execute-a-phase.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Run user acceptance testing
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-verify-work 1
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD reads the phase's `SUMMARY.md` files, extracts user-observable deliverables, and walks you through them one at a time. For each checkpoint it presents what *should* happen and asks whether reality matches.
|
||||||
|
|
||||||
|
- `yes` / `y` / empty → pass, move to next test
|
||||||
|
- Anything else → recorded as an issue, severity inferred from your description
|
||||||
|
|
||||||
|
You never need to categorise severity — GSD infers it from your words ("crashes" → blocker, "doesn't work" → major, "looks off" → cosmetic).
|
||||||
|
|
||||||
|
Progress is written to `.planning/phases/01-<name>/01-UAT.md` and survives a `/clear`. If a session is interrupted, re-run `/gsd-verify-work 1` and GSD offers to resume from the last checkpoint.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## When failures are found: auto-diagnose and fix planning
|
||||||
|
|
||||||
|
If any tests report issues, GSD proceeds automatically:
|
||||||
|
|
||||||
|
1. **Diagnoses root causes** — spawns parallel debug agents, one per issue, and updates `UAT.md` with root causes.
|
||||||
|
2. **Plans gap closure** — spawns a `gsd-planner` in gap-closure mode, which reads `UAT.md` (with diagnoses) and writes new `PLAN.md` files.
|
||||||
|
3. **Verifies the fix plans** — spawns a `gsd-plan-checker` to ensure the plans are executable. If issues are found, the planner and checker iterate up to three times.
|
||||||
|
4. **Presents next step** — when plans pass the checker:
|
||||||
|
|
||||||
|
```
|
||||||
|
Plans verified and ready for execution.
|
||||||
|
|
||||||
|
`/clear` then `/gsd-execute-phase 1 --gaps-only`
|
||||||
|
```
|
||||||
|
|
||||||
|
Run the suggested command to apply fixes, then re-run `/gsd-verify-work 1` to confirm everything passes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## When all tests pass: ship the phase
|
||||||
|
|
||||||
|
Once all UAT tests pass (or if this is your first run and no issues are found), the phase is marked complete in `ROADMAP.md` and `STATE.md` automatically.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-ship 1
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD runs preflight checks (verification status, clean working tree, branch, remote, `gh` CLI authentication), pushes the branch, and creates a PR:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-ship 1 # Ready-for-review PR
|
||||||
|
/gsd-ship 1 --draft # Draft PR — useful when more phases will follow
|
||||||
|
```
|
||||||
|
|
||||||
|
The PR body is assembled from planning artefacts automatically:
|
||||||
|
|
||||||
|
- Phase goal from `ROADMAP.md`
|
||||||
|
- Per-plan summaries from `SUMMARY.md` files and their key files
|
||||||
|
- Requirements addressed (REQ-IDs)
|
||||||
|
- Verification status from `VERIFICATION.md`
|
||||||
|
- Key decisions from `STATE.md`
|
||||||
|
|
||||||
|
No manual body writing required.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Optional: code review before or after shipping
|
||||||
|
|
||||||
|
`/gsd-ship` does not run a code review automatically, but you can slot one in at any point:
|
||||||
|
|
||||||
|
**Before verification** (catches issues before UAT):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-code-review 1 # Standard review
|
||||||
|
/gsd-code-review 1 --fix # Review then auto-fix Critical + Warning findings
|
||||||
|
```
|
||||||
|
|
||||||
|
**After the PR is open** (to gate on quality before merge):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-code-review 1 --depth=deep # Cross-file analysis including import graphs
|
||||||
|
```
|
||||||
|
|
||||||
|
See [Set up cross-AI review](set-up-cross-ai-review.md) to configure Gemini, Codex, or other reviewers for plan review earlier in the cycle.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Optional: create a clean PR branch
|
||||||
|
|
||||||
|
If your branch contains `.planning/` commits that you do not want reviewers to see:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-pr-branch # Filter against main
|
||||||
|
/gsd-pr-branch develop # Filter against develop
|
||||||
|
```
|
||||||
|
|
||||||
|
`/gsd-pr-branch` creates a new branch with only code changes — planning artefact commits are excluded. Run this before `/gsd-ship` if your team's review policy excludes planning noise.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Closing a milestone
|
||||||
|
|
||||||
|
If this was the last phase in the milestone, run the milestone audit and archive it:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-audit-milestone # Verify all requirements shipped
|
||||||
|
/gsd-complete-milestone # Archive, create git tag
|
||||||
|
```
|
||||||
|
|
||||||
|
`/gsd-complete-milestone` is the natural next step after the PR merges. See the [The phase loop](../explanation/the-phase-loop.md) for how verification and shipping fit into the full project lifecycle.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Execute a phase](execute-a-phase.md)
|
||||||
|
- [Set up cross-AI review](set-up-cross-ai-review.md)
|
||||||
|
- [The phase loop](../explanation/the-phase-loop.md)
|
||||||
|
- [Commands](../COMMANDS.md)
|
||||||
157
docs/how-to/work-in-parallel-with-workstreams.md
Normal file
157
docs/how-to/work-in-parallel-with-workstreams.md
Normal file
@@ -0,0 +1,157 @@
|
|||||||
|
# How to work on multiple areas in parallel with workstreams
|
||||||
|
|
||||||
|
**Goal:** Run concurrent work on different milestone areas — backend API, frontend dashboard, infrastructure, or any other concern — without planning state from one area bleeding into another.
|
||||||
|
|
||||||
|
**Prerequisites:** An active GSD Core project (`.planning/ROADMAP.md` exists). If not, run `/gsd-new-project` first.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What workstreams are
|
||||||
|
|
||||||
|
A workstream is an isolated planning context within a single codebase. Each workstream gets its own `.planning/workstreams/<name>/` subtree containing independent `STATE.md`, `ROADMAP.md`, `REQUIREMENTS.md`, and `phases/` directories. The codebase itself — source code, git history, and branches — is shared across all workstreams.
|
||||||
|
|
||||||
|
```
|
||||||
|
.planning/
|
||||||
|
├── PROJECT.md ← shared
|
||||||
|
├── config.json ← shared
|
||||||
|
├── codebase/ ← shared
|
||||||
|
└── workstreams/
|
||||||
|
├── backend-api/
|
||||||
|
│ ├── STATE.md
|
||||||
|
│ ├── ROADMAP.md
|
||||||
|
│ ├── REQUIREMENTS.md
|
||||||
|
│ └── phases/
|
||||||
|
└── frontend-dash/
|
||||||
|
├── STATE.md
|
||||||
|
├── ROADMAP.md
|
||||||
|
├── REQUIREMENTS.md
|
||||||
|
└── phases/
|
||||||
|
```
|
||||||
|
|
||||||
|
When a workstream is active, every GSD command — `/gsd-progress`, `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase` — reads from and writes to that workstream's directory. Switching workstreams redirects all of those commands to a different subtree without touching the source tree.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Create a workstream
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workstreams create backend-api
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD creates the workstream directory under `.planning/workstreams/backend-api/` and seeds it with a skeleton `STATE.md` and `ROADMAP.md`. The workstream is not automatically activated — you switch to it explicitly.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## List workstreams
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workstreams list
|
||||||
|
```
|
||||||
|
|
||||||
|
Shows all workstreams and which one is currently active in your session.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Switch to a workstream
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workstreams switch backend-api
|
||||||
|
```
|
||||||
|
|
||||||
|
From this point forward, all GSD workflow commands operate in the `backend-api` context. The switch is session-scoped: when multiple Claude Code terminals are open on the same repo, each session can hold a different active workstream without interfering with the others.
|
||||||
|
|
||||||
|
Once switched, drive the normal phase workflow:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-discuss-phase 1
|
||||||
|
/gsd-plan-phase 1
|
||||||
|
/gsd-execute-phase 1
|
||||||
|
/gsd-verify-work 1
|
||||||
|
```
|
||||||
|
|
||||||
|
To work on another area, switch workstreams in a second terminal:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workstreams switch frontend-dash
|
||||||
|
/gsd-discuss-phase 1
|
||||||
|
/gsd-plan-phase 1
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Check progress across all workstreams
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workstreams progress
|
||||||
|
```
|
||||||
|
|
||||||
|
Prints a cross-workstream summary — phase status, current position, and outstanding work for every workstream — without requiring you to switch between them.
|
||||||
|
|
||||||
|
For detailed status on a single workstream:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workstreams status backend-api
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resume work in a workstream
|
||||||
|
|
||||||
|
After a context reset or a new session, restore your position:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workstreams resume backend-api
|
||||||
|
```
|
||||||
|
|
||||||
|
This activates the workstream and restores your last known position within it, equivalent to switching and then running `/gsd-resume-work`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Archive a completed workstream
|
||||||
|
|
||||||
|
When a workstream's milestone work is done:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-workstreams complete backend-api
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD marks the workstream as archived and moves it out of the active listing. The planning artifacts are preserved under `.planning/workstreams/backend-api/` for audit purposes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scope a single command to a workstream without switching
|
||||||
|
|
||||||
|
If you need to run one command against a specific workstream without changing your session's active context, use the `--ws` flag:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-progress --ws frontend-dash
|
||||||
|
/gsd-plan-phase 2 --ws backend-api
|
||||||
|
```
|
||||||
|
|
||||||
|
`--ws` takes highest priority in the resolution order and does not alter the session-scoped pointer.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## When to use workstreams instead of workspaces
|
||||||
|
|
||||||
|
Choose workstreams when:
|
||||||
|
|
||||||
|
- All the work lives in the **same repository** and shares the same git history
|
||||||
|
- You want to plan or discuss different concern areas (API, UI, infra) **concurrently** without one workstream's `STATE.md` overwriting another's
|
||||||
|
- You do not need a separate branch per workstream at creation time (though you can branch as normal within each workstream's execution)
|
||||||
|
- The overhead of creating full git worktrees is not justified by the isolation you need
|
||||||
|
|
||||||
|
Choose [workspaces](isolate-work-with-workspaces.md) instead when:
|
||||||
|
|
||||||
|
- You are working across **multiple repositories** (e.g., `hr-ui` and `ZeymoAPI`)
|
||||||
|
- You need the isolation of a **separate git worktree** or clone per feature — fully independent branches, lock files, and build artefacts
|
||||||
|
- You want to run `/gsd-new-project` independently in each workspace with a wholly separate `.planning/` root, not a subdirectory of the main repo's `.planning/`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Isolate work with workspaces](isolate-work-with-workspaces.md)
|
||||||
|
- [The phase loop](../explanation/the-phase-loop.md)
|
||||||
|
- [Commands](../COMMANDS.md)
|
||||||
|
- [docs index](../README.md)
|
||||||
@@ -173,11 +173,10 @@ scope for this guide.
|
|||||||
|
|
||||||
## Related
|
## Related
|
||||||
|
|
||||||
- [docs/USER-GUIDE.md](USER-GUIDE.md) — task-oriented walkthroughs of
|
- [The phase loop](explanation/the-phase-loop.md) — how discuss → plan → execute → verify → ship fits together as a repeating cycle.
|
||||||
individual commands referenced above.
|
- [Workspaces how-to](how-to/work-in-parallel-with-workstreams.md) — step-by-step guide to creating and managing parallel worktrees.
|
||||||
- [docs/COMMANDS.md](COMMANDS.md) — full reference for `/gsd-*`
|
- [docs index](README.md) — full table of contents for GSD Core documentation.
|
||||||
commands.
|
- [docs/USER-GUIDE.md](./USER-GUIDE.md) — task-oriented walkthroughs of individual commands referenced above.
|
||||||
- [docs/FEATURES.md](FEATURES.md) — feature-level capability matrix
|
- [docs/COMMANDS.md](COMMANDS.md) — full reference for `/gsd-*` commands.
|
||||||
(workspaces, manager, autonomous, verify, review, ship).
|
- [docs/FEATURES.md](FEATURES.md) — feature-level capability matrix (workspaces, manager, autonomous, verify, review, ship).
|
||||||
- [docs/ARCHITECTURE.md](ARCHITECTURE.md) — phase-artifact lifecycle
|
- [docs/ARCHITECTURE.md](ARCHITECTURE.md) — phase-artifact lifecycle and `STATE.md` mechanics.
|
||||||
and `STATE.md` mechanics.
|
|
||||||
|
|||||||
@@ -1,30 +1,30 @@
|
|||||||
# GSD アーキテクチャ
|
# GSD Core アーキテクチャ
|
||||||
|
|
||||||
> コントリビューターおよび上級ユーザー向けのシステムアーキテクチャ文書です。ユーザー向けドキュメントは[機能リファレンス](FEATURES.md)または[ユーザーガイド](USER-GUIDE.md)をご覧ください。
|
> コントリビューターおよび上級ユーザー向けのシステムアーキテクチャ文書です。ユーザー向けドキュメントは [機能リファレンス](FEATURES.md) または [ユーザーガイド](USER-GUIDE.md) をご覧ください。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 目次
|
## 目次
|
||||||
|
|
||||||
- [システム概要](#システム概要)
|
- [システム概要](#system-overview)
|
||||||
- [設計原則](#設計原則)
|
- [設計原則](#design-principles)
|
||||||
- [コンポーネントアーキテクチャ](#コンポーネントアーキテクチャ)
|
- [コンポーネントアーキテクチャ](#component-architecture)
|
||||||
- [エージェントモデル](#エージェントモデル)
|
- [エージェントモデル](#agent-model)
|
||||||
- [データフロー](#データフロー)
|
- [データフロー](#data-flow)
|
||||||
- [ファイルシステムレイアウト](#ファイルシステムレイアウト)
|
- [ファイルシステムレイアウト](#file-system-layout)
|
||||||
- [インストーラーアーキテクチャ](#インストーラーアーキテクチャ)
|
- [インストーラーアーキテクチャ](#installer-architecture)
|
||||||
- [フックシステム](#フックシステム)
|
- [フックシステム](#hook-system)
|
||||||
- [CLIツールレイヤー](#cliツールレイヤー)
|
- [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が必要とするすべてを提供する構造化アーティファクト
|
1. **コンテキストエンジニアリング** — タスクごとに AI が必要とするすべてを提供する構造化アーティファクト（[コンテキストエンジニアリング](explanation/context-engineering.md) 参照）
|
||||||
2. **マルチエージェントオーケストレーション** — 専門エージェントをフレッシュなコンテキストウィンドウで起動する軽量オーケストレーター
|
2. **マルチエージェントオーケストレーション** — フレッシュなコンテキストウィンドウで専門化されたエージェントを生成する薄いオーケストレーター（[マルチエージェントオーケストレーション](explanation/multi-agent-orchestration.md) 参照）
|
||||||
3. **仕様駆動開発** — 要件 → 調査 → 計画 → 実行 → 検証のパイプライン
|
3. **仕様駆動開発** — 要件 → 調査 → 計画 → 実行 → 検証のパイプライン
|
||||||
4. **状態管理** — セッションやコンテキストリセットをまたいだ永続的なプロジェクトメモリ
|
4. **状態管理** — セッションやコンテキストリセットをまたいだ永続的なプロジェクトメモリ
|
||||||
|
|
||||||
@@ -106,47 +106,93 @@ GSDは、ユーザーとAIコーディングエージェント（Claude Code、G
|
|||||||
|
|
||||||
### コマンド（`commands/gsd/*.md`）
|
### コマンド（`commands/gsd/*.md`）
|
||||||
|
|
||||||
ユーザー向けのエントリーポイントです。各ファイルにはYAMLフロントマター（name、description、allowed-tools）とワークフローをブートストラップするプロンプト本文が含まれています。コマンドは以下の形式でインストールされます：
|
ユーザー向けのエントリーポイントです。各ファイルには YAML フロントマター（name、description、allowed-tools）とワークフローをブートストラップするプロンプト本文が含まれています。コマンドは以下の形式でインストールされます：
|
||||||
- **Claude Code:** カスタムスラッシュコマンド（`/gsd-command-name`）
|
|
||||||
- **OpenCode / Kilo:** スラッシュコマンド（`/gsd-command-name`）
|
- **Claude Code:** カスタムスラッシュコマンド（ハイフン形式、`/gsd-command-name`）
|
||||||
|
- **OpenCode / Kilo:** スラッシュコマンド（ハイフン形式、`/gsd-command-name`）
|
||||||
- **Codex:** スキル（`$gsd-command-name`）
|
- **Codex:** スキル（`$gsd-command-name`）
|
||||||
- **Copilot:** スラッシュコマンド（`/gsd-command-name`）
|
- **Copilot:** スラッシュコマンド（ハイフン形式、`/gsd-command-name`）
|
||||||
|
- **Gemini CLI:** `gsd:` 名前空間下のスラッシュコマンド（コロン形式、`/gsd:command-name`）——Gemini はすべてのカスタムコマンドをプラグイン ID の下で名前空間化するため、インストールパスがすべての本文テキスト参照をコロン形式に書き換える
|
||||||
- **Antigravity:** スキル
|
- **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`）
|
### ワークフロー（`get-shit-done/workflows/*.md`）
|
||||||
|
|
||||||
コマンドが参照するオーケストレーションロジックです。以下を含むステップバイステップのプロセスが記述されています：
|
コマンドが参照するオーケストレーションロジックです。以下を含むステップバイステップのプロセスが記述されています：
|
||||||
|
|
||||||
- `gsd-tools.cjs init` によるコンテキスト読み込み
|
- `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`）
|
### エージェント（`agents/*.md`）
|
||||||
|
|
||||||
フロントマターで以下を指定する専門エージェント定義：
|
フロントマターで以下を指定する専門化されたエージェント定義：
|
||||||
|
|
||||||
- `name` — エージェント識別子
|
- `name` — エージェント識別子
|
||||||
- `description` — 役割と目的
|
- `description` — 役割と目的
|
||||||
- `tools` — 許可されたツールアクセス（Read、Write、Edit、Bash、Grep、Glob、WebSearchなど）
|
- `tools` — 許可されたツールアクセス（Read、Write、Edit、Bash、Grep、Glob、WebSearch など）
|
||||||
- `color` — 視覚的な区別のためのターミナル出力色
|
- `color` — 視覚的な区別のためのターミナル出力色
|
||||||
|
|
||||||
**エージェント総数:** 16
|
**エージェント総数:** 33
|
||||||
|
|
||||||
### リファレンス（`get-shit-done/references/*.md`）
|
### リファレンス（`get-shit-done/references/*.md`）
|
||||||
|
|
||||||
ワークフローとエージェントが `@-reference` で参照する共有知識ドキュメント：
|
ワークフローとエージェントが `@-reference` で参照する共有知識ドキュメント（信頼できる数と完全なロスターについては [`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped) を参照）：
|
||||||
|
|
||||||
|
**コアリファレンス：**
|
||||||
|
|
||||||
- `checkpoints.md` — チェックポイントタイプの定義とインタラクションパターン
|
- `checkpoints.md` — チェックポイントタイプの定義とインタラクションパターン
|
||||||
|
- `gates.md` — プランチェッカーと検証者に組み込まれた 4 つの正規ゲートタイプ（Confirm、Quality、Safety、Transition）
|
||||||
- `model-profiles.md` — エージェントごとのモデルティア割り当て
|
- `model-profiles.md` — エージェントごとのモデルティア割り当て
|
||||||
|
- `model-profile-resolution.md` — モデル解決アルゴリズムのドキュメント
|
||||||
- `verification-patterns.md` — 各種アーティファクトの検証方法
|
- `verification-patterns.md` — 各種アーティファクトの検証方法
|
||||||
- `planning-config.md` — 設定スキーマの全体像と動作
|
- `verification-overrides.md` — アーティファクトごとの検証オーバーライドルール
|
||||||
- `git-integration.md` — gitコミット、ブランチ、履歴のパターン
|
- `planning-config.md` — 完全な設定スキーマと動作
|
||||||
|
- `git-integration.md` — git コミット、ブランチ、履歴のパターン
|
||||||
|
- `git-planning-commit.md` — planning ディレクトリのコミット規約
|
||||||
- `questioning.md` — プロジェクト初期化のためのドリーム抽出フィロソフィー
|
- `questioning.md` — プロジェクト初期化のためのドリーム抽出フィロソフィー
|
||||||
- `tdd.md` — テスト駆動開発の統合パターン
|
- `tdd.md` — テスト駆動開発の統合パターン
|
||||||
- `ui-brand.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/`）
|
### テンプレート（`get-shit-done/templates/`）
|
||||||
|
|
||||||
@@ -172,26 +218,36 @@ GSDは、ユーザーとAIコーディングエージェント（Claude Code、G
|
|||||||
| `gsd-prompt-guard.js` | `PreToolUse` | `.planning/` への書き込みにプロンプトインジェクションパターンがないかスキャン（アドバイザリー） |
|
| `gsd-prompt-guard.js` | `PreToolUse` | `.planning/` への書き込みにプロンプトインジェクションパターンがないかスキャン（アドバイザリー） |
|
||||||
| `gsd-workflow-guard.js` | `PreToolUse` | GSDワークフローコンテキスト外でのファイル編集を検出（アドバイザリー、`hooks.workflow_guard` によるオプトイン） |
|
| `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 の解析、更新、進行、メトリクス |
|
| `state.cjs` | STATE.md の解析、更新、進行、メトリクス |
|
||||||
| `phase.cjs` | フェーズディレクトリ操作、小数番号付け、プランインデックス |
|
| `phase.cjs` | フェーズディレクトリ操作、小数番号付け、プランインデックス |
|
||||||
| `roadmap.cjs` | ROADMAP.md の解析、フェーズ抽出、プラン進捗 |
|
| `roadmap.cjs` | ROADMAP.md の解析、フェーズ抽出、プラン進捗 |
|
||||||
| `config.cjs` | config.json の読み書き、セクション初期化 |
|
| `config.cjs` | config.json の読み書き、セクション初期化 |
|
||||||
| `verify.cjs` | プラン構造、フェーズ完了度、リファレンス、コミット検証 |
|
| `verify.cjs` | プラン構造、フェーズ完了度、リファレンス、コミット検証 |
|
||||||
| `template.cjs` | テンプレート選択と変数置換による穴埋め |
|
| `template.cjs` | テンプレート選択と変数置換による穴埋め |
|
||||||
| `frontmatter.cjs` | YAMLフロントマターのCRUD操作 |
|
| `frontmatter.cjs` | YAML フロントマターの CRUD 操作 |
|
||||||
| `init.cjs` | ワークフロータイプごとの複合コンテキスト読み込み |
|
| `init.cjs` | ワークフロータイプごとの複合コンテキスト読み込み |
|
||||||
| `milestone.cjs` | マイルストーンのアーカイブ、要件マーキング |
|
| `milestone.cjs` | マイルストーンのアーカイブ、要件マーキング |
|
||||||
| `commands.cjs` | その他コマンド（slug、タイムスタンプ、todos、スキャフォールディング、統計） |
|
| `commands.cjs` | その他コマンド（slug、タイムスタンプ、todos、スキャフォールディング、統計） |
|
||||||
| `model-profiles.cjs` | モデルプロファイル解決テーブル |
|
| `model-profiles.cjs` | モデルプロファイル解決テーブル |
|
||||||
| `security.cjs` | パストラバーサル防止、プロンプトインジェクション検出、安全なJSON解析、シェル引数バリデーション |
|
| `security.cjs` | パストラバーサル防止、プロンプトインジェクション検出、安全な JSON 解析、シェル引数バリデーション |
|
||||||
| `uat.cjs` | UATファイル解析、検証デット追跡、audit-uatサポート |
|
| `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
|
└── Update state: gsd-tools.cjs state update/patch/advance-plan
|
||||||
```
|
```
|
||||||
|
|
||||||
### エージェント起動カテゴリ
|
### 主要エージェント生成カテゴリ
|
||||||
|
|
||||||
| カテゴリ | エージェント | 並列実行 |
|
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-project-researcher、gsd-phase-researcher、gsd-ui-researcher、gsd-advisor-researcher | 4 並列（stack、features、architecture、pitfalls）；advisor は discuss-phase 中に起動 |
|
||||||
| **シンセサイザー** | gsd-research-synthesizer | 逐次（リサーチャー完了後） |
|
| **シンセサイザー** | gsd-research-synthesizer | 逐次（リサーチャー完了後） |
|
||||||
| **プランナー** | gsd-planner, gsd-roadmapper | 逐次 |
|
| **プランナー** | gsd-planner、gsd-roadmapper | 逐次 |
|
||||||
| **チェッカー** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | 逐次（検証ループ、最大3回反復） |
|
| **チェッカー** | gsd-plan-checker、gsd-integration-checker、gsd-ui-checker、gsd-nyquist-auditor | 逐次（検証ループ、最大 3 回反復） |
|
||||||
| **エグゼキューター** | gsd-executor | ウェーブ内は並列、ウェーブ間は逐次 |
|
| **エグゼキューター** | gsd-executor | ウェーブ内は並列、ウェーブ間は逐次 |
|
||||||
| **ベリファイアー** | gsd-verifier | 逐次（全エグゼキューター完了後） |
|
| **ベリファイアー** | gsd-verifier | 逐次（全エグゼキューター完了後） |
|
||||||
| **マッパー** | gsd-codebase-mapper | 4並列（tech、arch、quality、concerns） |
|
| **マッパー** | gsd-codebase-mapper | 4 並列（tech、arch、quality、concerns） |
|
||||||
| **デバッガー** | gsd-debugger | 逐次（インタラクティブ） |
|
| **デバッガー** | 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）
|
- プロジェクトコンテキスト（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
|
plan-phase
|
||||||
|
├── Research gate (blocks if RESEARCH.md has unresolved open questions)
|
||||||
├── Phase Researcher → RESEARCH.md
|
├── Phase Researcher → RESEARCH.md
|
||||||
├── Planner → PLAN.md files
|
│ └── Package Legitimacy Gate: slopcheck on every package; [SLOP] removed,
|
||||||
└── Plan Checker → Verify loop (max 3x)
|
│ [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)
|
├── Wave analysis (dependency grouping)
|
||||||
├── Executor per plan → code + atomic commits
|
├── Executor per plan → code + atomic commits
|
||||||
├── SUMMARY.md per plan
|
├── SUMMARY.md per plan
|
||||||
└── Verifier → VERIFICATION.md
|
└── Verifier → VERIFICATION.md
|
||||||
|
└── Decision coverage gate (CONTEXT.md decisions → shipped artifacts, NON-BLOCKING — #2492)
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
verify-work → UAT.md (user acceptance testing)
|
verify-work → UAT.md (user acceptance testing)
|
||||||
@@ -344,29 +426,37 @@ UI-SPEC.md (per phase) ───────────────────
|
|||||||
|
|
||||||
```
|
```
|
||||||
~/.claude/ # Claude Code (global install)
|
~/.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/
|
├── get-shit-done/
|
||||||
│ ├── bin/gsd-tools.cjs # CLI utility
|
│ ├── bin/gsd-tools.cjs # CLI utility
|
||||||
│ ├── bin/lib/*.cjs # 15 domain modules
|
│ ├── bin/lib/*.cjs # Domain modules (authoritative roster: docs/INVENTORY.md)
|
||||||
│ ├── workflows/*.md # 42 workflow definitions
|
│ ├── workflows/*.md # Workflow definitions (authoritative roster: docs/INVENTORY.md)
|
||||||
│ ├── references/*.md # 13 shared reference docs
|
│ ├── references/*.md # Shared reference docs (authoritative roster: docs/INVENTORY.md)
|
||||||
│ └── templates/ # Planning artifact templates
|
│ └── templates/ # Planning artifact templates
|
||||||
├── agents/*.md # 15 agent definitions
|
├── agents/*.md # Agent definitions (authoritative roster: docs/INVENTORY.md)
|
||||||
├── hooks/
|
├── hooks/*.js # Node.js hooks (statusline, guards, monitors, update check)
|
||||||
│ ├── gsd-statusline.js # Statusline hook
|
├── hooks/*.sh # Shell hooks (session state, commit validation, phase boundary)
|
||||||
│ ├── gsd-context-monitor.js # Context warning hook
|
|
||||||
│ └── gsd-check-update.js # Update check hook
|
|
||||||
├── settings.json # Hook registrations
|
├── settings.json # Hook registrations
|
||||||
└── VERSION # Installed version number
|
└── VERSION # Installed version number
|
||||||
```
|
```
|
||||||
|
|
||||||
他のランタイムでの同等パス：
|
他のランタイムでの同等パス：
|
||||||
- **OpenCode:** `~/.config/opencode/` または `~/.opencode/`
|
|
||||||
- **Kilo:** `~/.config/kilo/` または `~/.kilo/`
|
- **OpenCode:** `~/.config/opencode/` global または `./.opencode/` local
|
||||||
- **Gemini CLI:** `~/.gemini/`
|
- **Kilo:** `~/.config/kilo/` global または `./.kilo/` local
|
||||||
- **Codex:** `~/.codex/`（コマンドの代わりにスキルを使用）
|
- **Gemini CLI:** `~/.gemini/` global または `./.gemini/` local
|
||||||
- **Copilot:** `~/.github/`
|
- **Codex:** `~/.codex/` global または `./.codex/` local
|
||||||
- **Antigravity:** `~/.gemini/antigravity/`（グローバル）または `./.agent/`（ローカル）
|
- **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/`）
|
### プロジェクトファイル（`.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`）
|
2. **インストール先の選択** — グローバル（`--global`）またはローカル（`--local`）
|
||||||
3. **ファイルデプロイ** — コマンド、ワークフロー、リファレンス、テンプレート、エージェント、フックをコピー
|
3. **ファイルデプロイ** — コマンド、スキル、ワークフロー、リファレンス、テンプレート、エージェント、フックをコピー
|
||||||
4. **ランタイム適応** — ランタイムごとにファイル内容を変換：
|
4. **ランタイム適応** — ランタイムごとにファイル内容を変換：
|
||||||
- Claude Code: そのまま使用
|
- Claude Code: そのまま使用
|
||||||
- OpenCode: コマンド/エージェントをOpenCode互換のフラットコマンド + サブエージェント形式に変換
|
- OpenCode: コマンド/エージェントを OpenCode 互換のフラットコマンド + サブエージェント形式に変換
|
||||||
- Kilo: OpenCode変換パイプラインをKiloの設定パスで再利用
|
- Kilo: OpenCode 変換パイプラインを Kilo の設定パスで再利用
|
||||||
- Codex: コマンドからTOML設定 + スキルを生成
|
- Codex: コマンドから TOML 設定 + スキルを生成
|
||||||
- Copilot: ツール名をマッピング（Read→read、Bash→executeなど）
|
- Copilot: ツール名をマッピング（Read→read、Bash→execute など）
|
||||||
- Gemini: フックイベント名を調整（`PostToolUse` の代わりに `AfterTool`）
|
- 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/` パスをランタイム固有のパスに置換
|
5. **パス正規化** — `~/.claude/` パスをランタイム固有のパスに置換
|
||||||
6. **設定統合** — ランタイムの `settings.json` にフックを登録
|
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` を書き込み
|
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対策、パスセパレーターの正規化
|
- **Windows:** 子プロセスでの `windowsHide`、保護ディレクトリへの EPERM/EACCES 対策、パスセパレーターの正規化
|
||||||
- **WSL:** WindowsのNode.jsがWSL上で実行されていることを検出し、パスの不一致について警告
|
- **WSL:** Windows の Node.js が WSL 上で実行されていることを検出し、パスの不一致について警告
|
||||||
- **Docker/CI:** カスタム設定ディレクトリの場所に `CLAUDE_CONFIG_DIR` 環境変数をサポート
|
- **Docker/CI:** カスタム設定ディレクトリの場所に `CLAUDE_CONFIG_DIR` 環境変数をサポート
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -474,32 +574,48 @@ Runtime Engine (Claude Code / Gemini CLI)
|
|||||||
### コンテキストモニターの閾値
|
### コンテキストモニターの閾値
|
||||||
|
|
||||||
| コンテキスト残量 | レベル | エージェントの動作 |
|
| コンテキスト残量 | レベル | エージェントの動作 |
|
||||||
|-------------------|-------|----------------|
|
| ----------------- | -------- | --------------------------------------- |
|
||||||
| > 35% | Normal | 警告なし |
|
| > 35% | Normal | 警告なし |
|
||||||
| ≤ 35% | WARNING | 「新しい複雑な作業の開始を避けてください」 |
|
| ≤ 35% | WARNING | 「新しい複雑な作業の開始を避けてください」 |
|
||||||
| ≤ 25% | CRITICAL | 「コンテキストがほぼ枯渇、ユーザーに通知してください」 |
|
| ≤ 25% | CRITICAL | 「コンテキストがほぼ枯渇、ユーザーに通知してください」 |
|
||||||
|
|
||||||
デバウンス：繰り返し警告の間隔は5回のツール使用。重大度のエスカレーション（WARNING→CRITICAL）はデバウンスをバイパスします。
|
デバウンス：繰り返し警告の間隔は 5 回のツール使用。重大度のエスカレーション（WARNING→CRITICAL）はデバウンスをバイパスします。
|
||||||
|
|
||||||
### 安全性の特性
|
### 安全性の特性
|
||||||
|
|
||||||
- すべてのフックはtry/catchでラップされ、エラー時はサイレントに終了
|
- すべてのフックは try/catch でラップされ、エラー時はサイレントに終了
|
||||||
- stdin タイムアウトガード（3秒）でパイプの問題によるハングを防止
|
- stdin タイムアウトガード（3 秒）でパイプの問題によるハングを防止
|
||||||
- 古いメトリクス（60秒超）は無視される
|
- 古いメトリクス（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）
|
### セキュリティフック（v1.27）
|
||||||
|
|
||||||
**Prompt Guard**（`gsd-prompt-guard.js`）：
|
**Prompt Guard**（`gsd-prompt-guard.js`）：
|
||||||
- `.planning/` ファイルへのWrite/Edit時にトリガー
|
|
||||||
- プロンプトインジェクションパターン（ロールオーバーライド、指示バイパス、systemタグインジェクション）をスキャン
|
- `.planning/` ファイルへの Write/Edit 時にトリガー
|
||||||
|
- プロンプトインジェクションパターン（ロールオーバーライド、指示バイパス、system タグインジェクション）をスキャン
|
||||||
- アドバイザリーのみ — 検出をログに記録するが、ブロックはしない
|
- アドバイザリーのみ — 検出をログに記録するが、ブロックはしない
|
||||||
- フックの独立性のため、パターンはインライン化（`security.cjs` のサブセット）
|
- フックの独立性のため、パターンはインライン化（`security.cjs` のサブセット）
|
||||||
|
|
||||||
**Workflow Guard**（`gsd-workflow-guard.js`）：
|
**Workflow Guard**（`gsd-workflow-guard.js`）：
|
||||||
- `.planning/` 以外のファイルへのWrite/Edit時にトリガー
|
|
||||||
- GSDワークフローコンテキスト外での編集を検出（アクティブな `/gsd-` コマンドやTaskサブエージェントがない場合）
|
- `.planning/` 以外のファイルへの Write/Edit 時にトリガー
|
||||||
|
- GSD ワークフローコンテキスト外での編集を検出（アクティブな `/gsd-` コマンドや Task サブエージェントがない場合）
|
||||||
- 状態追跡される変更には `/gsd-quick` や `/gsd-fast` の使用をアドバイス
|
- 状態追跡される変更には `/gsd-quick` や `/gsd-fast` の使用をアドバイス
|
||||||
- `hooks.workflow_guard: true` によるオプトイン（デフォルト: false）
|
- `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/` |
|
| Claude Code | `~/.claude` | `./.claude` | グローバル `skills/gsd-*/SKILL.md`；ローカル `commands/gsd/*.md` | `agents/gsd-*.md` | `settings.json` フックと statusLine エントリ |
|
||||||
| Gemini CLI | `/gsd-command` | Task起動 | `~/.gemini/` |
|
| OpenCode | `~/.config/opencode` | `./.opencode` | `command/gsd-*.md` | `agents/gsd-*.md` | `opencode.json` または `opencode.jsonc`；GSD フックなし |
|
||||||
| Codex | `$gsd-command` | スキル | `~/.codex/` |
|
| Kilo | `~/.config/kilo` | `./.kilo` | `command/gsd-*.md` | `agents/gsd-*.md` | `kilo.json` または `kilo.jsonc`；GSD フックなし |
|
||||||
| Copilot | `/gsd-command` | エージェント委譲 | `~/.github/` |
|
| Gemini CLI | `~/.gemini` | `./.gemini` | `commands/gsd/*.toml` | `agents/gsd-*.md` | `settings.json` フィーチャーフラグ、フック、statusline |
|
||||||
| Antigravity | スキル | スキル | `~/.gemini/antigravity/` |
|
| 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）
|
1. **ツール名マッピング** — 各ランタイムは独自のツール名を持つ（例：Claude の `Bash` → Copilot の `execute`）
|
||||||
2. **フックイベント名** — Claude Codeは `PostToolUse`、Geminiは `AfterTool` を使用
|
2. **フックイベント名** — Claude Code は `PostToolUse`、Gemini は `AfterTool` を使用
|
||||||
3. **エージェントフロントマター** — 各ランタイムは独自のエージェント定義形式を持つ
|
3. **エージェントフロントマター** — 各ランタイムは独自のエージェント定義形式を持つ
|
||||||
4. **パス規約** — 各ランタイムは異なるディレクトリに設定を保存
|
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)
|
||||||
|
|||||||
@@ -1,26 +1,36 @@
|
|||||||
# GSD CLI ツールリファレンス
|
# 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
|
```bash
|
||||||
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
|
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
|
||||||
```
|
```
|
||||||
|
|
||||||
**グローバルフラグ:**
|
**グローバルフラグ（CJS）:**
|
||||||
| フラグ | 説明 |
|
|
||||||
|--------|------|
|
|
||||||
| `--raw` | 機械可読な出力（JSON またはプレーンテキスト、フォーマットなし） |
|
| フラグ | 説明 |
|
||||||
| `--cwd <path>` | 作業ディレクトリの上書き（サンドボックス化されたサブエージェント向け） |
|
| -------------- | ---------------------------------------------------------------------------- |
|
||||||
|
| `--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]
|
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 スナップショット
|
### State スナップショット
|
||||||
@@ -152,7 +169,9 @@ node gsd-tools.cjs config-set-model-profile <profile>
|
|||||||
```bash
|
```bash
|
||||||
# 現在のプロファイルに基づいてエージェント用モデルを取得
|
# 現在のプロファイルに基づいてエージェント用モデルを取得
|
||||||
node gsd-tools.cjs resolve-model <agent-name>
|
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`
|
エージェント名: `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/ の整合性チェック、任意で修復
|
# .planning/ の整合性チェック、任意で修復
|
||||||
node gsd-tools.cjs validate health [--repair]
|
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 コマンド
|
## Template コマンド
|
||||||
@@ -275,9 +303,13 @@ node gsd-tools.cjs init todos [area]
|
|||||||
node gsd-tools.cjs init milestone-op
|
node gsd-tools.cjs init milestone-op
|
||||||
node gsd-tools.cjs init map-codebase
|
node gsd-tools.cjs init map-codebase
|
||||||
node gsd-tools.cjs init progress
|
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
|
```bash
|
||||||
INIT=$(node gsd-tools.cjs init execute-phase "1")
|
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
|
```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 stats [json|table]
|
||||||
|
|
||||||
# 進捗表示
|
# 進捗表示（人間が読める形式）
|
||||||
node gsd-tools.cjs progress [json|table|bar]
|
node gsd-tools.cjs progress [json|table|bar]
|
||||||
|
|
||||||
|
# 型付き JSON サーフェスとしての進捗（#455）
|
||||||
|
node gsd-tools.cjs progress --json
|
||||||
|
|
||||||
# TODO を完了にする
|
# TODO を完了にする
|
||||||
node gsd-tools.cjs todo complete <filename>
|
node gsd-tools.cjs todo complete <filename>
|
||||||
|
|
||||||
# UAT 監査 — 全フェーズの未解決項目をスキャン
|
# UAT 監査 — 全フェーズの未解決項目をスキャン
|
||||||
node gsd-tools.cjs audit-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 コミット
|
# 設定チェック付き 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 キーが必要）
|
# Web 検索（Brave API キーが必要）
|
||||||
node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
|
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` |
|
| State | `lib/state.cjs` | すべての `state` サブコマンド、`state-snapshot` |
|
||||||
| Phase | `lib/phase.cjs` | フェーズ CRUD、`find-phase`、`phase-plan-index`、`phases list` |
|
| 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` | ロードマップ解析、フェーズ抽出、進捗更新 |
|
| Roadmap | `lib/roadmap.cjs` | ロードマップ解析、フェーズ抽出、進捗更新 |
|
||||||
| Config | `lib/config.cjs` | 設定の読み書き、セクション初期化 |
|
| Config | `lib/config.cjs` | 設定の読み書き、セクション初期化 |
|
||||||
| Verify | `lib/verify.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/検証監査 |
|
| UAT | `lib/uat.cjs` | 全フェーズ横断 UAT/検証監査 |
|
||||||
| Profile Output | `lib/profile-output.cjs` | 開発者プロファイルのフォーマット |
|
| Profile Output | `lib/profile-output.cjs` | 開発者プロファイルのフォーマット |
|
||||||
| Profile Pipeline | `lib/profile-pipeline.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)
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
493
docs/ja-JP/INVENTORY.md
Normal file
493
docs/ja-JP/INVENTORY.md
Normal 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)
|
||||||
@@ -1,27 +1,69 @@
|
|||||||
# GSD Core ドキュメント
|
# 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）
|
- [はじめてのプロジェクト](tutorials/your-first-project.md) — インストールから最初のフェーズ出荷まで、確実な一本道
|
||||||
- **はじめに:** [README](../README.md) → インストール → `/gsd-new-project`
|
- [既存コードベースのオンボーディング](tutorials/onboarding-an-existing-codebase.md) — ブラウンフィールドのリポジトリに GSD Core を導入する
|
||||||
- **ワークフロー完全ガイド:** [ユーザーガイド](USER-GUIDE.md)
|
|
||||||
- **コマンド一覧:** [コマンドリファレンス](COMMANDS.md)
|
---
|
||||||
- **GSD の設定:** [設定リファレンス](CONFIGURATION.md)
|
|
||||||
- **システム内部の仕組み:** [アーキテクチャ](ARCHITECTURE.md)
|
## How-to guides
|
||||||
- **コントリビュートや拡張:** [CLI ツールリファレンス](CLI-TOOLS.md) + [エージェントリファレンス](AGENTS.md)
|
|
||||||
|
- [ランタイムへのインストール](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) — リリース履歴
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
@@ -2,9 +2,9 @@
|
|||||||
|
|
||||||
ツール使用後に実行されるフック（Claude Code では `PostToolUse`、Gemini CLI では `AfterTool`）で、コンテキストウィンドウの使用量が高くなった際にエージェントに警告します。
|
ツール使用後に実行されるフック（Claude Code では `PostToolUse`、Gemini CLI では `AfterTool`）で、コンテキストウィンドウの使用量が高くなった際にエージェントに警告します。
|
||||||
|
|
||||||
## 課題
|
## 問題
|
||||||
|
|
||||||
ステータスラインはコンテキスト使用量を**ユーザー**に表示しますが、**エージェント**自身はコンテキストの制限を認識していません。コンテキストが不足すると、エージェントは限界に達するまで作業を続行し、タスクの途中で状態を保存できないまま停止する可能性があります。
|
ステータスラインはコンテキスト使用量を**ユーザー**に表示しますが、**エージェント**自身はコンテキストの制限を認識していません。コンテキストが不足すると、エージェントは限界に達するまで作業を続行し、状態を保存できないままタスクの途中で止まる可能性があります。
|
||||||
|
|
||||||
## 仕組み
|
## 仕組み
|
||||||
|
|
||||||
@@ -16,34 +16,34 @@
|
|||||||
## しきい値
|
## しきい値
|
||||||
|
|
||||||
| レベル | 残量 | エージェントの動作 |
|
| レベル | 残量 | エージェントの動作 |
|
||||||
|--------|------|------------------|
|
|-------|-----------|----------------|
|
||||||
| Normal | > 35% | 警告なし |
|
| Normal | > 35% | 警告なし |
|
||||||
| WARNING | <= 35% | 現在のタスクをまとめ、新しい複雑な作業の開始を避ける |
|
| WARNING | <= 35% | 現在のタスクをまとめ、新しい複雑な作業の開始を避ける |
|
||||||
| CRITICAL | <= 25% | 即座に停止し、状態を保存する（`/gsd-pause-work`） |
|
| CRITICAL | <= 25% | 即座に停止し、状態を保存する（`/gsd-pause-work`） |
|
||||||
|
|
||||||
## デバウンス
|
## デバウンス
|
||||||
|
|
||||||
エージェントへの繰り返し警告を防ぐため:
|
エージェントへの繰り返し警告を防ぐため：
|
||||||
- 最初の警告は即座に発火
|
- 最初の警告は即座に発火
|
||||||
- 以降の警告は間に5回のツール使用が必要
|
- 以降の警告は間に 5 回のツール使用が必要
|
||||||
- 深刻度のエスカレーション（WARNING -> CRITICAL）はデバウンスをバイパス
|
- 深刻度のエスカレーション（WARNING -> CRITICAL）はデバウンスをバイパス
|
||||||
|
|
||||||
## アーキテクチャ
|
## アーキテクチャ
|
||||||
|
|
||||||
```
|
```
|
||||||
ステータスラインフック (gsd-statusline.js)
|
Statusline Hook (gsd-statusline.js)
|
||||||
| 書き込み
|
| writes
|
||||||
v
|
v
|
||||||
/tmp/claude-ctx-{session_id}.json
|
/tmp/claude-ctx-{session_id}.json
|
||||||
^ 読み取り
|
^ reads
|
||||||
|
|
|
|
||||||
コンテキストモニター (gsd-context-monitor.js, PostToolUse/AfterTool)
|
Context Monitor (gsd-context-monitor.js, PostToolUse/AfterTool)
|
||||||
| 注入
|
| injects
|
||||||
v
|
v
|
||||||
additionalContext -> エージェントが警告を確認
|
additionalContext -> Agent sees warning
|
||||||
```
|
```
|
||||||
|
|
||||||
ブリッジファイルはシンプルな JSON オブジェクトです:
|
ブリッジファイルはシンプルな 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` に `statusLine` として登録されます；コンテキストモニター（`gsd-context-monitor.js`）は `PostToolUse` フックとして登録されます（Gemini CLI の場合は `AfterTool`）。どちらのエントリも、インストーラーを実行した Node 実行ファイルの絶対パスを使います。Windows PowerShell では、引用符付きの実行ファイルパスに `&` をプレフィックスしてください。
|
||||||
- **コンテキストモニター**（ブリッジファイルの読み取り）: 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"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 安全性
|
## 安全性
|
||||||
|
|
||||||
- フックは全体を try/catch で囲み、エラー時はサイレントに終了
|
- フックは全体を try/catch で囲み、エラー時はサイレントに終了
|
||||||
- ツール実行をブロックしない — モニターの故障がエージェントのワークフローを壊してはならない
|
- ツール実行をブロックしない — モニターが壊れてもエージェントのワークフローを壊してはならない
|
||||||
- 古いメトリクス（60秒以上前）は無視
|
- 古いメトリクス（60 秒以上前）は無視
|
||||||
- ブリッジファイルが存在しない場合も正常に処理（サブエージェント、新規セッション）
|
- ブリッジファイルが存在しない場合も正常に処理（サブエージェント、新規セッション）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [アーキテクチャ](ARCHITECTURE.md)
|
||||||
|
- [設定](CONFIGURATION.md)
|
||||||
|
- [ドキュメント索引](README.md)
|
||||||
|
|||||||
90
docs/ja-JP/explanation/context-engineering.md
Normal file
90
docs/ja-JP/explanation/context-engineering.md
Normal 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
146
docs/ja-JP/explanation/multi-agent-orchestration.md
Normal 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
117
docs/ja-JP/explanation/security-model.md
Normal 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
129
docs/ja-JP/explanation/the-phase-loop.md
Normal 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
218
docs/ja-JP/how-to/configure-model-profiles.md
Normal 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
178
docs/ja-JP/how-to/debug-a-failed-execution.md
Normal 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
149
docs/ja-JP/how-to/design-a-ui-phase.md
Normal 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
158
docs/ja-JP/how-to/discuss-a-phase.md
Normal 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
176
docs/ja-JP/how-to/drive-gsd-from-a-tracker-issue.md
Normal 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
119
docs/ja-JP/how-to/execute-a-phase.md
Normal 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
121
docs/ja-JP/how-to/handle-quick-and-fast-tasks.md
Normal 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
291
docs/ja-JP/how-to/install-on-your-runtime.md
Normal 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
144
docs/ja-JP/how-to/isolate-work-with-workspaces.md
Normal 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
145
docs/ja-JP/how-to/migrate-from-gsd-2.md
Normal 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
216
docs/ja-JP/how-to/plan-a-phase.md
Normal 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
323
docs/ja-JP/how-to/recover-and-troubleshoot.md
Normal 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
124
docs/ja-JP/how-to/run-phases-autonomously.md
Normal 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
159
docs/ja-JP/how-to/set-up-cross-ai-review.md
Normal 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
160
docs/ja-JP/how-to/spike-and-sketch.md
Normal 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
120
docs/ja-JP/how-to/update-gsd.md
Normal 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
124
docs/ja-JP/how-to/verify-and-ship.md
Normal 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
157
docs/ja-JP/how-to/work-in-parallel-with-workstreams.md
Normal 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
92
docs/ja-JP/issue-driven-orchestration.md
Normal 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
148
docs/ja-JP/reference/context-md.md
Normal 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
249
docs/ja-JP/reference/plan-md.md
Normal 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
225
docs/ja-JP/reference/planning-artifacts.md
Normal 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
201
docs/ja-JP/reference/state-md.md
Normal 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
226
docs/ja-JP/tutorials/onboarding-an-existing-codebase.md
Normal 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
291
docs/ja-JP/tutorials/your-first-project.md
Normal 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 の導入
|
||||||
@@ -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`（デフォルト）
|
### `discuss`（デフォルト）
|
||||||
|
|
||||||
従来のインタビュー形式のフローです。Claude がフェーズ内の不明瞭な領域を特定し、選択肢として提示した後、各領域について約4つの質問を行います。以下のケースに適しています:
|
オリジナルのインタビュースタイルのフロー。Claude がフェーズのグレーエリアを特定し、選択のために提示し、エリアごとに約 4 つの質問をします。以下の場合に適しています：
|
||||||
|
|
||||||
- コードベースが初めてで、初期フェーズの場合
|
- コードベースが新しい初期フェーズ
|
||||||
- ユーザーが積極的に意見を表明したい場合
|
- ユーザーが積極的に表明したい強い意見を持っているフェーズ
|
||||||
- ガイド付きの対話的なコンテキスト収集を好むユーザー
|
- ガイドされた会話形式のコンテキスト収集を好むユーザー
|
||||||
|
|
||||||
### `assumptions`
|
### `assumptions`
|
||||||
|
|
||||||
コードベース優先のフローです。Claude がサブエージェントを通じてコードベースを深く分析し（関連ファイルを5〜15個読み取り）、根拠付きの仮説を立てて確認・修正を求めます。以下のケースに適しています:
|
コードベースファーストのフロー。Claude はサブエージェント経由でコードベースを深く分析し（関連ファイルを 5〜15 件読み取り）、証拠付きで仮定を形成し、確認または修正のために提示します。以下の場合に適しています：
|
||||||
|
|
||||||
- 明確なパターンが確立されたコードベース
|
- 明確なパターンを持つ確立されたコードベース
|
||||||
- インタビューの質問が自明と感じるユーザー
|
- インタビューの質問が明らかに思えるユーザー
|
||||||
- より高速なコンテキスト収集（約2〜4回のやり取り vs 約15〜20回）
|
- より速いコンテキスト収集（約 2〜4 回のやり取り vs 約 15〜20 回）
|
||||||
|
|
||||||
## 設定
|
## 設定
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# assumptions モードを有効にする
|
# 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 モードの仕組み
|
## Assumptions モードの仕組み
|
||||||
|
|
||||||
1. **初期化** — discuss モードと同様（前回のコンテキスト読み込み、コードベース調査、TODO チェック）
|
1. **Init** — discuss モードと同じ（以前のコンテキストを読み込み、コードベースを偵察し、todo を確認）
|
||||||
2. **深層分析** — Explore サブエージェントがフェーズに関連するコードベースファイルを5〜15個読み取る
|
2. **深い分析** — Explore サブエージェントがフェーズに関連する 5〜15 のコードベースファイルを読み取る
|
||||||
3. **仮説の提示** — 各仮説には以下が含まれる:
|
3. **仮定の表示** — 各仮定には以下が含まれる：
|
||||||
- Claude が何をどのような理由で行うか（ファイルパスを引用）
|
- Claude が何をどのような理由で行うか（ファイルパスを引用）
|
||||||
- 仮説が間違っていた場合のリスク
|
- 仮定が誤っている場合に何が問題になるか
|
||||||
- 確信度レベル（Confident / Likely / Unclear）
|
- 信頼レベル（Confident / Likely / Unclear）
|
||||||
4. **確認または修正** — ユーザーが仮説をレビューし、変更が必要なものを選択
|
4. **確認または修正** — ユーザーが仮定を確認し、変更が必要なものを選択
|
||||||
5. **CONTEXT.md の生成** — discuss モードと同一の出力フォーマット
|
5. **CONTEXT.md の書き込み** — discuss モードと同一の出力フォーマット
|
||||||
|
|
||||||
## フラグの互換性
|
## フラグの互換性
|
||||||
|
|
||||||
| フラグ | `discuss` モード | `assumptions` モード |
|
| フラグ | `discuss` モード | `assumptions` モード |
|
||||||
|--------|-----------------|---------------------|
|
|------|----------------|-------------------|
|
||||||
| `--auto` | 推奨回答を自動選択 | 確認ゲートをスキップし、Unclear 項目を自動解決 |
|
| `--auto` | 推奨される答えを自動選択 | 確認ゲートをスキップし、Unclear 項目を自動解決 |
|
||||||
| `--batch` | 質問をバッチでグループ化 | N/A（修正は既にバッチ化済み） |
|
| `--batch` | 質問をバッチでグループ化 | N/A（修正はすでにバッチ化） |
|
||||||
| `--text` | プレーンテキスト形式の質問（リモートセッション向け） | プレーンテキスト形式の質問（リモートセッション向け） |
|
| `--text` | プレーンテキストの質問（リモートセッション） | プレーンテキストの質問（リモートセッション） |
|
||||||
| `--analyze` | 質問ごとにトレードオフ表を表示 | N/A（仮説に根拠が含まれる） |
|
| `--analyze` | 質問ごとにトレードオフテーブルを表示 | N/A（仮定には証拠が含まれる） |
|
||||||
|
|
||||||
## 出力
|
## 出力
|
||||||
|
|
||||||
両モードとも、同じ6セクション構成の CONTEXT.md を生成します:
|
両方のモードが同じ 6 つのセクションを持つ同一の `CONTEXT.md` を生成します：
|
||||||
- `<domain>` — フェーズの境界
|
|
||||||
- `<decisions>` — 確定した実装上の決定事項
|
|
||||||
- `<canonical_refs>` — 下流エージェントが読むべき仕様・ドキュメント
|
|
||||||
- `<code_context>` — 再利用可能なアセット、パターン、統合ポイント
|
|
||||||
- `<specifics>` — ユーザーの参照情報と好み
|
|
||||||
- `<deferred>` — 将来のフェーズに先送りするアイデア
|
|
||||||
|
|
||||||
下流エージェント（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 ドキュメントの完全な目次。
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# GSD 아키텍처
|
# GSD Core 아키텍처
|
||||||
|
|
||||||
> 기여자와 고급 사용자를 위한 시스템 아키텍처입니다. 사용자 문서는 [Feature Reference](FEATURES.md) 또는 [User Guide](USER-GUIDE.md)를 참조하세요.
|
> 기여자와 고급 사용자를 위한 시스템 아키텍처. 사용자 문서는 [기능 레퍼런스](FEATURES.md) 또는 [사용자 가이드](USER-GUIDE.md)를 참조하라.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -21,12 +21,12 @@
|
|||||||
|
|
||||||
## 시스템 개요
|
## 시스템 개요
|
||||||
|
|
||||||
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에게 필요한 모든 것을 제공하는 구조화된 아티팩트
|
1. **컨텍스트 엔지니어링** — 작업별로 AI에게 필요한 모든 것을 제공하는 구조화된 결과물([컨텍스트 엔지니어링](explanation/context-engineering.md) 참조)
|
||||||
2. **멀티 에이전트 오케스트레이션** — 새로운 컨텍스트 윈도우로 전문화된 에이전트를 생성하는 가벼운 오케스트레이터
|
2. **다중 에이전트 오케스트레이션** — 신선한 컨텍스트 윈도우로 전문화된 에이전트를 생성하는 얇은 오케스트레이터([다중 에이전트 오케스트레이션](explanation/multi-agent-orchestration.md) 참조)
|
||||||
3. **명세 주도 개발** — 요구 사항 → 조사 → 계획 → 실행 → 검증 파이프라인
|
3. **명세 주도 개발** — 요구 사항 → 리서치 → 계획 → 실행 → 검증 파이프라인
|
||||||
4. **상태 관리** — 세션과 컨텍스트 초기화를 넘나드는 영구적인 프로젝트 메모리
|
4. **상태 관리** — 세션과 컨텍스트 리셋 전반에 걸친 영구적인 프로젝트 메모리
|
||||||
|
|
||||||
```
|
```
|
||||||
┌──────────────────────────────────────────────────────┐
|
┌──────────────────────────────────────────────────────┐
|
||||||
@@ -54,8 +54,8 @@ GSD는 사용자와 AI 코딩 에이전트(Claude Code, Gemini CLI, OpenCode, Ki
|
|||||||
│ │ │
|
│ │ │
|
||||||
┌──────▼──────────────▼─────────────────▼──────────────┐
|
┌──────▼──────────────▼─────────────────▼──────────────┐
|
||||||
│ CLI TOOLS LAYER │
|
│ CLI TOOLS LAYER │
|
||||||
│ get-shit-done/bin/gsd-tools.cjs │
|
│ gsd-tools.cjs command families + domain modules │
|
||||||
│ (State, config, phase, roadmap, verify, templates) │
|
│ command-routing-hub + observability seams │
|
||||||
└──────────────────────┬───────────────────────────────┘
|
└──────────────────────┬───────────────────────────────┘
|
||||||
│
|
│
|
||||||
┌──────────────────────▼───────────────────────────────┐
|
┌──────────────────────▼───────────────────────────────┐
|
||||||
@@ -69,36 +69,39 @@ GSD는 사용자와 AI 코딩 에이전트(Claude Code, Gemini CLI, OpenCode, Ki
|
|||||||
|
|
||||||
## 설계 원칙
|
## 설계 원칙
|
||||||
|
|
||||||
### 1. 에이전트별 새로운 컨텍스트
|
### 1. 에이전트별 신선한 컨텍스트
|
||||||
|
|
||||||
오케스트레이터가 생성하는 모든 에이전트는 새로운 컨텍스트 윈도우(최대 200K 토큰)를 받습니다. 이를 통해 컨텍스트 오염을 방지합니다 — AI가 컨텍스트 윈도우에 누적된 대화로 인해 품질이 저하되는 현상입니다.
|
오케스트레이터가 생성하는 모든 에이전트는 깨끗한 컨텍스트 윈도우(최대 200K 토큰)를 받는다. 이는 컨텍스트 부패 — AI가 컨텍스트 윈도우를 누적된 대화로 채울 때 발생하는 품질 저하 — 를 제거한다.
|
||||||
|
|
||||||
### 2. 가벼운 오케스트레이터
|
### 2. 얇은 오케스트레이터
|
||||||
|
|
||||||
워크플로우 파일(`get-shit-done/workflows/*.md`)은 무거운 작업을 직접 수행하지 않습니다. 다음 작업만 담당합니다.
|
워크플로우 파일(`get-shit-done/workflows/*.md`)은 무거운 작업을 직접 수행하지 않는다. 오케스트레이터가 하는 것:
|
||||||
- `gsd-tools.cjs init <workflow>`로 컨텍스트를 로드합니다
|
|
||||||
- 집중된 프롬프트로 전문화된 에이전트를 생성합니다
|
- `gsd-tools.cjs init <workflow>`로 컨텍스트 로드
|
||||||
- 결과를 수집하여 다음 단계로 전달합니다
|
- 집중된 프롬프트로 전문화된 에이전트 생성
|
||||||
- 단계 사이에 상태를 업데이트합니다
|
- 결과 수집 및 다음 단계로 라우팅
|
||||||
|
- 단계 사이에 상태 업데이트
|
||||||
|
|
||||||
### 3. 파일 기반 상태
|
### 3. 파일 기반 상태
|
||||||
|
|
||||||
모든 상태는 `.planning/`에 사람이 읽을 수 있는 Markdown과 JSON으로 저장됩니다. 데이터베이스, 서버, 외부 의존성이 없습니다. 이를 통해 다음이 가능합니다.
|
모든 상태는 `.planning/`에 사람이 읽을 수 있는 마크다운과 JSON으로 저장된다. 데이터베이스도, 서버도, 외부 의존성도 없다. 이것이 의미하는 바:
|
||||||
- 컨텍스트 초기화(`/clear`) 이후에도 상태가 유지됩니다
|
|
||||||
- 사람과 에이전트 모두 상태를 확인할 수 있습니다
|
- 컨텍스트 리셋(`/clear`) 이후에도 상태가 유지된다
|
||||||
- 팀 가시성을 위해 git에 커밋할 수 있습니다
|
- 사람과 에이전트 모두 상태를 확인할 수 있다
|
||||||
|
- 팀 가시성을 위해 git에 커밋할 수 있다
|
||||||
|
|
||||||
### 4. 부재 = 활성화
|
### 4. 부재 = 활성화
|
||||||
|
|
||||||
워크플로우 기능 플래그는 **부재 = 활성화** 패턴을 따릅니다. `config.json`에 키가 없으면 기본값은 `true`입니다. 사용자는 기능을 명시적으로 비활성화하며 기본값을 활성화할 필요가 없습니다.
|
워크플로우 기능 플래그는 **부재 = 활성화** 패턴을 따른다. `config.json`에 키가 없으면 기본값은 `true`이다. 사용자는 기능을 명시적으로 비활성화하며; 기본값을 활성화할 필요가 없다.
|
||||||
|
|
||||||
### 5. 심층 방어
|
### 5. 심층 방어
|
||||||
|
|
||||||
여러 레이어가 일반적인 실패 모드를 방지합니다.
|
여러 계층이 일반적인 실패 모드를 방지한다:
|
||||||
- 계획은 실행 전에 검증됩니다 (plan-checker 에이전트)
|
|
||||||
- 실행은 작업당 원자적 커밋을 생성합니다
|
- 계획은 실행 전에 검증된다 (plan-checker 에이전트)
|
||||||
- 실행 후 검증은 단계 목표에 대해 확인합니다
|
- 실행은 작업당 원자적 커밋을 생성한다
|
||||||
- UAT는 최종 게이트로서 사람의 검증을 제공합니다
|
- 실행 후 검증은 단계 목표에 대해 확인한다
|
||||||
|
- UAT는 최종 게이트로서 사람 검증을 제공한다
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -106,51 +109,121 @@ GSD는 사용자와 AI 코딩 에이전트(Claude Code, Gemini CLI, OpenCode, Ki
|
|||||||
|
|
||||||
### Commands (`commands/gsd/*.md`)
|
### Commands (`commands/gsd/*.md`)
|
||||||
|
|
||||||
사용자 대면 진입점입니다. 각 파일은 YAML 전문(name, description, allowed-tools)과 워크플로우를 부트스트랩하는 프롬프트 본문을 포함합니다. 명령어는 다음과 같이 설치됩니다.
|
사용자 대면 진입점. 각 파일은 YAML 전문(name, description, allowed-tools)과 워크플로우를 부트스트랩하는 프롬프트 본문을 포함한다. 명령어는 다음과 같이 설치된다:
|
||||||
- **Claude Code:** 커스텀 슬래시 명령어 (`/gsd-command-name`)
|
|
||||||
- **OpenCode / Kilo:** 슬래시 명령어 (`/gsd-command-name`)
|
- **Claude Code:** 커스텀 슬래시 명령어 (하이픈 형식, `/gsd-command-name`)
|
||||||
|
- **OpenCode / Kilo:** 슬래시 명령어 (하이픈 형식, `/gsd-command-name`)
|
||||||
- **Codex:** Skills (`$gsd-command-name`)
|
- **Codex:** Skills (`$gsd-command-name`)
|
||||||
- **Copilot:** 슬래시 명령어 (`/gsd-command-name`)
|
- **Copilot:** 슬래시 명령어 (하이픈 형식, `/gsd-command-name`)
|
||||||
|
- **Gemini CLI:** `gsd:` 네임스페이스 하의 슬래시 명령어 (콜론 형식, `/gsd:command-name`) — Gemini는 플러그인 id 아래 모든 커스텀 명령어를 네임스페이스화하므로 설치 경로가 모든 본문 텍스트 참조를 콜론 형식으로 다시 쓴다
|
||||||
- **Antigravity:** Skills
|
- **Antigravity:** Skills
|
||||||
|
|
||||||
**전체 명령어 수:** 44개
|
**전체 명령어 수:** 권위 있는 개수와 전체 목록은 [`docs/INVENTORY.md`](INVENTORY.md#commands)를 참조하라.
|
||||||
|
|
||||||
|
#### 2단계 계층적 라우팅 (v1.40, [#2792](https://github.com/open-gsd/gsd-core/issues/2792))
|
||||||
|
|
||||||
|
열망적 스킬 목록 토큰 비용을 낮게 유지하기 위해 v1.40은 구체적인 하위 스킬 위에 계층화된 여섯 개의 네임스페이스 **메타 스킬** (`gsd-workflow`, `gsd-project`, `gsd-quality`, `gsd-context`, `gsd-manage`, `gsd-ideate` — `commands/gsd/ns-*.md`에서 소싱되지만 호출 가능한 `name:`은 여기 표시된 간단한 형식)을 도입한다. 모델은 평평한 86개 스킬 목록(~2,150 토큰) 대신 6개의 네임스페이스 라우터(~120 토큰)를 보고, 네임스페이스를 선택한 다음 네임스페이스 라우터 본문에 내장된 라우팅 테이블을 통해 구체적인 하위 스킬로 라우팅한다. 네임스페이스 스킬은 **가산적**이다 — 모든 구체적인 명령어는 여전히 직접 호출 가능하다.
|
||||||
|
|
||||||
|
라우터 설명은 ~40% 토큰 비용으로 프로세 대비 키워드 밀도 태그가 라우팅에서 더 뛰어나다는 Tool Attention 연구에 따라 도구당 파이프로 구분된 키워드 태그(≤ 60자)를 사용한다.
|
||||||
|
|
||||||
|
#### MCP 토큰 예산 상호작용
|
||||||
|
|
||||||
|
열망적 스킬 목록은 턴당 반복되는 두 가지 토큰 비용 중 하나이다. 다른 하나는 `.claude/settings.json`의 모든 활성화된 MCP 서버가 주입하는 MCP 도구 스키마이다. 무거운 MCP 서버(브라우저/playwright, Mac-tools, Windows-tools)는 각각 턴당 20k+ 토큰 비용이 들 수 있다 — 종종 `model_profile` 튜닝이 절약하는 것을 압도한다. 토글은 Claude Code 하니스(`.claude/settings.json`의 `enabledMcpjsonServers` / `disabledMcpjsonServers`)에 있으며 GSD 관심사가 아니다. 2단계 라우팅 계층(#2792)과 규율 있는 MCP 활성화를 함께 사용하는 것이 턴당 가장 큰 비용 레버이다. [`docs/USER-GUIDE.md`](USER-GUIDE.md)와 `references/context-budget.md`에서 감사 체크리스트를 참조하라.
|
||||||
|
|
||||||
### Workflows (`get-shit-done/workflows/*.md`)
|
### Workflows (`get-shit-done/workflows/*.md`)
|
||||||
|
|
||||||
명령어가 참조하는 오케스트레이션 로직입니다. 다음을 포함하는 단계별 프로세스를 담습니다.
|
명령어가 참조하는 오케스트레이션 로직. 다음을 포함하는 단계별 프로세스를 담는다:
|
||||||
- `gsd-tools.cjs init`을 통한 컨텍스트 로드
|
|
||||||
- 모델 해석을 포함한 에이전트 생성 지시
|
- `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 — 집중된 단일 목적 워크플로우 (목표 등급) |
|
||||||
|
|
||||||
|
`workflows/discuss-phase.md`는 이슈 #2551에 따라 더 엄격한 <500줄 상한을 유지한다. 워크플로우가 등급을 초과하면 모드별 본문은 `workflows/<workflow>/modes/<mode>.md`로, 템플릿은 `workflows/<workflow>/templates/`로, 공유 지식은 `get-shit-done/references/`로 추출한다. 부모 파일은 현재 호출에 필요한 모드 및 템플릿 파일만 읽는 얇은 디스패처가 된다.
|
||||||
|
|
||||||
|
`workflows/discuss-phase/`가 이 패턴의 정규 예시이다 — 부모는 디스패치하고, modes/는 플래그별 동작(`power.md`, `all.md`, `auto.md`, `chain.md`, `text.md`, `batch.md`, `analyze.md`, `default.md`, `advisor.md`)을 담으며, templates/는 해당 출력 파일이 작성될 때만 읽히는 CONTEXT.md, DISCUSSION-LOG.md, checkpoint.json 스키마를 담는다.
|
||||||
|
|
||||||
### Agents (`agents/*.md`)
|
### Agents (`agents/*.md`)
|
||||||
|
|
||||||
다음을 지정하는 전문화된 에이전트 정의 파일입니다.
|
다음을 지정하는 전문화된 에이전트 정의:
|
||||||
|
|
||||||
- `name` — 에이전트 식별자
|
- `name` — 에이전트 식별자
|
||||||
- `description` — 역할과 목적
|
- `description` — 역할과 목적
|
||||||
- `tools` — 허용된 도구 접근 권한 (Read, Write, Edit, Bash, Grep, Glob, WebSearch 등)
|
- `tools` — 허용된 도구 접근 (Read, Write, Edit, Bash, Grep, Glob, WebSearch 등)
|
||||||
- `color` — 시각적 구분을 위한 터미널 출력 색상
|
- `color` — 시각적 구분을 위한 터미널 출력 색상
|
||||||
|
|
||||||
**전체 에이전트 수:** 16개
|
**전체 에이전트 수:** 33개
|
||||||
|
|
||||||
### References (`get-shit-done/references/*.md`)
|
### References (`get-shit-done/references/*.md`)
|
||||||
|
|
||||||
워크플로우와 에이전트가 `@-reference`로 참조하는 공유 지식 문서입니다.
|
워크플로우와 에이전트가 `@-reference`하는 공유 지식 문서([`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped)에서 권위 있는 개수와 전체 목록 참조):
|
||||||
|
|
||||||
|
**핵심 레퍼런스:**
|
||||||
|
|
||||||
- `checkpoints.md` — 체크포인트 유형 정의 및 상호작용 패턴
|
- `checkpoints.md` — 체크포인트 유형 정의 및 상호작용 패턴
|
||||||
- `model-profiles.md` — 에이전트별 모델 티어 할당
|
- `gates.md` — plan-checker와 verifier에 연결된 4가지 정규 게이트 유형 (확인, 품질, 안전, 전환)
|
||||||
- `verification-patterns.md` — 다양한 아티팩트 유형 검증 방법
|
- `model-profiles.md` — 에이전트별 모델 등급 할당
|
||||||
|
- `model-profile-resolution.md` — 모델 해결 알고리즘 문서
|
||||||
|
- `verification-patterns.md` — 다양한 결과물 유형 검증 방법
|
||||||
|
- `verification-overrides.md` — 결과물별 검증 재정의 규칙
|
||||||
- `planning-config.md` — 전체 config 스키마 및 동작
|
- `planning-config.md` — 전체 config 스키마 및 동작
|
||||||
- `git-integration.md` — git 커밋, 브랜칭, 히스토리 패턴
|
- `git-integration.md` — git 커밋, 브랜칭, 이력 패턴
|
||||||
|
- `git-planning-commit.md` — 계획 디렉터리 커밋 컨벤션
|
||||||
- `questioning.md` — 프로젝트 초기화를 위한 꿈 추출 철학
|
- `questioning.md` — 프로젝트 초기화를 위한 꿈 추출 철학
|
||||||
- `tdd.md` — 테스트 주도 개발 통합 패턴
|
- `tdd.md` — 테스트 주도 개발 통합 패턴
|
||||||
- `ui-brand.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` — 의사 결정 포인트에서의 조건부 thinking partner 활성화
|
||||||
|
|
||||||
|
**Thinking 모델 레퍼런스:**
|
||||||
|
|
||||||
|
GSD 워크플로우에 thinking 클래스 모델(o3, o4-mini, Gemini 2.5 Pro)을 통합하기 위한 레퍼런스:
|
||||||
|
|
||||||
|
- `thinking-models-debug.md` — 디버깅 워크플로우를 위한 thinking 모델 패턴
|
||||||
|
- `thinking-models-execution.md` — 실행 에이전트를 위한 thinking 모델 패턴
|
||||||
|
- `thinking-models-planning.md` — 계획 에이전트를 위한 thinking 모델 패턴
|
||||||
|
- `thinking-models-research.md` — 리서치 에이전트를 위한 thinking 모델 패턴
|
||||||
|
- `thinking-models-verification.md` — 검증 에이전트를 위한 thinking 모델 패턴
|
||||||
|
|
||||||
|
**모듈식 플래너 분해:**
|
||||||
|
|
||||||
|
플래너 에이전트(`agents/gsd-planner.md`)는 일부 런타임에서 부과하는 50K 문자 제한 이하로 유지하기 위해 단일 모놀리식 파일에서 핵심 에이전트 + 레퍼런스 모듈로 분해되었다:
|
||||||
|
|
||||||
|
- `planner-gap-closure.md` — 갭 클로저 모드 동작 (VERIFICATION.md 읽기, 대상 재계획)
|
||||||
|
- `planner-reviews.md` — 교차 AI 리뷰 통합 (`/gsd-review`의 REVIEWS.md 읽기)
|
||||||
|
- `planner-revision.md` — 반복적 개선을 위한 계획 수정 패턴
|
||||||
|
|
||||||
### Templates (`get-shit-done/templates/`)
|
### Templates (`get-shit-done/templates/`)
|
||||||
|
|
||||||
모든 계획 아티팩트를 위한 Markdown 템플릿입니다. `gsd-tools.cjs template fill`과 `scaffold` 명령어가 사전 구조화된 파일을 생성하는 데 사용합니다.
|
모든 계획 결과물을 위한 마크다운 템플릿. `gsd-tools.cjs template fill` / `phase.scaffold`(와 최상위 `scaffold`)가 사전 구조화된 파일을 생성하는 데 사용:
|
||||||
- `project.md`, `requirements.md`, `roadmap.md`, `state.md` — 핵심 프로젝트 파일
|
- `project.md`, `requirements.md`, `roadmap.md`, `state.md` — 핵심 프로젝트 파일
|
||||||
- `phase-prompt.md` — 단계 실행 프롬프트 템플릿
|
- `phase-prompt.md` — 단계 실행 프롬프트 템플릿
|
||||||
- `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — 세분화 인식 요약 템플릿
|
- `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — 세분화 인식 요약 템플릿
|
||||||
@@ -158,40 +231,60 @@ GSD는 사용자와 AI 코딩 에이전트(Claude Code, Gemini CLI, OpenCode, Ki
|
|||||||
- `UI-SPEC.md`, `UAT.md`, `VALIDATION.md` — 전문화된 검증 템플릿
|
- `UI-SPEC.md`, `UAT.md`, `VALIDATION.md` — 전문화된 검증 템플릿
|
||||||
- `discussion-log.md` — 논의 감사 추적 템플릿
|
- `discussion-log.md` — 논의 감사 추적 템플릿
|
||||||
- `codebase/` — 브라운필드 매핑 템플릿 (stack, architecture, conventions, concerns, structure, testing, integrations)
|
- `codebase/` — 브라운필드 매핑 템플릿 (stack, architecture, conventions, concerns, structure, testing, integrations)
|
||||||
- `research-project/` — 조사 출력 템플릿 (SUMMARY, STACK, FEATURES, ARCHITECTURE, PITFALLS)
|
- `research-project/` — 리서치 출력 템플릿 (SUMMARY, STACK, FEATURES, ARCHITECTURE, PITFALLS)
|
||||||
|
|
||||||
### Hooks (`hooks/`)
|
### Hooks (`hooks/`)
|
||||||
|
|
||||||
호스트 AI 에이전트와 통합되는 런타임 훅입니다.
|
호스트 AI 에이전트와 통합되는 런타임 훅:
|
||||||
|
|
||||||
| 훅 | 이벤트 | 목적 |
|
| 훅 | 이벤트 | 목적 |
|
||||||
|------|-------|---------|
|
|------|-------|---------|
|
||||||
| `gsd-statusline.js` | `statusLine` | 모델, 작업, 디렉터리, 컨텍스트 사용 바 표시 |
|
| `gsd-statusline.js` | `statusLine` | 모델, 작업, 디렉터리, 컨텍스트 사용 바 표시 |
|
||||||
| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | 잔여 35%/25% 시점에 에이전트 대면 컨텍스트 경고 주입 |
|
| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | 잔여 35%/25% 시점에 에이전트 대면 컨텍스트 경고 주입 |
|
||||||
| `gsd-check-update.js` | `SessionStart` | 새 GSD 버전을 백그라운드에서 확인 |
|
| `gsd-check-update.js` | `SessionStart` | 백그라운드 업데이트 확인을 위한 포어그라운드 트리거 |
|
||||||
| `gsd-prompt-guard.js` | `PreToolUse` | `.planning/` 쓰기 작업에서 프롬프트 인젝션 패턴 스캔 (권고용) |
|
| `gsd-check-update-worker.js` | (헬퍼) | `gsd-check-update.js`가 생성하는 백그라운드 워커; 직접 이벤트 등록 없음 |
|
||||||
| `gsd-workflow-guard.js` | `PreToolUse` | GSD 워크플로우 컨텍스트 외부의 파일 편집 감지 (권고용, `hooks.workflow_guard`로 활성화) |
|
| `gsd-prompt-guard.js` | `PreToolUse` | `.planning/` 쓰기에서 프롬프트 인젝션 패턴 스캔 (자문적) |
|
||||||
|
| `gsd-read-injection-scanner.js` | `PostToolUse` | 신뢰할 수 없는 콘텐츠에서 주입된 지시 사항을 위한 Read 도구 출력 스캔 |
|
||||||
|
| `gsd-workflow-guard.js` | `PreToolUse` | GSD 워크플로우 컨텍스트 외부의 파일 편집 감지 (자문적, `hooks.workflow_guard`를 통한 옵트인) |
|
||||||
|
| `gsd-read-guard.js` | `PreToolUse` | 세션에서 아직 읽지 않은 파일에 Edit/Write를 방지하는 자문적 가드 |
|
||||||
|
| `gsd-session-state.sh` | `PostToolUse` | 쉘 기반 런타임을 위한 세션 상태 추적 |
|
||||||
|
| `gsd-validate-commit.sh` | `PostToolUse` | 컨벤셔널 커밋 시행을 위한 커밋 검증 |
|
||||||
|
| `gsd-phase-boundary.sh` | `PostToolUse` | 워크플로우 전환을 위한 단계 경계 감지 |
|
||||||
|
|
||||||
|
권위 있는 11개 훅 목록은 [`docs/INVENTORY.md`](INVENTORY.md#hooks-11-shipped)를 참조하라.
|
||||||
|
|
||||||
|
### Command Routing Hub (`get-shit-done/bin/lib/command-routing-hub.cjs`)
|
||||||
|
|
||||||
|
CJS 명령어 패밀리 라우터는 `CommandRoutingHub`를 통해 디스패치한다. 허브는 no-throw 순수 결과 계약(`hub.dispatch()`는 내부 예외를 잡아 `{ ok: false, kind, ...typedPayload }`를 반환)과 닫힌 런타임 오류 분류(`UnknownCommand`, `InvalidArgs`, `HandlerRefusal`, `HandlerFailure`)를 소유한다. 라우터 어댑터는 얇은 CLI 번역기로 유지된다 — 허브를 구축하고, `dispatch`를 호출하고, 결과를 `output()`/`error()` 호출에 매핑한다. 런타임은 단일 경로이다(이중 런타임 모드 선택 없음). `docs/adr/0174-retire-gsd-sdk-package-boundary.md` 참조.
|
||||||
|
|
||||||
### CLI Tools (`get-shit-done/bin/`)
|
### CLI Tools (`get-shit-done/bin/`)
|
||||||
|
|
||||||
17개의 도메인 모듈을 포함하는 Node.js CLI 유틸리티(`gsd-tools.cjs`)입니다.
|
`get-shit-done/bin/lib/`에 걸쳐 분할된 도메인 모듈을 가진 Node.js CLI 유틸리티(`gsd-tools.cjs`)(권위 있는 목록은 [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) 참조):
|
||||||
|
|
||||||
|
|
||||||
|
| 모듈 | 책임 |
|
||||||
|
| ---------------------- | --------------------------------------------------------------------------------------------------- |
|
||||||
|
| `core.cjs` | 오류 처리, 출력 형식, 공유 유틸리티; 계획 헬퍼를 위한 호환성 재내보내기 |
|
||||||
|
| `planning-workspace.cjs` | 계획 심(`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 작업 |
|
||||||
|
| `init.cjs` | 각 워크플로우 유형을 위한 복합 컨텍스트 로딩 |
|
||||||
|
| `milestone.cjs` | 마일스톤 보관, 요구 사항 표시 |
|
||||||
|
| `commands.cjs` | 기타 명령어 (slug, timestamp, todos, scaffolding, stats) |
|
||||||
|
| `model-profiles.cjs` | 모델 프로필 해결 테이블 |
|
||||||
|
| `security.cjs` | 경로 탐색 방지, 프롬프트 인젝션 탐지, 안전한 JSON 파싱, 쉘 인수 검증 |
|
||||||
|
| `uat.cjs` | UAT 파일 파싱, 검증 부채 추적, audit-uat 지원 |
|
||||||
|
| `docs.cjs` | 문서 업데이트 워크플로우 초기화, 마크다운 스캔, 모노레포 감지 |
|
||||||
|
| `workstream.cjs` | 워크스트림 CRUD, 마이그레이션, 세션 범위 활성 포인터 |
|
||||||
|
| `schema-detect.cjs` | ORM 패턴에 대한 스키마 드리프트 감지 (Prisma, Drizzle 등) |
|
||||||
|
| `profile-pipeline.cjs` | 사용자 행동 프로파일링 데이터 파이프라인, 세션 파일 스캔 |
|
||||||
|
| `profile-output.cjs` | 프로필 렌더링, USER-PROFILE.md 및 dev-preferences.md 생성 |
|
||||||
|
|
||||||
| 모듈 | 역할 |
|
|
||||||
|--------|---------------|
|
|
||||||
| `core.cjs` | 오류 처리, 출력 포매팅, 공유 유틸리티 |
|
|
||||||
| `state.cjs` | STATE.md 파싱, 업데이트, 진행, 메트릭 |
|
|
||||||
| `phase.cjs` | 단계 디렉터리 작업, 소수 번호 매기기, 계획 인덱싱 |
|
|
||||||
| `roadmap.cjs` | ROADMAP.md 파싱, 단계 추출, 계획 진행 상황 |
|
|
||||||
| `config.cjs` | config.json 읽기/쓰기, 섹션 초기화 |
|
|
||||||
| `verify.cjs` | 계획 구조, 단계 완성도, 참조, 커밋 검증 |
|
|
||||||
| `template.cjs` | 변수 치환을 포함한 템플릿 선택 및 채우기 |
|
|
||||||
| `frontmatter.cjs` | YAML 전문 CRUD 작업 |
|
|
||||||
| `init.cjs` | 각 워크플로우 유형을 위한 복합 컨텍스트 로드 |
|
|
||||||
| `milestone.cjs` | 마일스톤 보관, 요구 사항 표시 |
|
|
||||||
| `commands.cjs` | 기타 명령어 (slug, timestamp, todos, scaffolding, stats) |
|
|
||||||
| `model-profiles.cjs` | 모델 프로필 해석 테이블 |
|
|
||||||
| `security.cjs` | 경로 탐색 방지, 프롬프트 인젝션 감지, 안전한 JSON 파싱, 셸 인수 검증 |
|
|
||||||
| `uat.cjs` | UAT 파일 파싱, 검증 부채 추적, audit-uat 지원 |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -200,65 +293,81 @@ GSD는 사용자와 AI 코딩 에이전트(Claude Code, Gemini CLI, OpenCode, Ki
|
|||||||
### 오케스트레이터 → 에이전트 패턴
|
### 오케스트레이터 → 에이전트 패턴
|
||||||
|
|
||||||
```
|
```
|
||||||
Orchestrator (workflow .md)
|
오케스트레이터 (workflow .md)
|
||||||
│
|
│
|
||||||
├── Load context: gsd-tools.cjs init <workflow> <phase>
|
├── 컨텍스트 로드: gsd-tools.cjs init <workflow> <phase>
|
||||||
│ Returns JSON with: project info, config, state, phase details
|
│ 반환 JSON: 프로젝트 정보, 설정, 상태, 단계 상세
|
||||||
│
|
│
|
||||||
├── Resolve model: gsd-tools.cjs resolve-model <agent-name>
|
├── 모델 해결: gsd-tools.cjs resolve-model <agent-name>
|
||||||
│ Returns: opus | sonnet | haiku | inherit
|
│ 반환: opus | sonnet | haiku | inherit
|
||||||
│
|
│
|
||||||
├── Spawn Agent (Task/SubAgent call)
|
├── 에이전트 생성 (Task/SubAgent 호출)
|
||||||
│ ├── Agent prompt (agents/*.md)
|
│ ├── 에이전트 프롬프트 (agents/*.md)
|
||||||
│ ├── Context payload (init JSON)
|
│ ├── 컨텍스트 페이로드 (init JSON)
|
||||||
│ ├── Model assignment
|
│ ├── 모델 할당
|
||||||
│ └── Tool permissions
|
│ └── 도구 권한
|
||||||
│
|
│
|
||||||
├── Collect result
|
├── 결과 수집
|
||||||
│
|
│
|
||||||
└── Update state: gsd-tools.cjs state update/patch/advance-plan
|
└── 상태 업데이트: gsd-tools.cjs state update / state patch / state advance-plan
|
||||||
```
|
```
|
||||||
|
|
||||||
### 에이전트 생성 카테고리
|
### 주요 에이전트 생성 범주
|
||||||
|
|
||||||
|
21개 주요 에이전트의 개념적 생성 패턴 분류. 권위 있는 31개 에이전트 목록(10개 고급/전문화 에이전트 포함: `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`)은 [`docs/INVENTORY.md`](INVENTORY.md#agents-31-shipped)를 참조하라.
|
||||||
|
|
||||||
|
|
||||||
|
| 범주 | 에이전트 | 병렬성 |
|
||||||
|
| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||||
|
| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4개 병렬 (stack, features, architecture, pitfalls); advisor는 discuss-phase 중 생성됨 |
|
||||||
|
| **Synthesizers** | gsd-research-synthesizer | 순차적 (리서처 완료 후) |
|
||||||
|
| **Planners** | gsd-planner, gsd-roadmapper | 순차적 |
|
||||||
|
| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | 순차적 (검증 루프, 최대 3회 반복) |
|
||||||
|
| **Executors** | gsd-executor | 웨이브 내 병렬, 웨이브 간 순차적 |
|
||||||
|
| **Verifiers** | gsd-verifier | 순차적 (모든 실행기 완료 후) |
|
||||||
|
| **Mappers** | gsd-codebase-mapper | 4개 병렬 (tech, arch, quality, concerns) |
|
||||||
|
| **Debuggers** | gsd-debugger | 순차적 (대화형) |
|
||||||
|
| **Auditors** | gsd-ui-auditor, gsd-security-auditor | 순차적 |
|
||||||
|
| **Doc Writers** | gsd-doc-writer, gsd-doc-verifier | 순차적 (writer 다음 verifier) |
|
||||||
|
| **Profilers** | gsd-user-profiler | 순차적 |
|
||||||
|
| **Analyzers** | gsd-assumptions-analyzer | 순차적 (discuss-phase 중) |
|
||||||
|
|
||||||
| 카테고리 | 에이전트 | 병렬성 |
|
|
||||||
|----------|--------|-------------|
|
|
||||||
| **Researchers** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4개 병렬 (stack, features, architecture, pitfalls); advisor는 discuss-phase 중 생성됨 |
|
|
||||||
| **Synthesizers** | gsd-research-synthesizer | 순차적 (조사자 완료 후) |
|
|
||||||
| **Planners** | gsd-planner, gsd-roadmapper | 순차적 |
|
|
||||||
| **Checkers** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | 순차적 (검증 루프, 최대 3회 반복) |
|
|
||||||
| **Executors** | gsd-executor | 웨이브 내 병렬, 웨이브 간 순차적 |
|
|
||||||
| **Verifiers** | gsd-verifier | 순차적 (모든 executor 완료 후) |
|
|
||||||
| **Mappers** | gsd-codebase-mapper | 4개 병렬 (tech, arch, quality, concerns) |
|
|
||||||
| **Debuggers** | gsd-debugger | 순차적 (대화형) |
|
|
||||||
| **Auditors** | gsd-ui-auditor | 순차적 |
|
|
||||||
|
|
||||||
### 웨이브 실행 모델
|
### 웨이브 실행 모델
|
||||||
|
|
||||||
`execute-phase` 중 계획은 의존성 웨이브로 그룹화됩니다.
|
`execute-phase` 중 계획은 의존성 웨이브로 그룹화된다:
|
||||||
|
|
||||||
```
|
```
|
||||||
Wave Analysis:
|
웨이브 분석:
|
||||||
Plan 01 (no deps) ─┐
|
계획 01 (의존성 없음) ─┐
|
||||||
Plan 02 (no deps) ─┤── Wave 1 (parallel)
|
계획 02 (의존성 없음) ─┤── 웨이브 1 (병렬)
|
||||||
Plan 03 (depends: 01) ─┤── Wave 2 (waits for Wave 1)
|
계획 03 (의존: 01) ─┤── 웨이브 2 (웨이브 1 대기)
|
||||||
Plan 04 (depends: 02) ─┘
|
계획 04 (의존: 02) ─┘
|
||||||
Plan 05 (depends: 03,04) ── Wave 3 (waits for Wave 2)
|
계획 05 (의존: 03,04) ── 웨이브 3 (웨이브 2 대기)
|
||||||
```
|
```
|
||||||
|
|
||||||
각 executor는 다음을 받습니다.
|
각 실행기는 다음을 받는다:
|
||||||
- 새로운 200K 컨텍스트 윈도우
|
|
||||||
|
- 신선한 200K 컨텍스트 윈도우 (또는 지원 모델에서 최대 1M)
|
||||||
- 실행할 특정 PLAN.md
|
- 실행할 특정 PLAN.md
|
||||||
- 프로젝트 컨텍스트 (PROJECT.md, STATE.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를 받아 이력 인식 검증 가능
|
||||||
|
|
||||||
|
오케스트레이터는 config에서 `context_window`를 읽고(`gsd-tools.cjs config-get context_window`) 값이 >= 500,000일 때 조건부로 더 풍부한 컨텍스트를 포함한다. 표준 200K 윈도우에서는 최대 컨텍스트 효율성을 위해 캐시 친화적 순서로 잘린 버전의 프롬프트를 사용한다.
|
||||||
|
|
||||||
#### 병렬 커밋 안전성
|
#### 병렬 커밋 안전성
|
||||||
|
|
||||||
같은 웨이브 내에서 여러 executor가 실행될 때 충돌을 방지하는 두 가지 메커니즘이 있습니다.
|
같은 웨이브 내에서 여러 실행기가 실행될 때 두 가지 메커니즘이 충돌을 방지한다:
|
||||||
|
|
||||||
1. **`--no-verify` 커밋** — 병렬 에이전트는 사전 커밋 훅을 건너뜁니다 (빌드 잠금 경쟁을 유발할 수 있음, 예: Rust 프로젝트의 cargo lock 충돌). 오케스트레이터는 각 웨이브 완료 후 `git hook run pre-commit`을 한 번 실행합니다.
|
1. `--no-verify` 커밋 — 병렬 에이전트는 사전 커밋 훅을 건너뛴다 (빌드 잠금 경합을 유발할 수 있음, 예: Rust 프로젝트의 cargo lock 충돌). 오케스트레이터는 각 웨이브 완료 후 `git hook run pre-commit`을 한 번 실행한다.
|
||||||
|
2. **STATE.md 파일 잠금** — 모든 `writeStateMd()` 호출은 lockfile 기반 상호 배제를 사용한다(`STATE.md.lock`, `O_EXCL` 원자적 생성). 이는 두 에이전트가 STATE.md를 읽고 서로 다른 필드를 수정하면 마지막 작성자가 다른 에이전트의 변경 사항을 덮어쓰는 읽기-수정-쓰기 경합 조건을 방지한다. 오래된 잠금 감지(10초 타임아웃)와 지터를 포함한 스핀 대기가 포함된다.
|
||||||
2. **STATE.md 파일 잠금** — 모든 `writeStateMd()` 호출은 lockfile 기반 상호 배제를 사용합니다 (`STATE.md.lock`, `O_EXCL` 원자적 생성). 이는 두 에이전트가 STATE.md를 읽고 서로 다른 필드를 수정하면 마지막 작성자가 다른 에이전트의 변경사항을 덮어쓰는 읽기-수정-쓰기 경쟁 조건을 방지합니다. 오래된 잠금 감지(10초 타임아웃)와 지터를 포함한 스핀 대기가 포함됩니다.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -267,73 +376,84 @@ Wave Analysis:
|
|||||||
### 새 프로젝트 흐름
|
### 새 프로젝트 흐름
|
||||||
|
|
||||||
```
|
```
|
||||||
User input (idea description)
|
사용자 입력 (아이디어 설명)
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
Questions (questioning.md philosophy)
|
질문 (questioning.md 철학)
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
4x Project Researchers (parallel)
|
4x 프로젝트 리서처 (병렬)
|
||||||
├── Stack → STACK.md
|
├── Stack → STACK.md
|
||||||
├── Features → FEATURES.md
|
├── Features → FEATURES.md
|
||||||
├── Architecture → ARCHITECTURE.md
|
├── Architecture → ARCHITECTURE.md
|
||||||
└── Pitfalls → PITFALLS.md
|
└── Pitfalls → PITFALLS.md
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
Research Synthesizer → SUMMARY.md
|
리서치 합성기 → SUMMARY.md
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
Requirements extraction → REQUIREMENTS.md
|
요구 사항 추출 → REQUIREMENTS.md
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
Roadmapper → ROADMAP.md
|
로드맵퍼 → ROADMAP.md
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
User approval → STATE.md initialized
|
사용자 승인 → STATE.md 초기화
|
||||||
```
|
```
|
||||||
|
|
||||||
### 단계 실행 흐름
|
### 단계 실행 흐름
|
||||||
|
|
||||||
```
|
```
|
||||||
discuss-phase → CONTEXT.md (user preferences)
|
discuss-phase → CONTEXT.md (사용자 선호도)
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
ui-phase → UI-SPEC.md (design contract, optional)
|
ui-phase → UI-SPEC.md (디자인 계약, 선택적)
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
plan-phase
|
plan-phase
|
||||||
├── Phase Researcher → RESEARCH.md
|
├── 리서치 게이트 (RESEARCH.md에 미해결 공개 질문이 있으면 차단)
|
||||||
├── Planner → PLAN.md files
|
├── 단계 리서처 → RESEARCH.md
|
||||||
└── Plan Checker → Verify loop (max 3x)
|
│ └── 패키지 적법성 게이트: 모든 패키지에 slopcheck; [SLOP] 제거,
|
||||||
|
│ [SUS]/[ASSUMED] 플래그; 감사 테이블을 RESEARCH.md에 작성
|
||||||
|
├── 플래너 (도달 가능성 검사 포함) → PLAN.md 파일
|
||||||
|
│ └── [ASSUMED]/[SUS] 설치 전에 checkpoint:human-verify 삽입;
|
||||||
|
│ 설치 포함 계획에 T-{phase}-SC STRIDE 행 추가
|
||||||
|
├── 계획 검사기 → 검증 루프 (최대 3회)
|
||||||
|
├── 요구 사항 커버리지 게이트 (REQ-ID → 계획)
|
||||||
|
└── 결정 커버리지 게이트 (CONTEXT.md `<decisions>` → 계획, 차단 — #2492)
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
execute-phase
|
state planned-phase → STATE.md (계획됨/실행 준비)
|
||||||
├── Wave analysis (dependency grouping)
|
|
||||||
├── Executor per plan → code + atomic commits
|
|
||||||
├── SUMMARY.md per plan
|
|
||||||
└── Verifier → VERIFICATION.md
|
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
verify-work → UAT.md (user acceptance testing)
|
execute-phase (컨텍스트 축소: 잘린 프롬프트, 캐시 친화적 순서)
|
||||||
|
├── 웨이브 분석 (의존성 그룹화)
|
||||||
|
├── 계획당 실행기 → 코드 + 원자적 커밋
|
||||||
|
├── 계획당 SUMMARY.md
|
||||||
|
└── 검증기 → VERIFICATION.md
|
||||||
|
└── 결정 커버리지 게이트 (CONTEXT.md 결정 → 출시된 결과물, 비차단 — #2492)
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
ui-review → UI-REVIEW.md (visual audit, optional)
|
verify-work → UAT.md (사용자 수락 테스트)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
ui-review → UI-REVIEW.md (시각적 감사, 선택적)
|
||||||
```
|
```
|
||||||
|
|
||||||
### 컨텍스트 전파
|
### 컨텍스트 전파
|
||||||
|
|
||||||
각 워크플로우 단계는 이후 단계에 공급되는 아티팩트를 생성합니다.
|
각 워크플로우 단계는 이후 단계에 공급되는 결과물을 생성한다:
|
||||||
|
|
||||||
```
|
```
|
||||||
PROJECT.md ────────────────────────────────────────────► All agents
|
PROJECT.md ────────────────────────────────────────────► 모든 에이전트
|
||||||
REQUIREMENTS.md ───────────────────────────────────────► Planner, Verifier, Auditor
|
REQUIREMENTS.md ───────────────────────────────────────► 플래너, 검증기, 감사기
|
||||||
ROADMAP.md ────────────────────────────────────────────► Orchestrators
|
ROADMAP.md ────────────────────────────────────────────► 오케스트레이터
|
||||||
STATE.md ──────────────────────────────────────────────► All agents (decisions, blockers)
|
STATE.md ──────────────────────────────────────────────► 모든 에이전트 (결정, 차단)
|
||||||
CONTEXT.md (per phase) ────────────────────────────────► Researcher, Planner, Executor
|
CONTEXT.md (단계별) ────────────────────────────────────► 리서처, 플래너, 실행기
|
||||||
RESEARCH.md (per phase) ───────────────────────────────► Planner, Plan Checker
|
RESEARCH.md (단계별) ───────────────────────────────────► 플래너, 계획 검사기
|
||||||
PLAN.md (per plan) ────────────────────────────────────► Executor, Plan Checker
|
PLAN.md (계획별) ────────────────────────────────────────► 실행기, 계획 검사기
|
||||||
SUMMARY.md (per plan) ─────────────────────────────────► Verifier, State tracking
|
SUMMARY.md (계획별) ─────────────────────────────────────► 검증기, 상태 추적
|
||||||
UI-SPEC.md (per phase) ────────────────────────────────► Executor, UI Auditor
|
UI-SPEC.md (단계별) ────────────────────────────────────► 실행기, UI 감사기
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -344,29 +464,37 @@ UI-SPEC.md (per phase) ───────────────────
|
|||||||
|
|
||||||
```
|
```
|
||||||
~/.claude/ # Claude Code (전역 설치)
|
~/.claude/ # Claude Code (전역 설치)
|
||||||
├── commands/gsd/*.md # 37개 슬래시 명령어
|
├── skills/gsd-*/SKILL.md # 전역 스킬 (권위 있는 목록: docs/INVENTORY.md)
|
||||||
|
├── commands/gsd/*.md # 로컬 Claude 설치는 전역 스킬 대신 슬래시 명령어 사용
|
||||||
├── get-shit-done/
|
├── get-shit-done/
|
||||||
│ ├── bin/gsd-tools.cjs # CLI 유틸리티
|
│ ├── bin/gsd-tools.cjs # CLI 유틸리티
|
||||||
│ ├── bin/lib/*.cjs # 15개 도메인 모듈
|
│ ├── bin/lib/*.cjs # 도메인 모듈 (권위 있는 목록: docs/INVENTORY.md)
|
||||||
│ ├── workflows/*.md # 42개 워크플로우 정의
|
│ ├── workflows/*.md # 워크플로우 정의 (권위 있는 목록: docs/INVENTORY.md)
|
||||||
│ ├── references/*.md # 13개 공유 참조 문서
|
│ ├── references/*.md # 공유 레퍼런스 문서 (권위 있는 목록: docs/INVENTORY.md)
|
||||||
│ └── templates/ # 계획 아티팩트 템플릿
|
│ └── templates/ # 계획 결과물 템플릿
|
||||||
├── agents/*.md # 15개 에이전트 정의
|
├── agents/*.md # 에이전트 정의 (권위 있는 목록: docs/INVENTORY.md)
|
||||||
├── hooks/
|
├── hooks/*.js # Node.js 훅 (statusline, guards, monitors, update check)
|
||||||
│ ├── gsd-statusline.js # 상태표시줄 훅
|
├── hooks/*.sh # 쉘 훅 (session state, commit validation, phase boundary)
|
||||||
│ ├── gsd-context-monitor.js # 컨텍스트 경고 훅
|
|
||||||
│ └── gsd-check-update.js # 업데이트 확인 훅
|
|
||||||
├── settings.json # 훅 등록
|
├── settings.json # 훅 등록
|
||||||
└── VERSION # 설치된 버전 번호
|
└── VERSION # 설치된 버전 번호
|
||||||
```
|
```
|
||||||
|
|
||||||
다른 런타임의 동등한 경로입니다.
|
다른 런타임의 동등한 경로:
|
||||||
- **OpenCode:** `~/.config/opencode/` 또는 `~/.opencode/`
|
|
||||||
- **Kilo:** `~/.config/kilo/` 또는 `~/.kilo/`
|
- **OpenCode:** `~/.config/opencode/` 전역 또는 `./.opencode/` 로컬
|
||||||
- **Gemini CLI:** `~/.gemini/`
|
- **Kilo:** `~/.config/kilo/` 전역 또는 `./.kilo/` 로컬
|
||||||
- **Codex:** `~/.codex/` (명령어 대신 skills 사용)
|
- **Gemini CLI:** `~/.gemini/` 전역 또는 `./.gemini/` 로컬
|
||||||
- **Copilot:** `~/.github/`
|
- **Codex:** `~/.codex/` 전역 또는 `./.codex/` 로컬
|
||||||
- **Antigravity:** `~/.gemini/antigravity/` (전역) 또는 `./.agent/` (로컬)
|
- **Copilot:** `~/.copilot/` 전역 또는 `./.github/` 로컬
|
||||||
|
- **Antigravity:** 자동 감지된 전역 루트 (`~/.gemini/antigravity/`, `~/.gemini/antigravity-ide/`, 또는 `~/.gemini/antigravity-cli/`) 또는 `./.agent/` 로컬
|
||||||
|
- **Cursor:** `~/.cursor/` 전역 또는 `./.cursor/` 로컬
|
||||||
|
- **Windsurf:** `~/.codeium/windsurf/` 전역 또는 `./.windsurf/` 로컬
|
||||||
|
- **Augment Code:** `~/.augment/` 전역 또는 `./.augment/` 로컬
|
||||||
|
- **Trae:** `~/.trae/` 전역 또는 `./.trae/` 로컬
|
||||||
|
- **Qwen Code:** `~/.qwen/` 전역 또는 `./.qwen/` 로컬
|
||||||
|
- **Hermes Agent:** `~/.hermes/` 전역 또는 `./.hermes/` 로컬
|
||||||
|
- **CodeBuddy:** `~/.codebuddy/` 전역 또는 `./.codebuddy/` 로컬
|
||||||
|
- **Cline:** `~/.cline/` 전역 또는 프로젝트 루트 `.clinerules` 로컬
|
||||||
|
|
||||||
### 프로젝트 파일 (`.planning/`)
|
### 프로젝트 파일 (`.planning/`)
|
||||||
|
|
||||||
@@ -378,15 +506,15 @@ UI-SPEC.md (per phase) ───────────────────
|
|||||||
├── STATE.md # 살아있는 메모리: 위치, 결정, 차단, 메트릭
|
├── STATE.md # 살아있는 메모리: 위치, 결정, 차단, 메트릭
|
||||||
├── config.json # 워크플로우 설정
|
├── config.json # 워크플로우 설정
|
||||||
├── MILESTONES.md # 완료된 마일스톤 보관
|
├── MILESTONES.md # 완료된 마일스톤 보관
|
||||||
├── research/ # /gsd-new-project의 도메인 조사
|
├── research/ # /gsd-new-project의 도메인 리서치
|
||||||
│ ├── SUMMARY.md
|
│ ├── SUMMARY.md
|
||||||
│ ├── STACK.md
|
│ ├── STACK.md
|
||||||
│ ├── FEATURES.md
|
│ ├── FEATURES.md
|
||||||
│ ├── ARCHITECTURE.md
|
│ ├── ARCHITECTURE.md
|
||||||
│ └── PITFALLS.md
|
│ └── PITFALLS.md
|
||||||
├── codebase/ # 브라운필드 매핑 (/gsd-map-codebase에서)
|
├── codebase/ # 브라운필드 매핑 (/gsd-map-codebase에서)
|
||||||
│ ├── STACK.md
|
│ ├── STACK.md # YAML 전문에 `last_mapped_commit` 포함
|
||||||
│ ├── ARCHITECTURE.md
|
│ ├── ARCHITECTURE.md # 실행 후 드리프트 게이트를 위한 (#2003)
|
||||||
│ ├── CONVENTIONS.md
|
│ ├── CONVENTIONS.md
|
||||||
│ ├── CONCERNS.md
|
│ ├── CONCERNS.md
|
||||||
│ ├── STRUCTURE.md
|
│ ├── STRUCTURE.md
|
||||||
@@ -395,14 +523,14 @@ UI-SPEC.md (per phase) ───────────────────
|
|||||||
├── phases/
|
├── phases/
|
||||||
│ └── XX-phase-name/
|
│ └── XX-phase-name/
|
||||||
│ ├── XX-CONTEXT.md # 사용자 선호도 (discuss-phase에서)
|
│ ├── XX-CONTEXT.md # 사용자 선호도 (discuss-phase에서)
|
||||||
│ ├── XX-RESEARCH.md # 생태계 조사 (plan-phase에서)
|
│ ├── XX-RESEARCH.md # 생태계 리서치 (plan-phase에서)
|
||||||
│ ├── XX-YY-PLAN.md # 실행 계획
|
│ ├── XX-YY-PLAN.md # 실행 계획
|
||||||
│ ├── XX-YY-SUMMARY.md # 실행 결과
|
│ ├── XX-YY-SUMMARY.md # 실행 결과
|
||||||
│ ├── XX-VERIFICATION.md # 실행 후 검증
|
│ ├── XX-VERIFICATION.md # 실행 후 검증
|
||||||
│ ├── XX-VALIDATION.md # Nyquist 테스트 커버리지 매핑
|
│ ├── XX-VALIDATION.md # Nyquist 테스트 커버리지 매핑
|
||||||
│ ├── XX-UI-SPEC.md # UI 디자인 계약서 (ui-phase에서)
|
│ ├── XX-UI-SPEC.md # UI 디자인 계약 (ui-phase에서)
|
||||||
│ ├── XX-UI-REVIEW.md # 시각적 감사 점수 (ui-review에서)
|
│ ├── XX-UI-REVIEW.md # 시각적 감사 점수 (ui-review에서)
|
||||||
│ └── XX-UAT.md # 사용자 수용 테스트 결과
|
│ └── XX-UAT.md # 사용자 수락 테스트 결과
|
||||||
├── quick/ # 빠른 작업 추적
|
├── quick/ # 빠른 작업 추적
|
||||||
│ └── YYMMDD-xxx-slug/
|
│ └── YYMMDD-xxx-slug/
|
||||||
│ ├── PLAN.md
|
│ ├── PLAN.md
|
||||||
@@ -420,34 +548,60 @@ UI-SPEC.md (per phase) ───────────────────
|
|||||||
└── continue-here.md # 컨텍스트 핸드오프 (pause-work에서)
|
└── continue-here.md # 컨텍스트 핸드오프 (pause-work에서)
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 실행 후 코드베이스 드리프트 게이트 (#2003)
|
||||||
|
|
||||||
|
`/gsd-execute-phase` 마지막 웨이브 커밋 후, 워크플로우는 비차단 `codebase_drift_gate` 단계를 실행한다(`schema_drift_gate`와 `verify_phase_goal` 사이). `last_mapped_commit..HEAD` diff를 `.planning/codebase/STRUCTURE.md`와 비교하고 네 종류의 구조적 요소를 집계한다:
|
||||||
|
|
||||||
|
1. 매핑된 경로 외부의 새 디렉터리
|
||||||
|
2. `(packages|apps)/<name>/src/index.*`의 새 배럴 내보내기
|
||||||
|
3. 새 마이그레이션 파일
|
||||||
|
4. `routes/` 또는 `api/` 하위의 새 라우트 모듈
|
||||||
|
|
||||||
|
집계가 `workflow.drift_threshold`(기본값 3)를 충족하면, 게이트는 제안된 `/gsd-map-codebase --paths …` 명령어와 함께 **경고**하거나(기본값), `gsd-codebase-mapper`를 영향받은 경로로 범위 지정하여 생성함으로써 **자동 재매핑**한다(`workflow.drift_action = auto-remap`). 감지 또는 재매핑의 오류는 로그되고 단계는 계속된다 — 드리프트 감지는 검증을 실패시킬 수 없다.
|
||||||
|
|
||||||
|
`last_mapped_commit`는 각 `.planning/codebase/*.md` 파일 상단의 YAML 전문에 있다; `bin/lib/drift.cjs`는 `readMappedCommit`와 `writeMappedCommit` 왕복 헬퍼를 제공한다.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 인스톨러 아키텍처
|
## 인스톨러 아키텍처
|
||||||
|
|
||||||
인스톨러(`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`)
|
2. **위치 선택** — 전역(`--global`) 또는 로컬(`--local`)
|
||||||
3. **파일 배포** — commands, workflows, references, templates, agents, hooks 복사
|
3. **파일 배포** — commands, skills, workflows, references, templates, agents, hooks 복사
|
||||||
4. **런타임 적응** — 런타임별 파일 내용 변환.
|
4. **런타임 적응** — 런타임별 파일 내용 변환:
|
||||||
- Claude Code: 그대로 사용
|
- Claude Code: 그대로 사용
|
||||||
- OpenCode: 명령어/에이전트를 OpenCode 호환 플랫 명령어 + 서브에이전트 형식으로 변환
|
- OpenCode: 명령어/에이전트를 OpenCode 호환 플랫 명령어 + 서브에이전트 형식으로 변환
|
||||||
- Kilo: Kilo 설정 경로로 OpenCode 변환 파이프라인을 재사용
|
- Kilo: Kilo 설정 경로로 OpenCode 변환 파이프라인 재사용
|
||||||
- Codex: commands에서 TOML config + skills 생성
|
- Codex: commands에서 TOML config + skills 생성
|
||||||
- Copilot: 도구 이름 매핑 (Read→read, Bash→execute 등)
|
- Copilot: 도구 이름 매핑 (Read→read, Bash→execute 등)
|
||||||
- Gemini: 훅 이벤트 이름 조정 (`PostToolUse` 대신 `AfterTool`)
|
- Gemini: 훅 이벤트 이름 조정 (`PostToolUse` 대신 `AfterTool`)
|
||||||
- Antigravity: Google 모델 등가물을 사용한 skills-first 방식
|
- Antigravity: Google 모델 등가물을 사용한 skills-first
|
||||||
|
- Cursor: Cursor 규칙 참조를 사용한 skills-first
|
||||||
|
- Windsurf: Windsurf 규칙 참조를 사용한 skills-first
|
||||||
|
- Trae: `settings.json` 또는 훅 통합 없이 `~/.trae` / `./.trae`에 skills-first 설치
|
||||||
|
- Qwen Code: Qwen 브랜드 경로 및 프롬프트 재작성을 사용한 skills-first
|
||||||
|
- Hermes Agent: `skills/gsd/` 하의 범주 기반 스킬
|
||||||
|
- CodeBuddy: CodeBuddy 경로 및 프롬프트 재작성을 사용한 skills-first
|
||||||
|
- Cline: 규칙 기반 통합을 위한 `.clinerules` 작성
|
||||||
|
- Augment Code: 전체 스킬 변환 및 설정 관리를 사용한 skills-first
|
||||||
5. **경로 정규화** — `~/.claude/` 경로를 런타임별 경로로 교체
|
5. **경로 정규화** — `~/.claude/` 경로를 런타임별 경로로 교체
|
||||||
6. **설정 통합** — 런타임의 `settings.json`에 훅 등록
|
6. **설정 통합** — 런타임의 `settings.json`에 훅 등록
|
||||||
7. **패치 백업** — v1.17부터 로컬 수정 파일을 `gsd-local-patches/`에 백업하여 `/gsd-update --reapply`에 사용
|
7. **패치 백업** — v1.17부터 로컬 수정 파일을 `gsd-local-patches/`에 백업하여 `/gsd-update --reapply`에 사용
|
||||||
8. **매니페스트 추적** — 깔끔한 제거를 위해 `gsd-file-manifest.json` 작성
|
8. **매니페스트 추적** — 깔끔한 제거를 위해 `gsd-file-manifest.json` 작성
|
||||||
9. **제거 모드** — `--uninstall`로 모든 GSD 파일, 훅, 설정 제거
|
9. **제거 모드** — `--uninstall`로 모든 GSD 파일, 훅, 설정 제거
|
||||||
|
|
||||||
|
설치 시 파일 이동, 오래된 결과물 정리, 설정 재작성, 사용자 데이터 보존은 인스톨러 마이그레이션 모듈이 관리한다. [인스톨러 마이그레이션](../installer-migrations.md)과 [ADR 0008](../adr/0008-installer-migration-module.md)을 참조하라.
|
||||||
|
마이그레이션 모듈은 레거시 설치에 대한 게이트된 최초 기준선 스캔도 소유하며, 이후 마이그레이션이 무언가를 제거하거나 재작성하기 전에 알려진 런타임 설치 표면을 분류한다.
|
||||||
|
|
||||||
|
계획 드리프트 가드(`plan_review.source_grounding`) — 실행 전에 생성된 계획에서 심볼 참조를 라이브 소스에 대해 검증하는 — 는 [ADR 22](../adr/22-plan-drift-guard.md)에 명시되어 있다.
|
||||||
|
|
||||||
### 플랫폼 처리
|
### 플랫폼 처리
|
||||||
|
|
||||||
- **Windows:** 자식 프로세스에 `windowsHide` 적용, 보호 디렉터리의 EPERM/EACCES 방지, 경로 구분자 정규화
|
- **Windows:** 자식 프로세스에 `windowsHide`, 보호 디렉터리에 EPERM/EACCES 방지, 경로 구분자 정규화
|
||||||
- **WSL:** WSL에서 실행 중인 Windows Node.js를 감지하고 경로 불일치에 대해 경고
|
- **WSL:** WSL에서 실행 중인 Windows Node.js 감지 및 경로 불일치 경고
|
||||||
- **Docker/CI:** 커스텀 config 디렉터리 위치를 위한 `CLAUDE_CONFIG_DIR` 환경 변수 지원
|
- **Docker/CI:** 커스텀 설정 디렉터리 위치를 위한 `CLAUDE_CONFIG_DIR` 환경 변수 지원
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -456,75 +610,138 @@ UI-SPEC.md (per phase) ───────────────────
|
|||||||
### 아키텍처
|
### 아키텍처
|
||||||
|
|
||||||
```
|
```
|
||||||
Runtime Engine (Claude Code / Gemini CLI)
|
런타임 엔진 (Claude Code / Gemini CLI)
|
||||||
│
|
│
|
||||||
├── statusLine event ──► gsd-statusline.js
|
├── statusLine 이벤트 ──► gsd-statusline.js
|
||||||
│ Reads: stdin (session JSON)
|
│ 읽기: stdin (세션 JSON)
|
||||||
│ Writes: stdout (formatted status), /tmp/claude-ctx-{session}.json (bridge)
|
│ 쓰기: stdout (형식화된 상태), /tmp/claude-ctx-{session}.json (브리지)
|
||||||
│
|
│
|
||||||
├── PostToolUse/AfterTool event ──► gsd-context-monitor.js
|
├── PostToolUse/AfterTool 이벤트 ──► gsd-context-monitor.js
|
||||||
│ Reads: stdin (tool event JSON), /tmp/claude-ctx-{session}.json (bridge)
|
│ 읽기: stdin (도구 이벤트 JSON), /tmp/claude-ctx-{session}.json (브리지)
|
||||||
│ Writes: stdout (hookSpecificOutput with additionalContext warning)
|
│ 쓰기: stdout (additionalContext 경고가 있는 hookSpecificOutput)
|
||||||
│
|
│
|
||||||
└── SessionStart event ──► gsd-check-update.js
|
└── SessionStart 이벤트 ──► gsd-check-update.js
|
||||||
Reads: VERSION file
|
읽기: VERSION 파일
|
||||||
Writes: ~/.claude/cache/gsd-update-check.json (spawns background process)
|
쓰기: ~/.claude/cache/gsd-update-check.json (백그라운드 프로세스 생성)
|
||||||
```
|
```
|
||||||
|
|
||||||
### 컨텍스트 모니터 임계값
|
### 컨텍스트 모니터 임계값
|
||||||
|
|
||||||
| 잔여 컨텍스트 | 수준 | 에이전트 동작 |
|
|
||||||
|-------------------|-------|----------------|
|
|
||||||
| > 35% | 정상 | 경고 주입 없음 |
|
|
||||||
| ≤ 35% | WARNING | "복잡한 새 작업 시작을 피하세요" |
|
|
||||||
| ≤ 25% | CRITICAL | "컨텍스트가 거의 소진됨, 사용자에게 알리세요" |
|
|
||||||
|
|
||||||
디바운스: 반복 경고 사이에 5회 도구 사용. 심각도 에스컬레이션(WARNING→CRITICAL)은 디바운스를 우회합니다.
|
| 잔여 컨텍스트 | 수준 | 에이전트 동작 |
|
||||||
|
| ----------------- | -------- | --------------------------------------- |
|
||||||
|
| > 35% | 정상 | 경고 주입 없음 |
|
||||||
|
| ≤ 35% | WARNING | "복잡한 새 작업 시작 금지" |
|
||||||
|
| ≤ 25% | CRITICAL | "컨텍스트 거의 소진됨, 사용자에게 알릴 것" |
|
||||||
|
|
||||||
|
|
||||||
|
디바운스: 반복 경고 사이에 5번의 도구 사용. 심각도 에스컬레이션(WARNING→CRITICAL)은 디바운스를 우회한다.
|
||||||
|
|
||||||
### 안전 속성
|
### 안전 속성
|
||||||
|
|
||||||
- 모든 훅은 try/catch로 감싸여 있으며 오류 시 자동 종료합니다
|
- 모든 훅은 try/catch로 감싸이며 오류 시 자동 종료한다
|
||||||
- stdin 타임아웃 가드(3초)로 파이프 문제 시 중단 방지
|
- stdin 타임아웃 가드(3초)로 파이프 문제 시 중단 방지
|
||||||
- 오래된 메트릭(60초 이상)은 무시됩니다
|
- 오래된 메트릭(60초 이상)은 무시된다
|
||||||
- 누락된 브리지 파일은 정상적으로 처리됩니다 (서브에이전트, 새 세션)
|
- 누락된 브리지 파일은 정상적으로 처리된다 (서브에이전트, 새 세션)
|
||||||
- 컨텍스트 모니터는 권고용입니다 — 사용자 선호도를 재정의하는 명령을 내리지 않습니다
|
- 컨텍스트 모니터는 자문적이다 — 사용자 선호도를 재정의하는 명령적 명령을 내리지 않는다
|
||||||
|
|
||||||
|
### 패키지 적법성 게이트 (v1.42.1)
|
||||||
|
|
||||||
|
리서처 → 플래너 → 실행기 파이프라인은 슬롭스쿼팅(악의적인 설치 후 스크립트와 함께 선점 등록된 AI 환각 패키지 이름)에 대한 공급망 게이트를 포함한다.
|
||||||
|
|
||||||
|
**위협 모델:** GSD는 "리서처가 패키지를 명명"에서 "실행기가 `npm install`을 실행"까지의 전체 경로를 자동화한다. `npm view`를 통과하는 환각된 이름(등록만 증명, 적법성은 아님)은 이전에는 감지되지 않고 흘러갔을 것이다. AI가 생성한 패키지 참조의 ~20%가 환각되며; 그 이름의 ~43%가 프롬프트 전반에 걸쳐 일관되게 반복되어 선점 등록이 공격자에게 경제적으로 실현 가능하다.
|
||||||
|
|
||||||
|
**게이트 계층:**
|
||||||
|
|
||||||
|
| 계층 | 컴포넌트 | 동작 |
|
||||||
|
|-------|-----------|--------|
|
||||||
|
| 리서치 | `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은 패키지 설치를 자동 수정 범위에서 제외; 실패한 설치는 체크포인트로 표시되며 절대 자동 대체하지 않음 |
|
||||||
|
|
||||||
|
**클레임 출처 통합:** WebSearch를 통해 발견된 패키지 이름은 `npm view` 결과와 관계없이 `[ASSUMED]`(not `[VERIFIED]`)로 태그된다. 이는 설치 경계에서 출처 태그를 하드 게이트로 시행하여 기존 `[ASSUMED]` / `[VERIFIED]` / `[CITED]` 출처 시스템을 확장한다 — `[ASSUMED]`는 항상 PLAN.md에 `checkpoint:human-verify`를 생성한다.
|
||||||
|
|
||||||
|
**생태계 커버리지:** 리서처는 단일 일반 검사 대신 레지스트리별 검증 명령을 사용한다 — `npm view` (Node), `pip index versions` (Python), `cargo search` (Rust). 이는 2025년 USENIX 연구에 문서화된 ~9% 비율의 교차 생태계 환각을 잡는다.
|
||||||
|
|
||||||
|
**정상적인 성능 저하:** `slopcheck`를 사용할 수 없으면 모든 추천 패키지가 `[ASSUMED]`로 태그되고 체크포인트로 게이트가 걸린다. 리서치와 계획은 진행된다; 시스템은 누락된 도구 의존성으로 인해 절대 하드 실패하지 않는다.
|
||||||
|
|
||||||
|
**외부 의존성:** `slopcheck` (MIT, pip 설치 가능). 유지 관리가 중단되면 `[ASSUMED]`-게이트 폴백이 사람 체크포인트 커버리지를 유지한다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
### 보안 훅 (v1.27)
|
### 보안 훅 (v1.27)
|
||||||
|
|
||||||
**Prompt Guard** (`gsd-prompt-guard.js`).
|
훅과 가드 계층이 더 광범위한 보안 접근 방식에 어떻게 맞는지에 대한 개념적 개요는 [보안 모델](explanation/security-model.md)을 참조하라.
|
||||||
- `.planning/` 파일에 Write/Edit 시 트리거됩니다
|
|
||||||
- 프롬프트 인젝션 패턴을 콘텐츠에서 스캔합니다 (역할 재정의, 지시 우회, system 태그 인젝션)
|
|
||||||
- 권고용 — 감지를 기록하며 차단하지 않습니다
|
|
||||||
- 패턴은 훅 독립성을 위해 인라인으로 포함됩니다 (`security.cjs`의 일부)
|
|
||||||
|
|
||||||
**Workflow Guard** (`gsd-workflow-guard.js`).
|
**Prompt Guard** (`gsd-prompt-guard.js`):
|
||||||
- `.planning/` 외부 파일에 Write/Edit 시 트리거됩니다
|
|
||||||
- GSD 워크플로우 컨텍스트 외부의 편집을 감지합니다 (활성 `/gsd-` 명령어 또는 Task 서브에이전트 없음)
|
- `.planning/` 파일에 Write/Edit 시 트리거
|
||||||
- 상태 추적 변경을 위해 `/gsd-quick` 또는 `/gsd-fast` 사용을 권고합니다
|
- 프롬프트 인젝션 패턴 스캔 (역할 재정의, 지시 우회, system 태그 인젝션)
|
||||||
- `hooks.workflow_guard: true`로 활성화 (기본값: false)
|
- 자문적 전용 — 탐지를 로그하며 차단하지 않음
|
||||||
|
- 패턴은 훅 독립성을 위해 인라인으로 포함됨 (`security.cjs`의 하위 집합)
|
||||||
|
|
||||||
|
**Workflow Guard** (`gsd-workflow-guard.js`):
|
||||||
|
|
||||||
|
- `.planning/` 외부 파일에 Write/Edit 시 트리거
|
||||||
|
- GSD 워크플로우 컨텍스트 외부의 편집 감지 (활성 `/gsd-` 명령어 또는 Task 서브에이전트 없음)
|
||||||
|
- 상태 추적 변경을 위해 `/gsd-quick` 또는 `/gsd-fast` 사용 권고
|
||||||
|
- `hooks.workflow_guard: true`를 통한 옵트인 (기본값: false)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 런타임 추상화
|
## 런타임 추상화
|
||||||
|
|
||||||
GSD는 통합된 명령어/워크플로우 아키텍처를 통해 여러 AI 코딩 런타임을 지원합니다.
|
GSD는 통합된 명령어/워크플로우 아키텍처를 통해 여러 AI 코딩 런타임을 지원한다.
|
||||||
|
|
||||||
| 런타임 | 명령어 형식 | 에이전트 시스템 | 설정 위치 |
|
### 런타임 설치 계약 매트릭스
|
||||||
|---------|---------------|--------------|-----------------|
|
|
||||||
| Claude Code | `/gsd-command` | Task 생성 | `~/.claude/` |
|
이 매트릭스는 인스톨러가 오늘 구체화하는 런타임 표면을 설명한다.
|
||||||
| OpenCode | `/gsd-command` | Subagent 모드 | `~/.config/opencode/` |
|
마이그레이션별 소유권과 소스 스냅샷은 [인스톨러 마이그레이션](../installer-migrations.md#runtime-configuration-contract-registry)에 있다.
|
||||||
| Kilo | `/gsd-command` | Subagent 모드 | `~/.config/kilo/` |
|
|
||||||
| Gemini CLI | `/gsd-command` | Task 생성 | `~/.gemini/` |
|
| 런타임 | 전역 루트 | 로컬 루트 | 호출 표면 | 에이전트 표면 | 설정 및 훅 |
|
||||||
| Codex | `$gsd-command` | Skills | `~/.codex/` |
|
| --- | --- | --- | --- | --- | --- |
|
||||||
| Copilot | `/gsd-command` | 에이전트 위임 | `~/.github/` |
|
| Claude Code | `~/.claude` | `./.claude` | 전역 `skills/gsd-*/SKILL.md`; 로컬 `commands/gsd/*.md` | `agents/gsd-*.md` | `settings.json` 훅 및 statusLine 항목 |
|
||||||
| Antigravity | Skills | Skills | `~/.gemini/antigravity/` |
|
| 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` | `agents/` 소스 마크다운 + 에이전트별 TOML | `config.toml` `[agents.gsd-*]`, `[features].hooks` (정규; 레거시 별칭 `codex_hooks`는 인식되며 재설치 시 마이그레이션됨, #3566), 훅 테이블 |
|
||||||
|
| GitHub Copilot | `~/.copilot` | `./.github` | `skills/gsd-*/SKILL.md` 및 `copilot-instructions.md` | `.agent.md` 파일 | GSD 훅 또는 statusline 없음 |
|
||||||
|
| Antigravity | 자동 감지: `~/.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` | 프로젝트 루트 | `.clinerules` | 규칙만 | GSD 훅 또는 statusline 없음 |
|
||||||
|
|
||||||
|
### 업스트림 계약 소스
|
||||||
|
|
||||||
|
런타임 설치 기대는 가용한 경우 기본 문서에 대해 확인된다. 현재 소스 스냅샷은 2026-05-11:
|
||||||
|
|
||||||
|
- Claude Code: Anthropic 슬래시 명령어, 설정, 훅, 서브에이전트 문서.
|
||||||
|
- OpenCode 및 Kilo: OpenCode 설정 문서 및 Kilo 커스텀 서브에이전트 문서.
|
||||||
|
- Gemini CLI 및 Qwen Code: 명령어/설정 문서; Qwen 명령어 문서는 2026-05-06에 마지막으로 업데이트됨.
|
||||||
|
- Codex: OpenAI Codex 문서 및 `config-schema.json`; 인스톨러는 에이전트 테이블 형태를 위한 Codex 0.124.0 호환성도 포함.
|
||||||
|
- Copilot, Cursor, Cline, Augment, Hermes, CodeBuddy: 커스텀 지시, 규칙, 스킬, 설정을 위한 벤더 문서.
|
||||||
|
- Antigravity, Windsurf, Trae: 소스가 제한된 행. 인스톨러는 현재 호환성 심을 문서화하며, 마이그레이션은 설정을 재작성하기 전에 해당 소스를 새로 고쳐야 한다.
|
||||||
|
|
||||||
### 추상화 포인트
|
### 추상화 포인트
|
||||||
|
|
||||||
1. **도구 이름 매핑** — 각 런타임은 고유한 도구 이름을 가집니다 (예: Claude의 `Bash` → Copilot의 `execute`)
|
1. **도구 이름 매핑** — 각 런타임은 고유한 도구 이름을 가진다 (예: Claude의 `Bash` → Copilot의 `execute`)
|
||||||
2. **훅 이벤트 이름** — Claude는 `PostToolUse`를 사용하고 Gemini는 `AfterTool`을 사용합니다
|
2. **훅 이벤트 이름** — Claude는 `PostToolUse`를 사용하고 Gemini는 `AfterTool`을 사용한다
|
||||||
3. **에이전트 전문** — 각 런타임은 고유한 에이전트 정의 형식을 가집니다
|
3. **에이전트 전문** — 각 런타임은 고유한 에이전트 정의 형식을 가진다
|
||||||
4. **경로 규칙** — 각 런타임은 서로 다른 디렉터리에 설정을 저장합니다
|
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)
|
||||||
|
|||||||
@@ -1,38 +1,48 @@
|
|||||||
# GSD CLI 도구 레퍼런스
|
# GSD CLI 도구 참조
|
||||||
|
|
||||||
> `gsd-tools.cjs`에 대한 프로그래밍 방식 API 레퍼런스입니다. 워크플로우와 에이전트가 내부적으로 사용합니다. 사용자 대면 명령어는 [Command Reference](COMMANDS.md)를 참조하세요.
|
> `gsd-tools` CLI(`get-shit-done/bin/gsd-tools.cjs`)에 대한 참조입니다. 슬래시 명령 및 사용자 흐름은 [명령 참조](COMMANDS.md)를 확인하세요. [문서 인덱스](README.md)로 돌아가기.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 개요
|
## 개요
|
||||||
|
|
||||||
`gsd-tools.cjs`는 GSD의 약 50개 명령어, 워크플로우, 에이전트 파일에서 반복되는 인라인 bash 패턴을 대체하는 Node.js CLI 유틸리티입니다. config 파싱, 모델 해석, 단계 조회, git 커밋, 요약 검증, 상태 관리, 템플릿 작업을 중앙화합니다.
|
`gsd-tools.cjs`는 GSD 명령, 워크플로우, 에이전트 전반에 걸쳐 설정 파싱, 모델 해석, 단계 조회, git 커밋, 요약 검증, 상태 관리, 템플릿 작업을 중앙에서 처리합니다.
|
||||||
|
|
||||||
**위치:** `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
|
```bash
|
||||||
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
|
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
|
||||||
```
|
```
|
||||||
|
|
||||||
**전역 플래그.**
|
**전역 플래그 (CJS):**
|
||||||
| 플래그 | 설명 |
|
|
||||||
|------|-------------|
|
|
||||||
| `--raw` | 기계 가독형 출력 (JSON 또는 일반 텍스트, 포매팅 없음) |
|
| 플래그 | 설명 |
|
||||||
| `--cwd <path>` | 작업 디렉터리 재정의 (샌드박스 서브에이전트용) |
|
| -------------- | ---------------------------------------------------------------------------- |
|
||||||
|
| `--raw` | 기계 판독 가능한 출력 (JSON 또는 일반 텍스트, 서식 없음) |
|
||||||
|
| `--cwd <path>` | 작업 디렉토리 재정의 (샌드박스된 서브에이전트용) |
|
||||||
|
| `--ws <name>` | `.planning/workstreams/<name>` 경로에 대한 워크스트림 컨텍스트 |
|
||||||
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## State 명령어
|
## 상태 명령
|
||||||
|
|
||||||
`.planning/STATE.md`를 관리합니다 — 프로젝트의 살아있는 메모리입니다.
|
`.planning/STATE.md` — 프로젝트의 살아있는 메모리를 관리합니다.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 전체 프로젝트 config + state를 JSON으로 로드
|
# 전체 프로젝트 설정 + 상태를 JSON으로 불러오기
|
||||||
node gsd-tools.cjs state load
|
node gsd-tools.cjs state load
|
||||||
|
|
||||||
# STATE.md 전문을 JSON으로 출력
|
# STATE.md 프론트매터를 JSON으로 출력
|
||||||
node gsd-tools.cjs state json
|
node gsd-tools.cjs state json
|
||||||
|
|
||||||
# 단일 필드 업데이트
|
# 단일 필드 업데이트
|
||||||
@@ -41,7 +51,7 @@ node gsd-tools.cjs state update <field> <value>
|
|||||||
# STATE.md 내용 또는 특정 섹션 가져오기
|
# STATE.md 내용 또는 특정 섹션 가져오기
|
||||||
node gsd-tools.cjs state get [section]
|
node gsd-tools.cjs state get [section]
|
||||||
|
|
||||||
# 여러 필드를 일괄 업데이트
|
# 여러 필드 일괄 업데이트
|
||||||
node gsd-tools.cjs state patch --field1 val1 --field2 val2
|
node gsd-tools.cjs state patch --field1 val1 --field2 val2
|
||||||
|
|
||||||
# 계획 카운터 증가
|
# 계획 카운터 증가
|
||||||
@@ -53,66 +63,73 @@ node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tas
|
|||||||
# 진행률 바 재계산
|
# 진행률 바 재계산
|
||||||
node gsd-tools.cjs state update-progress
|
node gsd-tools.cjs state update-progress
|
||||||
|
|
||||||
# 결정 추가
|
# 결정 사항 추가
|
||||||
node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."]
|
node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."]
|
||||||
# 또는 파일에서:
|
# 또는 파일에서:
|
||||||
node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path]
|
node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path]
|
||||||
|
|
||||||
# 차단 항목 추가/해결
|
# 차단 항목 추가/해제
|
||||||
node gsd-tools.cjs state add-blocker --text "..."
|
node gsd-tools.cjs state add-blocker --text "..."
|
||||||
node gsd-tools.cjs state resolve-blocker --text "..."
|
node gsd-tools.cjs state resolve-blocker --text "..."
|
||||||
|
|
||||||
# 세션 연속성 기록
|
# 세션 연속성 기록
|
||||||
node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path]
|
node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path]
|
||||||
|
|
||||||
|
# 단계 시작 — 새로운 단계의 STATE.md 상태/최근 활동 업데이트
|
||||||
|
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 Snapshot
|
### 상태 스냅샷
|
||||||
|
|
||||||
전체 STATE.md의 구조화된 파싱 결과입니다.
|
전체 STATE.md의 구조화된 파싱:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
node gsd-tools.cjs state-snapshot
|
node gsd-tools.cjs state-snapshot
|
||||||
```
|
```
|
||||||
|
|
||||||
현재 위치, 단계, 계획, 상태, 결정, 차단, 메트릭, 최근 활동을 포함한 JSON을 반환합니다.
|
반환 JSON 포함 항목: 현재 위치, 단계, 계획, 상태, 결정 사항, 차단 항목, 메트릭, 최근 활동.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Phase 명령어
|
## 단계 명령
|
||||||
|
|
||||||
단계를 관리합니다 — 디렉터리, 번호 매기기, 로드맵 동기화.
|
단계 — 디렉토리, 번호 지정, 로드맵 동기화를 관리합니다.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 번호로 단계 디렉터리 찾기
|
# 번호로 단계 디렉토리 찾기
|
||||||
node gsd-tools.cjs find-phase <phase>
|
node gsd-tools.cjs find-phase <phase>
|
||||||
|
|
||||||
# 삽입을 위한 다음 소수 단계 번호 계산
|
# 삽입을 위한 다음 소수점 단계 번호 계산
|
||||||
node gsd-tools.cjs phase next-decimal <phase>
|
node gsd-tools.cjs phase next-decimal <phase>
|
||||||
|
|
||||||
# 로드맵에 새 단계 추가 + 디렉터리 생성
|
# 로드맵에 새 단계 추가 + 디렉토리 생성
|
||||||
node gsd-tools.cjs phase add <description>
|
node gsd-tools.cjs phase add <description>
|
||||||
|
|
||||||
# 기존 단계 이후에 소수 단계 삽입
|
# 기존 단계 뒤에 소수점 단계 삽입
|
||||||
node gsd-tools.cjs phase insert <after> <description>
|
node gsd-tools.cjs phase insert <after> <description>
|
||||||
|
|
||||||
# 단계 제거, 이후 단계 재번호 매기기
|
# 단계 제거, 이후 번호 재지정
|
||||||
node gsd-tools.cjs phase remove <phase> [--force]
|
node gsd-tools.cjs phase remove <phase> [--force]
|
||||||
|
|
||||||
# 단계 완료 표시, state + roadmap 업데이트
|
# 단계 완료 표시, 상태 + 로드맵 업데이트
|
||||||
node gsd-tools.cjs phase complete <phase>
|
node gsd-tools.cjs phase complete <phase>
|
||||||
|
|
||||||
# 웨이브와 상태를 포함한 계획 인덱싱
|
# 웨이브 및 상태와 함께 계획 인덱싱
|
||||||
node gsd-tools.cjs phase-plan-index <phase>
|
node gsd-tools.cjs phase-plan-index <phase>
|
||||||
|
|
||||||
# 필터링을 포함한 단계 목록
|
# 필터링으로 단계 목록 표시
|
||||||
node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]
|
node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Roadmap 명령어
|
## 로드맵 명령
|
||||||
|
|
||||||
`ROADMAP.md`를 파싱하고 업데이트합니다.
|
`ROADMAP.md` 파싱 및 업데이트.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# ROADMAP.md에서 단계 섹션 추출
|
# ROADMAP.md에서 단계 섹션 추출
|
||||||
@@ -121,27 +138,27 @@ node gsd-tools.cjs roadmap get-phase <phase>
|
|||||||
# 디스크 상태를 포함한 전체 로드맵 파싱
|
# 디스크 상태를 포함한 전체 로드맵 파싱
|
||||||
node gsd-tools.cjs roadmap analyze
|
node gsd-tools.cjs roadmap analyze
|
||||||
|
|
||||||
# 디스크에서 진행률 표 행 업데이트
|
# 디스크에서 진행 테이블 행 업데이트
|
||||||
node gsd-tools.cjs roadmap update-plan-progress <N>
|
node gsd-tools.cjs roadmap update-plan-progress <N>
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Config 명령어
|
## 설정 명령
|
||||||
|
|
||||||
`.planning/config.json`을 읽고 씁니다.
|
`.planning/config.json` 읽기 및 쓰기.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# config.json을 기본값으로 초기화
|
# 기본값으로 config.json 초기화
|
||||||
node gsd-tools.cjs config-ensure-section
|
node gsd-tools.cjs config-ensure-section
|
||||||
|
|
||||||
# config 값 설정 (점 표기법)
|
# 설정 값 지정 (점 표기법)
|
||||||
node gsd-tools.cjs config-set <key> <value>
|
node gsd-tools.cjs config-set <key> <value>
|
||||||
|
|
||||||
# config 값 가져오기
|
# 설정 값 가져오기
|
||||||
node gsd-tools.cjs config-get <key>
|
node gsd-tools.cjs config-get <key>
|
||||||
|
|
||||||
# 모델 프로필 설정
|
# 모델 프로파일 설정
|
||||||
node gsd-tools.cjs config-set-model-profile <profile>
|
node gsd-tools.cjs config-set-model-profile <profile>
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -150,16 +167,18 @@ node gsd-tools.cjs config-set-model-profile <profile>
|
|||||||
## 모델 해석
|
## 모델 해석
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 현재 프로필 기반으로 에이전트 모델 가져오기
|
# 현재 프로파일 기반으로 에이전트에 대한 모델 가져오기
|
||||||
node gsd-tools.cjs resolve-model <agent-name>
|
node gsd-tools.cjs resolve-model <agent-name>
|
||||||
# 반환값: opus | sonnet | haiku | inherit
|
# 원시 출력은 선택된 모델 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`
|
에이전트 이름: `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`
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Verification 명령어
|
## 검증 명령
|
||||||
|
|
||||||
계획, 단계, 참조, 커밋을 검증합니다.
|
계획, 단계, 참조, 커밋을 검증합니다.
|
||||||
|
|
||||||
@@ -167,13 +186,13 @@ node gsd-tools.cjs resolve-model <agent-name>
|
|||||||
# SUMMARY.md 파일 검증
|
# SUMMARY.md 파일 검증
|
||||||
node gsd-tools.cjs verify-summary <path> [--check-count N]
|
node gsd-tools.cjs verify-summary <path> [--check-count N]
|
||||||
|
|
||||||
# PLAN.md 구조 + 작업 확인
|
# PLAN.md 구조 + 태스크 확인
|
||||||
node gsd-tools.cjs verify plan-structure <file>
|
node gsd-tools.cjs verify plan-structure <file>
|
||||||
|
|
||||||
# 모든 계획에 요약이 있는지 확인
|
# 모든 계획에 요약이 있는지 확인
|
||||||
node gsd-tools.cjs verify phase-completeness <phase>
|
node gsd-tools.cjs verify phase-completeness <phase>
|
||||||
|
|
||||||
# @-참조 + 경로 해석 확인
|
# @-참조 + 경로 확인
|
||||||
node gsd-tools.cjs verify references <file>
|
node gsd-tools.cjs verify references <file>
|
||||||
|
|
||||||
# 커밋 해시 일괄 검증
|
# 커밋 해시 일괄 검증
|
||||||
@@ -188,48 +207,57 @@ node gsd-tools.cjs verify key-links <plan-file>
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Validation 명령어
|
## 유효성 검사 명령
|
||||||
|
|
||||||
프로젝트 무결성을 확인합니다.
|
프로젝트 무결성 확인.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 단계 번호 매기기, 디스크/로드맵 동기화 확인
|
# 단계 번호 지정, 디스크/로드맵 동기화 확인
|
||||||
node gsd-tools.cjs validate consistency
|
node gsd-tools.cjs validate consistency
|
||||||
|
|
||||||
# .planning/ 무결성 확인, 선택적으로 복구
|
# .planning/ 무결성 확인, 선택적 복구
|
||||||
node gsd-tools.cjs validate health [--repair]
|
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 명령어
|
## 템플릿 명령
|
||||||
|
|
||||||
템플릿 선택 및 채우기입니다.
|
템플릿 선택 및 채우기.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 세분화에 따른 요약 템플릿 선택
|
# 세분성에 따라 요약 템플릿 선택
|
||||||
node gsd-tools.cjs template select <type>
|
node gsd-tools.cjs template select <type>
|
||||||
|
|
||||||
# 변수로 템플릿 채우기
|
# 변수로 템플릿 채우기
|
||||||
node gsd-tools.cjs template fill <type> --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}']
|
node gsd-tools.cjs template fill <type> --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}']
|
||||||
```
|
```
|
||||||
|
|
||||||
`fill`의 템플릿 유형: `summary`, `plan`, `verification`
|
`fill`에 대한 템플릿 유형: `summary`, `plan`, `verification`
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Frontmatter 명령어
|
## 프론트매터 명령
|
||||||
|
|
||||||
모든 Markdown 파일에 대한 YAML 전문 CRUD 작업입니다.
|
Markdown 파일에 대한 YAML 프론트매터 CRUD 작업.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 전문을 JSON으로 추출
|
# 프론트매터를 JSON으로 추출
|
||||||
node gsd-tools.cjs frontmatter get <file> [--field key]
|
node gsd-tools.cjs frontmatter get <file> [--field key]
|
||||||
|
|
||||||
# 단일 필드 업데이트
|
# 단일 필드 업데이트
|
||||||
node gsd-tools.cjs frontmatter set <file> --field key --value jsonVal
|
node gsd-tools.cjs frontmatter set <file> --field key --value jsonVal
|
||||||
|
|
||||||
# JSON을 전문에 병합
|
# JSON을 프론트매터에 병합
|
||||||
node gsd-tools.cjs frontmatter merge <file> --data '{json}'
|
node gsd-tools.cjs frontmatter merge <file> --data '{json}'
|
||||||
|
|
||||||
# 필수 필드 검증
|
# 필수 필드 검증
|
||||||
@@ -238,9 +266,9 @@ node gsd-tools.cjs frontmatter validate <file> --schema plan|summary|verificatio
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Scaffold 명령어
|
## 스캐폴드 명령
|
||||||
|
|
||||||
사전 구조화된 파일과 디렉터리를 생성합니다.
|
미리 구조화된 파일 및 디렉토리 생성.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# CONTEXT.md 템플릿 생성
|
# CONTEXT.md 템플릿 생성
|
||||||
@@ -252,15 +280,15 @@ node gsd-tools.cjs scaffold uat --phase N
|
|||||||
# VERIFICATION.md 템플릿 생성
|
# VERIFICATION.md 템플릿 생성
|
||||||
node gsd-tools.cjs scaffold verification --phase N
|
node gsd-tools.cjs scaffold verification --phase N
|
||||||
|
|
||||||
# 단계 디렉터리 생성
|
# 단계 디렉토리 생성
|
||||||
node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"
|
node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Init 명령어 (복합 컨텍스트 로드)
|
## Init 명령 (복합 컨텍스트 로딩)
|
||||||
|
|
||||||
특정 워크플로우에 필요한 모든 컨텍스트를 단일 호출로 로드합니다. 프로젝트 정보, config, state, 워크플로우별 데이터를 포함한 JSON을 반환합니다.
|
하나의 호출로 특정 워크플로우에 필요한 모든 컨텍스트를 로드합니다. 프로젝트 정보, 설정, 상태, 워크플로우별 데이터가 포함된 JSON을 반환합니다.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
node gsd-tools.cjs init execute-phase <phase>
|
node gsd-tools.cjs init execute-phase <phase>
|
||||||
@@ -275,9 +303,13 @@ node gsd-tools.cjs init todos [area]
|
|||||||
node gsd-tools.cjs init milestone-op
|
node gsd-tools.cjs init milestone-op
|
||||||
node gsd-tools.cjs init map-codebase
|
node gsd-tools.cjs init map-codebase
|
||||||
node gsd-tools.cjs init progress
|
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
|
```bash
|
||||||
INIT=$(node gsd-tools.cjs init execute-phase "1")
|
INIT=$(node gsd-tools.cjs init execute-phase "1")
|
||||||
@@ -286,20 +318,52 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Milestone 명령어
|
## 마일스톤 명령
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 마일스톤 보관
|
# 마일스톤 아카이브
|
||||||
node gsd-tools.cjs milestone complete <version> [--name <name>] [--archive-phases]
|
node gsd-tools.cjs milestone complete <version> [--name <name>] [--archive-phases]
|
||||||
|
|
||||||
# 요구 사항을 완료로 표시
|
# 요구사항을 완료로 표시
|
||||||
node gsd-tools.cjs requirements mark-complete <ids>
|
node gsd-tools.cjs requirements mark-complete <ids>
|
||||||
# 허용 형식: REQ-01,REQ-02 또는 REQ-01 REQ-02 또는 [REQ-01, REQ-02]
|
# 허용 형식: REQ-01,REQ-02 또는 REQ-01 REQ-02 또는 [REQ-01, REQ-02]
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 유틸리티 명령어
|
## 에이전트 스킬
|
||||||
|
|
||||||
|
지정된 에이전트 유형에 대한 스킬 블록을 출력합니다.
|
||||||
|
|
||||||
|
```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
|
```bash
|
||||||
# 텍스트를 URL 안전 슬러그로 변환
|
# 텍스트를 URL 안전 슬러그로 변환
|
||||||
@@ -309,10 +373,10 @@ node gsd-tools.cjs generate-slug "Some Text Here"
|
|||||||
# 타임스탬프 가져오기
|
# 타임스탬프 가져오기
|
||||||
node gsd-tools.cjs current-timestamp [full|date|filename]
|
node gsd-tools.cjs current-timestamp [full|date|filename]
|
||||||
|
|
||||||
# 대기 중인 할 일 개수 및 목록
|
# 보류 중인 할 일 카운트 및 목록
|
||||||
node gsd-tools.cjs list-todos [area]
|
node gsd-tools.cjs list-todos [area]
|
||||||
|
|
||||||
# 파일/디렉터리 존재 확인
|
# 파일/디렉토리 존재 여부 확인
|
||||||
node gsd-tools.cjs verify-path-exists <path>
|
node gsd-tools.cjs verify-path-exists <path>
|
||||||
|
|
||||||
# 모든 SUMMARY.md 데이터 집계
|
# 모든 SUMMARY.md 데이터 집계
|
||||||
@@ -324,44 +388,112 @@ node gsd-tools.cjs summary-extract <path> [--fields field1,field2]
|
|||||||
# 프로젝트 통계
|
# 프로젝트 통계
|
||||||
node gsd-tools.cjs stats [json|table]
|
node gsd-tools.cjs stats [json|table]
|
||||||
|
|
||||||
# 진행률 렌더링
|
# 진행률 렌더링 (사람이 읽을 수 있는 형태)
|
||||||
node gsd-tools.cjs progress [json|table|bar]
|
node gsd-tools.cjs progress [json|table|bar]
|
||||||
|
|
||||||
# 할 일 완료 처리
|
# 타입이 지정된 JSON 인터페이스로서의 진행률 (#455)
|
||||||
|
node gsd-tools.cjs progress --json
|
||||||
|
|
||||||
|
# 할 일 완료
|
||||||
node gsd-tools.cjs todo complete <filename>
|
node gsd-tools.cjs todo complete <filename>
|
||||||
|
|
||||||
# UAT 감사 — 모든 단계에서 미해결 항목 스캔
|
# UAT 감사 — 모든 단계에서 미해결 항목 스캔
|
||||||
node gsd-tools.cjs audit-uat
|
node gsd-tools.cjs audit-uat
|
||||||
|
|
||||||
# config 확인을 포함한 git 커밋
|
# 교차 아티팩트 감사 큐 — `.planning/`에서 미해결 감사 항목 스캔
|
||||||
node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify]
|
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] [--respect-staged]
|
||||||
```
|
```
|
||||||
|
|
||||||
> **`--no-verify`**: 사전 커밋 훅을 건너뜁니다. 빌드 잠금 경쟁을 피하기 위해 웨이브 기반 실행 중 병렬 executor 에이전트가 사용합니다 (예: Rust 프로젝트의 cargo lock 충돌). 오케스트레이터는 각 웨이브 완료 후 훅을 한 번 실행합니다. 순차 실행 중에는 `--no-verify`를 사용하지 마세요 — 훅이 정상적으로 실행되어야 합니다.
|
> `--no-verify`: 사전 커밋 훅을 건너뜁니다. 병렬 실행기 에이전트가 웨이브 기반 실행 중에 빌드 잠금 충돌(예: Rust 프로젝트의 cargo lock 경쟁)을 방지하기 위해 사용합니다. 오케스트레이터는 각 웨이브 완료 후 훅을 한 번 실행합니다. 순차 실행 중에는 `--no-verify`를 사용하지 마세요 — 훅이 정상적으로 실행되도록 하세요.
|
||||||
|
> `--files <paths>` **스테이징 동작**: 기본적으로 `--files`는 커밋 전에 각 명명된 파일에 대해 `git add -- <path>`를 실행합니다. 이렇게 하면 `git add -p`를 통해 설정된 헝크별 스테이징이 덮어쓰여집니다. `--respect-staged`를 전달하면 `git add` 단계를 건너뛰고 요청된 경로 사양 내에서 이미 인덱스에 있는 것만 커밋합니다. 해당 범위 내에서 스테이징된 것이 없으면 명령은 오류 없이 `{ committed: false, reason: 'nothing staged' }`를 반환합니다. 커밋의 후행 `-- <paths>` 경로 사양은 두 모드 모두에서 적용되므로 `--files` 범위 외부에서 스테이징된 파일은 절대 포함되지 않습니다(#3061 불변식).
|
||||||
|
|
||||||
```bash
|
|
||||||
# 웹 검색 (Brave API 키 필요)
|
# 웹 검색 (Brave API 키 필요)
|
||||||
node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
|
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` |
|
| State | `lib/state.cjs` | 모든 `state` 서브명령, `state-snapshot` |
|
||||||
| Phase | `lib/phase.cjs` | Phase CRUD, `find-phase`, `phase-plan-index`, `phases list` |
|
| 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` | 로드맵 파싱, 단계 추출, 진행률 업데이트 |
|
| Roadmap | `lib/roadmap.cjs` | 로드맵 파싱, 단계 추출, 진행률 업데이트 |
|
||||||
| Config | `lib/config.cjs` | Config 읽기/쓰기, 섹션 초기화 |
|
| Config | `lib/config.cjs` | 설정 읽기/쓰기, 섹션 초기화 |
|
||||||
| Verify | `lib/verify.cjs` | 모든 verification 및 validation 명령어 |
|
| Verify | `lib/verify.cjs` | 모든 검증 및 유효성 검사 명령 |
|
||||||
| Template | `lib/template.cjs` | 템플릿 선택 및 변수 채우기 |
|
| Template | `lib/template.cjs` | 템플릿 선택 및 변수 채우기 |
|
||||||
| Frontmatter | `lib/frontmatter.cjs` | YAML 전문 CRUD |
|
| Frontmatter | `lib/frontmatter.cjs` | YAML 프론트매터 CRUD |
|
||||||
| Init | `lib/init.cjs` | 모든 워크플로우를 위한 복합 컨텍스트 로드 |
|
| Init | `lib/init.cjs` | 모든 워크플로우를 위한 복합 컨텍스트 로딩 |
|
||||||
| Milestone | `lib/milestone.cjs` | 마일스톤 보관, 요구 사항 표시 |
|
| Milestone | `lib/milestone.cjs` | 마일스톤 아카이브, 요구사항 표시 |
|
||||||
| Commands | `lib/commands.cjs` | 기타: slug, timestamp, todos, scaffold, stats, websearch |
|
| Commands | `lib/commands.cjs` | 기타: slug, timestamp, todos, scaffold, stats, websearch |
|
||||||
| Model Profiles | `lib/model-profiles.cjs` | 프로필 해석 테이블 |
|
| Model Profiles | `lib/model-profiles.cjs` | 프로파일 해석 테이블 |
|
||||||
| UAT | `lib/uat.cjs` | 단계 간 UAT/verification 감사 |
|
| UAT | `lib/uat.cjs` | 교차 단계 UAT/검증 감사 |
|
||||||
| Profile Output | `lib/profile-output.cjs` | 개발자 프로필 포매팅 |
|
| Profile Output | `lib/profile-output.cjs` | 개발자 프로파일 서식 지정 |
|
||||||
| Profile Pipeline | `lib/profile-pipeline.cjs` | 세션 분석 파이프라인 |
|
| Profile Pipeline | `lib/profile-pipeline.cjs` | 세션 분석 파이프라인 |
|
||||||
|
| Graphify | `lib/graphify.cjs` | 지식 그래프 빌드/쿼리/상태/diff/스냅샷 (`/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 "" # clear — fall back to session model
|
||||||
|
```
|
||||||
|
|
||||||
|
슬러그는 `[a-zA-Z0-9_-]+`에 대해 검증됩니다; 비어 있거나 경로를 포함하는 슬러그는 거부됩니다. 전체 필드 참조는 [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing)를 참조하세요.
|
||||||
|
|
||||||
|
## 시크릿 처리
|
||||||
|
|
||||||
|
`/gsd-settings`(`brave_search`, `firecrawl`, `exa_search`)를 통해 설정된 API 키는 `.planning/config.json`에 일반 텍스트로 기록되지만 모든 `config-set` / `config-get` 출력, 확인 테이블, 대화형 프롬프트에서 마스킹(`****<last-4>`)됩니다. 마스킹 구현은 `get-shit-done/bin/lib/secrets.cjs`를 참조하세요. `config.json` 파일 자체가 보안 경계입니다 — 파일시스템 권한으로 보호하고 git에서 제외하세요(`.planning/`는 기본적으로 gitignore됩니다).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
|
||||||
|
- [명령](COMMANDS.md)
|
||||||
|
- [설정](CONFIGURATION.md)
|
||||||
|
- [아키텍처](ARCHITECTURE.md)
|
||||||
|
- [문서 인덱스](README.md)
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
493
docs/ko-KR/INVENTORY.md
Normal file
493
docs/ko-KR/INVENTORY.md
Normal 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 표면의 공식 목록입니다. 주제별 탐색은 [문서 색인](README.md)을 참조하세요.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 에이전트 (33개 출시)
|
||||||
|
|
||||||
|
전체 목록은 `agents/gsd-*.md`에 있습니다. "주요 문서" 열은 [`docs/AGENTS.md`](AGENTS.md)에서 전체 역할 카드(*primary*), "고급 및 특수 에이전트" 섹션의 짧은 스텁(*advanced stub*), 또는 다루지 않음(*inventory only*)을 표시합니다.
|
||||||
|
|
||||||
|
| 에이전트 | 역할 (한 줄) | 생성자 | 주요 문서 |
|
||||||
|
|-------|-----------------|------------|-------------|
|
||||||
|
| 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` 워크플로우 | primary |
|
||||||
|
| gsd-advisor-researcher | discuss-phase 어드바이저 모드에서 단일 회색 지대 결정을 조사. | `discuss-phase` 워크플로우 (어드바이저 모드) | 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` (검증 루프) | primary |
|
||||||
|
| gsd-integration-checker | 단계 간 통합 및 엔드투엔드 플로우 검증. | `/gsd-audit-milestone` | primary |
|
||||||
|
| gsd-ui-checker | 품질 차원에 대한 UI-SPEC.md 설계 계약 검증. | `/gsd-ui-phase` (검증 루프) | primary |
|
||||||
|
| gsd-verifier | 목표 역방향 분석을 통한 단계 목표 달성 검증. | `/gsd-execute-phase` | primary |
|
||||||
|
| gsd-nyquist-auditor | 테스트 생성으로 나이퀴스트 검증 공백 채움. | `/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` (조사와 계획 사이) | 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 | 분류된 계획 문서를 우선순위 규칙, 순환 감지, 세 버킷 충돌 보고서로 단일 통합 컨텍스트로 합성. | `/gsd-ingest-docs` | advanced stub |
|
||||||
|
|
||||||
|
**커버리지 참고.** `docs/AGENTS.md`는 21개 주요 에이전트에 대한 전체 역할 카드와 12개 고급 에이전트에 대한 간결한 스텁을 제공합니다. 해당 파일의 에이전트 도구 권한 요약은 주요 21개 에이전트만 다루며; 고급 에이전트의 도구 목록은 `agents/gsd-*.md`의 에이전트별 프론트매터에 기록됩니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 명령어 (67개 출시)
|
||||||
|
|
||||||
|
전체 목록은 `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` | 품질 게이트 라우터 — 코드 리뷰, 디버그, 감사, 보안, 평가, UI. | [commands/gsd/ns-review.md](../../commands/gsd/ns-review.md) |
|
||||||
|
| `/gsd-context` | 코드베이스 인텔리전스 라우터 — 맵, 그래프화, 문서, 학습. | [commands/gsd/ns-context.md](../../commands/gsd/ns-context.md) |
|
||||||
|
| `/gsd-manage` | 관리 라우터 — 설정, 워크스페이스, 워크스트림, 스레드, 업데이트, 출시, 인박스. | [commands/gsd/ns-manage.md](../../commands/gsd/ns-manage.md) |
|
||||||
|
| `/gsd-ideate` | 탐색 및 캡처 라우터 — 탐색, 스케치, 스파이크, 스펙, 캡처. | [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` | 프레임워크 선택, 조사, 평가 계획을 통한 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` | 완료된 단계의 나이퀴스트 검증 공백을 소급 감사 및 채움. | [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` | 하나의 터미널에서 여러 단계를 관리하는 인터랙티브 커맨드 센터. | [commands/gsd/manager.md](../../commands/gsd/manager.md) |
|
||||||
|
| `/gsd-workstreams` | 병렬 워크스트림 관리 — 목록, 생성, 전환, 상태, 진행도, 완료, 재개. | [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개 출시)
|
||||||
|
|
||||||
|
전체 목록은 `get-shit-done/workflows/*.md`에 있습니다. 워크플로우는 명령어가 내부적으로 참조하는 얇은 오케스트레이터입니다; 대부분은 최종 사용자가 직접 읽지 않습니다. 아래 행은 각 워크플로우 파일을 역할(`<purpose>` 블록에서 도출)과, 해당하는 경우 호출 명령어에 매핑합니다.
|
||||||
|
|
||||||
|
| 워크플로우 | 역할 | 호출자 |
|
||||||
|
|----------|------|------------|
|
||||||
|
| `add-backlog.md` | 999.x 번호 체계를 사용하여 ROADMAP.md에 백로그 항목 추가. | `/gsd-capture --backlog` |
|
||||||
|
| `add-phase.md` | 로드맵의 현재 마일스톤 끝에 새 정수 단계 추가. | `/gsd-phase` (기본값) |
|
||||||
|
| `add-tests.md` | 완료된 단계의 아티팩트를 기반으로 단위 및 E2E 테스트 생성. | `/gsd-add-tests` |
|
||||||
|
| `add-todo.md` | 세션 중 발생하는 아이디어나 태스크를 구조화된 todo로 캡처. | `/gsd-capture` (기본값) |
|
||||||
|
| `ai-integration-phase.md` | 프레임워크 선택 → AI 조사 → 도메인 조사 → 평가 계획을 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` (자동 진단) |
|
||||||
|
| `discovery-phase.md` | 적절한 깊이 수준에서 탐색 실행. | `/gsd-new-project` (탐색 경로) |
|
||||||
|
| `discuss-phase-assumptions.md` | 가정 모드 discuss — 코드베이스 우선 분석을 통한 구현 결정 추출. | `/gsd-discuss-phase` (`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` (계획별 하위 에이전트) |
|
||||||
|
| `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 단계) |
|
||||||
|
| `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` (복구) |
|
||||||
|
| `note.md` | 마찰 없는 아이디어 캡처 — 단일 Write 호출, 단일 확인 줄. | `/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 라우팅, 마스킹된(`****<last-4>`) 표시로 `agent_skills.<agent-type>` 주입 구성. | `/gsd-config --integrations` |
|
||||||
|
| `ship.md` | 검증 후 PR 생성, 리뷰 실행, 병합 준비. | `/gsd-ship` |
|
||||||
|
| `sketch.md` | 스케치당 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` | 완료된 단계의 나이퀴스트 검증 공백을 소급 감사 및 채움. | `/gsd-validate-phase` |
|
||||||
|
| `verify-phase.md` | 목표 역방향 분석을 통한 단계 목표 달성 검증. | `execute-phase.md` (실행 후) |
|
||||||
|
| `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개 출시)
|
||||||
|
|
||||||
|
전체 목록은 `get-shit-done/references/*.md`에 있습니다. 레퍼런스는 워크플로우와 에이전트가 `@-참조`하는 공유 지식 문서입니다. 아래 그룹화는 [`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>`를 통해 executor 스폰 프롬프트에 로드됨. |
|
||||||
|
| `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` | Windows stdio 멈춤 완화를 위한 청크 모드 반환 형식(`## OUTLINE COMPLETE`, `## PLAN COMPLETE`). |
|
||||||
|
| `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` 자동 업데이트 상태(실행 중 / 실패 / 부실 HEAD)를 표면화하는 방법. `graphify.auto_update`를 통해 옵트인 (#3347). |
|
||||||
|
| `planner-interface-context.md` | executor를 위한 인터페이스 컨텍스트 규칙 — 기존 코드에서 핵심 인터페이스/타입/익스포트 추출 방법과 다운스트림 계획이 사용할 새 인터페이스 문서화. |
|
||||||
|
| `skeleton-template.md` | 새 프로젝트 Walking Skeleton(Phase 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개 출시)
|
||||||
|
|
||||||
|
전체 목록: `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 Phase 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 명령어(슬러그, 타임스탬프, 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` | 오류 처리, 출력 포매팅, 공유 유틸리티, 런타임 폴백; 계획 워크스페이스 헬퍼를 위한 호환성 재내보내기 |
|
||||||
|
| `decisions.cjs` | CONTEXT.md `<decisions>` 블록 파싱; 숫자형(D-42) 및 영숫자형(D-INFRA-01) ID 허용; `{id, text, category, tags, trackable}` 반환 |
|
||||||
|
| `docs.cjs` | 문서 업데이트 워크플로우 초기화, 마크다운 스캔, 모노레포 감지 |
|
||||||
|
| `drift.cjs` | 실행 후 코드베이스 구조 드리프트 감지기(#2003): 파일 변경을 new-dir/barrel/migration/route 카테고리로 분류하고 `last_mapped_commit` 프론트매터를 왕복 처리 |
|
||||||
|
| `fallow-runner.cjs` | `/gsd-code-review`를 위한 Fallow 감사 어댑터: 바이너리 해석(`PATH` 이후 `node_modules/.bin`), 실행 가능한 누락 바이너리 오류, 구조적 결과 정규화 |
|
||||||
|
| `frontmatter.cjs` | YAML 프론트매터 CRUD 작업 |
|
||||||
|
| `gap-checker.cjs` | 계획 후 공백 분석(#2493): REQUIREMENTS.md + CONTEXT.md 결정 대 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, 비례 계획 잘라내기, 컨텍스트/조사/요구사항 삭제, 하드 실패 가드), `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`, 안정적인 트리플릿 검증, 정규화된 튜플 파싱)(#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 Phase 2) |
|
||||||
|
| `task-command-router.cjs` | `gsd-tools task`를 위한 얇은 CJS 하위 명령어 라우터 어댑터 |
|
||||||
|
| `template.cjs` | 변수 치환을 통한 템플릿 선택 및 채우기 |
|
||||||
|
| `uat.cjs` | UAT 파일 파싱, 검증 부채 추적, audit-uat 지원 |
|
||||||
|
| `ui-safety-gate.cjs` | 셸 없는 단어 경계 UI 토큰 감지기(#3706, #3718); stdin에서 단계 섹션 텍스트를 읽어 0(UI 발견) 또는 1(UI 없음) 종료; GSD 설치 프로그램이 `$RUNTIME_DIR`에 배포하도록 `get-shit-done/bin/lib/`에도 배포 |
|
||||||
|
| `update-context.cjs` | `/gsd:update`를 위한 순수 설치 컨텍스트 해석기 — update.md bash에서 포팅된 런타임/범위/설정 디렉터리/버전 감지(LOCAL/GLOBAL/UNKNOWN); `gsd-tools update-context` 지원(#498) |
|
||||||
|
| `validate-command-router.cjs` | `gsd-tools validate`를 위한 얇은 CJS 하위 명령어 라우터 어댑터 |
|
||||||
|
| `validate.cjs` | 순수 단계 변형 정규화 헬퍼(`phaseVariants`, `buildRoadmapPhaseVariants`, `buildNotStartedPhaseVariants`), W006/W007 확인을 위해 `verify.cjs`에서 사용; 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개 출시)
|
||||||
|
|
||||||
|
전체 목록: `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 상태라인을 사용하지 않을 때 업데이트 가용성을 표면화하는 옵트인 배너(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` | 컨벤셔널 커밋 적용을 위한 커밋 검증 |
|
||||||
|
| `gsd-phase-boundary.sh` | `PostToolUse` | 워크플로우 전환을 위한 단계 경계 감지 |
|
||||||
|
| `gsd-graphify-update.sh` | `PostToolUse` | 메인 HEAD 진행 후 지식 그래프 자동 재빌드 (옵트인, 기본 비활성화 — #3347) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 유지 관리
|
||||||
|
|
||||||
|
- 새 명령어, 에이전트, 워크플로우, 레퍼런스, CLI 모듈, 또는 훅이 출시될 때, 릴리스가 잘리기 전에 해당 섹션을 여기에 업데이트하세요.
|
||||||
|
- `tests/` 아래의 드리프트 가드 테스트(위의 "이 파일 사용 방법" 참조)는 출시된 모든 파일이 이 인벤토리에 열거되어 있음을 어설트합니다. 일치하는 행이 없는 새 파일은 CI를 실패시킵니다.
|
||||||
|
- 파일시스템이 `docs/ARCHITECTURE.md` 수량 또는 엄선된 하위 집합 문서(예: `docs/AGENTS.md`의 주요 목록)와 다를 경우, 이 파일이 진실의 원천입니다.
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
|
||||||
|
- [명령어](COMMANDS.md) — 사용자 대면 명령어 참조
|
||||||
|
- [아키텍처](ARCHITECTURE.md) — 표면이 어떻게 맞물리는지
|
||||||
|
- [문서 색인](README.md)
|
||||||
@@ -1,29 +1,69 @@
|
|||||||
# GSD Core 문서
|
# GSD Core 문서
|
||||||
|
|
||||||
GSD Core (Git. Ship. Done.) 문서입니다. GSD Core는 AI 코딩 에이전트를 위한 메타 프롬프팅, 컨텍스트 엔지니어링, 스펙 기반 개발 시스템입니다.
|
문서는 네 가지 유형으로 구성됩니다. **튜토리얼**은 직접 해보며 배우고, **how-to 가이드**는 특정 작업을 해결하며, **레퍼런스**는 권위 있는 사실을 제시하고, **설명**은 개념과 설계 결정을 탐구합니다.
|
||||||
|
|
||||||
언어 버전: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) · [日本語](ja-JP/README.md) · [简体中文](zh-CN/README.md) · [한국어](ko-KR/README.md)
|
언어 버전: [English](../README.md) · [Português (pt-BR)](../pt-BR/README.md) · [日本語](../ja-JP/README.md) · [简体中文](../zh-CN/README.md) · **한국어**
|
||||||
|
|
||||||
## 문서 목차
|
---
|
||||||
|
|
||||||
| 문서 | 대상 독자 | 설명 |
|
## 튜토리얼
|
||||||
|------|-----------|------|
|
|
||||||
| [Architecture](ARCHITECTURE.md) | 기여자, 고급 사용자 | 시스템 아키텍처, 에이전트 모델, 데이터 흐름, 내부 설계 |
|
|
||||||
| [Feature Reference](FEATURES.md) | 전체 사용자 | 요구사항이 포함된 전체 기능 및 함수 문서 |
|
|
||||||
| [Command Reference](COMMANDS.md) | 전체 사용자 | 모든 명령어의 구문, 플래그, 옵션 및 예제 |
|
|
||||||
| [Configuration Reference](CONFIGURATION.md) | 전체 사용자 | 전체 설정 스키마, 워크플로우 토글, 모델 프로필, git 브랜칭 |
|
|
||||||
| [CLI Tools Reference](CLI-TOOLS.md) | 기여자, 에이전트 작성자 | CJS `gsd-tools.cjs` + `gsd-tools.cjs query` 안내 |
|
|
||||||
| [Agent Reference](AGENTS.md) | 기여자, 고급 사용자 | 18개 전문 에이전트의 역할, 도구, 스폰 패턴 |
|
|
||||||
| [User Guide](USER-GUIDE.md) | 전체 사용자 | 워크플로우 안내, 문제 해결, 복구 방법 |
|
|
||||||
| [Context Monitor](context-monitor.md) | 전체 사용자 | 컨텍스트 윈도우 모니터링 훅 아키텍처 |
|
|
||||||
| [Discuss Mode](workflow-discuss-mode.md) | 전체 사용자 | discuss 단계의 assumptions 모드와 interview 모드 |
|
|
||||||
|
|
||||||
## 빠른 링크
|
- [첫 번째 프로젝트](tutorials/your-first-project.md) — 설치부터 첫 단계 출시까지, 확실한 한 가지 경로
|
||||||
|
- [기존 코드베이스 온보딩](tutorials/onboarding-an-existing-codebase.md) — 기존 저장소에 GSD Core 적용하기
|
||||||
|
|
||||||
- **v1.39의 새로운 기능:** `--minimal` 설치 프로파일(콜드 스타트 ≥94% 감소), `/gsd-phase --edit`, 머지 후 빌드 & 테스트 게이트, `review.models.<cli>` 런타임별 리뷰 모델, 워크스트림 설정 상속, 수동 카나리 릴리스 워크플로, 스킬 통합(86 → 59)
|
---
|
||||||
- **시작하기:** [README](../README.md) → 설치 → `/gsd-new-project`
|
|
||||||
- **전체 워크플로우 안내:** [User Guide](USER-GUIDE.md)
|
## How-to guides
|
||||||
- **모든 명령어 한눈에 보기:** [Command Reference](COMMANDS.md)
|
|
||||||
- **GSD 설정하기:** [Configuration Reference](CONFIGURATION.md)
|
- [런타임에 설치하기](how-to/install-on-your-runtime.md) — 지원하는 15개 런타임 각각의 설치 단계
|
||||||
- **시스템 내부 동작 원리:** [Architecture](ARCHITECTURE.md)
|
- [단계 논의하기](how-to/discuss-a-phase.md) — 기획 시작 전 구현 결정 사항 정리
|
||||||
- **기여 또는 확장:** [CLI Tools Reference](CLI-TOOLS.md) + [Agent Reference](AGENTS.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) — 주 에이전트가 생성한 코드를 두 번째 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) — 컨텍스트 rot가 형성되는 방식과 GSD Core의 방지 방법
|
||||||
|
- [단계 루프](explanation/the-phase-loop.md) — 논의 → 기획 → 실행 → 검증 → 출시 사이클의 설계 근거
|
||||||
|
- [멀티 에이전트 오케스트레이션](explanation/multi-agent-orchestration.md) — 서브에이전트의 생성, 범위 지정, 조율 방식
|
||||||
|
- [보안 모델](explanation/security-model.md) — 신뢰 경계, 권한, 안전한 자동화
|
||||||
|
- [아키텍처](ARCHITECTURE.md) — 시스템 아키텍처, 에이전트 모델, 데이터 흐름
|
||||||
|
- [논의 모드](workflow-discuss-mode.md) — `/gsd-discuss-phase`의 가정 모드와 인터뷰 모드
|
||||||
|
- [컨텍스트 모니터링](context-monitor.md) — 컨텍스트 창 모니터링 훅 아키텍처
|
||||||
|
- [이슈 기반 오케스트레이션](issue-driven-orchestration.md) — 기존 프리미티브를 사용해 트래커 이슈로 GSD를 구동하는 레시피
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [루트 README](../README.md) — 랜딩 페이지, 빠른 시작, 문서 개요
|
||||||
|
- [변경 로그](../../CHANGELOG.md) — 릴리스 이력
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
@@ -1,32 +1,32 @@
|
|||||||
# 컨텍스트 윈도우 모니터
|
# 컨텍스트 윈도우 모니터
|
||||||
|
|
||||||
에이전트의 컨텍스트 윈도우 사용량이 높을 때 경고를 주는 post-tool 훅입니다 (Claude Code의 경우 `PostToolUse`, Gemini CLI의 경우 `AfterTool`).
|
에이전트의 컨텍스트 윈도우 사용량이 높을 때 경고를 주는 post-tool 훅 (Claude Code의 경우 `PostToolUse`, Gemini CLI의 경우 `AfterTool`).
|
||||||
|
|
||||||
## 문제
|
## 문제
|
||||||
|
|
||||||
상태바(statusline)는 **사용자**에게 컨텍스트 사용량을 보여주지만 **에이전트** 자체는 컨텍스트 한계를 인식하지 못합니다. 컨텍스트가 부족해지면 에이전트는 한계에 부딪힐 때까지 작업을 계속 진행하며 상태가 저장되지 않은 채 작업 도중에 멈출 수 있습니다.
|
상태바(statusline)는 **사용자**에게 컨텍스트 사용량을 보여주지만 **에이전트** 자체는 컨텍스트 한계를 인식하지 못한다. 컨텍스트가 부족해지면 에이전트는 한계에 부딪힐 때까지 작업을 계속 진행한다 — 상태가 저장되지 않은 채 작업 도중에 멈출 수 있다.
|
||||||
|
|
||||||
## 동작 방식
|
## 동작 방식
|
||||||
|
|
||||||
1. statusline 훅이 컨텍스트 메트릭을 `/tmp/claude-ctx-{session_id}.json`에 기록합니다.
|
1. statusline 훅이 컨텍스트 메트릭을 `/tmp/claude-ctx-{session_id}.json`에 기록한다
|
||||||
2. 각 도구 사용 후 context monitor가 해당 메트릭을 읽습니다.
|
2. 각 도구 사용 후 context monitor가 해당 메트릭을 읽는다
|
||||||
3. 남은 컨텍스트가 임계값 아래로 떨어지면 `additionalContext`로 경고를 주입합니다.
|
3. 남은 컨텍스트가 임계값 아래로 떨어지면 `additionalContext`로 경고를 주입한다
|
||||||
4. 에이전트는 대화에서 경고를 받고 그에 맞게 대응할 수 있습니다.
|
4. 에이전트는 대화에서 경고를 받고 그에 맞게 대응할 수 있다
|
||||||
|
|
||||||
## 임계값
|
## 임계값
|
||||||
|
|
||||||
| 레벨 | 남은 비율 | 에이전트 동작 |
|
| 레벨 | 남은 비율 | 에이전트 동작 |
|
||||||
|------|-----------|---------------|
|
|-------|-----------|----------------|
|
||||||
| Normal | > 35% | 경고 없음 |
|
| Normal | > 35% | 경고 없음 |
|
||||||
| WARNING | <= 35% | 현재 작업 마무리, 새로운 복잡한 작업 시작 금지 |
|
| WARNING | <= 35% | 현재 작업 마무리, 새로운 복잡한 작업 시작 금지 |
|
||||||
| CRITICAL | <= 25% | 즉시 중단 후 상태 저장 (`/gsd-pause-work`) |
|
| CRITICAL | <= 25% | 즉시 중단 후 상태 저장 (`/gsd-pause-work`) |
|
||||||
|
|
||||||
## Debounce
|
## Debounce
|
||||||
|
|
||||||
에이전트에게 반복적인 경고가 쌓이는 것을 방지하기 위한 동작입니다.
|
에이전트에게 반복적인 경고가 쌓이는 것을 방지하기 위해:
|
||||||
- 첫 번째 경고는 항상 즉시 발생합니다.
|
- 첫 번째 경고는 항상 즉시 발생한다
|
||||||
- 이후 경고는 5번의 도구 사용 간격이 필요합니다.
|
- 이후 경고는 5번의 도구 사용 간격이 필요하다
|
||||||
- 심각도 상승 (WARNING → CRITICAL) 시에는 debounce를 우회합니다.
|
- 심각도 상승 (WARNING → CRITICAL) 시에는 debounce를 우회한다
|
||||||
|
|
||||||
## 아키텍처
|
## 아키텍처
|
||||||
|
|
||||||
@@ -43,7 +43,7 @@ Context Monitor (gsd-context-monitor.js, PostToolUse/AfterTool)
|
|||||||
additionalContext -> 에이전트가 경고를 받음
|
additionalContext -> 에이전트가 경고를 받음
|
||||||
```
|
```
|
||||||
|
|
||||||
브리지 파일은 단순한 JSON 객체입니다.
|
브리지 파일은 단순한 JSON 객체이다:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
@@ -56,60 +56,25 @@ additionalContext -> 에이전트가 경고를 받음
|
|||||||
|
|
||||||
## GSD와의 통합
|
## GSD와의 통합
|
||||||
|
|
||||||
GSD의 `/gsd-pause-work` 명령어는 실행 상태를 저장합니다. WARNING 메시지는 해당 명령어 사용을 권장하며 CRITICAL 메시지는 즉각적인 상태 저장을 지시합니다.
|
GSD의 `/gsd-pause-work` 명령어는 실행 상태를 저장한다. WARNING 메시지는 해당 명령어 사용을 권장하며 CRITICAL 메시지는 즉각적인 상태 저장을 지시한다.
|
||||||
|
|
||||||
## 설정
|
## 설정
|
||||||
|
|
||||||
두 훅 모두 `npx @opengsd/gsd-core` 설치 중에 자동으로 등록됩니다.
|
두 훅 모두 `npx @opengsd/gsd-core` 설치 중에 자동으로 등록된다 — 정상적인 상황에서는 수동 단계가 필요하지 않다. 훅 설정 상세, 임계값 재정의, 수동 등록 예시는 [설정](CONFIGURATION.md)을 참조하라.
|
||||||
|
|
||||||
- **Statusline** (브리지 파일 기록): settings.json에 `statusLine`으로 등록
|
간략한 참고: statusline 훅은 `settings.json`에 `statusLine`으로 등록된다; context monitor(`gsd-context-monitor.js`)는 `PostToolUse` 훅으로 등록된다(Gemini CLI의 경우 `AfterTool`). 두 항목 모두 설치 프로그램을 실행한 절대 Node 실행 경로를 사용한다. Windows PowerShell에서는 인용된 실행 경로 앞에 `&`를 붙인다.
|
||||||
- **Context Monitor** (브리지 파일 읽기): 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"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 안전성
|
## 안전성
|
||||||
|
|
||||||
- 훅은 모든 동작을 try/catch로 감싸며 오류 발생 시 조용히 종료합니다.
|
- 훅은 모든 동작을 try/catch로 감싸며 오류 발생 시 조용히 종료한다
|
||||||
- 도구 실행을 절대 차단하지 않습니다. 모니터에 문제가 생겨도 에이전트 워크플로우가 중단되지 않습니다.
|
- 도구 실행을 절대 차단하지 않는다 — 모니터에 문제가 생겨도 에이전트 워크플로우가 중단되지 않아야 한다
|
||||||
- 60초 이상 된 오래된 메트릭은 무시됩니다.
|
- 60초 이상 된 오래된 메트릭은 무시된다
|
||||||
- 누락된 브리지 파일은 정상적으로 처리됩니다 (서브에이전트, 새 세션 등의 경우).
|
- 누락된 브리지 파일은 정상적으로 처리된다 (서브에이전트, 새 세션 등의 경우)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [아키텍처](ARCHITECTURE.md)
|
||||||
|
- [설정](CONFIGURATION.md)
|
||||||
|
- [문서 인덱스](README.md)
|
||||||
|
|||||||
90
docs/ko-KR/explanation/context-engineering.md
Normal file
90
docs/ko-KR/explanation/context-engineering.md
Normal file
@@ -0,0 +1,90 @@
|
|||||||
|
# 컨텍스트 엔지니어링
|
||||||
|
|
||||||
|
> GSD Core가 존재하는 이유와 해결하고자 하는 문제.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 문제: 컨텍스트 부패
|
||||||
|
|
||||||
|
모든 AI 코딩 세션은 새롭게 시작된다. 모델은 질문을 읽고, 추론하고, 답변을 돌려준다. 그러나 하나의 세션이 단 한 번의 교환으로 끝나는 경우는 드물다. 추가 질문을 던지고, 오류 메시지를 붙여넣고, 코드를 반복적으로 개선하며, 모델이 엉뚱한 방향으로 흘러갈 때 방향을 바로잡는다. 각 대화 차례마다 토큰이 컨텍스트 윈도우에 쌓인다 — 모델이 한 번에 "볼 수" 있는 유한한 텍스트 버퍼.
|
||||||
|
|
||||||
|
이 윈도우가 채워지면 미묘한 일이 벌어진다. 모델은 요란하게 실패하지 않는다. 계속해서 답변을 생성한다. 하지만 답변의 품질은 서서히 저하된다. 초반에 주어진 지시 사항이 모델이 집중할 수 있는 범위의 가장자리로 밀려난다. 처음 몇 번의 교환에서 다뤘던 뉘앙스들 — 제시했던 제약 조건, 합의한 아키텍처, 언급했던 엣지 케이스들 — 이 이후에 쌓인 모든 내용과 주의를 경쟁하게 된다. 연구자들은 이를 **컨텍스트 부패(context rot)**라고 부른다.
|
||||||
|
|
||||||
|
컨텍스트 부패는 여러 형태로 나타난다.
|
||||||
|
|
||||||
|
- 모델이 이전에 인정했던 결정들을 모순되게 다루기 시작한다.
|
||||||
|
- 코드 스타일이 세션 초반에 확립한 컨벤션에서 벗어난다.
|
||||||
|
- 계획이 명확하게 명시되었지만 이제 깊이 묻혀버린 요구 사항들을 무시하기 시작한다.
|
||||||
|
- 모델이 20개의 메시지 전에는 정확히 알고 있던 파일 이름이나 함수 시그니처를 환각으로 만들어낸다.
|
||||||
|
|
||||||
|
이것은 모델 버그가 아니다. 긴 시퀀스에서 트랜스포머 어텐션이 작동하는 방식의 근본적인 특성이다. 모델은 "잊어버리는" 것이 아니다 — 인간적 의미에서의 "기억"은 애초에 없었다. 유한한 윈도우 안에서 관련성에 가중치를 부여하고 있으며, 누적된 노이즈로 윈도우가 채워질수록 신호 대 잡음비가 저하된다.
|
||||||
|
|
||||||
|
단순한 대응책은 `/clear`로 세션을 초기화하는 것이다. 그러나 그러면 연속성을 잃는다. 컨텍스트를 다시 설명하고, 관련 파일을 다시 붙여넣고, 제약 조건을 다시 명시해야 한다. 세션이 사실상 제로부터 다시 시작된다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## GSD Core의 답: 신선한 컨텍스트 서브에이전트
|
||||||
|
|
||||||
|
GSD Core의 핵심적인 통찰은 코딩 세션에서 이루어지는 작업의 *대부분*이 메인 컨텍스트에서 이루어질 필요가 없다는 것이다. 리서치, 계획 수립, 코드 작성, 검증은 각각 독립적이고 범위가 한정된 작업들이다. 각각을 깔끔하고 신중하게 범위가 지정된 컨텍스트 윈도우로 시작하는 전문화된 서브에이전트에게 넘기고 — 결과를 효율적으로 유지되는 얇은 오케스트레이터에게 보고할 수 있다.
|
||||||
|
|
||||||
|
이것은 컨텍스트 부패를 위한 임시방편이 아니다. 구조적인 해결책이다.
|
||||||
|
|
||||||
|
오케스트레이터 — 메인 세션 — 는 소스 파일을 직접 다루지 않는다. 에이전트를 생성하고, 결과를 수집하며, 공유 상태를 업데이트하고, 다음 단계로 라우팅한다. 오케스트레이터가 스스로 하는 작업이 매우 적기 때문에 컨텍스트 윈도우가 느리고 예측 가능하게 증가한다. 무거운 작업은 각각 신선하게 시작하고, 자신의 작업에 필요한 정확한 컨텍스트만 받고, 완료 시 종료하는 에이전트에서 수행된다.
|
||||||
|
|
||||||
|
실제로 어떤 의미인지 생각해보자. `/gsd-plan-phase`를 실행하면 오케스트레이터는:
|
||||||
|
|
||||||
|
1. 압축된 JSON 컨텍스트 페이로드(프로젝트 요약, 단계 목표, 관련 설정)를 로드한다.
|
||||||
|
2. 200k 토큰의 깨끗한 윈도우로 리서처 에이전트를 생성한다.
|
||||||
|
3. 리서치 출력물과 단계 요구 사항을 가진 플래너 에이전트를 생성한다.
|
||||||
|
4. 실행 전에 계획을 검증하는 계획 검사기 에이전트를 생성한다.
|
||||||
|
|
||||||
|
각 에이전트는 세션의 누적된 이력으로 부담받지 않고, 최대 능력으로 작동한다. 플래너가 `PLAN.md` 파일들을 `.planning/phases/`에 작성할 때, 그 출력물은 내구성 있는 결과물이 된다 — 공유 컨텍스트 윈도우 속에서 깨지기 쉬운 기억이 아니라.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 명세 주도 개발과 메타 프롬프팅
|
||||||
|
|
||||||
|
컨텍스트 엔지니어링만으로는 충분하지 않다. 에이전트가 신선하게 시작하더라도 모호한 지시 사항을 받으면 모호한 결과물을 생성한다. GSD Core는 신선한 컨텍스트 서브에이전트와 두 가지 보완적인 원칙을 함께 사용한다.
|
||||||
|
|
||||||
|
**명세 주도 개발**은 모든 단계가 실행 전에 구조화된 결과물을 생성한다는 것을 의미한다. `CONTEXT.md`는 논의 단계의 구현 결정 사항들을 캡처한다. `RESEARCH.md`는 리서처가 발견한 내용을 기록한다. `PLAN.md`는 명시적인 수락 기준을 가진 개별적인 의존성 순서의 작업들로 작업을 분해한다. 실행 에이전트가 파일에 손을 대는 시점에는 긴 대화의 재해석이 아닌 정확한 명세를 가지고 있다.
|
||||||
|
|
||||||
|
**메타 프롬프팅**은 에이전트 정의 자체가 애드혹 지시 사항이 아닌 신중하게 설계된 프롬프트라는 것을 의미한다. `get-shit-done/workflows/`와 `agents/`의 파일들은 작업의 범위를 지정하는 방법, 무엇을 검증해야 하는지, 언제 사람에게 체크포인트를 요청해야 하는지에 대한 소중한 지식을 담고 있다. 사용자는 매 세션마다 이 지식을 다시 설명할 필요가 없다; 그것은 시스템 자체의 프롬프트에 이미 내장되어 있다.
|
||||||
|
|
||||||
|
이 조합은 의도적이다. 신선한 컨텍스트는 각 에이전트가 명확하게 추론하도록 보장한다. 명세 주도 결과물은 각 에이전트가 *올바른* 것에 대해 추론하도록 보장한다. 메타 프롬프팅은 각 에이전트가 *어떻게* 잘 추론해야 하는지 알도록 보장한다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## `.planning/`의 역할
|
||||||
|
|
||||||
|
컨텍스트 엔지니어링은 지식이 컨텍스트 리셋을 통해 살아남아야 한다는 것을 요구한다. GSD Core는 이를 위해 파일 시스템을 사용한다. 모든 의미 있는 출력물은 사람이 읽을 수 있는 마크다운 또는 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)를 참조하라.
|
||||||
|
|
||||||
|
단계 루프는 컨텍스트 부패가 실제 위험인 만큼 복잡한 작업 — 다중 파일 기능, 횡단 관심사 리팩터링, 몇 시간 또는 여러 세션에 걸친 작업 — 에서 그 가치를 발휘한다. 그 외의 경우에는 더 가벼운 기본 도구를 사용하라.
|
||||||
|
|
||||||
|
유용한 경험 법칙: 단일 짧은 프롬프트로 완전히 명시되고 더 이상의 설명 없이 에이전트 한 번의 작업으로 완료될 수 있다면, 단계 루프를 건너뛰어라. 리서치가 필요하거나, 최근에 읽지 않은 파일이 포함되거나, 아직 결정되지 않은 사항에 의존한다면, 단계 루프가 보호해준다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [단계 루프](the-phase-loop.md) — 논의 → 계획 → 실행 → 검증 → 출시 사이클이 컨텍스트 엔지니어링을 실천에 옮기는 방법
|
||||||
|
- [다중 에이전트 오케스트레이션](multi-agent-orchestration.md) — 서브에이전트가 생성, 범위 지정, 조율되는 방법
|
||||||
|
- [아키텍처](../ARCHITECTURE.md) — 시스템 아키텍처, 에이전트 모델, 데이터 흐름
|
||||||
|
- [문서 인덱스](../README.md)
|
||||||
151
docs/ko-KR/explanation/multi-agent-orchestration.md
Normal file
151
docs/ko-KR/explanation/multi-agent-orchestration.md
Normal file
@@ -0,0 +1,151 @@
|
|||||||
|
# GSD Core의 다중 에이전트 오케스트레이션
|
||||||
|
|
||||||
|
> **설명** — 이 문서는 GSD Core가 다중 에이전트 오케스트레이션을 중심으로
|
||||||
|
> 설계된 *이유*와 *구성 요소들이 어떻게 맞물리는지*를 설명한다. 단계별
|
||||||
|
> 가이드가 아니다. 설정에 대해서는
|
||||||
|
> [모델 프로필 설정](../how-to/configure-model-profiles.md)과
|
||||||
|
> [설정 레퍼런스](../CONFIGURATION.md)를 참조하라. 전체 에이전트 목록은
|
||||||
|
> [인벤토리](../INVENTORY.md)를 참조하라.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 이 설계가 해결하는 문제
|
||||||
|
|
||||||
|
AI 코딩 에이전트는 저하된다. 모델이 나빠지기 때문이 아니라 *컨텍스트 윈도우가 채워지기* 때문이다. 대화가 길어질수록 초반의 결정들과 코드가 중간 단계들의 노이즈에 밀려나거나 희석된다. 복잡한 작업에서 다섯 번째 파일을 작성할 때쯤 에이전트는 첫 번째 메시지에서 명시된 제약 조건을 이미 잊었을 수도 있다. 이를 *컨텍스트 부패*라고 부르기도 한다.
|
||||||
|
|
||||||
|
GSD Core의 다중 에이전트 설계는 그 문제에 대한 직접적인 대응이다. 하나의 장시간 실행 에이전트가 전체 세션을 담당하는 대신, 얇은 오케스트레이터가 **신선한 200K 토큰 컨텍스트 윈도우**와 *자신의 특정 작업을 수행하는 데 필요한 결과물만* 갖고 시작하는 단수명 전문화 에이전트들을 생성한다. 오케스트레이터 자신은 절대 무거운 작업을 하지 않는다; 컨텍스트를 로드하고, 적합한 에이전트를 생성하고, 결과를 수집하고, `.planning/`의 공유 상태를 업데이트한다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 오케스트레이터 → 에이전트 패턴
|
||||||
|
|
||||||
|
`get-shit-done/workflows/`의 모든 워크플로우는 동일한 형태를 따른다:
|
||||||
|
|
||||||
|
```text
|
||||||
|
오케스트레이터 (워크플로우 .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
|
||||||
|
계획 01 (의존성 없음) ─┐
|
||||||
|
계획 02 (의존성 없음) ─┤─── 웨이브 1 (병렬)
|
||||||
|
계획 03 (의존: 01) ─┤─── 웨이브 2 (웨이브 1 대기)
|
||||||
|
계획 04 (의존: 02) ─┘
|
||||||
|
계획 05 (의존: 03, 04) ─── 웨이브 3 (웨이브 2 대기)
|
||||||
|
```
|
||||||
|
|
||||||
|
웨이브 내 각 실행기는:
|
||||||
|
|
||||||
|
- 신선한 컨텍스트 윈도우(200K 토큰, 또는 지원 모델에서 최대 1M)를 받는다
|
||||||
|
- 담당하는 특정 `PLAN.md`를 받는다
|
||||||
|
- 프로젝트 컨텍스트(`PROJECT.md`, `STATE.md`)를 받는다
|
||||||
|
- 단계 컨텍스트(가용한 경우 `CONTEXT.md`, `RESEARCH.md`)를 받는다
|
||||||
|
- 완료 시 원자적 git 커밋을 생성한다
|
||||||
|
- 만들어진 것을 설명하는 `SUMMARY.md`를 작성한다
|
||||||
|
|
||||||
|
웨이브의 모든 실행기가 완료된 후, 오케스트레이터는 전체 웨이브에 대해 한 번 사전 커밋 훅을 실행한다. 실행기는 여러 에이전트가 병렬로 커밋할 때의 빌드 잠금 경합(예: Rust 프로젝트의 Cargo 잠금 충돌)을 방지하기 위해 `--no-verify`로 커밋한다. 따라서 훅은 커밋당 한 번이 아닌 웨이브당 한 번 실행된다.
|
||||||
|
|
||||||
|
### 병렬 커밋 안전성
|
||||||
|
|
||||||
|
여러 실행기가 동시에 실행될 때 쓰기 충돌을 방지하는 두 가지 메커니즘이 있다:
|
||||||
|
|
||||||
|
1. **`STATE.md`에 대한 원자적 잠금** — `STATE.md`에 대한 모든 쓰기는 `O_EXCL` 원자적 생성을 사용하는 잠금파일(`STATE.md.lock`)을 사용한다. 이는 두 에이전트가 각각 파일을 읽고, 서로 다른 필드를 수정하고, 나중에 쓰는 쪽이 먼저 쓴 쪽의 변경 사항을 덮어쓰는 읽기-수정-쓰기 경합 조건을 방지한다. 오래된 잠금(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)을 참조하라.
|
||||||
|
|
||||||
|
다중 에이전트 오케스트레이션은 두 가지 방식으로 컨텍스트 엔지니어링을 구현한다:
|
||||||
|
|
||||||
|
**컨텍스트 격리.** 각 에이전트는 필요한 것만 받는다. 리서처는 프로젝트 설명과 도메인 질문들을 받는다; 전체 계획 이력은 받지 않는다. 검증기는 모든 계획과 요약을 받는다; 원시 리서치는 받지 않는다. 격리는 각 에이전트의 컨텍스트를 다른 파이프라인 단계들의 노이즈로 희석되지 않고 신호로 밀도 있게 유지한다.
|
||||||
|
|
||||||
|
**세션 간 컨텍스트 위생.** 모든 상태가 사람이 읽을 수 있는 마크다운과 JSON으로 `.planning/`에 저장되기 때문에(에이전트의 컨텍스트 윈도우가 아닌), GSD 워크플로우는 컨텍스트 리셋(`/clear`), 탭 전환, 며칠간의 휴식을 견뎌낸다. 다음 에이전트는 항상 긴 대화의 재구성된 기억이 아닌 영속적이고 검증된 결과물에서 시작한다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 트레이드오프
|
||||||
|
|
||||||
|
다중 에이전트 오케스트레이션은 비용이 없지 않다.
|
||||||
|
|
||||||
|
**조율 오버헤드.** 각 에이전트 생성은 왕복이다: 오케스트레이터가 프롬프트를 형식화하고, 컨텍스트를 넘기고, 서브에이전트가 완료될 때까지 기다리고(일반적으로 1-5분), 결과를 파싱해야 한다. 하나의 컨텍스트에서 작동하는 단일 능력 있는 에이전트는 단순한 작업에서 더 빨리 완료될 것이다. GSD는 의존성이 허용되는 모든 곳에서 병렬성을 기본값으로 만들어 이를 완화한다 — `plan-phase`의 네 리서처들은 순차적이 아닌 동시에 실행된다.
|
||||||
|
|
||||||
|
**실행 중 불투명성.** 서브에이전트가 실행되는 동안 그 작업은 부모 세션에서 보이지 않는다. 실시간 진행 스트림이 없다. 이것은 신선한 컨텍스트 설계의 의도적인 결과이다: 서브에이전트가 자체 컨텍스트 윈도우에서 작동하고 있다. 오케스트레이터는 생성 라인에 활성 표시를 보여줌으로써("서브에이전트에서 실행됨 — 반환될 때까지 출력 없음") 기대치를 설정한다.
|
||||||
|
|
||||||
|
**컨텍스트 스티칭 비용.** 각 에이전트에 적합한 결과물들을 패키징하려면 오케스트레이터가 컨텍스트 페이로드를 조립하고 전송하는 데 토큰을 소비해야 한다. 이것이 격리의 비용이다. `gsd-tools.cjs init` 핸들러는 완전성과 토큰 예산의 균형을 맞추는 JSON 페이로드를 생성하며, 반복 호출에서 캐시에 도달하도록 캐시 친화적 순서를 적용한다.
|
||||||
|
|
||||||
|
**모델 비용 증폭.** Opus 등급으로 다섯 개의 에이전트를 병렬로 실행하는 것은 하나를 실행하는 것보다 더 비용이 많이 든다. 모델 프로필 시스템(`model_profiles.md`, `model-profiles.cjs`에 의해 에이전트별로 해결됨)을 사용하면 덜 중요한 에이전트에 더 저렴한 등급을 할당할 수 있다. `dynamic_routing` 기능은 모든 에이전트를 더 저렴한 등급에서 시작하고 소프트 실패 시에만 에스컬레이션함으로써 비용을 더 줄여준다. 전체 옵션은 [설정](../CONFIGURATION.md)을 참조하라.
|
||||||
|
|
||||||
|
이런 비용의 대가로 이 설계는 *대형 단계에서의 일관된 품질*을 제공한다. 400줄 계획의 열 번째 파일을 작성하는 실행기는 컨텍스트가 신선하기 때문에 저하되지 않는다. 스무 개의 요구 사항을 확인하는 검증기는 처음 열 개를 잊지 않는다. 왜냐하면 대화 이력이 아닌 구조화된 입력으로 모두 받았기 때문이다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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)
|
||||||
123
docs/ko-KR/explanation/security-model.md
Normal file
123
docs/ko-KR/explanation/security-model.md
Normal file
@@ -0,0 +1,123 @@
|
|||||||
|
# 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의 보안 모델은 하나의 조직 원칙을 중심으로 구축된다: **심층 방어(defence in depth)**. 어떤 단일 제어도 완벽하다고 가정하지 않는다. 여러 겹치는 계층이 각각 고유한 종류의 위험을 줄이며, 함께 공격 표면을 완전히 제거하지는 않지만 악용하기 상당히 더 어렵게 만든다. 이 문서 끝의 솔직한 요약은 시스템이 방어할 수 없는 것을 설명한다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 계층 1 — 공급망 보호: 패키지 적법성 게이트
|
||||||
|
|
||||||
|
### 위협
|
||||||
|
|
||||||
|
AI 모델은 패키지 이름을 환각한다. 이것은 변두리 실패 모드가 아니다: 2025년 연구에서 AI가 생성한 패키지 참조의 약 20%가 합법적인 패키지와 대응되지 않는 환각된 이름으로 문서화되었다. 그 환각된 이름들의 일부 — 같은 연구에서 약 43% — 는 프롬프트 전반에 걸쳐 일관되게 반복되며, 이는 공격자가 AI 도구들이 일반적으로 생성하는 이름을 관찰하고 악의적인 설치 후 스크립트로 npm, PyPI, 또는 crates.io에 해당 이름들을 선점 등록할 수 있다는 것을 의미한다. 이 기법을 *슬롭스쿼팅(slopsquatting)*이라고 한다.
|
||||||
|
|
||||||
|
슬롭스쿼팅의 교활한 특성은 `npm view`를 통과하는 환각된 이름이 *합법적으로 보인다*는 것이다. 레지스트리 항목은 누군가가 이름을 등록했다는 것만 증명한다 — AI가 말한 것을 패키지가 한다거나, 합법적인 사용자가 있다거나, 설치 스크립트가 안전하다는 것은 증명하지 않는다. 게이트 없이는 환각된 이름이 GSD의 리서처 → 플래너 → 실행기 파이프라인을 통해 감지되지 않고 흐르다가 결국 사용자의 기계에서 `npm install <attacker-package>`로 실행될 것이다.
|
||||||
|
|
||||||
|
### 게이트 작동 방식
|
||||||
|
|
||||||
|
게이트는 세 가지 파이프라인 단계에 걸쳐 작동한다:
|
||||||
|
|
||||||
|
**리서치 단계.** `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 시스템 프롬프트가 되는 마크다운 파일을 생성한다. 리서치 파이프라인은 외부 웹 콘텐츠를 읽는다; 계획 파이프라인은 사용자가 제공한 텍스트(`--text-file`, `--prd`)를 통합한다; 실행 파이프라인은 에이전트 컨텍스트로 나중에 다시 읽히는 계획 결과물을 작성한다. 이런 결과물들에 흐르는 사용자가 제어하는 텍스트는 잠재적인 **간접 프롬프트 인젝션** 벡터이다 — 시스템 프롬프트 안에 들어가면 에이전트의 지시 사항을 재정의하거나 정보를 유출하려는 공격자가 제어하는 문자열.
|
||||||
|
|
||||||
|
### 방어 작동 방식
|
||||||
|
|
||||||
|
GSD Core는 세 가지 수준에서 프롬프트 인젝션을 다룬다.
|
||||||
|
|
||||||
|
**입력 유효성 검사(`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 소스 자체의 인젝션 시도를 잡아낸다 — 예를 들어 워크플로우 파일을 수정하여 역할 재정의 지시 사항을 추가하는 공급망 공격.
|
||||||
|
|
||||||
|
### 읽기 인젝션 스캐너 vs 프롬프트 가드
|
||||||
|
|
||||||
|
두 훅은 보완적인 표면을 커버한다. `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를 실패시킨다.
|
||||||
|
|
||||||
|
**로케일 안전 텍스트 스캔.** 출력 및 사용자 대면 문자열은 유니코드 동형 문자, 양방향 오버라이드 문자, 보이지 않는 유니코드에 대해 스캔된다 — 차이점에서 악의적인 콘텐츠를 숨길 수 있는 CVE-2021-42574("Trojan Source")에 문서화된 공격 클래스.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 트레이드오프와 한계
|
||||||
|
|
||||||
|
여기에 설명된 보안 모델은 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/ko-KR/explanation/the-phase-loop.md
Normal file
129
docs/ko-KR/explanation/the-phase-loop.md
Normal file
@@ -0,0 +1,129 @@
|
|||||||
|
# 단계 루프
|
||||||
|
|
||||||
|
> GSD Core가 작업을 조직하는 방식의 핵심 멘탈 모델.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 루프란 무엇인가
|
||||||
|
|
||||||
|
GSD Core는 모든 개발 작업을 반복되는 사이클로 구조화한다.
|
||||||
|
|
||||||
|
```text
|
||||||
|
논의 → (UI 디자인) → 계획 → 실행 → 검증 → 출시
|
||||||
|
```
|
||||||
|
|
||||||
|
모든 작업 단위 — **단계(phase)**라고 부름 — 는 이 순서대로 각 단계를 거친다. 루프는 형식적인 절차가 아니다. 각 단계는 이전 단계 혼자서는 방지할 수 없는 특정 종류의 실패를 막기 위해 존재한다.
|
||||||
|
|
||||||
|
이 문서는 루프가 이런 형태를 갖는 *이유*를 설명한다. 각 단계를 실행하는 방법에 대한 지침은 하단에 링크된 how-to 가이드를 참조하라.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 각 단계가 존재하는 이유
|
||||||
|
|
||||||
|
### 논의(Discuss)
|
||||||
|
|
||||||
|
무엇을 만들어야 하는지뿐만 아니라 *어떻게* 만들어야 하는지를 알기 전까지는 계획을 시작할 수 없다. `ROADMAP.md`의 단계 목표는 결과를 설명한다. 논의 단계는 그 결과로 가는 경로를 형성하는 구현 결정 사항들을 캡처한다: 어떤 라이브러리를 사용할지, 오류 처리 전략, 기능이 라우트별인지 전역인지, 엣지 케이스의 동작 방식.
|
||||||
|
|
||||||
|
논의 단계 없이는 플래너가 이런 결정들을 스스로 내려야 한다. 때로는 맞게 추측하기도 한다. 그러나 그럴듯하지만 틀리게 추측하는 경우도 많다 — 일관성은 있지만 실제 선호도와 맞지 않는 계획을 생성한다. 실행이 완료되고 오류를 발견했을 때는 이미 상당한 작업을 되돌려야 하는 상황이 된다.
|
||||||
|
|
||||||
|
논의 단계는 의도적으로 가볍다. 명세 작성 훈련이 아니라 대화이다. 출력물은 단계 디렉터리의 `CONTEXT.md`이다: 플래너, 실행기, 검증기 모두 읽을 수 있는 결정 사항들의 구조화된 기록. 대화는 몇 분이 걸리지만; 수 시간의 재작업을 절약할 수 있다.
|
||||||
|
|
||||||
|
### UI 디자인(선택적)
|
||||||
|
|
||||||
|
시각적 컴포넌트가 있는 단계의 경우, 논의와 계획 사이에 선택적인 `/gsd-ui-phase` 단계가 있다. 코드 작성 전에 레이아웃, 인터랙션, 시각적 동작을 설명하는 디자인 계약인 `UI-SPEC.md`를 생성한다. UI가 복잡하여 디자인의 모호함이 다양한 구현 선택을 만들어낼 만큼 복잡할 때 이 단계를 실행할 가치가 있다. 명확한 디자인 계약은 재구현보다 훨씬 비용이 저렴하다.
|
||||||
|
|
||||||
|
### 계획(Plan)
|
||||||
|
|
||||||
|
계획 단계는 실행에 필요한 리서치, 분해, 구조적 사고를 수행한다. 신선한 컨텍스트 서브에이전트들의 시퀀스로 실행된다: 생태계를 조사하고 `RESEARCH.md`에 결과를 기록하는 리서처, 리서치와 `CONTEXT.md` 모두를 읽어 `PLAN.md` 파일들을 생성하는 플래너, 계획이 완전하고 일관성 있으며 범위 내에 있는지 검증하는 계획 검사기.
|
||||||
|
|
||||||
|
계획에는 무엇이 포함되는가? 각 `PLAN.md`는 작업의 범위가 한정된 단위를 설명한다: 수정할 파일들, 수행할 구체적인 변경 사항들, 완료를 정의하는 수락 기준. 계획들은 병렬 실행이 안전하도록 의존성 웨이브 순서로 정렬된다 — 같은 웨이브의 실행기들은 겹치지 않는 관심사를 다룬다.
|
||||||
|
|
||||||
|
계획 단계는 모호함이 가장 비용이 많이 드는 순간이다. 모호한 계획은 가정을 세우는 실행기를 만든다. 같은 관심사에 대해 서로 다른 가정을 세우는 여러 병렬 실행기들은 충돌을 만든다. 계획 검사기의 임무는 실행 전에 이런 문제들을 잡아내는 것이다.
|
||||||
|
|
||||||
|
### 실행(Execute)
|
||||||
|
|
||||||
|
실행은 계획들을 수행한다. 각 실행기는 자신에게 필요한 것들만 정확히 담긴 신선한 200k 토큰 컨텍스트 윈도우를 받는다: 프로젝트 요약, 단계 컨텍스트, 리서치, 그리고 자신의 작업에 대한 특정 `PLAN.md`. 그 이상은 없다.
|
||||||
|
|
||||||
|
실행기는 코드를 작성하고 원자적으로 커밋한다. 각 커밋은 계획에서 완료된 작업과 대응된다. 병렬 실행기들의 웨이브가 완료되면, 오케스트레이터는 상태를 병합하고 다음 웨이브를 시작한다.
|
||||||
|
|
||||||
|
실행기의 신선한 컨텍스트는 편의를 위한 것이 아니다 — 컨텍스트 부패를 방지하는 메커니즘이다. 180k 토큰의 누적된 세션 이력으로 실행되는 실행기는 저하된 실행기이다. 깨끗하게 시작하고 계획이 필요로 하는 것만 읽는 실행기는 최대 능력으로 작동하는 실행기이다.
|
||||||
|
|
||||||
|
### 검증(Verify)
|
||||||
|
|
||||||
|
모든 실행기가 완료된 후, 검증기 에이전트는 단계 목표, `CONTEXT.md` 결정 사항들, 계획들, 실행 요약들을 읽고 — 만들어진 것이 의도한 것과 일치하는지 확인한다. `VERIFICATION.md`를 생성하고, 불일치가 있으면 대상이 명확한 수정 계획을 생성한다.
|
||||||
|
|
||||||
|
검증은 단순한 테스트가 아니다. 요구 사항 커버리지(모든 REQ-ID가 처리되었는가?), 결정 커버리지(`CONTEXT.md`에 캡처된 결정 사항들이 실제로 구현되었는가?), 전반적인 단계 목표 정렬을 확인한다. 단계는 실행이 오류 없이 완료되었기 때문에 완료되는 것이 아니다. 만들어진 것이 계획된 것이고, 계획된 것이 결정된 것이기 때문에 완료된다.
|
||||||
|
|
||||||
|
### 출시(Ship)
|
||||||
|
|
||||||
|
출시 단계는 풀 리퀘스트를 생성하고 단계 결과물들을 아카이브한다. `STATE.md`가 업데이트되어 단계 완료를 표시한다. 루프가 다음 단계를 위해 다시 시작된다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 마일스톤과 단계
|
||||||
|
|
||||||
|
**마일스톤**은 버전 사이클 — 프로젝트의 의미 있고 릴리스 가능한 증분이다. 이름, 버전 번호, 그리고 무엇을 제공해야 하는지 정의하는 요구 사항들의 집합을 갖는다. 마일스톤은 모든 단계들이 출시되고 요구 사항들이 충족되면 완료된다.
|
||||||
|
|
||||||
|
**단계**는 마일스톤 내의 하나의 작업 단위이다. 단계는 목표, 처리하는 요구 사항들의 집합, 그리고 그것을 구현하는 계획들의 집합을 갖는다.
|
||||||
|
|
||||||
|
이 관계가 중요한 이유는 마일스톤과 단계가 서로 다른 관심 범위를 갖기 때문이다. 마일스톤은 묻는다: "이 버전의 제품은 무엇을 하고, 무엇을 하지 않는가?" 단계는 묻는다: "우리가 다음으로 연구하고, 계획하고, 실행하고, 검증할 수 있는 범위가 한정된 것은 무엇인가?"
|
||||||
|
|
||||||
|
마일스톤 경계는 자연스러운 제품 경계에서 그어진다 — 배포 가능한 API, 작동하는 UI 플로우, 완전한 데이터 모델. 단계 경계는 루프가 다루기 힘들어지지 않고 하나의 루프에서 안전하게 실행될 수 있는 범위의 한계에서 그어진다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 좋은 단계 범위란 무엇인가
|
||||||
|
|
||||||
|
이것은 루프와 관련된 마찰의 가장 일반적인 원인이기 때문에 심층적으로 살펴볼 가치가 있다.
|
||||||
|
|
||||||
|
너무 큰 단계는 그 자체로 리서치 프로젝트가 된다. 플래너는 독립적인 계획들로 분해하는 데 어려움을 겪는다. 이후 웨이브의 실행기들이 이전 웨이브를 기다리며 막힌다. 검증이 대상이 명확한 리뷰보다 전체 감사가 된다. 피드백 사이클이 몇 시간에서 며칠로 늘어나고, 많은 코드가 작성된 후에야 — 근본적인 설계 오류를 발견할 위험이 급격히 높아진다.
|
||||||
|
|
||||||
|
너무 작은 단계는 자연스럽게 함께 속하는 작업을 분할한다. 몇 줄에 불과한 계획 파일들, 몇 분 안에 완료되는 단계들, 실행 비용을 압도하는 계획 오버헤드가 발생한다. 루프가 도움이 되기보다 관료적으로 느껴진다.
|
||||||
|
|
||||||
|
좋은 단계 범위는 다음과 같은 경우이다:
|
||||||
|
|
||||||
|
- 목표가 명백히 사소하지도 않고 의심스럽게 광범위하지도 않은 하나의 문장으로 명시될 수 있다.
|
||||||
|
- 계획에 필요한 리서치가 제한되어 있다 — 생태계 질문들이 다른 단계들이 먼저 완료되는 것에 의존하지 않는 답을 가진다.
|
||||||
|
- 실행이 수십 개가 아니라 소수의 겹치지 않는 계획들로 병렬화될 수 있다.
|
||||||
|
- 검증기가 전체 코드베이스를 읽지 않고도 확인할 수 있는 명확하고 테스트 가능한 완료 정의가 있다.
|
||||||
|
|
||||||
|
구체적으로: "HMAC-SHA256 서명 검증 미들웨어 추가"는 좋은 단계 범위이다. "인증 시스템 구축"은 일반적으로 아니다 — 거의 항상 별도의 단계로 더 잘 처리될 여러 독립적인 관심사들을 포함한다. "README의 오타 수정"은 루프가 가치를 추가하는 임계값 아래이다; 대신 `/gsd-quick`을 사용하라.
|
||||||
|
|
||||||
|
의심스러울 때는 분할하라. 더 작은 단계는 더 빨리 완료되고, 더 자신 있게 검증되고, 설계 결정이 잘못된 것으로 판명될 경우 방향을 수정하기 더 쉽다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## `.planning/`이 루프 전반에 걸쳐 상태를 유지하는 방법
|
||||||
|
|
||||||
|
루프는 단일 세션이 아니다. 리서치, 계획 수립, 실행은 그 사이에 컨텍스트 리셋이 있는 여러 세션에 걸쳐 발생할 수 있다. `.planning/` 디렉터리가 이것을 가능하게 한다.
|
||||||
|
|
||||||
|
루프의 모든 단계는 이전 단계에서 생성된 결과물들을 읽고 이후 단계를 위한 결과물들을 작성한다. 논의 단계가 생성하는 CONTEXT.md는 플래너가 실행될 때도 사용 가능하다 — 몇 시간 후 다른 세션에서 실행되더라도. 플래너가 생성하는 PLAN.md 파일들은 실행기가 실행될 때도 사용 가능하다 — 재시작 후에도. 검증기가 작성하는 VERIFICATION.md는 단계를 검토할 때도 사용 가능하다.
|
||||||
|
|
||||||
|
`STATE.md`는 이 모든 것 위에 있는 내비게이션 레이어이다. 프로젝트가 루프의 정확히 어느 위치에 있는지 기록한다: 어느 마일스톤이 활성 상태인지, 어느 단계가 진행 중인지, 어느 계획들이 완료되고 어느 것들이 대기 중인지. 방향을 잡아야 하는 에이전트나 워크플로우는 먼저 `STATE.md`를 읽는다.
|
||||||
|
|
||||||
|
이 파일들의 정확한 구조는 [계획 결과물](../reference/planning-artifacts.md)과 [STATE.md 스키마](../reference/state-md.md)를 참조하라.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 루프는 리듬이지 제약이 아니다
|
||||||
|
|
||||||
|
루프를 관료주의로 바라보는 시각이 있다 — 코드를 작성하기 전에 수행해야 하는 일련의 필수 단계들. 그 프레임은 틀렸다.
|
||||||
|
|
||||||
|
루프는 각 단계가 나중에 수정하는 데 실제로 비용이 많이 드는 실패들을 방지하기 때문에 존재한다. 논의는 잘못된 가정 위에서 계획하는 것을 방지한다. 계획은 근본적으로 깨진 설계를 실행하는 것을 방지한다. 검증은 요약 사항을 놓친 작업을 출시하는 것을 방지한다. 이것들은 인위적인 문제가 아니다. 실제 기능 규모에서 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/ko-KR/how-to/configure-model-profiles.md
Normal file
218
docs/ko-KR/how-to/configure-model-profiles.md
Normal file
@@ -0,0 +1,218 @@
|
|||||||
|
# 모델 프로파일을 설정하는 방법
|
||||||
|
|
||||||
|
프로젝트에 적합한 모델 티어 전략을 선택한 다음, 대규모 재정의 블록을 작성하지 않고 개별 에이전트나 전체 페이즈 유형을 조정하세요. 이 가이드는 가장 간단한 방법부터 시작하여 동적 라우팅까지 다룹니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 네 가지 프로파일 (`adaptive`와 `inherit` 포함)
|
||||||
|
|
||||||
|
`.planning/config.json`에서 `model_profile`을 설정하거나 `/gsd-config --profile <name>`을 사용하세요:
|
||||||
|
|
||||||
|
| 프로파일 | 플래너 | 실행자 | 리서처 | 검증자 | 사용 시기 |
|
||||||
|
|---------|---------|----------|-------------|----------|----------|
|
||||||
|
| `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` 블록을 사용하세요. 여섯 가지 페이즈 유형을 티어 별칭으로 매핑합니다:
|
||||||
|
|
||||||
|
```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"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
5개의 리서치 에이전트 모두 `sonnet`으로 해결되지만, `gsd-codebase-mapper`는 `haiku`로 고정됩니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 동적 라우팅 — 기본 저렴하게, 실패 시 에스컬레이션
|
||||||
|
|
||||||
|
기본적으로 저렴한 티어를 사용하고 에이전트가 품질 게이트에 실패할 때만 에스컬레이션하려면 `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]`를 선택합니다. 오케스트레이터가 소프트 실패(검증 불확실, 플랜 체크 플래그 등)를 감지하면 한 티어 위로 에이전트를 재실행합니다. `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 네이티브 모델 및 추론 노력으로 해결합니다.
|
||||||
|
|
||||||
|
**비 Claude 런타임에서 에이전트별 모델 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. 런타임 기본값 — 다른 것이 적용되지 않을 때
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 올바른 방법 선택
|
||||||
|
|
||||||
|
| 원하는 것 | 사용할 것 |
|
||||||
|
|---|---|
|
||||||
|
| 모든 에이전트에 단일 티어 전략 | `model_profile` |
|
||||||
|
| 거친 페이즈 레벨 조정 ("기획에 Opus") | `models.<phase_type>` |
|
||||||
|
| 에이전트별 정밀도 ("코드베이스 매퍼에 Haiku 강제") | `model_overrides[<agent>]` |
|
||||||
|
| 특정 에이전트에 완전히 정규화된 모델 ID | `model_overrides[<agent>]: "openai/gpt-5"` |
|
||||||
|
| 기본적으로 저렴하게, 실패 시만 에스컬레이션 | `dynamic_routing` |
|
||||||
|
| 모든 에이전트가 세션 모델을 따름 (비 Anthropic 프로바이더) | `model_profile: "inherit"` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
|
||||||
|
- [설정 참조](../CONFIGURATION.md)
|
||||||
|
- [멀티 에이전트 오케스트레이션](../explanation/multi-agent-orchestration.md)
|
||||||
|
- [명령어 참조](../COMMANDS.md)
|
||||||
|
- [문서 목차](../README.md)
|
||||||
178
docs/ko-KR/how-to/debug-a-failed-execution.md
Normal file
178
docs/ko-KR/how-to/debug-a-failed-execution.md
Normal file
@@ -0,0 +1,178 @@
|
|||||||
|
# 실패한 실행을 디버그하는 방법
|
||||||
|
|
||||||
|
**목표:** 페이즈 실행이 실패하거나, 멈추거나, 불완전한 결과를 생성했을 때 — 이미 성공한 작업을 잃거나 반복하지 않고 깔끔하게 복구하고 재개합니다.
|
||||||
|
|
||||||
|
**사전 조건:** `/gsd-execute-phase N`을 실행했는데 `VERIFICATION.md` 작성 전에 실행이 중단된 경우, 또는 예상치 못한 출력, 누락된 파일, 멈춘 스피너가 보이는 경우.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 실행이 멈췄는지 실패했는지 감지
|
||||||
|
|
||||||
|
복구 조치를 취하기 전에 실제로 무슨 일이 일어났는지 파악합니다.
|
||||||
|
|
||||||
|
### "Spawning…"만 표시되고 1~5분 후에도 출력이 없는 경우
|
||||||
|
|
||||||
|
이것은 정상 동작이며 멈춤이 아닙니다. GSD 서브에이전트는 격리된 컨텍스트 창에서 실행됩니다. 스폰 라인의 활성 상태 메모가 이를 확인해 줍니다. 세션을 중단하지 마세요.
|
||||||
|
|
||||||
|
10분 이상 결과가 없다면 Claude Code 사이드바를 확인하세요. 에이전트 작업이 완료된 것으로 표시되지만 출력이 나타나지 않았다면 컨텍스트 전환에서 결과가 손실되었을 수 있습니다 — 동일한 명령을 다시 실행합니다:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase 1
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD는 실행자를 디스패치하기 전에 `SUMMARY.md` 파일이 있는지 확인합니다. 이미 `SUMMARY.md`가 있는 플랜은 자동으로 건너뜁니다.
|
||||||
|
|
||||||
|
### 실행이 오류 메시지와 함께 파동 중간에 중단된 경우
|
||||||
|
|
||||||
|
git 히스토리를 확인하여 어떤 플랜이 성공적으로 커밋되었는지 확인합니다:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git log --oneline -20
|
||||||
|
```
|
||||||
|
|
||||||
|
작업을 커밋한 플랜은 `feat(01-02): …`와 같은 항목을 가집니다. 커밋이 없는 플랜은 불완전하며 재실행 시 다시 실행됩니다.
|
||||||
|
|
||||||
|
### 실행자가 코드를 커밋했지만 SUMMARY.md를 작성하지 않은 경우
|
||||||
|
|
||||||
|
GSD는 다음 실행 시 이를 감지하고 세 가지 옵션이 있는 안전 재개 게이트를 표시합니다:
|
||||||
|
|
||||||
|
- **수동으로 마무리** — 커밋을 직접 검사하고 `SUMMARY.md`를 작성한 후 재실행합니다.
|
||||||
|
- **처음부터 재실행** — 새 실행자를 디스패치하기 전에 부분 커밋을 되돌리거나 대체합니다.
|
||||||
|
- **표시 후 건너뜀** — 이상 현상을 기록하고 계속 진행하되 명시적인 확인이 필요합니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 근본 원인 진단
|
||||||
|
|
||||||
|
### `/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`는 읽기 전용으로 프로젝트 파일을 절대 수정하지 않습니다.
|
||||||
|
|
||||||
|
**감지 항목:**
|
||||||
|
|
||||||
|
- **반복 루프** — 짧은 시간 내에 연속적으로 세 개 이상의 커밋에 동일한 파일이 나타남(커밋 메시지가 유사하면 HIGH 신뢰도)
|
||||||
|
- **누락된 아티팩트** — 페이즈에 커밋이 있지만 `SUMMARY.md`나 `VERIFICATION.md`가 없음
|
||||||
|
- **방치된 작업** — 커밋되지 않은 변경과 함께 STATE.md가 실행 중간 상태를 표시하고 마지막 커밋이 두 시간 이상 지남
|
||||||
|
- **충돌 또는 중단** — 커밋되지 않은 변경과 활성 실행 상태 및 고아 워크트리가 결합됨
|
||||||
|
- **범위 이탈** — 최근 커밋이 현재 페이즈의 예상 파일 집합 밖의 파일을 수정함
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 복구 후 실행 재개
|
||||||
|
|
||||||
|
근본적인 문제가 해결되면 실행 명령을 다시 실행합니다:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase 1
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD는 이미 `SUMMARY.md`가 존재하는 플랜을 건너뛰고 나머지 플랜에 대해서만 실행자를 디스패치합니다.
|
||||||
|
|
||||||
|
특정 파동만 재실행해야 하는 경우:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase 1 --wave 2
|
||||||
|
```
|
||||||
|
|
||||||
|
디스패치하기 전에 `.planning/` 무결성을 검증하려면:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-execute-phase 1 --validate
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## `/gsd-undo`로 롤백
|
||||||
|
|
||||||
|
실행이 전적으로 버리고 싶은 코드를 생성한 경우, 수동 `git revert` 대신 플랜 매니페스트를 사용하여 롤백합니다:
|
||||||
|
|
||||||
|
### 단일 플랜 롤백
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-undo --plan 03-02
|
||||||
|
```
|
||||||
|
|
||||||
|
페이즈 `3`의 플랜 `02`에 대한 모든 커밋을 되돌립니다. GSD는 변경 사항을 작성하기 전에 확인 게이트를 표시합니다.
|
||||||
|
|
||||||
|
### 전체 페이즈 롤백
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-undo --phase 03
|
||||||
|
```
|
||||||
|
|
||||||
|
페이즈 `3`의 모든 커밋을 되돌립니다. GSD는 이후 페이즈가 이 페이즈에 의존하는지 확인하고 진행 전에 경고합니다.
|
||||||
|
|
||||||
|
### 최근 커밋에서 대화식으로 선택
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-undo --last 5
|
||||||
|
```
|
||||||
|
|
||||||
|
가장 최근 GSD 커밋 다섯 개를 표시하고 어떤 것을 되돌릴지 선택할 수 있게 합니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 중단 후 세션 컨텍스트 복원
|
||||||
|
|
||||||
|
컨텍스트 초기화나 새 세션 후 프로젝트로 돌아온 경우:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-resume-work
|
||||||
|
```
|
||||||
|
|
||||||
|
마지막 핸드오프의 전체 세션 컨텍스트(현재 페이즈, 블로커, 실행이 중단된 위치)를 복원합니다.
|
||||||
|
|
||||||
|
또는 현재 위치를 확인하고 다음 올바른 단계로 자동 진행하려면:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-progress --next
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
|
||||||
|
- [페이즈 실행](execute-a-phase.md)
|
||||||
|
- [복구 및 문제 해결](recover-and-troubleshoot.md)
|
||||||
|
- [명령 참조](../COMMANDS.md)
|
||||||
|
- [문서 인덱스](../README.md)
|
||||||
149
docs/ko-KR/how-to/design-a-ui-phase.md
Normal file
149
docs/ko-KR/how-to/design-a-ui-phase.md
Normal 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는 현재 페이즈를 대상으로 합니다.
|
||||||
|
|
||||||
|
명령은 두 단계로 실행됩니다:
|
||||||
|
|
||||||
|
1. **`gsd-ui-researcher`** — `CONTEXT.md`, `RESEARCH.md`, `REQUIREMENTS.md`에서 기존 결정을 읽고, 디자인 시스템 상태(shadcn `components.json`, Tailwind 설정, 기존 토큰)를 감지하며, 간격, 색상, 타이포그래피, 카피라이팅, 레지스트리 안전성 다섯 영역에 걸쳐 답하지 않은 디자인 질문만 묻습니다.
|
||||||
|
2. **`gsd-ui-checker`** — 결과로 생성된 `UI-SPEC.md`를 여섯 가지 차원에서 검증합니다. 문제가 발견되면 수정 루프가 플래그된 항목만을 대상으로 연구자를 다시 실행합니다(최대 두 번 반복).
|
||||||
|
|
||||||
|
**출력:** `.planning/phases/{phase-dir}/`의 `{padded_phase}-UI-SPEC.md`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## UI-SPEC의 적용 범위
|
||||||
|
|
||||||
|
연구자는 다섯 영역에 걸쳐 결정을 확정합니다:
|
||||||
|
|
||||||
|
| 영역 | 예시 |
|
||||||
|
|---|---|
|
||||||
|
| **간격** | 기본 스케일(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. 경험 디자인 — 로딩, 오류, 빈 상태 커버리지
|
||||||
|
|
||||||
|
**출력:** 점수와 우선순위 상위 세 가지 수정 사항이 포함된 `{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`의 작업은 스펙이 확정한 간격 토큰, 색상 변수, 카피라이팅 결정을 참조합니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
|
||||||
|
- [스파이크와 스케치](spike-and-sketch.md)
|
||||||
|
- [페이즈 계획](plan-a-phase.md)
|
||||||
|
- [명령 참조](../COMMANDS.md)
|
||||||
|
- [문서 인덱스](../README.md)
|
||||||
158
docs/ko-KR/how-to/discuss-a-phase.md
Normal file
158
docs/ko-KR/how-to/discuss-a-phase.md
Normal file
@@ -0,0 +1,158 @@
|
|||||||
|
# 페이즈를 논의하는 방법
|
||||||
|
|
||||||
|
**목표:** 기획이 시작되기 전에 페이즈에 필요한 구현 결정을 수집합니다. 이를 통해 리서처와 플래너가 다시 질문하지 않고도 작업할 수 있습니다.
|
||||||
|
|
||||||
|
**전제 조건:** `.planning/ROADMAP.md`가 존재해야 합니다. 없다면 먼저 `/gsd-new-project`를 실행하세요.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 논의 모드 선택
|
||||||
|
|
||||||
|
GSD Core는 두 가지 모드를 제공합니다. 코드베이스에 대한 이해도에 따라 선택하세요.
|
||||||
|
|
||||||
|
**구현 방향을 직접 표현하고 싶은 경우** (인터뷰 모드, 기본값):
|
||||||
|
|
||||||
|
```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개를 읽고, 근거와 신뢰도와 함께 가정을 형성하여 확인 또는 수정을 위해 제시합니다. 일반적으로 15~20번의 상호작용 대신 2~4번의 상호작용으로 처리됩니다.
|
||||||
|
|
||||||
|
돌아가려면:
|
||||||
|
|
||||||
|
```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
|
||||||
|
```
|
||||||
|
|
||||||
|
모든 프롬프트가 대화형 선택기 대신 일반 텍스트 번호 목록으로 렌더링됩니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 그룹으로 질문 처리
|
||||||
|
|
||||||
|
한 번에 하나씩이 아닌 여러 질문을 동시에 답변하고 싶다면:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-discuss-phase 2 --batch
|
||||||
|
```
|
||||||
|
|
||||||
|
Claude는 한 번에 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는 작성되지 않습니다. 출력을 검토한 후 수정이 필요한 경우 일반 논의 또는 가정 모드 세션을 실행하세요.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## CONTEXT.md의 내용
|
||||||
|
|
||||||
|
논의 모드와 가정 모드 모두 페이즈 디렉터리에 동일한 `{phase}-CONTEXT.md`를 생성합니다. 다운스트림 에이전트(리서처, 플래너, 플랜 체커)는 어떤 모드에서 생성했든 이 파일을 동일하게 읽습니다. 파일은 여섯 개의 섹션으로 구성됩니다:
|
||||||
|
|
||||||
|
| 섹션 | 목적 |
|
||||||
|
|---|---|
|
||||||
|
| `<domain>` | 페이즈 경계 — 이 페이즈가 무엇을 제공하는지 |
|
||||||
|
| `<decisions>` | 세션에서 확정된 구현 결정 사항 |
|
||||||
|
| `<canonical_refs>` | 다운스트림 에이전트가 반드시 읽어야 할 명세, ADR, 문서 |
|
||||||
|
| `<code_context>` | 재사용 가능한 자산, 패턴, 통합 지점 |
|
||||||
|
| `<specifics>` | 사용자 참조 및 선호 사항 |
|
||||||
|
| `<deferred>` | 향후 페이즈를 위해 기록된 아이디어 |
|
||||||
|
|
||||||
|
`<canonical_refs>` 섹션은 필수입니다. 논의 중 문서, 명세, ADR을 참조하면 Claude가 즉시 추가하고 이후 질문에 반영하기 위해 읽습니다.
|
||||||
|
|
||||||
|
전체 필드 참조는 [CONTEXT.md 스키마](../reference/context-md.md)를 참고하세요.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 결정 사항이 기획에 반영되는 방식
|
||||||
|
|
||||||
|
다음에 `/gsd-plan-phase`를 실행할 때 플래너는 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를 합성하고 모든 요구 사항을 확정된 결정으로 처리합니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
|
||||||
|
- [페이즈 기획](plan-a-phase.md)
|
||||||
|
- [논의 모드](../workflow-discuss-mode.md)
|
||||||
|
- [CONTEXT.md 스키마](../reference/context-md.md)
|
||||||
|
- [문서 목차](../README.md)
|
||||||
176
docs/ko-KR/how-to/drive-gsd-from-a-tracker-issue.md
Normal file
176
docs/ko-KR/how-to/drive-gsd-from-a-tracker-issue.md
Normal file
@@ -0,0 +1,176 @@
|
|||||||
|
# 트래커 이슈에서 GSD Core를 구동하는 방법
|
||||||
|
|
||||||
|
**목표:** 사용자 정의 스크립트나 트래커 통합 없이 GSD Core에 이미 존재하는 명령만으로 단일의 명확히 범위가 정해진 GitHub, Linear, 또는 Jira 이슈를 격리된 워크스페이스에서 병합된 PR까지 전체 GSD 파이프라인을 통해 진행합니다.
|
||||||
|
|
||||||
|
**사전 조건:** 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
|
||||||
|
```
|
||||||
|
|
||||||
|
진행 상황을 보고 페이즈 전반에 걸쳐 작업을 디스패치할 수 있는 대화식 대시보드:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-manager
|
||||||
|
```
|
||||||
|
|
||||||
|
세 가지 접근 방식 모두 `STATE.md`를 업데이트하고, 각 작업을 원자적으로 커밋하며, 페이즈 후 검증기를 실행합니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6단계: 작업 검증
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-verify-work N
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD는 페이즈 목표(트래커 이슈를 반영)의 수락 기준을 하나씩 안내합니다. 무언가 실패하면 GSD가 근본 원인을 진단하고 수정 플랜을 만듭니다. 모든 검사가 통과될 때까지 실행과 검증을 반복합니다.
|
||||||
|
|
||||||
|
코드가 올바르게 보여도 `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" # 할 일로 추가
|
||||||
|
/gsd-capture --seed "Idea worth a future phase" # 다음 마일스톤을 위해 보존
|
||||||
|
/gsd-capture --backlog "Not urgent but worth tracking" # 백로그에 저장
|
||||||
|
```
|
||||||
|
|
||||||
|
GSD는 트래커에 자동으로 게시하지 않습니다. 캡처된 후속 작업에서 트래커 이슈를 생성하는 것은 별도의 수동 단계입니다 — 이는 검토 루프에 사람이 참여하도록 유지합니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 조건부 처리
|
||||||
|
|
||||||
|
| 상황 | 할 일 |
|
||||||
|
|-----------|-----------|
|
||||||
|
| 이슈가 매우 작음(오타, 설정 변경) | 워크스페이스 + 논의 + 계획 건너뜀; 대신 `/gsd-quick` 사용 |
|
||||||
|
| 이슈에 여러 독립적인 하위 작업이 있음 | `/gsd-manager`를 사용하여 플랜 전반에 걸쳐 실행 병렬화 |
|
||||||
|
| 이슈가 다른 이슈에 의해 차단됨 | 상위 블로커가 해결될 때까지 시작하지 않음; GSD에는 자동 의존성 폴러가 없음 |
|
||||||
|
| 실행 중간에 이슈 범위가 예상보다 큰 것으로 드러남 | 중단하고, `/gsd-phase --insert N`을 실행하여 하위 페이즈 추가 후 계속 |
|
||||||
|
| 대화식 논의를 건너뛰고 싶음 | `/gsd-discuss-phase`와 함께 `--auto` 플래그 사용, 또는 프로젝트 전체 자동화를 위해 `workflow.skip_discuss: true` 설정 |
|
||||||
|
| 여러 이슈가 일관된 릴리즈를 형성 | `/gsd-new-milestone`으로 그룹화하고 `/gsd-autonomous`로 순서대로 실행 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
|
||||||
|
- [이슈 기반 오케스트레이션 설명](../issue-driven-orchestration.md)
|
||||||
|
- [워크스페이스로 작업 격리](isolate-work-with-workspaces.md)
|
||||||
|
- [검증 및 출시](verify-and-ship.md)
|
||||||
|
- [문서 인덱스](../README.md)
|
||||||
119
docs/ko-KR/how-to/execute-a-phase.md
Normal file
119
docs/ko-KR/how-to/execute-a-phase.md
Normal file
@@ -0,0 +1,119 @@
|
|||||||
|
# 페이즈를 실행하는 방법
|
||||||
|
|
||||||
|
**목표:** 기획된 페이즈를 웨이브 기반 병렬 실행으로 처리하고 각 계획을 원자적 git 커밋으로 완료합니다.
|
||||||
|
|
||||||
|
**전제 조건:** 페이즈에 최소 하나의 `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)을 참고하세요.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 단일 웨이브 실행
|
||||||
|
|
||||||
|
예를 들어 웨이브 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는 안전 재개 게이트를 표시하고 세 가지 옵션을 제공합니다:
|
||||||
|
|
||||||
|
- `수동으로 마무리` — 커밋을 검사하고 `SUMMARY.md`를 작성한 후 재실행
|
||||||
|
- `처음부터 재실행` — 부분 커밋을 되돌리거나 대체한 후 새 실행자 실행
|
||||||
|
- `표시하고 건너뛰기` — 명시적 확인 하에 이상을 기록하고 진행
|
||||||
|
|
||||||
|
체계적인 실패 진단에 대해서는 [실패한 실행 디버그](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
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
|
||||||
|
- [페이즈 기획](plan-a-phase.md)
|
||||||
|
- [검증 및 배포](verify-and-ship.md)
|
||||||
|
- [실패한 실행 디버그](debug-a-failed-execution.md)
|
||||||
|
- [명령어 참조](../COMMANDS.md)
|
||||||
121
docs/ko-KR/how-to/handle-quick-and-fast-tasks.md
Normal file
121
docs/ko-KR/how-to/handle-quick-and-fast-tasks.md
Normal file
@@ -0,0 +1,121 @@
|
|||||||
|
# 빠른 작업과 간단한 작업을 처리하는 방법
|
||||||
|
|
||||||
|
모든 작업이 페이즈 안에 맞는 것은 아닙니다. GSD는 전체 discuss → plan → execute → verify 루프가 필요 없는 작업을 위한 두 가지 경량 명령을 제공합니다.
|
||||||
|
|
||||||
|
전체 페이즈 파이프라인이 오버헤드를 감당할 가치가 있는 경우에 대한 맥락은 [컨텍스트 엔지니어링](../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`) |
|
||||||
|
| 워크트리 격리 | 없음 | 있음 (기본값) |
|
||||||
|
| 태스크당 원자적 커밋 | 단일 커밋 | 계획 태스크당 하나 |
|
||||||
|
| STATE.md 추적 | 테이블이 있으면 행 추가 | 항상 업데이트됨 |
|
||||||
|
| `.planning/quick/` 산출물 | 없음 | 있음 |
|
||||||
|
|
||||||
|
핵심 차이는 서브에이전트 격리입니다. `/gsd-quick`은 별도의 컨텍스트 창에서 새 플래너와 실행자를 실행하므로 작업이 적절히 기획되고 커밋이 태스크당 원자적이며 오케스트레이터가 결과를 검증할 수 있습니다. `/gsd-fast`는 현재 컨텍스트 창만 사용하며 이러한 것이 필요하지 않을 만큼 사소한 변경에 의도적으로 제한됩니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
|
||||||
|
- [페이즈 루프](../explanation/the-phase-loop.md)
|
||||||
|
- [컨텍스트 엔지니어링](../explanation/context-engineering.md)
|
||||||
|
- [명령어 참조](../COMMANDS.md)
|
||||||
|
- [문서 목차](../README.md)
|
||||||
291
docs/ko-KR/how-to/install-on-your-runtime.md
Normal file
291
docs/ko-KR/how-to/install-on-your-runtime.md
Normal 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
|
||||||
|
```
|
||||||
|
|
||||||
|
신규 설치 또는 런타임 전환 후 인스톨러를 재실행할 때 필요한 명령은 이것뿐입니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 런타임별 설치 방법
|
||||||
|
|
||||||
|
### 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 스타일의 플랫 마크다운 명령 형식을 사용합니다.
|
||||||
|
|
||||||
|
**설치 디렉터리 재정의:**
|
||||||
|
|
||||||
|
```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` 파일 및 저장소 지시 파일로 설치됩니다.
|
||||||
|
|
||||||
|
**설치 디렉터리 재정의:**
|
||||||
|
|
||||||
|
```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는 스킬과 에이전트를 설치합니다. 훅 또는 상태 표시줄 소유권은 없습니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 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는 스킬, 에이전트, 규칙 참조를 설치합니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 로컬 설치 vs 전역 설치
|
||||||
|
|
||||||
|
위의 모든 예시는 사용자 계정 전체에 GSD를 한 번 설치하는 `--global`을 사용합니다. 단일 프로젝트로 범위를 제한하려면 `--global`을 `--local`로 바꾸세요:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @opengsd/gsd-core@latest --claude --local
|
||||||
|
```
|
||||||
|
|
||||||
|
로컬 설치는 프로젝트 루트의 `.claude/` 디렉터리에 작성됩니다. 둘 다 존재하는 경우 로컬 설치 설정이 전역 설정보다 우선합니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 프리릴리스 에디션 설치 (Next / Nightly / Insiders / Preview)
|
||||||
|
|
||||||
|
런타임의 프리릴리스 에디션(Windsurf Next, Cursor Nightly, VS Code Insiders, Codex 프리뷰 채널 등)은 인접한 설정 디렉터리에서 읽습니다. 인스톨러 실행 전에 해당하는 `*_CONFIG_DIR` 환경 변수를 설정하세요:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
|
||||||
|
```
|
||||||
|
|
||||||
|
인스톨러 프롬프트에서 해당하는 안정적인 런타임을 선택하세요. GSD는 프리릴리스 에디션을 별도의 명명된 런타임으로 열거하지 않습니다. 이 환경 변수 메커니즘을 통한 지원은 최선의 방식이며 릴리스 CI에서 별도로 테스트되지 않습니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Node.js 없이 설치하기
|
||||||
|
|
||||||
|
`npx`를 실행할 수 없는 경우(예: Node.js가 없는 Windows 환경), 두 가지 옵션이 있습니다.
|
||||||
|
|
||||||
|
**옵션 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 형식입니다. 각 런타임은 다른 구조를 요구합니다. 런타임별 정확한 필드 변환에 대해서는 사용자 가이드의 [수동 설치 / Node.js 없는 설정](../USER-GUIDE.md#manual-install--no-nodejs-setup)을 참고하세요. OpenCode 변환 전체를 다루며 다른 런타임용 인스톨러의 `convert*Frontmatter` 함수를 안내합니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 설치 후
|
||||||
|
|
||||||
|
새 명령과 에이전트를 적용하려면 런타임을 재시작하세요. 그런 다음 첫 번째 프로젝트를 시작합니다:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-new-project
|
||||||
|
```
|
||||||
|
|
||||||
|
재시작 후 명령을 찾을 수 없다면 설치 디렉터리가 런타임이 기대하는 설정 경로와 일치하는지 확인하세요. 위의 프리릴리스 에디션 섹션에서 가장 흔한 불일치 사례를 다룹니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
|
||||||
|
- [첫 번째 프로젝트](../tutorials/your-first-project.md)
|
||||||
|
- [GSD Core 업데이트](update-gsd.md)
|
||||||
|
- [설정](../CONFIGURATION.md)
|
||||||
|
- [문서 목차](../README.md)
|
||||||
144
docs/ko-KR/how-to/isolate-work-with-workspaces.md
Normal file
144
docs/ko-KR/how-to/isolate-work-with-workspaces.md
Normal file
@@ -0,0 +1,144 @@
|
|||||||
|
# 워크스페이스로 작업을 격리하는 방법
|
||||||
|
|
||||||
|
**목표:** 피처 브랜치나 멀티 저장소 작업을 위해 별도의 git 워크트리, 독립적인 `.planning/` 루트, 그리고 선택적으로 여러 저장소를 포함하는 완전히 격리된 GSD 환경을 만듭니다.
|
||||||
|
|
||||||
|
**사전 조건:** `git`이 설치되어 있고 저장소가 워크트리를 지원해야 합니다. 멀티 저장소 워크스페이스의 경우 대상 저장소가 로컬 머신에 존재하거나 경로로 접근 가능해야 합니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 워크스페이스란
|
||||||
|
|
||||||
|
워크스페이스는 하나 이상의 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/`, 메인에서의 상태 유입 없음:
|
||||||
|
|
||||||
|
```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 워크트리를 제거하고 워크스페이스 디렉터리를 정리합니다. 이 작업은 원격 저장소에서 브랜치를 삭제하지 않으며 로컬 워크트리와 워크스페이스 디렉터리만 제거합니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 워크스트림 대신 워크스페이스를 선택할 때
|
||||||
|
|
||||||
|
워크스페이스를 선택할 때:
|
||||||
|
|
||||||
|
- **여러 저장소**(예: API 저장소와 함께 출시되는 UI 저장소)를 하나의 GSD 프로젝트 아래서 조율해야 할 때
|
||||||
|
- 피처별로 자체 브랜치, 잠금 파일, 빌드 아티팩트를 가진 **별도의 git 워크트리**가 필요할 때 — 한 환경에서의 빌드와 의존성 설치가 다른 환경에 영향을 주지 않도록
|
||||||
|
- 메인 저장소의 `.planning/` 하위 디렉터리가 아닌 **완전히 독립적인 `.planning/` 루트**를 원할 때
|
||||||
|
- 각 트래커 이슈가 워크스페이스에 매핑되는 이슈 기반 워크플로를 따를 때([트래커 이슈에서 GSD 구동](drive-gsd-from-a-tracker-issue.md) 참조)
|
||||||
|
|
||||||
|
[워크스트림](work-in-parallel-with-workstreams.md)을 선택할 때:
|
||||||
|
|
||||||
|
- 모든 작업이 **하나의 저장소**에 있고 같은 git 히스토리를 공유할 때
|
||||||
|
- 서로의 `STATE.md` 파일 간의 컨텍스트 유입 없이 서로 다른 관심 영역(API, UI, 인프라)에 대해 동시에 `/gsd-plan-phase` 또는 `/gsd-discuss-phase`를 실행하고 싶을 때
|
||||||
|
- 관심사별로 별도의 워크트리가 필요하지 않고 계획 컨텍스트 전환으로 충분할 때
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
|
||||||
|
- [워크스트림으로 병렬 작업](work-in-parallel-with-workstreams.md)
|
||||||
|
- [트래커 이슈에서 GSD 구동](drive-gsd-from-a-tracker-issue.md)
|
||||||
|
- [명령 참조](../COMMANDS.md)
|
||||||
|
- [문서 인덱스](../README.md)
|
||||||
145
docs/ko-KR/how-to/migrate-from-gsd-2.md
Normal file
145
docs/ko-KR/how-to/migrate-from-gsd-2.md
Normal 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`를 사용합니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 충돌 해결
|
||||||
|
|
||||||
|
충돌 감지에서 블로커가 발견되면 — 예를 들어, 기존 `.planning/PROJECT.md`와 모순되는 GSD-2 기술 스택 선언 — 충돌 보고서를 출력하고 파일을 작성하지 않고 중단합니다.
|
||||||
|
|
||||||
|
보고서를 읽고 모순을 해결한 후(소스 문서 또는 기존 계획 아티팩트 편집), `/gsd-import --from-gsd2`를 다시 실행합니다. 마이그레이션은 완전히 통과될 때까지 안전하게 재실행할 수 있습니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 외부 플랜 파일 가져오기
|
||||||
|
|
||||||
|
전체 GSD-2 프로젝트가 아닌 독립형 플랜 문서(팀 계획 문서, 마크다운 스펙, 내보낸 작업 목록)가 있는 경우 `--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`는 항상 세 가지 버킷(자동 해결, 경쟁 변형, 미해결 블로커)이 있는 `INGEST-CONFLICTS.md`를 생성합니다. 모든 인제스트 실행 후 이 파일을 검토하세요. LOCKED vs 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에 미해결 블로커가 나열됨 | 영향받는 문서가 계획에 통합되기 전에 수동 해결 필요 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
|
||||||
|
- [첫 번째 프로젝트](../tutorials/your-first-project.md)
|
||||||
|
- [명령 참조](../COMMANDS.md)
|
||||||
|
- [문서 인덱스](../README.md)
|
||||||
216
docs/ko-KR/how-to/plan-a-phase.md
Normal file
216
docs/ko-KR/how-to/plan-a-phase.md
Normal file
@@ -0,0 +1,216 @@
|
|||||||
|
# 페이즈를 기획하는 방법
|
||||||
|
|
||||||
|
**목표:** 페이즈 결정 사항과 리서치를 실행 준비가 된 원자적이고 검증 가능한 태스크 계획으로 변환합니다.
|
||||||
|
|
||||||
|
**전제 조건:** `.planning/ROADMAP.md`가 존재해야 합니다. `/gsd-discuss-phase`에서 생성된 `{phase}-CONTEXT.md`를 강력히 권장하지만 필수는 아닙니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 표준 기획 흐름 실행
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 2
|
||||||
|
```
|
||||||
|
|
||||||
|
다음 세 단계를 순서대로 실행합니다:
|
||||||
|
|
||||||
|
1. **리서치** — `gsd-phase-researcher` 서브에이전트가 도메인을 조사하고 `{phase}-RESEARCH.md`를 작성합니다.
|
||||||
|
2. **기획** — `gsd-planner` 서브에이전트가 컨텍스트, 리서치, 요구 사항을 읽고 하나 이상의 `{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`는 프로젝트 스캐폴드, 라우팅, 실제 DB 읽기/쓰기 하나, 실제 UI 인터랙션 하나, 개발 배포를 다루는 `SKELETON.md`도 생성합니다.
|
||||||
|
|
||||||
|
플래그 없이 페이즈에 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` | frontmatter, 웨이브 할당, 인수 기준이 포함된 실행 가능한 태스크 계획 |
|
||||||
|
| `{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가 최소 하나의 계획에 나타남
|
||||||
|
8. Nyquist 테스트 매핑 — 계획이 VALIDATION.md의 검증 전략을 다룸
|
||||||
|
|
||||||
|
수정 루프는 최대 3회 실행됩니다. 3회 반복 후에도 품질 게이트를 통과하지 못하면 체커가 남은 문제를 수동 검토를 위해 표시합니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 닫힌 페이즈 재기획
|
||||||
|
|
||||||
|
`status: passed`가 있는 `VERIFICATION.md`가 있는 페이즈는 닫힌 것으로 간주됩니다. 재기획을 시도하면 오류로 중단됩니다. 종료가 잘못된 경우 `--force`로 재정의하세요:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gsd-plan-phase 2 --force
|
||||||
|
```
|
||||||
|
|
||||||
|
트랜스크립트와 커밋된 계획 문서에 경고가 기록됩니다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 관련 문서
|
||||||
|
|
||||||
|
- [페이즈 논의](discuss-a-phase.md)
|
||||||
|
- [페이즈 실행](execute-a-phase.md)
|
||||||
|
- [PLAN.md 스키마](../reference/plan-md.md)
|
||||||
|
- [명령어 참조](../COMMANDS.md)
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user