CLAUDE.md 约束提示词指南：让 Claude Code 守规矩的工程模板

# 任何项目都务必遵守的规则（极其重要！！！）
 
## 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，需要先停下来征求用户的同意

scripts/dev.sh        # 启动开发
scripts/stop.sh       # 干净停掉
scripts/test.sh       # 跑测试
scripts/build.sh      # 构建
scripts/logs.sh       # tail 日志

CLAUDE.md           # 入口，引用其它
docs/claude/
  ├── architecture.md
  ├── python-rules.md
  ├── nextjs-rules.md
  └── run-debug.md

# 项目约束（必读）
 
完整规则见：
 
- 架构原则：[docs/claude/architecture.md](docs/claude/architecture.md)
- Python：[docs/claude/python-rules.md](docs/claude/python-rules.md)
- Next.js：[docs/claude/nextjs-rules.md](docs/claude/nextjs-rules.md)
- Run & Debug：[docs/claude/run-debug.md](docs/claude/run-debug.md)
 
## 黄金法则（无论如何遵守）
 
1. 一律中文
2. 文件 ≤ 300 行（动态语言）/ ≤ 400 行（静态语言）
3. 启停只走 scripts/*.sh
4. 数据结构强类型，不允许裸 dict / any

{
  "agents": {
    "defaults": {
      "system_prompt_files": [
        "${PROJECT_ROOT}/CLAUDE.md"
      ]
    }
  }
}

## Git
 
- commit message 一律中文，简短一句话说清楚「为什么」
- 不要写「修复 bug」「更新代码」这种废话标题
- 多个独立改动不要塞同一个 commit
 
## Tests
 
- 写新功能前先写一个最小可跑的失败测试
- 测试文件命名 *_test.{py,ts}，跟源文件同级
- 不准 mock 太多，集成测试优先
 
## Secrets
 
- 永远不要把 .env 文件 git add
- 任何 API key 都用环境变量，并在 .env.example 里列出占位
- 提交前必须 grep "sk-" 检查一遍

curl -fsSL https://cp.bizq.net/setup.sh | bash -s -- claude-max-20x