From 446a946549187eaf91f58cd1e1cd5e002b784f59 Mon Sep 17 00:00:00 2001 From: ila Date: Sun, 24 May 2026 17:30:22 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20CLAUDE.md=20?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E5=8D=8F=E4=BD=9C=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0861393 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,137 @@ +# 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 | 用途 | +|------|------| +| `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 文件