5af71253dd
- 指南新增「探索章与结晶」一节：形态 定型|探索（人对意图清晰度的声明，不是任务进度）；探索章必填 轮廓、试探、不做、预算、收敛信号；每轮试验的终验行（保留/否决 + 理由）作为结晶原料；收敛或预算用完时由 agent 起草意图提炼、人确认后转为定型（小版本）；未收敛由人三选一，agent 不得自行延长预算 - 目录语法：新增「形态」字段与「不必开章的情况」（修修补补和直接做 MVP 不必开章）；goal 编译第 5 步补探索章分支；确认卡增加形态与轮次行；离线检查新增第 11 条（探索章必填字段），已用夹具实测 - 设计文档头部注明此次修订；起因与决策见模块决策记录（下一提交） Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
264 lines
15 KiB
Markdown
264 lines
15 KiB
Markdown
# 意图目录编写与使用指南
|
||
|
||
> 适用对象：所有 agent（Claude Code、Codex、DSH 等）和人。本文件是意图目录语法与 goal 编译流程的**单一来源**。
|
||
> 模块：`.blueprint/modules/intent-catalog.md`。设计依据：`docs/tasks/2026-10-04-intent-catalog-design.md`（临时文件，IC3 后删除）。
|
||
> 试用期（P8 收口前）只用文档和 shell 单行命令；门控脚本 `intent-gate.cjs` 在 Phase 4 落地后替换「离线检查」一节。
|
||
|
||
意图目录 `.blueprint/catalog.md` 是蓝图之上由人持有的一层：每章写一个意图方向、怎么判断做对了、不做什么。任务卡单向挂到章上，agent 据此把意图编译成评估器能判定的 /goal。**书装意图，指向事实**：代码、状态、规格、凭据都不进目录，目录里只放指针。
|
||
|
||
| 角色 | 写什么 | 不写什么 |
|
||
|---|---|---|
|
||
| 人 | 章的意图、人看、不做；大版本修订；确认小版本、书签切换和 goal 确认卡 | 卡的状态（由 agent 判定）；机器坐标的具体命令 |
|
||
| agent | 机器坐标指针、小版本提案、goal 编译、收口回执、卡上的 `- 终验:` 记录 | 章的完成状态（只能推导）；替人改意图 |
|
||
| 炼境 | 无，只经 get_project_file 只读提供同一份文件 | 不编译 goal、不选模型、不判定完成 |
|
||
|
||
## 目录语法
|
||
|
||
**位置与骨架**：`.blueprint/catalog.md`，放在 modules/ 之外，依次为引言行、书签、各章、墓碑、附录。
|
||
|
||
```markdown
|
||
# 意图目录
|
||
> catalog_version: 1.0 | 前言 → path:AGENTS.md#项目定位 | 语法 → path:docs/ai-context/intent-catalog-guide.md
|
||
|
||
## 书签
|
||
- 当前 → path:docs/tasks/2026-10-03-coordination.md#0. 方针与本阶段终点
|
||
|
||
## INT-01 <章名：一个意图方向>
|
||
- rev: 1.0
|
||
- 意图: <一句话，人的原意>
|
||
- 人看: <人在投影上看到什么就算做对了>
|
||
- 机器: <可断言坐标的类型化指针，例如 card:<module>#<卡键>>
|
||
- 不做: <边界；多条用「；」分隔>
|
||
|
||
## INT-09（已撤销）
|
||
- 撤销: YYYY-MM-DD → module:<id>#决策记录
|
||
|
||
## 附录
|
||
- <名称> → <类型化指针>
|
||
```
|
||
|
||
**章导语字段**：
|
||
|
||
| 字段 | 必填 | 含义 |
|
||
|---|---|---|
|
||
| rev | 是 | 该章最后一次变更时的目录版本，不大于 catalog_version |
|
||
| 意图 | 是 | 人的原意，一句话 |
|
||
| 人看 | 是 | 人看的投影坐标（对应 human_verify） |
|
||
| 机器 | 是 | agent 可断言的坐标，只写指针，不写命令全文 |
|
||
| 不做 | 是 | 边界，agent 扩范围时的刹车 |
|
||
| 风险 | 否 | 低、中、高，或指向不可逆操作的说明 |
|
||
| 假设 | 否 | 指向既有的证伪落点（某张 spike 卡或复盘），目录里不存证伪状态 |
|
||
| 证据 | 否 | 指向已有证据（卡上的 verify 记录、PR） |
|
||
| 墙 | 否 | 关联的承重墙编号，例如 `W12,W13` |
|
||
| 形态 | 否 | `定型`（缺省）或 `探索`；只能由人确认修改，见「探索章与结晶」 |
|
||
|
||
**不必开章的情况**：只是修修补补的卡，照常做，不写 intent；属于某个已有章的，就挂上去，算补丁级。完全没有意图、直接做 MVP 的，先不开章，做两三轮以后再从试用反馈里提炼。目录和卡侧 intent 都是可选的，不会挡住任何工作。
|
||
|
||
**防膨胀（硬限制）**：
|
||
|
||
- 每个字段只写一行，不超过 120 字；
|
||
- 每个章块不超过 12 行；
|
||
- 全文件不超过 200 行、8KB；
|
||
- 禁止出现 `status`、`progress`、`doc`、`files`、`acceptance`、`model` 键，也不写模型名；
|
||
- 不设文件内修订历史，修订历史看 git log。
|
||
|
||
**类型化指针**（多个指针用「；」分隔）：
|
||
|
||
| 前缀 | 写法 | 校验方式 |
|
||
|---|---|---|
|
||
| path: | `path:<相对路径>[#标题前缀]` | 文件存在；有 `#` 时标题能匹配 |
|
||
| module: | `module:<id>[#段名]` | `.blueprint/modules/<id>.md` 存在 |
|
||
| card: | `card:<module>#<卡键>` | 该模块里存在这张卡；卡键取标题去掉状态前缀后的第一个 token，例如 `IC6`、`P8e` |
|
||
| spec: | `spec:<路径>#标题` | 指向子项目已有的规格（例如 `.specify/specs/...`），只指向不复制 |
|
||
| cmd: | `cmd:<命令或工具名>` | 只校验格式，不执行 |
|
||
| W | `W1`–`W14` | 承重墙编号，定义见模块文件「承重墙」节 |
|
||
|
||
**ID 规则**：章用两位数 `INT-NN`，永不复用。撤销的章保留墓碑 `## INT-NN（已撤销）`，注意编号后面紧跟全角括号、没有空格。
|
||
|
||
**卡侧挂靠（单向）**：
|
||
|
||
- 卡上可选写一行 `- intent: INT-NN@X.Y`，放在 `- complexity:` 后面，表示这张卡服务哪一章、编译自目录哪一版。
|
||
- 模块头 blockquote 可选写 `| intent: INT-NN` 作为整个模块的默认挂靠，不带版本，影响分析里计为低置信。
|
||
- 章的「机器:」只是验收坐标，不登记成员名单。反向索引现算，不存储。
|
||
|
||
**终验记录**：卡上另起一行 `- 终验: YYYY-MM-DD 通过|否决：<理由>`，由 agent 记录人在会话里给出的裁决。不要写进 `- notes:`，因为多条 notes 后一条会覆盖前一条。
|
||
|
||
**解析器约束**：模块 md 里，「任务卡」段以外一律不用 `###`。未识别的 `##` 段下出现 `###` 会被当成任务卡。
|
||
|
||
## 修订与钉版
|
||
|
||
**版本**：引言里写一个 `catalog_version: X.Y`；每章有自己的 `rev`。这套版本号与 manifest.iteration 互不借号。
|
||
|
||
| 级别 | 什么时候 | 怎么做 | 版本变化 |
|
||
|---|---|---|---|
|
||
| 补丁 | 只改正文（卡、模块），目录不动 | agent 自主完成，照常走需求对齐协议 | 无 |
|
||
| 小版本 | 改某章的人看、机器或不做；由正文反推修改目录 | agent 提出 S 级三行确认卡，附 diff 和 base blob，人说「确认」 | Y+1；被改章的 rev = 新版本 |
|
||
| 大版本 | 增删章节、调整方向 | 人主导，agent 协助起草 | X+1、Y 归零；涉及的章更新 rev；删掉的章留墓碑；按 T4 检查 AGENTS.md「项目定位」 |
|
||
|
||
**提案**：附上目录 diff 和 base blob，base blob 用下面的命令取：
|
||
|
||
```bash
|
||
git rev-parse --short HEAD:.blueprint/catalog.md
|
||
```
|
||
|
||
人确认后提交，提交前再取一次 blob。如果已经不等于 base，说明目录被别人改过，必须重新提案，不能硬合。
|
||
|
||
**提交格式**：
|
||
|
||
- 首行：`docs(intent): <改了什么>`
|
||
- body：一句理由，必要时写来源，例如某次终验否决、某张卡的设计发现。
|
||
- 末尾：带 `Feature-Confirmed: true`。
|
||
- 目录改动单独小提交，不和代码混在一起。
|
||
|
||
**钉版**：卡写 `- intent: INT-NN@X.Y`；goal 标签写 `INT-NN@X.Y#<blob7>`。
|
||
|
||
**影响分析**：
|
||
|
||
| 判定 | 条件 | 处理 |
|
||
|---|---|---|
|
||
| stale | 卡钉的版本低于章 rev，且卡未完成 | 复核 acceptance。没变化就改钉，算补丁，并在简报里报告；有变化就按小版本走 |
|
||
| orphan | 卡钉在已撤销的章上 | 停下找人，决定改挂哪一章还是撤卡 |
|
||
| low_confidence | 卡只有模块默认挂靠，没有卡侧钉版 | 编译 goal 前补写卡侧 intent |
|
||
|
||
**在制品保护**：钉旧版的 🔵 卡照常做完，只复核 acceptance。章被撤销，或新的「不做」覆盖了这张卡时，停下找人。任何情况下都不自动改写卡。
|
||
|
||
## 探索章与结晶
|
||
|
||
意图常常不是一开始就清楚的，而是做 MVP、反复试用以后才长出来。探索章就是给这种情况用的：先写下在找什么、找多久，等意图结晶出来再改成定型章。
|
||
|
||
```markdown
|
||
## INT-04 <轮廓名>
|
||
- rev: 1.1
|
||
- 形态: 探索
|
||
- 轮廓: <人的原话，模糊也可以>
|
||
- 试探: <这一阶段想弄清的问题，例如「哪种交互最顺手」>
|
||
- 不做: <再模糊也要有的边界>
|
||
- 预算: <最多 N 轮 MVP 或 N 天>
|
||
- 收敛信号: <出现什么就说明方向定了，例如「连续两轮不再想改核心交互」>
|
||
- 证据: <各轮试验卡的指针>
|
||
```
|
||
|
||
| | 定型章 | 探索章 |
|
||
|---|---|---|
|
||
| 必填 | rev、意图、人看、机器、不做 | rev、形态: 探索、轮廓、试探、不做、预算、收敛信号 |
|
||
| 回答 | 做到什么样算对 | 我们在找什么、找多久 |
|
||
| goal 终点 | 交付终点 | 每轮试验的终点 |
|
||
| 度量 | goal 一次判对率 | 几轮收敛、是否守住预算、否决理由是否越来越少 |
|
||
|
||
**每轮试验**：
|
||
- 拆一张试验卡，挂到探索章上：`- intent: INT-NN@X.Y`。
|
||
- 人试用后，agent 把反应记成卡上的终验行：`- 终验: YYYY-MM-DD 保留|否决：<理由>`。
|
||
- 这些保留和否决的理由，就是结晶的原料。
|
||
|
||
**结晶（探索 → 定型）**：
|
||
- 收敛信号出现，或预算用完时，agent 汇总各轮终验行，起草「意图提炼」：建议的意图、人看、机器、不做，以及依据（哪几轮保留、哪几轮否决、为什么）。
|
||
- 人确认后，形态改为定型，按小版本修订：Y+1，本章 rev 更新，轮廓、试探、预算、收敛信号几行换成意图、人看、机器。
|
||
|
||
**预算用完仍未收敛**：由人三选一：
|
||
- 追加预算继续，小版本；
|
||
- 换方向重写轮廓，小版本；
|
||
- 放弃，大版本，留墓碑。
|
||
|
||
agent 不得自行延长预算。
|
||
|
||
## goal 编译
|
||
|
||
本流程只依赖读文件和 git，不依赖任何特定客户端或模型。Claude 的 /architect 只是可选包装，任何 agent 都可以照着手工执行。产出是一张目标确认卡加一段 /goal 文本。
|
||
|
||
1. **定位**
|
||
- 读 `.lian-jing/context.json` 取 project_id；记下当前分支、worktree 路径和 `git rev-parse --short HEAD`。
|
||
- 要求 `git status --porcelain -- .blueprint/catalog.md` 输出为空：目录有未提交改动时不编译。
|
||
- 取 catalog blob：`git rev-parse --short HEAD:.blueprint/catalog.md`。
|
||
2. **读书签**：书签指向当前章（P8 期间指向 coordination §0 的终点）。读该章的导语和 rev。
|
||
3. **校验**：跑「离线检查」一节的全部命令（Phase 4 后改为 `node .claude/hooks/intent-gate.cjs --report INT-NN --impact`）。只要出现悬空指针、stale 或 orphan、防膨胀超限，就先修或先提案，不往下编译。
|
||
4. **收卡**
|
||
- 取挂在本章、标题前缀为 📋 或 🔵 的卡。
|
||
- 没有可执行 agent_verify 的卡，列入「须先补 acceptance」，不进 goal。
|
||
5. **合成终点**
|
||
- 取各卡 agent_verify 的合取，改写成在会话里能判定的形式：贴出命令和预期输出、纳入卡前缀都是 ✅、回执已写入。
|
||
- human_verify 不进终点，单列为终验待办。
|
||
- 过程词黑名单命中数必须为 0：「按方针」「符合设计」「设计已完成」「基本完成」，以及任何无法从会话输出判定的形容词。
|
||
- **探索章**不编译「意图的终点」，只编译本轮试验的终点：
|
||
- 做出可试用的 MVP 变体，写明最小动作和可演示方式；
|
||
- 校验命令通过；
|
||
- 试验卡为 ✅ 且已写回执。
|
||
- 人的试用反馈作为终验待办，记到终验行。
|
||
- 确认卡写明这是第几轮、共几轮预算；超出预算就不编译，转入结晶或请人三选一。
|
||
6. **写停止条件**：遇到以下任一情况必须停下找人：
|
||
- human_verify；
|
||
- 写运行中的数据库；
|
||
- 删除文件、数据或分支；
|
||
- 凭据或机器状态变更；
|
||
- 超出纳入卡或本章范围；
|
||
- 需要修改目录；
|
||
- 出现 stale 或 orphan；
|
||
- 同一问题失败 3 次。
|
||
7. **输出**：一张目标确认卡（格式见下一节），加 /goal 文本，首行带同样的标签。人读完亲手粘贴就算确认；要改就重新编译。agent 不得自行启动 goal，也不得静默改写 goal 文本。
|
||
|
||
## 确认卡与回执
|
||
|
||
**目标确认卡**（兼作最小任务简报，新会话只读它就能开工）：
|
||
|
||
```text
|
||
[INT-NN@X.Y#<blob7>] 目标确认卡
|
||
项目: <project_id> | 分支/worktree: <branch> @ <path> | HEAD: <sha7>
|
||
章意图: <一句> | 不做: <…>
|
||
形态: 定型 | 探索（第 k/N 轮；收敛信号: <…>）
|
||
纳入卡: <卡键>（来源 agent_verify 原文）、<卡键>（…）
|
||
终点（合取）: 1) <命令> → <预期输出> 2) … 3) 纳入卡均 ✅ 且已写 Goal-Receipt
|
||
终验待办: <各卡 human_verify>
|
||
停止找人: <第 6 步清单>
|
||
能力入口: <校验命令，例如 pnpm typecheck / cargo test；可用的 MCP 工具>
|
||
没验什么: <编译时已知的盲区>
|
||
作废: 分支变化或 catalog blob ≠ <blob7>
|
||
```
|
||
|
||
由非 Claude 客户端编译时，在提交 body 里另加一行 `Compiled-By: <客户端名>`，用于跨 agent 验证。
|
||
|
||
**收口回执**：goal 收口时写进收口提交的 body；M 级同时复制到 PR body；炼境在线时可以再调一次 append_project_note。
|
||
|
||
```text
|
||
Goal-Receipt: INT-NN@X.Y#<blob7>
|
||
Goal-Cards: <纳入卡键列表>
|
||
Goal-Result: 判对|误判|中止(<原因>)
|
||
Goal-Rounds: <轮数>
|
||
Goal-Interventions: <人工介入次数>
|
||
Goal-Tokens: <客户端可得时填，否则 n/a>
|
||
Not-Verified: <没验什么>
|
||
Human-Pending: <待人终验项>
|
||
```
|
||
|
||
回执不写进模块决策记录，因为 UI 会把它当决策展示；也不要手改 `.blueprint/notes-archive.jsonl`，它以炼境 DB 为事实源，会被整文件重写。
|
||
|
||
## 离线检查
|
||
|
||
试用期的检查全部是 shell 单行命令，在仓库根目录执行。期望输出写在每条后面的注释里。
|
||
|
||
```bash
|
||
# 1. 版本行恰好一行
|
||
grep -c '^> catalog_version: ' .blueprint/catalog.md # → 1
|
||
# 2. 有效章数（墓碑不计）
|
||
grep -cE '^## INT-[0-9]{2} ' .blueprint/catalog.md # → 章数
|
||
# 3. 体量
|
||
wc -l < .blueprint/catalog.md; wc -c < .blueprint/catalog.md # → ≤200 行、≤8192 字节
|
||
# 4. 禁用键与模型名
|
||
grep -cE '^- (status|progress|doc|files|acceptance|model):' .blueprint/catalog.md # → 0
|
||
# 5. path 指针可解析（没有输出即通过）
|
||
grep -oE 'path:[^ #；|]+' .blueprint/catalog.md | sed 's/^path://' | sort -u | while read -r p; do test -e "$p" || echo "悬空: $p"; done
|
||
# 6. module 指针可解析（没有输出即通过）
|
||
grep -oE 'module:[a-z0-9-]+' .blueprint/catalog.md | sed 's/^module://' | sort -u | while read -r m; do test -e ".blueprint/modules/$m.md" || echo "悬空: $m"; done
|
||
# 7. 卡侧 intent 引用的章都存在且未撤销（没有输出即通过）
|
||
comm -23 <(grep -hoE '^- intent: INT-[0-9]{2}' .blueprint/modules/*.md | grep -oE 'INT-[0-9]{2}' | sort -u) <(grep -oE '^## INT-[0-9]{2} ' .blueprint/catalog.md | grep -oE 'INT-[0-9]{2}' | sort -u)
|
||
# 8. 钉版与章 rev 对照（人工比对：钉的版本低于 rev 且卡未完成，即为 stale）
|
||
grep -hoE 'intent: INT-[0-9]{2}@[0-9]+\.[0-9]+' .blueprint/modules/*.md | sort | uniq -c
|
||
awk '/^## INT-[0-9]{2} /{c=$2} /^- rev:/{print c, $3}' .blueprint/catalog.md
|
||
# 9. 改模块 md 前后的任务卡计数应相等（新增卡时等于新增数），防止误写 ###
|
||
cat .blueprint/modules/*.md | grep -c '^### '
|
||
# 10. goal 文本的过程词黑名单（把 /goal 文本存成临时文件后检查）
|
||
grep -cE '按方针|符合设计|设计已完成|基本完成' <goal 文本文件> # → 0
|
||
# 11. 探索章的必填字段齐全（没有输出即通过）
|
||
awk '/^## /{if(e&&!(b&&s))print "缺预算或收敛信号: "c; c=$2;e=0;b=0;s=0} /^- 形态: 探索/{e=1} /^- 预算:/{b=1} /^- 收敛信号:/{s=1} END{if(e&&!(b&&s))print "缺预算或收敛信号: "c}' .blueprint/catalog.md
|
||
```
|
||
|
||
card: 指针目前只能人工核对，到模块文件里搜索卡键，Phase 4 后由门控自动校验。指针中带 `#标题` 的部分，也是同样的人工核对方式。
|