# CLAUDE.md

适用于 `life_goals` 仓库的 Claude Code 协作规则。

---

## 会话启动

每次新 session 开始时，按顺序执行：

1. 读取 `docs/PROGRESS.md` — 了解当前功能状态和正在进行的任务
2. 执行 `git log --oneline -10` — 查看最近提交，了解上次做到哪里
3. 确认当前所在 Phase，再开始任务

> 用户说"继续上次的开发"时，完成以上步骤后直接接续，不需要重新介绍项目背景。

---

## 项目定位

个人成长 App，帮助用户管理人生目标树、每日/每周复盘并通过 AI 教练保持方向感。

- **前期用户**：产品作者本人（自用），后续面向外部用户推广
- **当前阶段**：Phase 0 MVP 已完成，Phase 1 待开发
- **维护者**：初级开发者 + AI 协作，所有改动优先保证可读、可理解、可接手

进入项目先读：
1. `docs/PROGRESS.md` — 当前各功能状态
2. `docs/decisions/` — 重要决策的背景和原因

---

## 目录职责

| 目录 | 说明 |
|------|------|
| `app/` | React 前端（PWA → Capacitor），Phase 2 迁入代码 |
| `server/` | 后端 API，Phase 4 账号体系阶段启动，当前为占位 |
| `docs/` | 所有项目文档，与代码同等重要 |
| `docs/PROGRESS.md` | 功能状态总览，每次功能变更必须同步更新 |
| `docs/decisions/` | ADR 决策记录，重要决策必须补文件 |
| `docs/01~06` | 需求、架构、开发计划等完整文档 |

---

## 修改原则

- 先读现有实现和相关文档，再动手；优先最小化改动范围。
- 已有实现可复用时，不新增平行实现。
- 先定位根因，再修复问题，不做只遮盖现象的补丁。
- 非任务要求，不改数据结构字段名、AI Prompt 格式、存储 key 命名。
- 涉及 Anthropic API 调用、存储读写、数据结构变更时，必须保守处理。

---

## 文档同步要求

**代码和文档必须同步提交，不允许代码改了文档没跟上。**

| 发生什么 | 必须更新 |
|---------|---------|
| 完成或开始一个功能 | `docs/PROGRESS.md` 状态标签 |
| 做了重要架构/产品决策 | `docs/decisions/` 新增 ADR 文件 |
| 需求发生变化 | `docs/01-需求收集/` 或 `docs/02-需求分析/` |
| 技术选型变化 | `docs/03-架构设计/技术选型与数据结构.md` |
| 迭代计划变化 | `docs/05-开发计划/MVP范围与迭代路线图.md` |

ADR 文件命名格式：`docs/decisions/00N-简短描述.md`，内容包含：背景、决策、原因、影响。

---

## 注释要求（面向初级维护者）

适量中文注释，只写必要信息。重点给以下场景加注释：

- AI Prompt 构建逻辑（字段含义、上下文组装规则）
- 数据结构的非直觉字段（如 `level` 推断规则、`nodes` flat 结构设计）
- 存储读写的关键路径（localStorage key 命名、数据合并逻辑）
- 外部约束（Anthropic API 参数限制、Capacitor 平台差异）

不写无效注释（如"给变量赋值"这类显而易见的描述）。

---

## 技术约定

### 当前阶段（Phase 0-1，无构建工具）
- 框架：React JSX，无 Vite / Webpack，直接运行
- 样式：Inline CSS + CSS Variables，不引入 CSS 框架
- 存储：localStorage 为主（Artifact Storage API 仅限 Claude 平台环境）
- AI：Anthropic API `/v1/messages`，模型 `claude-sonnet-4-20250514`

### Phase 2+ 引入后
- 构建工具引入 Vite 时，需同步更新 `app/README.md` 和架构文档
- 存储迁移（localStorage → SQLite）需保留数据迁移路径，不破坏已有数据
- 后端引入时，Anthropic API 调用必须迁移至 `server/`，不再从前端直连

---

## 安全要求

- **严禁**将 API Key、密码、token 提交到 git
- `.env` / `.env.local` 已在 `.gitignore` 中，永远不提交
- 当前前端直连 Anthropic API 是临时方案，Phase 4 引入后端后必须改为服务端代理

---

## 验证要求

改动完成后做最小必要验证：

- UI 改动：在浏览器确认渲染和交互正常
- 存储改动：确认数据写入和读取正确，刷新后数据保持
- AI 相关改动：确认 Prompt 构建正确，API 调用返回符合预期
- 如无法验证，必须说明原因和风险

---

## 提交规范

格式：`<type>(<scope>): <简短描述>`

| type | 用途 |
|------|------|
| `feat` | 新功能 |
| `fix` | 修复问题 |
| `docs` | 文档变更 |
| `refactor` | 重构（不改功能） |
| `chore` | 构建/配置/依赖 |

scope 对应目录或阶段，例如：

```
feat(phase1): 完成每周复盘模块
fix(app): 修复漏打卡日期显示异常
docs(adr): ADR-005 服务端技术选型
docs: 更新 PROGRESS.md Phase1 状态
```

---

## 提交前检查

- [ ] 未改动无关文件
- [ ] 未引入不必要重构
- [ ] 未硬编码 API Key、密码、密钥等敏感信息
- [ ] 未留下临时代码、调试输出、未说明的 TODO
- [ ] `docs/PROGRESS.md` 状态已同步更新
- [ ] 重要决策已补 ADR 文件