项目中的 CLAUDE.md 应该怎么写？

在使用 Claude Code 辅助开发时，它到底听不听话，效率高不高，很大程度上取决于你有没有“喂好它”。

怎么喂？写一份清晰、全面、硬核的 CLAUDE.md，就像给一个熟练工打好工作说明书。
本篇我们就来讲讲——CLAUDE.md 中应该包含哪些高质量约束提示词，才能让 Claude 真正成为你的强力助手。

🚨 开门见山：这是 Claude 必须遵守的核心规则

你可以直接复制这份“军规”到 CLAUDE.md 文件中。
必要的时候，也记得提醒 Claude：“请回顾 CLAUDE.md 后再执行操作。”

#1 通讯规范：必须讲中文

## Communication

- 永远使用简体中文进行思考和对话

Claude 有多语言能力没错，但不要浪费，团队规范就是：中文对话、中文思考。

#2 文档规范：目录结构要清晰

## Documentation

- 编写 .md 文档时，也要用中文
- 正式文档 → 放在 docs/
- 讨论/方案文档 → 放在 discuss/

避免文档乱飞，让 Claude 也知道该写哪类文档，放在哪个目录。

#3 代码结构约束：三道铁律

## Code Architecture

- Python/JS/TS 文件 ≦ 300 行
- Java/Go/Rust 文件 ≦ 400 行
- 每层文件夹 ≦ 8 个文件

这些行数和文件限制，不是为了限制 Claude 的能力，而是为了可维护性。

注意：文件行数不是死线，可以浮动，但建议设定在 200~400 行之间。

#4 架构审美：防止“代码腐烂”的七宗罪

Claude 写代码不能只看能不能跑，还要避开这些“代码坏味道”：

• 僵化：一动全身的系统
• 冗余：复制粘贴盛行
• 循环依赖：你中有我，我中有你
• 脆弱：一改就崩
• 晦涩：写完看不懂
• 数据泥团：参数到处飘
• 过度设计：用坦克轧蚂蚁

发现了？及时问用户：是否要优化？能优化什么？怎么优化？

#5 启动 & 调试规范：一切靠脚本

## Run & Debug

- 所有启停命令必须封装为 scripts/*.sh 脚本
- 永远不要直接用 npm、pnpm、uv、python 这些命令
- 日志统一输出到 logs/ 目录

Claude 写的调试命令要符合可重复执行、团队统一、可维护的标准。

🐍 Python 项目约束

## Python

- 尽量使用强类型（typing）
- 虚拟环境目录永远是 .venv
- 一律使用 uv（不是 pip/poetry/conda）
- 根目录 & main.py 保持最简洁

Claude 想用 dict？先问你行不行。

⚛️ React / Next.js / TypeScript 项目约束

## React / Next.js / TypeScript / JavaScript

- Next.js 强制用 v15.4
- React 强制用 v19
- Tailwind CSS 强制用 v4
- 禁用 CommonJS
- 优先 TypeScript，only fallback to JS if necessary
- 数据结构必须强类型，避免 any/json 派

版本统一、模块系统一致、类型安全，Claude 写的代码才不会埋下“技术债”。

✅ 建议使用方式

• CLAUDE.md 文件就像 AI 团队成员的“开发者守则”
• 放在项目根目录，Claude 读一次，胜过你说十次
• 每次 Claude 表现怪异的时候，提醒它：“请回顾 CLAUDE.md”

📌 最后

Claude Code 再智能，它也只是你的工具。你给它什么规则，它就能发挥多大能力。

给 AI 设定好“边界”，比让它“自由发挥”更重要。

CLAUDE.md 就是你对 AI 的“项目控制面板”——
写好它，Claude 就能高效安全地为你打工。

附：完整提示词

# 任何项目都务必遵守的规则（极其重要！！！）

## Communication

- 永远使用简体中文进行思考和对话

## Documentation

- 编写 .md 文档时，也要用中文
- 正式文档写到项目的 docs/ 目录下
- 用于讨论和评审的计划、方案等文档，写到项目的 discuss/ 目录下

## Code Architecture

- 编写代码的硬性指标，包括以下原则：
  （1）对于 Python、JavaScript、TypeScript 等动态语言，尽可能确保每个代码文件不要超过 300 行
  （2）对于 Java、Go、Rust 等静态语言，尽可能确保每个代码文件不要超过 400 行
  （3）每层文件夹中的文件，尽可能不超过 8 个。如有超过，需要规划为多层子文件夹
- 除了硬性指标以外，还需要时刻关注优雅的架构设计，避免出现以下可能侵蚀我们代码质量的「坏味道」：
  （1）僵化 (Rigidity): 系统难以变更，任何微小的改动都会引发一连串的连锁修改。
  （2）冗余 (Redundancy): 同样的代码逻辑在多处重复出现，导致维护困难且容易产生不一致。
  （3）循环依赖 (Circular Dependency): 两个或多个模块互相纠缠，形成无法解耦的“死结”，导致难以测试与复用。
  （4）脆弱性 (Fragility): 对代码一处的修改，导致了系统中其他看似无关部分功能的意外损坏。
  （5）晦涩性 (Obscurity): 代码意图不明，结构混乱，导致阅读者难以理解其功能和设计。
  （6）数据泥团 (Data Clump): 多个数据项总是一起出现在不同方法的参数中，暗示着它们应该被组合成一个独立的对象。
  （7）不必要的复杂性 (Needless Complexity): 用“杀牛刀”去解决“杀鸡”的问题，过度设计使系统变得臃肿且难以理解。
- 【非常重要！！】无论是你自己编写代码，还是阅读或审核他人代码时，都要严格遵守上述硬性指标，以及时刻关注优雅的架构设计。
- 【非常重要！！】无论何时，一旦你识别出那些可能侵蚀我们代码质量的「坏味道」，都应当立即询问用户是否需要优化，并给出合理的优化建议。


## Run & Debug

- 必须首先在项目的 scripts/ 目录下，维护好 Run & Debug 需要用到的全部 .sh 脚本
- 对于所有 Run & Debug 操作，一律使用 scripts/ 目录下的 .sh 脚本进行启停。永远不要直接使用 npm、pnpm、uv、python 等等命令
- 如果 .sh 脚本执行失败，无论是 .sh 本身的问题还是其他代码问题，需要先紧急修复。然后仍然坚持用 .sh 脚本进行启停
- Run & Debug 之前，为所有项目配置 Logger with File Output，并统一输出到 logs/ 目录下

## Python

- 数据结构尽可能全部定义成强类型。如果个别场景不得不使用未经结构化定义的 dict，需要先停下来征求用户的同意
- Python 虚拟环境永远使用 .venv 作为目录名
- 必须使用 uv，而不是 pip、poetry、conda、python3、python。包括依赖管理、构建、调试启动等所有环节
- 项目的根目录必须保持简洁，只保留必须存在的文件
- main.py 内容也要简洁。只保留必须存在的代码

## React / Next.js / TypeScript / JavaScript

- Next.js 强制使用 v15.4 版本，不要再用 v15.3 或 v14 或以下版本
- React 强制使用 v19 版本，不要再用 v18 或以下版本
- Tailwind CSS 强制使用 Tailwind CSS v4。不要再用 v3 或以下版本
- 严禁使用 commonjs 模块系统
- 尽可能使用 TypeScript。只有在构建工具完全不支持 TypeScript 的时候，才使用 JavaScript（如微信小程序的主工程）
- 数据结构尽可能全部定义成强类型。如果个别场景不得不使用 any 或未经结构化定义的 json，需要先停下来征求用户的同意

Mobile Study

2025年8月9日土曜日