Skip to content
Skills Library
Management & product · Planning

doc-driven-development

/doc-driven-development

Treat documents as the single source of truth for development. Dual-sided session records (8 user-side categories, 6 AI-side items, 8-dimension option comparison), an issue inbox that logs findings without interrupting, a generated timeline, ADRs with bidirectional supersede chains, EARS-phrased contracts, and a three-level plan (direction/work/task) scored on six dimensions across multiple views — all machine-validated by stdlib scripts. Use when the user asks to record or trace development process and system evolution, keep discussions and decisions on file, manage and prioritise what comes

Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
14
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: build.py, install.py

What it does and when to use it

Treat documents as the single source of truth for development. Dual-sided session records (8 user-side categories, 6 AI-side items, 8-dimension option comparison), an issue inbox that logs findings without interrupting, a generated timeline, ADRs with bidirectional supersede chains, EARS-phrased contracts, and a three-level plan (direction/work/task) scored on six dimensions across multiple views — all machine-validated by stdlib scripts. Use when the user asks to record or trace development process and system evolution, keep discussions and decisions on file, manage and prioritise what comes

Arguments

/doc-driven-development Point me at the project root, or paste the decisions and next steps to record
Original author description

Treat documents as the single source of truth for development. Dual-sided session records (8 user-side categories, 6 AI-side items, 8-dimension option comparison), an issue inbox that logs findings without interrupting, a generated timeline, ADRs with bidirectional supersede chains, EARS-phrased contracts, and a three-level plan (direction/work/task) scored on six dimensions across multiple views — all machine-validated by stdlib scripts. Use when the user asks to record or trace development process and system evolution, keep discussions and decisions on file, manage and prioritise what comes

How it works

  1. 内核总纲
  2. 核心结构
  3. 分工边界:谁定什么、谁核什么
  4. 写什么
  5. 硬规则
  6. 边界
  7. 开发哲学:敏捷
  8. 日常三动作
  9. 主干道:从需求到证据
  10. 从不空手开始
Original SKILL.md headings · 467 lines, 3,634 words
SKILL.md preview
---
name: doc-driven-development
name_en: Doc-Driven Development
name_zh: 文档驱动的开发过程
description: Treat documents as the single source of truth for development. Dual-sided session records (8 user-side categories, 6 AI-side items, 8-dimension option comparison), an issue inbox that logs findings without interrupting, a generated timeline, ADRs with bidirectional supersede chains, EARS-phrased contracts, and a three-level plan (direction/work/task) scored on six dimensions across multiple views — all machine-validated by stdlib scripts. Use when the user asks to record or trace development process and system evolution, keep discussions and decisions on file, manage and prioritise what comes next, lay down a docs/ hierarchy or single source of truth, backfill verifiable docs into an existing project, or mentions ADR, session records, ISS ids, plan ranking, EARS, or doc drift.
description_en: 'Treat documents as the single source of truth for development: dual-sided session records, issue inbox, generated timeline, ADRs with supersede chains, EARS-phrased contracts, and a scored three-level plan, all machine-validated. Use for recording/tracing development process, archiving decisions, prioritising next steps, or laying down a verifiable docs/ hierarchy.'
description_zh: 用文档当成唯一事实源来管住开发:双侧会话档案(用户侧 8 类 + AI 侧 6 项 + 八维选项对比)、问题收件箱、时间线、ADR(双向取代链)、EARS 句式契约、三层开发计划(方向/工作/任务)配六维优先级与多视角排序,全部带脚本校验与棘轮基线。当用户要求"记录/追溯开发过程与系统演化""把讨论和决策留档""管理下一步做什么并排优先级""搭一套文档体系/唯一事实源""给现有项目补可校验的文档骨架",或提到 docs/ 分层目录、ADR、会话档案、ISS 编号、开发计划排序、EARS、文档漂移时使用。
argument-hint: Point me at the project root, or paste the decisions and next steps to record
argument-hint_en: Point me at the project root, or paste the decisions and next steps to record
argument-hint_zh: 告诉我项目根目录,或把要留档的讨论结论与下一步候选贴给我
user-invocable: true
whenToUse: 会话开始要读现状或开档时;过程中发现缺陷/口径冲突/文档债/风险/待决/机会时;收尾要跑校验、回写计划、写交接段时;用户问"下一步做什么""这些决定当时为什么这么定""这条需求怎么验证"时;要给现有项目补 docs/ 骨架或把讨论落档时。
---
## 内核总纲

整个技能围绕**一个骨架、两条主线**组织(D18):骨架不变,组件可换;读任何一条规则,先问它服务哪一块。

- **骨架(不变)——人凭什么信**:文档是唯一事实源(五层结构、编号体系、状态只被证据推进)+五道门(对齐 / 评审 / 设计 / 对照 / 考核;机器判形式、人判语义)。骨架不因两主线而免:任何主线上的便利都不构成跳过门禁的理由。
- **流程线(开发怎么走)**:从最小可用系统出发,先固定再扩展;系统内组件可替换、调整、优化,骨架不动。快速实现、及时反馈(每轮改动 AI 先自查+用户当场反馈)、灵活调整——可逆的 AI 直接做,不可逆的人签字。
- **开发者线(读着怎么感受)**:降低认知负荷——能用图不用字(内联、可 diff)、回复按档位简短易读、一次一维、锚点真实。

| 章节 | 归属 | 一句话 |
|---|---|---|
| 核心结构 | 骨架 | 三件事各一份唯一文档 + 问题收件箱 + RV 台账 |
| 分工边界 | 骨架 | 每个动作谁定、人核什么、谁签字 |
| 写什么 | 骨架 | 各文档的形状与会话档案七段约定 |
| 硬规则 | 骨架 | 机器判据全表 |
| 边界 | 骨架 | 不做什么 |
| 开发哲学:敏捷 | 流程线 | 最小可用 → 固定 → 扩展;重 AI 压短「做出来再调」的周期 |
| 日常三动作 | 流程线 | 开场 / 过程 / 收尾的具体动作与命令 |
| 主干道:从需求到证据 | 流程线 | 需求 → 功能 → 任务 → 证据的十一格 |
| 从不空手开始 | 操作 | `doc_init` 铺骨架 |
| 坑 | 操作 | 真实踩过的坑,不是假设 |
| 现实不配合时怎么办 | 操作 | 环境受限时的回落路径 |
| 按需加载 | 操作 | 深用时的扩展入口 |
| 模板与脚本 | 操作 | 资产位置 |
| 验收 | 操作 | 本文自检清单 |

## 核心结构

三件事各有一份**唯一**文档,其余文档只做索引或引用:

| 想知道 | 唯一载体 | 谁维护 |
|---|---|---|
| 这件事怎么一步步变成现在这样 | 会话档案(一次会话一份)+ 时间线 | 会话进行中边写边补 |
| 为什么这么定、还摆着哪些选项 | ADR(一文件一决策,带取代链) | 定案时 |
| 下一步做什么、为什么是它 | 开发计划(三层 + 六维 + 多视角) | 每次收尾 |
| 这个实现到底行不行(要等用够 / 攒够) | 真机验收台账(`RV` 编号 + 观察记录) | 开单时、每场收尾记一条 |

外加一张**问题收件箱**:过程中发现的一切问题先落地,不打断当前话题。另有一张**真机验收台账**:实现不是最终版、结论只能等真机用出来的条目落在这里——它不是缺陷也不是待办,收件箱「修完就关」的寿命模型套不上它(ADR-007)。

## 分工边界:谁定什么、谁核什么

总则一句:可逆的 AI 直接做,不可逆的人签字。下表把主要动作逐条摆开,每行三栏——AI 定什么、人必须核什么、谁签字。表未覆盖的动作按总则回落;复述门与考核门本身也是分工点,改这张表前先过它们。这张表是分工的唯一权威,vision 与 README 只留指针。

| 动作 | AI 定什么 | 人必须核什么 | 谁签字 |
|---|---|---|---|
| 开场读现状 | 跑 `brief`、解读一屏、建本场档案 | —(结果归后续门) | AI |
| 方向确立(D) | 起草方向卡:现状、路径、接缝、走通验收 | 成功状态是不是你要的;这条路值不值得现在走 | 人 |
| 需求立项(REQ) | 写 EARS 句、配 `verify:` 命令、写回看三行 | 这句是不是必须成立的那一句 | 人 |
| 功能评审(F) | 答三问(满足哪条需求、能不能做、代价)与拆分闭合 | 代价与取舍值不值 | 人 |
| 设计定稿(K) | 摆选项空间(至少 3 个,含不做)、写接口与失败边界 | 选哪条;失败边界写得够不够 | 人(边界必过复述门) |
| 任务拆分与排期 | 拆任务、打六维分、算三视角排序 | 用哪个视角先看——排序不是唯一答案 | AI(人选视角) |
| 实施与冒烟 | 读文档、改代码、跑冒烟命令 | —(结果归对照门) | AI |
| 预审 | 只出四格:指向、逐字引文、疑点、建议动作 | 裁决:采纳哪条、怎么处理 | 人 |
| 对照(实施后、测试前) | 填功能对照四列 | 做的是不是需求那一句(行为覆盖);差异是否落了 ISS | 人 |
| 考核回顾 | 写任务考核四格草稿 | 写法与判断;结论是保留还是改造 | 人 |
| 测试与回写 | 跑 `verify:`、按证据推状态、记 `完成于` | 锚点真实:命令能跑、commit 存在、证据不是形容词 | 证据(状态只被证据推进) |
| 收尾五连跑 | 跑五条命令、把 error 修到 0 | 0 error 才算收尾 | 机器 |
| 开放问题收口 | 摆回顾:哪些 ISS 有关、哪些挂着、回到条件 | 关哪些、挂哪些 | 人 |
| 发版与回滚 | 打包、装端、执行回滚命令 | 打 tag、发 release、回退到哪个 commit;发版前整体核对全库图与文字是否一致 | 人(必过复述门) |

**档位:人门按代价伸缩**

> 判据只有一条:**这次改动改没改事实**(碰不碰契约、结构、判据、规则),以及**一处还是要多处**。与硬规则 12 同源:**小档=轻档**,**中 / 大档是重档的两半**;同一改动的两处结论不许打架。

| 档 | 什么改动 | 人必须答 | 机器判 |
|---|---|---|---|
| 小 | 措辞 / 格式 / 注释 / 示例文字;不碰契约、结构、判据、规则 | 只有发版(若发);对照与考核不单独走门,由每轮「AI 自查+用户当场反馈」覆盖 | 改动触及的校验 |
| 中 | 一处行为变化或一个小能力(含新增 / 小改一条需求);不动结构、数据形态、公开接口、判据、规则;能一次退回 | 前置一次:评审三问 + 三行设计(需求那一句先过对齐 / 复述);后置一次:对照 + 考核一起答;发版(若发) | 同上 |
| 大 | 动结构 / 数据形态 / 公开接口 / 判据 / 规则本身;或一场做不完、多处联动 | 五道门全过 + 开放问题收口 + 发版(若发) | 同上 |

- **判档**:AI 先判,并在会话档案 §1 写「本次档位:<档>(理由)」;**只升不降**——用户可降,降档要写一句理由。
- **不可降的门**:方向、契约口径、发版与回滚、开放问题收口——任何档都要过人;档位只决定其余门的密度与时机。
- **一次回顾**:后置一次=AI 先摆草稿(对照四列、考核四格、预审疑点),人只答三件——做的是不是这件事 / 值不值 / 可以发吗;**考核四格结论仍由人写**。
- **与五道门的关系**:门本身不删、判据不变;档位只改「谁答、答几次、什么时候答」。

## 写什么

**会话档案七段**(顺序固定):本次范围 → 用户侧记录 → AI 侧记录 → 决策与选项对比 → 开放项 → 本次产出 → 交接。
交接段**首行**必须是「下一步:<计划任务编号>」——编号要在计划 §5 的任务表里(`devlog check` 的 `S8`/`S9` 互校);计划全部完成时写「下一步:无」。
§2 每一行都必须有**落点**(`Q` 答在哪段、`D` 进了哪份 ADR、`X` 为什么排除);`S10` 把空落点和 `—`/`待补`/`无` 这类占位判成错误——「没回答的问题」最先消失的就是这一格。
档案 `status: snapshot` + `authority: 4`:它是记录,**不构成约束**。

**用户侧 8 类**:`Q` 提问 / `R` 需求 / `F` 功能 / `E` 实现探讨 / `D` 决策 / `C` 确认否决 / `X` 明确排除 / `O` 其它。
"未定的决策"必须同时进 §5 开放项——否则会烂在档案里。

**AI 侧 6 项**:需求理解(含与用户原话的偏差)/ 实现思路 / 组件归属(组件 + 位置 + REQ 或 ADR)/ 系统位置 / gap 四列(`期望 / 现在 / 证据 / 缺口`,无证据只写"未核实")/ 本轮提出的问题。

**决策对比 8 维**:语义正确性、实现成本、改动半径、可逆性、长期维护、用户可感知、可验证性、风险(允许"两者相当")。
被否决的选项**不删**:写清当时为什么没选 + **回到条件** + **触发信号**。

**契约用 EARS 句式**:`WHEN <条件> THE SYSTEM SHALL <行为>`。写不出触发条件,说明还没想清楚——先去开 ADR,别在契约里糊一句"必须好用"。每条需求另带 `verify:` 列:一条能直接跑的命令或测试文件路径,**用反引号包住**(`verify.py` 只执行第一个反引号片段);写成"人工检查一下"等于没写。详见 `references/requirements-ears.md`。

**开发计划三层**:方向 `D-n`(写成 `D1`)/ 工作 `W-n.m`(写成 `W1.1`)/ 任务 `T-n.m.k`(写成 `T1.1.1`)。唯一分层判据——**会话收尾能不能一句话说清"这个做完了"**。编号前缀是结构:`T1.2.3` 的所属必须是 `W1.2`;这三条格式与引用关系都由 `plan.py check` 机器判(码 `P1`–`P16`,输出里带 `[P?]`,可直接 grep)。

**任务有双亲**:每个任务同时挂一个功能 `F-nnn` 与一个工作 `W-n.m`(`P14`)。需求线按「必须成立什么」切、方向线按「用户怎么走通」切,两条线在任务上合流;一个功能拆 1..n 个任务,一个工作含 1..n 个任务,两者可以互相跨。先于双亲模型的存量任务才允许写 `—(历史)`,且只对**已完成**的任务开放。

方向的来源是现状,不是拍脑袋:先 `brief` + 多轮对话,把现状和方向一起说清楚——方向是这一步的结论,不是独立一步。**方向卡是方向的唯一载体**(`00-门面/方向卡.md`,一个方向一行),计划 §3 只登记 `编号 / 方向 / 卡 / 依据`,不重复写内容;`D` 是它的编号。`W` 挂 `D`,`T` 挂 `W` 与 `F`;每推完一个 `T`,回写现状与任务考核。

**六维**(只对任务打分;分越高越先做,成本取反):`U` 用户可感知 / `C` 闭环贡献 / `S` 系统完备 / `R` 正确性风险 / `V` 可验证 / `E` 实施成本。
**三视角权重**:尽快看到效果、系统更完备、核心功能优化——加视角只是加一行权重,不改脚本。

**三条硬约束**(优先于分数):门禁 > 优先级;`R=5` 且动已存数据则置顶;前置未解标 ⛔ 不排期。

## 硬规则

1. **一个事实一处**:出现两份定义同类内容,删弱的那份或降为 `reference`,不要两边同步维护。
2. **过程不构成约束**:要成为约束,必须回写契约或新开 ADR。
3. **只记要点,不逐字转录**:原话摘句 ≤ 2 行。
4. **发现即登记**:不打断用户;收件箱不是待办清单,排序归计划。
5. **`ISS-nnn` 只增不复用**;终态从主表移出:`实现关闭` 只进「已闭环」,`拒绝` 只进「已拒绝」(表名即状态,不另设状态列;字段见 `references/process-recording.md` 的「三张表」;两处都留会报 D1 / D9);开放问题不得 `实现关闭`(D5)。
6. **状态只被证据推进**:`已实现(未验收)` ≠ `已完成`;状态词必须在白名单里,否则报 P3。
7. **生成区不手改**:时间线与排序视图由脚本重建。
8. **`title` 必须与正文 H1 逐字一致**(从模板复制后最常忘)。
9. **模板内只写纯文本路径**:模板放在上层目录却要指向子目录时,相对链接两头都不对。
10. **`summary` ≤ 80 字**;`updated` 必须是真实日期,失真比错误更坏。
11. **结构只在一处定义**:加层、改目录名、加状态词、加段——只改 `assets/default-schema.json`(层表与枚举的默认来源,`doc_init` 铺骨架时读它写入项目的 `docs/_schema.json`);已有项目之后只认自己的 `_schema.json`。脚本里的默认 schema 只兜底「schema 只写了半截」的缺键,不定义项目结构,不要去那边加结构。
12. **改动分级**:判据只有一条——**这次改动有没有改变事实**。只改措辞、错字、格式、注释,且不碰契约条款、ADR、开发计划、码表、`_schema.json` 与脚本行为,算**轻档**:不新开会话档案、不跑收尾五连跑,但仍要跑改动真正触及的校验(文档 → `doc_check`;档案/收件箱 → `devlog check`;计划 → `plan check`;脚本 → `self_test`);只要动了上述任一处(含改脚本行为、加层改段),就是**重档**,走满日常三动作与收尾五连跑。**分级只决定过程成本,永不豁免校验**——同一份文件在哪一档都过同一套检查,报错照报。

**快速参考清单**(判据仍是「是否改变事实」,下表只减少判断成本;表上没列的按判据自己想):

| 明确轻档 | 明确重档 |
|---|---|
| 改错别字、标点、格式 | 改契约条款(`requirements.md`) |
| 改代码注释 | 改 ADR 内容与决策 |
| 改 README / vision 文案 | 改开发计划(方向 / 工作 / 任务) |
| 改模板占位符、示例文字 | 改脚本行为与校验逻辑 |
| 改会话档案里的非决策内容 | 改校验码(`E`/`P`/`S`/`D`/`W`/`V`) |
|  | 改 `_schema.json` 与层结构 |
|  | 改方向卡 / 设计卡的核心内容 |
|  | 改硬规则与判据口径 |

中间地带(表上没列、拿不准的)默认**重档**,但允许收尾时在档案里标注「本次按轻档处理,理由:…」——下一场 `brief` 不追溯、不补建档。**档位**:本条只管过程成本(建不建档、跑不跑五连跑);人门的数量与时机按「分工边界」的档位表(小=轻档,中 / 大=重档的两半),两处同一判据、结论不许打架。
13. **任务双亲、考核下沉**:新任务必须同时挂 `F-nnn`(功能台账里存在的行)与 `W-n.m`;`已完成` 的任务必须写验收 + 任务考核四格 + 完成于(`P15`);`已验收` 的功能只写一行「考核汇总」,不把四格复制回来(`E27`),汇总点名的任务必须真挂在该功能下(`P16`)。`—(历史)` 只给存量已完成任务,新任务不给这个口子。
14. **开场先跑 `brief`,收尾必回填 §3.7**:`brief` 是只读的开场第一动作——没跑它不算开工(它给出上一场交接锚点、未完成计划、`@日期` 到期、以及「整理:」提醒)。若它报「整理:上一场档案还没填 §3.7」,收尾时必须把本场用户原话里的 目标 / 愿景 / 功能 / 需求 抽一次(`S13` 只判填没填,`E29` 判逐字与落点)。插件侧的常驻提醒只覆盖 DSH;这一条是其他宿主也照做的兜底——**靠命令,不靠宿主**。
15. **真机验收不等于收件箱**:实现不是最终版时开 `RV` 单,别塞进 `ISS`——两者寿命不同(修完就关 vs 等有结论),混放会让「还没结论」被当成待办清理掉。`RV` 只增不复用;进度由观察记录累加,不设手写进度列;脚本只判形式(V1–V6),不判「用够了没有」「这个场景算不算新」;不主动提醒、不进开场简报(ADR-007)。**回看日到期必须拍板**:`@YYYY-MM-DD` 到期后,状态必须从「观察中」推到「已定论」(保持 / 改造 / 撤销三选一),或写明续期理由 + 新回看日;**续期最多 2 次**,第 3 次到期不许再续——到了必须拍板,哪怕结论是「保持,理由:用了这么久没出事」。时间盒防的是「永远不定」,不是逼你选错。
16. **定期减法**:开场简报报「距上次减法 N 场」,N ≥ 4 时本轮必做一次。扫描对象只有四类——硬规则、校验码、模板段落、文档段落(任务、功能、需求、ISS 各有自己的退役通道,不扫)。逐条只问四件事:还成立吗 / 还有人用吗 / 能不能并到一起 / **还服务骨架或两主线吗**(D18);结论四选一:保持 / 合并 / 降为 reference / 删除。除「保持」外当场改,依据写进本场档案 §3.10。**判据只由人给**:脚本只数场次与判断 §3.10 填没填,不判断某条规则该不该留。上次减法的位置从档案里算,不另存状态文件;一篇都没有时从第一场算起。第四问的**启用条件**=D17 真机三场观察落地(在此之前只作参考问,不单独作为删除依据——没有使用数据就删,是拍脑袋精简)。
17. **系统可视化按改动量出图、内联在文档里**:判据是**本次改动的活动件数**,不是系统体量——0 件不出图(措辞 / 格式 / 行为不变的重构);1 件单点画流程图,有状态加状态图;2 件有交互加时序图或泳道图;3 件有边界加组件图与依赖图;4 件要追因加监控看板或调用链图;横切:有界面加界面原型,用户路径变加用户旅程图。图归在文档名下(方向卡「系统现状图」、设计卡「需求落位」与「可视化」),不另立事实源;**内联**在文档里,用能像文字一样编辑比对的方式,不用截图。维护三规则:与文字**同一次提交**;**以文字为准**(图文不符重画图);**机器只查「有没有图 / 指针空不空」,画得对不对靠人**。**需求线上另有一处**:设计卡「需求落位」——每条被确认的需求写下它落在哪些组件、接口、数据或页面,现状 / 目标 / 接缝各是什么;图只画被这条需求碰到的节点与接缝,与「可视化」图是同一张时只画一次。查的时机三条:**改到哪查哪** + **需求确认时查落位** + **发版前整体查**。目录、分档表与示例见 `references/visualization.md`。

## 边界

覆盖:过程留档与追溯、决策的选项开放性、问题不丢、待分诊与开工门禁、下一步的唯一排序、形式校验自动化、存量债棘轮、门禁落地。

**机器判不了的(该认命,不是该装东西)**:

- **语义重复**:只有 `summary` 相同这一条弱信号。
- **ADR 撤销条件是否已成立**:仍要定期人工复核。反向判据(撤销条件 / 回到条件 / 走通验收)写了 `@YYYY-MM-DD` 就到期提醒(`brief` 单列「复核:已到期 N」,ISS-050 已修);没写日期的脚本判不了,也不猜。
- **条款写得对不对**:`E13` / `W7` 只判形式。
- **改动分级判得对不对**:判据是「是否改变事实」,脚本只能证明「分级不改变校验结果」,判不了这句改动是措辞还是口径变更。
- **术语唯一性**:只在被登记进别名表之后才生效。
- **「问了没答」的跨会话提醒节奏**:本技能只到「本场记进待分诊、下一次开场分诊」。

**交给别的技能的(该装,不是该认命)**:

- **「问了没答」的持续提醒与过期判定** → `open-decisions`。
- **会话该不该收尾 / 归档单** → `session-lifecycle`;决策回顾的形状与 §4 / ADR 模板仍归本技能,两边不各写一份。
- **ADR 门禁与不可变架构** → `project-engineering`;本技能只要求「决策回写契约或 ADR」。
- **外链失效** → lychee(见 `ecosystem.md`)。
- **与外部看板 / Issues 的同步**:不覆盖,也不建。

**假设:一个人 + 一个 Agent、一次一个会话**。同一工作区并行两个会话会互相踩:校验可能瞬时红(另一个会话正写到一半),`devlog.py new` 的 `ISS` 号分配与 `.dd/pending` 都不是并发安全的。要支持并发,先给编号分配与 pending 加锁再谈;加锁之前,同一工作区只留一个写者。

## 开发哲学:敏捷

先做最小框架,快速做出可用产品,再在使用中调整、优化或替换。**重 AI 是敏捷的实现方式**:不少调整只有产品做出来、真机用过才知道;可逆部分交给 AI 直接做,人只守不可逆门禁,能把「做出来再调」的周期压短。**实现不是最终版时**——两种实现对比不出优劣、明知是临时方案、或结论只能靠真机体验——选最容易回退的那一种,把接口、参数与部件保持可替换,并在真机验收台账开一条 `RV` 单:观察对象、判据(`时长:N` / `场景:N` / `信号:一句话`)、回看日,缺一不可;只留一句回到条件不算登记(REQ-044 / REQ-045、ADR-007)。

这条哲学不替代五道门:门守的是不可逆与语义对齐,敏捷管的是可逆部分的推进速度。

## 日常三动作

**开场**:

```bash
python scripts/devlog.py brief                                    # 先读:上一场交接锚点 / 计划未完成 / 收件箱计数 / 到期复核
python scripts/devlog.py new --title "本次主题" --scope "范围"
python scripts/devlog.py flow                                     # 补漏步:§2 漏记 / 待分诊 / 计划未完成(只读)
```

> `brief` 是只读命令,不写文件、不产生码。开场先跑它,是因为「先读现状」靠自觉必然失效——不读就不会知道自己落后在哪。上一场档案的 §3.7「想法候选」没填时,它会多一行「整理:」提醒——`S13` 只判填没填,判不了「这条算不算想法」,所以只提醒、不阻断。
>
> **反向判据靠 `@日期` 醒来**:在 `ISS` 的「回到条件」、ADR 的「撤销条件」、方向卡的「走通验收」里写 `@YYYY-MM-DD`(下次该复核的那天),到期后 `brief` 会单列一行「复核:已到期 N」。没写日期的那部分脚本判不了,也不猜——猜错会变成噪音,噪音会让整条提醒失效(ISS-050)。没收口的活跃问题会另起一行「回访:N 条活跃问题没设 @日期」——它们不会自己响,收口时补日期,或写明「无日期」原因。
>
> **下一步只有一个出口**:`python scripts/plan.py next` 按第一个视角给出 Top-1 与「方向 → 工作 → 任务」路径;其它视角第一名不同会并列出来——排序不是唯一答案,先看哪个由人定。
>
> **`flow` 也是只读命令**:不写文档、不新增码;开场一次看「§2 漏记 / 待分诊 / 计划未完成」,收尾一次看「§7 锚点 / §3.6 / §3.7」补齐了没有。**新建档案时 §7 与 §3.6 / §3.7 报「未填」属正常**,补完就消失。漏记判定要传本场消息条数(`--seen N`,不传只报行数——不猜);这是流程提醒,不是门禁,不许拿它阻断工作(REQ-055 / ISS-119)。

> `brief` 只给一屏现状;方向不是从这一屏直接拍出来的。先和用户多轮对话,把「现在有什么、卡在哪、哪些是旧账、哪些是新问题」说清楚,再从现状里定方向。方向卡写在 `00-门面/方向卡.md`(现状 / 为什么是现在 / 用户·起点 / 成功状态 / 路径 / 接缝 / 不覆盖 / 走通验收 / 关联),**卡没写出来之前,不要往计划 §3 加 `D`**——`P18` 会检查两处编号对上、四格(现状 / 成功状态 / 走通验收 / 接缝)不空、走通验收带 `@YYYY-MM-DD` 复核日、卡里引用的 `F-nnn` / `W<n.m>` / `K<n>` 存在(REQ-018)。**方向入计划前先回看**:在方向卡「回看(方向确立前)」写一行——上游原句(逐字)/ 已有方向(哪些 `D` 已覆盖相邻问题)/ 与它哪里重叠或空着及怎么处理;没写不进 §3,三行质量人读。**实跑走通后,把「最近走通 / 结论 / 证据」写进方向卡的「覆盖」表**——`brief` 用 `覆盖:n/m` 汇总(REQ-022);只记实际跑过的,不写计划。**工作全部完成的方向,`brief` 会列进「走通待补」**——跑一次该方向的走通验收并写进覆盖表,补齐后该行消失(REQ-023)。**覆盖只证「每步走过」,不证「步与步之间串起来走过」**——跨 ≥2 个功能点的串联写进方向卡「链路」表(起点 / 终点 / 涉及功能点 / 关键接缝 / 走通验收 / 最近走通 / 结论 / 证据),`P20` 只判形式(`F` 真实存在、接缝非空、`@复核日`、引用存在),`brief` 用 `链路覆盖:n/m` 汇总并列出「接缝待验」(REQ-039–041、ADR-006);走没走通、接缝归谁仍人判,缺链路表不报错。

> 只改措辞 / 错字 / 格式 / 注释的**轻档**改动不建档、不跑收尾五连跑;判据与「不豁免校验」的边界见硬规则 12。

**过程中**:用户说的每句话按 8 类归档(`Q R F E D C X O`),每行都要有落点;AI 侧边做边填需求理解、实现思路、组件归属、gap。发现任何问题——缺陷、缺口、债、冲突、风险、机会、待决——立刻在收件箱加一行(记类型 + 性质 + 影响 + 依据),然后继续当前话题。**不要停下来问用户要不要处理它**。要用户定的事(「要不要 X」「A 还是 B」)进待分诊而不是收件箱:`python scripts/devlog.py ask "问题" --if "什么变了它就作废"`——不占 `ISS` 号,所以门槛低;收尾前必须分诊(`pending --clear`),否则下一场 `new` 会被挡住。

**消息路由**(REQ-054):每条用户消息到达,先按 8 类判类、再按映射接入——这是流程的入口,不是又一扇门。**判类之后先落任务记录、再按入口推进**:会话档案 §2 一行就是这条消息的任务(类型 / 原话 / 入口 / 状态四格),**没有入口不许推进**——「找不到入口」恰是要接入的信号,不是跳过的理由。人话对照:**提出需求=`R`、寻找方向=`E`/`D`、提出问题=`Q`**;判不准先用这三问回落,仍判不了归 `O`。

| 类 | 接入点 |
|---|---|
| `Q` 提问 | 直接回答(拿证据用 `brief` / `next` / `tree`);提问的任务就是回答本身,不另开计划任务;答出决策 → 转 `D` |
| `R` 需求 | 回看三行(档案 §3.3)→ 对齐门(复述 / 采纳)→ 立项 |
| `F` 功能 | 评审门三问 → 拆分闭合 → 进计划 |
| `E` 实现探讨 | 先广度后深度 → 设计门 / 复述门 |
| `D` 决策 | 复述门(按反悔成本判必过 / 可免)→ 档案 §4 决策块 |
| `C` 确认否决 | 更新对应载体的状态(采纳 / 驳回) |
| `X` 明确排除 | 写进「不得做的事」或卡的不覆盖 |
| `O` 其它 | 兜底回落:按当前任务推进(执行指令、插话、确认) |

三条规则:**每条消息必有任务记录**(§2 一行四格;提问类的任务就是回答本身);**复合消息以主类接入**(如「提交推送打版」=`D`+执行,主类 `D` 过复述门、执行按当前任务推进),副类照常进档案 §2;**判不了先三问回落、再归 `O`**,用户纠偏后重路由,不静默。映射是提示、不替代任何门——门照过;判类与记录是语义活由 agent 判,不新增脚本判据,也不构成跳过门禁的理由。

### 编辑与批量重构

同一模式要在多处(≥3 处)重复改时,先出**精确编辑清单**——每条写清文件、位置(**原文锚点**:从目标文件逐字复制、能在目标中唯一命中的一段文字,不用行号——插一行就漂)、旧文本 → 新文本,先贴进会话(或落盘)再动手;锚点出现 0 次(目标已变)或多次(会顺手改错行)都不许应用,按目标原文重取后再写;再写一次性脚本(模板 / 正则替换 / 批量写)一趟应用,同一变体只写一次规则;应用后核对 diff:清单内的每条都命中、清单外的文件不动,对不上先修脚本再重跑,不用手改补漏。只改一处、或探路性改动不在此列。

**同一文件改多处(≥3 处)也走同一套清单**——哪怕不是同一个模式(2026-11-13 实战教训:一个前端页面单场改了 19 次、
一个服务文件 16 次,其中两次「改坏再补」)。因此:① 先读目标函数的**完整边界**(`with` / `try` / 缩进段),把相邻语句
一起放进锚点上下文,别只裹住要改的那一行;② 清单里逐条写「锚点原文 → 新文本」,一次应用;③ 应用后**读回目标段落**,
确认清单外一行没动。两类已实测的返工都由此而来:替换两行只写回一行,**吞掉下一句**(`concept_ready` 被吞);在
`session` 关闭后访问 ORM 对象(`<LearningGoal …> is not bound to a Session`,LLM 调用在 `with` 外,角度块必须在
`with` 内先算好)。

**开工前先列「落地清单」**:口径 / 决定落定后、动手前,先把这次要动的点列全——**代码点 / 测试点 / 文档点**,每点写文件 + 位置(或原文锚点);一次编辑到位,收尾逐点勾。与上面的**精确编辑清单**分工:后者管「多处同模式怎么改」,这条管「这次一共要改哪些点」,两者可并用。依据是外部会话实测(2026-11-12):单页 16 次、`FEATURES.md` 12 次补改,16 组 repeat_edit 升级信号——边做边补改时,「改完没改完」无法自查。验收信号:同规模改动的 repeat_edit ≤2 次 / 文件(`session_review(friction=summary)` 可回看)。

**问题四维**:层(候选 `Q` / 台账 `ISS` / 约束 `REQ`/`ADR`/`D-W-T`)、状态(确立 → 实施中 → 实现关闭 / 拒绝;候选在待分诊,不占 `ISS` 号)、性质(可关闭 / 开放)、类型(缺陷 / 缺口 / 债 / 冲突 / 风险 / 机会 / 待决)。**开放问题永远不进「实现关闭」**:一轮做完回「确立」,带着新的「本轮边界」和「回到条件」。每个状态的「依据」都要写清:确立为什么是真问题,实施中做到哪 / 卡在哪,关闭凭什么说解决了,拒绝为什么不做、什么条件重来。

**真机验收不是问题收件箱**:它不是缺陷、不是待办,寿命是「等到有结论」而不是「修完就关」。遇到非最终版实现,用 `python scripts/devlog.py rv new --object "F-nnn / W<n.m>" --kind 场景 --threshold 5 --why "为什么现在定不了"` 开单;样本型按**不同场景**计,同一场景用十次不算十份数据。状态只有三档:观察中 → 信号已足待拍板 → 已定论;`rv list` 只提示「到门槛了」,拍板与结论仍归人。结论三档出口:`保持:一句话` / `改造:T 或 REQ 编号` / `撤销:回滚 <commit 短号>`,后两者必须能落地,否则不许写「已定论」(V4)。**这张表不进开场简报、不显示计数**——用户问「还有哪些问题」时才 `rv list` 展开。

**新增 ISS 前先查一次**:`python scripts/devlog.py inbox --similar "这条问题的表述"` 摆出字面候选,把「是包含 / 扩展 / 还是独立」讲给用户定;转正时 `pending --clear <Q> --as iss --relation new|merge:ISS-nnn|extends:ISS-nnn|updates:ISS-nnn|duplicate:ISS-nnn`——`new` 由脚本自动分配 `ISS-nnn`,`--type/--impact/--to` 三格必须由你给,`--nature` 缺省按类型推断(机会 / 待决 = 开放,其余 = 可关闭)。

**收尾**:先做一次**决策回顾**——只对**用户拍板的**决策,逐条回答「背景 / 影响 / 依据(用户原话照抄)/ 为什么更合理(对比维持现状或被否备选)/ 撤销条件」;答不出的标「断链」并用 `python scripts/devlog.py ask` 进待分诊。agent 的实现选择不进回顾;窗口与现查四路见 `references/process-recording.md` 的「决策回顾」一节。**真机验收记一笔**:问用户一句「这段时间用到了吗」;用过的用 `python scripts/devlog.py rv add <RV-id> --scene "场景" --observed "看到什么"` 记一条;会话里出现「刚试了…」这类痕迹时由 AI 直接补,记录人标 AI(用户主动补的标 用户)。**摩擦回顾**:顺手在档案 §3.6 记本轮摩擦——同一动作 ≥3 次 / 同一失败 ≥2 次 / 某一步明显超出预期;会再犯的转收件箱(机会 / 债),只影响本轮的不转。**成本自报**:在档案 front-matter 写 `cost_minutes`(本场总耗时,分钟)、`cost_tool_minutes`(其中花在门 / 预审 / 校验上的)、`cost_note`(卡在哪、比上一场省力还是更费);`devlog.py cost` 会汇成 `70-过程/成本台账.md`(自报 + 自动密度 + 环比)。**想法整理**:从本场用户原话里抽出 目标 / 愿景 / 功能 / 需求 四类想法写进档案 §3.7——原话逐字(`E29` 会对着出处核,改一个字就拒收),并给出落点建议(vision / `D-n` / `REQ-nnn` / `F-nnn`);**人裁决之后**才写进载体,整理本身不新增写入路径。然后跑:

```bash
python scripts/devlog.py flow --seen <本场消息条数>   # 先查漏步:§7 锚点 / §3.6 / §3.7 / §2 漏记 / 待分诊
python scripts/devlog.py check      # 七段顺序、front-matter、ISS 引用、文件名
python scripts/devlog.py index      # 重建时间线 + 决策台账 + 成本台账
python scripts/plan.py check        # 编号 / 分值 / 状态词 / 所属工作 / 前置与方向引用
python scripts/plan.py index        # 重建排序视图
python scripts/plan.py tree         # 只读全貌:方向 → 工作 → 任务(要页面加 --html --out x.html)
python scripts/doc_check.py         # 全库字段与链接
```

**一条命令串跑(与上面同序、留运行记录)**:`python scripts/observe.py five-run` 按**上面相同的顺序**跑完五步(`doc_check` 最后),任一步失败即非零退出;每步写进一条运行记录(`.dd/observe/runs/<run_id>.jsonl`)。收尾时把 `run_id` 记进本场档案 §6——它只增记录、不改台账状态,顺序由 `self_test` 第 72 组用独立期望序列盯住。`devlog check` 校验 §6 引用的 `run_id` 真实存在(`S15`);没写只提醒(`W14`),分开跑五条时写「无(分开跑)」——判不了「这次该不该用串跑」,所以只提醒、不阻断。

全部 0 error 才算收尾完成。新建档案在填完 §7 前会报 `S6 交接段过短` WARN 与 `S8` 提醒,属正常;§7 已写正文、首行却不是「下一步:<任务编号>」时,`S8` 才是错误。

**`完成于` 的顺序**:`完成于` 记的是**提交之后**才有的 commit 短号,所以收尾按这个顺序——先提交代码与文档 → 再回写 `完成于` / `已验收` → 再补一次 docs 提交。写 `待提交` 不算记:`P15` / `E27` 都按缺锚点报(ISS-046)。没有锚点的「已完成」不可回滚,等于只能靠记忆复原。

回写状态有一条命令,不必三个文件手工改:`python scripts/plan.py set-status <T-id> --to 已完成 --commit <短号> --review "做法=…|一致=…|代价=…|结论=…"`(`--dry-run` 只打印清单)。它只写既有列、先验「改完之后」的文本、任一校验失败零写入、重跑幂等,不新增状态载体(REQ-017);人工编辑仍是等价路径。

建一个功能同样有一条命令,不必在五份载体上手改:`python scripts/plan.py new-feature` 一次写 `REQ` / `F` / `W` / `T` / `K`——编号从表格首列自动 `max+1`(正文里的 `F-999` 反例不算),落点按表头名定位(功能行插在 `F-001` 之后,不会掉进「任务考核」表),先验「改完之后」的文本、任一校验失败零写入;`--work-id W1.1` 表示挂已有工作(不新建 `K`),`--dry-run` 只列清单(REQ-031)。

契约回检另有一条:`python scripts/verify.py` 按每条需求的 `verify:` 真跑(失败/超时 → exit 1,状态=`待实现/阻塞` 的行跳过)。它可能很慢,所以**不在收尾五连跑里**;CI 每次 push 跑它,改了契约或测试再本地跑一次。

**实施完之后先对照,再测**(顺序别倒):

```bash
python scripts/devlog.py features --state 实施中   # 取数:这次要对照的功能
```

按 `40-运行/功能对照.md`(`doc_init` 铺的就是它;模板在包内 `assets/templates/feature-check.md`)填四列(功能 / 该验什么 / 结论 / 差异 · 证据),结论只有 `一致 / 差异 / 未覆盖` 三种;写「差异」「未覆盖」必须同时登记一条 ISS。差异清完、入口与行为对得上,才把功能状态推到 `已对照`,再跑测试推 `已验收`——**测试证明符合断言,对照证明断言写的是需求那一句**。

第一次接入**存量项目**时用棘轮,别试图一天清完:

```bash
python scripts/doc_check.py --update-baseline   # 记下当前债务
python scripts/doc_check.py --baseline          # 之后只许降不许升
```

## 主干道:从需求到证据

一句话:**需求定"必须成立什么",功能定"交付哪一块能力",设计与任务定"怎么做、先做什么",证据定"到底做到了没有"**。十一格,每格都有落点:

| # | 阶段 | 落在哪 | 判据(机器 / 人) |
|---|---|---|---|
| 1 | 需求 | `20-契约/requirements.md` 的 `REQ-nnn`(EARS + `verify:` + `确认`) | `E18` / `E22` / `E23`;`verify.py` 真跑;**回看三行=人读(需求 §3.3 / 方向卡 / 设计卡 / 决策块);拆分闭合表=人读(档案 §3.3,每处 1→N 各一行)** |
| 2 | 功能 | `40-运行/FEATURES.md` 的 `F-nnn`(评审 / 考核汇总 / 完成于) | `E24` / `E27`:状态词、需求引用、评审、入口、证据、汇总 |
| 3 | 工作 | 计划 §4 的 `W`,挂在方向 `D` 上 | `P3` / `P12`;六维评分与三视角排序 |
| 4 | **设计** | `00-门面/设计卡.md`,一个工作一张(接口 / 可替换点 / 扩展点 / 失败边界 / 任务拆分);重要取舍开 ADR | `P19` 判「还没做完的工作有卡」与三格非空;**可替换点的质量=人** |
| 5 | 任务 | 计划 §5 的 `T`,**同时挂 `W` 与 `F`**(双亲) | `P1`–`P16`、`P19`:编号、分值、状态词、前置、功能存在、已完成有考核、设计卡;**两条边各自的闭合=人读(档案 §3.3)** |
| 6 | 实施 | 代码 + CI | 人 |
| 7 | 冒烟 | `python scripts/self_test.py`(本仓库;你的项目里=一条最便宜的端到端命令) | 人(只为让"对照"有可观察对象) |
| 8 | **对照** | `40-运行/功能对照.md` 四列:功能 / 该验什么 / 结论 / 差异 · 证据 | 入口存在=`E24`(机器);**行为覆盖=人读**;差异必须落一条 `ISS` |
| 9 | **考核回顾** | 任务行:`做法 / 一致 / 代价 / 结论 / 完成于`(FEATURES「任务考核」表);功能行:一行「考核汇总」;另记流程回顾、开放问题、可调整 / 可优化 / 可替换 / 可扩展评估 | `P15` 判任务四格齐全,`E27` 判功能汇总齐全;**写法与判断=人**;结论=改造时回到设计或定任务 |
| 10 | 测试 | 契约的 `verify:` 命令 | `verify.py`(0 / 1 / 2);`--strict` 让跳过也算失败 |
| 11 | 回写 | 需求 → `已实现`;任务 → `已完成` + 任务考核;功能 → `已对照` → `已验收` + 考核汇总 + 完成于 | `E22` / `E23` / `E24` / `E27` / `P15` / `P16`;状态只被证据推进 |

**轻档改动**(只改措辞 / 错字 / 格式 / 注释,且不碰契约 / ADR / 计划 / 码表 / `_schema.json` / 脚本行为)不建档、不跑完整主干;只跑改动触及的校验(硬规则 12)。**设计卡按改动大小伸缩**:小改动写 3 行(接口 / 可替换点 / 失败边界);没有可替换点的写「无」并说明为什么。

**五道门**:

- **对齐门(需求 / 方向确立前)**:需求与功能都必须在用户**复述/采纳**之后才立得住——需求行写 `确认`(`复述✓ 2026-11-01|档案 §` 或 `采纳✓ …`),功能行写「评审」列。`E23` 判"已实现的需求必须有确认",`E24` 判"已评审的功能必须有评审结论"。没对齐就不立项。**回看先于复述**:① 需求写 `确认` 之前,先在档案 §3.3 写三行——上游原句(用户原话或方向卡哪一句,逐字)/ 系统里现在有什么(已存在的功能、契约、决策、代码入口)/ 这一条与它哪里对不上(重复 / 冲突 / 缺口)及怎么处理;② 方向写进计划 §3 之前,先在方向卡「回看(方向确立前)」写一行——上游原句(逐字)/ 已有方向(哪些 `D` 已覆盖相邻问题)/ 与它哪里重叠或空着及怎么处理。没写只停在 `待确认` / 方向不入计划;`E23` 与 `P18` 判不了三行的质量,由人读。
- **评审门(功能 / 工作进计划前)**:`待评审` 推到 `已评审` 之前必须答完三问——满足需求吗(挂哪条 `REQ`)、能实现吗(依赖与卡点)、代价合理吗(`S/M/L` + 一句话)。没过不进计划。**三问之后还要闭合一次**:功能与工作各是一次 1→N 拆分,写「已评审」前在档案 §3.3「拆分闭合」表各写一行——上层原句(逐字)/ 下层清单(`F` 或 `W`)/ 各条覆盖上层哪一句 / 漏了哪段 / 多了什么或哪两条重 / 结论;需求→功能、方向→工作两处都要写。没写不进计划;`E24` / `P3` 判得了引用、判不了「合起来是否等于」,由人读。
- **设计门(设计卡定稿前、拆任务前)**:接口稳定吗、可替换点隔离了吗、扩展点合理吗、失败边界写清了吗、任务拆分覆盖设计吗。卡写在 `00-门面/设计卡.md`(`## K<n> · W<n.m> · 标题`),`P19` 判「待开工 / 进行中的工作有没有卡」与接口 / 可替换点 / 失败边界非空;**设计卡没定,不拆任务**。**拆之前先回看上游**:每张设计卡写一组「回看(拆分确立前)」——上游原句(REQ 或方向卡哪一句,逐字)/ 系统里现在有什么(已有任务、覆盖、代码入口)/ 拆出来哪里可能漏或重及怎么处理;没写不拆任务,质量人读。**拆完再闭合**:同一批任务写完后,在档案 §3.3 闭合表写**两行**——对 `W` 一行(这批任务合起来是否等于该工作)、对 `F` 一行(是否交付该功能,任务双亲),都写上层原句 / 下层清单 / 覆盖 / 漏 / 多或重 / 结论;没写不拆任务。**先广度后深度**:用户提议只是备选,不是讨论边界;选项空间至少 3 个结构不同的方案(含一个不做 / 少做、不同轴),被否方案留「回到条件 / 触发信号」,可切回;`W10` 只判这个形状,广度够不够仍人读;`W12` 只提醒「待开工 / 进行中」的卡缺「观测四格」,存量不追溯。
- **对照门(实施后、测试前)**:`E24` 只能证明"入口存在","做的是不是这件事"要人读;差异不落 `ISS` 不许推到 `已对照`。`W9` 只提醒「已验收功能在对照清单里有没有行」,不判「对照过」——有行 ≠ 对照过。
- **对照门与考核门的衔接**:两道门中间只隔「跑 `verify:` 测试」。如果测试在本场内跑完,两道门**连续过**——同一次回顾先填对照四列、再写考核四格,省一次上下文切换;如果测试跨会话(很慢 / 要等环境),对照门在测试前过、考核门在测试后过,各写各的档案。门的结构、产物、门禁不变,只是"能不能连过"取决于测试是否在本场内完成。
- **考核门(`已验收` 之前;考核落在任务上)**:每个 `已完成` 的任务在 FEATURES「任务考核」表里写满 `做法|一致|代价|结论` 并记 `完成于`(`P15`);功能行只写一行 `考核汇总`(`各任务考核见 T…|整体一致|代价|结论`,`E27` + `P16` 判汇总有来源)。结论为「改造」,或开放问题要求实现更可调整 / 可优化 / 可替换 / 可扩展时,**回到设计或定任务**,不硬推到已验收。

**门的密度按档位伸缩**:见「分工边界」的档位表——门本身不删、判据不变,只改谁答、答几次、什么时候答。

**可观测性(四维 / 四问)**:项目侧在 `40-运行/可观测性.md` 写清组件与串联怎么被观测;设计卡写「观测四格」(观测对象 / 要回答的问题 / 信号 / 窗口),`W12` 只提醒「待开工 / 进行中」的卡、存量不追溯。四维是**可观测 / 可解释 / 可诊断 / 可改进**;四问是**运行的是什么 / 为什么是这个结果 / 预期是什么样的 / 系统下一步是什么**——四问是记录内容,四维是验收框架;可改进要跨 run 聚合(稳定 `key` + `tool_version`),单次记录答不了。技能只提供模板 / 检查 / 参考实现,不替项目跑运行时。**自身参考实现**:`python scripts/observe.py five-run` 串五连跑(与「日常三动作 · 收尾」同序:先重建生成区,`doc_check` 最后)、`observe.py run -- <命令>` 包一条命令,记录落 `.dd/observe/runs/`;`show` / `status` / `trend` 只读回看(`trend` 按「码 + 目标文件」跨 run 聚合复发 / 趋势),写失败只降级、不改主命令退出码。

**回复形态(五道门内生效)**:先判这一轮 agent 在出什么——**提案**(设计对比、方案取舍):用伪代码或白话,不拿现有实现的文件 / 函数 / 行号当论据,提现状一句「当前实现如此」;**说明**(对照门讲解、考核门「做法」):优先伪代码,标「伪代码」,不冒充真代码;**锚点**(代码入口 / `verify:` / 测试组号与实际输出 / `完成于`):必须真路径 / 真命令 / 真 commit,伪代码不能替代——否则对照成自证、回滚无目标。**一次一维**:广度一次给(方案名 + 一句差异,含一个不做 / 少做),但这是**起步集、不是全集**——给完留一句「你也可以提新方案 / 改一条」,不把列表写成闭集;广度轮先不排序、不写初判(要推荐就等用户补完,或明说「暂定偏好,不是边界」)。深度按维度逐轮,每轮一维,结尾「下一维:X,继续?」;拆开就判不了的不拆(评审三问、考核四格整组给)。**每轮改动:AI 自查+用户反馈**:本轮动了代码 / 脚本 / 文档(含 agent 自己改的),AI 先自查——跑改动触及的验证(`verify:` / 冒烟 / 相关校验)并核对行为,回复报自查结果,失败如实报、当场修到过再交;回复末尾固定带一行「验证」给用户当场体验——能跑给可复制命令+预期结果,纯措辞 / 格式改动给一句「看哪里、看什么」;用户反馈不对 → 当场修(可逆)或落 `ISS`。全档位生效,不落档、不推状态、不替代收尾五连跑与对照门——它是人的即时感知,不是机器校验的重跑,也不占用「对照」一词(对照门是功能级;D1 / D2,2026-11-11)。

**回复档位(默认「强」)**:同一个人的可读性需求会随经验变化,所以按档位输出,使用中随时可切。三档只定义「写到多深」,不改变事实与判据。

- **强(默认)**:读者零代码经验。固定三段——① **结论一句**(发生了什么 / 要不要你动手);② **依据**(业务词为主;实现词首次出现给一句人话;一条回复最多一个编号且放句尾;不出现命令、路径、判据码);③ **要你做的事**(没有就写「这条不用你动手」)。一条回复最多一张表。
- **标准**:懂实现、要密度。按上一段「提案 / 说明 / 锚点」三层写,一次一维。
- **精简**:熟练用户。只给结论与可选锚点,不复述背景,细节等追问。

档位存在项目根 `.dd/reply-tier`(一行,不进版本库——它是「这台机器上的这个人」的偏好)。`python scripts/devlog.py reply-tier` 看当前档位,`--set 强|标准|精简` 切换;`brief` 每场显示。文件缺失或值非法按「强」输出:偏好坏了不该让会话停住。

**预审(LLM 辅助,只出疑点)**:评审 / 设计 / 对照 / 考核四门前,可以让 agent 先跑一次预审——只产出「指向 / 逐字引文 / 疑点 / 建议动作」四格,**裁决由人填**;引文必须逐字(`E30` 拒收改写),记录表头不得有状态 / 确认 / 评审 / 考核列。对齐门(复述 / 采纳)、发版 / 回滚、开放问题收口**不预审**,只列「不适用」。预审是建议,不是判决。

**主干之外的两处决策(也必须由人拍板)**:① **开放问题收口**——回顾与收尾时,哪些 `ISS` 关、哪些挂着、哪些回到条件已成立;② **发版与回滚**——打 tag、发 release、装到宿主、用 `完成于` 回退已验收的实现,都是不可逆或半不可逆的动作。发版前还要做一次**全库图核对**:图与文字不一致时以文字为准,重画后再发(`references/visualization.md`)。这两处不在五道门里:门按「一次开发怎么走」排列,决策按「什么时候值得冒不可逆的险」出现。

**复述门(每次用户拍板前,必做)**:用户要做决定时,**只核两件事**——① **这次要你做什么**;② **做错后推翻代价多大**。不问术语定义、不考记忆、不出刁钻问题。用户答不上来时换人话解释到懂,不换更难的问题、不催点头。用户可回「**强制过:<原因>**」直接过门:原因必须写清「为什么现在必须过、你担心什么」;原因空不能过,只有一句口号(如「来不及」)追问一次。档案记 `**复述**:强制过——<原因>`,不判失败,也不写成「已复述」。判据按反悔成本:**必过**——发版 / 回滚、方向、边界(层归属、写路径、接口)、契约口径变化;**可免**——纯实现选择、行为不变的重构(写「拍板:agent 自选」)。落台账时,用户拍板的决策块「依据」**必须引用用户原话**(`「…」`,照抄不改写),且该句在本档 §4 之外的正文里逐字可查(`S12` 判);决策块留一行 `**复述**:要做什么 / 推翻代价` 作痕迹。复述质量仍由人判——机器只保证「有据可查」,保证不了「理解一致」。

**预审判据(载体是这段规程,不是脚本)**:评审 / 设计 / 对照 / 考核四门前跑预审时,**任何端、任何模型都按同一套扫**——规程随包走,产物落本场档案 §3.8(`E30` 校验形状,裁决留人)。

1. **先定位**:写清审的是哪道门、哪个对象(`REQ-nnn` / `F-nnn` / `W<n.m>` / `T<n.m.k>` / 某篇档案),不写「整体审一遍」。
2. **按链扫**:需求 → 功能 → 任务 → 考核 → 对照,逐环看三件事——**编号在不在**(引用的 id 真实存在)、**状态对不对**(`已实现` 有确认、`已验收` 有汇总与完成于、`已完成` 有考核四格)、**证据指向真东西**(`verify:` 是能跑的命令;「证据」写的是日期 + 来源,不是形容词)。
3. **只报两类**:**断链**(指向不存在 / 状态与证据对不上)与**过期**(日期早于最近一次改动、引文与原文不符——引文必须逐字抄,`E30` 会核)。报不出具体断在哪的,不报。
4. **宁少不错**:误报比漏报更伤——一条误报就让人开始不信预审。拿不准的写进「疑点」时点明「不确定」,不给建议动作。
5. **不代判**:不写状态、不改台账、不填裁决;建议动作只有 `补证据 / 改条款 / 维持` 三选一;「对齐门 / 发版 / 回滚 / 开放问题收口」写「不适用」。

**为什么对照在测试之前**:测试证明"符合断言",对照证明"断言写的是需求那一句"。顺序倒了,会拿"为错方向写的测试全绿"当完成证据——这正是这套实践要消灭的假通过。

**为什么考核在测试之前、回写之前**:对照只看"做的是不是这件事",考核还要回答"做得值不值、代价估错没有、下次怎么改"——它是给用户看的**实现回顾**(一行做法 + 一致度 + 代价偏差 + 结论),也是系统在回写前的最后一次自检。**它在任务级**:一场会话能做完、能验证、能考核的只有任务;功能一大会退化成整块总结,写不出「代价估错没有」。功能行的汇总只回答「这些任务整体值不值」,并且点得出是哪几个任务。还要多问一句"现在的实现经不经得起下一次改动"——可调整、可优化、可替换、可扩展;答案是否就回到设计或定任务,而不是硬推到已验收。

**为什么冒烟在对照之前**:对照要观察行为,跑不起来就无从对照;冒烟只为"能起",不追覆盖率。

**推翻与回滚**:需求作废走 `_delta` 的 `REMOVED`(编号作废不复用,`_archive/` 留档);功能撤回把状态改成 `撤回` 并在「考核」里写理由。要回到某个功能之前,用 `完成于` 里的 commit:`git revert <commit>` 或 `git checkout <commit>^ -- <文件>`;要回到某个需求之前,先作废它、再按 `完成于` 回滚实现——**先改文档再改代码,才不会出现"代码回退了但需求还写着已实现"**。


## 从不空手开始

`doc_init.py` **只在技能目录里**(它要靠 `../assets/templates` 取模板,所以不会被复制进项目)。在项目根目录直接写 `python scripts/doc_init.py` 会报 `can't open file`——初始化必须带技能目录绝对路径:

```bash
python "<技能目录>/scripts/doc_init.py" --target .              # 5 层:门面/契约/决策/运行/过程
python "<技能目录>/scripts/doc_init.py" --target . --full       # 再加 架构/术语/规范
python "<技能目录>/scripts/doc_init.py" --target . --full --ci  # 另写 pre-commit + GitHub Actions
```

技能目录本机是 `~/.qwenworkcn/skills/doc-driven-development`。

幂等,不覆盖已有文件。落地内容:层目录、**`docs/_schema.json`(层/枚举/段结构/编号规则/路径的唯一来源)**、README、开发计划、需求清单、收件箱、时间线、会话模板、ADR 模板、过程层协议入口、别名表、最小占位文档,并把 `doc_check.py` / `devlog.py` / `plan.py` / `verify.py` 复制进 `<target>/scripts`——日常命令才是「在项目根目录跑 `python scripts/<脚本>.py`」这个形式;前三件是收尾门禁,`verify.py` 供 CI 回检契约。

铺完先跑 `python scripts/doc_check.py`,应为 `errors=0`(若有 `E9 层为空`,说明有层没内容:补一篇或从 `_schema.json` 删该层)。

## 坑(都是真实踩过的,不是假设)

- **同一文件逐点 edit 十几次** → 返工与上下文成本双高(2026-11-13:ThemePage 19 次、path_generation 16 次、metrics 6 次);
  且最容易「替换两行只写回一行」吞掉相邻语句、或在 `session` 关闭后访问 ORM 对象。改 ≥3 处先出清单、先读完整函数边界、
  改完读回目标段落(见「编辑与批量重构」末段)。
- **从模板复制会话档案后忘改 `title`** → E4 立刻报。顺序应该是:先改 front-matter 的 `title/session_date/session_no/scope`,再写正文。
- **在模板里写相对链接** → 模板被复制到 `会话/` 子目录后,指向 `../00-门面/x.md` 的链接两头都不对。模板内只写纯文本路径(不带 `[]()`)。
- **开放问题的 ISS 不填「回到条件」** → D2 报错,但更重要的是:三个月后没人知道该不该把它捡回来。开放问题不是「没做完」,是「没有做完这个判据」——它的落点是「这一轮做到哪 + 什么信号回来」。
- **把 `authority: 4` 的会话档案当裁决依据** → 记录变成了判决书,整套权威体系随之失效。
- **表格 cell 里写了未转义的竖线** → 整行错位,每一格都往后挪:`E18` 读到别人的内容、校验全绿而 CI 的 verify 红(REQ-014 就这么跑过半天绿)。转义成 `\|`(脚本认),或改写成「A / B / C 三列」;`E28` 判。
- **把模块内部的异常处理写进方向卡的「接缝」** → 方向线退化成一张多余的纸:接缝写的是**步与步之间**(上一步的输出/失败/权限/空状态怎么影响下一步),异常处理归设计卡的「失败边界」(`P19`)。`P18` 判不了这句写得对不对,只能人读(ISS-069)。
- **契约层写成说明文** → 全篇没有「必须/不得」,E13 会拦;但 E13 只能拦形式,句子的可判性仍要人读。
- **ADR 只写「为什么没选」,不写「回到条件」** → 决策变成单向门,半年后没人敢推翻它。
- **写「完成」而不是「已完成」** → 不在状态白名单,P3 直接报(旧版会静默把它当成未完成继续排序,那才难查)。
- **把旧称留在门面/契约/规范里** → E16 会报。历史快照与 ADR 不扫描,它们记录的是当时口径。
- **`.skill` 是构建产物** → 改了源仓库的脚本要重新打包,否则技能里的版本会悄悄落后(这份包就因为漏了重新生成,曾缺 8 条规则)。
- **手改五处建功能** → 漏一处不会报错;往 `FEATURES.md` 末尾追加功能行更会落进最后一张「任务考核」表(`E24` 看不见它,首列不是 `F-nnn` 的行直接跳过),校验全绿而台账少一行。优先用 `plan.py new-feature`(插在 `F-001` 之后、先验后写);手工编辑时功能行仍要插在 `F-001` 那一行后面。
- **串跑工具的顺序与收尾口径写反** → `doc_check` 会先于生成区重建跑,校验的是旧产物;顺序错了也全绿(自测只断「5/5 都过」)。`five-run` 现在与收尾同序、`doc_check` 最后,第 72 组用独立期望序列盯住。

## 现实不配合时怎么办

| 情况 | 正确行为 |
|---|---|
| `python` 不可用(Windows 常见,只有 `python3` / `py` / `py -3`) | 换 `python3` 或 `py -3` 重试;仍失败就如实报告"脚本没跑成",**不要假装跑过了** |
| `python scripts/doc_init.py` 报 `can't open file` | 正常——`doc_init.py` 只在技能目录里。改用 `python "<技能目录>/scripts/doc_init.py" --target <项目>`;装完之后 `doc_check/devlog/plan` 才在 `<项目>/scripts` 里 |
| `docs/` 不在默认位置 | 用 `--docs 文档` 指定。各脚本都会先找 `docs` / `文档` / `documentation`;找不到会**直接 exit 2 并说明**,不再返回 `errors=0` 的假通过 |
| 项目已有一套自己的文档体系 | 先只跑 `doc_check.py` 摸清现状,不要 `doc_init` 覆盖;用 `--update-baseline` 记下存量,再逐条收敛 |
| 校验报错但用户说"先别管" | 把错误原文写进会话档案 §3.5 与收件箱,继续当前话题(符合"发现即登记"),不要静默丢弃 |
| `verify.py` 很慢 / 命令要联网 | 调 `--timeout`、先 `--dry-run` 看要跑什么;不要为了变绿去删契约行或把状态改回「待实现」——那是拿掉证据,不是修好 |
| 用户的项目要过合规审计(ISO 26262 / DO-178C / IEC 62304) | 契约层改用 StrictDoc 或 sphinx-needs 承载,本实践只保留过程层与计划层。见 `references/ecosystem.md` |
| 用户想整套换成 Spec Kit / BMAD / Kiro | 说明它们解决的是"一次变更讲清楚",不是"项目连续演化留痕";可借鉴格式,不建议替换过程层 |

## 按需加载

| 文件 | 何时读 |
|---|---|
| `references/reference.md` | 模板与脚本完整清单、按需加载全表(本文件只列索引,细节在那) |
| `references/layer-model.md` | 判断某份文档该放哪层、`status`/`authority` 填什么、要不要加层、怎么改 `_schema.json` |
| `references/process-recording.md` | 写会话档案、分类用户消息、做八维对比、收尾的决策回顾、设计收件箱字段 |
| `references/plan-model.md` | 建/改开发计划、状态词表、加维度或视角、判断某物该是方向还是任务 |
| `references/visualization.md` | 要画系统图、判断该不该出图 / 出哪种图、图放哪、什么时候查 |
| `references/requirements-ears.md` | 写契约层、把含糊需求改成可判真假的一句话、理解 E13/W7 的边界 |
| `references/check-rules.md` | 校验报错看不懂、要解释"为什么这条必须机器判"、接 CI |
| `references/ecosystem.md` | 要不要换现成工具、哪些交给 lychee / StrictDoc / sphinx-needs、为什么不整套替换 |

## 模板与脚本

详细清单见 `references/reference.md`。这里只列目录级入口:模板在 `assets/templates/`(含 `docs-README`、`session-record`、`inbox`、`verification`、`timeline`、`dev-plan`、`adr`、`requirements`、`features`、`direction`、`design`、`observability`、`feature-check`、`alias-table`、`process-readme`),CI 样例在 `assets/ci/`,`AGENTS.md` 片段在 `assets/agents-snippet.md`,DSH 薄模式样例在 `assets/dsh-preset/`;脚本在 `scripts/`(`doc_init` / `doc_check` / `devlog` / `plan` / `verify` / `self_test` / `observe` / `yaml_rules`)。

脚本按**表头**识别维度列(单大写字母列即维度),因此加维度、加视角都不用改代码。

## 验收

1. `doc_init.py` 铺完,`doc_check.py` 为 `errors=0`。
2. `devlog.py new` 能建出编号与文件名正确的档案。
3. 故意制造断链、ADR 缺段、`summary` 超长、ISS 重复、分值越界——五种错误都能被报出。
4. 改任一任务行后 `plan.py index --check` 报过时;重跑 `index` 后转为 up-to-date。
5. 时间线按日期倒序列出全部会话,链接可点。
6. 把某篇契约的「必须」删掉 → E13 报;把 `superseded_by` 指向不存在的 ADR → E15 报。
7. 在 `docs/文档` 而不是 `docs/` 下铺骨架 → `doc_check --docs 文档` 通过,`devlog.py` / `plan.py` 不报假通过。
8. **跨天**:铺完骨架后把 `会话档案模板.md` 的日期改成昨天(模拟"骨架是昨天铺的"),再 `devlog.py new` → `check` 必须 0 error,文件名前缀 = `<session_date>-<session_no>-`,时间线日期列与档案标题同一天。2.0.0 就是缺这一条:`doc_init` 把模板里的 `{{DATE}}` 烤死在铺骨架那天,第二天起每次开档都自相矛盾。
9. 前置写一个表里不存在的编号 → `plan.py check` 报 `[P11]`;工作表方向列写 `D9`(方向表里没有)→ 报 `[P12]`。查不出这两条时,任务会被永久标 ⛔ 且没有任何诊断。
10. 把 `_schema.json` 改成非法 JSON → 四份脚本(`doc_check` / `devlog` / `plan` / `verify`)都给 `exit 2` + 一行说明(不是回溯)。
11. 把某条需求 `verify:` 指向的测试改成必然失败 → `python scripts/verify.py` 退出码 1;状态=`待实现` 的行跳过。
12. **改动分级不改变校验结果**:只改一段正文的轻档改动,`doc_check` 的 `errors/warnings` 与改前一致;在同一处制造断链、删掉条款的 `verify:` → `E7` / `E18` 照报;`SKILL.md` 硬规则里恰有一条这样的体量判据。
13. **交接锚点与计划表互校**:交接段首行写「下一步:T1.1.1」(计划表里有)→ `devlog.py check` 0 error;写一个不存在的编号 → `S9` 且 exit 1;首行没有锚点 → `S8`;计划表还有未完成任务却写「下一步:无」→ `S9`(「无」只对最新一篇判:更早的档案写下「无」后又被插任务,不追溯)。
14. **开场简报**:还没有任何档案时跑 `devlog.py brief` → 0 error 且提示「尚无会话档案」;建一档、把 §7 首行写成「下一步:T1.1.1」→ brief 复述该锚点并列出计划未完成任务与收件箱 `确立`/`实施中` 计数;计划全部完成时显示「未完成 0」;跑前跑后 `docs/` 字节不变(只读)。
15. **用户侧落点必填**:把 §2 一行的落点留空或写成 `—` / `待补` → `devlog.py check` 报 `S10` 且 exit 1;写成「§3.1」→ 0 error;刚建出的档案(§2 仍是模板占位)不报 `S10`。
16. **待分诊与开工门禁**:`devlog.py ask "要不要拆任务?" --if "计划里还是一个任务"` → `pending` 能看到 `Q1`;此时 `new` 退出码 1 并列出 `Q1`;`pending --clear Q1 --as drop --note "已过期"` 后 `new` 通过;延期 6 条时 `new` 仍拒绝;`brief` 首屏给「待分诊」计数;分诊过的 pending 文件保留(不静默删除)。
17. **跨项目找目录 + 时间线同步**:用开发副本的脚本在**另一个项目目录**跑 `devlog.py new` → 档案建在那个项目里,本仓库会话数不变(`find_docs` 先 cwd 后脚本目录,ISS-028);`new` 之后 `devlog.py check` 报 `S11`,跑 `devlog.py index` 之后消失(ISS-030)。
18. **转正一步 + 新增前查重**:`pending --clear Q1 --as iss` 不给 `--relation` → 先摆候选再 exit 2;`--relation new --type … --impact … --to …` → 自动分配下一个 `ISS-nnn` 并追加收件箱行;`--relation merge:ISS-nnn` → 不新增行、只标「合并入」;`devlog.py inbox --similar "…"` 能按字面找到候选。
19. **需求状态与出处**:需求行状态写成 `做完了` → `[E22]`;状态 `已实现` 但「依据」是 `—` → `[E23]`;改成 `已实现` + `ADR-001` → 0 error;骨架里 `待实现` + `—` 不报(E22/E23 只要求"声称实现了就指得出出处")。
20. **功能台账**:功能行状态写 `做完了` → `[E24]`;`满足的需求` 引用不存在的 `REQ-999` → `[E24]`;`已验收` 但代码入口写 `—` → `[E24]`;入口存在 + `verify` + 证据 → 0 error;骨架里 `待评审` 那一行不报。
21. **评审门**:功能行状态推到 `已评审` 但「评审」列是 `—` → `[E24]`;写上三问结论(满足✓ 可做✓ 代价S)→ 不报;历史行(`—(历史)`)带历史评审 → 不报;**挂需求的行拿 `—(历史)` 背书** → `[E24]`。

22. **功能对照的取数**:`devlog.py features` 列出功能台账各行(含 `--state` 筛选);筛到 `实施中` 时提示对照清单 `40-运行/功能对照.md`(`doc_init` 铺出来的实例);对照结论只有 `一致 / 差异 / 未覆盖`,写差异必须同时登记一条 ISS。
23. **对账**:需求没有任何功能覆盖 → `W8` 提醒(不阻断:需求可以先写);功能证据里写「第 99 组」而自测里没有 → `[E26]`;写真实组号 → 0 error。

24. **对齐门**:需求「已实现」但「确认」是 `—` → `[E23]`;写成 `复述✓ 2026-11-01|档案 012 §2` → 0 error;存量行 `—(历史)` 放行。
25. **考核门与回滚锚点**:`已验收` 的考核写「看着还行」→ `[E27]`;四格齐但缺「完成于」→ `[E27]`;四格 + commit 短号 → 0 error;`撤回` 是合法状态、入口可为空但要写考核。
26. **决策回顾的机器判**:最新一篇 §4 的用户决策块缺「依据」或「撤销条件」→ `devlog.py check` 报 `S12` 且 exit 1;补上是 0 error;写「拍板:agent 自选」可豁免;更早的档案不追溯。
27. **计划表被截断**:在 §5 任务表中间插一个空行 → `plan.py check` 报 `[P13]` 且 exit 1;接回同一张表 → 0 error;一行写成两行(断行)同样报。
28. **YAML 校验器随包走**:`SKILL.md` 的 plain 值含「: 」、引号未闭合,或 `.skill-metadata.yaml` 缩进坏掉 → `build.py` 体检与随包 `self_test.py` 都报;真实的两份文件通过。

29. **问题状态机**:性质 / 状态不在白名单 → `[D3]`;开放问题标 `实现关闭` → `[D5]`;`实施中` 缺关联任务 → `[D6]`;依据没有状态前缀 → `[D4]`;拒绝缺理由 / 重新考虑条件 → `[D7]`;闭环缺闭环日 → `[D8]`。
30. **产出对账**:最新一篇 §6「本次产出」里用反引号列了一个不存在的路径 → `devlog.py check` 出 `[W11]`(提醒,不阻断);路径都在 → 无 `[W11]`。

31. **任务双亲与考核下沉**:任务写不存在的 `F-999` → `[P14]`;未完成的任务写 `—(历史)` → `[P14]`;删掉功能台账 → `[P14]`(不能当成"没有功能"静默通过);`已完成` 但「任务考核」表里没有它、或四格 / 完成于缺项 → `[P15]`;任务考核表里有计划里没有的任务 → `[P15]`;功能 `已验收` 却没有任何任务挂它,或汇总点名了不挂本功能的任务 → `[P16]`;汇总不写「各任务考核见」→ `[E27]`。

32. **方向卡**:计划里有 `D1` 而卡里没有 → `[P18]`;卡的「现状 / 成功状态 / 走通验收 / 接缝」任一为空 → `[P18]` 指名那一格;走通验收缺 `@复核日` → `[P18]`;路径 / 接缝 / 走通验收里引用不存在的 `F-nnn` / `W<n.m>` / `K<n>` → `[P18]`(REQ-018 / ISS-061);卡里有 `D9` 而计划没有 → `[P18]` 孤儿方向;删掉方向卡 → 一条 `[P18]`(不逐行刷屏);骨架自带的示例行 → 0 error。

33. **设计卡**:工作停在「待开工」却没有卡 → `[P19]`;卡的「接口 / 可替换点 / 失败边界」任一为空或只写「无」→ `[P19]` 指名那一格;卡里写 `W9.9` 而计划 §4 没有 → `[P19]` 孤儿卡;一个工作两张卡 → `[P19]`;删掉设计卡 → 一条 `[P19]`(不逐行刷屏);已做完的工作不追溯;骨架自带的示例卡 → 0 error。

34. **计划树视图**:`plan.py tree` 列出 方向 / 工作 / 任务 三层,每行带功能、状态、完成于;`--html` 是**单文件**(不引外部资源、页面里写明「不要手改」、离线可看);`--json` 的 `tasks` 计数与计划表行数一致。

35. **表格竖线**:把 `| ID | 状态 |` 直接写进一格 → `[E28]` 并指出「第 N 行有 9 格、表头 7 格」;写成 `\| ID \| 状态 \|` → 0 error(切表与校验同口径);数据行以 `|` 开头却不以 `|` 结尾(表尾截断)→ `[E28]` 报「第 N 行表尾截断」,补上末尾竖线即消。

36. **摩擦留痕与转正列**:会话档案模板缺 `### 3.6 本轮摩擦` → 自测第 41 组失败;`pending --clear --as iss` 转正时 `--impact` 落进「影响(不处理会怎样)」列(不是「—」)→ 通过;落进别的列 → 失败。

37. **状态转写子命令**:`plan.py set-status <T-id> --to 已完成 --commit <短号> --review "做法=…|一致=…|代价=…|结论=…"` 一次写全计划 §5 的状态与 FEATURES 的考核行;任务号不存在 / 状态不在白名单 / 锚点写「待提交」/ 缺四格 → exit 1 且两个文件哈希不变;`--dry-run` 只打印清单;原样重跑 → 无改动、不新增任何文件。

38. **已验收 → 对照行**:FEATURES 里 `已验收` 且不在存量豁免清单(F-001–F-020)的功能,`40-运行/功能对照.md` 没有它的行 → `W9` 提醒(不阻断,exit 0);文案含「有行 ≠ 对照过」;补行或写明为什么不需要后消失;F-001–F-020 与「—(历史)」不报。

39. **设计卡选项空间**:待开工 / 进行中工作的设计卡缺「选项空间」表 / 少于 3 个方案 / 没有「不做 / 少做」/ 被否方案没有回到条件 → `W10` 提醒(不阻断,exit 0);合法卡不报;`W10` 只判形状,广度够不够仍人读。

40. **五件套批量入口**:`plan.py new-feature` 一次建 `REQ` / `F` / `W` / `T` / `K`;自动编号只认表格首列(正文写 `F-999` 反例不会把下一个推成 `F-1000`);功能行落在「任务考核」表之前;缺必填 / 撞号 / 分值越界 / 工作与方向不一致 → exit 1 且所有被写文件哈希不变(新工作 4 个 / 挂已有工作 3 个);`--dry-run` 零写入;`--work-id W1.1` 不新建卡。

41. **项目侧观测载体**:`doc_init` 铺出 `40-运行/可观测性.md`(四维 / 四问 / 系统级节);待开工 / 进行中的设计卡缺「观测四格」→ `W12`(exit 0);补齐 → 无;已完成卡缺格不报;重复 `doc_init` 不覆盖。

42. **自身参考实现**:`observe.py run` 包一条失败命令 → 记录含四问、退出码不变;`five-run` 一条 trace 5 个 span,且 span 顺序与收尾五连跑一致(`doc_check` 最后)、任一步失败即 exit 1;`show` / `status` 可回看;`trend` 跨 run 聚合(第 64 组);写失败只降级;无记录 `status --check` 报证据缺口且 exit 0;自测第 63 / 64 / 72 组。

43. **3.8 语法门**:随包 `scripts/*.py` 全部能被 Python 3.8 接受——`ast.parse(feature_version=(3, 8))` 拦语句级新语法,另扫 f-string 表达式里的反斜杠(PEP 701 只在 3.12 放开,3.12 的 `feature_version` 不拦);失败给 file:line;反例(`f"{re.sub(r'\d', '', x)}"`)判出、反证(正则挪出表达式)通过;自测第 65 组。

44. **问题链**:「落点」里的 `源自 ISS-nnn` / `须先 ISS-nnn` 由 `devlog.py check` 判——指向不存在或自指 → `D11`;`须先` 成环 → `D12`;被未关闭的 `须先` 挡住却写成「实施中」/「实现关闭」→ `D13`(根因未关,表象只停在「确立」);`源自` 时间倒挂 → `D14`;`须先` 已闭环 → `W13` 提醒可推进;旧行不写标记不判。自测第 66 组。

45. **真机验收台账**:`doc_init` 铺出台账且示例行首跑 0 error;`rv new` 自动分配下一个编号;同一场景记两条只算 1 个场景;到门槛只提示「建议拍板」、不自动改状态;`rv add` 缺参 → exit 1 且零写入;判据格式坏 / 状态词非法 / 已定论无合法出口 / 记录指向不存在 / 回看日坏 各报 `V2` / `V3` / `V4` / `V5` / `V6`;不进开场简报(自测第 69 组)。

46. **定期减法**:`doc_init` 铺出的档案模板含 §3.10;空项目 `brief` 报「距上次 0 场 / 4」不提示到点;建满 4 场后报「距上次 4 场」并提示「到点了」;只写表头与空占位行不算做过;填一行结论后复位为 0 场;`--json` 带 `prune.since / every / due`(自测第 70 组)。
47. **运行记录引用**:最新一篇 §6 引用存在的 `run id` → 0 error;引用不存在的 → `S15`;没写 → `W14` 提醒(不阻断);写「无(分开跑)」不提醒;更早的档案不追溯(自测第 73 组)。

`scripts/self_test.py` 把上面 1–44 跑成断言;改任何脚本或文档后先跑它,再跑 `build.py`。
Files in this package (14)
  • .gitattributes 1 KB
  • .gitignore 1 KB
  • .skill-metadata.yaml 5 KB
  • AGENTS.md 6 KB
  • CHANGELOG.md 100 KB
  • CONTRIBUTING.md 8 KB
  • LICENSE 1 KB
  • README.en.md 12 KB
  • README.md 10 KB
  • SKILL.md 76 KB
  • VERSION 1 KB
  • build.py 23 KB
  • install-targets.json 1 KB
  • install.py 12 KB

Versions

The database has no other skills named doc-driven-development.

Database snapshot: 13.11.2026 · package version d6bdf841a72f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95development-workflow
    Spec-driven development lifecycle — EARS requirements, technical design docs, implementation tracking, and contribution guidelines. Use when planning features, defining requirements, or managing project lifecycle.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.