契约化多端架构：基于领域模型的Harness实践（中）

契约化多端架构基于领域模型的Harness实践中本文为《契约化多端架构基于领域模型的Harness实践》系列第 2 篇共 3 篇分为上中下三篇建议连续阅读。05 完整工作流说完领域模型接下来讲完整工作流。第一次接入项目时先跑 /project-init/project-init .它会做下面几件事情探测项目类型Roku / Next.js / Linux TV / ...根据_DETECTION_HINTS扫描项目生成 domain-mapping.json从 infrastructure-templates/ 读取对应类型的模板生成项目专属规范跑完这一步Harness 才算真正接入了你的项目。后续开发新需求时直接从需求输入开始需求输入 → 需求拆分 → 红队验证 → 验收标准 → 初始化存档 → 方案设计 → 编码开发 → → 观测回收5.1 项目初始化/project-init 流程5.1.1 接入步骤第一次接入项目时跑这个命令让 AI 把通用领域模型映射到你的项目。整个流程 5 步步骤干什么产出啥环境准备解析路径、判断单仓/Monorepo、读项目配置项目上下文变量MCP 配置问你要不要配 MCP连 TAPD、企微这些外部工具mcp.json可选项目探测扫描项目目录识别项目类型问你确认项目类型 特定配置领域映射逐层确认 Page / API / UI Module 的映射关系完整映射表内存中生成文件把前面收集的信息写成项目专属配置文件.codebuddy/ 目录下的所有文件领域映射这一步最关键分三层确认层AI干啥你要确认啥Page 层根据_DETECTION_HINTS找到每个页面对应的实际文件识别对了没漏了没API 层找到项目中实际的 API 调用代码跟通用定义做匹配接口路径对不对UI Module 层找到项目中实际的 UI 组件跟通用定义做匹配组件路径对不对三层都确认完AI 展示完整映射表你点头后才进入生成文件这一步。生成的文件清单文件内容config/domain-mapping.json领域模型映射表rules/domain-mapping.md映射文件的可读版rules/coding-standards.md编码规范从项目真实配置生成rules/test-standards.md测试规范patterns/idioms.md代码模式库如果项目没有 E2E 测试基础设施还会生成测试骨架。关键设计每一步都要你确认才继续。因为领域模型映射一旦错了后面所有 AI 生成的代码都会跟着错。5.1.2 流程图5.2 需求分析阶段需求分析分 5 步TAPD 拉取 → 需求拆分 → Figma 设计稿处理 → 红队验证 → 验收标准。5.2.1 第一步TAPD 拉取 父需求回溯 Figma 链接扫描AI 从 TAPD 拉取需求详情如果 description 为空会自动回溯父需求tapd有可能是需求下story步骤AI干啥你要确认啥解析输入识别是 TAPD 短 ID / 完整链接 / 自然语言-拉取需求调用 TAPD MCP获取 name / description / parent_id等字段-父需求回溯如果 description 为空且 parent_id存在自动拉取父需求-Figma 链接扫描从 description 中提取 Figma / 蓝湖 / Axure 链接Figma 链接对不对人员信息确认展示需求详情名称、描述、处理人、开发人员、测试人员人员信息对不对如果需求信息不足AI 会问你 3 个问题需求信息不完整需要补充几个关键点5.2.2 第二步需求拆分AI 把需求拆成一级任务、二级子任务输出 working/breakdown.md。步骤AI干啥你要确认啥两级拆分拆成一级任务功能模块 二级子任务技术动作拆分结果对不对工时预估每个一级任务预估工时0.5h ~ 1 天工时合理不写入文件按标准 Schema 写入 breakdown.md确认无误拆分原则一级任务用户可感知的完整功能单元半天 ~ 1 天可完成二级任务实现一级任务需要的具体代码动作1 ~ 3 小时可完成5.2.3 第三步Figma 设计稿处理D2C 精简模式如果有 Figma 链接AI 会调用 D2C Skill精简模式生成设计约束文档。步骤AI干啥产出啥结构梳理get_design_context get_metadata获取组件层级Figma 节点映射表素材整理get_variable_defs提取 Token 映射表Token 映射表存量排查codebase_search查已有组件、图标、样式变量存量复用清单产出格式追加到 breakdown.md 末尾5.2.4 第四步红队验证拆分完成后AI 会自己当对手找遗漏场景。维度检验目标示例数据边界API 返回的所有可能数据状态空数据、null、超大数据、网络超时交互边界用户可能的所有操作序列快速连点、加载中操作、离线操作环境边界不同运行环境下的兼容性SSR 兼容性、弱网环境、权限缺失找完展示给你【这里是我们linux-tv实际项目的演示图】请选择下一步操作[1] 立即修复所有 P0/P1 问题[2] 仅修复 P0 问题P1/P2 标记为技术债[3] 查看详细报告后再决定选完后会更新 breakdown.md把遗漏的场景补进去。5.2.5 第五步验收标准生成拆分确认后AI 基于 breakdown.md 生成 working/acceptance-criteria.md。从三个维度推导用例维度来源产出功能边界breakdown.md 一级任务每个功能 1 个 Happy Path 用例P0数据边界api-layer.json 的 errorHandling每个错误码 1 个异常用例P1交互边界ui-modules.json 的 interactions每个关键交互 1 个交互用例P0/P1生成示例生成后展示给你确认确认后才继续。关键设计每一步都要你确认才继续。因为需求拆分一旦错了后面所有 AI 生成的代码都会跟着错。5.2.6 流程图5.3 方案设计流程方案设计分 2 步代码分析 → 方案规划。5.3.1 第一步代码分析Reader编码前AI 先让 code-analyzerreader上场做情报收集。reader 只干一件事编码前只读情报收集。步骤AI干啥产出啥领域模型分析读 domain-mapping.json、pages.json、api-layer.json涉及哪些页面/API/组件代码扫描用 codebase_search找可复用组件、hooks、工具函数可复用资产清单惯用法识别读 patterns/idioms.md标注相关条目相关惯用法列表技术风险识别扫描相关文件找 SSR 兼容性陷阱、跨包依赖等技术风险清单产出格式通过 send_message发给 planner[READER_DONE] task_id2.1关键设计reader 不修改任何源码只收集情报。情报报告会传给 planner用来做方案。5.3.2 第二步方案规划Plannerreader 收集完情报后AI 让 code-plannerplanner上场出方案。planner 只干一件事基于情报产出 impl-plan-{taskId}.md不修改源码。步骤AI干啥产出啥读取基础资料读 breakdown.md、session-state.json、acceptance-criteria.md、adversary-report.md任务上下文加载记忆层读 patterns/anti-patterns.md 和 patterns/idioms.md禁止事项清单 惯用法参考代码库探查用 codebase_search找可复用组件、hooks、工具函数可复用资产清单Figma 设计约束解析如有读 breakdown.md 末尾的设计约束章节调用 D2C 精简模式获取详细结构附录 AFigma 设计约束起草方案按标准 Schema 逐节填写 impl-plan-{taskId}.md完整实现方案写入文件把方案写成 working/impl-plan-{taskId}.md方案文件展示审批展示方案摘要等你审批你的审批结论方案文件标准Schema这里不详细贴了说白了就是详细描述代码开发的技术方案