27 autonomous project work guide

SmartFarm 自主设计工作指引

本文档规定 Codex 在 SmartFarm V1 开发前设计阶段如何持续工作、作出决定、维护证据和恢复上下文。详细进度统一查看 26-pre-development-master-checklist.md。

一、启动读取顺序

每次新会话、上下文压缩或任务恢复后，按顺序读取：

1. 26-pre-development-master-checklist.md：当前状态、活动队列、阻塞和完成定义。
2. Home.md：完整文档目录和推荐评审顺序。
3. 12-v1-business-decisions-and-glossary.md：唯一业务规则来源。
4. 24-g3-g4-decision-register.md：技术和 UI 决策状态。
5. 与当前活动任务直接相关的专题文档。

不得仅依赖聊天历史恢复任务。

二、当前阶段

开发前设计已完成 Codex 自主预审，当前处于“研发启动会准备”阶段，仍不是业务代码开发阶段。除非项目方明确切换目标并确认启动基线，否则继续遵守本节禁止项。

允许：

• 只读源码、数据库、运行页面、接口和 Figma。
• 编辑项目文档、工作指引、项目 Skill 和 Figma。
• 做非破坏性的文档、布局、链接和一致性验证。

禁止：

• 编写或修改智慧农业业务代码。
• 写入数据库业务数据或修改演示业务配置。
• 执行不可逆操作。
• 提前创建与现有 CRMEB 重复的基础组件或业务框架。

三、标准工作循环

每个任务按以下顺序执行：

1. 从 26 读取当前活动项和完成证据。
2. 读取对应业务决策、页面、数据、API、事件、文件和测试文档。
3. 使用当前源码、只读数据库或运行页面验证现状事实。
4. 记录发现的冲突、缺口、现状缺陷和推荐决定。
5. 按风险最低且最符合 CRMEB 的方案更新专题文档。
6. 把决定写入 12、24 或 26，不得只留在聊天中。
7. 更新所有受影响的页面、字段、API、文件和测试映射。
8. 运行 Markdown 链接、表格、术语、路径和差异检查。
9. 更新 26 的状态、证据、活动队列和变更记录。

四、自主决策规则

可自动确认

• 不改变商业模式的技术实现方式。
• CRMEB 已有模式能够明确证明的复用方案。
• 可逆、低风险且不影响现有商城语义的页面和文件组织。
• 命名、目录、编号、文档结构和设计交付顺序。
• 可以通过源码、数据库和运行页面验证的现状结论。

需要证据后确认

• 订单、支付、退款、库存和账本扩展点。
• 商品规格身份、库存锁定和结算入账接口。
• 服务端认证、数据范围和移动布局。
• 第三方 SDK 在多端的兼容性。
• 可能扩大普通商城回归范围的公共重构。

这些事项先标记“待专项验证”，完成只读验证后再自动确认。

必须询问项目方

仅限持续目标规定的五类情况：

1. 商业模式发生分叉。
2. 需要付费服务。
3. 需要代码、数据库写入或不可逆操作。
4. 现有证据无法判断。
5. 需要验证码、授权或人工审批。

五、决策记录格式

自动决定写入 26，技术决定写入 24，业务规则写入 12。

每条至少记录：

编号
主题
事实依据
最终决定
主要理由
替代方案
影响文档
验证状态

禁止用“先这样”“开发时再看”“大概复用”作为最终结论。

六、现状与需求分离

所有内容必须区分：

• 现状事实：已经由源码、数据库或运行页面证明。
• 现状缺陷：CRMEB 当前已有问题，单独建立修复任务。
• V1 业务规则：项目已经确认的产品行为。
• 建议方案：尚待证据或评审的设计。
• 已确认技术决定：证据、理由和影响已经完整。

不能把 Figma 变量、候选目录、建议表名或页面草案写成已经存在的源码能力。

七、CRMEB 复用原则

• 普通商城、商品、订单、支付、物流、售后、商户和财务底座优先复用。
• 云仓只复用普通秒杀的展示和通用交易外壳，不复用其持仓、批次和结算语义。
• 用户端优先组合现有 uni-app 页面和组件，不复制大型页面形成平行版本。
• 平台和商户端保持 Vue 2、Element UI 和当前 CRMEB 密度。
• 服务端保留 PC 客服壳，移动现场入口必须有独立布局边界。
• 新增领域能力必须说明为什么现有组件、接口或数据结构无法满足。

八、源码调查规则

• 仓库存在 .codegraph/ 时，理解符号、调用链和影响范围优先使用 CodeGraph。
• 精确文本、配置、路由和文件清单使用 rg。
• 数据库只做只读查询，并记录库、表、筛选口径和查询日期。
• 浏览器核验记录页面地址、使用角色、运行状态和截图。
• 结论必须引用真实文件、菜单、配置或运行证据。

九、Figma 工作规则

• 正式文件固定为 SmartFarm V1 - CRMEB Baseline & Product Design。
• 先完成参考、令牌、字段、状态、组件复用映射和低保真，再做高保真。
• 不整体重做 CRMEB，不使用与当前系统割裂的模板。
• 每个 Frame 使用 页面编号 / 页面名称 / 状态 / 视口。
• 每个关键流程建立独立 Prototype Flow。
• 设计完成后必须检查桌面、H5、小程序安全区、长文本和金额溢出。
• 当前 RC 入口固定为 08 Handoff & Assets 的 Handoff / SmartFarm V1 RC-1（节点 59:2），详细状态见 figma-state-smartfarm-v1.json。
• 当前连接的 Figma MCP 不支持原生版本历史保存；不得编造版本 ID，启动会需要时由文件成员保存同名原生版本。
• 登录密码、验证码、访问令牌和生产密钥不得写入 Figma 或文档。

十、验证规则

每轮文档工作至少检查：

• 本地 Markdown 链接存在。
• Markdown 表格列数一致。
• 页面编号、决策编号、状态码和目录名无冲突。
• 新旧业务口径搜索无残留。
• git diff --check 无空白错误。
• 未意外修改业务代码或数据库。

Figma 工作还必须检查：

• Frame 无重叠和裁切。
• 文本、金额和状态不溢出。
• 真实参考与建议设计分区明确。
• 原型连线只指向真实可执行动作。

十一、安全与凭据

• 不在文档、源码、Skill、Figma、日志或回复中保存或重复账号密码。
• 使用官方 OAuth 或已经建立的安全连接。
• 涉及外部写入、付费资源或高风险授权时，按持续目标的询问条件处理。

十二、完成与交接

一次任务完成只表示主清单中的某个项目取得证据，不表示持续目标完成。

当前 26-pre-development-master-checklist.md 已记录 G1-G5 自主预审通过。后续会话恢复时：

1. 若项目方仍要求完善文档，继续以 26 的证据和变更控制为准。
2. 若项目方明确进入开发，先完成 G6 人工启动会、RC 确认和首轮 Ready 任务认领。
3. 不因上下文压缩重新设计已冻结口径；新需求必须按变更单评估影响。