ccw-cli-tools

CLI ツール - 統合実行フレームワーク

目的：設定に基づくツール選択、統一されたプロンプトテンプレート、品質ゲート付きの実行により、構造化された CLI ツールの使用を実現します。

設定：~/.claude/cli-tools.json（グローバル、初期化時に必ず読み込みます）

初期化（最初に必ず実行）

ツールの選択や推奨を行う前に：

1. 設定がメモリ内にあるか確認します。

   • 設定が会話メモリにすでにある場合 → そのまま使用します
   • メモリ内にない場合 → 設定ファイルを読み込みます：

     Read(file_path="~/.claude/cli-tools.json")
     

2. JSON を解析し、以下を確認します。

   • 利用可能なツールとその enabled ステータス
   • 各ツールの primaryModel と secondaryModel
   • タグベースのルーティングに定義されているタグ
   • ツールの種類（builtin、cli-wrapper、api-endpoint）

3. 選択プロセス全体を通じて設定を使用します

理由：ツール、モデル、タグは変更される可能性があります。設定ファイルを唯一の信頼できる情報源とします。 最適化：冗長なファイル読み込みを避けるため、メモリ内の設定を再利用します。

プロセスフロー

┌─ USER REQUEST
│
├─ STEP 1: Load Configuration
│  ├─ Check if configuration exists in conversation memory
│  └─ If NOT in memory → Read(file_path="~/.claude/cli-tools.json")
│
├─ STEP 2: Understand User Intent
│  ├─ Parse task type (analysis, implementation, security, etc.)
│  ├─ Extract required capabilities (tags)
│  └─ Identify scope (files, modules)
│
├─ STEP 3: Select Tool (based on config)
│  ├─ Explicit --tool specified?
│  │  YES → Validate in config → Use it
│  │  NO  → Match tags with enabled tools → Select best match
│  │       → No match → Use first enabled tool (default)
│  └─ Get primaryModel from config
│
├─ STEP 4: Build Prompt
│  └─ Use 6-field template: PURPOSE, TASK, MODE, CONTEXT, EXPECTED, CONSTRAINTS
│
├─ STEP 5: Select Rule Template
│  ├─ Determine rule from task type
│  └─ Pass via --rule parameter
│
├─ STEP 6: Execute CLI Command
│  └─ ccw cli -p "<PROMPT>" --tool <tool> --mode <mode> --rule <rule>
│
└─ STEP 7: Handle Results
   ├─ On success → Deliver output to user
   └─ On failure → Check secondaryModel or fallback tool

設定リファレンス

設定ファイルの場所

パス：~/.claude/cli-tools.json（グローバル設定）

重要：まず会話メモリを確認してください。設定がメモリ内にない場合にのみ、ファイルを読み込みます。

設定の読み込み

優先事項：まず会話メモリを確認します

読み込み方法：

• 方法 1（推奨）：会話内ですでに読み込まれている場合は、メモリ内の設定を使用します
• 方法 2（代替）：メモリ内にない場合は、ファイルから読み込みます

# Read configuration file
cat ~/.claude/cli-tools.json

設定には、利用可能なすべてのツール、その有効ステータス、モデル、タグが定義されています。

設定の構造

JSON ファイルには tools オブジェクトが含まれ、各ツールには以下のフィールドがあります。

フィールド	型	説明	例
enabled	boolean	ツールの利用可否ステータス	true または false
primaryModel	string	実行時のデフォルトモデル	"gemini-2.5-pro"
secondaryModel	string	プライマリモデルが失敗した場合のフォールバックモデル	"gemini-2.5-flash"
tags	array	ルーティング用の機能タグ	["分析", "Debug"]
type	string	ツールの種類	"builtin"、"cli-wrapper"、"api-endpoint"

想定されるツール（参考のみ）

設定内で一般的に見られるツール（実際に利用可能かどうかは、ファイルを読み込んで確認します）：

ツール	一般的な種類	主な用途
gemini	builtin	分析、Debug（分析、Debug タグ）
qwen	builtin	一般的なコーディング
codex	builtin	コードレビュー、実装
claude	builtin	一般的なタスク
opencode	builtin	オープンソースモデルのフォールバック

注：ツールの利用可否、モデル、タグは異なる場合があります。メモリ内の設定を使用するか、キャッシュされていない場合は ~/.claude/cli-tools.json を読み込んでください。

設定フィールド

• enabled：ツールの利用可否（boolean）
• primaryModel：実行時のデフォルトモデル
• secondaryModel：プライマリモデルが失敗した場合のフォールバックモデル
• tags：ルーティング用の機能タグ（分析、Debug、実装など）
• type：ツールの種類（builtin、cli-wrapper、api-endpoint）

汎用プロンプトテンプレート

構造：すべての CLI コマンドは、この 6 フィールドのテンプレートに従います

ccw cli -p "PURPOSE: [goal] + [why] + [success criteria] + [scope]
TASK: • [step 1: specific action] • [step 2: specific action] • [step 3: specific action]
MODE: [analysis|write|review]
CONTEXT: @[file patterns] | Memory: [session/tech/module context]
EXPECTED: [deliverable format] + [quality criteria] + [structure requirements]
CONSTRAINTS: [domain constraints]" --tool <tool-id> --mode <mode> --rule <template>

フィールドの仕様

PURPOSE（目標の定義）

内容：明確な目的 + 動機 + 成功基準 + スコープの境界

構成要素：

• What：具体的なタスクの目標
• Why：ビジネス上または技術上の動機
• Success：測定可能な成功基準
• Scope：範囲を限定したコンテキスト／ファイル

例 - 良い例：

PURPOSE: Identify OWASP Top 10 vulnerabilities in auth module to pass security audit;
success = all critical/high issues documented with remediation;
scope = src/auth/** only

例 - 悪い例：

PURPOSE: Analyze code

TASK（アクションの手順）

内容：明確な動詞と対象を含む、具体的で実行可能な手順

形式：具体的なアクションを箇条書きで記述します

例 - 良い例：

TASK:
• Scan for SQL injection in query builders
• Check XSS in template rendering
• Verify CSRF token validation

例 - 悪い例：

TASK: Review code and find issues

MODE（権限レベル）

オプション：

• analysis - 読み取り専用、自動実行しても安全です
• write - ファイルの作成／変更／削除、すべての操作
• review - Git を考慮したコードレビュー（codex のみ）

ルール：

• 必ず明示的に指定してください
• 読み取り専用タスクでは、デフォルトで analysis を使用してください
• ファイルを変更する場合は、明示的に --mode write を指定してください
• Git を考慮したレビューには、--tool codex とともに --mode review を使用してください

CONTEXT（ファイル範囲 + メモリ）

形式：CONTEXT: @[file patterns] | Memory: [memory context]

ファイルパターン：

• @**/* - すべてのファイル（デフォルト）
• @src/**/*.ts - 特定のパターン
• @../shared/**/* - 親／兄弟ディレクトリ（--includeDirs が必要）

メモリコンテキスト（以前の作業を引き継ぐ場合）：

Memory: Building on auth refactoring (commit abc123), using JWT for sessions
Memory: Integration with auth module, shared error patterns from @shared/utils/errors.ts

EXPECTED（出力仕様）

内容：出力形式 + 品質基準 + 構造要件

例 - 良い例：

EXPECTED: Markdown report with:
severity levels (Critical/High/Medium/Low),
file:line references,
remediation code snippets,
priority ranking

例 - 悪い例：

EXPECTED: Report

CONSTRAINTS（適用範囲）

内容：範囲の制限、特別な要件、重点領域

例 - 良い例：

CONSTRAINTS: Focus on authentication | Ignore test files | No breaking changes

例 - 悪い例：

CONSTRAINTS: (missing or too vague)

CLI 実行モード

MODE: analysis

• 権限：読み取り専用
• 用途：コードレビュー、アーキテクチャ分析、パターンの発見、調査
• 安全性：はい - 自動実行できます
• デフォルト：指定がない場合

MODE: write

• 権限：ファイルの作成／変更／削除
• 用途：機能の実装、バグ修正、ドキュメント作成、コード作成
• 安全性：いいえ - 明示的な --mode write が必要です
• 要件：ユーザーによる明示的な要求が必要です

MODE: review

• 権限：読み取り専用（Git を考慮したレビュー出力）
• 用途：未コミットの変更、ブランチの差分、特定のコミットのコードレビュー
• ツールのサポート：codex のみ（それ以外は analysis として扱われます）
• 制約：対象フラグ（--uncommitted、--base、--commit）とプロンプトは相互に排他的です

コマンド構造

基本コマンド

ccw cli -p "<PROMPT>" --tool <tool-id> --mode <analysis|write|review>

コマンドオプション

オプション	説明	例
--tool <tool>	設定から選ぶツール	--tool gemini
--mode <mode>	必須：analysis/write/review	--mode analysis
--model <model>	モデルの上書き	--model gemini-2.5-flash
--cd <path>	作業ディレクトリ	--cd src/auth
--includeDirs <dirs>	追加ディレクトリ	--includeDirs ../shared,../types
--rule <template>	テンプレートを自動読み込み	--rule analysis-review-architecture
--resume [id]	セッションを再開	--resume または --resume <id>

高度なディレクトリ設定

作業ディレクトリ（--cd）

--cd を使用する場合：

• @**/* = 作業ディレクトリツリー内のファイルのみ
• --includeDirs がない場合、親／兄弟ディレクトリは参照できません
• コンテキストの範囲を絞ることで、トークンの使用量を削減します

インクルードディレクトリ（--includeDirs）

外部ファイルを指定するための 2 段階の要件：

1. --includeDirs パラメーターを追加します
2. CONTEXT で @ パターンを使って参照します

# Single directory
ccw cli -p "CONTEXT: @**/* @../shared/**/*" \
  --tool gemini --mode analysis \
  --cd src/auth --includeDirs ../shared

# Multiple directories
ccw cli -p "..." \
  --tool gemini --mode analysis \
  --cd src/auth --includeDirs ../shared,../types,../utils

セッションの再開

使用する場面：

• 複数ラウンドの計画（分析 → 計画 → 実装）
• 複数モデルでの協業（同じトピックでツール A → ツール B）
• トピックの継続（以前の調査結果を引き継ぐ）

使用方法：

ccw cli -p "Continue analyzing" --tool <tool-id> --mode analysis --resume              # Resume last
ccw cli -p "Fix issues found" --tool <tool-id> --mode write --resume <id>              # Resume specific
ccw cli -p "Merge findings" --tool <tool-id> --mode analysis --resume <id1>,<id2>      # Merge sessions

使用可能なルールテンプレート

テンプレートシステム

--rule <template-name> を使用すると、プロトコル + テンプレートがプロンプトに追加され、自動的に読み込まれます

汎用テンプレート

• universal-rigorous-style - 明確に定義されたタスク（デフォルト）
• universal-creative-style - 探索的なタスク

分析テンプレート

• analysis-trace-code-execution - 実行のトレース
• analysis-diagnose-bug-root-cause - バグの原因究明
• analysis-analyze-code-patterns - コードパターンの分析
• analysis-analyze-technical-document - ドキュメント分析
• analysis-review-architecture - アーキテクチャレビュー
• analysis-review-code-quality - コードレビュー
• analysis-analyze-performance - パフォーマンス分析
• analysis-assess-security-risks - セキュリティリスクの評価

計画テンプレート

• planning-plan-architecture-design - アーキテクチャ設計
• planning-breakdown-task-steps - タスクの分解
• planning-design-component-spec - コンポーネント設計
• planning-plan-migration-strategy - 移行戦略

開発テンプレート

• development-implement-feature - 機能の実装
• development-refactor-codebase - コードのリファクタリング
• development-generate-tests - テストの生成
• development-implement-component-ui - UI コンポーネント
• development-debug-runtime-issues - ランタイムのデバッグ

タスクタイプ別の例

例 1：セキュリティ分析（読み取り専用）

ccw cli -p "PURPOSE: Identify OWASP Top 10 vulnerabilities in authentication module to pass security audit; success = all critical/high issues documented with remediation
TASK: • Scan for injection flaws (SQL, command, LDAP) • Check authentication bypass vectors • Evaluate session management • Assess sensitive data exposure
MODE: analysis
CONTEXT: @src/auth/**/* @src/middleware/auth.ts | Memory: Using bcrypt for passwords, JWT for sessions
EXPECTED: Security report with: severity matrix, file:line references, CVE mappings where applicable, remediation code snippets prioritized by risk
CONSTRAINTS: Focus on authentication | Ignore test files
" --tool gemini --mode analysis --rule analysis-assess-security-risks --cd src/auth

例 2：機能の実装（書き込みモード）

ccw cli -p "PURPOSE: Implement rate limiting for API endpoints to prevent abuse; must be configurable per-endpoint; backward compatible with existing clients
TASK: • Create rate limiter middleware with sliding window • Implement per-route configuration • Add Redis backend for distributed state • Include bypass for internal services
MODE: write
CONTEXT: @src/middleware/**/* @src/config/**/* | Memory: Using Express.js, Redis already configured, existing middleware pattern in auth.ts
EXPECTED: Production-ready code with: TypeScript types, unit tests, integration test, configuration example, migration guide
CONSTRAINTS: Follow existing middleware patterns | No breaking changes
" --tool gemini --mode write --rule development-implement-feature

例 3：バグの根本原因分析

ccw cli -p "PURPOSE: Fix memory leak in WebSocket connection handler causing server OOM after 24h; root cause must be identified before any fix
TASK: • Trace connection lifecycle from open to close • Identify event listener accumulation • Check cleanup on disconnect • Verify garbage collection eligibility
MODE: analysis
CONTEXT: @src/websocket/**/* @src/services/connection-manager.ts | Memory: Using ws library, ~5000 concurrent connections in production
EXPECTED: Root cause analysis with: memory profile, leak source (file:line), fix recommendation with code, verification steps
CONSTRAINTS: Focus on resource cleanup
" --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause --cd src

例 4：コードレビュー（Codex レビューモード）

# Option 1: Custom focus (reviews uncommitted by default)
ccw cli -p "Focus on security vulnerabilities and error handling" --tool codex --mode review

# Option 2: Target flag only (no prompt with target flags)
ccw cli --tool codex --mode review --uncommitted
ccw cli --tool codex --mode review --base main
ccw cli --tool codex --mode review --commit abc123

ツール選択戦略

選択アルゴリズム

STEP 0（必須）：設定を読み込みます（メモリ優先戦略）

# Check if configuration exists in conversation memory
# If YES → Use in-memory configuration
# If NO → Read(file_path="~/.claude/cli-tools.json")

次に、選択を進めます。

1. タスクの意図を解析 → 必要な機能を抽出します
2. 設定を読み込む → JSON から有効なツールとタグを解析します
3. タグを照合する → 必要な機能に対応するツールを絞り込みます
4. ツールを選択する → 優先順位（明示指定 > タグ一致 > デフォルト）に従って選択します
5. モデルを選択する → primaryModel を使用し、利用できない場合は secondaryModel に切り替えます

選択決定木

0. LOAD CONFIGURATION (memory-first)
   ├─ In memory? → Use it
   └─ Not in memory? → Read ~/.claude/cli-tools.json
   ↓
1. Explicit --tool specified?
   YES → Validate tool is enabled in config → Use it
   NO  → Proceed to tag-based selection
         ├─ Extract task tags (security, analysis, implementation, etc.)
         │  ├─ Find tools with matching tags
         │  │  ├─ Multiple matches? Use first enabled
         │  │  └─ Single match? Use it
         │  └─ No tag match? Use default tool
         │
         └─ Default: Use first enabled tool in config

よく使われるタグのルーティング

注：タスクタイプを ~/.claude/cli-tools.json で定義されたタグと照合してください。

タスクタイプ	照合する一般的なタグ
セキュリティ監査	分析, analysis, security
バグ診断	Debug, 分析, analysis
実装	implementation、（有効なツールはすべて）
テスト	testing、（有効なツールはすべて）
リファクタリング	refactoring、（有効なツールはすべて）
ドキュメント作成	documentation、（有効なツールはすべて）

選択ロジック：tags 配列に一致するキーワードを含むツールを探します。一致するものがなければ、最初の有効なツールを使用します。

フォールバックチェーン

プライマリツールが失敗した場合（~/.claude/cli-tools.json の設定に基づきます）：

1. 同じツールの secondaryModel を確認します（設定の secondaryModel を使用します）
2. タグが一致する次の有効なツールを試します（設定内の有効なツールを確認します）
3. デフォルトの有効なツールに切り替えます（設定内で最初に有効になっているツール）

フォールバックの例：

Tool1: primaryModel fails
  ↓
Try Tool1: secondaryModel
  ↓ (if fails)
Try Tool2: primaryModel (next enabled with matching tags)
  ↓ (if fails)
Try default: first enabled tool

権限フレームワーク

1 回限りの承認：実行のたびに、ユーザーから明示的な指示を受ける必要があります。以前の承認は引き継がれません。

モードの階層：

• analysis：読み取り専用、自動実行しても安全です
• write：ファイルの作成・変更・削除を行います。明示的に --mode write を指定する必要があります
• review：Git を考慮したコードレビュー（codex のみ）です。明示的に --mode review を指定する必要があります
• 例外：「変更」「作成」「実装」などの明確な指示をユーザーが提示した場合

自動呼び出しのトリガー

CLI のプロアクティブな呼び出し - 次の状況に遭遇した場合、ccw cli を自動的に呼び出します。

トリガー	推奨ルール	タイミング
自己修復に失敗	analysis-diagnose-bug-root-cause	修正を 1 回以上試みて失敗した後
要件が曖昧	planning-breakdown-task-steps	タスクの説明が不明確な場合
アーキテクチャの決定	planning-plan-architecture-design	複雑な機能に設計が必要な場合
パターンが不確か	analysis-analyze-code-patterns	既存の規約が不明な場合
重要なコードパス	analysis-assess-security-risks	セキュリティまたはパフォーマンスに注意が必要な場合

自動呼び出しの実行原則

• デフォルトモード：--mode analysis（読み取り専用で安全）
• 確認は不要：トリガーに該当したら、プロアクティブに呼び出します
• 結果を待つ：次のアクションに進む前に、分析を完了します
• ツールの選択：状況に適したツール、またはフォールバックチェーンを使用します
• ルールの柔軟性：推奨ルールはガイドラインです。必要に応じて調整してください

ベストプラクティス

基本原則

• 設定駆動 - すべてのツール選択は cli-tools.json から行います
• タグベースのルーティング - タスクの要件とツールの機能を照合します
• 早めに、頻繁にツールを使う - ツールは手動分析より高速で、より徹底的です
• 統一 CLI - パラメーター処理の一貫性を保つため、常に ccw cli -p を使用します
• デフォルトは分析 - 読み取り専用の場合は --mode を省略し、変更する場合は明示的に --mode write を使用します
• テンプレートには --rule を使用 - プロトコルとテンプレートを自動読み込みし、プロンプトに追加します
• 書き込み保護 - ファイル操作には明示的な --mode write を必須とします

ワークフローの原則

• 統一インターフェースを使用 - 常に ccw cli -p 形式を使用します
• 常にテンプレートを含める - --rule <template-name> を使用してテンプレートを読み込みます
• 具体的に記述する - PURPOSE、TASK、EXPECTED フィールドを明確にします
• 制約を含める - CONSTRAINTS にファイルパターンと対象範囲を記載します
• メモリーコンテキストを活用する - 以前の作業を基に進める場合に使用します
• まずパターンを調べる - CLI を実行する前に rg/MCP を使用します
• デフォルトで全コンテキストを使用 - 特定のファイルが必要な場合を除き、@**/* を使用します

計画チェックリスト

• 目的を定義 - 目標と意図を明確にします
• モードを選択 - --mode analysis|write|review
• コンテキストを収集 - ファイル参照とメモリー（デフォルトは @**/*）
• ディレクトリを移動 - 必要に応じて --cd および／または --includeDirs を使用します
• ツールを選択 - --tool を明示するか、タグベースの自動選択を使用します
• ルールテンプレート - --rule <template-name> でテンプレートを読み込みます
• 制約 - CONSTRAINTS フィールドにドメイン固有の制約を記載します

CLAUDE.md の指示との統合

グローバルな CLAUDE.md より：

• Task ツールのエージェント呼び出しでは、常に run_in_background: false を使用します
• デフォルト：CLI 呼び出しでは Bash の run_in_background: true を使用します
• CLI 呼び出し後：直ちに出力を停止し、フックのコールバックを待ちます
• 結果を待つ：書き込み操作を行う前に、CLI の分析結果を必ず待ちます
• すべての呼び出しを有効活用：分析結果を無駄にせず、解決策を提案する前に集約します

cli-tools-usage.md より：

• cli-tools.json の設定を厳守します
• 設定駆動でツールを選択します
• --rule による自動読み込みを備えたテンプレートシステムを使用します
• 1回限りの認可を伴う権限フレームワークを使用します
• よくある失敗シナリオでは自動呼び出しをトリガーします