doc-framework：面向文档开发体系

把一套在真实全栈项目中验证过的「契约文档 + 测试文档 + 实施计划」开发方法——面向文档开发（Document-Oriented Development）——抽象为可跨项目复用的方法论资产：文档模板 + 六个 skill + 安装工具。

AI 深度参与开发的全栈项目越多，这套体系越值钱——它给 AI 定"规矩"：文档永远反映真实代码，代码永远长在既有架构上。 支持多应用工作区：一个项目可登记 N 个前端应用 + N 个后端服务（不同技术栈），档案「应用清单」统一路由，契约保持业务语义唯一真相，应用只是落点。

设计取向：skill 不焊死任何技术栈（项目特定约定全在「项目档案」，换技术栈只换档案）· 契约 = 当前代码的语义映射，是业务的唯一语义真相 · 上下文从体系中来（档案 → 总契约 → 标杆 → 边界），用户只给业务需求。

从这里开始（按你的角色）

我是谁	先读什么	为什么
第一次用	安装 → 接入初始化	装好并对 AI 说"初始化项目"
已经接入，想知道怎么干活	术语表 → 六个技能 → 日常开发流程	先认词，再看技能分工与流程图
只想改个小东西	小改动通道	三条通道判据 + 直改通道，多数小改免建计划
遇到问题	常见问题 FAQ → 升级	安装 / 同步 / 命令用途
要改这套框架本身	docs/设计文档.md → 参与开发	架构、契约模型规格、各层实现、同步 checklist

本文件是使用者文档：只讲"怎么用、为什么这样设计"到必要为止。规则清单、参数全集、实现细节一律不在本文件复述（会随实现漂移）——各自有唯一归属：命令参数见 doc-framework --help；check 判据见设计文档 §6.3；升级机制见设计文档 §9.3，迁移动作见老项目升级上下文。

术语表（契约模型）

一句话模型：契约 = 当前代码的语义映射（应然 ≡ 实然，永不领先代码）；语义变更 = 计划的「语义增量」，批准后被授权、实施后由合并增量落账。

术语	定义
待实现模块	代码库中尚无任何实现的模块（无目录 / 无路由 / 无表 / 无接口 / 无契约）。只要有任何一处实现，它就不是待实现模块。英文同义词 greenfield。
首次建模计划	待实现模块的计划：必须 完整 形态、含全量「语义增量」（几乎全是 ADDED）与「建模补充」节。
存量模块（已建档）	有实现 + 有契约：改动走"计划增量 → 合并增量的 update 落账"。
存量模块（未建档）	有实现 + 无契约（接入体系时已有代码）：走 /module-doc 代码对账补建（不走计划）。
语义增量	计划里的 Delta 节：ADDED / MODIFIED / REMOVED 三张固定列表 + 主计划 列，是待生效语义与 /module-code 的实施约束；批准 = 语义定稿。
合并状态（三值）	待合并 / 已合并（可带日期，如 已合并（2026-01-02））/ 无需合并；三值外的旧写法不再识别（命名只中文，见文档体系）；无需合并 用于空增量（纯实现改动）或已废弃计划。
合并增量	/module-doc 的合并处理：update = 存量模块按增量落账，create = 待实现模块首次建档 + 回写总契约。

最容易混的一处：存量模块未建档 ≠ 待实现模块——只要有一行代码 / 一张表 / 一个接口，它就是存量模块，走代码对账补建；待实现模块是"计划时刻"的状态，实施一落代码就转成存量模块。三态的判定与路径全表见设计文档 §3.1。

契约不是百科：五层文档 + 非文档出口

契约只写“当前必须成立什么”，不写“怎么实现、什么时候改过、各端怎么接”。 这是 v4 文档结构（本次发布版本 4.0.0，tag v4.0.0）的核心口径。

层	文档	只回答
L0 索引	总契约.md、项目档案.md、§7 能力契约索引	有哪些模块/能力、谁依赖谁、谁拥有哪个能力
L1 能力契约	边界/{能力}边界.md	跨应用能力的语义、协议、失败模式、消费者、验收
L2 模块契约	模块/{模块名}/契约.md	本模块的不变量、状态机、权限、接口对状态的影响、落点、模块验收
L3 接口契约	模块/{模块名}/接口.md、接口规范.md	字段名/类型/必填/示例/错误码/分页
L4 应用规范	规范/应用-*.md、主题分册	本端技术栈机制、目录、构建、路由、配置读取点

历史与决策不是文档层：变更史归 git，决策与被否方案归 探索/，计划只是执行快照；任何文档都不承载变更记录。测试/验收.md 是验收场景（SC）的唯一事实源，由 /module-doc 维护；测试/方案.md、测试/{主题}_测试.md、测试/test.sh 由 /module-test 维护，不新增语义。

契约头部必须声明所有权：本契约拥有 / 委托给 / 本契约不拥有。跨应用能力由 边界/ 接管后，模块契约删除正文、只留回链（移动而非复制）；§7 只写 INV-{模块名}-NN（TRAP 已退场）；契约 §8 只留指针，SC-{模块名}-NN 与正文在 测试/验收.md 且 1:1。

六个技能的使用方式

六个 skill 用 /命令 显式触发（防误触发，不用自然语言关键词），DSH 只识别英文技能名。核心分工一句话：探索归 /module-explore、文档归 /module-doc、计划归 /module-plan、代码归 /module-code、测试归 /module-test、检查归 /module-review——各司其职，谁都不越界。记忆点：探路、写文档、写计划、写代码、写测试、收尾检查。各技能的职责边界全表见设计文档 §4.1，细节详见各 SKILL.md。

技能速览

0. /module-explore —— 探索与讨论（可选前置）：需求模糊、方案取舍、不熟代码库、范围存疑时先做一次零承诺对话（调研代码、比较方案、把问题问清楚）。产出默认不落盘（决策留在对话里），待实现模块场景强制落盘；硬护栏：不写代码 / 契约 / 计划，只谈要不要做、放哪、走哪条路、范围，不设计字段接口。

1. /module-doc —— 模块文档（契约 / 接口）：核心文档聚合在 模块/{模块名}/ 下——契约.md（语义约束）、接口.md（字段级服务端真相，唯一事实源）。按真相来源自动分三种处理方式（合并增量 / 代码对账 / 产物补齐），由 AI 探测、确认门带编号可强制切换。核心纪律：契约永不领先代码——语义变更写进计划的「语义增量」节，实施后由合并增量落账。路由要点与三种方式的真值来源见设计文档 §4.2。

2/3. /module-plan 与 /module-code —— 计划与代码：/module-plan 建计划（待审核）→ /module-code 执行（调用即批准：计划还是「待审核」时自动登记「已批准」后实施；逐项勾选任务）→ 登记「已完成」→ 归档。并非所有改动都值得一套完整计划——/module-code 按判据自动分三通道，见小改动通道；状态机与归档规则见计划 30 秒。

4. /module-review —— 模块审查：读档案（注入技术栈特有检查项）→ 总契约 → 核心文档（契约 / 接口）→ 对照代码逐项检查；输出分级问题清单 CRITICAL / HIGH / MEDIUM / LOW + 回写查账（跑 check 看「文档落后检查」有无未回写提示、§9 生产 SQL 登记、接口.md 与代码一致性、总契约索引）；CRITICAL 与 HIGH 清零才提示可提交。

5. /module-test —— 模块测试（可选）：测试 = 契约的映射。/module-test {模块名} 生成 测试/方案.md、测试/{主题}_测试.md、测试/test.sh；/module-test 测试/{主题}_测试.md 直接执行该主题；/module-test 测试/方案.md 全量执行；报告写 测试/报告/。白盒断言写入 测试/方案.md，不生成独立脚本。只有 _测试.md 是可执行测试文档。

触发说明：DSH 只认 /技能名 显式触发（小写字母 / 数字 / 连字符）；其他 agent 按其自身触发约定使用。

计划：30 秒说明

计划是当时的最新方案快照（人读层 §1 讲清"需求 / 实施后结果 / 思路"），契约才是长期真相。一次需求一份计划，从「待审核」走到「已完成 / 已废弃」即可归档；归档时校验 合并状态=已合并 且契约已承接 → 移入 计划/归档/（归档不删文件——清理由人手动决定；长期追溯靠 git 提交信息的 trailer（计划:{计划标识}），不依赖计划文件存活）。计划不记修订史与决策史：正文始终只有最新方案（就地改写），被否理由归探索记录、历史归 git。

状态：待审核 → 已批准 → 实施中 → 已完成，另有 修订中（改计划必经）与 已废弃。「已批准」有两个入口：用户确认，或 /module-code 的调用即批准（显式调用执行「待审核」计划时，它先登记「已批准」再实施——「修订中 / 已废弃 / 已完成」不在此列）。状态机图与两类计划的落盘位置见设计文档 §3.6。

语义增量是语义变更的唯一载体（ADDED / MODIFIED / REMOVED 三表 + 合并状态，批准计划 = 语义定稿）；合并状态的三个取值与定义见术语表，其组合后果（已完成 + 待合并 → check 硬报错且拒绝归档等）见设计文档 §3.4 不变量 I2/I4。

三条纪律：① 任务只勾事实完成的项，未勾完不得登记「已完成」——但勾选框只留给 AI 能自己干完并验证的事，人工/平台侧步骤写成 - 【人工·…】…（不带勾选框，只显示、不阻塞「已完成」）；② 实施完成 ≠ 可以归档——归档是 /module-plan {模块名} 归档 的独立动作，时机由人定（可能还要等生产 SQL 执行、等验收）；③ 跨模块计划放全局 计划/，只能用 {计划路径} 直达。

常见误解：计划确认后不会自动实施（必须显式 /module-code——而显式执行「待审核」计划就是批准，不必先手动改状态）· 已批准计划不能直接改 · 任务不能最后一起勾 · 人工/平台侧步骤根本不打勾（写成无框的登记行）· 「已完成」的计划不能追加任务 · 小改不一定建计划（见下节）。

完整规则（11 条常见误解等）见设计文档 §3.7。

小改动通道：直改与轻量计划

设计原则：授权粒度 ∝ 爆炸半径。三条底线不可让渡——AI 不能自我授权（必须有一次人的确认）、不能改到范围外的应用、事后可追溯。

/module-code 按三通道判据自动分派（先命中先定：触契约语义 / 含 SQL → 完整计划；跨应用 → 轻量计划；单应用 + ≤5 文件 + 无决策 → 直改通道免计划）——判据表与判据 1 的客观形式（"能不能在契约里找到对应条目"）唯一权威源是 skills/module-code/SKILL.md §0.1，本文不复述。直改通道的编号确认门、边界来源（契约 §5 应用落点）、硬禁用清单与留痕见设计文档 §3.5；改完跑 doc-framework diff-check --module {模块名} 对账。途中发现要动契约语义 → 立即停，升级完整计划（已改部分如实汇报）。

轻量计划：保留 §1 需求与思路（压缩版：四小节各一句，图按需）/ 逐应用表态 / 变更文件清单 / 任务清单 四节，头部标 > 计划形态：轻量，不含「语义增量」节（发现触语义 → 升级完整计划）。批准的对象是作用域（表态 + 清单）：扩作用域 = 扩权，必须退回「修订中」重新批准；作用域内追加任务项属记账，可直接更新——一份轻量计划能承接同范围的多轮小改，配合 list --stale {N} 与 /module-plan {模块名} 归档，归档从"每改一次"降为"每迭代一次"。

成本对比（5 步 → 1 命令 + 1 次确认）与防滥用设计见设计文档 §3.5、§3.8。

安装

前提：Node >= 22 + git；CLI 没有运行时依赖。分发物是 GitHub 仓库的 tag，没有发布到 npm——不要裸跑 npx doc-framework，项目没装依赖时它会去 npm registry 找同名包。

唯一安装入口：GitHub tag + 显式 install

一个 install 入口，两种取包方式，安装行为完全一致。

A. 已有 package.json（推荐：CLI 留在项目里，check / diff-check 可进 CI）

{
  "devDependencies": {
    "doc-framework": "github:knight-peter/doc-framework#<tag>"
  }
}

npm install               # 或 pnpm install
npx doc-framework install # pnpm 项目：pnpm exec doc-framework install

git 依赖的版本由 tag 钉住、随 lockfile 固定；不会因为装依赖自动铺 skill。<tag> 用下方 B 节的 ls-remote 命令取最新。

B. 没有 package.json（一次性取包，不落依赖）

npx --yes "github:knight-peter/doc-framework#<tag>" install

后续 check / sync / doctor 用同一条前缀。<tag> 用下面的命令取最新（本文不写死版本号）：

git ls-remote --tags --refs https://github.com/knight-peter/doc-framework.git 'v*' \
  | sed 's|.*refs/tags/||' | sort -V | tail -1

钉 tag 可复现；不写 #tag 会取默认分支最新提交（不推荐用于 CI）。

install 做四件事：

1. 把 skills/* 拷到项目级 skill 目录（默认 .agents/skills/，可经 doc-framework.config.json 配置）；
2. 写版本标记 .doc-framework.json（逐文件 sha256 + per-skill 版本）；
3. 未初始化项目：预置 doc-framework/ 骨架目录（模块/、边界/、规范/、计划/、探索/ + 引导 README）；
4. 未初始化项目：生成项目根《接入指南.md》并写入 AGENTS.md 接入引导段（已初始化项目自动跳过）。

为什么是显式命令：安装不依赖 postinstall / 生命周期脚本，避免 pnpm v10、store 复用与 INIT_CWD 带来的目录歧义。升级时改 tag → install（强制刷新）或 sync（安全跳过定制），两者都不动文档。

接入初始化（一次性）

安装后项目根出现《接入指南.md》。对 AI 说 "初始化项目"（或 AI 按 AGENTS.md 引导主动提示）：

• 既有代码库：AI 扫描代码 → 生成档案草案（逐项标注证据来源与置信度）→ 开发者确认 → 提炼第一份契约（标杆）→ 生成文档骨架；
• 全新项目：AI 提问（技术栈 / 约定 / 业务域）→ 生成档案 + 骨架。

渲染纪律：所有骨架文档一律从官方模板渲染生成（模板位置见《接入指南.md》「模板来源」），禁止凭空自创结构；{占位符} 必须全部替换为项目实际值，完成后运行 doc-framework check 自检（有依赖用 npx doc-framework check；无依赖用上面的 npx --yes "github:...#tag" check）。

初始化完成后 AI 自动清理一次性引导：移除 AGENTS.md 接入引导段、删除《接入指南.md》与 doc-framework/README.md（骨架引导）。

日常开发流程

flowchart TB
    H["新需求 / 小改（只给业务描述）"] --> I["自动发现：档案应用清单 → 总契约 → 标杆 → 边界"]
    I --> E{"不确定？"}
    E -->|"是（返工要动契约/计划/多模块）"| EX["/module-explore：零承诺探索（待实现模块强制落盘）"]
    E -->|"否"| CH{"通道判据（触语义？含 SQL？跨应用？）"}
    EX --> CH
    CH -->|"触语义 / 含 SQL"| J["/module-plan：完整计划——语义写进「语义增量」节（待实现模块 = 首次建模计划）"]
    CH -->|"跨应用，不触语义"| LIGHT["/module-plan：轻量计划（§1 需求与思路 + 表态 + 清单 + 任务；不含增量）"]
    CH -->|"单应用，不触语义"| DIRECT["/module-code：直改通道（编号确认，边界=契约 §5 落点）"]
    J --> APPR{"批准（批准 = 语义定稿 + 授权作用域）"}
    LIGHT --> APPR
    APPR -->|"用户确认，或直接 /module-code（调用即批准）"| T["/module-code：按增量 + 契约不变量实施（SQL → 主责服务 → 下游/聚合 → 逐端）"]
    DIRECT --> T
    T --> U["一致性自检 + diff-check（计划白名单 / --module 契约落点）"]
    U --> V{"计划通道？"}
    V -->|"否（直改，无语义变更）"| W["提交信息 trailer 留痕（模块: + 计划:无 + 契约:无需变更）"]
    V -->|"是"| M2["/module-doc 合并增量：按增量合并进契约 + 接口.md（合并前以代码校正）→ 翻「合并状态=已合并」"]
    M2 --> M3{"首次建模计划？"}
    M3 -->|"是（待实现模块）"| M4["合并增量的 create：契约全章 + 接口.md + 回写总契约"]
    M3 -->|"否（存量模块）"| M5["合并增量的 update 分支：更新契约 §3/§4/§5/§8 + 接口.md"]
    M4 --> X
    M5 --> X
    W --> X
    X["/module-review：分级清单 + 多应用对账 + 完成度 + 增量合并完整性 + 通道合规"]
    X --> Y{"CRITICAL/HIGH 清零？"}
    Y -->|"否"| T
    Y -->|"是"| Z["测试：接口/库/端/编排 四层"]
    Z --> AA{"发现问题？"}
    AA -->|"代码 Bug"| T
    AA -->|"语义缺口 / 计划外漂移"| AB["回 /module-plan 修订：语义补进「语义增量」节 → 重新批准；若代码是既成事实 → /module-doc 代码对账补登"]
    AB --> T
    AA -->|"无"| AC["完成：提交信息带 trailer + 计划标「已完成」"]
    AC --> AR["/module-plan 归档（校验 合并状态=已合并 → 移入 计划/归档/）"]

Loading

异常分支：计划处于「修订中 / 已废弃」时 /module-code 拒绝执行，退回 /module-plan 处理（「待审核」不再是拒绝理由——显式调用即批准）；直改途中发现语义变更 → 立即停，升级完整计划、计划通道重做（已改部分如实汇报）。

文档体系（初始化后生成）

doc-framework/
├── 项目档案.md          ← 唯一需人工确认的文件（应用清单 = skill 路由表；通用约定全局段+应用覆盖）
├── 总契约.md            ← 总索引：业务域、应用拓扑、模块索引表（索引+依赖单表）、依赖全景图、跨模块业务流程、§7 能力契约索引
├── 测试规范.md          ← 通用测试方法论（接口层/库层/端层/编排层 四层验证、缺陷闭环）
├── 接口规范.md          ← 全局接口约定（REST/认证/统一响应外层与错误码/分页/接口层字段语义；兼容性红线在计划模板 §6「接口兼容性声明」）
├── 规范/                ← 三层 + 分册：类型-前端、类型-后端（类型层共性）+ 应用-{应用标识}（每应用一份差异 = 索引）+ {应用标识}-{主题}（深度技术主题分册，按需）
├── 边界/                ← 能力契约：跨模块/跨服务/跨应用共享能力（工作流/附件/权限/服务间调用/事件与MQ/鉴权网关/平台接入等；§5 失败模式、§6 验收、§7 关联代码）
├── 计划/                ← 跨模块实施计划；归档/ 为已归档计划（不自动删除）
├── 探索/                ← 探索记录（/module-explore 落盘的单次决策记录；根目录 = 探索中 + 已定案待吸收，归档/ = 已使用 + 已作废）
└── 模块/{模块名}/       ← 模块聚合资产（业务语义唯一真相，应用只是落点）
    ├── 契约.md          ← 语义约束（所有权声明 + §5 应用落点 + §7 INV + §8 指针（SC 在 `测试/验收.md`）+ §9 生产 SQL——**历史归 git，本文件只记当前真相**）
    ├── 接口.md          ← 字段级服务端真相（唯一事实源）：服务归属/类型/消费方 + 各应用接入状态
    ├── 测试/
    │   ├── 验收.md      ← SC 唯一事实源（/module-doc）
    │   ├── 方案.md      ← 测试方案 + 主题索引（/module-test）
    │   ├── {主题}_测试.md ← 可执行测试文档（/module-test）
    │   ├── test.sh      ← 多服务 BASE_URL 参数化（可选）
    │   └── 报告/        ← 每次执行报告（不参与文档内容校验，只校验文件名）
    └── 计划/            ← 单模块实施计划（YYYY-MM-DD-{主题}.md：形态=完整/轻量）；归档/ 为已归档计划

上面这棵树即完整的路径清单——不另设"产物命名表"（同一批路径写两处必然漂移，与体系自己的"规则归属单一职责"纪律冲突）。

产物命名只有一套：中文：文档根固定 doc-framework/，目录 / 文件 / 章节 / 头部字段 / 枚举值一律中文；英文只影响文档内容，不影响命名。命名清单的运行时权威是 plan.js 的 NAMES.zh；路径以本树为准，设计文档 §8.1 只做指向（决策与理由见 §8.3）。

升级

1. 有 package.json：把 git 依赖的 tag 改成新 tag → npm install（或 pnpm install）→ npx doc-framework sync（安全）或 install（强制刷新 skill）。
2. 无 package.json：npx --yes "github:knight-peter/doc-framework#<新 tag>" sync（或 install）。
3. 跑 npx doc-framework doctor 看安装 / AGENTS / 旧结构提示，再跑 check；升级后重开一个会话。

三条边界：

• 只动 skill 文件：install / sync 绝不改写你的 doc-framework/ 文档根与 AGENTS.md（除首次安装写入引导段）；
• 本地定制过的 skill 自动跳过（marker + 逐文件 sha256 比对）；
• templates 升级只影响新项目初始化：已初始化项目的档案与契约永不回灌。

升级是单向的：体系不兼容旧文档结构。迁移动作（P0–P3 批次）见 docs/老项目升级上下文.md；升级机制见设计文档 §9.3。没有「留在旧结构也能用」这条路。

常见问题（FAQ）

下文的 npx doc-framework <命令> 指项目里已装 git 依赖（走 node_modules/.bin）；没有 package.json 的项目，把前缀换成 npx --yes "github:knight-peter/doc-framework#<tag>"。

Q1：doc-framework install 跑完了，但 .agents/skills 里没有 skill？

先看 install 的输出方向（默认 .agents/skills/；若项目已有 .claude/skills / .cursor/skills 会优先用它，也可在 doc-framework.config.json 的 targetDirs 指定）。再确认没有把 install 跑在子目录——用 --root <项目根> 显式指定；装依赖不会自动铺 skill，必须显式跑 install。

Q2：要不要钉版本？

建议在 CI / 多人项目钉住 tag："doc-framework": "github:knight-peter/doc-framework#<tag>"，或一次性安装时用 npx --yes "github:knight-peter/doc-framework#<tag>" install。不写 #tag（或写 #main）会取默认分支最新提交，行为可能随提交变化。

Q3：doc-framework sync 提示"跳过（本地已定制）"？

这是防漂移设计：版本标记 .doc-framework.json 按相对路径（如 module-code/SKILL.md）逐文件记录 sha256，判定粒度是单个 skill——该 skill 下任一文件与官方版本不一致，整个 skill 就被视为本地定制、跳过不覆盖；其它 skill 照常升级。

被跳过的 skill 会保留自己的旧版本号（记录在 marker 的 skills[名称].version），所以下次 sync 仍会继续尝试它，不会因为"其它 skill 已是最新"而永久搁浅。

sync 还会保护没有 marker 的同名 skill 目录（无法区分官方文件与用户文件时宁可跳过；强制刷新用 install）。

放弃定制恢复官方版本：跑 npx doc-framework install（install 语义是无条件先删后拷）。注意 sync 不会修复被删掉的定制文件（删文件会被视为定制差异），所以**"删掉某个文件再跑 sync"找不回来**。

Q4：安装失败残留了部分 skill 目录？

安装中途失败会留下不完整目录且没有版本标记。重跑 npx doc-framework install 会先删后拷自动覆盖，无需手动清理。

Q5：升级会覆盖项目里的文档吗？

不会——升级只换 skill 文件，templates 的改动只影响新项目初始化（见升级）。

命令速查

命令	用途	关键点
install	首次安装 / 强制刷新 skill	未初始化项目同时铺骨架、接入指南与 AGENTS 引导段
sync	安全升级 skill	按单个 skill 比对 marker，本地定制跳过；目标目录缺失退出码 1
check	文档体系审计	退出码 0/1；ℹ️ 不影响退出码；--strict 把提示项升为 ⚠️；--json 输出 DF-*；--rules 打印规则目录；2026-10 起含契约内容健康（历史/§7/SC/所有权）
audit	契约健康/边界/净增长报告	只读；--module <名> 单模块、--all 全仓、--json 机器可读、--plan <计划> 按计划归因净增长；不替代 check
migrate v4|v5	v4/v5 迁移动作清单	只读；--dry-run/--json；不自动改写契约（规则归类/SC 迁移需语义判断）
diff-check	提交前 / CI 对账	计划路径按白名单；--module 按契约 §5 落点推导应用级白名单
list / show	只读查询	在途计划、探索记录、任务进度；list --stale N 是批量归档入口
doctor	安装 / 升级健康检查	只读；查 marker、AGENTS 永久段、旧哨兵、旧 schema2 契约 §9 变更表、旧归档目录
template	打印官方模板	未装依赖也可用；模板来源见《接入指南》

参数全集以 doc-framework --help 为唯一权威；check 判据见设计文档 §6.3，diff-check 管辖范围见 §6.4，list / show 输出契约见 §6.5。

使用纪律

1. 语义先于代码、记录后于代码：语义变更（字段 / 接口 / 状态机 / 权限标识 / 应用落点）先在计划的「语义增量」节定稿，代码照增量实现；实施后由 /module-doc 合并进契约与 接口.md——契约永不领先代码。"代码在前"的例外（既有代码无契约 / 待实现模块）见术语表与日常开发流程；
2. 测试→契约回写闭环：发现问题先定性"代码 Bug vs 契约缺口"，涉及约定变化必回写契约；
3. 契约只记当前真相，历史归 git：查历史用 git log -- <模块代码路径>（提交信息带 模块: / 计划: / 契约: trailer）；不把变更记录写进任何文档；
4. 计划是事实登记：任务只勾事实完成的项，未勾完不得登记「已完成」；勾选框 ⇔ AI 可执行任务，人工步骤是无框的登记行（只显示、不阻塞，由 list / show 露出）；归档前校验 合并状态=已合并（见计划 30 秒）；
5. 通道可以降级，边界与留痕不能：小改免计划必须过编号确认（AI 不得自我授权），改完跑 diff-check --module 并在提交信息写 契约:无需变更——省的是仪式，不是纪律。

参与开发

改这套框架本身（templates/ skills/ scripts/）请先读 docs/设计文档.md：总体架构、契约模型规格、各层实现、同步 checklist（§11.2）都在那里。改动后跑回归：

npm run lint                          # 零依赖语法/架构守卫（含单安装入口检查）
npm test                              # node:test 单测（解析器 / env / installer）
bash scripts/selftest.sh              # 端到端回归（需 node；可用 NODE_BIN=/path/to/node 指定）

分发 = git tag：改完版本号后 git tag vX.Y.Z && git push origin vX.Y.Z 即可；GitHub Release 由 tag 流水线生成。不发布 npm（package.json 保持 private: true，lint 会检查 release workflow 不出现 npm publish）。

License

MIT