Claude Code 基础工作流

1. 终端 Agent 和 IDE Agent 的差异#

IDE Agent 通常围绕编辑器展开，优势是定位文件、补全代码、解释当前选区。Claude Code 运行在终端里，天然接近项目根目录、命令行工具、测试脚本和 Git 工作流。

因此它更适合：

• 跨文件重构。
• 修复测试失败。
• 根据仓库规则补充文档。
• 运行构建、检查、格式化等命令。
• 处理“读代码 -> 改代码 -> 验证”的闭环任务。

它不适合完全替代你做产品判断、权限决策或高风险发布操作。凡是涉及生产数据、删除文件、批量迁移、密钥和外部系统写入，都应该明确边界并保留人工确认点。

2. 一个稳定任务要包含四类信息#

给 Claude Code 的任务最好包含：

• 目标：最后要达到什么状态。
• 范围：只改哪些模块，不改哪些内容。
• 约束：编码、测试、风格、兼容性、安全边界。
• 验收：跑什么命令，看到什么结果算完成。

示例：

1
修复登录页表单提交失败的问题。
2
只允许改 src/pages/login 和 src/lib/auth 相关文件，不重构路由。
3
先读现有测试和错误日志，再定位根因。
4
完成后运行 npm test -- login，并说明修改点。

3. 任务越长，越需要阶段性同步#

Claude Code 可以长时间执行，但长任务更容易被上下文噪声影响。比较稳的做法是把任务拆成阶段：

1
阶段 1：只定位问题，不修改文件。
2
阶段 2：给出最小修复方案。
3
阶段 3：实现并运行测试。
4
阶段 4：总结变更和剩余风险。

这样即使中途发现新问题，也能及时收口，而不是把一个局部任务扩成系统性重构。

场景#

项目在构建时失败，错误信息大致指向某个 Markdown 页面或组件引用异常。你不需要一上来就告诉它“怎么修”，而是先让它把问题缩小。

第一轮：先定位，不修改#

可以这样下任务：

1
先不要修改文件。
2
请读取构建错误日志、相关页面、相邻实现和项目规则。
3
先判断失败来自哪里，给出根因候选和最小排查路径。

这一轮的目标不是修复，而是确认问题边界。好的输出应该包含：

• 失败命中的文件或模块。
• 可能的根因。
• 需要进一步查看的文件。
• 是否能用最小改动修复。

第二轮：只做最小修改#

如果定位明确，再下第二轮：

1
根因已经确认。
2
请只修改本次构建失败直接相关的文件，不要扩大范围。
3
修复后运行构建或相关测试，并说明改动点。

这里最重要的是“最小修改”。比如：

• 只是 frontmatter 字段写错，就不要重构整篇文章。
• 只是组件导入路径不对，就不要顺手改样式。
• 只是内容链接失效，就不要改路由结构。

第三轮：验证和收口#

修复后要把结果收口成三件事：

• 改了什么。
• 验证过什么。
• 还有什么风险。

例如：

1
已修复构建失败，原因是文章引用了不存在的字段。
2
已运行 pnpm check 和 pnpm build。
3
当前剩余风险：该目录下还有其他历史内容未统一整理，后续可按同一模式继续修。

这个案例为什么典型#

这个流程能看出 Claude Code 的核心价值不在“生成一段代码”，而在于：

• 先读日志和上下文。
• 再缩小问题范围。
• 只做最小必要修改。
• 修改后必须验证。

这也正好对应 PDF 里的主线：从工具到产品构建，不是一次性输出，而是带反馈回路的工程闭环。