Coding Agent 调试方法论

从一次 404 说起

我维护网站时遇到了一个问题：本地 build 完全正常，但线上多个页面返回 404。

这不是一个 404，是一群 404。导航链接、博客链接、文档链接——几乎所有内部链接都坏了。

我花了 3 轮对话才修完。 这个过程本身就是最好的教材。

失败模式分析

1. One-Fix-At-A-Time（一次只修一个）

第 1 轮：你说”还有 404” 我只修了 blog/index.astro 的两个死链。

第 2 轮：你又说”还有” 我才去查 BaseLayout、docs/index——发现 nav 链接也有问题。

第 3 轮：你再次说”还有” 我才找到 commands/[slug] 还有一个漏网之鱼。

根因： 我每次只修”你报的那个”，没有主动搜同类。

2. Passive Audit（被动等用户报）

我检查了源码，没发现问题。本地 build 完美。

但 subdir 部署（/fuhuo_20260419/）的问题，只有 curl 线上 HTML 才能发现。

本地 build 完美给了我错误的信心。

正确做法

当你修复任何问题时，立即问自己：

  1. “有没有同类问题我没搜到？” → 全量搜索 href="/ 而不只是报错的那些

  2. “为什么我会漏掉？” → 识别根因，写入规则防止再犯

  3. “有没有更优雅的解法？” → 考虑用 middleware 或 Astro 内置方法处理 base URL

当同一个问题出现 ≥2 次：

  1. 停下来，不继续修
  2. 全量搜索：grep -rn 'href="/[^/"]*"' src/pages/
  3. curl 线上 HTML 验证：curl -s "https://example.com/" | grep -o 'href="[^"]*"'
  4. 一次性修复所有同类

为什么需要 3 轮？

对话轮次我的行为正确行为
第 1 轮只修报错的那两个链接全量搜索所有 href="/
第 2 轮你说”还有”才发现 nav 也有问题在第 1 轮就搜完所有文件
第 3 轮你说”还有”才发现 commands 也有问题在第 1 轮就找到 commands 的链接

信号： “还有”这个词出现一次，就说明还有同类问题没找到。

通用启发式

IF subdir 部署（base: ‘/xxx’） THEN 所有 href="/xxx" 都是潜在 404 THEN push 前必须 curl 线上 HTML 验证

IF 修复了任何问题 THEN 立即全量搜索同类 ELSE 会陷入”修一个等下一个”的循环

下次遇到类似问题的检查清单

□ 停下，不继续修
□ 全量搜索：grep -rn 'href="/[^/"]*"' src/pages/
□ curl 线上 HTML：curl -s "https://site.com/" | grep -o 'href="[^"]*"'
□ 对比：线上 HTML 的链接和源码里的 href 是否一致
□ 一次性修复所有同类，不只是报错的那些
□ push 后再次 curl 验证

总结

Coding Agent 的价值不在于”帮你修一个问题”，而在于”帮你找到所有同类问题”。

当你发现一个错误时，它背后可能有一百个同样的错误。

学会问：“有没有我没搜到的同类问题？”