Claude Code 指南：CLAUDE.md 模板、Rules 与 Best Practices

Claude Code 为什么总是乱改代码？

Cursor Agent 为什么总喜欢过度重构？

答案很简单：不要先换模型，先写 CLAUDE.md。

本文是 VPSSpark 的 Claude Code Guide / Claude Code Tutorial 支柱页：讲清 CLAUDE.md 是什么、Claude Code Rules 与 Claude Code Best Practices 怎么写，并提供可复制粘贴的 CLAUDE.md Template。同时覆盖 Claude Code Memory、Claude Code Project Instructions、Cursor Rules、AGENTS.md 与 AI Coding Rules——属于 Evergreen 教程，不是几天就过气的 GitHub 热点摘要。

社区仓库 andrej-karpathy-skills（163k+ Star）只是把一套成熟的团队 AI Coding 规范做成了模板；下文以方法论为主，文末再附出处。需要模板可直接 跳到第六节 Copy & Paste。

一、AI Coding 最大的问题，往往不是模型能力

很多人认为：Claude Code 不够聪明、Cursor Agent 上下文不够大，所以 Claude Code 代码质量差。但从我们机房日常 AI Coding 实践来看，更常见的瓶颈是：缺少工程约束——没写清 Claude Code Rules 或 Cursor Rules。

同一个 Sonnet 档模型，在项目根目录没有 CLAUDE.md 时，和按 Claude Code Best Practices 写好 Claude Code Project Instructions 之后，产出的 diff 可能是两个质量等级。这不是换模型能单独解决的，而是 AI Coding Rules 是否在 Harness 里生效。

行业里（含 Sequoia Ascent 2026 对 Vibe Coding 与 Agentic Engineering 的区分）共识越来越清晰：前者靠对话即兴改代码，后者靠团队 AI Coding Rules、验收与长跑任务。CLAUDE.md、AGENTS.md 搜索量暴涨，正是因为大家在补「纪律层」——这和当年搜 prompt engineering、system prompt 是同一类需求。

二、GitHub 数据：Star、Fork 与 Trending 热度（可自查）

「16 万 Star」不是营销话术。截至 2026 年 6 月，multica-ai/andrej-karpathy-skills 在 GitHub API 上约为 163,000+ Star、16,700+ Fork、110+ 开放 Issue；仓库 2026-01-27 创建，数月内增速远超多数 ML 教程 repo。你可以在仓库页直接核对：

提示：上图徽章走 shields.io，Star 数会随 GitHub 更新；发布后可打开 仓库首页 与 Pulse 活跃度 自行截图存档，用于团队内部分享。

三、CLAUDE.md 是什么？和 Cursor Rules、AGENTS.md 怎么分工？

CLAUDE.md 是什么？ 在 Anthropic 体系里，它是仓库级的 Claude Code Memory 文件——每次开 session，Claude Code 都会读取其中的 Claude Code Project Instructions，相当于项目专属的 system prompt / Claude Code Rules。

和 Cursor Rules 的区别： 语义上可以相同，只是载体不同——CLAUDE.md 服务 Claude Code，.cursor/rules/*.mdc 服务 Cursor Agent。团队应维护一套 AI Coding Rules、两处分发，避免双 Harness 各写各的。

和 AGENTS.md 的关系： Codex 等工具读 AGENTS.md；很多团队把同四条原则复制进三个文件，或只维护 CLAUDE.md 再脚本同步。

GitHub 上 andrej-karpathy-skills 是流行的开源 CLAUDE.md Template（无训练代码，约 80 行 Markdown + Cursor 映射说明）。其四条原则最早由 Andrej Karpathy 在 X 上归纳，社区做成可 fork 模板——你真正要抄的是方法论，不是明星名字。

四、Claude Code 代码质量差？先看四类慢性问题

在把 Claude Code Rules 写进 CLAUDE.md 之前，先看四类常见问题——也是搜「Claude Code bad code」「Cursor rewrite everything」的人真正想解决的：

• 静默假设：「模型会替你做错假设并一路狂奔，不管理自己的困惑，不寻求澄清，不呈现权衡，该顶回去的时候不顶回去。」
• 过度工程：「特别喜欢把代码和 API 搞复杂，堆抽象，该删的死代码不删……100 行能搞定的事写出 1000 行。」
• 附带伤害：「仍会改动/删除自己没充分理解、且与任务正交的注释和代码。」
• 模糊执行：用户说「修好 bug」「加点校验」，Agent 却缺少可验证的「完成定义」，只能凭感觉 loop。

这四类问题有个共同点：不是模型「不会写语法」，而是 RL 训练与海量企业代码库塑造的默认策略——显得专业、显得周到、显得主动。对人类评审友好的 diff，对仓库维护者往往是灾难。这也是 2026 年 AI Coding 讨论从「换更强模型」转向「写清 Rules」的根本原因。

五、四条团队 AI Coding Rules：CLAUDE.md 里该写什么？

所谓「教会 AI」，在工程上更准确的说法是：在 Claude Code / Cursor 的系统提示层注入行为先验——也就是你把 Claude Code Project Instructions 写进 CLAUDE.md，把同一语义同步进 Cursor Rules，必要时再抄一份到 AGENTS.md 给 Codex 用。四条原则与上述四类问题一一对应，也是这份 Claude Code Rules 的全文骨架：

1. Think Before Coding（先想清楚再写）

针对：静默假设、隐藏困惑、缺少 tradeoff。

教给 AI 的：实现前必须显式列出假设；不确定就问；存在多种合理解读时全部摆出来，禁止悄悄选一条；发现更简单做法要说出来；说不清就停下，点名哪里糊涂。

这改的是决策顺序：从「收到 prompt → 立刻改文件」变成「收到 prompt → 对齐语义 → 再动刀」。对团队而言，收益往往是少一轮「你理解错需求了」的全量回滚。

2. Simplicity First（极简优先）

针对：过度抽象、 speculative 功能、不可能场景上的防御性代码。

教给 AI 的：只写解决当前问题所需的最小代码；不为单次使用造抽象；不加未被要求的「灵活性/可配置性」；若写了 200 行而 50 行够用，重写；自问「资深工程师会不会说这就 over-engineered 了？」

文件开头有一句诚实的 tradeoff：这些指南偏向谨慎而非速度，琐碎任务可自行判断。 也就是说，它刻意压低 Agent 的「表现欲」——这在 demo 里不够炫，在长期维护的真实仓库里却常常更省钱。

3. Surgical Changes（手术式改动）

针对：顺手重构、格式化邻居文件、删「看起来没用」的旧代码。

教给 AI 的：只碰必须碰的；不「改进」相邻注释/格式；风格跟现有代码走；发现无关死代码可以提及但不要擅自删；若自己的改动造成孤儿 import/变量，清掉自己造成的，别清历史包袱。

验收标准写得很硬：每一行变更都应能追溯到用户请求。这直接对准 AI Coding code review 里最常见的愤怒点：「我只要一个 toggle，为什么 diff 里还有 40 处引号风格？」——也是 Cursor 乱改代码 投诉的高频来源。

4. Goal-Driven Execution（目标驱动执行）

针对：模糊指令下的无效循环。

教给 AI 的：把任务改写成可验证目标——「加校验」→「先写无效输入测试，再让测试通过」；「修 bug」→「先写复现测试」；多步任务列出 brief plan，每步带 verify 检查点。

这一点利用了模型在有明确奖励信号时更会 self-loop 的特性：你给的不再是「步骤清单」，而是裁判规则，Agent 自己跑测试、自己对齐 done。这也是 Claude Code Best Practices 里最值得写进 CLAUDE.md 的一条。

六、CLAUDE.md 模板（Copy & Paste，复制即可用）

搜索 CLAUDE.md template 的人，通常只想拿走能用的文件。下面这份是 VPSSpark 机房在开源模板基础上整理的 Claude Code Rules 起点（英文正文，便于模型稳定遵循；中文团队可在同文件末尾加业务附录）。

用法： 复制下面整段 → 保存为仓库根目录 CLAUDE.md → 新开 Claude Code session 即生效。Cursor 用户可把同一语义写入 Cursor Rules；Codex 用户可复制到 AGENTS.md。

# CLAUDE.md — Project Rules (VPSSpark / community baseline)

Behavioral guidelines to reduce common LLM coding mistakes.
Merge with your project-specific instructions below.

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them — don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

## 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it — don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan with verify checkpoints per step.

---

## Project-specific (edit below)

- Test command: `npm test` (replace with yours)
- Do not modify: `generated/`, `vendor/`
- PR: keep diff minimal; no drive-by refactors

若你需要中文版规则标题、仅给团队阅读，可在文件顶部加一段中文目录，但行为约束建议保留英文，与多数 Claude Code Best Practices 一致，模型遵循更稳定。

七、实际案例：同一需求，两种 Claude Code Rules

下面是我们 VPSSpark 机房用同一提示复现的示意 diff（需求：「支付接口在金额为 0 时崩溃，只修 bug，不要重构」）。无 CLAUDE.md 时，Cursor Agent 与 Claude Code 行为类似；写入上一节模板后，diff 规模差一个数量级。

无规则（默认 Claude Code / Cursor）

# 新增文件（节选）
+ CheckoutManager.swift
+ CheckoutProtocol.swift
+ CheckoutFactory.swift
+ CheckoutConfig.swift
+ PaymentValidator.swift

# 顺带修改
~ 格式化 PaymentService.swift 全文引号
~ 删除「未使用」的 legacy 注释块

结果： 5 个文件 · 约 320 行 变更 · review 重点被淹没。

有 CLAUDE.md 模板（项目 Rules）

# PaymentService.swift
-    func charge(amount: Decimal) {
-        gateway.send(amount)
+    func charge(amount: Decimal) {
+        guard amount > 0 else { return }
+        gateway.send(amount)

结果： 1 个文件 · 约 12 行 变更 · 与需求一一对应。

八、机房实测：放进 Claude Code 一周后

我们在 VPSSpark 内部两个仓库做了对照：一个只有默认 Claude Code 配置，另一个在根目录使用第六节 CLAUDE.md Template（并同步到 Cursor Rules）。观察周期约一周，任务包括修 Bug、补测试、改文档站——真实 AI Coding 工作流，不是 benchmark。

一周后我们看到的差异：

• Diff 明显变小：平均 PR 行数下降，无关文件触碰减少；
• 无关重构减少：以前常见的「我顺便优化了一下架构」基本消失；
• Agent 更频繁提问：需求含糊时，Claude Code 会先列假设，而不是静默选一条路；
• 改代码前会简述方案：符合 Think Before Coding，review 时更容易打断错误方向。

也有 tradeoff：Claude Code 工作流 在极小任务上会变慢（多一轮确认）。我们对照组的处理是：在 CLAUDE.md 末尾保留仓库原文——「琐碎任务可自行判断」——避免 Claude Code Project Instructions 变成官僚主义。总体而言，有 Claude Code Memory 规则 的生产仓库更适合长期维护；无规则更适合一次性 Vibe Coding 脚本。

测试环境： 本次对照全部运行在 VPSSpark M4 云端 Mac 上——Claude Code 通过 tmux 长时间会话跑对照任务，避免本地笔记本合盖、休眠导致 Agent 中断；需要 xcodebuild 的仓库也在同一台云 Mac 上完成验证。若你正在搭 Agentic Engineering 流水线，「规则写进 repo + 构建跑在云端 Mac」是常见组合。

说明：这是机房内部体验，不是第三方基准测试；你的栈、语言、团队 review 习惯不同，数字会变，但diff 变干净（见上一节对比）在我们这边可复现。

九、一份 CLAUDE.md 不能解决什么

即使 Star 很高的开源模板，也不能替代你们自己的业务规则。下面这类内容仍需写进 CLAUDE.md 的 Project-specific 段或单独 rules 文件：

• 领域知识（你的支付、合规、iOS 签名流程仍要写在项目规则里）；
• 工具链技能（测试命令、部署脚本、MCP 服务器）；
• 安全沙箱或 hook（不会像 ECC（affaan-m/ECC）那样管 session、AgentShield）；
• 自动 ML 研究循环（进阶可看 autoresearch 类 program.md 范式，与日常 App 开发无关）。

团队 AI Coding Rules 约束的是「怎么改代码」，不是「改什么业务」。你也仍需能读懂 diff——否则模板只是心理安慰。

十、轻量 CLAUDE.md vs 重型 Harness（ECC 等）

对多数团队：先用第六节模板跑一周 → 再按需加 ECC hook/skill。切忌 ECC + 厚重 AGENTS.md + 全文规则叠三层——Agent 会随机挑一条遵守。

十一、Claude Code Tutorial：安装与同步 Cursor / AGENTS.md

Claude Code 用户： 根目录放好 CLAUDE.md（见 Claude Code Memory 与 Overview）。新开 session 即加载 Claude Code Project Instructions。

Cursor 用户： 同一套 AI Coding Rules 写入 .cursor/rules（Cursor Rules）。Cursor Agent 与 Claude Code 语义一致时，review 成本最低。

AGENTS.md： 给 Codex / 其他 Agent 用；与 CLAUDE.md 保持同步，避免双标。

建议工作流（Claude Code Best Practices 最小集）：

1. 复制 第六节模板，跑一周，看 drive-by refactor 是否下降；
2. 在模板底部填测试命令、禁止目录、完成定义；
3. 长跑任务放 云端 Mac + tmux，避免本机休眠断 session；
4. 需要 hooks / 安全扫描再考虑 ECC，而非第一天就全量安装。

十二、谁该用、谁可以跳过

十三、Claude Code 规范管「怎么写」；云 Mac 管「在哪跑」

CLAUDE.md 解决的是：AI 应该怎么写代码——管住 Claude Code、Cursor Agent 的默认坏习惯。它不回答：长时间任务挂在哪、Webhook 谁接、xcodebuild 在哪台 Mac 跑。

当团队把 Agent 接入长时间任务、Webhook、自动构建、自动测试，就会出现第二个问题：这些任务应该运行在哪里。 常见分工是：

• 本机：Claude Code / Cursor + CLAUDE.md，负责结对、review、小步提交；
• Linux VPS：OpenClaw Gateway 等，负责 7×24 通道、回调、Headless 队列；
• macOS 构建机：云端 Mac，负责 xcodebuild、签名与 TestFlight。

很多团队会把 Claude Code + OpenClaw + Cloud Mac 组合使用：规范写在仓库的 CLAUDE.md 与 Cursor Rules 里，执行层按任务类型分流。这不是「为了上云而上云」，而是 Agentic Engineering 从 Vibe Coding 走向自动化流水线时的自然延伸——AI Coding Rules 管写法，云主机管跑法。

十四、VPSSpark AI Coding 规范专题（Topic Cluster）

本文是专题支柱页（Pillar Page），后续会拆更多 Evergreen 教程，全部链回本篇。建议收藏本页；若你负责团队规范，可把第六节模板放进内部 Wiki。

商业转化路径对 VPSSpark 很自然：Claude Code 结对 → 长任务 / tmux → 云端 Mac。读本文的人，本身就是云 Mac 目标用户。

十五、总结

CLAUDE.md 是 2026 年 AI Coding 的超级关键词——和当年的 prompt engineering、system prompt、Cursor Rules 同类。你要的不是再换一个模型，而是把四条工程纪律写进 Claude Code Memory：先对齐、极简、手术式改动、可验证目标。

若你搜的是 CLAUDE.md template：复制第六节即可。 若你还在纠结 Claude Code 乱改代码：用第七节 diff 自测，在 VPSSpark 云 Mac 上跑一周再定稿。163k Star 只是社交证明，PR diff 干不干净 才是裁判。

延伸阅读（官方与社区来源）

以下链接均在新标签页打开，建议收藏 CLAUDE.md 原文与 Anthropic / Cursor 官方文档：