workflow-mastery

.NET でワークフローを極める

基本原則

1. 逐次処理ではなく並列処理 — git worktree を使って、Claude のセッションを 3～5 個同時に実行します。1 つで機能を開発し、別のセッションでバグを修正し、3 つ目でテストを実行します。生産性を最も大きく高める方法です。
2. 計画してから実行する — 重要なタスクでは、まずプランモードで開始し、計画に抜けがなくなるまで反復してから、自動承認に切り替えます。良い計画があれば、Claude は一度で実装を完了できます。
3. 検証でループを閉じる — Claude が作業を証明できる手段を用意します。dotnet build、dotnet test、MCP 経由の get_diagnostics などです。この習慣だけで、出力の品質が 2～3 倍になります。
4. コンテキストは予算であり、何でも放り込む場所ではありません — コンテキストウィンドウはすぐに埋まります。一般的な .cs ファイルは 500～2000 トークンで、ファイルを 50 個読み込むと予算の大部分を消費することがあります。スプリントのキャパシティと同じように、トークンを計画的に使いましょう。
5. 繰り返し作業を自動化する — 1 日に 2 回以上行う作業は、フック、スラッシュコマンド、またはサブエージェントにします。安全な権限は事前に許可し、手間をなくしましょう。
6. 知識を積み重ねる — 修正のたびに、その内容を MEMORY.md のルールにします（instinct-system スキルを参照）。PR レビューのたびに学びを追加します。プロジェクトのナレッジベースが成長するにつれて、Claude のミスは次第に減っていきます。

パターン

Git Worktree を使った並列セッション

生産性を最も大きく高める方法です。各 worktree は、それぞれ専用の Claude セッションとファイルを持ち、競合は発生しません。

# Create worktrees for parallel work
git worktree add ../my-project-feature origin/main
git worktree add ../my-project-bugfix origin/main
git worktree add ../my-project-tests origin/main

# Start Claude in each (separate terminal tabs)
cd ../my-project-feature && claude
cd ../my-project-bugfix && claude
cd ../my-project-tests && claude

実用的な .NET ワークフロー：

Worktree	タスク	Claude セッション
feature	新しいエンドポイントとハンドラーを開発する	メイン開発
bugfix	失敗している CI テストを修正する	自律的なバグ修正
tests	既存機能の統合テストを作成する	テスト生成
analysis	Roslyn MCP に問い合わせ、ログを読み、アーキテクチャをレビューする	読み取り専用の調査

ヒント：

• タスク名をターミナルのタブに付けて、どのセッションかすぐに分かるようにします
• シェルのエイリアス（alias zf='cd ../my-project-feature'）を使って、1 回のキー操作で切り替えます
• セッションが入力を必要としたときに分かるよう、ターミナルの通知を有効にします

.NET 用の自動フォーマットフック

ファイルを書き込むたびにフォーマットの問題を検出し、「フォーマットが原因で CI が失敗する」という繰り返しをなくします。

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "dotnet format --include \"$CLAUDE_FILE_PATH\" --no-restore 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

|| true を使う理由：フックによって Claude のワークフローが止まらないようにします。フォーマットに失敗した場合（C# 以外のファイルなど）も、エラーを表に出さずに続行します。

.NET の安全な権限を事前に許可する

すべての dotnet コマンドで「許可」をクリックする必要がなくなります。これらを .claude/settings.json に追加します。

{
  "permissions": {
    "allow": [
      "Bash(dotnet build *)",
      "Bash(dotnet test *)",
      "Bash(dotnet run *)",
      "Bash(dotnet ef *)",
      "Bash(dotnet format *)",
      "Bash(dotnet restore *)",
      "Bash(dotnet pack *)",
      "Bash(dotnet tool *)"
    ]
  }
}

チーム全体がスムーズに作業できるよう、この設定を git にチェックインします。

プランモードの戦略

3 個以上のファイルに関わるタスクや、アーキテクチャ上の判断が必要なタスクでは、次のようにします。

Step 1: Enter plan mode (Shift+Tab twice)
Step 2: Describe the task with full context
Step 3: Iterate on the plan — challenge assumptions, ask "what about edge cases?"
Step 4: Once the plan is solid, switch to normal mode
Step 5: Claude executes with auto-accept — often 1-shots the implementation

高度なパターン： 1 つ目の Claude に計画を作成させたあと、2 つ目の Claude セッションを立ち上げ、スタッフエンジニアの視点でレビューさせます。

"Review this plan as a staff .NET engineer. Challenge every assumption.
What could go wrong? What's missing? What would you do differently?"

うまくいかないとき： 実装が計画から外れたら、すぐに停止します。そのまま進めてはいけません。プランモードに戻り、何が変わったのかを把握して計画を立て直してから、作業を再開します。

.NET の検証ループ

構造化された PASS／FAIL レポートを含む、7 フェーズの検証パイプライン（ビルド、診断、アンチパターン、テスト、セキュリティ、フォーマット、差分レビュー）については、verify スキルを参照してください。

Boris の一番のヒントは、「Claude が作業を検証できる手段を用意すること」です。要点は、完了とする前に必ず dotnet build、dotnet test、get_diagnostics、dotnet format --verify-no-changes を実行するよう Claude に指示することです。verify スキルでは、短絡実行のルールとレポートのテンプレートを含む完全なパイプラインを確認できます。

修正を通じて知識を積み重ねる

修正を捉えるシステム全体（検出、一般化、分類して保存、定期的な監査）については、instinct-system スキルを参照してください。要点は、修正のたびに一般化したルールを MEMORY.md に記録し、同じミスが二度と起きないようにすることです。

.NET のプロンプトテクニック

Claude の作業に異議を唱える：

"Grill me on these changes. Would this pass a staff .NET engineer's code review?
Check for: N+1 queries, missing CancellationToken, exposed domain entities,
missing validation, incorrect service lifetimes."

証拠を求める：

"Prove this works. Run the tests, show me the output.
Then diff the API response between main and this branch."

修正が今ひとつだった場合：

"Knowing everything you know now, scrap this and implement the elegant solution.
No hacks, no workarounds."

EF Core のマイグレーションの場合：

"Generate the migration, then show me the raw SQL it produces.
I want to verify the migration before applying it."

.NET のサブエージェントパターン

このキットには、専門分野を持つ 10 個のエージェントが含まれています。独自のエージェントを作成する前に、まずこれらを使ってください。 dotnet-architect、code-reviewer、refactor-cleaner、test-engineer、 security-auditor、build-error-resolver、ef-core-specialist、 api-designer、performance-analyst、devops-engineer。それぞれに、汎用エージェントのセッションにはないスキルとドメインのコンテキストがあらかじめ読み込まれています。

使い方：

"Run the code-reviewer agent on my changes before I create the PR."
"Have refactor-cleaner simplify the files I just modified."
"Send the failing CI log to build-error-resolver."

キットが対応していないワークフローについては、.claude/agents/ にプロジェクト固有のサブエージェントを作成します。役割、番号付きのタスクリスト、必須のレポート形式（要約付きの PASS／詳細付きの FAIL）を記載した Markdown ファイルを用意してください。出力をレビューしやすく保つため、エージェントごとに担当する関心事を 1 つに絞ってください。

メインコンテキストに任せるか、サブエージェントに委任するか： 以下の「コンテキスト管理」を参照してください。サブエージェントは単なるタスク実行者ではなく、コンテキストを隔離するための部屋でもあります。

コンテキスト管理

.claude/rules/agents.md のルールでは、すでに MCP を最優先にしたコードの探索（ファイルを読む前に find_symbol、ビルドより get_diagnostics）を義務付けています。このセクションでは、その上位にある戦略、つまり予算の立て方、委任するタイミング、復旧方法について説明します。

トークンのコスト

Roslyn MCP クエリのコストは 30～150 トークンですが、ファイルの読み取りには 500～2000 以上かかります。OrderService を理解するために MCP を 4 回呼び出す（find_symbol → get_public_api → find_references → get_type_hierarchy）と、約 310 トークンです。関連する 4 つのファイルを読む場合は約 2900 トークンかかります。その後、変更するメソッドだけを読みます。ファイル全体を読むのは、編集するファイルに限ってください。

サブエージェントへの委任判断マトリックス

OFFLOAD TO A SUBAGENT WHEN:
- Exploring unfamiliar code (> 3 files to read)
- Research requiring docs or multiple files
- Verbose output (test runs, diagnostics, comparisons)
- Any task where the journey is verbose but the answer is concise

STAY IN MAIN CONTEXT WHEN:
- Modifying a file you've already read
- Quick lookups (1-2 MCP queries)
- Work that builds on the ongoing conversation with the user

サブエージェントには、回答を簡潔にするよう依頼してください。「ログインからトークン検証までの認証フローを追跡してください。ファイル名と行番号の参照を付けて、番号付きの手順で返してください。」生のファイルを 15k トークン分受け取る代わりに、約 300 トークンの調査結果を得られます。

ファイル読み取りの優先順位付け

PRIORITY 1 — Files you will modify: read fully (exact content needed for edits)
PRIORITY 2 — Contracts you must satisfy: read the interface, skip implementations
PRIORITY 3 — Reference patterns: get_public_api first, read only if insufficient
PRIORITY 4 — General context: subagent summarizes; never read in main context

NEVER READ: entire directories (get_project_graph), test files for context
(get_test_coverage_map), generated files/migrations, configs unless needed

予算の計画と復旧

複雑なタスクに取りかかる前に、トークンの使用量を見積もります。把握に約 5k（MCP とサブエージェント）、計画に約 2k、実装に約 15k（対象の読み取り、記述、反復）、検証に約 3k を使い、会話のためにコンテキストウィンドウの大部分を残します。

WARNING SIGNS: 10+ files read, 50+ exchanges, forgetting earlier details,
re-reading files you already saw

RECOVERY: summarize what you know in 5-10 lines → subagents for remaining
exploration → MCP-only lookups → suggest a fresh session if still degraded

LARGE CODEBASES (50+ projects): get_project_graph → narrow to 2-3 relevant
projects → find_symbol for key types → get_public_api for interfaces →
read ONLY files you'll modify → subagents for cross-cutting concerns

スキルの遅延読み込み

「念のため」とスキルを最初にすべて読み込まないでください。各約 300 トークンのスキルを 15 個読み込むと、作業開始前に約 4500 トークンを消費します。関連する場合はセッション開始時に modern-csharp を読み込み、ef-core、testing などは話題に上がった時点で読み込んでください。

アンチパターン

複雑なタスクで計画モードを省略しない

// BAD — dive straight into a multi-file refactor
"Refactor the Orders module to use DDD with aggregates and value objects"
*Claude modifies 15 files, misses half the invariants, tangles the migration*

// GOOD — plan first, execute after
"Enter plan mode. I want to refactor the Orders module to use DDD.
Let's plan which files change, what the aggregate boundary is,
how value objects map to EF Core, and what the migration strategy is."

並列化できる場合に、単一のセッションで作業しない

// BAD — sequential work in one session
1. Build feature       (20 min)
2. Write tests         (15 min)
3. Fix formatting      (5 min)
4. Update docs         (10 min)
Total: 50 minutes

// GOOD — parallel worktrees
Worktree 1: Build feature     (20 min)
Worktree 2: Write tests       (15 min, started simultaneously)
Worktree 3: Update docs       (10 min, started simultaneously)
Total: ~20 minutes (wall clock)

最初の解決策をそのまま受け入れない

// BAD — accept mediocre code
Claude: "Here's the implementation" *generic, works but not great*
You: "Looks good, ship it"

// GOOD — push for quality
Claude: "Here's the implementation"
You: "Would a staff .NET engineer approve this?
      What about the service lifetime? Is this N+1 safe?
      Is there a more elegant way using C# 14 features?"

コンテキストウィンドウが大きいからといって、すべてを読み込まない

// BAD — "the context window is huge, let's load everything"
Read all 30 files in the Orders module, all 15 test files,
docker-compose.yml, every migration
*80k tokens consumed before writing a single line of code*

// GOOD — minimum viable context
MCP: get_project_graph (solution shape) + find_symbol (locate targets)
Read: the 2-3 files you'll actually modify
Subagent: summarize anything else
*~3k tokens consumed, the rest free for actual work*

判断ガイド

シナリオ	推奨事項
タスクが 3 つ以上のファイルに関係する	まず計画モードを使う
タスクが単純なバグ修正である	修正して、dotnet test で検証する
ビルド、テスト、レビューが必要	3 つの並列ワークツリーを使う
CI でフォーマットの失敗が続く	PostToolUse フォーマットフックを追加する
権限確認のプロンプトが煩わしい	dotnet * コマンドを事前に許可する
Claude が間違えた	「同じ間違いを繰り返さないよう、CLAUDE.md を更新してください」と指示する
コードがその場しのぎに感じられる	「ここまでに得た知識をすべて踏まえて、洗練された解決策を実装してください」と指示する
アーキテクチャを検証したい	2 つ目のセッションをスタッフレビュー担当として起動する
PR の作業が繰り返し発生する	キットのエージェント（code-reviewer、refactor-cleaner）に依頼するか、プロジェクトのサブエージェントを作成する
新しいコードベースを学びたい	/config で「説明的」な出力スタイルを使う
型の API や場所を知りたい	ファイルを読まずに get_public_api／find_symbol を使う
ファイルを変更する必要がある	正確な内容が必要なため、ファイル全体を読む
不慣れなコードを調べる	サブエージェントを起動して、メインコンテキストをクリーンに保つ
セッション中に 10 個以上のファイルを読んだ	いったん停止して、MCP とサブエージェントに切り替える
コンテキストが重く、反応が遅い	現在の知識を要約し、以降はサブエージェントを使う
大規模なコードベース（プロジェクト 50 個以上）	MCP を最優先し、サブエージェントを多用して、変更するファイルだけを読む
セッション中に新しい話題が出た	事前ではなく、必要になった時点で該当するスキルを読み込む