Claude Code 工作原理与日常开发：从读项目到交付改动
看清 Agent Loop、项目上下文与验证怎样共同支撑开发。
让编码助手一上来就修改项目，常常会得到一个看起来合理、却不符合现有工程约定的答案。Claude Code 的优势在于能读取工程、调用工具并检查结果；要用好它，首先要让它建立正确的项目上下文，再把修改限制在一个可验证的目标内。
01 / 定义：编码助手通过工具理解和改变工程
编码助手不是始终知道整个仓库的模型。它根据当前对话、项目说明和工具返回的信息形成判断，再选择读取文件、搜索、编辑或运行命令。工具结果成为下一轮判断的输入，形成“观察—行动—检查”的循环。
因此，同样一句“修一下导出”，在不同上下文中可能产生完全不同的改动。当前分支、未提交变更、测试入口和业务规则都影响结果。项目说明可以降低重复解释，但它不是代码实际行为的证明。
02 / 推导：先探索，再规划，再改动
已有工程最贵的错误，往往是误解约定：重复实现已有能力、绕过权限层、使用错误的数据模型。只读探索的目的，是把这些不确定性暴露出来，而不是让助手输出一大段项目介绍。
- 探索的产物：相关文件、调用路径、已有约定、尚未确定的问题。
- 计划的产物：准备改哪几处、每处为什么必要、用什么检查。
- 实现的产物：最小差异，而不是顺带重构整个模块。
- 交付的产物：改动摘要、运行结果和仍未验证的条件。
一个拼写错误不需要复杂计划；涉及身份、数据或多个模块的改动，先确认关键路径通常更划算。步骤应服务风险，不是固定仪式。
03 / 应用：修复项目导出范围错误
沿用工单导出案例。假设当前接口已经检查管理员角色，却没有检查项目归属。下面是你可以直接组织的一次工作流程；文件名应由助手读工程后确定，不能凭空假设项目结构。
- 保存现场。查看当前分支和工作区差异，确认哪些修改是你已有的；需要隔离时建立工作分支。不要为了“清洁环境”删除未提交内容。
- 只读定位。要求助手追踪导出请求从路由到查询的调用链，列出角色判断与项目判断各在哪里，引用函数和条件。
- 建立失败样例。用 P-02 的管理员请求 P-01，预期拒绝。先在隔离测试数据上观察旧实现是否错误返回数据。
- 批准最小修复方向。在服务端已有授权层补项目检查，查询也限定允许范围。不另造一套前端身份判断。
- 运行相关检查。越权请求必须失败，本项目正常请求必须成功，空结果和原有导出格式仍然成立。
- 审查差异。确认没有把测试绕过、硬编码用户或扩大权限当成修复；再阅读错误文案和日志是否泄露信息。
先只读分析当前工程的导出功能。
目标：识别“管理员角色通过，但项目不属于该用户”的访问路径。
返回相关入口、函数、权限条件、已有测试和最小反例。
不要修改代码，不要运行生产数据操作。
完成定位后，提出最小修复与验证计划。
实现时保留已有改动；交付实际运行的命令、结果与未验证项。不要只让助手“补一项测试”。应先确定这个测试是否真的能在旧实现上失败，再确认修复后通过，否则测试可能只是在重复实现的假设。
04 / 验收：读懂助手的完成报告
可靠报告应说明改了什么、为什么、如何验证，以及哪些条件没有测试。看到命令退出码为零，还要确认命令确实运行了目标测试，未因筛选错误执行零项，也没有把失败吞掉。
| 报告用语 | 你应追问的证据 |
|---|---|
| “已检查权限” | 具体条件、入口与越权反例 |
| “所有测试通过” | 测试命令、数量、范围与结果 |
| “不影响其他功能” | 受影响路径及其回归证据 |
| “问题已解决” | 旧行为如何复现，新行为如何验证 |
当测试依赖不可用时，助手可以继续做静态检查和局部验证，但应把缺口留下。安装大量依赖、改测试框架或替换技术栈，不应成为绕过一个失败检查的默认方法。
05 / 迁移：把项目知识留在项目里
把稳定约定写入项目说明：运行入口、目录职责、测试命令、生成文件边界和危险操作。当前任务的现场状态则放进任务记录，避免过时的临时细节长期污染项目规则。
练习：新会话忘了上次进展，是让它重读全部聊天吗？
先给目标、已完成变更、有效证据、剩余问题和关键文件入口，再让它读取当前源码确认。聊天可能包含放弃的方案；当前文件与最新验证更适合恢复工作。
长任务如何恢复、哪些动作适合自动化，见持续可靠的 AI 开发；需要独立调查时再考虑Subagent，不要把增加助手数量当成提高正确性的保证。