# Claude Code 项目规则(FmodeStudio 规范包 · 阶段视图 2/4:设计建模)

> 本文件为 FmodeStudio 规范包的**客户项目入口**(自 `stages/stage-2-设计建模-CLAUDE.md` 派生并预填本项目信息)。
> **阶段视图机制**:黄金规则 11 条 + AI 协作义务 + 环节-Skill 调用表**全阶段常驻**(本文件正文各阶段一致);仅「六、模块规则」@import 区块按阶段裁剪。阶段切换由 AI 自动执行——条件达成后 AI 直接编辑本文件「六、模块规则」区块为目标阶段清单并留痕,无需用户手动操作文件(清单与条件见包内《阶段视图切换指南.md》)。
> **规范母版(唯一权威源)**:随包 rules/(21 模块全集)、templates/(25 模板)、.claude/skills/(60 技能)、ui-kit/(官方组件底座)。客户项目内不修改 rules/ 内容;踩坑经验由交付方回写母版后随新版本同步。
> 规范版本:企业交付版 v1.0(自 FmodeStudio 平台版规范 v1.4 派生)| 更新日期:2026-08-19 | 同步至本项目日期:2026-10-14

## 当前阶段说明

- **当前阶段:② 设计建模 + 设计系统**(加载 6 个模块,等效约 330 行)
- **⚠️ 本项目阶段② 含两个部分**(用户裁决 6「先文档 → UI 设计 → 功能完善」):
  1. **设计建模**(规范标准内容):数据范式文档(1NF/2NF/3NF 判定 + Schema + CLP)→ API 契约 → 建模评审
  2. **设计系统**(本项目新增):设计令牌定稿 / 组件规范 / 关键页面原型 / 双端布局规范
- **本阶段目标**:产出**可实施的完整设计规范**,并通过评审闭环
- **进入下一阶段的条件**:数据范式文档 + API 契约评审通过(**评审员子代理出具评审报告并修复闭环**)
- **切换动作(AI 自动执行,用户无需手动操作文件)**:条件达成后 AI 直接编辑本文件「六、模块规则」区块为目标阶段清单(清单见《阶段视图切换指南.md》),在 docs/00-tracking/操作追踪.md 留痕并简报
- **需求回溯保障**:需求变更时临时把 19 模块加回 @import(黄金规则 3 全程常驻兜底)
- **⚠️ 本项目特有的硬门禁 `G-D1`**:关键页面原型产出后**必须先交用户查看确认**(裁决 11),未确认**不得进入编码**

## 项目补充信息

- 项目名称:**fmode-app-v2** — Fmode 双端客户端(桌面横版 + 手机竖版)· 人机共生 IM 中枢
- 应用类型与规模:**单前端 Angular SPA**(无自建后端);双端路由 `/desktop/**` + `/mobile/**`,约 20 条路由;不做响应式布局切换——入口页 `replaceUrl` 按 UA/视口一次性判定跳端,之后各端布局固定;两端共享 `core/` 服务与 `components/` 组件
- **fmode-ng 依赖版本与初始化 config 实例名**:`fmode-ng ^0.0.246`,`FmodeParse.with('nova')` → appId `ncloudmaster` / `serverURL https://server.fmode.cn/parse`
- 目录布局:**单 Angular workspace(非 monorepo)**,根目录即应用;`src/app/` 下计划 `core/`(共享服务)· `components/`(业务外壳组件)· `ui/`(ui-kit 官方底座,整目录接入,禁改)· `desktop/` · `mobile/` · `pages/`
- **config.json 位置与部署模式:不适用**。纯前端 SPA,无 `apps/server/config.json`;数据访问与业务逻辑全部走 **fmode 平台云函数**(服务端托管),前端不持有任何服务端密钥
- 前端技术栈:**Angular 20.3.0** + 全 standalone 组件 + lazy `loadComponent`/`loadChildren`;**Tailwind 3.4(preflight 正常启用)** + **ui-kit 官方组件底座(桌面 76 + 移动 71 组件)**,整目录接入 `src/app/ui/`;`matrix-js-sdk ^42.4.0`(懒加载 chunk,不进主包);`@fortawesome/fontawesome-free ^7.3.1`;Karma + Jasmine
- **设计令牌真源**:ui-kit 的 `src/styles.uikit.css`(`:root` / `.dark` / `[data-accent]` 语义 token:`--canvas`/`--surface`/`--ink`/`--primary`…)。**禁止再造令牌前缀,禁止硬编码色值**(存量项目 3 套前缀 + 321 处硬编码的教训)
- 常用命令:
  - 本地开发:`npm start`(`ng serve` → http://localhost:4200/);强制某端可直开 `/desktop/chat` 或 `/mobile/messages`
  - 构建:`npm run build`
  - 测试:`npm test`(Karma + Jasmine)
  - 冒烟:`NODE_PATH=$PWD/node_modules node scripts/smoke-imhub.js`(待建,Playwright 双端全路由断言)
  - 部署:待定(见重建方案风险 R6)
- 迭代记录见 `docs/00-tracking/操作追踪.md`;当前方案见 `docs/02-design/plans/2026-10-14-v2重建方案.md`
- **⚠️ 待确认项(请勿擅自认定)**
  - 黄金规则 2 提到的「PreToolUse hook 强制拦截 git 提交」:本项目 `.claude/` 下当前**只有 `skills/`,没有 `settings.json`**,该 hook 未配置。在补齐前,「禁止自动提交」依赖本规则自律执行。
  - 后端云函数清单与契约(`xlosi3m46q` 状态、`lfYlgU7SkK` 交付物、`RP5Ht55NeX` provision、`zl4yU8PAEB` token-sync、`AlP56LCKFm` upload-url)散见于存量 README 与代码调用点,**尚无集中的 API 契约文档**,且字段定义未经核对(`docs/02-design/database/ER-图-草案.md` 中标 ❓ 者为逆向推测)。若触及后端契约,必须先补 `docs/03-interface/api/`。
  - `tasks[]` 多任务字段在存量系统中**从未落库**,"多任务并行"当前是宣传语而非实现(见访谈问卷 Q3.3-D1)。
  - **安全事项待处置**:存量 `E:\work\fmode-app\scripts\deploy.sh` 有 4 个明文 OBS 凭证且已进 git 历史;存量 `core/matrix-client.ts` 有明文 TURN 凭据。均违反黄金规则 9,已列访谈问卷 S1/S2 待用户裁决。

## 一、身份与语言

- 始终使用中文与用户交流、输出文档与提交信息。
- 不编造、不臆测:信息不足时先提问,不猜测文件路径、配置、密钥、远程地址。
- 一次只做一件事,不擅自扩大任务范围。

## 二、黄金规则(优先级从高到低,全阶段常驻)

1. **[必须] 先问后做,决策分层**:需求不明确、存在多种方案、影响范围大、可能破坏既有功能时,必须先提问确认;按意图三分与澄清策略分级(高/中/低)决定问什么、问多少——业务语义/范围/验收口径等人级决策必须问用户,技术实现决策(schema 字段、表关系、接口形态)由 AI 定并留痕说明,禁止把技术细节抛给用户。
2. **[必须] 禁止自动提交**:任何 `git commit / git push` 前必须征得用户明确同意(原由 PreToolUse hook 强制拦截;**本项目暂未配置该 hook,见「待确认项」,更须自律**)。
3. **[必须] PRD 阅读与执行**:需求以 PM 产出的 PRD/MVP 范围/交接文档为准直接执行,禁止擅自增加页面/接口/需求;需求缺口与矛盾写变更请求回 PM 确认,禁止自行拍板。本项目需求源为 `docs/01-requirements/prd/`,存量基线正文见 `E:\work\fmode-app\docs\`。
4. **[必须] 文档同步**:功能计划/逻辑变更必须先写或更新文档(技术方案/PlantUML 数据范式/API/修改留痕),再实现代码;实现完成后再次同步相关文档。
5. **[必须] 数据访问统一 fmode-ng 封装**:前端与后端统一通过 `fmode-ng`(`FmodeParse.initialize` 仅初始化一次 + `FmodeParse.with('nova')` 取实例)访问数据,官方 parse SDK 仅经 fmode-ng 使用,禁止绕过封装裸调;禁止引入任何第三方 Parse 封装库。
6. **[必须] 平台铁律(红线)**:`serverURL` 只在初始化处配置一次,禁止散落各处;`masterKey` 与数据库密码不得出现在前端代码(仅 config.json 与服务端);删除用软删 `isDeleted=true`;业务表必须带 `company: Pointer<Company>` 多租户隔离;禁止让用户手动建表/连库/配服务器——由 `FmodeSchema` 与平台能力自动完成。
7. **[必须] 依赖按需引入**:新增依赖必须说明理由并经用户确认;图标白名单按需引入,禁止全量引入。
8. **[必须] 测试通过才算完成**:任何改动必须运行对应测试并输出验证证据,测试失败不得视为完成、不得提交;无法验证或降级处理的条目必须在交付时显式披露为「未验证项/已知限制」,禁止隐藏。
9. **[必须] 环境与密钥**:`config.json`(含 masterKey/databaseURI)与 `.env` 不入 git;前端严禁出现 masterKey 与任何服务端密钥(含 OBS AK/SK、TURN 凭据);Nginx 配置入库;生产环境双重校验保证鉴权不可误关。
10. **[必须] 修改留痕与全程追踪**:项目必须维护 `docs/00-tracking/` 追踪体系——「操作追踪.md」按动作逐条追加(时间/内容/原因/涉及文件/关联设计文档链接),重大修改按日期新建当日文档;修改留痕带日期;任何操作可回溯「做了什么、为什么这么做」。
11. **[必须] 评审员隔离与子代理评审**:复杂任务(≥3 文件/数据模型/安全权限)交付前派发独立评审员子代理(独立 prompt 只含技术栈事实+评审检查单+被评审物,不携带规范设计过程与本对话上下文),按指定技术栈专项评审;评审报告归档 `docs/04-quality/review/`,问题修复闭环(复审通过)后方可宣称完成。

## 三、AI 协作义务

- **代码自查**:AI 生成代码后必须自查——无调试残留 `console.log`、无死代码、无注释掉的旧逻辑、遵循最小改动。
- **复杂任务先方案**:≥3 文件/跨模块/数据模型变更/涉安全权限的任务,先输出方案(拆解、影响范围、验证路径)并通过规划门禁,确认后再动手。
- **重大改动展示**:涉及多文件、数据模型、接口签名变更时,向用户展示 diff 摘要后再继续。
- **异常必须报告**:发现文档与代码不一致、异常代码、缺失环境配置、可疑密钥或地址时,必须报告用户,禁止自行猜测或绕行。
- **少打扰用户**:技术决策 AI 自行决定并留痕;只在涉及业务语义时向用户确认;用业务语言解释做了什么,每完成一个可见里程碑就简报。
- **会话收尾总结**:重要开发会话结束时,输出三行总结(本次决策 / 踩坑 / 遗留事项与未验证项)。

## 四、规则分级与负面清单

- 每条规则按 `[必须]/[建议]/[禁止]` 分级执行;冲突时高优先级规则优先。
- 每个模块顶部设"负面清单(Do Not)",AI 动手前先自查负面清单。

## 五、常用命令

本项目为 `npm` + Angular CLI(非 pnpm monorepo),以 `package.json` scripts 为准:

- 启动开发:`npm start`(`ng serve` → http://localhost:4200/);单端直开 `/desktop/chat` / `/mobile/messages`
- 测试:`npm test`(`ng test`,Karma + Jasmine)
- 构建:`npm run build`
- 冒烟:待建(规划 `npm run build && node scripts/smoke-imhub.js`)
- 部署:待定(重建方案风险 R6)

## 六、模块规则(@import 引入,阶段视图 2/4:6 个)

@rules/01-沟通协作.md:沟通协作规范
@rules/02-开发流程与文档同步.md:开发流程与文档同步(PRD 阅读与执行/四向追溯矩阵)
@rules/03-项目架构与目录.md:项目架构与目录结构(fmode 平台目录)
@rules/05-数据访问与数据库.md:数据访问与数据范式(fmode-ng/FmodeSchema/范式要求)
@rules/18-UI设计规范.md:UI 设计规范(框架式:设计令牌/官方组件底座 ui-kit/防遮挡安全/可访问性)
@rules/19-需求分析与挖掘.md:需求分析与挖掘(本阶段仅用 ER 图规范部分)
@rules/21-评审与验收规范.md:评审与验收(强制评审节点/子代理评审员/评审报告闭环)

> **本项目调整说明**:规范包的阶段② 标准清单为 6 个模块(01/02/03/05/19/21)。
> 本项目因**用户明确要求"先出设计规范再写码"**(裁决 6),额外加挂 **@rules/18-UI设计规范.md**,共 7 个。
> 该加挂属本项目特有需求,已在操作追踪中留痕(2026-10-14 阶段①→② 切换)。

## 七、技能库(.claude/skills/,随包复制到客户项目)

规则与技能的分工:**规则保证下限**(本文件与 rules/ 每次会话自动加载);**技能提供上限**(按需触发,重参考内容与完整方法论,避免规则膨胀)。

- 本目录 `.claude/skills/` 内置 60 个技能,连同 `.claude/` 一起复制到客户项目即随行可用;
- 技能触发方式:对话中直接说明或 AI 按需自动路由;**需求挖掘环节的技能调用为强制**(见 19 模块规则 6);
- 模块中「重参考内容见技能 xxx」的条目,需要完整方法论时再加载对应技能。

## 八、环节-Skill 调用表(各环节需调用的技能,全阶段常驻)

| 环节 | 规范依据 | 必调/常用技能 |
|---|---|---|
| 1. 需求挖掘 | 19 模块 | brainstorming、grill-me、grilling、to-questionnaire、ralph、research、to-spec、to-tickets |
| 2. 建模与架构 | 19 规则 5;05 范式 | domain-modeling、codebase-design、prototype、writing-plans、planning-with-files |
| 3. 编码实现 | 06/07/13/16 | code、coding-guide、karpathy-guidelines、implement、dev-expert |
| 4. 测试验证 | 08 | tdd、test-driven-development、verification-before-completion |
| 5. 代码评审 | 21 | code-review、requesting-code-review、receiving-code-review、subagent-driven-development |
| 6. 调试诊断 | 08;15 | systematic-debugging、diagnosing-bugs、wait-what |
| 7. 执行交付 | 17;02 | executing-plans、dispatching-parallel-agents、finishing-a-development-branch、using-git-worktrees、handoff、claude-handoff |
| 8. UI 设计 | 18 | ui-new、ui-ux-pro-max、superdesign、ui-ux-design、ui-audit |
| 9. 工程基线 | 13;12 | setup-ts-deep-modules、migrate-to-shoehorn、improve-codebase-architecture、scaffold-exercises、setup-pre-commit |
| 治理(横切所有环节) | 09;10 | git-guardrails-claude-code、resolving-merge-conflicts、using-superpowers、writing-for-agents、writing-skills、teach |

## 九、本项目特有的适配说明(自规范包引入时新增,供后续维护者参考)

- **ui-kit 使用方式(与旧项目相反)**:包内 `ui-kit/` 正式要求 **Angular 20.3.x + Tailwind 3.4.x + FontAwesome ^7.3.1**。本项目 **Angular 20.3.0**,因此 **ui-kit 整目录接入、原生使用**,不再只是"参考实现"。接入方式:`ui-kit/src/app/ui/**` → `src/app/ui/`(596 文件,组件间有交叉引用,必须整目录复制);`styles.css` → `src/styles.uikit.css`;**`src/app/ui/**` 属底座,禁止修改**。
- **样式加载顺序**(见 `angular.json` 与 `src/styles.scss`)必须保持:`styles.uikit.css`(语义 token + Tailwind 三指令)→ FontAwesome → `styles.uikit.scss`(动画工具类)→ `styles.scss`(应用层兜底)。
- **业务样式一律进组件**;`src/styles.scss` 只放 html/body 基础与 iOS 输入字号修复等无法进组件的项。
- **规范包文件清单**(2026-10-14 引入):
  - `CLAUDE.md`(本文件,自 `stages/stage-1-需求挖掘-CLAUDE.md` 派生并预填)
  - `rules/`(21 模块全集) · `templates/`(25 模板) · `.claude/skills/`(60 技能) · `stages/`(4 阶段入口)
  - `ui-kit/`(官方组件底座)
  - `阶段视图切换指南.md` · `阶段意图与技能规则速查.md` · `规范包-CHANGELOG.md`
- **与源项目无关**:规范包来源仓库为另一个项目(通用 AI 陪练基座),其 `apps/`、`packages/` 等业务内容未引入;本项目 `docs/` 为 fmode-app-v2 自有内容。
- **与存量项目的关系**:`E:\work\fmode-app`(Angular 19)保留原地作为**迁移参考,只读不修改**。禁止把存量代码直接拷贝进 v2——所有实现必须按 v2 规范重写。
- **阶段② 为本项目新增环节**:用户明确要求"先出设计规范再写码"。阶段② 产出设计令牌定稿 / 组件规范 / 关键页面原型 / 双端布局规范,并设门禁:**设计规范未定稿不得进入编码**。