129 lines
4.3 KiB
Plaintext
129 lines
4.3 KiB
Plaintext
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
|
||
## 最重要的事情
|
||
|
||
1. **最优路径优先** - 先判断当前约束下的最优路径，锁定后直接推进；不先为了自我防御铺退路、保守版或兼容版
|
||
2. **TDD 先行** - fix/feat 必须先写失败测试，红黄绿循环
|
||
3. **原子提交** - 每个 commit 只做一件事，可独立回滚
|
||
4. **文档驱动** - feat 改动关联 doc/ 下文档，多输出表格、流程图、ASCII 原型图
|
||
5. **知识沉淀** - 有价值的迭代沉淀到 CLAUDE.md（拿捏不准主动问我）
|
||
6. **利用现有工具** - 不重复造轮子，会开车 > 会修车
|
||
7. **有头有尾** - 头：只问会改变最优路径判断的问题，锁定后立刻动手；尾：自己跑验证，不把验证甩给用户
|
||
8. **任务结束后追加** - 主人，用不用我沉淀 or git 提交？
|
||
|
||
## 项目概述
|
||
|
||
**{{项目名称}}** — {{一句话描述}}
|
||
|
||
**产品目标**：
|
||
- {{目标1}}
|
||
- {{目标2}}
|
||
- {{目标3}}
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 | 说明 |
|
||
|------|------|------|
|
||
| 前端 | {{前端技术}} | {{说明}} |
|
||
| 后端 | {{后端技术}} | {{说明}} |
|
||
| 数据库 | {{数据库}} | {{说明}} |
|
||
| 缓存 | {{缓存方案，如无可删除此行}} | {{说明}} |
|
||
| AI 服务 | {{AI 服务，如无可删除此行}} | {{说明}} |
|
||
| 部署 | {{部署方案}} | {{说明}} |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
{{项目名称}}/
|
||
├── {{目录1}}/ # {{说明}}
|
||
│ ├── {{子目录}}/ # {{说明}}
|
||
│ └── {{子目录}}/ # {{说明}}
|
||
├── doc/ # 项目文档
|
||
│ ├── PRD.md
|
||
│ ├── DevelopmentPlan.md
|
||
│ └── tasks.md
|
||
└── {{其他文件}} # {{说明}}
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
### 开发
|
||
|
||
```bash
|
||
{{开发启动命令}}
|
||
```
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
{{构建命令}}
|
||
```
|
||
|
||
### 测试
|
||
|
||
```bash
|
||
{{测试命令}}
|
||
```
|
||
|
||
### 部署
|
||
|
||
```bash
|
||
{{部署命令}}
|
||
```
|
||
|
||
## 开发约定
|
||
|
||
- **包管理器**: 使用 {{包管理器}}（不是 {{其他包管理器}}）
|
||
- **TDD 流程**: 先写测试再实现，核心业务逻辑覆盖率 100%
|
||
- **日志规范**: 使用日志管理器，避免 console.log
|
||
- **入口统一校验**: 所有外部输入（API 参数、用户输入、配置项）在入口处统一校验，内部代码信任已校验的数据，不重复检查
|
||
- **空值显式报错**: 禁止静默吞掉 null/undefined/空字符串，遇到非预期空值必须抛出明确错误信息（含变量名和上下文），让问题在第一现场暴露
|
||
- **关键节点结构化日志**: 在业务关键节点（请求进出、状态变更、外部调用、异常捕获）输出结构化日志，包含 traceId、操作、耗时、结果，便于排查和监控
|
||
- **知识沉淀**: 将有价值的对话迭代沉淀到文档中，包括：
|
||
- 重要技术决策和架构演进 → 更新 CLAUDE.md 相关章节
|
||
- 新功能实现方案 → 更新组件职责、数据流等章节
|
||
- 踩坑经验和解决方案 → 添加到踩坑经验章节
|
||
- API 使用技巧和注意事项 → 更新相关技术栈说明
|
||
- **成功经验复刻**: 一次对话形成可复用结果后，用 `/capture <目录>` 或 `$capture <目录>` 输出结构化记录；另留单独位置保存“味道”
|
||
|
||
{{在此添加项目特定的开发约定}}
|
||
|
||
## 交互准则
|
||
|
||
### 任务有头有尾
|
||
|
||
**头 — 先锁定最优路径再动手**：
|
||
- 收到任务后，先复述理解、列出不确定的点
|
||
- 只追问会改变最优路径判断的问题；能基于上下文和环境判断的，不拿来做前置防御
|
||
- 一旦最优路径锁定，立即沿该路径推进，不先铺退路、折中版或兼容版
|
||
- 确认范围边界：做什么、不做什么、验收标准
|
||
|
||
**尾 — 自己验证，说到做到**：
|
||
- 任务完成后，自己执行验证（跑测试、构建、截图、检查输出等）
|
||
- 把验证结果直接展示给用户，而不是列一堆步骤让用户自己验
|
||
- 验证不通过就自己修，循环直到通过
|
||
- 最终交付物 = 已通过的验证结果
|
||
|
||
### 其他
|
||
|
||
- 任务彻底结束后，追加一句：**主人，用不用我沉淀 or git 提交？**
|
||
|
||
## 踩坑经验
|
||
|
||
<!-- 格式示例：
|
||
|
||
### {{问题简述}}
|
||
|
||
**问题现象**：{{描述现象}}
|
||
|
||
**根因**：{{分析根因}}
|
||
|
||
**解决方案**：{{解决方案}}
|
||
|
||
**注意事项**：{{补充说明}}
|
||
|
||
-->
|