malganiswu/red-bean-nian-gao/red-bean-nian-gao-development-workflow

red-bean-nian-gao 开发流程

本 Skill 是本仓开发流程的唯一事实来源。

通用流程（一次开发的产出 plan / decision / design 及触发判据、三条红线、各自骨架、验收条件去向、

变更分级、六阶段、执行纪律、文档影响审查、交付核验）在

`references/common.md`——与 Runtime SDK 仓 red-bean-qing-tuan 中的同名

文件逐字相同，由 scripts/check-shared-files.mjs 校验。本文件只写本仓特有的流程落点。

开始任务前完整读取两份：本文件 + `references/common.md`。

本仓特有的流程落点

本仓有四个 workspace，各自特有的流程与测试分层写在：

• plan 的落点：跨 workspace 落仓库根 docs/plans/<date>-<feature>.md；仅影响单个 workspace 时

落 backend/docs/plans/ 或 frontend/docs/plans/。

• 模块级 vs 非模块级：新增业务 Module、修改跨模块公开接口、新增 migration、新增 API 端点、

新增外部依赖属模块级，必须走完六阶段。

• 交付前跑一条 `make verify`，它会依次跑四个 workspace 的验证；逐项清单见

`AGENTS.md`「门禁」。

• 改 Runtime SDK 的公开行为或接入方式时，本仓按 runtime.lock 消费它：先改 SDK 仓并提交，

本仓 bump lock 时逐字比对会强制同步。

UI 变更：mock 先行（本仓特有）

改动涉及界面（新增页面、组件、交互或视觉）时，在通用六阶段的阶段 1 需求与阶段 2 计划 之间多两步。任务步骤与组件状态在每一步上对齐——本节是组件状态定义的唯一事实来源：

状态准入条件：

• proposal 无门槛——草稿即可，多个候选并存，不对前端承诺
• accepted = 人工确认 + token 与交互口径冻结
• implemented = 真实组件、Showcase、正式消费方三者一致
• deprecated = 已标出替代方案与移除窗口，不再新增消费方
• removed = 无正式引用 + 无文档残留 + 通过漂移检查，三条同时成立

只有两次跃迁需要人介入：proposal → accepted（确认方向）与 implemented 前的目视验证。

• mock 是草稿，不是产出物：文件只落在本地 design-system/previews/（已被 .gitignore 忽略）；

确认结论写进 plan 或提交说明，草稿本身不留档。

• 顺序不可颠倒：plan 必须写已确认的视觉方向；design-system 先于前后端开发，前端只能引用

已入册的组件。

• 不是所有 UI 改动都要 mock：已有设计约定、预期行为清楚的简单修复可直接实施；涉及新的

外观或交互方案选择时，先问开发者是否需要 mock，再按答复执行。

• 改哪一层决定从哪起手：改共享组件、token 或基础视觉语言 → 先在 Design System 更新真实组件与

Showcase 并验证，再检查正式前端；改产品特有的页面级业务组件 → 直接在前端做，复用已有的 Design System 组件与 token，不为走流程而在 Design System 里复制一份。两类都要定义验收场景、 执行适当测试、目视验证，并审查设计文档影响。

• 非 UI 改动不走这条（纯后端、纯文档、纯配置），直接走通用六阶段。

Design System 资产变更分级（本仓特有）

评审记录：影响现有视觉的提案必须在提交或计划文档中记录问题证据、确认结果、受影响组件、 迁移范围和验证结果。Preview 文件本身不入库，留档的是确认记录而非草稿；没有确认记录的 Preview 不得被视为正式规范。

资产的唯一定位（token / 组件 / Showcase / 业务容器各归哪）见 `../../design-system/AGENTS.md`。

测试先行分层（本仓特有）

TDD 约束的是行为增量，不要求为每一行实现代码单独写测试。重构应在已有测试保持绿色的前提下进行。