几千行的单文件总是改不动：为什么整文件重写风险最高，怎么切片改
数据截至 2026-07，各产品的额度与报错口径以官方最新说明为准。
大文件改不动，绝大多数人归错了因：以为是模型”不够聪明”或者”上下文装不下”，于是换更强的模型、开更大的窗口，结果照样翻车。具体的失败原因其实有好几种（下一节会拆成三类），但把它们统统放大成灾难的是同一件事：你让它交付一份”整个文件的新版本”。一次生成上千行代码，任何一处遗漏都会以”看起来完整的代码”形式呈现出来，你没有任何局部信号能发现它。 换句话说，不是它改不好，是这种交付方式把”漏改”和”改坏”变成了不可观测的事件——同样的错误如果发生在一段三十行的片段里，你扫一眼就抓住了。
这一点和站内另外两篇要区分开：大仓库上下文塞不下 讲的是跨文件、跨模块时工具看不到全貌该怎么喂料，AI 改动范围失控 讲的是它擅自动了你没让它动的文件；本篇只盯一个场景——单个文件本身太大，你明明只想改其中一小段，却拿回来一整份重写。
一、先分因：三种”改不动”长得很像
同样是”改完不能用”，底下的成因完全不同，处置动作也不同。先别急着重试，花两分钟做判别。
成因 A：定位不准。 文件里有多个同名或近似的函数、多处相似的分支，模型改到了另一处。特征是新旧文件行数差不多，你要的行为没变，别的地方却动了。
成因 B：输出被截断或省略。 长输出中途停了，或者中间出现”其余保持不变”之类的省略式占位。特征是文件末尾突兀、括号不配对、语法检查直接报错，或者行数比原文件明显少了一大截。这类问题的通用排查思路可以参考输出被截断的排查。
成因 C：模型顺手”优化”。 它一边改你要的那处，一边把它认为不规范的地方重写了：换了日志格式、合并了分支、删掉了它认为无用的兼容代码。特征是行数接近甚至更少，但 diff 铺开有几十上百处无关改动，这属于改坏代码后的回滚要处理的范畴。
判别这三者只需要两条命令。先看规模：
git diff --numstat -- path/to/big_file.py
再看散布：
git diff -U0 -- path/to/big_file.py | grep -c '^@@'
第二条数的是 diff 里的 hunk 数量。你只想改一处逻辑，hunk 数应该是个位数。如果它是几十，不管代码看起来多漂亮，这次结果都不能要。
二、判别表：从现象直接查处置
| 现象 | 大概率成因 | 怎么验证 | 处置动作 |
|---|---|---|---|
| 行数接近，目标行为没变，别处却动了 | 定位到了同名/相似代码块 | 用 git diff -U0 看改动落在哪些行号区间，和目标函数的行号范围对照：hunk 只有一两处且整体落在别的函数里，就是定位错；hunk 散成几十处才是下面的顺手重构 | 丢弃本次结果，改用行号区间锚定重发 |
| 文件末尾突然中断、括号不配对 | 输出被截断 | 跑语法检查（如 python -m py_compile file.py），或对比前后总行数 | 丢弃，缩小到单个函数重发，不要求整文件 |
| 结构看着完整，但总行数比原文少了一大截 | 中间被省略式占位替换了 | 全文搜省略语义的注释行和连续三个点；再跑语法检查兜底，但别只信它（注释式占位会让缩进块为空而报错，写成 ... 的占位在 Python 里是合法表达式，编译照样通过） | 丢弃，明确只要改动片段不要全文 |
| hunk 数几十上百 | 顺手重构 | 数 @@ 出现次数 | 丢弃，或用 git add -p 只挑你要的 hunk |
| 语法过、单测过，线上行为不对 | 改动落在未覆盖分支 | 看目标函数的测试覆盖情况，补一条针对性用例再跑 | 先补测再改，参考下文第四节 |
| 每次重试结果都不一样且都不对 | 任务描述本身不可判定 | 你能否用一句话说清”改完之后什么表达式的值会变” | 停手，回到需求，别再重试 |
合并时出现冲突标记 <<<<<<< | 并行改了同一文件 | git status 看是否处于合并态 | 先解决冲突再谈内容对错 |
这张表的用法是自上而下：先排除截断和省略这类机械故障，再看范围问题，最后才怀疑逻辑本身。反过来查会浪费很多次重试。
三、切片改：把一次大改拆成能验证的小步
确认了成因，动作只有一个方向——不要整文件进、不要整文件出。
第一步，定位到行号区间。 大文件里最可靠的坐标不是函数名（会重名），是行号。先把文件的结构骨架拉出来：
python -c "import ast,sys;src=open(sys.argv[1],encoding='utf-8').read();[print(n.lineno,type(n).__name__,n.name) for n in ast.parse(src).body if hasattr(n,'name')]" path/to/big_file.py
这条命令列出顶层的类和函数及其起始行。你要改的那段落在哪个区间，一眼就能定。其他语言没有 ast 这么方便，用编辑器的大纲视图或者 grep -n 定位定义行，效果一样。
第二步，只把相关切片交出去。 目标函数本体、它调用的两三个内部工具函数、它依赖的常量定义，这些够了。文件顶部几百行的 import 和无关的类，不要一起给。给多了不会更准，只会让模型更倾向于”顺手整理一下”。
第三步，要求返回改动片段而不是文件。 让它给出替换后的函数体，或者给出一段可读的差异说明；你自己粘回去。这一步很多人嫌麻烦，但它把”漏改”变成了可观测的事——片段只有几十行，你逐行看得完。
第四步，一刀只做一件事。 修 bug 就只修 bug，重命名、提取函数、补类型标注各自单独一刀，各自单独提交。理由不是洁癖：混在一起的 diff 你审不动，出问题时也没法二分定位是哪一刀引入的。
第五步，每刀落地就提交。 用 git add -p 挑 hunk，不要 git add .。提交信息写清这刀改了什么行为。这样后面任何一步出问题，回滚粒度是”一刀”而不是”一天”。
如果这个文件要连续改好几处，可以开一个独立工作区并行推进，互不污染：
git worktree add -b fix/slice-a ../repo-fix-a
四、验证：每一刀都要能回答”我怎么知道没改坏”
大文件难改的另一半原因是它通常没测试——正因为没测试，它才长成了几千行。所以验证要靠自己搭。
语法/编译先过。 这是最便宜的一道闸，能直接筛掉截断和括号不配对。任何语言都有对应的快速检查手段，改完立刻跑，别攒着。
给目标函数补一条最小用例。 不追求覆盖率，只要一条：改动前它是什么结果，改动后应该是什么结果。写这条用例的过程还有个副作用——如果你写不出来，说明你其实没想清楚要改什么，这时候继续改就是在赌。
用 git log -L 看这段代码的历史。
git log -L 820,960:path/to/big_file.py
它只显示这个行区间的演化。大文件里的诡异分支往往有来历，看一眼历史能避免把别人踩过坑加的补丁又删掉。
跑一遍调用方。 大文件的函数常被十几处调用，找出来确认签名和返回结构没变：
grep -rn "your_function_name" --include="*.py" .
别把”测试绿了”当终点。 大文件的测试往往只覆盖主干路径，绿灯不代表边界分支没坏，这个陷阱在测试绿了线上还是炸里讲得更细。
五、什么情况下别再折腾：止损点与回滚点
工程上最贵的不是改不对，是明知改不对还在重试。给你三条明确的停手信号。
信号一：同一处改动重试三次以上，每次错法都不同。 这说明问题不在执行，在描述。你的要求里存在模型无法判定的部分——比如”让这个函数更健壮”、“处理一下异常情况”。停手，回去把要求改写成可验证的形式：什么输入、原来返回什么、期望返回什么。改完描述再发一次，通常一次就过。
信号二：diff 已经看不动了。 如果你打开 diff 的第一反应是往下拉而不是逐行读，这份改动就不该合并。此刻的正确动作是 git checkout -- path/to/big_file.py 全部丢弃，然后把任务切得更细重来。丢弃已经生成的代码在心理上有点难受，但你要比较的是”丢掉半小时”和”带着不明改动上线”。
信号三：这个文件已经改到第三次冲突。 说明它是团队热点文件，边改边被别人改。这时候值得先做一次纯机械的物理拆分——把明显内聚的几个类各自搬到独立文件，不改任何逻辑，单独提交并跑全量测试。拆完再改内容，成本会低一个量级。
回滚点怎么设：改动前打一个标记提交或者临时分支，别只依赖编辑器的撤销栈。工具在长任务里可能改过你没注意的文件，撤销栈救不了跨文件的状态。
还有一种情况是该换路而不是回滚：如果这段代码你自己都说不清它现在的行为，那正确顺序是先补一层”记录当前行为”的测试（哪怕记录的是有 bug 的行为），再动它。跳过这一步直接重写，等于用一个你不理解的旧实现换一个你不理解的新实现。
六、避坑清单：为什么会踩，怎么避
坑一：让它”顺便把这个文件整理一下”。 会踩是因为你觉得反正要动，一起做省事。但整理和修 bug 混在同一个 diff 里，审查者无法分辨哪些改动是必要的，出事时也没法二分。避法：整理单独一刀、单独提交，且整理那一刀必须是行为不变的纯机械操作。
坑二：用函数名当唯一定位锚。 会踩是因为几千行的文件里重名概率极高，handle、process、validate 这类名字常常出现好几次，还可能分属不同的类。避法：定位用”行号区间 + 所属类名”双锚，交出去的切片自己带上起止行号。
坑三：不看行数直接合并。 会踩是因为返回的代码语法正确、格式漂亮，人对”完整感”的判断非常不可靠。避法：合并前必看 git diff --numstat 的增删行数，删除行数明显大于你的预期就是红灯。
坑四：把大文件整个粘进对话反复迭代。 会踩是因为第一轮似乎有效，于是一直这么用。但多轮之后早期的内容会被挤压，模型会拿着一份残缺的印象继续改，前面的约束悄悄失效。避法：每一刀开新会话，只带当前切片；同一个会话不要连续改超过两三处。
坑五：并行开多个任务改同一个文件。 会踩是因为你觉得反正是不同的函数。但它们写回的是同一份文件，后写的会覆盖先写的，或者留下冲突标记。避法：同一文件串行改，确实要并行就用不同的 worktree，各自提交后再合并。
坑六：省略式占位没检查就保存。 会踩是因为占位注释看起来很像正常注释，扫一眼过去不显眼。避法：保存前全文搜一遍省略语义的注释和连续三个点，别把语法检查当唯一防线——注释式占位会让函数体为空而直接报错，这类能被拦住；但如果占位写成 ...（Python 里它是合法表达式）或者空的 pass，编译和语法检查全都过得去，只有你自己的搜索和行数对比能发现。这也是为什么第三节要求返回片段而不是整文件：片段短到你必须逐行看，占位藏不住。
坑七：以为换个更强的工具就能整文件重写。 会踩是因为宣传口径容易让人觉得”装得下就能改好”。装得下和改得对是两件事：读得进去只保证它知道现在长什么样，而输出越长，需要一次不错地复述出来的原有代码就越多，出现遗漏、省略和顺手改写的机会也就越多，而这些你在一整份新文件里根本看不出来。另外，如果你打算换的是海外工具，先确认可用性再谈效果——部分海外 AI 编程产品与模型服务对中国大陆的开放范围、账号与支付方式各不相同，能不能合规、稳定地接入是选型的前置条件，具体以其官方最新说明为准。这件事要在动手改代码之前问清楚，而不是改到一半才发现服务不可用。
收束：合并前的六条自检
大文件不是不能改，是不能用”整份交付”的方式改。把交付单位从文件降到函数、把验证单位从”跑通”降到”一条用例”，几千行的文件就退化成了几十个小文件的集合，难度就此消失。
每次准备把改动合进主干前，过一遍这六条：
git diff --numstat的增删行数是否落在你的预期量级内。- diff 的 hunk 数是否是个位数；不是就说明范围超了。
- 语法/编译检查是否跑过。
- 全文是否搜过省略式占位（注释形式的和
...这种能通过编译的都要搜）。 - 目标行为是否有一条能跑的用例证明它变了，且只有它变了。
- 这一刀是否只做了一件事，提交信息是否说得清。
六条里任何一条答不上来，就别合。丢弃重来的成本，永远低于把一份看不懂的改动放进主干。