AI Agent / 系统课时
修改与创建文件
修改与创建文件
本课完成一次可控的代码改动:先限定目标和文件范围,再让 Claude Code 编辑或创建文件,最后通过 Git 状态、差异和基础检查确认没有越界修改。
学习目标
- 在修改前明确允许变更的文件和行为
- 审查 Claude Code 产生的新文件与差异
- 发现范围扩大或实现偏差时及时纠正
从小范围任务开始
第一次修改适合选择一个行为清楚、影响面小、容易验证的任务,例如补充参数校验、修复空值分支或增加一个独立工具函数。请求中要明确“先阅读再修改”,并指出不允许触碰的区域。
请先阅读 @src/utils/formatName.js 及其相关测试。
目标:让 formatName 在输入为空字符串或只包含空白字符时返回 "Unknown"。
范围:只修改该工具函数和对应测试。
约束:不新增依赖,不改变非空输入的现有格式。
完成后请列出修改文件,并说明每项改动如何满足验收标准。这是会话输入示例,不是 Shell 命令。项目路径和函数名必须替换为真实对象。Claude Code 可能先提出计划,也可能请求编辑权限;批准前要检查目标文件和动作是否与范围一致。
创建新文件时说明职责
“创建一个工具文件”过于模糊。新文件请求至少应说明所在目录、导出接口、调用方和测试位置。若文件应由框架命令生成,也要优先使用项目约定的生成方式,而不是手写一套近似结构。
新文件完成后,应确认它确实被调用或被构建系统纳入。仅仅出现在目录中不代表功能已生效。对于配置文件,还要说明加载位置;对于源码文件,则要检查导入、注册或路由关系。
用 Git 审查改动
Claude 完成编辑后,不要只阅读它的总结。应直接查看工作区状态和差异。下面的命令不会提交代码。
git status --short
git diff --check
git diff --stat
git diff预期结果
<CHANGED_FILES>
<NO_OUTPUT_FROM_DIFF_CHECK>
<DIFF_STAT>
<UNCOMMITTED_DIFF>git diff --check 没有输出通常表示未发现空白错误;其他内容会随实际改动变化。新建但未暂存的文件可能只出现在 git status --short,因此还要直接打开文件检查。若需要把未跟踪文件纳入差异审查,可以先确认内容,再选择性暂存,切勿为了方便执行宽泛的 git add .。
审查四类问题
第一类是范围:是否修改了请求之外的文件。第二类是行为:实现是否真的满足目标,而不是只让测试通过。第三类是兼容性:公共接口、配置格式和错误处理是否保持约束。第四类是可维护性:命名、重复逻辑和注释是否符合项目现有风格。
发现问题时,用具体反馈继续会话,例如“撤销对 package.json 的改动,只保留两个目标文件”,或“当前实现把 null 和空字符串混为一类,请保持原有 null 行为”。不要笼统地说“再优化一下”,否则改动范围可能再次扩张。
保留可回退边界
在确认差异之前不要要求提交。若工作区原本已有个人改动,应明确禁止覆盖,并在审查时区分本次任务与既有变更。复杂修改可以拆成多个小步骤,每一步都先查看差异,再进入下一步。
Claude Code 的修改总结是导航信息,Git 差异才是最终审查对象。