我把 Karpathy 的 AI 编码准则，改造成了一套全栈开发的"工作流宪法"，开源了

去年 Karpathy 那套 andrej-karpathy-skills 爆火的时候，我第一反应是：这不就是我这两年用 AI 写稿写码踩的坑，被一个大神一句话点破了么。

但光"抄"一份别人的准则，没意思，也没用。

我这半年干的事，是把它当底子，又扒了另外几个顶级 CLAUDE.md（GoMall 的 RIPER-5、Cloudflare 的 Monorepo 测试规范、Dan Abramov 的个人声音），融合成一套全栈开发通用的行为准则，直接开源了。

今天就在这片星球里，把这套东西的来龙去脉、以及它到底牛在哪，完整讲一遍。外面只发精简引流版，核心在这。

普通 CLAUDE.md 为什么没用

先说个扎心的事实。

你随手让 AI 写的 CLAUDE.md，十有八九是这种东西：

“请写好代码。请保持代码风格一致。请注意性能。

这是愿望清单，不是约束。AI 看完该翻车还是翻车。

我踩过最惨的一次：让 AI 给一个 Spring Boot 2.7 的项目加熔断，它给我 import 了 Spring Cloud 2024.0 的 API。编译都过不了。读者要是拿去跑，直接原地爆炸。

问题不在工具，在规则写得太虚。

Karpathy 那套之所以火，是因为它不喊口号，而是把 LLM 的坑收束成几条可执行的行为约束。我顺着这个思路，把全栈开发里所有会翻车的点，一条条敲死了。

四原则：每条都对应一个真实翻车

我把核心收成四条，每条背后都是一个我或者同行真实踩过的雷。

第一，动笔前先对齐。

AI 最常犯的错，是默默选了一种理解就开干。写错受众、写错角度，整篇返工。我现在的要求是：动手前两句话，必须能说清"我理解你要 X，面向 Y，做 Z，对吗"。说不清，就是还没对齐。

第二，专业准确、克制发挥。

这条权重最高。一个错误的 API、版本号、命令，能让整篇技术文信任归零。我的红线是：不确定就查官方文档，猜出来的"看起来对"比直接说"我不会"更有害。涉及任何技术栈，必须标版本。Spring Boot 3.x 就得配 Spring Cloud 2023.x 往后，别拿 2.7 去凑 2024.0。

第三，精准改动、最小侵入。

真实项目里，AI 最大的风险是顺手改坏无关内容。你让它把 Kafka 的 enable.auto.commit 改成 false，它顺手把整个类的命名风格从 camelCase 改成 snake_case，还重写了注释。PR 200 行，真正相关的 2 行。我的准则：每处改动都能追溯到你的请求，发现无关坏味道，提出来，不擅自改。

第四，目标驱动、可验证交付。

"帮我运营一下""加个功能"这种模糊指令，AI 最容易跑偏。必须变成可验证目标：成功标准是什么、怎么验证、跑完自检清单再交付。

四条看着简单，但每一条都来自一个能让你社死的现场。

RIPER-5：让生产代码有据可查

光有原则还不够。写代码是重活，得有工作流。

这块我直接借鉴了 GoMall 的 RIPER-5 协议，它是把"严谨 AI 工作流"收敛成五个强制阶段：

RESEARCH  → 只调研，禁止写码
INNOVATE  → 只头脑风暴方案，禁止定方案
PLAN      → 只出详尽规格和编号清单，禁止写码
EXECUTE   → 严格按计划实现，逐项勾选
REVIEW    → 逐行比对计划与实现，标记任何偏离

每轮回复开头要声明当前模式：[MODE: RESEARCH]。

我吃过跳过 PLAN 的亏。有次让 AI 给检索服务加个按标签过滤的接口，它没声明模式、没出计划，直接在 main 上改了 4 个文件、加了新依赖、顺手重构了检索逻辑。CI 挂了一片，reviewer 看不懂为什么这么改。

现在我的准则里写死：多文件或生产代码任务，必须走 RIPER-5。不在 EXECUTE 做未报告的偏离，不跳过 PLAN 直接写生产代码。轻量例外只有一种，改错别字、明显一行 fix、纯配置微调。

全栈技术栈红线：这是最硬的一块

前面那些偏方法论，这条是实打实的肌肉。

我把全栈常用的技术栈都列了准确性红线，随便举几个：

• Redis：标大版本（7.x），redis-cli 命令必须真实，FLUSHALL ASYNC 是子命令不是参数，别瞎编组合。
• Kafka 3.x：topic/partition/replica/consumer group/offset 概念准确，用真实命令行工具，区分"精确一次"和"至少一次"语义。
• **Go 1.22+**：gofmt/golangci-lint 干净，错误显式 return err，别用 panic 兜底业务逻辑，goroutine 带 context 做取消。
• **Python 3.11+**：关键处给类型标注，依赖用 venv/uv 隔离，别 pip install 污染全局。
• 前端：React/Vue/Next.js 标版本，TS 类型准确，不动别人组件的 props 接口，不引未被要求的重型依赖。
• 云原生：K8s/Docker 的 yaml 必须真实可 apply，不编造不存在的字段。

这活儿没捷径，就是一条条啃下来的。但它让 AI 产出的代码，至少在我熟悉的栈里，不会一跑就崩。

测试硬规则：抄 Cloudflare 的

Monorepo 里最怕 AI 跨项目乱改。这块我直接搬了 Cloudflare Workers SDK 的 AGENTS.md 做法：

声称完成前，本地把质量门跑完（lint + type-check + format + 相关测试），不依赖 CI 兜底。真实行为优于 mock。用 vitest 的话，expect 从 test context 取，别从包里 import。

还有一条铁律：不直推 main。从 main 拉分支改，提交信息像务实资深工程师——casual、说清做了什么加为什么，别来"leveraging cutting-edge methodologies"那种机器人腔。

个人声音：拒绝机器人腔

最后这块，是 Dan Abramov（Overreacted.io）给我的启发。

他的 CLAUDE.md 里有一句我特别喜欢：Don't embarrass me with robot speak, marketing buzzwords, or vague fluff. You're not writing a fucking pamphlet.

翻译过来就一句话：别用机器人腔、营销话术、空话。像个人一样说话。

我把它收进准则：承认不确定性，不确定就查或标"未实测"，不装懂；提交信息讲清"做了什么加为什么"，不虚张声势。

三格式同源，丢进项目就能用

这套东西我做了三个格式，内容完全同源，只是面向的工具不同：

你直接 cat CLAUDE.md >> 你的项目/CLAUDE.md 就生效。也可以整个目录软链成 skill，开箱即用。

我还附了 13 个翻车场景的 before/after（含 RIPER-5 跳步、Go 不过 lint、Python 污染全局、前端乱改 props、提交信息机器人腔、Monorepo 跨项目乱改），这部分是准则"有嚼头"的来源，也是我拿去给团队做 AI 协作培训的底料。

开源了，拿去用

我把它整理成了一个独立的开源仓库 agent-guidelines，MIT 协议，随便用、随便改。

为什么开源？两个原因。

一是这东西本来就是从大神们公开的 CLAUDE.md 里长出来的，回馈社区顺理成章。Karpathy 的四原则、GoMall 的 RIPER-5、Cloudflare 的测试规范、Abramov 的个人声音，都是公开的智慧，我只是做了全栈领域化的缝合和校验。

二是我想验证一件事：一个后端开发者，能不能把"大神踩过的坑"沉淀成一套能直接抄的准则，而不是停留在收藏夹里吃灰。 现在看，能。

做技术号这么多年，我越来越觉得：工具不重要，用法才重要。同一份 AI，有人用出玩具，有人用出生产线。差的那层，往往就是这么一份"工作流宪法"。

这套准则现在是我的生产线底座。你也可以用。Github 开源地址 https://github.com/MageByte-Zero/agent-guidelines