1066 lines
31 KiB
Markdown
1066 lines
31 KiB
Markdown
<<<<<<< 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
|