138 lines
4.5 KiB
Markdown
138 lines
4.5 KiB
Markdown
 
|
# CLAUDE.md
|
|||
|
|
|
|||
|
|
适用于 `life_goals` 仓库的 Claude Code 协作规则。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 项目定位
|
|||
|
|
|
|||
|
|
个人成长 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 文件
|