<<<<<<< HEAD # Workspace Constitution ## SIMA × AI 协作最高规约（CLAUDE.md） > 本文件定义本项目开发、协作、迭代行为的最高规范**。 > 任何未遵循本规约的方法、流程或输出，视为无效或需重做。 --- ## -1. 技能精神宪章（Spirit） > 详见 [skills/SPIRIT.md](skills/SPIRIT.md) ### 第一纲领：于细微处发大隙 > **这是所有 SIMA Skills 必备的品质。** **核心要求**： - 产品文档必须穷举所有分支、状态、边界条件 - 必须列举所有字段取值、配置项、角色权限 - 必须覆盖"在 XX 状态/角色/场景下"的不同行为路径 - 文档中不能有未展开的"等情况"、"多种模式"等模糊表述 **验证清单**（每次输出前自问）： - [ ] 是否有分支场景我没有追踪？ - [ ] 是否有字段枚举我没有列举完整？ - [ ] 是否有"用户操作后"的不同路径我没有探索？ - [ ] 是否有"不同角色下"的行为差异我没有说明？ ### 第二纲领：工具先行，深入证据，并行攻坚 > **不做字面功夫，要深入实质。调用一切能调用的工具，团结一切可团结的力量。** **核心要求**： - **工具先行**：手上有什么 MCP 就用什么 MCP，能读资产就读资产 - **深入证据**：不在假设上构建，要读 CodeMap、DomainMap、Runtime、用户资料 - **并行攻坚**：该发动多个 Agent 就开多个，独立任务并行执行 - **团结力量**：需要找资料就找资料，需要花力气就花力气，攻坚克难不避艰辛 **验证清单**（每次执行任务前自问）： - [ ] 我是否已盘点了手上所有可用资产？（CodeMap、DomainMap、Runtime、Chrome DevTools...） - [ ] 我是否在用证据深入分析，而非基于假设？ - [ ] 我是否可以并行启动多个 Agent/任务？ - [ ] 我是否该花力气去找/采集新证据？ ### 第三纲领：实践才能检验真理 > **需求文档和设计稿充满逻辑推理，但不是事实。Runtime 才是真相 —— 界面、字段、真实的数据和行为。** **核心要求**： - **Runtime 是唯一的事实来源**：需求是"应该如何"，Runtime 是"实际如何" - **一切结论必须有证据**：截图、CodeMap、DomainMap、用户提供的资料 - **快照是证据的载体**：所有 Runtime 探索必须留下截图/snapshot 作为"呈堂证供" - **无证据则标记为假设**：没有证据验证的结论，必须在文档中标记为 `[ASSUMPTION]` **验证清单**（每次输出结论前自问）： - [ ] 我的结论有证据吗？ - [ ] 我是否用 chrome-devtools 截图验证了页面？ - [ ] 不同场景下的差异是否都有证据了？ - [ ] 截图/证据是否保存到 materials/ 目录作为存档？ - [ ] 没有证据的结论是否标记为 `[ASSUMPTION]`？ **文档标记规范**： ```markdown > **验证状态**: ✅ 已验证 / ⚠️ 部分验证 / ❌ 未验证（假设） > **证据位置**: materials/xxx.png 或 [CODEMAP:assets/codemap/...] ``` --- ## 0. 本 Workspace 的根本目标（Mission） 本 Workspace 的目标不是"生成若干产品文档"， 而是： > **构建一套可复用的、可演化的产品文档生成方法与 Skills， 使 AI 能稳定地产出接近专业 PM 水平的 PRD、FRD、DAR 等产品文档。** 最终交付物包括但不限于： - 高质量产品文档（PRD/FRD/DAR） - 一组或多组可复用的 PM Assist Skills - 对应的方法论、流程与验证标准 --- ## 1. 核心方法论（Methodology） ### 1.1 WWH / PDCA —— 做事的基本法则 #### WWH（What / Why / How） **What（现状与目标澄清）** 必须明确回答： - **需求是什么**（原始需求、业务目标） - **文档类型是什么**（PRD / FRD / DAR） - **已有资料是什么**（CodeMap / DomainMap / Runtime / 用户资料） What 阶段只做「描述与对照」，不做方案设计。 --- **Why（差距与根因洞察）** 必须回答： - 为什么要做这个需求？ - 当前系统有什么问题或缺陷？ - 业务目标是什么？风险是什么？ Why 必须覆盖（但不限于）： - 业务背景 - 用户痛点 - 技术现状 - 风险识别 Why 阶段**不允许直接给解决方案**。 --- **How（方案设计与实施路径）** 基于 Why 的洞察，回答： - 通过什么方案、流程、配置，才能达成需求目标？ - 不同角色、不同端、不同状态下的处理逻辑是什么？ --- ### 1.2 PDCA（戴明环） 本 Workspace 内所有任务，**必须声明自己当前所处阶段**： - **P — Plan**：基于 WWH 制定文档生成计划，明确证据采集清单 - **D — Do**：生成、重构、改写具体文档片段，引用证据 - **C — Check**：对照模板、验证证据充足性、检查逻辑一致性 - **A — Act**： - 固化有效方法 - 修正无效路径 - 抽象并沉淀为 Skill > ❗ 未声明 PDCA 阶段的输出，视为无效输出。 --- ## 2. Workspace 资源与路径认知（Resource Awareness） ### 2.1 基本原则 - 本 Workspace 中的所有资源，都必须被明确认知其： - 含义 - 作用 - 使用时机 - 阅读深度要求 --- ### 2.2 资源使用方式约定 - **CodeMap**（`assets/codemap/`） - 含义：代码结构、字段定义、调用链 - 使用场景：理解系统现状、技术实现细节 - 阅读方式：定向深挖到字段/分支层级 - **强制要求**：PRD/FRD 必须至少引用 1 个 CodeMap 证据 - **DomainMap**（`assets/domainmap/`） - 含义：业务概念、流程、规则、分支证据 - 使用场景：业务逻辑、领域建模 - 阅读方式：精读关键节点 - **强制要求**：PRD/FRD 必须至少引用 1 个 DomainMap 证据 - **RuntimeScan**（`assets/runtime-scan/`） - 含义：真实系统运行态、页面截图、接口数据 - 使用场景：验证实际行为、补全流程闭环 - 阅读方式：问题导向式精读 - **用户提供资料**（`materials/`） - 含义：原型、截图、文档、链接 - 使用场景：需求澄清、设计验证 - 阅读方式：全文精读并摘要 --- ## 3. 标准推进流程（From 需求到文档） ### Step 0：阶段声明（强制） 每一次输出前，必须明确声明： - 当前处于 What / Why / How - 当前处于 PDCA 的哪个阶段 --- ### Step 1：文档类型分流（What） 根据用户初始描述进行分支；不确定就追问： - **PRD**：新需求、流程优化、产品规划、业务方案 - **FRD**：具体功能实现、接口/数据/流程细节 - **DAR**：线上缺陷、事故复盘、根因分析 > 选择后加载对应模板： - PRD → `skills/pmassist/references/prd.md` - FRD → `skills/pmassist/references/frd.md` - DAR → `skills/pmassist/references/dar.md` --- ### Step 2：工作目录与资料采集（Plan） 必须同时具备： 1. 项目工作目录（`./{项目简称}-{YYYYMMDD-HHMM}`） 2. 资料索引文件（`materials_index.md`） 3. 证据采集计划（需要读取的 CodeMap / DomainMap / Runtime） 输出形式必须是**结构化清单**。 --- ### Step 3：证据深挖与分析（Do） 原则： - **不允许基于假设生成文档** - 必须至少读取并引用以下层级中的每一类至少 1 个证据： - CodeMap：前端结构、后端字段、调用链 - DomainMap：领域证据、分支证据 - Runtime：页面截图、接口数据 通过多轮对话不断调优： - 结构 - 证据引用 - 逻辑推理 - 表达精度 --- ### Step 4：质量验证（Check） 必须回答： - 哪些章节已有证据支撑？ - 哪些章节是 `[ASSUMPTION]`？ - 证据→章节映射表是否完整？ - 是否包含必备的图表（至少 1 个 mermaid 图 + 1 个表）？ --- ### Step 5：Skill 抽象与固化（Act） 从成功文档中反向提炼： - 输入条件 - 关键推理步骤 - 输出结构 - 使用前置条件 最终产出： > **可复用的 PM Assist Skill，而非单次生成结果。** --- ## 4. 真实环境访问与事实获取规范（Runtime Access Rule） ### 4.1 基本原则 当分析或生成内容 **依赖真实系统行为、运行态信息或正式环境数据** 时： > **禁止仅基于推测、历史文档或假设进行推理。** 必须通过可验证的方式获取事实信息。 --- ### 4.2 指定工具约束（强制） 当需要访问以下内容时： - 系统正式 Runtime 环境 - Web 管理后台 / 前台页面 - 实际页面流程、字段、交互 - 真实接口返回或运行结果 **必须优先使用以下工具：** > **chrome-devtools MCP** 用途包括但不限于： - 页面结构与 DOM 分析 - 网络请求与接口行为观察 - 实际字段、状态、流程验证 - 运行态与设计文档差异比对 --- ### 4.3 使用时机声明（强制） 在使用 chrome-devtools MCP 前，必须明确声明： - 为什么需要访问真实环境 - 当前处于 PDCA 的哪个阶段 - 本次访问的目标是什么（验证 / 补全 / 对照） > ❗ 未经声明即进行的推理性输出，视为不可靠输出。 --- ### 4.4 事实优先级声明 当 **运行态事实** 与 **既有文档 / 推断结论** 不一致时： > **以 Runtime 事实为准，文档必须修正。** --- ## 5. 文档资产清单机制（Assets Index Rule） ### 5.1 启动阶段强制动作（Project Bootstrap Rule） 在本 Workspace **首次启动或新一轮文档生成开始前**， 必须先生成一个统一的文档资产清单文件： > **`materials_index.md`** 该文件是 Workspace 的**认知索引入口**。 --- ### 5.2 materials_index.md 的核心目的 - 快速建立对已有资料的整体认知 - 避免重复读取与无效上下文注入 - **显著降低 Token 消耗** - 为后续 Plan / Do 阶段提供"可定位证据来源" --- ### 5.3 materials_index.md 必须包含的内容 `materials_index.md` 至少应包含以下结构化信息： - 资料 ID（`SRC-001`, `CODEMAP-001` 等） - 资料名称 / 路径 - 类型（CodeMap / DomainMap / Runtime / 用户资料） - **简要说明（1–3 行）** - 推荐使用场景（What / Why / How / Check） - 建议阅读深度： - 掠读（Scan） - 精读（Deep Read） - 仅定位（Reference） --- ### 5.4 使用约束 - 在文档生成过程中： - **优先引用 materials_index.md 中的资源** - 明确指出使用的是哪一项资产（`[SRC-001]`, `[CODEMAP:...]`） - 当新增重要资源时： - 必须同步更新 materials_index.md > ❗ 未进入 materials_index.md 的重要资源，视为"不可被稳定复用的知识"。 --- ## 6. 证据标注与映射规则（Evidence Mapping Rule） ### 6.1 强制要求 每个关键结论、数据、规则必须标注来源： - **CodeMap 证据**：`[CODEMAP:assets/codemap/frontend/routes.yaml]` - **DomainMap 证据**：`[DOMAINMAP:assets/domainmap/branch_evidence.yaml]` - **Runtime 证据**：`[RUNTIME:screenshot_001.png]` - **用户资料**：`[SRC-001]` - **无证据**：`[ASSUMPTION]` --- ### 6.2 证据→章节映射表（强制） 在 PRD/FRD/DAR 中必须维护"证据映射表"： | 章节 | 关键结论 | 证据来源 | |-----|---------|---------| | 2.1 核心概念定义 | 预估里程定义 | [CODEMAP:dataobjects/Order.yaml] | | 2.2 双轨计费生效条件 | 商户配置逻辑 | [DOMAINMAP:branch_evidence.yaml] | | 3.1 下单流程 | 路线获取逻辑 | [RUNTIME:screenshot_002.png] | --- ### 6.3 证据缺口清单（Check 阶段强制输出） 若章节无法绑定证据，必须显式标记并列入"证据缺口清单"： | 章节 | 缺失证据 | 影响 | 下一步 | |-----|---------|-----|-------| | 4.2 外协订单处理 | BC段里程计算规则 | 无法验证结算逻辑 | 需 Runtime 验证或用户确认 | --- ## 7. 问题清单与问答闭环（Question List Rule） ### 7.1 强制要求 每轮 PDCA 的 Plan / Do 阶段，必须生成问题清单： - **P0 阻塞问题**（必须回答，否则不进入下轮） - **P1 关键决策问题**（影响方案设计） - **P2 细节确认问题**（影响细节完整性） 问题格式模板（`questions/round_N.yaml`）： ```yaml round: 1 questions: - id: Q1-1 priority: P0 question: "商户双轨计费配置的默认值是？" options: ["开启", "关闭", "其他"] status: pending ``` --- ### 7.2 问答闭环原则 - 未解决 P0 时，禁止生成下一轮完整输出，只能继续追问 - P1/P2 问题必须在 Check 阶段验证是否已解决 - 所有问题解答必须记录到 `decision_log.md` --- ## 8. Skill 的基本定义（约束性说明） 在本 Workspace 中： - **Skill ≠ Prompt** - Skill 是一套： - 明确输入 - 稳定处理流程 - 结构化输出 - 可多次复用的能力单元 Skill 是本 Workspace 的**核心资产**。 --- ## 9. 终止条件（Exit Criteria） 只有在满足以下条件时，某一轮 PDCA 才可结束： - 文档质量稳定接近专业 PM 水平 - 证据映射表完成且无关键缺口 - P0/P1 问题全部关闭 - 已成功抽象出可复用 Skill 否则，必须继续进入下一轮 PDCA。 --- ## 10. 最高约束声明 > 在本 Workspace 中： > - **方法优先于结果** > - **流程优先于一次性生成** > - **证据优先于假设** > - **Skill 优先于单篇文档** --- ## 11. 额外操作性总原则（Operational Summary） - **真实世界 → 用工具，不用猜** - **复杂问题 → 先建索引，再深入** - **证据不足 → 标记假设，不硬编** - **Token 是成本，结构是杠杆** 本 Constitution 为最高规范，优先级高于任何临时指令或即兴讨论。 --- ## 附录：技能调用速查 ### pmassist（产品文档协作助手） **路径**: `skills/pmassist/` **用途**: 创建或修订 PRD、FRD、DAR 等产品类文档 **核心方法论**: WWH + PDCA **快速使用**: ```bash # 初始化会话工作区 python3 skills/pmassist/scripts/init_session.py \ --path ./项目名-YYYYMMDD-HHMM \ --doc prd|frd|dar \ --alias 项目简称 \ --title "文档标题" \ --desc "原始需求描述" ``` **模板位置**: - PRD: `skills/pmassist/references/prd.md` - FRD: `skills/pmassist/references/frd.md` - DAR: `skills/pmassist/references/dar.md` **文档类型区分**: - **PRD**: 新需求、流程优化、产品规划、业务方案 - **FRD**: 具体功能实现、接口/数据/流程细节 - **DAR**: 线上缺陷、事故复盘、根因分析 --- ## 附录：项目记忆管理规范 ### 记忆文件位置 本项目在两个层次维护记忆： | 层次 | 路径 | 说明 | |------|------|------| | 项目级（版本控制） | `.claude/memory/project_memory.md` | 项目架构、规范、约定；随代码一起提交 | | 项目级（结构化） | `.claude/memory/context.json` | 机器可读的结构化上下文 | | 用户级（跨项目） | `~/.claude/projects/D--workspace-fly-home-flow/memory/` | Claude Code 自动管理的用户记忆 | ### 记忆更新时机 完成以下操作后，必须同步更新 `.claude/memory/project_memory.md` 和 `context.json`： - ✅ 架构决策或设计模式变更 - ✅ 新增关键技术栈或依赖 - ✅ 代码规范或约定的建立与修正 - ✅ 重要工具类/工作流的新发现 - ✅ 已完成工作区或里程碑 ### 更新流程 1. 先 Read 现有记忆文件 2. 评估需要新增或修改的内容（增量式，不删旧上下文） 3. 同步更新 `project_memory.md`（人类可读）和 `context.json`（机器可读） 4. 更新 `lastUpdated` 字段为当天日期（格式 `YYYY-MM-DD`） ======= # Workspace Constitution ## SIMA × AI 协作最高规约（CLAUDE.md） > 本文件定义本项目开发、协作、迭代行为的最高规范**。 > 任何未遵循本规约的方法、流程或输出，视为无效或需重做。 --- ## -1. 技能精神宪章（Spirit） > 详见 [skills/SPIRIT.md](skills/SPIRIT.md) ### 第一纲领：于细微处发大隙 > **这是所有 SIMA Skills 必备的品质。** **核心要求**： - 产品文档必须穷举所有分支、状态、边界条件 - 必须列举所有字段取值、配置项、角色权限 - 必须覆盖"在 XX 状态/角色/场景下"的不同行为路径 - 文档中不能有未展开的"等情况"、"多种模式"等模糊表述 **验证清单**（每次输出前自问）： - [ ] 是否有分支场景我没有追踪？ - [ ] 是否有字段枚举我没有列举完整？ - [ ] 是否有"用户操作后"的不同路径我没有探索？ - [ ] 是否有"不同角色下"的行为差异我没有说明？ ### 第二纲领：工具先行，深入证据，并行攻坚 > **不做字面功夫，要深入实质。调用一切能调用的工具，团结一切可团结的力量。** **核心要求**： - **工具先行**：手上有什么 MCP 就用什么 MCP，能读资产就读资产 - **深入证据**：不在假设上构建，要读 CodeMap、DomainMap、Runtime、用户资料 - **并行攻坚**：该发动多个 Agent 就开多个，独立任务并行执行 - **团结力量**：需要找资料就找资料，需要花力气就花力气，攻坚克难不避艰辛 **验证清单**（每次执行任务前自问）： - [ ] 我是否已盘点了手上所有可用资产？（CodeMap、DomainMap、Runtime、Chrome DevTools...） - [ ] 我是否在用证据深入分析，而非基于假设？ - [ ] 我是否可以并行启动多个 Agent/任务？ - [ ] 我是否该花力气去找/采集新证据？ ### 第三纲领：实践才能检验真理 > **需求文档和设计稿充满逻辑推理，但不是事实。Runtime 才是真相 —— 界面、字段、真实的数据和行为。** **核心要求**： - **Runtime 是唯一的事实来源**：需求是"应该如何"，Runtime 是"实际如何" - **一切结论必须有证据**：截图、CodeMap、DomainMap、用户提供的资料 - **快照是证据的载体**：所有 Runtime 探索必须留下截图/snapshot 作为"呈堂证供" - **无证据则标记为假设**：没有证据验证的结论，必须在文档中标记为 `[ASSUMPTION]` **验证清单**（每次输出结论前自问）： - [ ] 我的结论有证据吗？ - [ ] 我是否用 chrome-devtools 截图验证了页面？ - [ ] 不同场景下的差异是否都有证据了？ - [ ] 截图/证据是否保存到 materials/ 目录作为存档？ - [ ] 没有证据的结论是否标记为 `[ASSUMPTION]`？ **文档标记规范**： ```markdown > **验证状态**: ✅ 已验证 / ⚠️ 部分验证 / ❌ 未验证（假设） > **证据位置**: materials/xxx.png 或 [CODEMAP:assets/codemap/...] ``` --- ## 0. 本 Workspace 的根本目标（Mission） 本 Workspace 的目标不是"生成若干产品文档"， 而是： > **构建一套可复用的、可演化的产品文档生成方法与 Skills， 使 AI 能稳定地产出接近专业 PM 水平的 PRD、FRD、DAR 等产品文档。** 最终交付物包括但不限于： - 高质量产品文档（PRD/FRD/DAR） - 一组或多组可复用的 PM Assist Skills - 对应的方法论、流程与验证标准 --- ## 1. 核心方法论（Methodology） ### 1.1 WWH / PDCA —— 做事的基本法则 #### WWH（What / Why / How） **What（现状与目标澄清）** 必须明确回答： - **需求是什么**（原始需求、业务目标） - **文档类型是什么**（PRD / FRD / DAR） - **已有资料是什么**（CodeMap / DomainMap / Runtime / 用户资料） What 阶段只做「描述与对照」，不做方案设计。 --- **Why（差距与根因洞察）** 必须回答： - 为什么要做这个需求？ - 当前系统有什么问题或缺陷？ - 业务目标是什么？风险是什么？ Why 必须覆盖（但不限于）： - 业务背景 - 用户痛点 - 技术现状 - 风险识别 Why 阶段**不允许直接给解决方案**。 --- **How（方案设计与实施路径）** 基于 Why 的洞察，回答： - 通过什么方案、流程、配置，才能达成需求目标？ - 不同角色、不同端、不同状态下的处理逻辑是什么？ --- ### 1.2 PDCA（戴明环） 本 Workspace 内所有任务，**必须声明自己当前所处阶段**： - **P — Plan**：基于 WWH 制定文档生成计划，明确证据采集清单 - **D — Do**：生成、重构、改写具体文档片段，引用证据 - **C — Check**：对照模板、验证证据充足性、检查逻辑一致性 - **A — Act**： - 固化有效方法 - 修正无效路径 - 抽象并沉淀为 Skill > ❗ 未声明 PDCA 阶段的输出，视为无效输出。 --- ## 2. Workspace 资源与路径认知（Resource Awareness） ### 2.1 基本原则 - 本 Workspace 中的所有资源，都必须被明确认知其： - 含义 - 作用 - 使用时机 - 阅读深度要求 --- ### 2.2 资源使用方式约定 - **CodeMap**（`assets/codemap/`） - 含义：代码结构、字段定义、调用链 - 使用场景：理解系统现状、技术实现细节 - 阅读方式：定向深挖到字段/分支层级 - **强制要求**：PRD/FRD 必须至少引用 1 个 CodeMap 证据 - **DomainMap**（`assets/domainmap/`） - 含义：业务概念、流程、规则、分支证据 - 使用场景：业务逻辑、领域建模 - 阅读方式：精读关键节点 - **强制要求**：PRD/FRD 必须至少引用 1 个 DomainMap 证据 - **RuntimeScan**（`assets/runtime-scan/`） - 含义：真实系统运行态、页面截图、接口数据 - 使用场景：验证实际行为、补全流程闭环 - 阅读方式：问题导向式精读 - **用户提供资料**（`materials/`） - 含义：原型、截图、文档、链接 - 使用场景：需求澄清、设计验证 - 阅读方式：全文精读并摘要 --- ## 3. 标准推进流程（From 需求到文档） ### Step 0：阶段声明（强制） 每一次输出前，必须明确声明： - 当前处于 What / Why / How - 当前处于 PDCA 的哪个阶段 --- ### Step 1：文档类型分流（What） 根据用户初始描述进行分支；不确定就追问： - **PRD**：新需求、流程优化、产品规划、业务方案 - **FRD**：具体功能实现、接口/数据/流程细节 - **DAR**：线上缺陷、事故复盘、根因分析 > 选择后加载对应模板： - PRD → `skills/pmassist/references/prd.md` - FRD → `skills/pmassist/references/frd.md` - DAR → `skills/pmassist/references/dar.md` --- ### Step 2：工作目录与资料采集（Plan） 必须同时具备： 1. 项目工作目录（`./{项目简称}-{YYYYMMDD-HHMM}`） 2. 资料索引文件（`materials_index.md`） 3. 证据采集计划（需要读取的 CodeMap / DomainMap / Runtime） 输出形式必须是**结构化清单**。 --- ### Step 3：证据深挖与分析（Do） 原则： - **不允许基于假设生成文档** - 必须至少读取并引用以下层级中的每一类至少 1 个证据： - CodeMap：前端结构、后端字段、调用链 - DomainMap：领域证据、分支证据 - Runtime：页面截图、接口数据 通过多轮对话不断调优： - 结构 - 证据引用 - 逻辑推理 - 表达精度 --- ### Step 4：质量验证（Check） 必须回答： - 哪些章节已有证据支撑？ - 哪些章节是 `[ASSUMPTION]`？ - 证据→章节映射表是否完整？ - 是否包含必备的图表（至少 1 个 mermaid 图 + 1 个表）？ --- ### Step 5：Skill 抽象与固化（Act） 从成功文档中反向提炼： - 输入条件 - 关键推理步骤 - 输出结构 - 使用前置条件 最终产出： > **可复用的 PM Assist Skill，而非单次生成结果。** --- ## 4. 真实环境访问与事实获取规范（Runtime Access Rule） ### 4.1 基本原则 当分析或生成内容 **依赖真实系统行为、运行态信息或正式环境数据** 时： > **禁止仅基于推测、历史文档或假设进行推理。** 必须通过可验证的方式获取事实信息。 --- ### 4.2 指定工具约束（强制） 当需要访问以下内容时： - 系统正式 Runtime 环境 - Web 管理后台 / 前台页面 - 实际页面流程、字段、交互 - 真实接口返回或运行结果 **必须优先使用以下工具：** > **chrome-devtools MCP** 用途包括但不限于： - 页面结构与 DOM 分析 - 网络请求与接口行为观察 - 实际字段、状态、流程验证 - 运行态与设计文档差异比对 --- ### 4.3 使用时机声明（强制） 在使用 chrome-devtools MCP 前，必须明确声明： - 为什么需要访问真实环境 - 当前处于 PDCA 的哪个阶段 - 本次访问的目标是什么（验证 / 补全 / 对照） > ❗ 未经声明即进行的推理性输出，视为不可靠输出。 --- ### 4.4 事实优先级声明 当 **运行态事实** 与 **既有文档 / 推断结论** 不一致时： > **以 Runtime 事实为准，文档必须修正。** --- ## 5. 文档资产清单机制（Assets Index Rule） ### 5.1 启动阶段强制动作（Project Bootstrap Rule） 在本 Workspace **首次启动或新一轮文档生成开始前**， 必须先生成一个统一的文档资产清单文件： > **`materials_index.md`** 该文件是 Workspace 的**认知索引入口**。 --- ### 5.2 materials_index.md 的核心目的 - 快速建立对已有资料的整体认知 - 避免重复读取与无效上下文注入 - **显著降低 Token 消耗** - 为后续 Plan / Do 阶段提供"可定位证据来源" --- ### 5.3 materials_index.md 必须包含的内容 `materials_index.md` 至少应包含以下结构化信息： - 资料 ID（`SRC-001`, `CODEMAP-001` 等） - 资料名称 / 路径 - 类型（CodeMap / DomainMap / Runtime / 用户资料） - **简要说明（1–3 行）** - 推荐使用场景（What / Why / How / Check） - 建议阅读深度： - 掠读（Scan） - 精读（Deep Read） - 仅定位（Reference） --- ### 5.4 使用约束 - 在文档生成过程中： - **优先引用 materials_index.md 中的资源** - 明确指出使用的是哪一项资产（`[SRC-001]`, `[CODEMAP:...]`） - 当新增重要资源时： - 必须同步更新 materials_index.md > ❗ 未进入 materials_index.md 的重要资源，视为"不可被稳定复用的知识"。 --- ## 6. 证据标注与映射规则（Evidence Mapping Rule） ### 6.1 强制要求 每个关键结论、数据、规则必须标注来源： - **CodeMap 证据**：`[CODEMAP:assets/codemap/frontend/routes.yaml]` - **DomainMap 证据**：`[DOMAINMAP:assets/domainmap/branch_evidence.yaml]` - **Runtime 证据**：`[RUNTIME:screenshot_001.png]` - **用户资料**：`[SRC-001]` - **无证据**：`[ASSUMPTION]` --- ### 6.2 证据→章节映射表（强制） 在 PRD/FRD/DAR 中必须维护"证据映射表"： | 章节 | 关键结论 | 证据来源 | |-----|---------|---------| | 2.1 核心概念定义 | 预估里程定义 | [CODEMAP:dataobjects/Order.yaml] | | 2.2 双轨计费生效条件 | 商户配置逻辑 | [DOMAINMAP:branch_evidence.yaml] | | 3.1 下单流程 | 路线获取逻辑 | [RUNTIME:screenshot_002.png] | --- ### 6.3 证据缺口清单（Check 阶段强制输出） 若章节无法绑定证据，必须显式标记并列入"证据缺口清单"： | 章节 | 缺失证据 | 影响 | 下一步 | |-----|---------|-----|-------| | 4.2 外协订单处理 | BC段里程计算规则 | 无法验证结算逻辑 | 需 Runtime 验证或用户确认 | --- ## 7. 问题清单与问答闭环（Question List Rule） ### 7.1 强制要求 每轮 PDCA 的 Plan / Do 阶段，必须生成问题清单： - **P0 阻塞问题**（必须回答，否则不进入下轮） - **P1 关键决策问题**（影响方案设计） - **P2 细节确认问题**（影响细节完整性） 问题格式模板（`questions/round_N.yaml`）： ```yaml round: 1 questions: - id: Q1-1 priority: P0 question: "商户双轨计费配置的默认值是？" options: ["开启", "关闭", "其他"] status: pending ``` --- ### 7.2 问答闭环原则 - 未解决 P0 时，禁止生成下一轮完整输出，只能继续追问 - P1/P2 问题必须在 Check 阶段验证是否已解决 - 所有问题解答必须记录到 `decision_log.md` --- ## 8. Skill 的基本定义（约束性说明） 在本 Workspace 中： - **Skill ≠ Prompt** - Skill 是一套： - 明确输入 - 稳定处理流程 - 结构化输出 - 可多次复用的能力单元 Skill 是本 Workspace 的**核心资产**。 --- ## 9. 终止条件（Exit Criteria） 只有在满足以下条件时，某一轮 PDCA 才可结束： - 文档质量稳定接近专业 PM 水平 - 证据映射表完成且无关键缺口 - P0/P1 问题全部关闭 - 已成功抽象出可复用 Skill 否则，必须继续进入下一轮 PDCA。 --- ## 10. 最高约束声明 > 在本 Workspace 中： > - **方法优先于结果** > - **流程优先于一次性生成** > - **证据优先于假设** > - **Skill 优先于单篇文档** --- ## 11. 额外操作性总原则（Operational Summary） - **真实世界 → 用工具，不用猜** - **复杂问题 → 先建索引，再深入** - **证据不足 → 标记假设，不硬编** - **Token 是成本，结构是杠杆** 本 Constitution 为最高规范，优先级高于任何临时指令或即兴讨论。 --- ## 附录：技能调用速查 ### pmassist（产品文档协作助手） **路径**: `skills/pmassist/` **用途**: 创建或修订 PRD、FRD、DAR 等产品类文档 **核心方法论**: WWH + PDCA **快速使用**: ```bash # 初始化会话工作区 python3 skills/pmassist/scripts/init_session.py \ --path ./项目名-YYYYMMDD-HHMM \ --doc prd|frd|dar \ --alias 项目简称 \ --title "文档标题" \ --desc "原始需求描述" ``` **模板位置**: - PRD: `skills/pmassist/references/prd.md` - FRD: `skills/pmassist/references/frd.md` - DAR: `skills/pmassist/references/dar.md` **文档类型区分**: - **PRD**: 新需求、流程优化、产品规划、业务方案 - **FRD**: 具体功能实现、接口/数据/流程细节 - **DAR**: 线上缺陷、事故复盘、根因分析 --- ## 附录：项目记忆管理规范 ### 记忆文件位置 本项目在两个层次维护记忆： | 层次 | 路径 | 说明 | |------|------|------| | 项目级（版本控制） | `.claude/memory/project_memory.md` | 项目架构、规范、约定；随代码一起提交 | | 项目级（结构化） | `.claude/memory/context.json` | 机器可读的结构化上下文 | | 用户级（跨项目） | `~/.claude/projects/D--workspace-fly-home-flow/memory/` | Claude Code 自动管理的用户记忆 | ### 记忆更新时机 完成以下操作后，必须同步更新 `.claude/memory/project_memory.md` 和 `context.json`： - ✅ 架构决策或设计模式变更 - ✅ 新增关键技术栈或依赖 - ✅ 代码规范或约定的建立与修正 - ✅ 重要工具类/工作流的新发现 - ✅ 已完成工作区或里程碑 ### 更新流程 1. 先 Read 现有记忆文件 2. 评估需要新增或修改的内容（增量式，不删旧上下文） 3. 同步更新 `project_memory.md`（人类可读）和 `context.json`（机器可读） 4. 更新 `lastUpdated` 字段为当天日期（格式 `YYYY-MM-DD`） >>>>>>> e1d85c48c09f4096267ecbe268b303094f2c2606