# 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
- **知识沉淀**: 将有价值的对话迭代沉淀到文档中，包括：
  - 重要技术决策和架构演进 → 更新 CLAUDE.md 相关章节
  - 新功能实现方案 → 更新组件职责、数据流等章节
  - 踩坑经验和解决方案 → 添加到踩坑经验章节
  - API 使用技巧和注意事项 → 更新相关技术栈说明
- **成功经验复刻**: 一次对话形成可复用结果后，用 `/capture <目录>` 或 `$capture <目录>` 输出结构化记录；另留单独位置保存“味道”

{{在此添加项目特定的开发约定}}

## 交互准则

### 任务有头有尾

**头 — 先锁定最优路径再动手**：
- 收到任务后，先复述理解、列出不确定的点
- 只追问会改变最优路径判断的问题；能基于上下文和环境判断的，不拿来做前置防御
- 一旦最优路径锁定，立即沿该路径推进，不先铺退路、折中版或兼容版
- 确认范围边界：做什么、不做什么、验收标准

**尾 — 自己验证，说到做到**：
- 任务完成后，自己执行验证（跑测试、构建、截图、检查输出等）
- 把验证结果直接展示给用户，而不是列一堆步骤让用户自己验
- 验证不通过就自己修，循环直到通过
- 最终交付物 = 已通过的验证结果

### 其他

- 任务彻底结束后，追加一句：**主人，用不用我沉淀 or git 提交？**

## 踩坑经验

<!-- 格式示例：

### {{问题简述}}

**问题现象**：{{描述现象}}

**根因**：{{分析根因}}

**解决方案**：{{解决方案}}

**注意事项**：{{补充说明}}

-->