我最早意识到“多文件重构必须交给 AI 但要管住它”这件事，是因为一次真实翻车：让 Sonnet 5.5 在一个中等规模的代码库里帮我做跨模块的接口调整，它确实把主流程改了，但把所有调用方的错误处理逻辑都改了，顺手还重构了两个无关文件，最后单测挂了 40 个，我回滚用掉的时间比自己手动改还久。后来我把这套多文件重构的约束思路沉淀成一个 CLAUDE.md，放到项目根目录，再跑同样的重构任务，行为完全变了个样：它会先列影响面、再按我排的顺序动文件、每步做增量编译验证，整个过程几乎不需要我盯。

这篇文章就把这套“用 CLAUDE.md 约束 Sonnet 5.5 多文件重构行为”的提示词工程实践经验完整拆开讲。内容包括：为什么多文件重构容易失控、CLAUDE.md 的加载机制和设计原则、一份可直接抄作业的约束模板及逐段解析、从普通重构到受约束重构的对比实操，以及我踩过的坑和排查方法。适合正在用 AI 编程助手做中大型重构、已经被 AI 改乱过代码、想从“碰运气式提需求”升级为“可预期流程管理”的开发者。

1. 多文件重构为什么会失控：先看清问题本质

1.1 上下文碎片化：AI 看不到全局拓扑

多文件重构和单文件改 bug 最本质的区别，在于变更影响的不是一个局部函数，而是一张调用关系网。我们人做重构时，脑子里装的是整个模块的依赖图谱：这个类被谁引用、这个接口在哪些地方被实现、改完返回值之后哪些分支需要跟着调整。但模型在生成时，能精确看到的只是当前对话窗口里贴进去的代码片段，加上少量项目文件内容。

Sonnet 5.5 的上下文窗口虽然很大，但“窗口大”和“全局理解”是两码事。你在一个多文件重构任务里贴了十几个文件，模型需要在几千行代码里自己找出“谁依赖谁”，这个工作量本身就容易出偏差。更麻烦的是，一旦生成过程中文件被分批读取，模型对早期文件的记忆会逐渐被新内容挤占，到了改第五个文件的时候，它可能已经忘了第一个文件里那个函数签名长什么样。

这就像一个临时工被派去装修一栋楼，他只拿到当前房间的图纸，不知道隔壁墙里埋着水管。局部看着改得没问题，整栋楼一通水马上爆管。多文件重构的大多数“改崩了”，不是模型的单点能力不行，而是它缺乏全局视角下的决策依据，只能靠猜。

1.2 局部最优陷阱：模型天然倾向最小改动

注意观察你会发现，模型在修改代码时有一个非常强的默认倾向：能不动就不动，动了就尽量少动。这个倾向来自训练数据的分布——大多数编程问答场景里，用户在问“怎么修这个 bug”，期望的是一个局部补丁，而不是系统性重构。

但在多文件重构场景里，这种倾向是致命的。比如你要把一个函数的参数从单个配置对象改成多个具名参数，正确的做法是：改函数定义、改所有调用方、改所有 mock、改所有测试夹具。模型却很可能只改函数定义和直接调用方，忽略类型定义、接口文档字符串、序列化层、以及间接调用的封装函数。它认为改动已经完成了，因为当前文件里的错误消失了。

这种“局部最优”行为在单次会话里很难被发现，因为模型每改一步都觉得自己是对的。只有当你编译全部代码、跑完整测试套件，才会看到那些它没碰过的文件跳出来报错。靠对话里的临时提醒“你漏了 xx 文件”能解决某一次问题，但解决不了行为模式问题——下次重构它还是会这么做。

1.3 指令遗忘：对话越长约束力越弱

还有一个经常被忽视的因素：指令的时效性衰减。就算你在对话开头明确说了“只允许修改 core/ 和 agent/ 目录，不要动 ui/ 和 tests/”，随着对话轮次增加，模型对这条早期指令的遵循度也会肉眼可见地下降。

原因在于注意力机制对距离的敏感度。早期指令会被后续大量的文件内容、编译报错、模型自己的分析结论逐渐淹没。到了重构中后期，模型的注意力集中在当前报错和当前文件上，开头约束的权重已经很低了。这时候它就很容易出现“越界操作”——比如顺手格式化了你没让它碰的文件，或者在 tests/ 里加了删了辅助函数。

这也解释了为什么很多人觉得“AI 重构改着改着就失控了”：不是 AI 变笨了，而是约束指令在长对话里被稀释了。你需要的不是更强的临时指令，而是一个始终在场、不会被对话内容覆盖的常驻约束源。

1.4 为什么 CLAUDE.md 是高优先级解法

CLAUDE.md 恰好解决以上三个问题。它不是对话里的临时指令，而是作为系统级上下文的一部分被持续加载，几乎等同于给每个请求都预置了一份“行为准则”。

从工程角度看，CLAUDE.md 的作用相当于给 AI 助手发了一个“岗位说明书”。你不需要每次对话都重申一遍“你是一个负责多文件重构的工程师，你需要注意影响面”，因为它会被自动加载；你也不需要担心对话变长之后约束被遗忘，因为它每轮请求都会重新注入。这意味着约束和对话内容是解耦的，对话内容的增长不会稀释它的权重。

不过要说明的是，CLAUDE.md 不是魔法，写不好就是一份废纸。我见过不少项目的 CLAUDE.md 写成了“自我介绍”或者“技术栈清单”，一点约束力都没有。要让它在多文件重构场景下真正约束模型行为，你必须把它设计成一套可执行的工作流规范，而不是一个说明文档。这个设计思路，我会在第 3 节详细展开。

2. CLAUDE.md 的加载机制与设计原则：它不是普通 README

2.1 持续加载的威力：为什么比对话内指令强

很多开发者以为 CLAUDE.md 跟 README.md 差不多，只是给 AI 看的项目说明，这种理解会浪费它最大的价值——它在每次请求中都会被作为系统级上下文自动加载，优先级远超普通对话内容。

用生活化的方式理解：对话里的指令像你在电话里跟外包师傅交代的注意事项，说完他可能转头就忘了；而 CLAUDE.md 像贴在施工现场的施工铭牌，任何作业人员进场第一眼就会看到，并且全程都挂在墙上，随时可以回来查阅。电话里说十遍，不如墙上贴一张规范来得有效。

在重构场景中，这个差别尤其明显。一次跨文件重构往往要持续很多轮对话，如果你的约束只在第一轮说了，后面每轮都在衰减；但放在 CLAUDE.md 里，每一轮模型都能看到完整的约束条款，衰减几乎为零。实测下来，加了 CLAUDE.md 之后，模型对“只允许改哪些目录”这类硬约束的违反率能下降一个数量级。

2.2 全局、项目、目录三层作用域与优先级

CLAUDE.md 不是只能放一个。它支持多层作用域，从用户级别的全局配置，到项目根目录，再到特定子目录。三层叠加时，更具体的优先于更宽泛的。

我在实际项目中常用的划分方式：

多文件重构主要靠项目层文件，但我会建议在核心模块目录也放一个精简版，说明这个模块的对外契约是什么、哪些接口属于稳定边界。这样模型在深入某个子目录时，能看到该目录专属的约束。

这里有一个很容易踩的坑：三层规则之间必须互斥。比如全局层说“不要改动测试文件”，项目层又说“重构时必须同步更新测试”，模型就不知道该听谁的，行为会变得不可预测。我的做法是设计规则时先列一份“绝对禁令”，再列一份“允许操作”，确保两层之间没有语义冲突。

2.3 设计原则：让约束可执行而不是可阅读

写 CLAUDE.md 最常见的误区，是把它写成散文。什么“本项目的核心设计理念是模块化、可扩展、易维护……”这种话，模型读到之后能理解但不知道具体要做什么，等于没写。

合格的 CLAUDE.md 约束应该是可直接执行的指令，最好满足以下特征：

• 动词开头，宾语明确：比如“禁止修改src/shared/下的文件”，而不是“注意保持共享模块稳定”。
• 边界清晰，可判断对错：模型每做一个动作，都应该能对照规则判断这个动作是否被允许。
• 顺序明确，流程化：多文件重构不是一次性动作，要给它排顺序。先做什么、再做什么、什么情况下可以停下来问，这些都要写成工作流。
• 有检查清单：最后给一个“提交前必须检查”的列表，让模型在完成时自检。

换句话说，CLAUDE.md 的行为约束设计思路，跟给初级工程师写带教手册是一样的。你不能只说“做事要认真负责”，你得告诉他“开发完成后必须跑一遍全量测试、确认零失败才能提交”。越是具体、可判断、可执行，模型遵守得越好。

3. 针对多文件重构场景的约束模板设计与逐行解析

3.1 一份可直接使用的 CLAUDE.md 模板

下面这份模板是我在多次实战中迭代出来的，适用范围是“在一个既有代码库里做跨模块重构”。你可以直接复制，再按项目情况调整目录名和命令。我会在 3.2 和 3.3 逐段解释每部分为什么这么写。

# 项目多文件重构约束规范 ## 角色定位 你是一个谨慎的代码重构工程师。你的工作内容是在现有代码库中进行多文件重构，目标是保持功能不变的前提下改善代码结构。你必须有全局意识：任何一处修改都可能会影响其他文件，改之前先确认影响面。 ## 全局硬性约束 1. 只允许修改 `src/core/`、`src/agent/` 目录下的文件。 2. 禁止修改 `src/ui/`、`tests/`、`docs/`、配置文件、锁文件。 3. 除非用户明确要求，禁止新建文件。新建文件前必须先说明原因并得到确认。 4. 禁止修改与本次任务无关的代码。不要顺手修 bug、优化格式、重构其他模块。 5. 禁止删除公共导出接口。如果必须改名或改签名，需要同步修改所有引用点，并在总结中列出全部改动过的引用文件。 ## 重构工作流程 在执行任何修改之前，必须按以下顺序进行： 1. 分析影响面：找出本次重构涉及的核心文件、直接调用方、间接调用方、测试引用。用一个列表列出全部涉及文件。 2. 给出执行计划：按依赖顺序排列修改步骤，明确每个步骤要改哪些文件、改动目标是什么。等待用户确认后再动手。 3. 逐文件修改：一次只处理一个文件，修改完成后用编译或静态检查验证该文件的正确性，然后继续下一个文件。 4. 修改调用方：核心文件改完必须先处理所有调用方。使用编译检查找出所有报错位置，逐一定位修复。 5. 同步测试：如果重构改变了外部行为或接口签名，按用户配置的测试命令更新受影响的测试。若测试文件在禁止修改范围内，需要提示用户并等待指示。 6. 全量验证：所有文件修改完成后，执行用户指定的完整验证命令，确认编译、静态检查、测试全部通过。 ## 重构完成标准 只有在以下条件全部满足时，才能向用户报告重构完成： - 所有允许目录下的文件修改完毕，并且没有越界修改其他文件。 - 编译或静态检查通过，没有未解决的报错。 - 测试全部通过，或者测试的失败与本次重构无关且有明确证据。 - 调用方列表中的所有文件都已同步更新，没有遗漏。 - 变更内容的所有引用点均被修正或显式列出。 ## 输出格式要求 1. 修改前先输出影响面清单，格式为：`影响文件 | 影响方式 | 处理动作`。 2. 每完成一个文件，用一句话说明改了什么、验证结果如何。 3. 全部完成后，输出一份变更摘要，包含：本次改动涉及全部文件列表、每个文件的修改要点、未处理或需要用户注意的事项。 4. 在任何不确定的情况下，停下来提问，不要凭猜继续改。 ## 反模式清单 以下是明确禁止的行为： - 未经确认同时修改多个文件后再统一验证，除非用户明确要求。 - 用“顺手”的理由修改无关代码。 - 在测试失败时通过删除或注释测试用例来让检查通过。 - 修改锁文件、构建脚本或依赖配置。 - 在未列出影响面的情况下直接开始改代码。

3.2 逐段解析：每条规则背后的行为约束逻辑

先看“角色定位”这段。我把它放在最前面，是因为它给整个文件定了一个基调。模型在生成时倾向于模仿角色描述的行为方式，写“谨慎的代码重构工程师”，强调“必须有全局意识”，等于在做任何操作前先被注入了一个行为原型。后续所有具体规则都是对这个人设的操作化展开。实测中，加了这一段的遵守率比直接上来列规则要高不少，因为角色描述会影响模型整体的决策风格。

“全局硬性约束”里，最有价值的是第 3 条和第 4 条。第 3 条“禁止新建文件”专门用来对抗一个典型失控场景：模型觉得新增一个辅助模块更优雅，于是开始擅自扩展项目结构。这对人来说不算大问题，但对一次受控重构是灾难——你的代码评审范围被无限扩大。第 4 条“禁止修改无关代码”则是对抗“顺手优化”行为。模型在改代码过程中经常发现相邻代码有问题就会顺手改了，这会让 diff 里混入大量无关变更，增加评审成本，也容易引入隐藏回归。这两条直接堵住了多文件重构最常见的失控源头。

第 5 条关于公共接口的约束，处理的是重构中最危险的操作——签名变更。模型如果删了一个导出接口，编译器会在某些调用方报错，但如果项目有动态调用、反射、或者字符串拼接调用，编译器可能根本查不出来。所以条款里要求“在总结中列出全部改动过的引用文件”，强制模型对影响面做显式交代。这不是靠模型自觉，而是靠“必须输出”来倒逼它检查。

“重构工作流程”这一段，是整个模板的核心。它的本质是把一次模糊的大任务拆成一连串可验证的小步骤，这符合模型擅长处理结构化任务的特点。一旦你让模型先列影响面再动手，它被迫在修改前建立全局图景，而不是边改边看；一旦你要求它“一次只处理一个文件并验证”，它就不会出现改完一堆文件后统一编译发现爆炸性错误的情况。

选择“先列影响面等待确认”而不是“直接开干”，还有一个工程上的考量：让用户在每个关键节点介入。AI 重构最大的风险就是失控后难以及时发现，影响面清单给了你一个检查点。如果模型列出的影响文件跟你的预期差太多，你有机会在改动发生之前纠正它，这比改完再回滚成本低太多了。

3.3 完成标准与输出格式：把“符合预期”变成可判断的事实

模板里“重构完成标准”这一段，我要特别强调一下它的作用。很多开发者要求 AI“把重构做好”，但“做好”不是一个模型能自行判断的模糊概念。你必须给它一组客观可验证的条件，它才能准确地判断自己是否完成了任务。

这组条件里的每一条都有对应意义：“所有允许目录下的文件修改完毕，且没有越界修改”对应硬性约束的遵守；“编译或静态检查通过”是机械验证；“测试全部通过”是行为验证；“调用方列表中的所有文件都已同步更新”是完整性验证；“变更引用点修正或列出”是透明性要求。有了这五条，模型做完重构之后会用这些条件逐项自检，能有效减少“以为做完了但实际上没做完”的情况。

输出格式要求看起来像形式主义，实际上也是约束的一部分。要求“修改前先输出影响面清单”，是为了阻止模型直接进入修改模式；要求“每完成一个文件，用一句话说明”，是为了让整个修改过程可以被跟踪审计；要求“不确定时停下来提问”，是为了抵抗模型在没有把握时硬猜的本能。

这背后有一个提示词工程的底层逻辑：你要求模型输出的内容，会影响它的思考过程。让模型写影响面清单，它在写的过程中就会去全局搜索调用关系；让模型在最后输出变更摘要，它就会回过头来复查是否所有引用点都被改到了。输出格式不是写给用户看的，而是为提高模型自身行为质量服务的。

4. 实操过程与核心环节实现：从普通重构到受约束重构

4.1 无约束状态下的典型翻车现场

为了让你直观感受到 CLAUDE.md 的价值，我先描述一次没有约束时让 Sonnet 5.5 做多文件重构的典型过程，这个场景我在模拟项目 X 上复现过。

任务很简单：把某个订单处理模块的getOrderSummary方法改名为getOrderDetail，同时把参数从单个 ID 改为对象。项目大概有 40 多个文件引用这个方法，分布在核心逻辑、接口层和测试里。

没有 CLAUDE.md 时，我的指令是：“请重构订单摘要方法，改为订单详情，参数改为对象，并更新所有引用。”模型第一轮就开始动手，它先改了核心文件里的方法定义，然后改了几个主要调用方，编译报错后就逐个跳转到报错位置修复。表面上很顺利，但问题藏在角落里：有一个通过反射调用的地方没有被编译器发现，模型根本没碰到那个文件；测试文件里的 mock 还沿用旧签名，运行时全挂了；最离谱的是，模型在修改过程中发现某个无关函数的名字不规范，主动把它也改成了驼峰命名。

结果就是：核心改动大约 15 分钟搞定，但修复遗漏的引用花了 3 个小时，review diff 时要在一堆无关改动里挑出真正的变更。整个过程给人一种“大部分时间是在擦屁股，而不是推进重构”的感觉。这就是没有行为约束的多文件重构：看起来 AI 在帮你干活，实际上它在帮你制造工作。

这个翻车现场的核心问题不在模型能力，而在于任务描述里缺少流程约束。模型拿到的是一个开放目标，它只能靠自己的默认行为模式来推进，而默认模式恰恰不适合多文件重构这种需要严格纪律的任务。

4.2 接入 CLAUDE.md 后的流程实录

同样的重构任务，我在项目根目录放了一份类似第 3.1 节的 CLAUDE.md 之后，整个过程变成了完全不同的形态。

首先是模型的响应方式变了。我发出同样一句“请重构订单摘要方法”，它没有直接开改，而是先输出了一张影响面清单。表格里列出了核心文件、6 个直接调用方、12 个间接调用方、5 个测试引用，总共 24 个文件，每个文件标注了影响方式和计划处理动作。这份清单比我手动搜索还全，因为它在搜索时还顺带注意到了文档字符串里的引用和配置里注册的 handler。

然后是流程控制。模型把修改步骤按依赖关系排了序，先改核心定义，再改直接调用方，再改测试 mock。每一步改动之前它都会说“现在修改文件 xx，当前预期影响是……”然后在一次修改完成后，跑一遍针对性检查确认没有遗漏。

到这里你可能已经注意到，CLAUDE.md 的约束并没有增加模型的能力，但它改变了模型的行为方式。原来它是一路狂奔边改边看，现在是先勘察再施工、每步验证、全程可追踪。这个差别不是模型的“聪明程度”带来的，而是流程设计带来的。

最终，整个重构在 4 轮对话内完成。修改的文件数和预期一致，没有越界改动，diff 干净干净。测试第一批就跑过了，没有出现“改完之后发现某个远古调用被遗漏”的情况。最让我意外的是，模型在最后输出变更摘要时，专门标注了两个“需要注意但无法自动处理的点”：一个是通过配置文件注册的适配器类需要手动检查，另一个是历史数据兼容逻辑需要人工决策。这说明它在流程执行中确实做了全局搜索，而不是只盯着编译错误看。

4.3 验证约束是否生效的快速检查法

接入 CLAUDE.md 之后，怎么快速判断它到底有没有起作用？我总结了一套只需两分钟左右的验证方法，在每次调整模板后都会跑一遍。

第一步，故意发一个跨目录的重构请求，比如“把src/core/里某个公共函数改名”，这个动作理论上会触发对tests/目录的同步修改需求。如果 CLAUDE.md 生效，模型应该在影响面清单里主动指出测试文件需要同步更新，但因为它被禁止修改测试目录，会停下来询问你如何处理。如果约束没有生效，它会直接改掉测试文件，或者完全不提测试这事。

第二步，查看模型在开始修改前是否先输出了影响面清单。没有 CLAUDE.md 时，模型几乎从不主动做全局影响分析。这一步是最直观的行为分水岭。

第三步，故意引入一个“与当前任务无关但明显有问题”的代码片段，然后让模型做重构。如果 CLAUDE.md 生效，它会无视这段问题代码。如果没有生效，模型大概率会顺手“帮你修一下”。

这三步验证法，本质上是在测试 CLAUDE.md 的约束是否从“装饰性文本”变成了“行为规则”。我建议每次调整 CLAUDE.md 后都跑一遍确认，否则你可能带着一份从未生效的规则自我感觉良好很久，直到某次重构失控才发现。

注意：CLAUDE.md 的生效依赖工具的正确加载。如果你使用的编辑器或命令行工具没有把 CLAUDE.md 作为项目上下文读取，上面的所有验证都会失败。排查时先确认工具版本和配置，再怀疑模板内容。

5. 常见问题与排查技巧实录

5.1 模型无视规则时的三个突破口

即使 CLAUDE.md 写得再规范，也偶尔会遇到模型“无视规则”的情况。根据我的排查经验，绝大多数不是因为模型“坏掉了”，而是三个原因。

第一个是规则被埋没。如果 CLAUDE.md 有八十行，大部分内容是项目介绍和技术栈说明，真正的约束条款藏在最底下，模型在生成时可能压根没把注意力放到那么靠后的位置。解决办法是把约束条款尽量前置，并把最关键的 5 条硬约束放在文件前 20 行内。长文件会被 AI 当作参考资料而不是行为准则，短文件才容易被当成操作手册。

第二个是规则与当前任务冲突。比如规则说“禁止修改测试文件”，但当前重构改了接口签名，不改测试就无法通过验证。这时候模型会在“遵守规则”和“完成任务”之间产生行为冲突，可能出现两种结果：要么违反规则改了测试，要么卡住不动反复提示。解决方法是在规则里主动预判这种冲突，写好处理方案，比如“如果测试因签名变更而失败，请列出需要修改的测试文件清单并等待用户确认，而不是直接修改”。

第三个是规则语言不够“硬”。像“请尽量不要修改其他文件”这种语气，模型的理解权重很低。它会把“尽量不要”当成意图参考，而不是硬性禁令。我实测下来，“禁止”“必须”“只有……才允许”这类强约束词，遵循度远高于“尽量”“希望”“建议”。规则要写成“禁止修改src/ui/目录下的任何文件”，而不是“注意不要在 UI 目录下随便改动”。

5.2 规则自相矛盾导致的“神秘执行”

CLAUDE.md 里的规则如果互相冲突，模型的执行就会变得非常奇怪——既不像遵守规则一，也不像遵守规则二，而是像在两条指令之间反复横跳。

我遇到过的一个真实案例：某个项目根目录的 CLAUDE.md 写着“重构前必须先生成影响面清单”，但子目录api/下的 CLAUDE.md 写着“本目录改动无需生成清单，直接修改”。当模型要改api/目录下某个被其他模块大量引用的函数时，它陷入了混乱。三次操作里两次先生成影响面清单，一次直接修改，整个行为无法预测。

这种问题的排查方法，是定期扫描多层 CLAUDE.md 之间的语义冲突。重点检查几对常见矛盾：全局层说“禁止 X”但项目层说“仅在某些条件下允许 X”；目录层说“直接操作”但全局层要求“所有修改都走审批流程”；约束里既说“测试很重要”又说“不要动测试文件”却没有说明例外条件。

规避冲突的手段有两个。第一，全局层文件尽量只放“绝对且无条件”的规则，任何需要条件的规则下沉到项目层或目录层，条件只在一处声明。第二，在文件之间建立明显的层级关系引用，比如项目层开头写“本文件建立在全局规则之上，仅做项目内的补充和细化”，这样模型理解时可以自动按层级合并而不是按内容互斥。

5.3 约束太死板导致模型“不敢动”怎么办

CLAUDE.md 写得太严，确实会出现另一个极端：模型变成“应声虫”，做什么都要来问你，推进速度慢了一半。这个体验也不舒服，因为你在用 AI 重构，结果每步都要你点头，效率还不如自己写。

我的经验是，区分“高风险动作”和“低风险动作”，对两者用不同强度的约束。高风险动作——修改公共接口、删除导出函数、新建文件、改动构建配置——保持硬约束，必须确认。低风险动作——在允许目录内调整私有函数实现、修复编译告警、更新注释——可以授权模型自主执行。

实际操作中，可以在模板里加一条授权声明，比如：“在允许目录内，涉及私有函数（非 export）的修改属于低风险动作，无需确认；涉及公共接口的修改属于高风险动作，必须先展示影响面清单并等待确认。”这样模型就有了一个清晰的判断依据，既能自主推进，又不至于在关键节点失控。

这个平衡点的设置，需要针对你的项目规模和风险偏好调整。对一个小项目，可能所有修改都算低风险；对一个核心交易系统，公共接口的任何变化都必须反复确认。CLAUDE.md 的价值本来就不是“越严越好”，而是让模型的行为与你对项目的风险容忍度对齐。

5.4 用变更记录反向迭代 CLAUDE.md

最后一个经验，是关于持续迭代的。CLAUDE.md 不是写一次就永久有效的静态文件，它应该随你在实战中遇到的问题持续演进。

我的做法是，在每次多文件重构结束后，检查模型的变更摘要和 diff，记录两个问题：它做了哪些我不希望它做的事？它漏做了哪些我希望它做的事？这些问题就是 CLAUDE.md 需要更新的方向。

举个例子，有一次重构后我发现模型在最后报告时没有列出反射调用处的改动记录，导致我自己 diff 的时候才发现它改了配置注册逻辑。虽然结果是好的，但过程不够透明。我就在模板的“输出格式要求”里加了一条：“如果本次重构涉及反射、配置注册、动态调用的引用点，必须在变更摘要中单独分组列出。”下次重构，它就真的照做了，因为输出格式的强制要求改变了它执行时的搜索范围。

这种“先用、再发现问题、再沉淀规则”的循环，是我认为提示词工程里最本质的实践方式。CLAUDE.md 的质量不是写出来的，是改出来的。每一次失控和遗漏，都是一次给这个文件升级的机会。我见过最好的项目级 CLAUDE.md，往往不是第一次就写得完美，而是在十几个真实的失败案例之后慢慢长成了刚好适合那个项目的样子。

我个人在实际操作中的感受是，CLAUDE.md 的终极形态，是你把团队里最资深工程师的工作习惯“蒸馏”成了一份给 AI 的操作手册：开场先分析影响面，动手前先汇报计划，一次只改一个文件，每一步都验证，改完检查测试，最后给出增量变更清单。这些习惯单独看都很朴素，但组合在一起，就能把一次混乱的多文件重构变成一次有序的、可控的、可审查的工程任务。如果你正在被 AI 重构搞得分身乏术，不妨从这份模板开始，跑两轮真实任务，再根据你自己的翻车经历去修改它。不用追求完美，先让它存在，然后让它在每一次失控中成长。