gather-plan-apply

リソース

scripts/
  validate-gpa-compliance.sh
references/
  examples-and-checklists.md

Gather-Plan-Apply プロトコル（GPA ワークフロー）

GPA ループでは、フェーズごとにツールタイプあたり 1 回だけ呼び出すワークフローを徹底し、過剰なツール呼び出しによるトークンの浪費を防ぎます。これは提案ではなく、すべての GoodVibes エージェントが必ず実行すべきパターンです。

正確なワークフロー

0. LOAD SKILLS (once, before any GPA cycle)
   - Call get_skill_content for role-relevant skills
   - This is NOT part of the GPA cycle itself

1. G — GATHER (1-2 tool calls)
   - Check .goodvibes/memory/ files FIRST (failures, patterns, decisions)
   - Single `discover` call with ALL queries batched inside
   - Multiple query types (glob, grep, symbols, structural) in one call
   - Can search file content via grep/symbols queries
   - Batch any file reads that need full content alongside discover
   - Output: files_only or locations (minimal verbosity)

2. P — PLAN (0 tool calls, cognitive only)
   - Agent thinks about what it learned from GATHER
   - Plans which files to create/write/edit
   - Plans which commands to run for validation
   - Identifies ALL batch opportunities — same-type ops go in one call
   - Plans the EXACT apply call structure

3. A — APPLY (1-2 tool calls)
   - Writes and edits batched into one precision_write or precision_edit call
   - Validation commands batched into one precision_exec call
   - Key: one call per tool type, everything batched inside it

4. LOOP — Back to G if:
   - Results didn't match expectations
   - Scope changed
   - Validation failed

サイクルあたりの呼び出し予算

フェーズ	ツール呼び出し	タイプ	目的
G（収集）	1-2	discover + オプションの precision_read	すべての探索とメモリの読み取り
P（計画）	0	認知作業	適用操作を計画する
A（適用）	1-2	precision_write/precision_edit + precision_exec	すべての書き込み／編集と検証
合計	2-4

基本ルール：フェーズごとに、ツールタイプあたり 1 回だけ呼び出します。同じフェーズで precision_read を 2 回呼び出してはいけません。両方のファイルを 1 回の呼び出しにまとめてください。

逐次呼び出しについて：操作が相互に依存する場合（例：書き込み後に検証）、逐次呼び出しは許容されます。内部の precision ツール配列（files 配列、edits 配列、commands 配列）を使って、実際にバッチ処理する方法を常に優先してください。

主なルール（必須）

1. discover では、すべての探索クエリを 1 回の呼び出しにまとめます — 探索に precision_glob や precision_grep を個別に使ってはいけません
2. Plan ステップではツール呼び出しはゼロです — 認知作業として、エージェントがテキストで考えます
3. フェーズごとにツールタイプあたり 1 回だけ呼び出します — 3 つのファイルを読み取る必要がある場合は、1 回の precision_read 呼び出しにまとめてください
4. APPLY の出力は 1～2 回の呼び出しです — ファイルには precision_write/edit、コマンドには precision_exec を使います
5. ToolSearch は GPA の一部ではありません — ツールは開始時に一度だけ読み込み、サイクルの途中で検索しないでください
6. 最初に必ずメモリを確認します — 実装前に常に .goodvibes/memory/ を読み取ってください

フェーズ 1：GATHER（1～2 回の呼び出し）

初期設定：メモリの確認

ファイルを探索する前に、すでに把握している内容を確認します。メモリの読み取りは、discover 呼び出しにまとめるか、別の読み取りとして実行してください。

# GOOD: Memory reads batched with file content reads
precision_read:
  files:
    - path: ".goodvibes/memory/failures.json"
    - path: ".goodvibes/memory/patterns.json"
    - path: ".goodvibes/memory/decisions.json"
  verbosity: minimal

discover ツール

discover ツールは、複数の grep/glob/symbols/structural クエリを並行して実行し、クエリ ID ごとに結果を返します。これは主要な探索手段です。

パターン：すべての探索クエリをまとめる

# GOOD: 1 discover call with everything
discover:
  queries:
    - id: existing_files
      type: glob
      patterns: ["src/features/auth/**/*.ts"]
    - id: existing_patterns
      type: grep
      pattern: "export (function|const|class)"
      glob: "src/features/**/*.ts"
    - id: exported_hooks
      type: symbols
      query: "use"
      kinds: ["function"]
    - id: console_logs
      type: structural
      structural_pattern: "console.log($$$ARGS)"
  verbosity: files_only

クエリのタイプ：

• glob - パスパターンでファイルを検索します
• grep - パターンを含むファイルを検索します
• symbols - エクスポートされた関数／型／クラスを検索します
• structural - AST パターン（例：関数呼び出し）を検索します

出力モード：

• count_only - 件数のみ（範囲の見積もり）
• files_only - ファイルパスのみ（対象リストの作成）← これを使用
• locations - ファイルパスと行番号（正確な位置が必要な場合）

ファイル全体の読み取り

ファイル全体を読み取るには、GATHER フェーズで precision_read を使い、メモリの読み取りとまとめるか、discover の結果が先に必要な場合は 2 回目の呼び出しとして実行します。

[BAD] と [GOOD] の Gather パターン

[BAD] — 探索クエリを逐次実行（複数のツール呼び出し）

# BAD: 4 separate tool calls for discovery
precision_glob:
  patterns: ["src/**/*.ts"]

precision_grep:
  queries:
    - id: exports
      pattern: "export function"

precision_read:
  files:
    - path: ".goodvibes/memory/failures.json"

precision_grep:
  queries:
    - id: imports
      pattern: "import.*from"

[GOOD] — discover を 1 回呼び出し、メモリの読み取りをまとめる（ツール呼び出し 2 回）

# GOOD: 1 discover call with all queries
discover:
  queries:
    - id: files
      type: glob
      patterns: ["src/**/*.ts"]
    - id: exports
      type: grep
      pattern: "export function"
      glob: "src/**/*.ts"
    - id: imports
      type: grep
      pattern: "import.*from"
      glob: "src/**/*.ts"
  verbosity: files_only

# GOOD: Memory reads in one batched call
precision_read:
  files:
    - path: ".goodvibes/memory/failures.json"
    - path: ".goodvibes/memory/patterns.json"
    - path: ".goodvibes/memory/decisions.json"
  verbosity: minimal

フェーズ 2：PLAN（呼び出し 0 回、認知作業のみ）

目的

計画は認知作業であり、ツール呼び出しではありません。次の内容をテキストで考えます。

• 作成／書き込みするファイル
• 編集するファイル（正確な検索／置換を含む）
• 検証のために実行するコマンド
• すべてのバッチ処理の機会 — 同じタイプの操作は必ずまとめる

出力：ツール呼び出しを含まない、記述された計画

計画の構成

Plan:
1. Create the following files:
   - src/features/auth/types.ts — User interface
   - src/features/auth/hooks.ts — useAuth hook
   - src/features/auth/index.ts — barrel export

2. Edit the following files:
   - src/app/layout.tsx — wrap App with AuthProvider

3. Validate:
   - npm run typecheck (expect exit 0)
   - npm run lint (expect exit 0)

4. Batch plan:
   - Call 1 (Apply): precision_write with 3 files + precision_edit with 1 edit
   - Call 2 (Apply): precision_exec with 2 commands

[BAD] と [GOOD] の計画

[BAD] — 逐次呼び出しにつながる曖昧な計画

Plan:
- Create some files
- Maybe edit layout
- Run typecheck

これにより、次のようになります。

precision_write: ...   # 1st call
precision_write: ...   # 2nd call! (should be batched)
precision_edit: ...    # 3rd call! (could combine with above pattern)

[GOOD] — 正確なバッチ構成を示した具体的な計画

Plan:
1. Write 3 files in 1 precision_write call:
   - src/features/auth/types.ts (symbols)
   - src/features/auth/hooks.ts (content)
   - src/features/auth/index.ts (content)

2. Edit 1 file in 1 precision_edit call:
   - src/app/layout.tsx — wrap with AuthProvider

3. Validate in 1 precision_exec call:
   - npm run typecheck
   - npm run lint

フェーズ 3：APPLY（1～2 回の呼び出し）

パターン：すべての書き込み／編集をまとめる

複数のファイルを含む precision_write の呼び出し 1 回：

precision_write:
  files:
    - path: "src/features/auth/types.ts"
      content: |
        export interface User {
          id: string;
          email: string;
        }
    - path: "src/features/auth/hooks.ts"
      content: |
        import type { User } from './types';
        export function useAuth(): User | null { /*...*/ }
    - path: "src/features/auth/index.ts"
      content: |
        export * from './types';
        export * from './hooks';
  verbosity: count_only

または、複数の編集を含む precision_edit の呼び出し 1 回：

precision_edit:
  edits:
    - path: "src/app/layout.tsx"
      find: "<App />"
      replace: "<AuthProvider><App /></AuthProvider>"
    - path: "src/middleware.ts"
      find: "export const config = {}"
      replace: "export const config = { matcher: ['/dashboard/:path*'] }"
    - path: "src/lib/api.ts"
      find: "headers: {}"
      replace: "headers: { Authorization: `Bearer ${token}` }"
  verbosity: minimal

precision_exec による検証（Apply の 2 回目の呼び出し）：

precision_exec:
  commands:
    - cmd: "npm run typecheck"
      expect:
        exit_code: 0
    - cmd: "npm run lint"
      expect:
        exit_code: 0
  verbosity: minimal

[BAD] と [GOOD] の Apply バッチ処理

[BAD] — precision_write を 3 回個別に呼び出す

precision_write:
  files:
    - path: "file1.ts"
      content: "..."

precision_write:  # Second call!
  files:
    - path: "file2.ts"
      content: "..."

precision_write:  # Third call!
  files:
    - path: "file3.ts"
      content: "..."

[GOOD] — 3 つのファイルを含む precision_write の呼び出し 1 回

precision_write:
  files:
    - path: "file1.ts"
      content: "..."
    - path: "file2.ts"
      content: "..."
    - path: "file3.ts"
      content: "..."
  verbosity: count_only

フェーズ 4：LOOP（Gather に戻るタイミング）

ループのトリガー

1. 結果が期待と異なる — 型チェックに失敗する、テストに失敗する、予期しない動作がある
2. スコープが変わった — 調査の結果、想定とは異なる状況が明らかになった
3. 新しい情報が得られた — 実行中にタスクの要件が明確になった

ループのパターン

# Initial GPA cycle
discover: ...          # Gather call 1
precision_read: ...    # Gather call 2 (memory + key files)
precision_write: ...   # Apply call 1
precision_exec: ...    # Apply call 2 — FAILS typecheck

# LOOP: Start new GPA cycle with refined discovery
discover:              # Gather call 1 (new cycle)
  queries:
    - id: find_missing_import
      type: grep
      pattern: "export.*User"
      glob: "src/**/*.ts"
  verbosity: locations  # Need exact location

precision_edit: ...    # Apply call 1 (new cycle) - fix the issue
precision_exec: ...    # Apply call 2 (new cycle) - re-validate

完全な例：認証機能の実装

サイクル 1：初期実装

ステップ 1 — GATHER（2 回の呼び出し）

# Call 1: Check memory
precision_read:
  files:
    - path: ".goodvibes/memory/failures.json"
    - path: ".goodvibes/memory/decisions.json"
  verbosity: minimal

# Call 2: Discover landscape
discover:
  queries:
    - id: existing_auth
      type: glob
      patterns: ["src/features/auth/**/*.ts", "src/**/auth*.ts"]
    - id: auth_patterns
      type: grep
      pattern: "(useAuth|getSession|AuthProvider)"
      glob: "src/**/*.{ts,tsx}"
    - id: user_types
      type: symbols
      query: "User"
      kinds: ["interface", "type"]
  verbosity: files_only

ステップ 2 — PLAN（0 回の呼び出し、認知作業）

Gather results:
- No memory failures for auth
- No existing auth files
- No auth patterns in use
- User type exists in src/types/user.ts

Plan:
Apply Call 1 (precision_write): Create 3 auth files
Apply Call 2 (precision_exec): typecheck + lint

ステップ 3 — APPLY（2 回の呼び出し）

# Call 1: Create files
precision_write:
  files:
    - path: "src/features/auth/provider.tsx"
      content: |
        import { ClerkProvider } from '@clerk/nextjs';
        export function AuthProvider({ children }: { children: React.ReactNode }) {
          return <ClerkProvider>{children}</ClerkProvider>;
        }
    - path: "src/features/auth/hooks.ts"
      content: |
        import { useUser } from '@clerk/nextjs';
        import type { User } from '@/types/user';
        export function useAuth(): User | null {
          const { user } = useUser();
          if (!user) return null;
          return { id: user.id, email: user.emailAddresses[0].emailAddress, name: user.fullName };
        }
    - path: "src/features/auth/index.ts"
      content: |
        export { AuthProvider } from './provider';
        export { useAuth } from './hooks';
  verbosity: count_only

# Call 2: Validate
precision_exec:
  commands:
    - cmd: "npm run typecheck"
      expect:
        exit_code: 0
    - cmd: "npm run lint"
      expect:
        exit_code: 0
  verbosity: minimal

# Result: typecheck FAILS — missing @clerk/nextjs

サイクル 1 の呼び出し合計：4 回（precision_read + discover + precision_write + precision_exec）

サイクル 2：不足している依存関係を修正

ステップ 1 — GATHER（1 回の呼び出し）

discover:
  queries:
    - id: package_json
      type: glob
      patterns: ["package.json"]
    - id: clerk_usage
      type: grep
      pattern: "@clerk/nextjs"
      glob: "src/**/*.{ts,tsx}"
  verbosity: files_only

ステップ 2 — PLAN（0 回の呼び出し、認知作業）

Discovery: @clerk/nextjs not in package.json
Plan:
Apply Call 1 (precision_exec): npm install @clerk/nextjs, then typecheck

ステップ 3 — APPLY（1 回の呼び出し）

precision_exec:
  commands:
    - cmd: "npm install @clerk/nextjs"
    - cmd: "npm run typecheck"
      expect:
        exit_code: 0
  verbosity: minimal

# Result: PASSES

サイクル 2 の呼び出し合計：2 回（discover + precision_exec）

よくある違反と修正方法

違反	ツール呼び出し回数	修正方法
precision_read の連続呼び出し	5 回以上	すべてのファイルを 1 回の precision_read 呼び出しにまとめる
precision_write の連続呼び出し	5 回以上	すべてのファイルを 1 回の precision_write 呼び出しにまとめる
precision_glob と precision_grep を別々に使用	2 回以上	両方のクエリタイプを含めて 1 回の discover 呼び出しを使用する
アウトラインを読んでから内容を読む	2 回	内容が必要な場合は、最初に一度だけ読む
ツール呼び出しによる計画	1 回以上	テキストで計画する（認知作業は呼び出し 0 回）
メモリの読み取りを省略	-	Gather フェーズでは必ず .goodvibes/memory/ を確認する

適用の徹底

1 つのフェーズ内で同じ種類のツールを 2 回使っていることに気づいた場合、プロトコルに違反しています。いったん止めて、構成を見直してください。

1. 調査にあたる呼び出しを特定し、1 回の discover 呼び出しにまとめる
2. メモリやファイルの読み取りにあたる呼び出しを特定し、1 回の precision_read 呼び出しにまとめる
3. 書き込みや編集にあたる呼び出しを特定し、同じ種類の呼び出しにまとめる（書き込み同士、編集同士）
4. 計画はツールではなく、テキストで行う

目標：フェーズごとにツールの種類あたり 1 回の呼び出し。

まとめ

• G（Gather）：メモリを確認 + discover + 必要に応じて主要ファイルの precision_read
• P（Plan）：呼び出し 0 回（認知作業）
• A（Apply）：検証のための precision_write／precision_edit + precision_exec
• LOOP：必要に応じて新しいサイクルを開始

ルール：フェーズごとにツールの種類あたり 1 回の呼び出し。各呼び出しで、できる限りまとめて処理してください。

これをデフォルトの動作モードにしてください。