precision-mastery

リソース

scripts/
  validate-precision-usage.sh
references/
  tool-reference.md

精密操作をマスターする

精密操作エンジンは、標準ツール（Read、Edit、Write、Grep、Glob、WebFetch）に代わる、トークン効率の高い手段を提供します。正しく使用すると、ファイル操作でトークンを75～95%節約できます。このスキルでは、最適な使い方を説明します。

冗長度のクイックガイド

必要な要件を満たす、最も低い冗長度を使用してください。冗長度はトークン消費量に直接影響します。

操作	デフォルト	推奨	理由
precision_write	standard	count_only	内容はすでに指定されているため、成功を確認するだけで十分です
precision_edit	with_diff	minimal	適用を確認し、デバッグ時以外は差分を省略します
precision_read	standard	standard	内容を確認する必要があります
precision_grep（検出）	standard	output.format で files_only	検出段階であり、内容を確認する段階ではありません
precision_grep（内容）	standard	output.format で matches	実際に一致した行が必要です
precision_glob	standard	output.format で paths_only	統計情報ではなく、ファイルパスが必要です
precision_exec（検証）	standard	minimal	stdout/stderr 全体が必要な場合を除きます
precision_exec（デバッグ）	standard	standard	問題を診断するために出力が必要です
precision_fetch	standard	standard	内容を確認する必要があります
discover	files_only（verbosity パラメーター）	files_only	検出段階であり、内容を確認する段階ではありません
precision_symbols	locations（verbosity パラメーター）	locations	通常はファイル名と行番号だけで十分です

トークン倍率：

• count_only：トークン約0.05倍
• minimal：トークン約0.2倍
• standard：トークン約0.6倍
• verbose：トークン1.0倍

基本ルール：書き込み／編集した内容を読み返す必要がない場合は、count_only を使用してください。

抽出モードの選択（precision_read）

ファイルを読む前に、何を知りたいのかを判断してください。抽出モードを使うと、全内容を取得する場合と比べてトークンを60～95%節約できます。

モード	使用する場面	トークン節約率	使用例
content	ファイル全体を読んで理解する必要がある	0%	設定ファイルの読み取り、編集対象のコードの読み取り
outline	内容ではなく構造が必要	60～80%	ファイル構成の把握、関数の検索
symbols	インポート用のエクスポート済みシンボルが必要	70～90%	インポート文の作成、API サーフェスの分析
ast	構造パターンが必要	50～70%	リファクタリング、パターン検出
lines	特定の行範囲が必要	80～95%	grep で見つけた後、特定の関数を読む

ベストプラクティス：

1. まず outline でファイル構造を把握します
2. インポート文の作成や API サーフェスの把握には symbols を使用します
3. grep で場所を特定した後、range: { start, end } を指定して lines を使用します
4. ファイル全体が本当に必要な場合にのみ content を使用します

# Step 1: Get structure
precision_read:
  files: [{ path: "src/components/Button.tsx", extract: outline }]
  verbosity: standard

# Step 2: If you need full content, read it
precision_read:
  files: [{ path: "src/components/Button.tsx", extract: content }]
  verbosity: standard

バッチ処理のパターン

バッチ処理は、トークンを節約するうえで最も重要な手法です。可能な場合は、常に操作をまとめて実行してください。

1. 複数ファイルの読み取り（1回の呼び出し）

5～10個のファイルを、5～10回に分けて呼び出すのではなく、1回の precision_read 呼び出しで読み取ります。

# Bad (5 separate calls)
precision_read:
  files: [{ path: "file1.ts" }]
precision_read:
  files: [{ path: "file2.ts" }]
# ...

# Good (1 batched call)
precision_read:
  files: [
    { path: "file1.ts", extract: outline },
    { path: "file2.ts", extract: outline },
    { path: "file3.ts", extract: outline },
    { path: "file4.ts", extract: outline },
    { path: "file5.ts", extract: outline }
  ]
  verbosity: minimal

2. 複数クエリの検出（1回の呼び出し）

discover を1回呼び出し、grep、glob、symbols のクエリを同時に実行します。これは最も強力な検出パターンです。

discover:
  queries:
    - id: find_components
      type: glob
      patterns: ["src/components/**/*.tsx"]
    - id: find_api_routes
      type: glob
      patterns: ["src/api/**/*.ts", "src/app/api/**/*.ts"]
    - id: find_auth_usage
      type: grep
      pattern: "useAuth|getSession|withAuth"
      glob: "src/**/*.{ts,tsx}"
    - id: find_hooks
      type: symbols
      query: "use"
      kinds: ["function"]
  verbosity: files_only

重要な理由：並列実行により、4つのクエリすべてが順次実行時の約200ミリ秒ではなく、約50ミリ秒で完了します。

3. 複数編集のアトミックトランザクション（1回の呼び出し）

アトミックトランザクションを使用し、1回の precision_edit 呼び出しで複数ファイルにわたる編集を適用します。いずれかの編集に失敗すると、すべての変更がロールバックされます。

precision_edit:
  edits:
    - path: "src/components/Button.tsx"
      find: "export default Button"
      replace: "export { Button as default }"
    - path: "src/components/index.ts"
      find: "export { default as Button } from './Button'"
      replace: "export { Button } from './Button'"
  transaction:
    mode: "atomic"
  verbosity: minimal

4. 複数ファイルの書き込み（1回の呼び出し）

1回の precision_write 呼び出しで複数のファイルを作成します。

precision_write:
  files:
    - path: "src/features/user/index.ts"
      content: |
        export * from './types';
        export * from './api';
        export * from './hooks';
    - path: "src/features/user/types.ts"
      content: |
        export interface User {
          id: string;
          email: string;
          name: string;
        }
    - path: "src/features/user/api.ts"
      content: |
        import type { User } from './types';
        export const getUser = async (id: string): Promise<User> => { /* ... */ };
  verbosity: count_only

5. 精密ツールのバッチ処理（最適）

バッチ処理の最上位の方法は、複数の精密ツールの呼び出しを単一のトランザクションにまとめることです。

各操作タイプ（read、write、exec、query）では、対応する precision_engine ツールのスキーマを使用します。たとえば、

• read 操作では precision_read スキーマを使用します（files 配列を使用）
• write 操作では precision_write スキーマを使用します（files 配列を使用）
• exec 操作では precision_exec スキーマを使用します（commands 配列を使用）
• query 操作では precision_grep／precision_glob スキーマを使用します

batch:
  operations:
    read:
      - files:
          - path: "src/types.ts"
            extract: symbols
    write:
      - files:
          - path: "src/features/auth/types.ts"
            content: |
              export interface User {
                id: string;
                email: string;
                name: string;
              }
    exec:
      - commands:
          - cmd: "npm run typecheck"
            expect:
              exit_code: 0
  config:
    transaction:
      mode: atomic
  verbosity: minimal

トークン予算とページネーション

大きなファイルやバッチ読み取りでは、出力サイズを制御するために token_budget を使用します。

# Read up to 20 files, but cap total output at 5K tokens
precision_read:
  files: [
    { path: "file1.ts" },
    { path: "file2.ts" },
    # ...
  ]
  token_budget: 5000
  page: 1  # Start with page 1
  verbosity: standard

結果が切り詰められた場合は、page を増やして次のバッチを取得します。

出力形式の選択（precision_grep）

precision_grep には、count_only、files_only、locations、matches、context の複数の出力形式があります。

形式	用途	トークンコスト
count_only	範囲の把握	非常に低い
files_only	検索フェーズ	低い
locations	対象がどこにあるかを特定	中程度
matches	実際に一致した行が必要な場合	高い
context	周辺のコードが必要な場合	非常に高い

段階的な情報開示：まず count_only で範囲を把握し、次に files_only で対象リストを作成し、その後 matches で内容を取得します。

ツールオーケストレーションの検出

discover ツールは、複数のクエリ（grep、glob、symbols）を並列実行するメタツールです。実装の前には必ず使用してください。

検出パターン：

1. 複数のクエリを指定して discover を実行します
2. 結果を分析して範囲を把握します
3. 検出結果に基づいて作業を計画します
4. バッチ処理で実行します

# Step 1: Discover
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"
  verbosity: files_only

# Step 2: Read key files with outline based on discovery
precision_read:
  files: [{ path: "src/features/auth/index.ts", extract: outline }]
  verbosity: minimal

# Step 3: Execute based on what was discovered
precision_write:
  files:
    - path: "src/features/auth/middleware.ts"
      content: "..."
  verbosity: count_only

precision_exec のパターン

1. バックグラウンドプロセス

長時間実行されるプロセスは、処理をブロックしないようバックグラウンドで実行します。

precision_exec:
  commands:
    - cmd: "npm run dev"
      background: true
  verbosity: minimal

2. 再試行パターン

不安定なコマンドを自動的に再試行します。

precision_exec:
  commands:
    - cmd: "npm install"
      retry:
        max: 3
        delay_ms: 1000
  verbosity: minimal

3. 条件成立までのパターン

条件が満たされるまでポーリングします。

precision_exec:
  commands:
    - cmd: "curl http://localhost:3000/api/health"
      until:
        pattern: "ok"
        timeout_ms: 30000
  verbosity: minimal

precision_fetch のパターン

1. URL のバッチ処理

複数の URL を 1 回の呼び出しで取得します。

precision_fetch:
  urls:
    - url: "https://api.example.com/users"
    - url: "https://api.example.com/posts"
    - url: "https://api.example.com/comments"
  verbosity: standard

2. 抽出モード

JSON レスポンスから特定のデータを抽出します。

precision_fetch:
  urls:
    - url: "https://api.example.com/users"
      extract: json  # Extract mode: raw, text, json, markdown, structured, etc.
  verbosity: standard

3. サービスレジストリ認証

事前設定済みのサービスを使用して、自動認証を行います。

precision_fetch:
  urls:
    - url: "https://api.openai.com/v1/models"
      service: "OpenAI"  # Auto-applies bearer token from config
  verbosity: standard

アンチパターン（絶対に行わないでください）

1. ネイティブツールの使用：Read、Edit、Write、Glob、Grep、WebFetch の使用は避けてください。precision の同等ツールを使用します。

2. 書き込み／編集で verbosity を "verbose" に設定する：トークンを無駄にします。書いた内容を、なぜ読み返す必要があるのでしょうか？

3. 概要やシンボルだけが必要なのにファイル全体を読む：抽出モードを使用します。

4. discover クエリを 1 つずつ実行する：まとめて実行します。

5. precision_grep のほうが速く見つけられる場合に precision_read を使用する：Grep は検索に最適化されています。

6. 書き込んだばかりのファイルを読む：内容はすでに把握しています。

7. 実装前に discover を使用しない：事前に調べずに実装すると、パターンの不一致につながります。

8. バッチ処理できる精密ツールの呼び出しを複数回に分けて順次行う：同じツールを 3 回以上呼び出す場合は、まとめて実行します。

9. verbosity: verbose をデフォルトで使用する：デバッグ時にのみ使用します。

10. 大きなバッチ読み取りで token_budget を無視する：予算を設定しないと、結果が切り詰められる可能性があります。

エスカレーション手順

精密ツールが失敗した場合：

1. エラーを確認する：ユーザー側のエラー（パスの誤り、構文の誤り）でしょうか？修正して再試行します。

2. ツール自体が失敗した場合：その特定のタスクに限り、ネイティブツールを使用します。

3. 精密ツールに戻る：次の操作では精密ツールを使用します。

4. 失敗を記録する：.goodvibes/memory/failures.json に記録します。

例：

• 特定のファイルで precision_read が失敗した場合 => そのファイルに限り Read を使用し、他のファイルでは precision_read に戻ります。
• 特定の編集で precision_edit が失敗した場合 => その編集に限り Edit を使用し、他の編集では precision_edit に戻ります。

絶対に行わないこと：1 回の呼び出しが失敗したからといって、精密ツールの使用を完全にやめないでください。

決定木：どのツールを使うか？

Do I know the exact file paths?
  |-- Yes -- precision_read (with appropriate extract mode)
  +-- No -- Do I know a pattern?
      |-- Yes -- precision_glob
      +-- No -- Am I searching for content?
         |-- Yes -- precision_grep
         +-- No -- Am I searching for symbols?
            |-- Yes -- precision_symbols
            +-- No -- Use discover with multiple query types

専用ツール（上記のツリーには含まれません）：

• precision_notebook — Jupyter ノートブックのセル操作（cell_id を指定した置換／挿入／削除）
• precision_agent — dossier ベースのコンテキスト注入を使用して、ヘッドレスの Claude セッションを起動します
• precision_config — 実行時設定（取得／設定／再読み込み）

パフォーマンスのベンチマーク

トークンの節約：

• outline と content の比較：60～80% 節約
• symbols と content の比較：70～90% 節約
• count_only と verbose の比較：95% 節約
• 5 ファイルのバッチ処理と個別の 5 回の呼び出しの比較：40～60% 節約（オーバーヘッドの削減）
• 4 件の並列 discover と逐次処理の比較：75% 高速化、トークンコストは同程度

時間の節約：

• 並列 discover（4 クエリ）：逐次処理の約 200ms に対し約 50ms
• 書き込みのバッチ処理（5 ファイル）：個別処理の約 400ms に対し約 80ms
• トランザクションを使用した編集のバッチ処理：失敗時にアトミックにロールバック

クイックリファレンス

よく使われるパターン：

# 1. Discover before implementing
discover:
  queries:
    - id: files
      type: glob
      patterns: ["pattern"]
    - id: patterns
      type: grep
      pattern: "regex"
  verbosity: files_only

# 2. Read with outline first
precision_read:
  files: [{ path: "file.ts", extract: outline }]
  verbosity: minimal

# 3. Batch writes with count_only
precision_write:
  files:
    - { path: "file1.ts", content: "..." }
    - { path: "file2.ts", content: "..." }
  verbosity: count_only

# 4. Batch edits with atomic transaction
precision_edit:
  edits:
    - { path: "f1.ts", find: "...", replace: "..." }
    - { path: "f2.ts", find: "...", replace: "..." }
  transaction: { mode: "atomic" }
  verbosity: minimal

# 5. Verify with minimal output
precision_exec:
  commands:
    - { cmd: "npm run typecheck", expect: { exit_code: 0 } }
  verbosity: minimal

---

覚えておいてください：precision engine はトークンを節約できますが、適切な詳細レベル、抽出モード、バッチ処理パターンを選んだ場合に限られます。このスキルを、効率的なツール使用のためのチートシートとして活用してください。