CLAUDE.md 终极最佳实践指南

这篇文章不仅涵盖了如何配置技术栈，更深入探讨了如何通过"行为契约"来约束 AI，防止其产生幻觉、过度设计或破坏现有代码。

🚀 CLAUDE.md 终极最佳实践指南：从配置到行为约束

在 AI 辅助编程时代，CLAUDE.md 不再仅仅是一个配置文件，它是你与 AI 之间的工程契约 。一个优秀的 CLAUDE.md 能将 AI 从一个"需要时刻盯着的实习生"转变为"可信赖的资深工程师"。

结合业界通用的工程实践与 Andrej Karpathy 提出的 LLM 行为心理学洞察，我们总结了以下构建高效 CLAUDE.md 的核心法则。

🧠 第一部分：核心设计哲学

在编写具体规则前，必须明确 CLAUDE.md 的三个核心定位：

行为契约，而非技术文档 ：不要在这里写"项目背景"或"团队介绍"。只写直接影响代码生成的指令。
防御性编程 ：LLM 天生倾向于"过度自信"和"过度设计"。你的配置文件必须包含刹车机制（如"禁止猜测"、"禁止随意重构"）。
最小有效原则：规则越少，执行力越强。每一条规则都应通过"删除它，AI 会犯错吗？"的测试。

🛠️ 第二部分：结构化最佳实践 (工程层)

一个标准的 CLAUDE.md 应包含以下四个核心模块，以确保技术执行的一致性。

1. 不可协商的硬约束

定义项目的技术底线，防止 AI 使用错误的工具或破坏安全边界。

包管理器 ：明确指定 pnpm、npm 或 yarn。
安全红线 ：明确禁止修改的目录（如 /legacy）或禁止硬编码的密钥。
验证闭环 ：规定任何修改必须通过的测试命令（如 pnpm test）。

2. 关键风格指南

仅记录与默认规范不同 或容易被 AI 忽略的风格。

TypeScript ：例如"优先使用 type 而非 interface"。
React：例如"组件必须使用 PascalCase 命名"。
CSS：例如"禁止使用内联样式，必须使用 Tailwind"。

3. 项目陷阱

列出那些 AI 无法通过阅读代码推断出的"隐形知识"。

环境依赖：例如"API 测试需要本地 Redis 运行在 6379 端口"。
遗留逻辑 ：例如"/auth 模块依赖旧的 session.js，修改前必须阅读 docs/auth-flow.md"。

4. 精确工作流

提供可复制粘贴的命令，而非模糊的描述。

开发：pnpm dev
测试：pnpm test --filter user

🛑 第三部分：Karpathy 行为约束 (心理层)

这是基于 Andrej Karpathy 对 LLM 缺陷的深刻观察而总结的高级行为准则 。将其加入 CLAUDE.md，可以显著减少 AI 的"幻觉"和"乱改代码"行为。

1. 谋定而后动

解决痛点：AI 经常在没有理解需求时就开始写代码，导致方向错误。

规则：如果需求模糊，必须先提问，禁止盲目猜测。
规则：在编码前，简要列出实现方案供用户确认。

2. 极简主义

解决痛点：AI 倾向于过度设计，引入不必要的抽象层。

规则：拒绝"未来可能的扩展"。如果代码只被调用一次，不要封装成通用库。
规则：能用 20 行解决绝不用 50 行。

3. 手术式修改

解决痛点：AI 喜欢"顺手"格式化或重构无关代码，引入潜在 Bug。

规则：只修改与当前任务直接相关的代码行。
规则：保持周围代码的原样，即使它们的风格很烂。

4. 目标驱动与验证

解决痛点：AI 经常声称"修好了"，但实际上并没有验证。

规则：对于 Bug 修复，先写一个能复现问题的测试，再修复代码。
规则：提交前必须运行验证命令，确保没有破坏现有功能。

📝 第四部分：最佳实践模板 (可直接复用)

你可以将以下内容保存为项目根目录下的 CLAUDE.md。

markdown 复制代码

# Project Guidelines (Engineering + Karpathy Principles)

## 1. Non-negotiables (硬约束)
- **包管理**：必须使用 `pnpm`，禁止使用 npm/yarn。
- **代码安全**：
  - **禁止修改 `/legacy` 目录**（除非明确要求）。
  - 修改前**必须运行 `git diff`** 确认改动范围，仅允许改动任务直接相关的行。
- **验证闭环**：任何代码变更**必须通过 `pnpm test`**。

## 2. Code Style (关键风格)
- **TypeScript**：优先使用 `type`，仅在需继承时使用 `interface`。
- **React**：组件名 PascalCase，禁止新增抽象层，单次调用代码 ≤ 50 行。
- **CSS**：使用 Tailwind，禁止内联样式。

## 3. Karpathy Behavior Principles (行为约束)
- **Think Before Coding**：需求模糊时**必须提问**，不要猜测。
- **Simplicity First**：拒绝过度设计。不要为了"未来扩展"添加抽象层。
- **Surgical Changes**：**手术式修改**。不要"顺手"重构或格式化无关代码。
- **Goal-Driven**：修复 Bug 时，**先写测试复现问题**，再修复。

## 4. Project Gotchas (项目陷阱)
- **API 测试**：需本地 Redis 运行在 `:6379`，否则测试会失败。
- **权限逻辑**：`/auth` 模块依赖遗留的 `session.js`，修改前必须同步 `docs/auth-flow.md`。

## 5. Workflow (精确命令)
- **开发**：`pnpm dev`
- **测试**：`pnpm test --filter user`
- **提交**：Commit message 用中文，格式 `[模块] 说明`。

🔄 第五部分：维护与迭代

CLAUDE.md 不是一次性文档，它是动态演进的工程规范。

错误驱动更新 ：每当 AI 犯了一个重复性错误（如删掉了注释、用了错误的包管理器），立即将修正措施写入 CLAUDE.md。
定期清理：每月审查一次，删除过时的规则（如旧框架的约束）。
分层管理 ：
- 全局配置 (~/.claude/CLAUDE.md)：存放个人偏好（如代码缩进）。
- 项目配置 (./CLAUDE.md)：存放项目特有的技术栈和行为约束。

📌 结语

优秀的 CLAUDE.md 是工程纪律的代码化。它通过明确的规则（如 Karpathy 原则）弥补了 LLM 在逻辑推理和上下文管理上的短板，让 AI 真正成为你手中可控、可信的生产力工具。