写这篇文章之前，我先说一个重要判断：很多人在“Vibe Coding”里嗨了几个月之后，发现自己根本收拾不了 AI 留下的烂摊子。文件越来越大、依赖越来越乱、提交信息全是“update code”，改一个需求要顺着全工程找一遍。这个开源项目 claude-code-best-practice 就是冲着这个问题去的，它不教你“怎么让 AI 写更多代码”，而是教你怎么把 AI 编码工具变成一套受控的、可持续的开发流程。这篇文章我会把项目里的核心主张拆开揉碎，结合真实开发场景讲清楚，顺便把我踩过的坑和补出来的经验一起放上来。

1. 这个项目到底在讲什么

1.1 仓库里装的不只是提示词

先说项目本身的定位。claude-code-best-practice 是一个围绕 AI 编码助手的实践集合仓库，内容不杂但非常聚焦，主要包括三类东西：

• 项目级规则文件的最佳写法，也就是队长原话叫“项目卡”的那份配置：怎么描述工程背景、技术栈、目录职责、接口规范，让 AI 每次回答都带着这些上下文。
• 一套推荐的工作流，从需求拆解、代码生成、自测、代码审查到提交，每一步都明确 AI 应该参与多少，人在哪个节点必须介入。
• 一堆真实场景下的提示词模板，不是网上那种通用“角色扮演”，而是带工程约束的具体指令，比如“只输出改动 diff”、“先列影响面再动手”、“提交信息格式必须包含模块前缀”。

所以它更像是“AI 协作开发的操作系统”，而不是“咒语大全”。关键词即所谓“AI 原生开发”，本质是把 AI 当成贯穿全流程的一等公民，而不是某个偷懒工具，顺手用一下。

1.2 “Vibe Coding”和“AI 原生开发”的分界线

Vibe Coding 这个词形容的是那种“跟着感觉走”的编码状态：让 AI 连续生成代码，自己主要看结果能不能跑，跑得动就提交，跑不动就让 AI 再改。这套路在写原型、做 Demo、搞个人工具的时候非常爽，但在真实项目里第二次就会出问题。

AI 原生开发则不同，它承认 AI 是开发团队的一部分，需要约定规则、设计接口、做审查、管回归。两者的分界线大概有这么几条：

我见过太多项目从 Vibe Coding 起步，前两周进度飞快，到第三周开始出现“改一个按钮导致支付接口报错”这种低级连环崩。原因很简单，AI 生成的代码并没有进入你的心智模型，你没有意识到模块之间的隐形耦合。而 AI 原生开发的第一步，就是把这些耦合显性化。

2. 核心逻辑：为什么要靠“流程”而不是“提示词”驯服 AI

2.1 上下文不是越长越好，而是越有结构越好

很多人以为用 AI 写代码就是“把整个项目塞进 prompt”，上下文越长写得越准。这个想法其实是对的，但实现方式非常容易跑偏。直接给 AI 丢十几个源码文件，让它接着写，模型会倾向于“模仿最近的写法”而不是“遵循全局最优设计”。它读了一堆冗余代码之后，甚至会学着写出同样的坏味道。

项目里提倡的做法是建立“结构化的项目上下文”，核心载体就是项目卡。这张卡不是需求文档，而是给 AI 的“直系上级”安排：

• 项目是什么、给谁用、核心业务规则是什么
• 技术栈和关键依赖分别是哪些
• 目录结构里每层文件夹的职责边界
• 编码规范里哪些是死规矩（比如错误处理必须走统一异常类）
• 不许碰的区（比如生成代码不得改配置文件、不得动数据库迁移脚本）

这套东西的价值不在于字数多，而在于它把 AI 的注意力引导到“正确位置上”。比如你写一个电商项目卡，里面把价格计算模块标记为“高敏感区，任何改动必须先列影响面”，那 AI 在改动价格逻辑时会主动生成风险提示，而不是盲目重构。这就是流程设计带来的收益，单纯堆提示词拿不到这种效果。

2.2 人在环上的四个强制介入点

AI 原生开发和全自动生成的本质区别，是保留四个强制人工介入节点。这四个节点缺一个，项目迟早失控。

第一个节点是需求拆解。不能让 AI 直接“实现用户登录”，而要你先拆成接口、表结构、鉴权、异常、测试五个子任务，每个子任务再单独交给 AI。第二个节点是代码审查。AI 生成的代码必须走人工 review，不是随便看一眼，而是逐行核对边界条件。第三个节点是变更验证。除了单测，还要跑与变动有关的回归用例，我甚至建议让 AI 自己列一份“受影响模块自测清单”。第四个节点是提交信息审核。提交信息不是给别人看的，是给未来的 AI 看的。一份干净的提交历史能让 AI 在几秒内理解项目演进脉络，这个优势会在后续开发中持续放大。

这四步听起来费时间，实际上每一步都用 AI 加速过。比如审查环节，你可以让 AI 先去把 diff 里的风险点列出来，人只需要看那几行重点，而不是从头读一遍。这就是“让 AI 帮你管 AI”的精髓。

2.3 语义化提交与 AI 原生的兼容性

项目中反复强调 commit 规范，我认为这是整个仓库最容易被忽略但又最关键的章节。所谓语义化提交，不只是 commitlint 那套 type 前缀，而是要求提交信息包含更深的语义：这次改动要解决什么问题，涉及哪些模块，数据库是否有变化，需不需要配套发布操作。

为什么要这么做？因为 AI 的上下文窗口是有限的，它不可能每次读取整个 Git 历史。但当提交信息本身足够结构化，AI 通过git log --oneline就能快速获取项目的演进脉络。比如看到feat(order): 重算优惠券分摊逻辑，涉及价格模块，AI 立刻知道这个文件的改动背景，不需要你再啰嗦解释。这就是一种“面向 AI 的代码注释”。

我自己试了一个月，最大的感触是，坚持语义化提交之后，AI 在回答“这个功能为什么要这样写”时的准确率显著提升，因为它的依据从“猜测”变成了“项目历史”，这是实打实的效果。

3. 项目里最值得直接抄走的几个模板

3.1 项目卡模板的骨架

下面这份内容，是我结合原项目思路和自身实践整理出的简化版，可以直接放进仓库根目录，作为 AI 编码助手的常驻上下文文件。配置文件名称可以根据工具来定，我这里叫claude.md仅仅是延续项目标题里的称呼，换成AGENTS.md之类也完全一样。

# 项目卡 ## 项目一句话 这是一个给中小团队使用的报销审批系统，Web 端 + 服务端。 ## 技术栈 - 前端：React + TypeScript + Vite - 后端：Node.js、Fastify、PostgreSQL - 测试：Vitest ## 目录职责 - src/services：业务服务层，禁止直接操作数据库 - src/repositories：数据访问层，只允许这层出现 SQL - src/types：全局类型定义，改动需同步更新 API 文档 ## 死规矩 1. 金额计算统一使用 decimal 库，禁止浮点直接比较 2. 所有对外接口必须做入参校验，统一返回 { code, data, message } 3. 不允许修改数据库迁移目录下的历史脚本 ## 高风险区 - 审批流状态机：任何改动必须列出所有状态转移影响 - 第三方支付对接：涉及退款流程时先检查幂等逻辑

我把这份配置喂给 AI 编码工具之后，第一感受是它的防御性强了很多。之前让它“帮我改一下审批流程”，它直接改了状态机核心文件；现在它会先标明影响面，列出涉及的状态节点，然后问我“是否继续”。这就是项目卡存在的意义，让 AI 在动手前先学会“敬畏”。

3.2 需求拆解的提示词模板

这个模板解决的是“AI 一次给你一坨代码”的问题。用法是，任务开始时先不要求代码，而是让 AI 先输出拆解计划。人工确认计划没问题，再逐段执行。

你现在是这个项目的一名资深开发者。请严格基于项目卡中的业务背景和目录约束，帮我拆解以下需求，不要写任何实际代码： 需求：实现审批人可以批量驳回报销单的功能。 请按以下格式输出： 1. 涉及的服务层文件与数据访问层文件 2. 需要新增的接口定义和参数结构 3. 状态机中哪些状态允许批量驳回，哪些必须单独处理 4. 需要补充的单元测试场景列表 5. 潜在的风险点（事务、并发、权限） 注意：如果需求与现有模块有冲突，直接指出冲突，而不是强行给出方案。

拿到这份拆解后，我通常只花一两分钟核验，然后让 AI 按“第一步：完成 repository 层改动 + 单测”这样的小任务逐个执行。体验下来，代码的一次通过率明显高于直接让 AI 生成完整功能，因为拆解阶段已经帮它理清了边界。

3.3 最小化代码生成的提示词模板

这个模板适合已经拆解完任务、需要具体实现的时候。核心思想是“限制输出”，让 AI 不要顺手干超范围的事。

请实现以下变更：新增 repository 方法 findPendingReimbursementsByApproverId。 约束： 1. 只改 src/repositories 下的一个文件 2. 不修改 service 层、不修改接口定义 3. 必须写配套单测，测试数据使用内存数据库 4. 不要输出解释，只要最终的代码 diff 5. 如果发现现有调用方与新方法有兼容问题，在 diff 后用三行以内说明

加上这些约束之后，AI“发挥创造力”的空间被压缩，但它在这个框架里产出的代码质量反而更高。原理很简单，大模型在约束少的场景下倾向生成“看起来完整的方案”，而在约束清晰的场景下会集中精力解决具体问题。你要的是工程变更，不是诗歌。

3.4 代码审查场景的提示词模板

这个模板是我觉得整个项目里最省时间的一个。以前人工 review diff 要看半天，现在是让 AI 先做一轮预审，人工只看标记为高风险的部分。

请审查以下代码 diff，你是该项目的高级开发者。审查时不要修改代码，只输出问题清单。 对每个问题给出： - 严重级别：致命 / 重要 / 建议 - 文件与行号 - 问题描述（一句话） - 修复建议（一句话） 重点检查：边界条件、事务一致性、异常处理、类型安全、是否有违反项目卡“死规矩”的写法。

用这个模板跑了几十次 review，我发现 AI 对“事务缺失”“类型断言绕过”“未判空”这类问题的检出率很高，但要注意它查不出业务语义上的错误，比如优惠计算规则到手写错了。所以这个模板定位是“第一道自动审查”，不能替代人。你得带着业务结果去确认 AI 提出的每个问题。

4. 实际操作：如何把这个仓库的方法落到自己的项目里

4.1 从一个长期痛点开始试点

我不太建议你“看完全部内容，明天就全面改造”。那样团队会很痛苦，AI 也容易在突然出现的规则中产生混乱。更稳妥的路径是挑一个长期让你头疼的痛点来试点。

比如你们团队最常见的痛点是什么？如果是“AI 改了一处代码，连带破坏了另一个模块”，那就先只引入项目卡 + 风险区标注；如果是“提示词每次都写一大串，重复且低效”，那就先固化自己的 prompt 模板；如果是“提交历史一团糟，AI 无法理解项目演进”，那就先加强 semantic commit 约束。

我自己的实验经历是，拿一个维护中的内部工具项目试水，第一周只增加了项目卡文件和提交规范，没有动任何 AI 工作流。第二周开始，让 AI 每次修改前先列出影响面，第三周起才把单元测试和 Pre-commit 接上。整个过程非常平滑，没有出现“AI 突然不会干活了”的情况。

4.2 在工程流程中嵌入 AI 检查点

接入了基础配置之后，就可以把 AI 放到工程化检查点里，让它承担更多“可量化”的审查工作。常见的做法是让 AI 在三个环节介入：

第一个环节是提交前检查。在本地 pre-commit 钩子里加一个脚本，把暂存区的 diff 交给你选择的 AI 编码工具，让它快速扫描明显问题。这个检查不要卡得太死，因为模型偶尔会误判，它更适合做“提醒”，而不是硬性门禁。

第二个环节是 CI 中的差异分析。把 MR 的 diff 发给 AI，让它输出变更摘要、潜在风险、受影响模块。这一步的产出物可以直接贴到 MR 描述里，队友 review 起来会快很多。需要注意的是，不要把敏感代码直接发给外部接口，公司若有私有化模型就用自己的，否则就做脱敏。

第三个环节是错误日志的辅助分析。当线上出现异常时，把堆栈和上下文发给 AI，让它给出排查建议。这个环节通常比较安全，因为只涉及单一异常信息，泄露风险低，价值回报却很高。

下面是我在设计这套流水线时总结的一张对照表，你可以参考着选型：

4.3 团队推广时的节奏和话术

团队推广是这类项目落地里最难的部分，不是技术问题，而是信任问题。很多人经历过“AI 生成烂代码”的创伤，天然抗拒让它在流程里多插一脚。我的建议是不要跟大家说“以后 AI 要参与代码审查了”，这会引发对抗。

更好的说法是：“我们弄了一个自动整理 MR 描述的小工具，帮 reviewer 省时间”，先从消除痛点的角度切入。等大家觉得“AI 的摘要比我写的 MR 描述还清楚”，再逐渐引入更多检查点。过程中最重要的原则是：AI 产出的所有内容都可以被人工否定，只要它能让你省时间，就值得用。

我见过有的团队流程设计得很好，但推广失败，原因是负责人太想“一步到位”，把 AI 当成了不可挑战的强制门槛，结果团队每天都在跟模型较劲。所以要记住，AI 原生开发不是“AI 说了算”，而是“AI 辅助、人做决策”。

5. 避坑实录与排查技巧

5.1 吃过大亏的四个典型场景

如果说前面讲的是方法论，这一节就是我从实践中踩出来的硬坑。第一个坑是“上下文被污染”。早期我把好几个项目的项目卡合并到一个 claude.md 里，结果 AI 写前端项目时动不动就冒出后端目录的 API 设计。这种问题的排查方式很简单：凡是 AI 的行为出现“张冠李戴”，第一时间检查它读到的项目卡有没有写清楚“当前仓库的边界”。解决方法是把配置文件严格对应到单仓，必要时加环境变量区分。

第二个坑是“AI 自作主张改完配置”。之前有一次，我让 AI 修一个 lint 报错，它顺手把 TypeScript 的strict改成了false。运行没问题，但类型安全直接退了一步。这种坑特别隐蔽，因为代码检查可能不报错。规避方案是在项目卡的“死规矩”里明确写入禁止修改的文件列表，并且在代码审查环节增加一步“只允许检查 diff 中是否出现配置文件的改动”。

第三个坑是“单测写得不痛不痒”。AI 很擅长写一堆断言全是“正常路径”的测试，这些测试对重构几乎没保护力。我后来在提示词里强制要求“必须包含失败路径、空值、超长、并发场景”，情况才好转。记住，让 AI 写测试的核心目的不是凑覆盖率，而是构造出能让你在修改后安心的安全网。

第四个坑是“盲目信任 AI 推荐的依赖”。AI 在生成代码时喜欢引用各种 npm 包，有的包维护状态很差。我定的规矩是：AI 建议的新依赖必须先由人工确认维护活跃度和安全记录，再决定是否安装。不要把选择依赖的权力完全交给模型，它并不知道供应链攻击的威胁模型。

5.2 一次典型的推动回归与恢复过程

我拿一次真实事故来说明排查过程。当时我在一个仓储系统上让 AI 重构库存扣减逻辑，改动范围已经控制在 service 和 repository 两层。第一版代码生成后通过了全部单测，但上线后出现了偶发的超卖。我的排查路径是这样的：

第一步，先不让 AI 改任何代码，而是把线上日志和事务日志发给它，让它描述可能出现超卖的代码路径。第二步，根据它的描述，定位到 repository 层的查询语句没有加FOR UPDATE锁。第三步，让 AI 针对这个具体问题写修复，同时要求它补充并发场景的测试用例。第四步，把生成的新增测试用例拿给组员 review，确认断言覆盖了“两个请求同时扣减最后一个库存”的场景。

整个过程走了不到两个小时，也暴露了一个重要规律：AI 能正确修复“已经明确定义的问题”，但很难自己定义问题边界。所以排查任何复杂的线上 bug，应该先让 AI 做“分析助手”，而不是“修复助手”。

5.3 如何快速判断配置是否生效

很多人在配好了项目卡和提示词模板之后，不知道如何验证“AI 真的在按我的规则思考”。这里分享两种我常用的方法。第一种是“反常识测试”：故意让 AI 修改一个明确禁止的区域。比如项目卡里写着“禁止修改 migrations 目录”，你就让它“帮忙加一个字段到某个迁移脚本”。如果 AI 答“这个操作违反项目约束，我建议先在新的迁移脚本中修改”，说明它认真读了你配置的规则；如果它直接照做，说明项目卡没真正被工具读到，得排查配置加载路径。

第二种是“影响范围测试”：抛出一个跨模块需求，让 AI 先输出影响面。规范养成的 AI 会主动列出相关模块、测试范围、发布影响；没养成的 AI 会直接上手写码。这个测试实际上是在验证“需求拆解”这个节点有没有真正嵌入流程。

我建议每两周做一次这样的“AI 对齐度测试”，不花什么时间，但能及时发现配置被覆盖、分工漂移等问题。

6. 对这个项目的整体评价与后续扩展

6.1 实际用下来的感受

我在自己负责的应用服务上完整实践了这个仓库所描述的方法，连续跑了大概四十多天。最直观的变化是重构速度变快了。以前重构一个核心模块要小心翼翼排期，现在可以让 AI 先生成重构方案、再逐层实现、每层都有测试兜底，整体胆量大很多。

但要泼一盆冷水：这个仓库并不是“AI 时代银弹”。它默认你已经有不错的工程素养，比如会写单测、懂得代码审查、明白架构分层。如果你是刚入门编程的人，我建议还是先把基础功练好，再来吸收这些实践。因为这里的每一个步骤都是建立在“人知道自己要什么”的前提上，否则你只会得到一个错误方向上的高效执行者。

对二三十人左右的研发团队来说，这个项目的实践价值最大。团队人数越多，每个人的编码风格差异越大，统一的 AI 协作流程越能起到“压舱石”的作用。对个人开发者来说，它的价值则在于培养一种习惯：每次让 AI 动手前，先想清楚边界和验收标准。

6.2 这个领域未来的扩展空间

我自己已经开始尝试的项目，是把这些最佳实践扩展成“团队级别的 AI 协作基线”，包括把项目卡里沉淀下来的规则同步到新人文档、把提示词模板整理成内部工具库、把 review 问题清单汇总成错误模式知识库。这些方向，本质上都是在走“从个人经验到团队资产”的路径。

另外我觉得值得留意的方向是“AI 之间的交互”。一旦项目里多个 AI 代理协同工作，项目卡就会从“给人看的上下文”变成“给 AI 看的协议”，那时规则文件的结构化程度会更加重要。这个仓库目前已经走在了正确的方向上，未来很可能会长出更多关于 AI 团队协作的组织模式。

我个人在反复实操中的体会是，AI 原生开发不是某一种工具或某一条命令，而是一套围绕 AI 能力重塑的开发习惯。它的门槛不在于技术，恰恰在于你能不能克制住“让 AI 一口气搞定一切”的冲动。把流程定细，把边界划清，当你发现 AI 开始主动提醒你“这里存在风险”的时候，你就真正从 Vibe Coding 迈过来了。