30know

项目手册经验分享

在上章这些更多算是官方层面的介绍,接下来这部分就比较主观了,是我自己用 AI 写这个网站的过程中,慢慢总结出来的一些经验。

先说明一下,我自己本身也不会代码,所以这里不会讲什么特别复杂的工程规范。我更关心的问题其实一直都很简单:对于一个不会代码、主要靠 AI 写项目的人,怎么尽可能避免项目越写越乱?

1. 先看,再改

这是我现在最重要的一条:没有看清楚现在的代码,就不要直接开始写。

AI 很容易犯一个问题,比如你问它:“给这里加一个收藏功能。”它可能不会先仔细找项目里面有没有收藏相关的逻辑,而是直接回一句:“好的,我来帮你实现。”然后啪一下又给你重新写一套。

所以我现在会明确要求它:修改之前,先找到这个功能现在在哪里、相关文件有哪些、项目里有没有已经存在的实现,然后再开始修改。尤其是长期项目,这一点很重要,因为项目越大,AI 越不能靠猜。

可以直接给 AI 加一句:

修改之前,先找到这个功能现在在哪里、相关文件有哪些、项目里有没有已经存在的实现,然后再开始修改。

2. 能改旧的,就不要重新造一个

这一条和上面其实是一套东西。AI 特别喜欢“重新写一个”,原本项目里面已经有一个 Header,不好改?那就再来一个 NewHeader,后面又要调整,它可能再来一个 HeaderV2,最后项目里面同时放着三套差不多的东西。

所以我的原则一直都是:优先复用已有组件、已有函数、已有逻辑。 真的需要重新做,也要先讲清楚为什么原来的不能继续用,而不是因为重新写一个更省事,就直接再造一套。

对于小白来说,这一点特别重要,因为我们根本没有能力自己进去清理这些技术债。AI 今天多造一个文件可能没什么感觉,但是半年以后,这些东西都会变成你修改项目时候的负担。

可以直接告诉 AI:

优先修改和复用项目里已经存在的组件、函数和逻辑。需要重新实现时,先确认原来的方案为什么不能继续使用,不要为了方便直接创造第二套相同功能。

3. 小改就是小改,不要顺手装修全家

这个也是我踩过很多次的坑。比如我只是说一句:“这个卡片的间距再小一点。”结果 AI 改完以后告诉我:“我顺便优化了卡片组件结构、统一了样式逻辑,并重构了部分 CSS。”

听起来很专业,但我的反应通常都是:我只是想改个间距啊。

所以我现在会明确要求:只修改和当前需求直接相关的东西,不要顺手优化旁边的代码。如果发现旁边确实有问题,可以告诉我,但是先别动。

我后来看到一个说法,我觉得特别适合形容这件事,叫 Surgical Changes——外科手术式修改。哪里有问题,就动哪里,不要开个小刀最后做成全身大手术。

我自己的规则大概就是:

只修改与当前需求直接相关的内容。不要顺手重构、优化或删除无关代码;如果发现其他问题,可以告诉我,但未经要求不要一起修改。

4. 大需求不要一口气生成完

这个也是 Vibe Coding 特别容易发生的问题。比如你跟 AI 说:“我想做一个社区。”它很可能马上回答:“没问题,我来帮你完成。”然后数据库、登录、帖子、评论、通知一口气全部开始写。

这个其实很危险,因为一旦方向错了,前面写得越多,后面需要推倒的东西就越多。所以现在遇到比较大的功能,我更喜欢让 AI 先拆,再做

比如做一个社区,可以先把信息结构想清楚,再做最基础的帖子展示,然后做发布、评论,最后才考虑通知、推荐之类的东西。每做完一块都可以单独检查,这样哪怕中间发现方向不对,损失也比较小。

所以我现在会直接把这条写进项目规则:

大需求必须拆成可以独立验证的小步骤,一次只推进一个明确的部分。不要一次性生成整个模块,然后告诉我“已经做完”。

对了,记得大需求的任务规划可以先用顶级的模型来执行写出待执行的内容,然后再切换成性价比高的模型执行

5. 大事让我拍板,小事你直接做

这个是我后来特别在意的一条。我不希望 AI 什么事情都问我,改一个颜色也问“是否确认修改”,改一句文字也问“是否继续”,这样其实非常影响 Vibe Coding 的效率。

但反过来,我也不希望它在真正重要的事情上自己做决定。比如要不要换框架、要不要新增依赖、数据库结构怎么改、登录权限怎么设计、要不要删除数据、要不要大改整个页面架构,这些事情一旦选错,影响可能是长期的。

所以我现在的规则非常简单:小事直接做,大事先说。

而且大事不是只问一句“是否确认”,而是先把为什么、风险和替代方案讲明白。我自己现在比较喜欢让 AI 按下面这个格式来:

结论:建议 / 不建议 / 可以做,但有条件

真问题:现在真正需要解决的问题是什么?

理由:为什么建议这样做?

风险:这样做以后可能有什么代价?

可选替代:还有没有更简单、更稳的方式?

请拍板:你选 A / B / 还是改方向?

改文案、改颜色、修一个已经明确的小 Bug,直接做;新功能、数据库、技术选型、大范围重构,再先分析、讲风险、让我确认。

6. 文件不要无限往里面堆

这个也是我自己项目做久以后越来越明显的问题。AI 很容易不停地往原来的文件继续加,500 行、800 行、1000 行、2000 行,一直往里面堆。

但是这里也不是说一个文件一超过 500 行就一定有问题。我现在更关心的是:这个文件是不是已经在同时负责很多件事情?

如果一个文件又负责页面、又负责接口、又负责数据处理、又塞了一堆组件,那后面每改一次东西都会越来越危险。所以我自己现在会给 AI 一个软提醒:源码文件到了大概 500~800 行的时候,就检查一下是不是已经出现了职责混杂。

如果是,就考虑拆;如果它本来就是一个很长的配置表、数据文件,或者虽然很长但是只负责一件事情,那也没必要为了“500 行”强行拆成好几个文件。

所以这个数字只是提醒,不是什么硬规则,重点不是文件到底有多少行,而是以后还改不改得动。

7. 项目越大,规则越要分层

刚开始做一个小网站的时候,其实一份 AGENTS.md 就完全够了。但是项目越做越大,如果还是什么东西都继续往里面塞,项目手册本身最后也会变成屎山。

所以我现在更倾向于把信息分层。比如 AGENTS.md 只负责全项目都应该遵守的规则;另外准备一份 CONTEXT.md,告诉 AI 这个项目现在是什么结构、重要入口在哪里;如果某个模块特别复杂,再给这个模块单独放一份说明,只记录它自己的特殊规则和踩过的坑。

这些文件叫什么其实不是重点,核心思想就是:总规则放总规则,局部信息放局部,不要什么东西都往一个文件里面塞。

同样也不要每次 AI 开工,都让它读几十页历史记录。真正长期有效、每次工作都会影响 AI 行为的内容,才值得一直放在项目手册里。

总结

如果你不想研究上面这么多东西,其实可以直接把下面这一段复制给你的编程 AI,然后让它结合你现在的项目,整理进自己的 AGENTS.mdCLAUDE.md 或其他项目规则里面:

请结合当前项目,把下面这些原则整理进项目手册。
不要机械照抄,如果项目已经有对应规则就合并,保持文档精简,若不适用项目的也不用强行运行:

1. 修改前先阅读相关代码和项目结构,不要凭猜测直接生成。
2. 优先复用已有组件、函数和逻辑,不要重复造轮子。
3. 尽量做最小范围修改,不要顺手重构与当前需求无关的代码。
4. 大需求拆成可以独立验证的小步骤,不要一次性生成整个模块。
5. 不确定项目实现时先搜索代码;不确定框架、API、第三方服务时优先查官方文档,不要编造。
6. 普通、低风险、容易撤销的小修改可以直接执行;涉及架构、数据库、依赖、权限、删除数据等重大决定时,先说明理由、风险和替代方案,让用户拍板。
7. 能通过代码、构建、接口、脚本或测试自行验证的内容,由 AI 自己完成验证。没有验证证据,不要直接说“已经完成”。
8. 文件明显过大或同时承担多个职责时,主动考虑拆分。500~800 行可以作为提醒线,但不要为了行数机械拆文件。
9. 未经明确允许,不要修改生产数据、提交密钥、git push、force push,或执行其他不可逆操作。
10. 项目规则保持精简,只记录长期有效、真正会影响后续开发行为的信息;局部规则放到对应模块,不要全部塞进根目录。

如果你发现这些规则和当前项目已有规则冲突,请先告诉我,不要直接覆盖。