跳到主要内容

Project Canonical Required Fields

状态：Active / 项目正文必备字段模板 最后更新：2026-05-15 用途：Project Controllers 写或重写 projects/<project>/{strategic-whitepaper,product-definition,mvp-product-definition}.md 时的字段 checklist + 必填占位

1. 模板触发根因​

2026-05-15 三方独立 audit 共识（evidence/reader-tests/2026-05-15-tri-perspective/）揭示 FR-014 / FR-015 / FR-017 三方一致 P0 未解决：

  • FR-014（OOSO + Codex 证据）：strategic-whitepaper / product-definition 文档厚但实施承接薄，PRD "defines what but not how"
  • FR-015（OOSO + Codex 证据）：MVP "what is NOT" 清楚但 "what IS" 不具体（首个用户 / 替代方案 / 量化指标 / 时间盒 / kill criteria 缺失）
  • FR-017（OOSO 8+ 处证据）：缺 JSON sample / 用户旅程 / 线框 / 状态机 / 真实 case

本模板把这三个 FR 的"应有产出"字段化，让 Controllers 按 checklist 回写，避免每次从零设计字段集。

2. 适用范围​

文件强度字段集
projects/<project>/strategic-whitepaper.md推荐§3.1
projects/<project>/product-definition.md强制§3.1 + §3.2
projects/<project>/mvp-product-definition.md强制§3.1 + §3.2 + §3.3

"强制" 不阻挡 PR 合并，但 Controller 必须在 PR 描述中显式说明每个字段的回答（或显式标 "本项目不适用 + 理由"）。

3. 字段集​

3.1 战略层（适用于所有三份 canonical）​

# Required: Strategic-Layer Fields

product_name: <string>                         # FinClaw / Data Horizon / 等
product_tagline: <string, ≤30 字>             # 一句话产品定位
ecosystem_role: <string>                       # 在 3+2 生态中的位置和邻接关系
upstream_dependencies:                         # 至少列出生态层依赖
  - <upstream-object-or-system>
downstream_consumers:                          # 至少列出生态层消费方
  - <downstream-object-or-system>
non_goals:                                     # 至少 5 项明确不做
  - <non-goal-1>
strategic_horizon: <string>                    # 此版本的战略时间盒（可粗：6 月 / 12 月 / V1）
authority_boundary:                            # 战略权威边界
  decided_by: <Controller / User / Joint>      # 谁最终拍板战略变更
  changes_require: <list of artifacts>         # 战略变更必须改的工程/治理产物

3.2 产品层（适用于 product-definition.md 与 mvp-product-definition.md）​

# Required: Product-Layer Fields

first_user_segment:                            # 首发用户段（不能为空）
  description: <string, ≤100 字>
  identifiable_persona: <string>               # 例: "活跃 1-3 年的加密散户，关注 1-3 个资产"
  reachable_through: <list>                    # 如何触达：Telegram / 微信 / X / 邀请码 / 等
  estimated_size: <number or 范围>             # 首发可触达数量级（10 / 100 / 1000）

alternatives_today:                            # 当前用户解决同一问题的替代方案（≥3）
  - name: <string>
    why_users_use_it: <string>
    why_we_can_displace: <string>

product_form:                                  # 产品形态
  primary_surface: <Web / Mobile / CLI / API / Channel>
  primary_input_modality: <NL / Form / Voice / Mixed>
  primary_output_modality: <Structured Object / Streaming Text / Mixed>
  example_first_session: <string, 1-3 段>      # 用户首次使用的具象画面

success_signals:                               # 量化成功信号（每项必须有数字）
  - signal: <string>
    metric_definition: <string>
    target_value: <number + 单位>              # 例: ">= 80%" / ">= 50 user/month"
    measurement_method: <string>
    measurement_frequency: <string>

failure_signals:                               # 失败信号（每项必须可观察）
  - signal: <string>
    detection_method: <string>
    response_action: <string>

3.3 MVP 层（仅适用于 mvp-product-definition.md）​

# Required: MVP-Layer Fields

mvp_scope:
  must_have:                                   # 必须有的功能（核心切片）
    - <feature-1>
  could_have:                                  # 可有可无的功能（可缓做）
    - <feature-2>
  must_not_have:                               # 明确不做的功能（防 scope creep）
    - <feature-3>

time_box:
  start_date: <YYYY-MM-DD>                     # 必须是具体日期，不能是"待定"
  trial_start_target: <YYYY-MM-DD>
  trial_end_target: <YYYY-MM-DD>
  hard_deadline: <YYYY-MM-DD>                  # 不再延期的硬截止
  owner: <name or Controller>                  # 时间负责人

kill_criteria:                                 # MVP 失败/中止条件（每项必须可量化判定）
  - criterion: <string>
    threshold: <number + 单位>
    decision_action: <Stop / Pivot / Reduce-scope>

implementation_artifacts:                      # 实施产物清单（FR-017 纠偏）
  json_sample_for_each_core_object:            # 每个 P0 对象至少 1 个完整 JSON sample
    - object: <name>
      location: <evaluation/<project>/seeds/...json>
  user_journey:
    type: <Mermaid / Figma / Screenshot>
    location: <path>
    coverage: <list of journey paths>
  state_machine:
    type: <Mermaid / DOT / PNG>
    location: <path>
    coverage: <list of state machines>
  ui_artifacts:
    wireframes_or_figma: <path or N/A + 理由>
  prompt_templates:
    location: <evaluation/<project>/prompts/>
    coverage: <list of skill / agent>
  eval_cases:
    location: <evaluation/<project>/cases/>
    minimum_count: <number>
    actual_count: <number>

4. 字段填写示例（以 FinClaw 为例的演示）​

参考 evaluation/finclaw/seeds/（如已存在）的 MarketCognitionSnapshot 种子作为 implementation_artifacts.json_sample_for_each_core_object 的填写样例。

5. Controller 使用流程​

  1. Controller 复制本模板字段到对应文件 frontmatter 或专用段（建议 ## 0. Required Fields Summary）
  2. 逐项回答；不能跳过
  3. 如某字段确实不适用，写 N/A + 理由，不允许留空
  4. 提交 PR 时在描述中引用本模板路径
  5. 完成回写后按 reader-testing-protocol.md 至少 L1 reader test
  6. 在 closeout sync packet 中显式列出本模板使用证据

6. 验收门控​

  • 字段缺失或 "TBD" 数量 = 0：进入 reader testing 阶段
  • 字段缺失但 ≤2 项 + 有显式 "本项目不适用 + 理由"：进入 reader testing 但需 Reviewer Controller 复核
  • 字段缺失 >2 项：退回 Controller 补齐，不得进入 closeout

7. 不在模板范围​

  • 项目战略 / 产品 / MVP 内容本身（Controller 责任）
  • 工程实现细节（工程仓库责任）
  • 评测 case 的具体 prompt（Evaluation owner 责任）

8. 与三方 audit 证据对照​

字段来自三方 audit 证据
first_user_segment.identifiable_personaCodex mvp-product-definition.md:42-59 "MVP much more concrete on user, market, scope" + OOSO Q5
time_box.hard_deadlineOOSO v1-trial-operations-plan.md:186-191 "Open Items: trial owner / participant count / exact calendar undefined"
kill_criteria.thresholdCodex P1 + OOSO P1 "11 metrics with no target values"
implementation_artifacts.json_sample_for_each_core_objectOOSO 4+ 处 P0 "Zero JSON samples for MarketCognitionSnapshot"
implementation_artifacts.state_machineOOSO P0 "10 user states with no state machine diagram"
implementation_artifacts.ui_artifacts.wireframes_or_figmaOOSO P0 "No wireframes, no Figma files"
implementation_artifacts.prompt_templatesOOSO P0 "Skills are 'capability labels, not implementation commitments'"