pro-workflow

プロワークフロー

実運用から生まれた、AI コーディングワークフローの完全なシステムです。オーケストレーションのパターン、リファレンスガイド、実戦で鍛えられた習慣が、時間とともに相乗効果を生み出します。

対応環境： Claude Code、Cursor、Codex、Gemini CLI、および skills add を介した 32 以上の AI コーディングエージェント。(Claude Code) と記されたセクションは Claude Code 固有の機能を使用しています。Cursor ユーザーはこれらをスキップするか、記載されている代替手段を使用できます。

中核となる考え方

「コードの 80% は AI が書き、20% はレビューと修正に費やしています。」— Karpathy

このスキルは、この比率を最適化します。ここで紹介するすべてのパターンが、修正サイクルを減らします。

---

1. 自己修正ループ

最も強力なパターンです。 修正を通じて、あなたの CLAUDE.md が自ら学習します。

仕組み

Claude に修正を指摘すると：

1. Claude が誤りを認めます
2. 再発を防ぐルールを提案します
3. あなたが承認すると → ルールがメモリに追加されます
4. 次回以降のセッションでは、同じ誤りを回避します

CLAUDE.md に追加

## Self-Correction Protocol

When the user corrects me or I make a mistake:
1. Acknowledge specifically what went wrong
2. Propose a concise rule: `[LEARN] Category: One-line rule`
3. Wait for approval before adding to LEARNED section

### LEARNED

トリガーフレーズ

• 「その内容をルールに追加して」
• 「これを覚えておいて」
• 「もう二度としないで」

使用例

User: You edited the wrong file
Claude: I edited src/utils.ts when you meant src/lib/utils.ts.

[LEARN] Navigation: Confirm full path before editing files with common names.

Should I add this?

---

1b. 事前確認の徹底

自己修正は事後に誤りを検出します。こちらは事前に防ぎます。

Karpathy によるLLM コーディングの落とし穴に関する考察では、根本にある問題として、黙ったままの思い込み、複雑すぎる差分、依頼範囲外の編集、曖昧な成功基準が挙げられています。4 つのルールで、それぞれを防ぎます。

ルール	防止できる問題
表面化し、思い込まない	誤った解釈、隠れた混乱、見落とされたトレードオフ
必要最小限のコード	50 行で済むはずが 200 行になる差分、先走った抽象化
担当範囲を守る	ついでのリファクタリング、隣接するコードへの「改善」
検証可能な目標	延々と続く確認のやり直し、「とにかく動くようにする」ループ

完全なルールは rules/pre-flight-discipline.mdc（alwaysApply: true）にあります。自己修正と組み合わせて使います。事前確認で誤りを防ぎ、すり抜けた場合には自己修正で教訓を記録します。

CLAUDE.md に追加

## Pre-Flight Discipline
Before coding: state assumptions, present ambiguity, push back if simpler exists.
Every changed line traces to the request - no drive-by edits.
Convert imperatives to verifiable goals: "fix bug" → "failing test → make it pass".

---

2. worktree を使った並列セッション

待ち時間ゼロ。 Claude が考えている間に、別の作業を進めましょう。

セットアップ

Claude Code：

claude --worktree    # or claude -w (auto-creates isolated worktree)

Cursor／その他のエディター：

git worktree add ../project-feat feature-branch
git worktree add ../project-fix bugfix-branch

バックグラウンドエージェントの管理 (Claude Code)

• Ctrl+F — バックグラウンドエージェントをすべて終了します（2 回押して確認）
• Ctrl+B — タスクをバックグラウンドに送ります
• サブエージェントは、エージェントのフロントマターで isolation: worktree をサポートしています

並列化する場面

状況	アクション
テストの完了待ち	worktree で新しい機能を始めます
ビルドに時間がかかる	並行して問題をデバッグします
方法を検討する	2～3 通りを同時に試します

CLAUDE.md に追加

## Parallel Work
When blocked on long operations, use `claude -w` for instant parallel sessions.
Subagents with `isolation: worktree` get their own safe working copy.

---

3. セッション終了の習慣

意識的にセッションを終えましょう。学びを記録し、状態を確認します。

/wrap-up チェックリスト

1. 変更の監査 - 変更したファイル、未コミットの変更を一覧表示します
2. 状態の確認 - git status、テスト、リンターを実行します
3. 学びの記録 - どんな間違いがありましたか？ 何がうまくいきましたか？
4. 次のセッション - 次は何をしますか？ 進行を妨げる要因はありますか？
5. 要約 - 達成した内容を 1 段落でまとめます

コマンドの作成

~/.claude/commands/wrap-up.md：

Execute wrap-up checklist:
1. `git status` - uncommitted changes?
2. `npm test -- --changed` - tests passing?
3. What was learned this session?
4. Propose LEARNED additions
5. One-paragraph summary

---

4. メモリの分割アーキテクチャ

複雑なプロジェクトでは、Claude のメモリをモジュール化します。

構成

.claude/
├── CLAUDE.md        # Entry point
├── AGENTS.md        # Workflow rules
├── SOUL.md          # Style preferences
└── LEARNED.md       # Auto-populated

AGENTS.md

# Workflow Rules

## Planning
Plan mode when: >3 files, architecture decisions, multiple approaches.

## Quality Gates
Before complete: lint, typecheck, test --related.

## Subagents
Use for: parallel exploration, background tasks.
Avoid for: tasks needing conversation context.

SOUL.md

# Style

- Concise over verbose
- Action over explanation
- Acknowledge mistakes directly
- No features beyond scope

---

5. 80/20 レビューパターン

変更のたびにレビューするのではなく、チェックポイントでまとめてレビューします。

レビューのタイミング

1. 計画の承認後
2. 各マイルストーンの完了後
3. 破壊的な操作の前
4. /wrap-up の実行時

CLAUDE.md に追加

## Review Checkpoints
Pause for review at: plan completion, >5 file edits, git operations, auth/security code.
Between: proceed with confidence.

---

6. モデルの選択

現在のラインナップ（2026年）： Fable 5.1、Opus 5.5、Sonnet 5、Haiku 4.5です。フラッグシップモデルは1Mトークンのコンテキストを備えています。Haiku 4.5は200Kです。最先端モデルの性能差は縮まっており、出力品質はモデルの選択よりもハーネスと effort 設定に左右されます。文字列、価格、ルーティングについては、references/models-2026.md を参照してください。

タスク	モデル	労力
簡単な修正、検索	Haiku 4.5	low
機能開発、バランスの取れた作業	Sonnet 5	high
リファクタリング、アーキテクチャ、難しいデバッグ	Opus 5.5	xhigh
長期的な自律型ビルド	Fable 5.1	high / xhigh

労力と適応型思考

現在のティアでは、固定の思考予算は廃止されています。effort（low から xhigh、max まで）で深さを制御します。コーディングやエージェント型の作業では xhigh がデフォルトです。適応型思考では、固定予算を設けずに、モデルがステップごとに推論の深さを調整できます。定型作業を担うサブエージェントは Haiku の low 労力で実行し、推論の流れは高性能なティアに保ちます。

CLAUDE.md に追加

## Model Hints
Route by task: Haiku 4.5 for lookups, Sonnet 5 for features, Opus 5.5 for
architecture and hard debugging, Fable 5.1 for long-horizon builds.
Effort is the lever, not thinking budgets: xhigh for coding, low for subagents.

---

7. コンテキストの管理

コンテキストは、1M トークン（Haiku 4.5 では200K）でも有限です。適切に管理しましょう。

ルール

1. 編集する前に読みます
2. タスクの区切りでコンテキストを圧縮します
3. 使用していない MCP を無効にします（有効なものは10未満、ツールは80未満）
4. 調査内容を要約します
5. 大量の出力（テスト、ログ、ドキュメント）を分離するためにサブエージェントを使います

コンテキストの圧縮

• 容量の約95%で自動圧縮されます（長時間実行中のエージェントを維持します）
• より早い圧縮を設定します：CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50
• 圧縮前に状態を保存するには PreCompact フックを使います
• サブエージェントはメインセッションとは独立して自動圧縮されます

適切な圧縮タイミング

• 計画後、実行前
• 機能の完成後
• コンテキストが70%を超えたとき
• 作業領域を切り替える前

---

8. 学習ログ

セッションから得た知見を自動で記録します。

CLAUDE.md に追加

## Learning Log
After tasks, note learnings:
`[DATE] [TOPIC]: Key insight`

Append to .claude/learning-log.md

---

Claude Code を学ぶ

/learn を実行すると、セッション、コンテキスト、CLAUDE.md、サブエージェント、フックなどをトピックごとに解説するガイドを確認できます（commands/learn.md を参照）。公式ドキュメント：https://code.claude.com/docs/

---

クイックセットアップ

最小構成

CLAUDE.md に追加します：

## Pro Workflow

### Self-Correction
When corrected, propose rule → add to LEARNED after approval.

### Planning
Multi-file: plan first, wait for "proceed".

### Quality
After edits: lint, typecheck, test.

### LEARNED

完全なセットアップ

git clone https://github.com/rohitg00/pro-workflow.git /tmp/pw
cp -r /tmp/pw/templates/split-claude-md/* ./.claude/
cp -r /tmp/pw/commands/* ~/.claude/commands/

---

フック (Claude Code)

Pro-workflow には、パターンを徹底するための自動フックが含まれています。Cursor ユーザーは rules/ ディレクトリ内の .mdc ルールで同等の徹底を行えます。

PreToolUse フック

トリガー	アクション
Edit/Write	編集回数を記録し、5回／10回でリマインダーを表示
git commit	品質ゲートの実行を促します
git push	/wrap-up についてリマインダーを表示

PostToolUse フック

トリガー	アクション
コード編集（.ts/.js/.py/.go）	console.log、TODO、シークレットを確認
テストコマンド	失敗から [LEARN] を提案

セッションフック

フック	アクション
SessionStart	LEARNED パターンを読み込み、worktree の数を表示
Stop	last_assistant_message を使ったコンテキストに応じたリマインダー
SessionEnd	未コミットの変更を確認し、学びの記録を促します
ConfigChange	セッション中に品質ゲートやフックが変更されたことを検出

フックをインストール

# Copy hooks to your settings
cp ~/skills/pro-workflow/hooks/hooks.json ~/.claude/settings.local.json

# Or merge with existing settings

フックの方針

Twitter のスレッドから得た知見に基づいています：

• 処理を妨げない - フックはリマインダーを表示し、処理をブロックしません（危険な操作を除く）
• チェックポイント方式 - 編集のたびではなく、間隔を空けて品質ゲートを実施します
• 学習重視 - パターンの記録を常に促します

---

コンテキスト

作業内容に応じてモードを切り替えます。

コンテキスト	トリガー	動作
dev	「作ってみましょう」	まずコードを書き、素早く反復します
review	「これをレビューして」	読み取り専用、セキュリティを重視
research	「理解を手伝って」	調査し、要約し、計画します

「Switch to dev mode」と入力するか、コンテキストファイルを読み込みます。

---

エージェント

特定のタスクに集中するための専門サブエージェントです。

エージェント	目的	ツール
planner	複雑なタスクを分解します	読み取り専用
reviewer	コードレビュー、セキュリティ監査	読み取り＋テスト

委任するタイミング

次の場合は planner エージェントを使用します。

• 5 ファイルを超えるタスク
• アーキテクチャ上の判断が必要
• 要件が不明確

次の場合は reviewer エージェントを使用します。

• コミット前
• PR のレビュー
• セキュリティ上の懸念

カスタムサブエージェント (Claude Code)

プロジェクト固有のサブエージェントを .claude/agents/ に、またはユーザー全体で使うサブエージェントを ~/.claude/agents/ に作成します。

• YAML フロントマターと Markdown のシステムプロンプトで定義します
• ツール、モデル、権限モード、フック、永続メモリを制御します
• /agents を使って対話形式で作成、編集、管理します
• ドメイン知識を得るために、スキルをサブエージェントに事前読み込みします

エージェントチーム (Claude Code, Experimental)

複数の Claude Code セッションをチームとして連携させます。

• 有効化：CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
• リードセッションが調整し、チームメイトは独立して作業します
• チームメイト同士が直接メッセージを送信します（報告するだけではありません）
• 依存関係を管理できる共有タスクリスト
• 表示方法：プロセス内（Shift+Down で移動、末尾から先頭に戻ります）または分割ペイン（tmux/iTerm2）
• 委任モード（Shift+Tab）：リードは調整のみを行い、コードを編集しません
• 最適な用途：並行レビュー、競合する仮説、複数レイヤーにまたがる変更
• ドキュメント： https://code.claude.com/docs/agent-teams

---

9. オーケストレーション：Command > Agent > Skill

複雑な機能に最も効果的なパターンです。3 つのレイヤーがそれぞれ 1 つの役割を担います。

アーキテクチャ

Command (user-facing entry point)
  └── Agent (execution, constrained tools, preloaded skills)
        └── Skill (domain knowledge, injected at startup)

複数フェーズの開発（/develop）

5 ファイルを超える機能や、アーキテクチャ上の判断が必要な機能の場合：

1. 調査 → オーケストレーターエージェントがコードベースを調査し、信頼度を評価します（0～100）
2. 計画 → 変更方法、変更するファイル、リスクを提示します。承認を待ちます。
3. 実装 → 5 回の編集ごとに品質ゲートを設けながら、計画を段階的に実行します
4. レビュー → reviewer エージェントがセキュリティ、ロジック、品質を確認します

4 つのフェーズはすべて順番に実行されます。次のフェーズを開始するには、各フェーズでユーザーの明示的な承認が必要です。

エージェントスキル（事前読み込み）

# Agent frontmatter
skills: ["api-conventions", "project-patterns"]

エージェントの起動時にスキルの内容全体を注入します。エージェントが常に必要とする知識に使用します。

オンデマンドスキル（呼び出し）

user-invocable: true を持つスキルは /skill-name で呼び出します。メインコンテキストを汚さずに分離して実行するには、context: fork を使用します。

オーケストレーションするタイミング

シナリオ	パターン
5 ファイルを超える機能	オーケストレーターを使った /develop
バグ調査	debugger エージェント
簡単な調査	scout エージェント（バックグラウンド）
コードレビュー	reviewer エージェント
単純なタスク	そのまま直接実行

---

10. 日々の習慣

毎回のセッション

• 調子がおかしいと感じたら /doctor を実行します
• 自動コンパクトを待たず、50% で手動の /compact を実行します
• 最大限に推論させるため、プロンプトに ultrathink を含めます
• /rename でセッションに名前を付け、/resume で簡単に再開できるようにします
• /wrap-up で締めくくり、得られた知見を記録します

コンテキスト管理

• CLAUDE.md：ルートは 60 行未満、最大 150 行
• 先回りしてコンパクト化するには CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 を使用します
• 負荷の高い調査はサブエージェントに委任します
• MCP は 10 個未満、ツールは 80 個未満に保ちます

エージェント横断のヒント

• タブ補完には Cursor を使い、難しい問題にはターミナルの Claude Code を使います
• 同じ MCP サーバーを両方で使用できます（プロジェクトルートの .mcp.json を共有します）
• npx skills add rohitg00/pro-workflow で、どのエージェントにもスキルをインストールできます

---

MCP 設定 (Claude Code)

まずは MCP を 3 つ使います。具体的な必要性がある場合にのみ追加します。

必須：

• context7 — 最新ドキュメントの検索
• playwright — ブラウザーの自動化（最もトークン効率が高い）
• github — PR、issue、コード検索

セットアップ方法と厳選されたおすすめについては、mcp-config.example.json を参照してください。

---

コマンド (Claude Code)

コマンド	目的	Cursor での同等機能
/wrap-up	セッション終了時の儀式	wrap-up スキル
/learn-rule	修正内容を抽出して記憶に保存	learn-rule スキル
/develop	複数フェーズにわたる機能開発	orchestrate スキル
/doctor	ヘルスチェック	—
/commit	品質ゲート付きのスマートコミット	smart-commit スキル
/insights	セッションの分析とパターン	insights スキル
/replay	過去の学びを提示	replay-learnings スキル
/handoff	セッション引き継ぎドキュメント	session-handoff スキル
/search	キーワードで学びを検索	—
/list	保存済みの学びをすべて一覧表示	—
/learn	トピックごとの Claude Code ガイド	—

---

リファレンスガイド

設定や機能の詳細：

ガイド	トピック
references/settings-guide.md	すべての設定キー、権限モード、階層、サンドボックス、環境変数
references/cli-cheatsheet.md	すべての CLI フラグ、キーボードショートカット、スラッシュコマンド
references/orchestration-patterns.md	コマンド > エージェント > スキルのアーキテクチャ、フロントマターのリファレンス
references/context-loading.md	CLAUDE.md のモノレポ読み込み、エージェントのメモリ、スキルの検出
references/cross-agent-workflows.md	Claude Code と Cursor の設定対応表、バックグラウンドエージェント
references/new-features.md	音声モード、エージェントチーム、チェックポイント、新しいフックイベント
references/daily-habits.md	セッションの習慣、デバッグのヒント、ターミナルの設定、アンチパターン

---

哲学

1. 改善を積み重ねる - 小さな修正が大きな成果につながります
2. 信頼しつつ検証する - AI に作業を任せ、チェックポイントで確認します
3. 無駄な時間をなくす - 並行セッションで勢いを保ちます
4. 記憶は貴重です - あなたの記憶も、AI の記憶も大切にします
5. 細かく管理せず、オーケストレーションする - パターンをつなぎ合わせ、実行はエージェントに任せます

---

Claude Code、Cursor などでの実運用から生まれた、完全な AI コーディングワークフローシステムです。