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

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

Browse Source 
* chore: wire docs/agents config into AGENTS.md Agent skills section

Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: rebrand to GSD Core and restructure docs with Diataxis

Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: backfill changeset PR number (#605)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-02 08:13:09 -04:00
committed by GitHub
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

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

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

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

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

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