workflow-mastery

.NET 工作流精通

核心原则

1. 并行优于串行 — 使用 git worktrees 同时运行 3-5 个 Claude 会话。在一个会话中开发功能，在另一个会话中修复 Bug，在第三个会话中运行测试。这是提升效率最显著的方法。
2. 先规划，再执行 — 对于任何非简单任务，先进入规划模式，反复迭代，直到计划无懈可击，再切换到自动接受模式。好的计划能让 Claude 一次性完成实现。
3. 验证闭环 — 为 Claude 提供证明工作成果的方式：dotnet build、dotnet test、通过 MCP 使用 get_diagnostics。仅这一项实践就能让输出质量提升 2-3 倍。
4. 上下文是预算，不是堆放场 — 上下文窗口很快就会填满：典型的 .cs 文件包含 500-2000 个 token，读取 50 个文件就可能消耗大量预算。像规划冲刺容量一样，有意识地分配 token。
5. 自动化重复工作 — 如果某件事你每天做不止一次，就把它做成钩子、斜杠命令或子 Agent。预先允许安全权限，消除摩擦。
6. 让知识持续积累 — 每次纠正都要在 MEMORY.md 中变成一条规则（参见 instinct-system 技能）。每次 PR 审查都会带来新的经验。随着项目知识库不断增长，Claude 的出错率也会逐渐降低。

模式

使用 Git Worktrees 并行运行会话

这是效率提升的最大助力。每个 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 测试	自主修复 Bug
tests	为现有功能编写集成测试	生成测试
analysis	查询 Roslyn MCP、读取日志、审查架构	只读研究

提示：

• 按任务为终端标签页命名，这样就不会弄混
• 使用 Shell 别名（alias zf='cd ../my-project-feature'），一键切换
• 启用终端通知，以便在会话需要输入时收到提示

.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

**进阶模式：**让一个 Claude 编写计划，再启动第二个 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 验证闭环

有关完整的 7 阶段验证流程（构建、诊断、反模式、测试、安全、格式、差异审查）及结构化 PASS/FAIL 报告，请参阅 verify 技能。

Boris 的首要建议：“为 Claude 提供验证其工作成果的方式。”简而言之：在宣布完成之前，始终让 Claude 运行 dotnet build、dotnet test、get_diagnostics 和 dotnet format --verify-no-changes。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 的子 Agent 模式

工具包附带 10 个专业 Agent——在自己编写之前，先将任务交给它们： dotnet-architect、code-reviewer、refactor-cleaner、test-engineer、 security-auditor、build-error-resolver、ef-core-specialist、 api-designer、performance-analyst、devops-engineer。每个 Agent 都预先加载了通用 Agent 会话所缺少的技能和领域背景。

使用方法：

"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/ 中创建项目专属的子 Agent——使用 Markdown 文件编写角色说明、带编号的任务列表，以及必需的报告格式（PASS 并附摘要／FAIL 并列出具体问题）。每个 Agent 只负责一个关注点，以便审查其输出。

**何时交给子 Agent，何时留在主上下文：**请参阅下文的上下文管理——子 Agent 也是隔离上下文的空间，而不只是任务执行器。

上下文管理

.claude/rules/agents.md 中的规则已要求优先使用 MCP 导航（读取文件前先用 find_symbol，优先使用 get_diagnostics 而不是构建）。本节在此基础上介绍策略层：如何规划预算、何时交给子 Agent，以及如何恢复。

Token 成本

一次 Roslyn MCP 查询需要 30–150 个 token；读取文件需要 500–2000 多个。要了解 OrderService，调用 4 次 MCP（find_symbol → get_public_api → find_references → get_type_hierarchy）约需 310 个 token；读取相关的 4 个文件则约需 2900 个。然后只读取你要修改的方法。完整读取文件仅限于即将编辑的文件。

子 Agent 分派决策矩阵

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

请子 Agent 提供精简答案：“追踪从登录到令牌验证的身份验证流程。以带文件名:行号引用的编号步骤返回结果。”这样你获得的是约 300 个 token 的发现结果，而不是 15k 个 token 的原始文件内容。

文件读取优先级

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 + 子 Agent），规划约 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

按需加载技能

不要“以防万一”提前加载所有技能——15 项技能每项约 300 个 token，开始工作前就会花掉约 4500 个 token。如果相关，可在会话开始时加载 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 个或更多文件	先使用计划模式
任务是简单的 Bug 修复	直接修复，并用 dotnet test 验证
需要构建、测试和审查	使用 3 个并行工作树
CI 持续因格式问题失败	添加 PostToolUse 格式钩子
厌倦了权限提示	预先允许 dotnet * 命令
Claude 犯了错误	“更新 CLAUDE.md，避免再次犯同样的错误”
代码看起来很粗糙	“考虑到你现在掌握的所有信息，实现优雅的解决方案”
想验证架构	启动第二个会话，作为资深审查员
重复的 PR 工作流	将任务交给工具包 Agent（code-reviewer、refactor-cleaner），或创建项目子 Agent
学习新的代码库	通过 /config 使用“Explanatory”输出风格
需要了解类型的 API 或位置	使用 get_public_api / find_symbol——不要读取文件
需要修改文件	完整读取文件——需要精确内容
探索不熟悉的代码	启动子 Agent，保持主上下文干净
单次会话中读取了 10 个以上文件	暂停，改用 MCP + 子 Agent
感觉上下文变得沉重或迟缓	总结已掌握的信息，之后改用子 Agent
大型代码库（50 个以上项目）	优先使用 MCP、大量使用子 Agent，只读取要修改的文件
会话中途出现新主题	按需加载相关技能，不要提前加载