msd-core/docs/ja-JP/ARCHITECTURE.md

GSD アーキテクチャ

コントリビューターおよび上級ユーザー向けのシステムアーキテクチャ文書です。ユーザー向けドキュメントは機能リファレンスまたはユーザーガイドをご覧ください。

---

目次

• システム概要
• 設計原則
• コンポーネントアーキテクチャ
• エージェントモデル
• データフロー
• ファイルシステムレイアウト
• インストーラーアーキテクチャ
• フックシステム
• CLIツールレイヤー
• ランタイム抽象化

---

システム概要

GSDは、ユーザーとAIコーディングエージェント（Claude Code、Gemini CLI、OpenCode、Kilo、Codex、Copilot、Antigravity、Trae、Cline、Augment Code）の間に位置するメタプロンプティングフレームワークです。以下の機能を提供します：

1. コンテキストエンジニアリング — タスクごとにAIが必要とするすべてを提供する構造化アーティファクト
2. マルチエージェントオーケストレーション — 専門エージェントをフレッシュなコンテキストウィンドウで起動する軽量オーケストレーター
3. 仕様駆動開発 — 要件 → 調査 → 計画 → 実行 → 検証のパイプライン
4. 状態管理 — セッションやコンテキストリセットをまたいだ永続的なプロジェクトメモリ

┌──────────────────────────────────────────────────────┐
│                      USER                            │
│            /gsd-command [args]                        │
└─────────────────────┬────────────────────────────────┘
                      │
┌─────────────────────▼────────────────────────────────┐
│              COMMAND LAYER                            │
│   commands/gsd/*.md — Prompt-based command files      │
│   (Claude Code custom commands / Codex skills)        │
└─────────────────────┬────────────────────────────────┘
                      │
┌─────────────────────▼────────────────────────────────┐
│              WORKFLOW LAYER                           │
│   get-shit-done/workflows/*.md — Orchestration logic  │
│   (Reads references, spawns agents, manages state)    │
└──────┬──────────────┬─────────────────┬──────────────┘
       │              │                 │
┌──────▼──────┐ ┌─────▼─────┐ ┌────────▼───────┐
│  AGENT      │ │  AGENT    │ │  AGENT         │
│  (fresh     │ │  (fresh   │ │  (fresh        │
│   context)  │ │   context)│ │   context)     │
└──────┬──────┘ └─────┬─────┘ └────────┬───────┘
       │              │                 │
┌──────▼──────────────▼─────────────────▼──────────────┐
│              CLI TOOLS LAYER                          │
│   get-shit-done/bin/gsd-tools.cjs                     │
│   (State, config, phase, roadmap, verify, templates)  │
└──────────────────────┬───────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────┐
│              FILE SYSTEM (.planning/)                 │
│   PROJECT.md | REQUIREMENTS.md | ROADMAP.md          │
│   STATE.md | config.json | phases/ | research/       │
└──────────────────────────────────────────────────────┘

---

設計原則

1. エージェントごとにフレッシュなコンテキスト

オーケストレーターが起動するすべてのエージェントは、クリーンなコンテキストウィンドウ（最大200Kトークン）を取得します。これにより、AIがコンテキストウィンドウに蓄積された会話で埋め尽くされることによる品質低下（コンテキストの劣化）が排除されます。

2. 軽量オーケストレーター

ワークフローファイル（get-shit-done/workflows/*.md）は重い処理を行いません。以下の役割に徹します：

• gsd-tools.cjs init <workflow> でコンテキストを読み込む
• 焦点を絞ったプロンプトで専門エージェントを起動する
• 結果を収集し、次のステップにルーティングする
• ステップ間で状態を更新する

3. ファイルベースの状態管理

すべての状態は .planning/ 内に人間が読めるMarkdownとJSONとして保存されます。データベースもサーバーも外部依存もありません。これにより：

• コンテキストリセット（/clear）後も状態が維持される
• 人間とエージェントの両方が状態を確認できる
• チームでの可視性のためにgitにコミットできる

4. 未設定 = 有効

ワークフローの機能フラグは 未設定 = 有効 のパターンに従います。config.json にキーが存在しない場合、デフォルトで true になります。ユーザーは機能を明示的に無効化します。デフォルトを有効化する操作は不要です。

5. 多層防御

複数のレイヤーで一般的な障害モードを防止します：

• 実行前に計画が検証される（plan-checkerエージェント）
• 実行時にタスクごとにアトミックなコミットが生成される
• 実行後の検証でフェーズ目標との整合性を確認する
• UATが最終ゲートとして人間による検証を提供する

---

コンポーネントアーキテクチャ

コマンド（commands/gsd/*.md）

ユーザー向けのエントリーポイントです。各ファイルにはYAMLフロントマター（name、description、allowed-tools）とワークフローをブートストラップするプロンプト本文が含まれています。コマンドは以下の形式でインストールされます：

• Claude Code: カスタムスラッシュコマンド（/gsd-command-name）
• OpenCode / Kilo: スラッシュコマンド（/gsd-command-name）
• Codex: スキル（$gsd-command-name）
• Copilot: スラッシュコマンド（/gsd-command-name）
• Antigravity: スキル

コマンド総数: 44

ワークフロー（get-shit-done/workflows/*.md）

コマンドが参照するオーケストレーションロジックです。以下を含むステップバイステップのプロセスが記述されています：

• gsd-tools.cjs init によるコンテキスト読み込み
• モデル解決を伴うエージェント起動の指示
• ゲート/チェックポイントの定義
• 状態更新パターン
• エラーハンドリングとリカバリー

ワークフロー総数: 46

エージェント（agents/*.md）

フロントマターで以下を指定する専門エージェント定義：

• name — エージェント識別子
• description — 役割と目的
• tools — 許可されたツールアクセス（Read、Write、Edit、Bash、Grep、Glob、WebSearchなど）
• color — 視覚的な区別のためのターミナル出力色

エージェント総数: 16

リファレンス（get-shit-done/references/*.md）

ワークフローとエージェントが @-reference で参照する共有知識ドキュメント：

• checkpoints.md — チェックポイントタイプの定義とインタラクションパターン
• model-profiles.md — エージェントごとのモデルティア割り当て
• verification-patterns.md — 各種アーティファクトの検証方法
• planning-config.md — 設定スキーマの全体像と動作
• git-integration.md — gitコミット、ブランチ、履歴のパターン
• questioning.md — プロジェクト初期化のためのドリーム抽出フィロソフィー
• tdd.md — テスト駆動開発の統合パターン
• ui-brand.md — 視覚的な出力フォーマットパターン

テンプレート（get-shit-done/templates/）

すべてのプランニングアーティファクト用のMarkdownテンプレートです。gsd-tools.cjs template fill および scaffold コマンドにより、事前構造化されたファイルを作成するために使用されます：

• project.md、requirements.md、roadmap.md、state.md — コアプロジェクトファイル
• phase-prompt.md — フェーズ実行プロンプトテンプレート
• summary.md（+ summary-minimal.md、summary-standard.md、summary-complex.md）— 粒度対応のサマリーテンプレート
• DEBUG.md — デバッグセッション追跡テンプレート
• UI-SPEC.md、UAT.md、VALIDATION.md — 専門検証テンプレート
• discussion-log.md — ディスカッション監査証跡テンプレート
• codebase/ — ブラウンフィールドマッピングテンプレート（スタック、アーキテクチャ、規約、懸念事項、構造、テスト、統合）
• research-project/ — リサーチ出力テンプレート（SUMMARY、STACK、FEATURES、ARCHITECTURE、PITFALLS）

フック（hooks/）

ホストAIエージェントと統合するランタイムフック：

フック	イベント	目的
gsd-statusline.js	statusLine	モデル、タスク、ディレクトリ、コンテキスト使用量バーを表示
gsd-context-monitor.js	PostToolUse / AfterTool	コンテキスト残量35%/25%でエージェント向け警告を注入
gsd-check-update.js	SessionStart	GSDの新バージョンをバックグラウンドで確認
gsd-prompt-guard.js	PreToolUse	.planning/ への書き込みにプロンプトインジェクションパターンがないかスキャン（アドバイザリー）
gsd-workflow-guard.js	PreToolUse	GSDワークフローコンテキスト外でのファイル編集を検出（アドバイザリー、hooks.workflow_guard によるオプトイン）

CLIツール（get-shit-done/bin/）

17のドメインモジュールを持つNode.js CLIユーティリティ（gsd-tools.cjs）：

モジュール	責務
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、タイムスタンプ、todos、スキャフォールディング、統計）
model-profiles.cjs	モデルプロファイル解決テーブル
security.cjs	パストラバーサル防止、プロンプトインジェクション検出、安全なJSON解析、シェル引数バリデーション
uat.cjs	UATファイル解析、検証デット追跡、audit-uatサポート

---

エージェントモデル

オーケストレーター → エージェントパターン

Orchestrator (workflow .md)
    │
    ├── Load context: gsd-tools.cjs init <workflow> <phase>
    │   Returns JSON with: project info, config, state, phase details
    │
    ├── Resolve model: gsd-tools.cjs resolve-model <agent-name>
    │   Returns: opus | sonnet | haiku | inherit
    │
    ├── Spawn Agent (Task/SubAgent call)
    │   ├── Agent prompt (agents/*.md)
    │   ├── Context payload (init JSON)
    │   ├── Model assignment
    │   └── Tool permissions
    │
    ├── Collect result
    │
    └── Update state: gsd-tools.cjs state update/patch/advance-plan

エージェント起動カテゴリ

カテゴリ	エージェント	並列実行
リサーチャー	gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher	4並列（stack、features、architecture、pitfalls）; advisorはdiscuss-phase中に起動
シンセサイザー	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並列（tech、arch、quality、concerns）
デバッガー	gsd-debugger	逐次（インタラクティブ）
オーディター	gsd-ui-auditor	逐次

ウェーブ実行モデル

execute-phase では、プランが依存関係に基づいてウェーブにグループ化されます：

Wave Analysis:
  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)

各エグゼキューターには以下が与えられます：

• フレッシュな200Kコンテキストウィンドウ
• 実行対象の特定のPLAN.md
• プロジェクトコンテキスト（PROJECT.md、STATE.md）
• フェーズコンテキスト（CONTEXT.md、利用可能な場合はRESEARCH.md）

並列コミットの安全性

同一ウェーブ内で複数のエグゼキューターが実行される場合、2つの仕組みで競合を防止します：

1. --no-verify コミット — 並列エージェントはpre-commitフックをスキップします（ビルドロックの競合を引き起こす可能性があるため。例：Rustプロジェクトでのcargo lockファイルの競合）。オーケストレーターは各ウェーブ完了後に git hook run pre-commit を1回実行します。

2. STATE.md ファイルロック — すべての writeStateMd() 呼び出しはロックファイルベースの相互排他（STATE.md.lock、O_EXCL によるアトミック作成）を使用します。これにより、2つのエージェントがSTATE.mdを読み取り、異なるフィールドを変更し、最後の書き込みが他方の変更を上書きする読み取り-変更-書き込みの競合状態を防止します。古いロックの検出（10秒タイムアウト）とジッター付きのスピンウェイトを含みます。

---

データフロー

新規プロジェクトフロー

User input (idea description)
    │
    ▼
Questions (questioning.md philosophy)
    │
    ▼
4x Project Researchers (parallel)
    ├── Stack → STACK.md
    ├── Features → FEATURES.md
    ├── Architecture → ARCHITECTURE.md
    └── Pitfalls → PITFALLS.md
    │
    ▼
Research Synthesizer → SUMMARY.md
    │
    ▼
Requirements extraction → REQUIREMENTS.md
    │
    ▼
Roadmapper → ROADMAP.md
    │
    ▼
User approval → STATE.md initialized

フェーズ実行フロー

discuss-phase → CONTEXT.md (user preferences)
    │
    ▼
ui-phase → UI-SPEC.md (design contract, optional)
    │
    ▼
plan-phase
    ├── Phase Researcher → RESEARCH.md
    ├── Planner → PLAN.md files
    └── Plan Checker → Verify loop (max 3x)
    │
    ▼
execute-phase
    ├── Wave analysis (dependency grouping)
    ├── Executor per plan → code + atomic commits
    ├── SUMMARY.md per plan
    └── Verifier → VERIFICATION.md
    │
    ▼
verify-work → UAT.md (user acceptance testing)
    │
    ▼
ui-review → UI-REVIEW.md (visual audit, optional)

コンテキスト伝播

各ワークフローステージは後続のステージに供給されるアーティファクトを生成します：

PROJECT.md ────────────────────────────────────────────► All agents
REQUIREMENTS.md ───────────────────────────────────────► Planner, Verifier, Auditor
ROADMAP.md ────────────────────────────────────────────► Orchestrators
STATE.md ──────────────────────────────────────────────► All agents (decisions, blockers)
CONTEXT.md (per phase) ────────────────────────────────► Researcher, Planner, Executor
RESEARCH.md (per phase) ───────────────────────────────► Planner, Plan Checker
PLAN.md (per plan) ────────────────────────────────────► Executor, Plan Checker
SUMMARY.md (per plan) ─────────────────────────────────► Verifier, State tracking
UI-SPEC.md (per phase) ────────────────────────────────► Executor, UI Auditor

---

ファイルシステムレイアウト

インストールファイル

~/.claude/                          # Claude Code (global install)
├── commands/gsd/*.md               # 37 slash commands
├── get-shit-done/
│   ├── bin/gsd-tools.cjs           # CLI utility
│   ├── bin/lib/*.cjs               # 15 domain modules
│   ├── workflows/*.md              # 42 workflow definitions
│   ├── references/*.md             # 13 shared reference docs
│   └── templates/                  # Planning artifact templates
├── agents/*.md                     # 15 agent definitions
├── hooks/
│   ├── gsd-statusline.js           # Statusline hook
│   ├── gsd-context-monitor.js      # Context warning hook
│   └── gsd-check-update.js         # Update check hook
├── settings.json                   # Hook registrations
└── VERSION                         # Installed version number

他のランタイムでの同等パス：

• OpenCode: ~/.config/opencode/ または ~/.opencode/
• Kilo: ~/.config/kilo/ または ~/.kilo/
• Gemini CLI: ~/.gemini/
• Codex: ~/.codex/（コマンドの代わりにスキルを使用）
• Copilot: ~/.github/
• Antigravity: ~/.gemini/antigravity/（グローバル）または ./.agent/（ローカル）

プロジェクトファイル（.planning/）

.planning/
├── PROJECT.md              # プロジェクトビジョン、制約、決定事項、発展ルール
├── REQUIREMENTS.md         # スコープ付き要件（v1/v2/スコープ外）
├── ROADMAP.md              # ステータス追跡付きフェーズ分解
├── STATE.md                # 生きたメモリ：位置、決定事項、ブロッカー、メトリクス
├── config.json             # ワークフロー設定
├── MILESTONES.md           # 完了済みマイルストーンのアーカイブ
├── research/               # /gsd-new-project によるドメインリサーチ
│   ├── SUMMARY.md
│   ├── STACK.md
│   ├── FEATURES.md
│   ├── ARCHITECTURE.md
│   └── PITFALLS.md
├── codebase/               # ブラウンフィールドマッピング（/gsd-map-codebase から）
│   ├── STACK.md
│   ├── ARCHITECTURE.md
│   ├── CONVENTIONS.md
│   ├── CONCERNS.md
│   ├── STRUCTURE.md
│   ├── TESTING.md
│   └── INTEGRATIONS.md
├── phases/
│   └── XX-phase-name/
│       ├── XX-CONTEXT.md       # ユーザー設定（discuss-phase から）
│       ├── XX-RESEARCH.md      # エコシステムリサーチ（plan-phase から）
│       ├── XX-YY-PLAN.md       # 実行プラン
│       ├── XX-YY-SUMMARY.md    # 実行結果
│       ├── XX-VERIFICATION.md  # 実行後の検証
│       ├── XX-VALIDATION.md    # ナイキストテストカバレッジマッピング
│       ├── XX-UI-SPEC.md       # UIデザインコントラクト（ui-phase から）
│       ├── XX-UI-REVIEW.md     # ビジュアル監査スコア（ui-review から）
│       └── XX-UAT.md           # ユーザー受け入れテスト結果
├── quick/                  # クイックタスク追跡
│   └── YYMMDD-xxx-slug/
│       ├── PLAN.md
│       └── SUMMARY.md
├── todos/
│   ├── pending/            # キャプチャされたアイデア
│   └── done/               # 完了済みtodo
├── threads/               # 永続コンテキストスレッド（/gsd-thread から）
├── seeds/                 # 将来に向けたアイデア（/gsd-plant-seed から）
├── debug/                  # アクティブなデバッグセッション
│   ├── *.md                # アクティブセッション
│   ├── resolved/           # アーカイブ済みセッション
│   └── knowledge-base.md   # 永続的なデバッグ知見
├── ui-reviews/             # /gsd-ui-review からのスクリーンショット（gitignore対象）
└── continue-here.md        # コンテキスト引き継ぎ（pause-work から）

---

インストーラーアーキテクチャ

インストーラー（bin/install.js、約3,000行）は以下を処理します：

1. ランタイム検出 — インタラクティブプロンプトまたはCLIフラグ（--claude、--opencode、--gemini、--kilo、--codex、--copilot、--antigravity、--all）
2. インストール先の選択 — グローバル（--global）またはローカル（--local）
3. ファイルデプロイ — コマンド、ワークフロー、リファレンス、テンプレート、エージェント、フックをコピー
4. ランタイム適応 — ランタイムごとにファイル内容を変換：
   • Claude Code: そのまま使用
   • OpenCode: コマンド/エージェントをOpenCode互換のフラットコマンド + サブエージェント形式に変換
   • Kilo: OpenCode変換パイプラインをKiloの設定パスで再利用
   • Codex: コマンドからTOML設定 + スキルを生成
   • Copilot: ツール名をマッピング（Read→read、Bash→executeなど）
   • Gemini: フックイベント名を調整（PostToolUse の代わりに AfterTool）
   • Antigravity: Googleモデル同等品によるスキルファースト
5. パス正規化 — ~/.claude/ パスをランタイム固有のパスに置換
6. 設定統合 — ランタイムの settings.json にフックを登録
7. パッチバックアップ — v1.17以降、ローカルで変更されたファイルを /gsd-update --reapply 用に gsd-local-patches/ へバックアップ
8. マニフェスト追跡 — クリーンアンインストールのために gsd-file-manifest.json を書き込み
9. アンインストールモード — --uninstall ですべてのGSDファイル、フック、設定を削除

プラットフォーム対応

• Windows: 子プロセスでの windowsHide、保護ディレクトリへのEPERM/EACCES対策、パスセパレーターの正規化
• WSL: WindowsのNode.jsがWSL上で実行されていることを検出し、パスの不一致について警告
• Docker/CI: カスタム設定ディレクトリの場所に CLAUDE_CONFIG_DIR 環境変数をサポート

---

フックシステム

アーキテクチャ

Runtime Engine (Claude Code / Gemini CLI)
    │
    ├── statusLine event ──► gsd-statusline.js
    │   Reads: stdin (session JSON)
    │   Writes: stdout (formatted status), /tmp/claude-ctx-{session}.json (bridge)
    │
    ├── PostToolUse/AfterTool event ──► gsd-context-monitor.js
    │   Reads: stdin (tool event JSON), /tmp/claude-ctx-{session}.json (bridge)
    │   Writes: stdout (hookSpecificOutput with additionalContext warning)
    │
    └── SessionStart event ──► gsd-check-update.js
        Reads: VERSION file
        Writes: ~/.claude/cache/gsd-update-check.json (spawns background process)

コンテキストモニターの閾値

コンテキスト残量	レベル	エージェントの動作
> 35%	Normal	警告なし
≤ 35%	WARNING	「新しい複雑な作業の開始を避けてください」
≤ 25%	CRITICAL	「コンテキストがほぼ枯渇、ユーザーに通知してください」

デバウンス：繰り返し警告の間隔は5回のツール使用。重大度のエスカレーション（WARNING→CRITICAL）はデバウンスをバイパスします。

安全性の特性

• すべてのフックはtry/catchでラップされ、エラー時はサイレントに終了
• stdin タイムアウトガード（3秒）でパイプの問題によるハングを防止
• 古いメトリクス（60秒超）は無視される
• ブリッジファイルの欠落は適切に処理される（サブエージェント、新規セッション）
• コンテキストモニターはアドバイザリーのみ — ユーザーの設定を上書きする命令的なコマンドは発行しない

セキュリティフック（v1.27）

Prompt Guard（gsd-prompt-guard.js）：

• .planning/ ファイルへのWrite/Edit時にトリガー
• プロンプトインジェクションパターン（ロールオーバーライド、指示バイパス、systemタグインジェクション）をスキャン
• アドバイザリーのみ — 検出をログに記録するが、ブロックはしない
• フックの独立性のため、パターンはインライン化（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コーディングランタイムをサポートしています：

ランタイム	コマンド形式	エージェントシステム	設定場所
Claude Code	/gsd-command	Task起動	~/.claude/
OpenCode	/gsd-command	サブエージェントモード	~/.config/opencode/
Kilo	/gsd-command	サブエージェントモード	~/.config/kilo/
Gemini CLI	/gsd-command	Task起動	~/.gemini/
Codex	$gsd-command	スキル	~/.codex/
Copilot	/gsd-command	エージェント委譲	~/.github/
Antigravity	スキル	スキル	~/.gemini/antigravity/

抽象化ポイント

1. ツール名マッピング — 各ランタイムは独自のツール名を持つ（例：ClaudeのBash → Copilotのexecute）
2. フックイベント名 — Claude Codeは PostToolUse、Geminiは AfterTool を使用
3. エージェントフロントマター — 各ランタイムは独自のエージェント定義形式を持つ
4. パス規約 — 各ランタイムは異なるディレクトリに設定を保存
5. モデル参照 — inherit プロファイルにより、GSDはランタイムのモデル選択に委譲

インストーラーはインストール時にすべての変換を処理します。ワークフローとエージェントはClaude Codeのネイティブ形式で記述され、デプロイ時に変換されます。