让 Claude 代码助手秒变你团队的“老员工”：一份能自动理解项目、不乱写代码的 CLAUDE.md 实战指南

作者提米哥

你好，我是提米哥，TMDM.cn 的首席选品官，专盯开发者真正用得上的硬核工具和技巧。今天不聊概念，不画大饼——就讲一个文件：CLAUDE.md。

它小到只有几 KB，却能决定你的 Claude Code 是「神队友」还是「猪队友」。
不是靠多喂 token，而是靠一份写对了的 Markdown 文件，让 AI 真正看懂你的项目结构、技术选型、团队规范，甚至“为什么这么设计”。

别被名字吓住——它不是配置文件，不是 JSON，更不是要你背文档。它就是个纯文本 .md 文件，放在项目根目录里，Claude 每次打开项目时自动读一遍，然后整个会话都带着你的上下文干活。

✅ 好的 CLAUDE.md：
– 告诉 Claude “我们用 pnpm 不是 npm”，它就不会再报 command not found；
– 告诉它 “所有数据库操作必须走 /api/src/repos/ 下的仓库类”，它就不会直接在路由里手写 SQL；
– 告诉它 “workspace 在我们系统里指租户隔离单元，不是 VS Code 工作区”，它就不会曲解业务逻辑。

❌ 坏的 CLAUDE.md（比如自动生成没改过的）：
– 堆满“用 2 空格缩进”“加分号”这种该由 ESLint 干的活 → 白烧 token，还容易冲突；
– 写满“本次重构要加缓存”这种一次性任务 → 后续每次对话都被干扰；
– 超过 300 行，像本百科全书 → Claude 直接当噪音过滤掉。

下面这份实战心法，来自 Effloow 团队真实运行 14 个 AI 代理的血泪经验，已验证能减少 70%+ 的无效重试、省下 40%+ 的 token 成本、让新人（或 AI）第一天就能写出符合规范的 PR。

✅ 三句话，记住好 CLAUDE.md 的核心

  1. WHAT（它面对什么？）：一句话说清项目是干啥的，技术栈是啥（TypeScript？Prisma？Next.js？），目录怎么分（/api / /web / /shared？）。
  2. WHY（为什么这么设计？）：不是只写“用服务端组件”，而是写“因为首屏 SEO 和数据安全要求，所有页面默认服务端渲染，仅交互区域升为客户端组件”。
  3. HOW（具体怎么干？）：命令必须带完整参数！比如：
  4. ❌ 运行测试
  5. ✅ pnpm test -- --grep "user login"

📄 一份能直接抄的极简模板（< 80 行，开箱即用）

# Project: MyEcomApp

## Overview
面向中小商家的 SaaS 电商后台系统，支持多店铺、订单履约和营销活动管理。

## Stack
- Language: TypeScript 5.4 (strict mode)
- Framework: Next.js 14 + App Router
- Database: PostgreSQL 16 via Prisma ORM
- Queue: BullMQ on Redis
- Auth: Clerk

## Architecture
- 前端 `/web` 和后端 `/api` 分离部署，共享 `/shared` 类型定义。
- 所有数据库访问必须通过 `/api/src/repos/` 下的 Repository 类（禁止 route handler 直连 DB）。
- 客户端状态管理用 Zustand，服务端状态用 React Server Components + `cache()`。

## Commands
- 安装依赖：`pnpm install`
- 启动开发：`pnpm dev`（同时启动 API + Web）
- 运行全部测试：`pnpm test`
- 运行单个测试：`pnpm test -- --grep "payment flow"`
- 类型检查：`pnpm typecheck`
- 自动修复代码风格：`pnpm lint:fix`

## Workflow
1. 从 `main` 分支拉新特性分支（如 `feat/order-refund`）
2. 编码 + 提交前运行：`pnpm typecheck && pnpm lint:fix && pnpm test`
3. 提交信息用约定式格式：`feat(order): 支持部分退款`

## Domain Terms
- workspace：指一个独立运营的商家店铺（含独立域名、数据隔离）
- campaign：指一次限时营销活动（非全局促销，绑定特定商品池）

💡 小技巧：把详细文档（如测试规范、API 设计约定）单独写成 docs/agent/testing.md 这样的文件，然后在 CLAUDE.md 里只写一句 详见 docs/agent/testing.md —— 这叫「渐进式披露」，既保持主文件清爽，又让 Claude 需要时自动去读。

⚠️ 绝对不要写的 4 类内容（新手高频翻车点）

  • 别当 ESLint 使：缩进、分号、引号风格 → 全交给 Biome 或 Prettier，CLAUDE.md 只需写一句：“格式化请执行 pnpm format”。
  • 别塞临时任务：比如“本周把用户表迁移到新 schema” → 这种写进当前对话 prompt 就行，别污染长期指令。
  • 别抄整篇架构文档：超过 100 行？删掉一半。Claude 不是来背书的，是来帮你干活的。
  • 别放任何密钥或路径：.env 里的东西让它自己读，CLAUDE.md 里只写“使用环境变量 DATABASE_URL 连接数据库”。

🌐 进阶提示：多工具团队用 AGENTS.md（未来-proof）

如果你团队有人用 Cursor、有人用 GitHub Copilot、还有人用 Claude Code —— 别维护 3 份不同格式的指令文件。
直接用行业新标准 AGENTS.md（Linux Foundation 背书），它被 10+ 主流 AI 编程工具原生支持，写一次，到处生效。
CLAUDE.md 只保留 Claude 特有功能（比如 @import 引入子配置），其他通用规则全挪到 AGENTS.md。

混合方案示例：
– ✅ AGENTS.md（根目录）：团队共用的技术规范、领域术语、核心命令
– ✅ CLAUDE.md（可选）：Claude 专属的 @import ./docs/claude-hooks.md
– ✅ CLAUDE.local.md（.gitignore 里）：你个人的快捷键偏好、常用调试命令

🔍 最后送你一个「5 秒自查清单」

打开你的 CLAUDE.md，快速扫一眼：
– [ ] 总行数 < 100？
– [ ] 没有一行是“用 4 空格”“加分号”这类 linter 职责？
– [ ] 每条命令都带完整参数和包管理器名（pnpm/bun/npm）？
– [ ] 至少写了 1 条“为什么”（WHY），不是只罗列“做什么”？
– [ ] 所有业务术语（如 tenant, workspace）都有明确定义？

如果 3 个以上打钩 → 恭喜，你的 Claude 已经比 80% 的开发者更懂你的项目了。

直达网址：https://effloow.com/articles/how-to-set-up-your-project-for-agentic-coding

作加

微信联系：timidamen

类似文章