一个人，半年，30万行代码：Reddit 老哥的 Claude Code 硬核指南

原文来源：Reddit - Claude Code is a Beast – Tips from 6 Months of Hardcore Use
GitHub 仓库：https://github.com/diet103/claude-code-infrastructure-showcase
翻译 + 分析：朴哲一
发布日期：2025-11-01 北京时间

开篇

大多数人用 AI 编程工具，都在"vibe-coding"——随便问问，随便改改，能跑就行。

但在 Reddit 上，有个老哥用了半年 Claude Code，独自一人把一个 10 万行的老项目重构到 30 万行，从 React 16 升级到 React 19，还把测试覆盖率从 0 拉到了可用水平。

他不是什么大厂架构师，也不是 AI 研究员。他只是个普通的 7 年 Web 开发，但他做了一件很多人都没做的事：把 AI 编程工具当成真正的工程问题来解决。

他的方法论很简单：

Skills 自动激活系统 - 让 Claude 真正用上你写的技能文档
Dev Docs 工作流 - 防止 Claude 失去上下文，忘记自己在干什么
PM2 + Hooks 零错误机制 - 不让任何 TypeScript 错误溜走
专业化 Agents 军团 - 代码审查、调试、规划全自动化

这套系统听起来很复杂，但核心思想只有一个：用工程化方法解决 AI 的不确定性。

下面是他的完整分享。文章很长（原帖 8000+ 字），但每个细节都值得细读。我翻译了核心内容，并在最后加上了自己的分析。

An image to describe post

免责声明（原作者）

我在 6 个月前发过一篇关于 Claude Code 的使用体验，当时只用了一周。现在半年过去了，我想再分享一些新的技巧、窍门和碎碎念。

这篇文章可能有点长，所以做好准备，泡杯咖啡，坐马桶上或者干点别的什么，就当刷 Reddit 了。

我想先声明：这篇文章里的所有内容，都只是我在分享目前对我最有效的设置，不应该被当成圣经或者唯一正确的做法。我只是希望能启发你优化自己的 AI 编程工作流。

我只是个普通人，这只是我的个人观点，老兄。

另外，我用的是 20x Max 计划，所以你的情况可能不一样。如果你只是想找 vibe-coding 的技巧，那你找错地方了。想从 Claude Code 榨取最大价值，你需要和它一起工作：规划、审查、迭代、探索不同方案等等。

（GitHub 仓库更新）：作者后来花了一下午把代码整理到了 GitHub 上：

🎯 仓库地址：https://github.com/diet103/claude-code-infrastructure-showcase

快速概览

半年高强度使用 Claude Code（独自重构 30 万行代码）后，我搭建了这套系统：

Skills 真正能自动激活了 - 不再是摆设
Dev Docs 工作流 - 防止 Claude 失去方向
PM2 + Hooks - 零错误遗留机制
专业化 Agents 军团 - 审查、测试、规划全自动化

背景故事：一个人重构 30 万行代码

我是谁

我是一个做了大约 7 年生产环境 Web 应用的软件工程师。我完全拥抱了 AI 这波浪潮。

我不太担心 AI 会抢我饭碗，因为它是我用来放大自己能力边界的工具。通过这种方式，我开发了很多新功能，还用 Claude 和 GPT-5 Thinking 做了很多提案演示，把新的 AI 系统集成到生产应用里。

这些都是我之前做梦都不敢想的项目——没有 AI 之前，我根本没时间考虑这些事。

因为这样，我在公司获得了不少职业安全感，还成了公司里的"AI 大师"，因为其他人在 AI 集成方面大概落后我一年左右。

立下 Flag：3 个月重构 10 万行代码

有了这份自信，我向老板提了一个相当大的重构/重设计方案——针对公司内部使用的一个 Web 应用。

这是个相当粗糙的项目，最初是个大学生做的，从我 7 年前当实习生时做的另一个项目 fork 出来（4 年前 fork 的）。

这可能有点过于雄心勃勃了，因为为了说服利益相关者，我同意在几个月内完成这个相当大规模项目（约 10 万行代码）的自顶向下重设计……而且是我一个人。

我知道即使有 Claude Code 帮忙，我也得加班才能搞定。但我心里清楚，这东西做成了会很牛逼，能自动化很多手动流程，给公司很多人省下大量时间。

6 个月后：30 万行代码，寿命减少 5 年

现在 6 个月过去了……是的，我当时不应该同意那个时间表。我测试了 Claude 和我自己理智的极限，就为了把这东西搞定。

我完全废掉了旧的前端，因为所有东西都严重过时了，我想玩最新最炫的技术：

React 16 JS → React 19 TypeScript
React Query v2 → TanStack Query v5
React Router v4 (hash router) → TanStack Router (文件路由)
Material UI v4 → MUI v7
严格遵守最佳实践

项目现在大约有 30-40 万行代码，我的预期寿命减少了约 5 年。它终于准备好可以测试了，我对结果非常满意。

从技术债地狱到可维护项目

这曾经是一个有着无法偿还的技术债、零测试覆盖率、糟糕透顶的开发体验（测试功能简直是噩梦）的项目，还有各种奇怪的问题。

我解决了所有这些问题：

✅ 不错的测试覆盖率
✅ 可控的技术债
✅ 实现了命令行工具用于生成测试数据
✅ 开发模式可以测试前端的不同功能

在这段时间里，我摸清了 Claude Code 的能力边界，知道能从它那期待什么。

关于质量和一致性的说明

很多人在抱怨什么？

我注意到论坛和讨论里有个反复出现的主题——人们对使用限制感到沮丧，担心输出质量随时间下降。

我先说清楚：我不是要否定这些体验，也不是说这只是"用法不对"的问题。每个人的用例和上下文都不一样，正当的担忧值得被听到。

我的体验：质量在提升

话虽如此，我想分享一下对我有效的东西。

在我的体验里，Claude Code 的输出质量在过去几个月实际上有提升，我相信这很大程度上是因为我一直在优化的工作流。

我希望如果你从我的系统中获得哪怕一点点启发，并把它融入你的 Claude Code 工作流，你会给它更好的机会产出你满意的高质量输出。

现实点：有时候 Claude 确实会搞砸

现在，说点实在的——Claude 绝对有完全跑偏、产出次优代码的时候。这可能因为各种原因发生。

首先，AI 模型是随机的（stochastic），意味着相同输入可能得到差异很大的输出。有时候随机性就是不站在你这边，你得到的输出质量确实很差，这不是你的错。

其他时候，问题在于提示词的结构。措辞稍有不同就可能导致输出有很大差异，因为模型会很字面地理解你的话。如果你措辞不当或表达模糊，可能导致结果大幅变差。

有时候你就得自己上

听着，AI 很强大，但它不是魔法。有些问题，人类的模式识别和直觉就是更快。

如果你看着 Claude 挣扎了 30 分钟，而你自己 2 分钟就能修好，那就自己修。没什么丢人的。

就像教人骑自行车，有时候你就得扶一下车把，然后再放手。

我在逻辑谜题或者需要真实世界常识的问题上特别明显地看到这一点。AI 可以暴力破解很多东西，但有时候人类就是"秒懂"。

不要因为固执或者某种"AI 应该做所有事"的错误观念而浪费时间。该出手时就出手，修好问题，继续前进。

反思你的提示词质量

我也有过很多糟糕的提示词，通常发生在一天快结束的时候，我变懒了，没怎么在提示词上下功夫。结果真的很明显。

所以下次你遇到这类问题，觉得输出质量明显变差，怀疑 Anthropic 偷偷削弱了 Claude 时，我建议你退一步，反思一下自己是怎么提示的。

经常重新提示。你可以双击 ESC 调出之前的提示词，选一个分支重来。你会惊讶地发现，带着"知道自己不想要什么"的知识再问一次，往往能得到好得多的结果。

总之，输出质量看起来变差可能有很多原因，自我反思并考虑你能做什么来给它最好的机会得到你想要的输出，是很重要的。

正如某个智者可能说过的：
"不要问 Claude 能为你做什么，要问你能给 Claude 什么样的上下文"
—— 某智者

好了，我要从肥皂箱上下来了，开始讲干货。

为什么这部分值得单独拿出来讲？

因为它彻底改变了我使用 Claude Code 的方式。

问题：Skills 就是个摆设

Anthropic 发布 Skills 功能时，我当时想"这看起来太棒了！"

这个想法很美好：可移植、可复用的指导文档，Claude 可以参考它们，听起来非常适合在我这个庞大的代码库中保持一致性。

我花了大量时间和 Claude 一起写了全面的技能文档：

前端开发
后端开发
数据库操作
工作流管理
等等……

我们写了几千行最佳实践、模式和示例。

然后……什么都没发生。

Claude 就是不用这些技能。

我试过：

❌ 用技能描述里的确切关键词 → 没用
❌ 编辑技能相关的文件 → 没用
❌ 明确告诉 Claude 去查技能文档 → 偶尔有用

太让人抓狂了。我能看到潜力，但这些技能就像昂贵的装饰品一样摆在那里。

"啊哈"时刻：用 Hooks 强制激活

那时我想到一个主意：既然 Claude 不会自动使用技能，那我就建一个系统，强制让它在做任何事之前先检查相关技能。

于是我深入研究了 Claude Code 的 Hooks 系统，用 TypeScript 构建了一个多层自动激活架构。

它真的有用！

工作原理

我创建了两个主要的 Hooks：

Hook 1: UserPromptSubmit（在 Claude 看到你的消息之前运行）

做什么：

分析你的提示词，查找关键词和意图模式
检查哪些技能可能相关
在 Claude 的上下文中注入格式化的提醒

效果：

现在当我问"布局系统是怎么工作的？"时，Claude 会先看到一个大大的提示：

🎯 SKILL ACTIVATION CHECK
使用 project-catalog-developer 技能

然后才会读我的问题。

（注：project-catalog 是我前端的一个大型复杂数据网格功能）

Hook 2: Stop Event（在 Claude 完成响应之后运行）

做什么：

分析哪些文件被编辑了
检查有风险的模式（try-catch 块、数据库操作、async 函数）
显示温和的自查提醒

效果：

显示类似这样的提醒：

❓ 你添加错误处理了吗？
❓ Prisma 操作使用了 repository 模式吗？

非阻塞，只是让 Claude 保持意识，不会很烦人。

skill-rules.json 配置

我创建了一个中央配置文件，定义每个技能的：

Keywords（关键词）：明确的主题匹配（"layout"、"workflow"、"database"）
Intent patterns（意图模式）：正则表达式捕捉动作（"(create|add).*?(feature|route)"）
File path triggers（文件路径触发器）：基于你正在编辑的文件激活
Content triggers（内容触发器）：如果文件包含特定模式就激活（Prisma imports、controllers 等）

配置示例

{
  "backend-dev-guidelines": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "high",
    "promptTriggers": {
      "keywords": ["backend", "controller", "service", "API", "endpoint"],
      "intentPatterns": [
        "(create|add).*?(route|endpoint|controller)",
        "(how to|best practice).*?(backend|API)"
      ]
    },
    "fileTriggers": {
      "pathPatterns": ["backend/src/**/*.ts"],
      "contentPatterns": ["router\\.", "export.*Controller"]
    }
  }
}

An image to describe post

效果：天差地别

现在当我做后端代码时，Claude 会自动：

✅ 在读我的提示词之前就看到技能建议
✅ 加载相关的指导文档
✅ 实际上一致地遵循这些模式
✅ 在结束时通过温和提醒进行自查

区别简直是天差地别：

之前：

代码不一致
"等等，Claude 又用回旧模式了"
每次都要手动告诉它检查指导文档

之后：

不再有不一致的代码
不再有"Claude 又用旧模式了"
不再需要每次手动提醒检查指导文档

An image to describe post

遵循 Anthropic 的最佳实践（走了弯路）

自动激活能用之后，我深入研究了 Anthropic 的官方最佳实践文档。

结果发现我做错了。

他们建议：

主 SKILL.md 文件保持在 500 行以内
使用渐进式披露（progressive disclosure）配合资源文件

糟糕。我的 frontend-dev-guidelines 技能有 1500+ 行。还有几个其他技能超过 1000 行。

这些庞大的单体文件违背了技能的初衷（只加载你需要的东西）。

重构：拆分成主文件 + 资源文件

于是我重新组织了所有东西：

frontend-dev-guidelines: 398 行主文件 + 10 个资源文件
backend-dev-guidelines: 304 行主文件 + 11 个资源文件

效果：

现在 Claude 最初只加载轻量级的主文件，只有在真正需要时才拉取详细的资源文件。

Token 效率提升了 40-60%（大多数查询）。

我创建的技能清单

指导原则与最佳实践

backend-dev-guidelines - Routes → Controllers → Services → Repositories
frontend-dev-guidelines - React 19, MUI v7, TanStack Query/Router 模式
skill-developer - 元技能，用于创建更多技能

领域特定

workflow-developer - 复杂工作流引擎模式
notification-developer - 邮件/通知系统
database-verification - 防止列名错误（这个是护栏技能，会实际阻止编辑！）
project-catalog-developer - DataGrid 布局系统

所有这些都基于我正在做的工作自动激活。就像有个真正记得所有模式的高级开发在盯着 Claude 的肩膀。

为什么这很重要

之前（技能 + Hooks 之前）：

❌ Claude 会用旧模式，即使我已经记录了新模式
❌ 每次都要手动告诉 Claude 检查 BEST_PRACTICES.md
❌ 30 万+ 行代码库中代码不一致
❌ 花太多时间修复 Claude 的"创意解读"

之后（技能 + Hooks 之后）：

✅ 一致的模式自动强制执行
✅ Claude 在我看到代码之前就自我纠正
✅ 可以信任指导原则正在被遵循
✅ 审查和修复花的时间少得多

我的建议

如果你在一个有既定模式的大型代码库上工作，我强烈推荐这套系统。

初始设置花了我几天时间才调对，但它的回报至少是成本的十倍。

核心洞察（我的补充）

为什么 Skills 默认不工作？

这不是 Anthropic 的 bug，而是 AI 模型的本质问题：

上下文窗口有限 - Claude 不可能每次都把所有技能文档加载进来
概率性触发不可靠 - "可能相关"不如"强制检查"
用户意图模糊 - Claude 无法准确判断你是不是真的需要某个技能

这位老哥做对了什么？

他把 AI 的问题当成工程问题来解决：

明确的触发条件 - 关键词、文件路径、内容模式
分层决策 - 提示词级别 + 文件编辑级别
温和的提醒而非强制阻断 - 保持灵活性
反馈循环 - Stop hook 让 Claude 自查

这不是 prompt engineering，这是 prompt infrastructure engineering。

CLAUDE.md 的问题：想做的太多了

在我 6 个月前写的帖子里，我有一节讲"规则是你最好的朋友"，我现在依然坚持这个观点。

但我的 CLAUDE.md 文件很快就失控了，想做的事太多。我还有一个巨大的 BEST_PRACTICES.md 文件（1400+ 行），Claude 有时会读，有时完全无视。

于是我花了一个下午和 Claude 一起，把所有东西整合重组成一个新系统。

重组：什么应该放在哪里？

迁移到 Skills 的内容

之前，BEST_PRACTICES.md 包含：

TypeScript 标准
React 模式（hooks、组件、suspense）
后端 API 模式（routes、controllers、services）
错误处理（Sentry 集成）
数据库模式（Prisma 使用）
测试指导
性能优化

所有这些现在都在 Skills 里，配合自动激活 Hook 确保 Claude 真正使用它们。

不再寄希望于 Claude 记得检查 BEST_PRACTICES.md。

保留在 CLAUDE.md 的内容

现在 CLAUDE.md 专注于项目特定信息（只有约 200 行）：

快捷命令（pnpm pm2:start, pnpm build 等）
服务特定配置
任务管理工作流（dev docs 系统）
测试认证路由
工作流 dry-run 模式
浏览器工具配置

新的文档结构

根目录 CLAUDE.md (100 行)
├── 关键的通用规则
├── 指向各仓库特定 claude.md 文件
└── 引用 Skills 获取详细指导

每个仓库的 claude.md (50-100 行)
├── Quick Start 部分，指向：
│   ├── PROJECT_KNOWLEDGE.md - 架构与集成
│   ├── TROUBLESHOOTING.md - 常见问题
│   └── 自动生成的 API 文档
└── 仓库特定的小技巧和命令

魔法在于：Skills 处理所有"如何写代码"的指导，CLAUDE.md 处理"这个特定项目如何工作"。

关注点分离，成功。

Dev Docs 系统：防止 Claude 失忆

在我尝试的所有东西里（除了 Skills），这个系统对我从 Claude Code 得到的结果影响最大。

核心问题

Claude 就像一个极度自信的、有严重失忆症的初级开发，很容易忘记自己在做什么。

Dev Docs 系统就是为了解决这个缺陷。

我的 CLAUDE.md 中的 Dev Docs 部分

### 开始大型任务

当从规划模式退出并接受计划时：

1. **创建任务目录**：
   mkdir -p ~/git/project/dev/active/[task-name]/

2. **创建文档**：
   - `[task-name]-plan.md` - 已接受的计划
   - `[task-name]-context.md` - 关键文件、决策
   - `[task-name]-tasks.md` - 工作清单

3. **定期更新**：立即标记完成的任务

### 继续任务

- 检查 `/dev/active/` 查找现有任务
- 在继续之前阅读所有三个文件
- 更新"最后更新"时间戳

这些文档会在每个功能或大型任务时创建。

为什么需要这个？

在使用这个系统之前，我有很多次突然意识到 Claude 已经跑偏了，我们不再在实现 30 分钟前计划的东西，因为我们因为某种原因跑去做了别的事。

我的规划流程

规划为王

如果你在让 Claude 实现东西之前，连规划模式都不用，那你会吃苦头的，嗯哼。

你不会让建筑工人来你家，在没有先画好图纸的情况下就开始加建吧。

我如何规划

当我开始规划一个功能时，我会进入规划模式，即使最终我会让 Claude 把计划写到 markdown 文件里。

我不确定进入规划模式是否必要，但对我来说，感觉规划模式在研究你的代码库和收集所有正确上下文来制定计划方面，会得到更好的结果。

strategic-plan-architect Agent

我创建了一个 strategic-plan-architect 子 Agent，基本上就是个规划猛兽。它会：

高效收集上下文
分析项目结构
创建全面的结构化计划，包含：
- 执行摘要
- 阶段
- 任务
- 风险
- 成功指标
- 时间线
自动生成三个文件：plan、context 和 tasks checklist

但我觉得很烦的是：

❌ 你看不到 Agent 的输出
❌ 更烦的是，如果你对计划说"不"，它就直接杀掉 Agent，而不是继续规划

所以我还创建了一个自定义 slash 命令（/dev-docs），用同样的提示词在主 Claude Code 实例上使用。

审查计划（关键步骤）

一旦 Claude 产出了那个漂亮的计划，我会花时间仔细审查。

这一步真的很重要。花时间理解它，你会惊讶地发现你能多频繁地抓到愚蠢的错误，或者 Claude 误解了请求或任务中非常关键的部分。

创建 Dev Docs 文件

通常退出规划模式后，我的上下文只剩 15% 或更少。但没关系，因为我们会把所有需要的东西放进 Dev Docs，以便全新开始。

Claude 通常喜欢直接冲进去开干，所以我会立即按 ESC 键打断它，然后运行我的 /dev-docs slash 命令。

这个命令会拿着已批准的计划，创建所有三个文件，有时如果还有足够的上下文，会做一些额外的研究来填补空白。

实现过程

完成这些之后，我基本上就可以让 Claude 完整实现功能，而不会迷路或忘记它在做什么，即使经历了自动压缩（auto-compaction）。

我只是确保每隔一段时间提醒 Claude 更新任务以及用任何相关上下文更新 context 文件。

当当前会话的上下文快用完时，我就运行我的 slash 命令 /update-dev-docs。Claude 会记录任何相关上下文（以及下一步），并标记完成的任务或添加新任务，然后我再压缩对话。

新会话里我只需要说"继续"就行。

分阶段实现

根据功能或任务的大小，我会特别告诉 Claude 一次只实现一两个部分。

这样，我有机会在每组任务之间进去审查代码。

而且我会定期让一个子 Agent 也审查变更，这样我能尽早抓到大错误。

如果你没有让 Claude 审查它自己的代码，那我强烈推荐，因为它帮我省了很多头疼，抓到了：

关键错误
缺失的实现
不一致的代码
安全漏洞

核心洞察（我的补充）

Dev Docs 本质上是什么？

这是一个外部化的工作记忆系统。

AI 的问题不是不够聪明，而是：

上下文窗口有限 - 无法记住所有历史
没有持久记忆 - 每次压缩都可能丢信息
容易被新信息分散 - 没有"大局观"锚点

Dev Docs 三文件系统对应：

plan.md = 目标（我们要去哪里）
context.md = 地图（我们在哪里，有什么资源）
tasks.md = 清单（我们做了什么，还剩什么）

An image to describe post

为什么有效？

这和人类项目管理的最佳实践一样：

明确的计划 - 防止范围蔓延
文档化的上下文 - 新成员能快速上手
可追踪的任务 - 知道进度

只不过这里的"新成员"是每次压缩后的 Claude。

可复用到哪里？

这套方法论不只适用于 Claude Code：

任何长期项目都应该有这三个文件
团队协作时，这是最小文档集
即使是人类开发，也经常忘记两周前的决策

好的工程实践对人和 AI 都有效。

PM2 进程管理：后端调试的救星

这是相对较新的改进，但让后端调试变得容易太多了。

问题：Claude 看不到后端日志

我的项目有 7 个后端微服务同时运行。

问题是 Claude 无法在服务运行时查看日志。我不能直接问"邮件服务出什么问题了？"——Claude 看不到日志，除非我手动复制粘贴到聊天里。

中间方案：手动写日志文件

有一段时间，我让每个服务用一个 devLog 脚本把输出写到带时间戳的日志文件里。

这个方案……勉强能用。Claude 可以读日志文件，但很笨重：

❌ 日志不是实时的
❌ 服务崩溃不会自动重启
❌ 管理所有东西很痛苦

真正的解决方案：PM2

然后我发现了 PM2，这是个改变游戏规则的东西。

我配置了所有后端服务通过 PM2 运行，一条命令搞定：

pnpm pm2:start

PM2 给我带来了什么：

✅ 每个服务作为托管进程运行，有自己的日志文件
✅ Claude 可以轻松实时读取单个服务的日志
✅ 崩溃自动重启
✅ 用 pm2 logs 实时监控
✅ 用 pm2 monit 监控内存/CPU
✅ 轻松管理服务（pm2 restart email, pm2 stop all 等）

PM2 配置示例

// ecosystem.config.js
module.exports = {
  apps: [
    {
      name: 'form-service',
      script: 'npm',
      args: 'start',
      cwd: './form',
      error_file: './form/logs/error.log',
      out_file: './form/logs/out.log',
    },
    // ... 另外 6 个服务
  ]
};

调试工作流对比

之前（没有 PM2）：

我：邮件服务在报错
我：[手动找日志并复制]
我：[粘贴到聊天]
Claude：让我分析一下...

现在（有 PM2）：

我：邮件服务在报错
Claude：[运行] pm2 logs email --lines 200
Claude：[读取日志] "我看到问题了 - 数据库连接超时..."
Claude：[运行] pm2 restart email
Claude："已重启服务，正在监控错误..."

天差地别。Claude 现在可以自主调试问题，不需要我做"人肉日志搬运工"。

Failed to upload image img-004-description.jpg

一个注意事项

热重载在 PM2 下不工作，所以我依然用 pnpm dev 单独运行前端。

但对于不那么频繁需要热重载的后端服务，PM2 太棒了。

Hooks 系统：#NoMessLeftBehind（零错误遗漏）

我的项目是多根目录（multi-root）的，根项目目录下有大约 8 个不同的仓库。一个前端 + 七个后端微服务和工具。

根据功能的不同，我经常在几个仓库之间来回切换做修改。

最让我抓狂的事

Claude 经常忘记在它正在编辑的仓库中运行构建命令来捕获错误。它就会留下十几个 TypeScript 错误，我没注意到。

然后几个小时后，我看到 Claude 像个好孩子一样运行构建脚本，我看到输出：

"有几个 TypeScript 错误，但它们无关，所以我们没事！"

不，我们有事，Claude。

Hook #1: 文件编辑追踪器

首先，我创建了一个 post-tool-use hook，在每次 Edit/Write/MultiEdit 操作后运行。它记录：

哪些文件被编辑了
它们属于哪个仓库
时间戳

最初，我让它在每次编辑后立即运行构建，但那太蠢了。Claude 一直在做会暂时破坏东西的编辑，然后很快修复它们。

Hook #2: 构建检查器

然后我添加了一个 Stop hook，在 Claude 完成响应时运行。它会：

读取编辑日志，找出哪些仓库被修改了
在每个受影响的仓库上运行构建脚本
检查 TypeScript 错误
如果 < 5 个错误：显示给 Claude
如果 ≥ 5 个错误：推荐启动 auto-error-resolver Agent
记录所有东西用于调试

自从实现这个系统，我再也没遇到过 Claude 留下错误让我后来发现的情况。Hook 立即捕获它们，Claude 在继续之前修复它们。

Hook #3: Prettier 格式化器

这个简单但有效。在 Claude 完成响应后，自动用 Prettier 格式化所有编辑过的文件，使用该仓库对应的 .prettierrc 配置。

不再需要手动进去编辑文件，只是为了让 Prettier 运行并产生 20 处修改，因为 Claude 上周创建那个文件时决定不加尾随逗号。

⚠️ 更新：我不再推荐这个 Hook

发布后，有个读者分享了详细数据，显示文件修改会触发 <system-reminder> 通知，可能消耗大量上下文 tokens。

在他们的案例中，Prettier 格式化导致仅 3 轮就消耗了 160k tokens，因为 system-reminders 显示文件差异。

虽然影响因项目而异（大文件和严格格式化规则是最坏情况），但我正在从我的设置中移除这个 Hook。

反正让格式化在你手动编辑文件时发生也不是什么大事，潜在的 token 成本不值得这点便利。

如果你想要自动格式化，考虑在会话之间手动运行 Prettier，而不是在 Claude 对话期间。

Hook #4: 错误处理提醒

这是我之前提到的温和哲学 Hook：

在 Claude 完成后分析编辑过的文件
检测风险模式（try-catch、async 操作、数据库调用、controllers）
如果写了风险代码，显示温和提醒
Claude 自我评估是否需要错误处理
无阻塞，无摩擦，只是保持意识

输出示例：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 错误处理自查
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️  检测到后端变更
   2 个文件已编辑

   ❓ 你在 catch 块中添加了 Sentry.captureException() 吗？
   ❓ Prisma 操作是否包裹在错误处理中？

   💡 后端最佳实践：
      - 所有错误都应该捕获到 Sentry
      - Controllers 应该继承 BaseController
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

完整的 Hook 流水线

现在每次 Claude 响应时发生的事情：

Claude 完成响应
  ↓
Hook 1: Prettier 格式化器运行 → 所有编辑文件自动格式化
  ↓
Hook 2: 构建检查器运行 → TypeScript 错误立即被捕获
  ↓
Hook 3: 错误提醒运行 → 温和的错误处理自查
  ↓
如果发现错误 → Claude 看到它们并修复
  ↓
如果错误太多 → 推荐 auto-error-resolver Agent
  ↓
结果：干净、格式化、无错误的代码

UserPromptSubmit hook 确保 Claude 在开始工作之前就加载相关技能。

零错误遗漏。太美了。

附加技巧：在 Skills 上附加脚本

从 Anthropic 的官方 GitHub skill 示例中学到的一个非常酷的模式：在技能上附加实用脚本。

例如，我的 backend-dev-guidelines 技能有一节关于测试认证路由的内容。与其只是解释认证如何工作，技能引用了一个实际的脚本：

### 测试认证路由

使用提供的 test-auth-route.js 脚本：

node scripts/test-auth-route.js http://localhost:3002/api/endpoint

脚本为你处理所有复杂的认证步骤：

从 Keycloak 获取 refresh token
用 JWT secret 签名 token
创建 cookie header
发起认证请求

当 Claude 需要测试一个路由时，它确切知道用什么脚本以及如何使用。

不再"让我创建个测试脚本"然后每次重新造轮子。

我计划扩展这个模式——在相关技能上附加更多实用脚本，这样 Claude 就有现成的工具，而不是从头生成它们。

核心洞察（我的补充）

PM2 的本质价值

PM2 不只是个进程管理器，它是可观测性基础设施。

对 AI 来说，可观测性 = 能力：

看不到日志 = 盲人修车
看到日志 = 能诊断问题
能重启服务 = 能验证修复

这就是为什么 Claude + PM2 组合这么强大。

Hooks 的哲学

这套 Hooks 系统体现了防御性编程的最佳实践：

Hook #1 (文件追踪) = 日志记录
Hook #2 (构建检查) = 持续集成
Hook #3 (格式化) = Linting（虽然后来移除了）
Hook #4 (错误提醒) = 代码审查

这不是在限制 AI，而是在给它装上安全带。

就像你不会让初级开发直接提交到 main 分支一样，你也不应该让 AI 在没有自动检查的情况下修改代码。

为什么"温和提醒"比"强制阻断"好？

注意 Hook #4 是非阻塞的——它只是提醒，不强制。

这很聪明，因为：

✅ 保持了灵活性（有时确实不需要错误处理）
✅ 避免了假阳性（不是所有 try-catch 都需要 Sentry）
✅ 培养了 Claude 的"意识"（而不是机械遵守）

好的工程文化是培养意识，不是制定无数规则。

辅助工具和技巧

SuperWhisper (Mac)

语音转文本，用于当我的手打字打累了的时候进行提示。

效果出奇地好，Claude 也能出奇地理解我絮絮叨叨的语音转文本。

Memory MCP

随着时间推移，我用这个越来越少了，因为现在 Skills 处理了大部分"记住模式"的工作。

但它对于追踪项目特定的决策和架构选择（不属于 Skills 的内容）依然有用。

BetterTouchTool

从 Cursor 复制相对 URL（用于分享代码引用）

我把 VSCode 开着，这样更容易找到我要找的文件，我可以双击 CAPS-LOCK，然后 BTT 会：

输入复制相对 URL 的快捷键
在剪贴板内容前加 @ 符号
聚焦到终端
粘贴文件路径

一气呵成。

双击热键快速聚焦应用

CMD+CMD = Claude Code
OPT+OPT = 浏览器

常用操作的自定义手势

老实说，光是不用在应用之间磕磕绊绊，BTT 的购买成本就值回票价了。

脚本解决一切

如果有什么烦人的重复任务，大概率有个脚本能搞定：

✅ 命令行工具生成模拟测试数据 - 在用 Claude Code 之前，生成模拟数据极其烦人，因为我必须向一个有大约 120 个问题的表单提交才能生成一条测试提交记录
✅ 认证测试脚本（获取 tokens、测试路由）
✅ 数据库重置和播种
✅ 迁移前的 Schema 差异检查器
✅ 开发数据库的自动备份和恢复

专业建议：当 Claude 帮你写了一个有用的脚本时，立即在 CLAUDE.md 中记录它，或者把它附加到相关的 Skill 上。未来的你会感谢过去的你。

文档（依然重要，但已演进）

我觉得除了规划，文档几乎同样重要。

我一边做一边记录所有东西，除了为每个任务或功能创建的 dev docs 之外。从系统架构到数据流图到实际的开发者文档和 APIs，仅举几例。

变化的是什么

但变化的是：文档现在与 Skills 协同工作，而不是代替它们。

Skills 包含：可复用的模式、最佳实践、操作指南
文档包含：系统架构、数据流、API 参考、集成点

例如：

"如何创建 controller" → backend-dev-guidelines Skill
"我们的工作流引擎如何工作" → 架构文档
"如何写 React 组件" → frontend-dev-guidelines Skill
"通知如何在系统中流转" → 数据流图 + notification Skill

我依然有很多文档（850+ markdown 文件），但现在它们专注于项目特定的架构，而不是重复那些由 Skills 更好服务的通用最佳实践。

你不一定要这么疯狂

你不一定要做到这么疯狂，但我强烈建议设置多层文档：

特定服务的广泛架构概览
其中包含指向其他文档的路径，这些文档深入到架构不同部分的更多细节

这会极大改善 Claude 轻松导航你代码库的能力。

提示词技巧

具体明确

当你写提示词时，你应该尽可能具体地说明你想要的结果。

再说一次，你不会让建筑工人过来给你建个新浴室，连计划都不讨论就开始干吧？

"你说得对！浴室里铺毛绒地毯可能确实不是个好主意。"

有时候你可能不知道具体细节，这没关系。

如果你不知道，问问题，让 Claude 研究并提出几个潜在方案。你甚至可以用专门的子 Agent 或用任何其他 AI 聊天界面做研究。

世界是你的牡蛎。我保证这会有回报，因为你能看着 Claude 产出的计划，更好地判断它是好、是坏、还是需要调整。

否则，你就是在盲飞，纯粹 vibe-coding。然后你会陷入这样的情况：你甚至不知道该包含什么上下文，因为你不知道哪些文件和你要修的东西相关。

不要在提示中引导

如果你想要诚实、无偏见的反馈，尽量不要在提示中引导。

如果你对 Claude 做的某事不确定，用中立的方式问，而不是说"这是好还是坏？"

Claude 倾向于告诉你它认为你想听的话，所以引导性问题会扭曲回复。

更好的做法是：只描述情况，然后询问想法或替代方案。这样，你会得到更平衡的答案。

Agents、Hooks 和 Slash Commands：三位一体

Agents 军团

我建了一支小型专业化 Agent 军队：

质量控制

code-architecture-reviewer - 审查代码的最佳实践遵守情况
build-error-resolver - 系统化修复 TypeScript 错误
refactor-planner - 创建全面的重构计划

测试与调试

auth-route-tester - 测试带认证的后端路由
auth-route-debugger - 调试 401/403 错误和路由问题
frontend-error-fixer - 诊断和修复前端错误

规划与策略

strategic-plan-architect - 创建详细的实现计划
plan-reviewer - 在实现前审查计划
documentation-architect - 创建/更新文档

专业化

frontend-ux-designer - 修复样式和 UX 问题
web-research-specialist - 在网上研究问题以及很多其他事情
reactour-walkthrough-designer - 创建 UI 导览

Agents 的关键在于给它们非常具体的角色和清晰的指令说明要返回什么。

我是痛苦地学到这一点的——之前创建的 Agents 会跑出去做天知道什么，然后回来说"我修好了！"却不告诉我它修了什么。

Hooks（前面已讲）

Hook 系统真的是把所有东西绑在一起的东西。

没有 Hooks：

❌ Skills 闲置不用
❌ 错误溜走
❌ 代码格式不一致
❌ 没有自动质量检查

有了 Hooks：

✅ Skills 自动激活
✅ 零错误遗漏
✅ 自动格式化
✅ 内置质量意识

Slash Commands

我有相当多的自定义 slash 命令，但这些是我最常用的：

规划与文档

/dev-docs - 创建全面的战略计划
/dev-docs-update - 在压缩前更新 dev docs
/create-dev-docs - 把已批准的计划转成 dev doc 文件

质量与审查

/code-review - 架构代码审查
/build-and-fix - 运行构建并修复所有错误

测试

/route-research-for-testing - 找到受影响的路由并启动测试
/test-route - 测试特定的认证路由

Slash 命令的美妙之处在于它们会展开成完整的提示词，所以你可以在一个简单命令里打包大量上下文和指令。

比每次都敲同样的指令好太多了。

结论

半年高强度使用后，我学到的东西：

必需品

✅ 规划一切 - 使用规划模式或 strategic-plan-architect
✅ Skills + Hooks - 自动激活是让 Skills 真正可靠工作的唯一方式
✅ Dev Docs 系统 - 防止 Claude 跑偏
✅ 代码审查 - 让 Claude 审查它自己的工作
✅ PM2 用于后端 - 让调试真正变得可忍受

锦上添花

专业化 Agents 处理常见任务
重复工作流的 Slash 命令
全面的文档
附加到 Skills 的实用脚本
Memory MCP 用于决策

原作者的话

我能想到的差不多就这些了。就像我说的，我只是个普通人，我很想听听其他人的技巧和窍门，以及任何批评。因为我一直在改进自己的工作流。

我只是想和其他人分享对我有效的东西，因为我在现实生活中真的没有其他人可以分享这些（我的团队非常小，他们在上 AI 火车这件事上都非常慢）。

如果你读到这里，感谢你花时间阅读。

如果你对这些东西有任何问题，或者想要更多实现细节，很乐意分享。

Hooks 和 Skills 系统尤其经历了一些试错才调对，但现在它能用了，我无法想象回到以前。

我的总结（译者补充）

读完这篇 8000+ 字的硬核指南，我有几个核心观察：

四个系统针对四个缺陷

他搭建的系统对应 Claude 的四个问题：

Claude 的问题	解决方案	数据
Skills 不自动激活	Hooks 强制触发	从"完全不用"到"每次必用"
容易失去上下文	Dev Docs 三文件系统	plan + context + tasks
忘记检查错误	自动化构建检查	6 个月零遗漏
看不到后端日志	PM2 可观测性	7 个微服务实时监控

一位使用 Claude Code 半年的开发者告诉我们："这些系统的本质是工程基础设施，不是提示词技巧。"

好的工程实践对人和 AI 都有效

他的方法是软件工程的最佳实践：

规划先行
文档分层
持续集成
代码审查
可观测性

区别在于：他把这些实践自动化了，并强制执行。

一位技术 Leader 评价："与其抱怨 AI 不靠谱，不如问自己是否遵守了基本的工程纪律。"

投入产出比

数据：

⏱️ 搭建系统：几周
📊 项目规模：10 万行 → 30 万行
⏳ 项目周期：6 个月
👤 团队规模：1 人

适用场景：

长期项目（>3 个月）
大型代码库（10 万行+）
需要保持一致性

不适用场景：

一次性脚本
原型验证
娱乐项目

可以借鉴什么

立即可用（0 成本）

Dev Docs 三文件系统（plan + context + tasks）
让 AI 审查自己的代码
规划先行，不直接开干

投入一天

整理 CLAUDE.md，区分"通用规则"和"项目特定"
为常用操作创建 Slash 命令
设置基础错误检查 Hook

投入一周

Skills 自动激活系统
PM2 后端调试方案
专业化 Agents

局限性

这套系统有边界：

初期成本高 - 不适合短期项目
维护负担重 - Skills、Hooks、Agents 都需要迭代
过度工程风险 - 小项目得不偿失
深度绑定 Claude Code

原作者的免责声明值得记住："这只是对我有效的东西，不是圣经。"

给 cc-devflow 项目的启示

我在做的 cc-devflow 项目可以融入这些点：

立即可融入

Dev Docs 三文件模板 - 每个功能自动生成 context
Hooks 错误检查 - Post-edit 记录文件，Stop 运行构建
Skills 自动激活配置 - 提供 skill-rules.json 模板

需要验证

PM2 方案的通用性 - 不是所有项目都是微服务
Token 成本 - Prettier Hook 的教训
适用边界 - 明确告诉用户小项目不需要重基础设施

核心观察

一位技术架构师看完这篇帖子后告诉我们："他问的不是'这个工具能做什么'，而是'我需要什么基础设施，才能让这个工具可靠地工作'。"

这是两种不同的思考方式。前者寄希望于工具，后者用工程方法解决问题。

工具会变，方法论长存。

#工程化 #AI协作 #技术修行