CLAUDE.md 失效的 5 个常见错误及修复方法

你写了 CLAUDE.md，放进了项目根目录。但 Claude Code 依然我行我素——你要 Next.js 它却选了 Express，完全无视你的命名规范。

熟悉吗？你不是一个人。

在前一篇文章中，我们介绍了设计 system prompt 的 5 条规则。今天我们聚焦一个具体文件——CLAUDE.md——以及让它失效的常见错误。

在 AI Autonomous Revenue 项目中为多个项目配置 CLAUDE.md 之后，我们发现了 5 种常见失败模式，解释了为什么你的 CLAUDE.md "不起作用"，以及如何修复每一个。

错误 1：写的是愿望，而不是指令

# Philosophy
- Clean code is important
- We value readability over cleverness
- Tests should be comprehensive

这读起来像团队宣言，而不是指令集。"Clean code is important" 没有给 Claude Code 任何可操作的信息。什么才算干净？如何衡量？

人类队友能从文化背景中推断含义。AI 不能，它只能字面解读。

# Coding Rules
- Functions must be under 30 lines. Extract into smaller functions if longer
- Variable names: camelCase, minimum 3 characters (single-letter only for loop counters)
- Every public function needs JSDoc with @param and @returns
- No nested ternary operators — use if/else or early return

原则：写能被判定为通过/失败的规则。如果你无法检查是否被遵守，Claude Code 也无法遵守。

错误 2：内容太多（重要规则被淹没）

你的 CLAUDE.md 有 200+ 行，涵盖所有内容：技术栈详情、所有命令、每个目录的解释、80 条编码规则、Git 工作流、部署说明……

当一切都是重点，就没有重点了。冗长的配置文件稀释了关键规则的权重。

# CRITICAL (always follow these)
- TypeScript strict mode. No `any` type ever
- Server Components by default. "use client" only with explicit directive
- All DB access through src/lib/db/ (never direct Prisma calls in components)

# Stack
- Next.js 14+ (App Router), TypeScript, Tailwind CSS, Prisma

# Commands
- Dev: `pnpm dev` | Build: `pnpm build` | Test: `pnpm test`

# Conventions (see docs/ for full details)
- Named exports only (except page.tsx/layout.tsx)
- Zod schemas in src/schemas/, validated at API boundary

原则：使用三层结构：

CRITICAL（顶部 3–5 条规则——这些是不可妥协的）

参考信息（Stack、Commands——Claude 需要知道的东西）

详情在别处（链接到 docs/ 查看完整约定）

错误 3：列出了你实际没用的技术

# Stack
- Next.js 14 with App Router
- NextAuth.js v5 for authentication    ← not installed yet
- Prisma + PostgreSQL                   ← actually using Drizzle + SQLite
- Redis for caching                     ← planned but not implemented

Claude Code 把 CLAUDE.md 当作事实来源。如果你列出了项目中不存在的库：

它会导入未安装的模块

它会基于不存在的 API 写代码

它会生成与你实际配置相悖的结构

这种情况通常发生在你复制了一个模板却忘记定制的时候。

# Stack (ACTUALLY INSTALLED — verify against package.json)
- Next.js 14 with App Router
- Drizzle ORM + SQLite (src/lib/db/schema.ts)
- Tailwind CSS + shadcn/ui

# NOT AVAILABLE (do not use or suggest these)
- No auth library yet (login handled by basic middleware)
- No caching layer (all queries hit DB directly)
- No state management library (use React state + URL params)

原则：只列出实际安装的东西。明确说明哪些是"不可用"的——这样可以防止 Claude 建议使用它们。

错误 4：只有约束，没有替代方案

# Rules
- Do NOT use any type
- Do NOT add new dependencies
- Do NOT use class components
- Do NOT modify .env files
- Do NOT use default exports
- Do NOT write inline styles

一个"不要做"的清单告诉 Claude 要避免什么，但没有告诉它应该用什么。如果 any 被禁用了，它应该用 unknown + 类型守卫？泛型？还是显式类型定义？

# Type Safety
- Never use `any`. Instead:
  - External API responses → define with Zod schema, use `z.infer<typeof schema>`
  - Unknown runtime values → `unknown` with type guard functions in src/lib/guards/
  - Generic containers → TypeScript generics with constraints

# Styling
- No inline styles. Instead:
  - Standard styling → Tailwind utility classes
  - Conditional styles → `clsx()` or `cn()` from src/lib/utils
  - Animations → Tailwind's built-in animation utilities

# Dependencies
- No new deps without justification. Use what's already available:
  - Date handling → native Date (no moment/dayjs)
  - HTTP → native fetch (no axios)
  - Validation → existing Zod setup in src/schemas/

原则：每一条"不要"都要配上"应该怎么做"。这消除了歧义，给 Claude 一条清晰的前进路径。

错误 5：写完一次，再也不更新

你的 CLAUDE.md 是三个月前项目启动时写的。从那以后：

包管理器从 npm 改成了 pnpm

测试框架从 Jest 换成了 Vitest

目录结构被重新组织了

现在 Claude Code 运行 npm test（失败），写 Jest 语法（错误），在已经不存在的目录里创建文件。

添加一个更新触发区：

# Meta
Last updated: 2026-08-01
Update this file when:
- [ ] package.json dependencies change
- [ ] Directory structure changes
- [ ] New coding conventions are adopted
- [ ] CI/CD pipeline changes
- [ ] Test framework or build tools change

原则：CLAUDE.md 是一个活文档。每月审查一次，或者在项目配置变化时及时更新。过时的指令比没有指令更糟糕。

快速检查清单：你的 CLAUDE.md 真的起作用吗？

[ ] 规则是具体的、可通过/失败测试的（不是愿望式的）

[ ] CRITICAL 部分存在，顶部 ≤5 条规则

[ ] Stack 部分列出的每项技术都是实际安装的（对照 package.json 检查）

[ ] 每一条"不要"都有对应的"应该怎么做"

[ ] 文件在最近 30 天内被审查过

[ ] 总长度在 100 行以内（详情在独立文档中）

如果你想跳过从头写 CLAUDE.md 的试错过程：

🎁 Claude Code Config Starter Pack（免费）——3 个模板（Next.js、TypeScript Library、Python FastAPI），遵循以上所有原则。

🛠️ Claude Code Config Pack——20 个模板（$5）——经过 Docker 验证的 20 种项目类型配置，包括 Go、Rust、Flutter、Terraform 等。

📘 The AI Coding Prompt Toolkit（$5）——52 个结构化 prompt，涵盖项目启动、功能实现、测试和重构。

你在 CLAUDE.md 上遇到过哪些错误？欢迎在评论区留言——我很想听听我遗漏的模式。