new-project-init

---
name: new-project-init
description: 已有项目文档/规范需要优化完善（存量完善）、中途加入已有项目补建文档体系、或新项目开工前初始化文档体系并固化 AI 协作工作流时使用
whenToUse: 用户提到「完善/优化项目文档」「补建文档体系」「初始化项目」「固化 AI 协作工作流」「new-project-init 迭代」等字眼，或任务明显匹配 description 时加载
---

# Skill: new-project-init（项目文档体系初始化）

## Skill 简介与致谢

**这是什么**：一个「项目文档体系初始化」skill——通过**提问驱动**把项目规划落实为一组特化规范文件（CLAUDE.md / memory 记忆库 / docs 文档 / specs 模块流程 / .gitignore 等），并固化「AI 分角色协作开发」工作流。覆盖**三种适用场景**（**以存量完善为核心**）：已有文档想完善规范 / 中途加入已有项目补建体系 / 新项目开工前。

**核心原则**：提问驱动落实（问透再写）· 先设计后动手 · 三种场景三分支（存量完善/中途/全新）· 双受众三因素 · on/off 开关 · 唯一出处 · 讨论驱动迭代 · 记忆库写入纪律 · 文档维护规则（变更记录必填）。

**迭代路径**：本 skill 在日常使用中持续迭代（用中学、学中改）。请求迭代 → 对 agent 说「用 new-project-init 迭代」；迭代纪律见下方「skill 迭代大前提」；版本演进见文末「版本与变更记录」（完整历史见 `docs/CREATION-LOG.md`）。

**致谢**：本 skill v9.0 起的设计方法论受 [obra/superpowers](https://github.com/obra/superpowers)（英文原版）与 [jnMetaCode/superpowers-zh](https://github.com/jnMetaCode/superpowers-zh)（中文增强版）启发——技能编写（触发条件式描述、形式匹配失败类型、合理化借口表、TDD 式技能开发）、流程设计（完成前验证、验证条件具体化、集成选项交给用户）等。模板体系与问询流程为本 skill 在 PTB-IMP 项目实战沉淀的原创内容，特此致谢并注明来源。

## 调用前介绍（agent 调用本 skill 时，先把这段讲给用户听）

> 本 skill 帮你把项目**文档体系 + AI 协作工作流**建起来。开始前先花一分钟了解你会经历什么：

- **我是干什么的**：项目工程化教练——通过提问把你的规划问出来，落成一组规范文件（CLAUDE.md / 记忆库 / docs 文档 / 模块流程模板等），并固化「AI 分角色协作开发」的工作流。
- **你会经历什么**：① 我先做能力摸底（几个概念铺垫，不熟也没关系，我会解释）② 按你的项目情况走几轮问询（技术栈/团队/记忆/git/编码/文档等，每轮 3-5 题，答不上来我给推荐默认）③ 我按答案生成文件，**每份你确认后再做下一份** ④ 全部完成我给你「接下来怎么用」的指引。
- **产出什么**：CLAUDE.md（项目规范）、memory 三件套（AI 记忆库）、docs 文档（按需）、specs 模块流程框架、.gitignore 等。
- **需要你什么**：如实回答问题（答不上来就说，我给默认）；**说「可以修改」我才动文件**——讨论和修改是分开的两步。
- **适合谁**：已有文档但想**完善规范 + 固化 AI 工作流**（存量完善，核心场景）/ 中途加入已有项目补建体系 / 新项目开工前（三类场景都支持，见执行流程）。
- **注意**：问询会比较多（最多 11 轮全新 / 7 轮中途），是为了挖全你的规划；不想答的轮次可以跳过用默认。

## 设计思想速览（全版本，使用者先读，防「看不懂规范」）

> 🧑💻 **作者**：warm-flame-core（[github.com/warm-flame-core](https://github.com/warm-flame-core) · [gitee.com/warm-flame-core](https://gitee.com/warm-flame-core)）——本 skill 在 PTB-IMP 项目实战中迭代沉淀，v10.1 起可对外分享（MIT 协议，见根目录 README.md）。
> 本 skill 经过多轮迭代沉淀了一套**设计思想与规范**——它们解决的是「项目跑一段时间后文档/流程开始乱」「AI 协作容易跑偏」的问题。开始用之前花两分钟理解下面的概念，之后看模板/产出物就不会困惑。**分两部分：历史核心设计思想（v1-v9 沉淀）+ v10.0 新增。**

### 一、历史核心设计思想（v1-v9 沉淀）

1. **提问驱动落实（核心机制）**：每个规范文件不是照模板硬套，而是**先问你对项目的规划**（技术栈/团队/记忆/git/编码/文档…），按你的答案特化生成。答不上来的给推荐默认（标注「可改」）。「问不透不写」——没问清楚前不动文件。
2. **三种场景三分支**：存量完善（4 轮 + 限制规则，**核心场景**）/ 中途加入（7 轮）/ 全新项目（11 轮问询）。存量完善核心是**谨慎**：进度以你口述为准（R1）、在途模块隔离不改（R2）、范围逐项确认（R5）、只记录不重构（R6）。
3. **三层推进结构 + 颗粒度递进**：大设计先定稿（设计文档）→ 再拆模块（推进清单）→ 最后逐模块五件套（plan/acceptance + 开发 + 验收）。上层未定稿不进入下层，防「颗粒度跳级导致返工」。
4. **闭环工作流（Vibe Coding）**：一个模块走「Planner 规划 → Developer 编码 → Reviewer 独立审查 → Tester 测试验收 → 收尾回看」固定闭环，每阶段有签署责任（谁产出谁签署，禁代签）——防「开发完就完事、没人验收」。
5. **双受众三因素（CLAUDE.md 等规范文件的取舍）**：一份文档要同时服务「人」和「AI」——人+AI 高频内容 = 详细但精炼（表格化）；仅 AI 操作 = 简洁速查清单；低频长流程 = 只留一行引用（详情在对应文件，防 AI 每次白吃 token）。
6. **on/off 开关**：新功能默认做开关或进问询——按项目实际决定生成/跳过（如无 API 不开状态码节、无工具链不开静态检查节），简单项目可关掉不需要的规范，不强制全量。
7. **记忆库纪律（AI 协作的「记忆」）**：记忆库三件套（project-context / file-index / agent-activity-log）+ logs 细档记录项目「状态/文件/进度」；**触发即写、动作即写、末尾自检、入场必读**——防 AI「失忆」和「臆测」。**借口自查表**配纪律防「明知故犯」。
8. **文档维护规则（三要素 + 增量标注）**：所有正式文档改后必填「内容实时更新 + 变更记录行 + 署名」三要素；修改已有文档时变更记录行内标注性质（新增/修改/删除/去重）；头部维护声明让 agent 打开即见。
9. **模块五件套 + 签署责任矩阵**：每模块产 plan / acceptance / changelog / review-report / test-report 五份文档，各角色签署自己的区（acceptance 只有 Tester 签、plan 由用户审批）——防代签漏签、让「谁负责什么」可追查。

### 二、v10.0 新增设计思想

10. **信息闭环图（CLAUDE.md A 区新增）**：项目里很多信息**多处出现**（如「模块状态」同时出现在任务清单、README、DOCUMENT-INDEX、记忆库…）。以前只靠 agents 按唯一出处引用，**人打开文档找不到权威位置**。v10.0 在规范宪法（CLAUDE.md）里画一张「信息闭环图」：每条多处信息标出 **唯一出处 → 引用方 → 同步方向**，**人也能看懂、好找信息**。图上**虚线节点 = 按你问询答案决定生成的可选文档**（你没选的文档不画）——问询时不想生成某些文档没关系，闭环图会按你的答案裁剪。
11. **三类产出模式（templates/ 按模式分目录）**：skill 用完之后产出的文件分三类——**只创建一次**的（CLAUDE.md、docs 文档，特化即正式文件，要写清下次怎么改）、**多次创建但不含文件夹**的（每天日志、交接文档，复制单个模板文件新建）、**多次创建且含文件夹**的（specs 五件套，复制整个特化模板文件夹新建）。模板目录按这三类分子目录（`templates/一次性/`、`多次-单文件/`、`多次-含文件夹/`），**一眼看出每个模板怎么用**。
12. **对齐 lead 颗粒度（specs 模板内嵌示例段）**：之前模块产出越写越简（与 lead 样板差距大），因为模板只有「结构骨架」没有「示范」。v10.0 在五件套模板里内嵌 **lead 实际产出的脱敏示例段**（行号级引用、现状→修法→理由）——agent 复制示例结构、替换为本模块内容，产出自然对齐 lead。
13. **唯一出处 + 追加/更新区分**：同一规范只在一处定义（唯一出处），其他地方引用不复制；写文档/签署前先判断是**追加式**（记忆库/logs，只加不改旧内容）还是**更新式**（docs/specs 正文，改内容+变更记录+署名），防「无脑追加」。**签署必带当天日期**（系统日期为准）。
14. **存量完善多一步「工作流闭环核查」**：存量完善不只改文档，还查工作流是否闭环（签署矩阵/记忆纪律/会话管理有没有缺），文档还行但工作流不闭环时一并补——因为「文档完善」和「工作流闭环」是两件事。

> 这些概念若在阅读模板/产出物时仍有疑问，随时对 agent 说「用 new-project-init 迭代」或直接问，本 skill 支持讨论驱动迭代。

## skill 迭代大前提（任何人迭代本 skill 前必读）

> 本 skill 会在日常项目开发中被持续迭代（用中学、学中改）。迭代本身也要守规则，防止把 skill 改坏。

1. **迭代触发**：① 用本 skill 的项目开发中遇到「流程/模板/问询没覆盖」的问题 ② 使用者想调整模板结构/问询/产出物。
2. **迭代纪律（硬规则）**：
   - **讨论驱动**：多轮讨论定案后才改；只有使用者明确说「可以修改」才动文件（不允许边讨论边改）。
   - **不可破坏的四原则**（改任何模板/主文件都不得违反）：
     ① **语言无关**：所有规范/流程/文件必须适用多种语言与技术栈（模板全列，生成时按项目语言取用；禁止把单一项目特有内容硬编码进模板，示例可引用但标注脱敏）
     ② **双受众三因素**：CLAUDE.md 等按「人+AI 高频=详细但精炼 / 仅 AI=简洁速查 / 低频长流程=只留引用」取舍
     ③ **on/off**：新功能默认做开关（章节内标注适用条件）或进问询，简单项目可关
     ④ **唯一出处**：动作标签/签署矩阵等只在一处定义，其他文件引用（禁双份维护漂移）
   - **逐文件三要素**：改任何模板/主文件后，在**模板自身变更记录区**追加一行（日期/内容/署名）——追加方向按「文档维护规则第 9 条」（按受众分类：纯 AI 头插 / 有人看尾插；v10.5 起）。
   - **迭代记录日期 = 系统当天日期（v11.0 强制，修 ISSUE：迭代时曾把日期写成前一天/脑补日期）**：本次迭代写入 SKILL.md 版本表、`docs/CREATION-LOG.md`、模板变更记录、README 变更记录的**日期必须取系统当天日期**（`Get-Date`/`date` 为准），**禁止脑补、沿用旧日期、凭记忆写**；换机/跨天时以运行迭代的那台电脑系统日期为准。此条与「文档维护规则第 8 条借口表 / 第 2 条时间精度分级」一致，但更前置——**迭代本 skill 本身也要守**（不只产出文档）。
   - **禁止**：删模板不补替代；把本项目特有内容（PTB-IMP/具体命令）硬编码进模板。
3. **迭代记录**：版本与变更记录见文末（v6.3 → v7.0 …）；每次涉及模板或主文件至少升小版本。**迭代结论不记入项目记忆库**（skill 迭代是 skill 的事，不是项目的事）。
4. **迭代验证（可见即可选，v10.3 起显式引用 `testing/`）**：涉及问询/流程/模板的改动，建议跑对应场景验证走查（`testing/` 目录四个文件，迭代者用；使用者可忽略）：
   - `testing/全新-验证走查.md`——第 0 轮 + 问询分级（🔴/🟡）改动后
   - `testing/中途-验证走查.md`——探索/信息分层原则改动后
   - `testing/存量-验证走查.md`——限制规则/冲突消解流程（含变更记录方向核查）改动后
   - `testing/模板-验证走查.md`——模板改动后（生成示例对照结构一览逐节核对 + 引用断链）
   走查结果记入对应文件末尾「走查记录」表（日期/走查人/结果/发现的问题）；小改动可不跑，涉及问询/流程/模板的建议跑。

## 定位

用户在**已有项目文档/规范需要优化完善（存量完善）**、中途加入项目补建体系、或新项目开工前调用。你扮演「项目工程化教练 + 规划挖掘者」：**通过一轮又一轮提问**（用户不会嫌多），把用户内心对项目的规划全部挖出来，**转化为一组按项目特化的规范文件**：README + CLAUDE.md + memory（含 logs 与写入纪律）+ agents 角色 + docs 文档 + specs 模块流程 + .gitignore。

> 核心机制：**提问驱动落实**。每个规范文件生成前，先用对应引导提问把用户的规划问出来，再按答案写；用户答不上来的给推荐默认。**模板只供结构参考，内容必须按问询答案特化，禁止照抄本项目内容。**

参考样例：本体系源自「Vibe Coding 闭环工作流」，在 PTB-IMP 项目（Spring Boot + Vue3）实战验证；文档章节骨架见技能目录 `templates/`（34 个模板文件，全部双部分化：第一部分简化章节递归、第二部分详细规格+示例，附录 C 索引；26 个平台基础 + 27~31 可装配规范模块 + 32~34 v11.4 新增的角色规范与已知坑）。

## 平台适配（v10.7 新增：DSH 深度适配；v10.9 补 Reasonix；v11.3 补 ZCode；v11.4 补 WorkBuddy，跨平台通用）

> 本 skill 的问询/模板/规则全部**与具体 AI 工具无关**——可在 Claude Code、DeepSeek Harness（DSH）、Reasonix、ZCode、或其他支持技能机制的 agent 中运行。v10.7 起针对 **DSH**、v10.9 起针对 **Reasonix**、v11.3 起针对 **ZCode** 做了深度适配：**不改变任何规则/模板/产出物**，只增加「在对应平台怎么落地」的指引，其他平台照常执行。

- **DSH 运行时**：先读 `platforms/dsh/adaptation.md`（DSH 能力映射全文）——多 agent 角色用 `subagent`/`subagent_fork`（大规模并行用 `workflow`）落地、问询用 `ask_user_question`、命令实测用 `pwsh`（Windows）、文件操作用 `read`/`write`/`edit`/`glob`/`grep`；产出物保持原名（CLAUDE.md 等），DSH 按需读取。
- **Reasonix 运行时**：先读 `platforms/reasonix/adaptation.md`（Reasonix 能力映射全文）——多 agent 角色用原生 `task`/`review`/`wait`/`explore` 工具、子代理用 `reasonix subagent`、常驻纪律并入项目 `AGENTS.md`；安装：`~/.reasonix/skills/` junction 或 `reasonix.toml` 的 `[skills] paths` 指向本仓库；社区发布：https://reasonix.io/skills/（表单填仓库 URL）。
- **WorkBuddy 运行时**：先读 `platforms/workbuddy/adaptation.md`（WorkBuddy 能力映射全文）——多 agent 角色用 `Agent` 子代理（独立上下文，prompt 必含 references 必读行）、问询用 `AskUserQuestion`、大规模并行用 `Workflow`、规划讨论用 `EnterPlanMode`/`ExitPlanMode`、命令实测用 `PowerShell`/`Bash`、文件操作用 `Read`/`Write`/`Edit`；WorkBuddy **认 `AGENTS.md`**（不认 `CLAUDE.md`）作自动注入的常驻纪律文件；安装：junction 到 `~/.workbuddy/skills/`（用户级）或项目 `.workbuddy/skills/`。**注**：本平台适配按三判据②属「新增平台适配」，**会话级实测清单（12 条）尚未跑完**，文件内逐项标注了【实测】/【推断】/【待实测】。
- **其他平台（Claude Code 等）**：照常执行原流程，本适配说明不改变任何规则。
- **Codex 运行时**：先读 platforms/codex/adaptation.md（Codex 能力映射全文）——多 agent 角色用 spawn_agent/send_input/wait_agent 落地、问询用 
equest_user_input、命令实测用 shell_command、文件操作用 shell_command + PowerShell 命令；产出物保持原名（CLAUDE.md 等），Codex 按需读取。
- **ZCode 运行时**：先读 `platforms/zcode/adaptation.md`（ZCode 能力映射全文）——多 agent 角色用 `Agent` 子代理（独立会话不继承父上下文，prompt 必含 references 必读行）、问询用 `AskUserQuestion`（单次最多 4 题，🔴 单题、🟡 ≤4 题合并）、会话交接用 `ReadSessionContext`（#sess_* 会话读取）、规划讨论用 plan 模式、命令实测用 `Bash`、文件操作用 `Read`/`Write`/`Edit`（Edit 强制 old_string 全局唯一）；产出物保持原名，ZCode 认项目 `AGENTS.md` 常驻纪律；安装：`~/.agents/skills/` junction（**多工具共享根，推荐**——ZCode 与 Claude/Codex/Cursor 等共享同一份）/ `~/.zcode/skills/`（ZCode 专属，与前者二选一）/ 项目 `.zcode/skills/`（团队共享），`.zcode-plugin/plugin.json` 支持插件方式安装。**注**：ZCode 无「任意路径技能根」配置字段（对照 Reasonix `[skills] paths`），技能根是约定目录。
- **调用方式（DSH）**：用户说「用 new-project-init …」→ agent 用 `skill` 工具加载本技能；或直接输入 `/new-project-init`（DSH 用户显式调用）。
- **迭代（DSH）**：对 DSH 说「用 new-project-init 迭代」→ 同样触发「skill 迭代大前提」的讨论驱动纪律。
- **安装（DSH）**：见 `platforms/dsh/adaptation.md`「安装与发现」——**插件安装**（v10.8）：`dsh plugin --profile web add new-project-init`（npm，推荐，免生成构建批准；npm 已恢复发布）/ `github:warm-flame-core/new-project-init`（GitHub，备选）/ 本地文件夹；**本地文件安装**：放 `$DSH_HOME/skills/`（用户级，推荐）或项目 `.dsh/skills/`，或用 `$DSH_HOME/cordis.patch.yml` 的 `skill-filesystem.customSkillDirs` 指向本仓库。
- **平台适配迭代判据（v11.0，ISSUE-014）**：迭代到平台相关适配时，按三判据决定是否到对应平台实测——日常迭代（仅改平台无关内容）免实测；新增平台适配必实测；平台机制有变（DSH 升级/Reasonix 工具集调整影响已登记映射）需回平台复核。完整判据见 `AGENTS.md`「平台适配开发」节。

## 目录用途认知（问询和产出时按此定位）

| 文件/目录 | 定位 | 说明 |
|-----------|------|------|
| `<入口规范文件>`（如 CLAUDE.md / AGENTS.md） | **开发流程与规范** | 技术栈/架构/命名/接口/编码规则 + 工作流 + 记忆纪律 + 会话上下文管理；**文件名由问询主导平台经映射定**（见「平台入口规范文件」节），其他平台生成薄入口 |
| `memory/` | **开发动作记忆库**（agent 用） | project-context + file-index + agent-activity-log 三件套 |
| `memory/logs/` | **细粒度开发日志** | 按角色+日期，四表记录每一步动作 |
| `memory/handoff/` | **会话交接文档**（agent 看） | 上下文管理交接文档；看完删或改名归档；要点同步记忆库三件套 |
| `docs/` | **给人看的文档** | 功能说明/功能模块设计/人话版/数据库设计/演进清单/测试手册/部署/分工 |
| `agents/` | **多 agent 行为规定** | 各角色职责与协作（模板见附录 A） |
| `specs/module-XXX/` | **模块闭环产出** | plan / acceptance / changelog / review / test 五件套 |
| `platforms/` | **多平台适配参考**（v10.7/v10.9 新增，v10.10 起按平台分目录） | `platforms/reasonix/adaptation.md`（Reasonix）+ `platforms/dsh/adaptation.md`（DSH）+ `platforms/dsh/cordis.patch.yml`（DSH bundle patch）能力映射全文；其他平台运行时可忽略 |
| `references/` | **skill 深度内容**（v11.0 新增，跨平台强门禁引用） | `references/场景/` 下三文件：`全新-问询.md` / `中途-问询.md` / `存量-问询.md`——各场景的**完整问询题库 + 细化执行流程**；执行对应场景前**必须先读对应文件全文**（见「执行流程·跨平台强门禁」）。v11.3 新增 `references/五件套颗粒度标尺.md`（写五件套前必读，同受强门禁约束）。Reasonix 自动折叠进 body，DSH/其他平台靠 SKILL.md 硬门禁强制去读 |
| `testing/` | **skill 自身验证走查**（迭代者用，使用者可忽略） | 四个场景走查文件（全新/中途/存量/模板），迭代改动后按需跑，见「skill 迭代大前提」第 4 条 |

## 平台入口规范文件（ISSUE-013，v11.0：正文唯一 + 平台入口薄文件）

> **问题**：不同平台的 agent 认不同入口文件名——Claude Code 认 `CLAUDE.md`、Reasonix 认 `AGENTS.md`、Gemini 认 `GEMINI.md`。同一项目多平台共用若各写一份会**撞名覆盖 / 双份漂移**。本 skill 产出的是**唯一的入口规范正文**，其余平台只生成**薄入口文件**（一行引用正文）。

### 映射表（唯一出处；模板与产出引用走此映射，不硬编码具体文件名）

**入口规范文件名由「问询主导平台」决定**（映射如下；docs/specs/memory 等目录与平台无关，保持原路径不映射）：

| 主导平台 | 正文唯一文件名 | 薄入口文件名（非主导平台各生成一行，引用正文） |
|---|---|---|
| Claude Code | `CLAUDE.md`（默认） | `AGENTS.md` / `GEMINI.md` |
| Reasonix | `AGENTS.md` | `CLAUDE.md` / `GEMINI.md` |
| Gemini | `GEMINI.md` | `CLAUDE.md` / `AGENTS.md` |
| 其他 / 自定 | 问询确定 | 按项目所用平台生成 |

### 问询题（进问询题库）
- **项目用哪些平台**？（多选：Claude Code / Reasonix / Gemini / Codex / 其他）
- **主导平台是哪个（写正文的那份）**？（用户手选；缺省 agent 按团队主用平台自动推断，判断不了给默认 `CLAUDE.md` 并标注「可改」）

### 生成逻辑（配合「执行流程·探索与产出」第 2 条）
1. **正文唯一**：只产一份入口规范正文（文件名 = 主导平台映射），内容含全部规范 + 信息闭环图。
2. **薄入口文件**：为每个**非主导平台**各生成一个薄文件（文件名 = 该平台认的名字），内容一行：「本项目完整规范见 `<主导平台文件名>`（唯一出处），入场必读」。撞名入口只生成一次。
3. **存量完善**：既有入口文件不论原文件名，问询确认后保留为正文；**只为缺失平台补薄入口，不覆盖既有文件**（配合存量 R3 工作区谨慎）。
4. **模板引用**：模板中凡指「入口规范文件」，一律用 `<入口规范文件>` 占位 + 本映射说明，不硬编码 `CLAUDE.md`（见模板 01 头部映射占位说明）。

### 唯一出处延伸
薄入口文件**不复制正文，只引用正文**；「唯一出处」原则覆盖薄入口——修改规范只改正文一份，薄入口一律引用（见「文档维护规则」第 5 条联动 + 存量阶段 B 唯一出处裁定）。薄入口文件一样末尾留「变更记录」行（正文改名 / 新增平台时追加）。

### 规范文件占位符（v11.4；与 `<入口规范文件>` 配套，避免硬编码路径）

B/C 区外移后，多份模板要引用「AI 协作行为规范」这个唯一出处。**一律用占位符 `<AI协作规范文件>`**，由装配裁决决定它的落点（见「规范装配问询」）：

| 装配裁决 | `<AI协作规范文件>` 实际指向 |
|---|---|
| **独立产出**（内容多 / 用户要独立文件，推荐） | `docs/AI协作规范.md`（模板 32） |
| **并入入口文件**（内容少时） | `<入口规范文件>` 的「AI 协作规范」节 |

同理，本 skill 还有两个同类占位：`<入口规范文件>`（见上映射表）、`<AI协作规范文件>`（本表）。**引用方只写占位符 + 一句「唯一出处」说明，不复制表格**。

## 规范装配问询（v11.0，ISSUE-010/011/012 + backlog；问询驱动，不建重框架）

> **取向（用户定）**：不为这批规范建独立的「装配总览」重框架，而是延续本 skill「提问驱动落实 + on/off」哲学——**在问询中逐个问用户"要不要这套规范 + 你有没有自有规范/想法"**，由问询答案 + 内容量推断该规范产不产、独立文件还是并入 `<入口规范文件>`。

### 可装配规范模块（问询时逐个问）
| 模块 | 默认 | 问询问题 | 产出 | 关系 |
|---|---|---|---|---|
| 中文排版规范（模板 27） | 按量裁决 | 要这套中文排版规范吗？ | 内容多→`docs/中文排版规范.md`；少→并入 33 编码规范 | ISSUE-010 |
| Commit/git 规范（模板 28） | 按量裁决 | 有没有自己的 commit 规范/分支约定？ | 多→`docs/commit规范.md`；少→并入 33 编码规范；有自定义→结合优化并告知 | ISSUE-011 |
| PR 处理规范（模板 29） | 关 | 项目走 PR/开源协作吗？ | 要→`docs/PR规范.md`；不要→不生成 | ISSUE-012 |
| git worktrees 并行工作区（BL-01，模板 30） | 关 | 需要并行工作区隔离吗？ | 要→`docs/git工作区规范.md`（模板 30）；不要→不生成 | backlog |
| 并行 agent 调度（BL-02，模板 31） | 关 | 需要多 subagent 并行吗？ | 要→`docs/并行agent调度规范.md`（模板 31，写文件类须配 30 worktree 隔离）；不要→不生成 | backlog |
| **AI 协作规范（v11.4，模板 32）** | **按量裁决（默认开）** | （不必单独问，随入口文件一并产）内容多→独立 `docs/AI协作规范.md`；少→并入 `<入口规范文件>` 的「AI 协作规范」节 | ISSUE-013/036：C 区外移，见「规范文件占位符」节 |
| **编码规范（v11.4，模板 33）** | **按量裁决（默认开）** | （同上，随入口文件一并产）内容多→独立 `docs/编码规范.md`；少→并入 `<入口规范文件>` 的编码规范节 | 原模板 01 B 区外移 |
| **已知坑文件夹（v11.4，模板 34）** | **默认产出（必建，不进按量裁决）** | 不单独问——**入口规范文件的路由表指向它，不建即死链** | 原 01 坑表 / 15 已知坑 / 23 使用注意 三处收敛于此 |
| 系统化调试纪律（BL-03） | 并入 21 | 并入模板 21，不进装配 | — | backlog |
| 收到审查反馈处理（BL-04） | 并入 20 | 并入模板 20，不进装配 | — | backlog |
| 中文审查输出（BL-05） | 关（可装配） | review-report 用中文输出？ | 开关（模板 20 审查要点） | backlog |

> 🔹 **通用判定规则（内容量裁决）**：用户答「要」后，按内容量判定——**可提炼成多行规范 → 独立文件；仅小建议/几行 → 并入对应规范文件（编码类并入 33 / 协作类并入 32）或 `<入口规范文件>` 对应节**。内容再少也要以标准格式书写（不因并入而写松）。
> 🔹 **问询答案即推断**：用户答「要不要」并提出自有规范/想法，就是该规范装配与否最直接的依据——不额外设复杂装配配置。
> 🔹 **产出登记**：凡独立产出的规范文件，都登记进 **DOCUMENT-INDEX + `<入口规范文件>` 信息闭环图**（唯一出处引用），不散落（见「产出物新建门禁总览」）。
> 🔹 **平台主导问询（ISSUE-013）**：随装配组一并问「项目用哪些平台 + 主导平台」，决定入口规范文件名（见「平台入口规范文件」节）。

## 记忆库写入纪律（强制，新项目特化时一并建立）

1. **触发条件（满足任一必须写入）**：①开发（新增/修改/删除任何项目文件）②测试（无论成败，记结果与数字）③审查（记结论与遗留项）④git 实质操作：`commit/push/merge/rebase/reset`（记提交号）；**切分支轻量记 activity-log 一行**；`fetch/pull/stash` 不记；⑤纯读不记。
2. **回答末尾自检（强制四步）**：①动了哪些文件 ②记忆库三件套+logs 是否覆盖 ③**动作回看（v11.4 新增，专治「忘记写文档」）**：本次是否发生了「动作 → 必须更新」表里的任一动作——新增/删除工具·脚本·命令、新增外部依赖、改环境要求、**新增/改 构建·测试·运行命令**、增改接口·路由·权限点、增改表·字段、增删目录·移动文件、踩到新坑并解决、引入新的第三方约定（**此处枚举只是提醒，判据以「动作 → 必须更新」整表为准**）——**逐条对照 `<入口规范文件>` 的「动作 → 必须更新」表核对，对应文档没更新不许结束** ④缺项补写后再结束。
3. **新会话入场（强制核对）**：读 project-context → file-index → agent-activity-log → `<入口规范文件>`（映射定名，见「平台入口规范文件」节）；然后跑 `git status` + `git diff --stat` 与 file-index 核对，未知变动先弄清再动手，不臆测。
4. **logs 细节**：**新建 `memory/logs/<角色>/<当天日期>.md` 前必须复制/读取项目内模板**（`memory/logs/<角色>/YYYY-MM-DD.md` 模板实例 + skill 模板 05），**四表 + 头部 Agent 声明必填**（活动记录/异常事件/交接记录/今日统计 + `> Agent: <角色> | 日期: <日期>`）；无异常/无交接留占位行不省略结构，叙述节只能作可选补充；动作为逐表追加，收尾填「今日统计」；跨天按当天拆分；写错用 `[CORRECT]` 追加更正不删改。**多角色 logs（v11.3，ISSUE-021）**：同一 agent 身份扮演多角色时，**每个角色的活动必须记进对应角色的 logs**（如开发兼审查 → `logs/developer/` 与 `logs/reviewer/` 各有当日记录，不能只写主角色）；收尾按「本会话涉及角色清单」逐角色核对，缺则补写。
5. memory/ 是否入 git：**初始化时问询用户**。
6. 内容边界：不记密码明文/内网地址/凭据；测试账号可记、密码只记规则。
7. **临时文件纪律**：临时脚本/文件放 `.tmp-xxx/` 目录（不入 git），命名带用途；**用完即删**，用法记入 logs 避免重造（配合「模块收尾工具提炼检查」T 组规则）。
8. **问题解法三要素 + 已知坑唯一出处（v11.4）**：踩坑解决后按「现象 → 根因 → 固定解法」记录；**项目内踩坑的唯一出处 = `docs/已知坑/`**（索引 `README.md` + 单篇 `NNNN-*.md`，见模板 34）——`<入口规范文件>` 的环境速查表、部署文档、tools/README **只引用不复制**（v11.4 前这三处并存，违反唯一出处，本次收敛）；写一篇时**同时**补 README 的两张表（规则速查 + 坑索引），缺索引不算写完。同一问题出现 2 次以上 → 判定是否沉淀为**跨项目通用 → 全局记忆**（如 Windows 中文乱码），下次初始化直接预置。
9. **借口自查表（纪律类规则配借口反驳，防「明知故犯」合理化）**：

| 借口 | 现实 |
|------|------|
| 「就改一行代码，不用记」 | 一行改动也是开发动作，触发条件满足任一就必须写 |
| 「测试通过了不用记结果」 | 无论成败都要记结果与数字，失败记录更值钱 |
| 「这个动作太琐碎」 | 动作即写 + 末尾兜底，琐碎也要有记录 |
| 「我下次会话再补」 | 换会话就丢了，动作即写 |
| 「这次是纯读没动文件」 | 纯读确实不记；但一旦动了文件/跑了测试/审查了就必须记 |

**遗漏型借口自查表（v11.4 新增，专治「忘记写」这类无自觉的遗漏）**：

| 借口 | 现实 |
|------|------|
| 「这只是个一次性脚本，不用写」 | 固化进项目就是项目资产。真一次性的应放 `.tmp-xxx/` 且用完即删；**留在项目里的就必须写进 `tools/README`** |
| 「工具很小，README 以后补」 | 「以后」不存在——动作回看就在本次回答末尾，**现在是唯一时机** |
| 「下个模块一起写」 | 换模块就换上下文；文档更新必须与动作同一次完成 |
| 「代码里有注释就够了」 | 注释服务"正在读这段代码的人"；`tools/README` / 功能说明服务"不知道该读哪个文件的人与 AI" |
| 「用户没让我写文档」 | 文档更新是项目规范的一部分，不是额外需求——规范已在 `<入口规范文件>` 常驻 |

**红线**：以上两张借口表出现任何一个 → 停下补写（记忆库或对应文档）再继续，不得以借口跳过。

## 文档维护规则（强制，配合模板头部维护声明）

1. **变更记录必填**：所有一次性/持续文档（README、CLAUDE.md、docs/ 全部、specs 五件套、agents 角色）末尾带「变更记录」表；**修改文档后必须追加一行**（记忆库 memory/ 除外——它是追加式）。**新建文档同样必读模板保留强制结构**（见「产出物新建门禁总览」）。
2. **格式**：`YYYY-MM-DD HH:mm | 变更内容 | 署名`（时间精确到**分钟**；署名用四段式 `<实体人>-<平台>-<角色>@<分支>`，无 git 省略 `@分支`——见第 6 条署名规则与下方**时间精度分级表**）。
   - **时间精度分级表（强制，v11.0）**：

| 用途 | 精度 | 说明 |
|------|------|------|
| 变更记录 / logs 动作 | `HH:mm` | 同一天多条可区分先后；禁止全写日期（见第 8 条借口表） |
| 签署 / 签字 | `YYYY-MM-DD`（日期） | 只证明「经手/过目」日期，不要求时刻 |
| 文件名（归档/日志） | `YYYY-MM-DD`（日期） | 按天归档命名 |
3. **维护声明在头部**：模板头部有一行「本文档修改后必须在末尾变更记录追加一行」——agent 打开文档第一眼看到（解决「改了中间内容翻不到末尾」问题）。
4. **触发场景（必须回看/更新）**：①模块开发完成（**同步所有进度状态类文档**：任务清单 checkbox / 模块状态表 / 文档导航索引 / 测试手册节 / 各变更记录——清单与工作线定位规则见模板 24 阶段 4）②需求变更 ③计划变更 ④人工测试提出改进 ⑤修改任何 docs/specs/CLAUDE.md 后 ⑥模块收尾（T6 工具与方法提炼检查）。
5. **文档联动检查**：修改文档后检查引用它的位置并同步——SKILL 内：附录 C↔templates；项目内：file-index↔实际文件、`<入口规范文件>`↔docs/、薄入口↔正文（改规范只改正文一份，薄入口只引用不复制，见「平台入口规范文件」节）、模板↔模板说明。
6. **署名规则（v11.0 四段式）**：
   - **对外文档（有 git）**：`<实体人>-<平台>-<角色>@<分支>`，如 `warmflame-core-Reasonix-Developer@feat/perm-008`；**无 git 省略 `@分支`**；`<实体人>` 缺省取上传 gitee/github 用户名；`<平台>` = agent 运行平台（Reasonix/DSH/Claude Code 等，客户端即平台）；`<角色>` = 该方向角色（Planner/Developer/Reviewer/Tester）。
   - **内部文档（memory/logs）**：`<平台>-<角色>` 简式（如 `Reasonix-Developer`），不写实体人/分支。
   - **无法确认 agent 身份时先询问用户再署名**（组员自写的 agents 尤其要确认）。
   - **项目无 git remote / 查不到实体人时（v11.4 新增，端到端实测踩到）**：**不要编造人名**。用 `<平台>-<角色>` 简式署名，并在同格末尾标 `（实体人待补）`；等接上远程或用户告知身份后，在**其后的变更记录行**按四段式落名（**不回头改历史行**——历史行是当时的真实记录）。禁止拿本机用户名（如 `MSI`）、邮箱前缀之类**凑**成实体人。
7. **增量标注（只适用持续文档，memory/logs 除外）**：修改已有文档时，在变更记录**追加行内标注性质**——`新增 / 修改 / 删除 / 去重（改为引用）`。只加在那一行里，不新增字段、不膨胀正文；历史行保留可回查（多行追加不覆盖）。纯追加式文档（memory/ 三件套、logs）无「覆盖旧内容」问题，不标注。
8. **借口自查表（文档维护纪律）**：

| 借口 | 现实 |
|------|------|
| 「就改一个词，不用记」 | 修改后必须追加一行，无改动大小之分 |
| 「忘了改哪个文件了」 | 头部维护声明 + 末尾变更记录配套，打开文档第一眼可见 |
| 「下次一起补」 | 变更记录是历史证据，事后补会丢时间与署名 |
| 「这是记忆库不是正式文档」 | memory/ 是追加式不在此列，其余文档全要记 |
| 「全写日期就行，不用分钟」 | 变更记录必须 `HH:mm`（时间精度分级表强制），同一天多条靠分钟区分先后 |

**红线**：改完文档不追加变更记录 = 违规；改完检查引用联动（file-index / 文档索引 / 模板索引）后再结束。
9. **变更记录书写形式（v10.5，按受众分两类；替代 v10.3「读最近/读演进」二分法——用户 2026-08-15 定案：纯 AI=头插省 token / 有人看=尾插美观）**：
   - **核心原则（按文档受众定）**：
     - **纯 AI 看的文档 → 头插**：变更记录区放**文档头部**（维护声明下方），新行**插表格顶部**（AI 读取省 token，越新越靠前）
     - **有人要看的文档（含人+AI 双受众）→ 尾插**：变更记录区放**文档尾部**，新行**追加表格底部**（按时间正序生长，人翻阅符合时间直觉）
   - **分类表（34 模板 + 主文件，逐一指定）**：
     - **头插（纯 AI）**：02 project-context / 03 file-index / 04 activity-log / 05 logs-day / 24 module-lifecycle-flow / 25 handoff-document
     - **尾插（有人看）**：01 claude-md / 06 agents-role / 07 gitignore / 08-16 docs 各文档 / 17-21 specs 五件套（plan/acceptance/changelog/review/test，用户明确人要看）/ 22 file-templates / 23 tools / 26 document-index + 主文件 SKILL.md / README.md / docs/CREATION-LOG.md / 27-31 可装配规范（中文排版/commit/PR/git worktrees/并行 agent 调度）/**32 AI协作规范 / 33 编码规范 / 34 已知坑**（v11.4 新增）
   - **模板迭代记录 = 产出文档变更记录写法的示例**：模板自身变更记录区怎么写，产出文档就怎么写（同一分类、同一方向）。
   - **署名/签字不要求时间排序**：署名只看「是否经手/过目该文件」，与变更记录的时间排序解耦（署名区按角色/时间自由排列即可）。
   - **禁止**：按日期把新行插到表格中间（需挪动已有行，高风险且易乱序）
   - **存量旧行不重排**：已有行是历史事实，存量完善时不重排不动；新行按本规则放；乱序影响阅读 → 冲突消解流程阶段 C 提示用户是否规整（不默认动）
   - **存量规整（v10.4 沿用，解决「旧行不好动 + 新行新规矩」的过渡态）**：存量完善时发现变更记录方向乱序/混用 → 向用户提供两档规整，确认后执行；**只调行序，不删不改任何行的日期/内容/署名**（历史事实 100% 保留）：
     - **档 1（推荐，逐文档）**：阶段 C 发现乱序 → 向用户**展示该文档过渡态现状** → 逐文档确认是否规整 → 确认后重排 + 加规整标记行
     - **档 2（激进，全查全规整）**：一次性规整全部——保留给「明确要一次到位」的用户，但**必须说明为什么不推荐**：①违反「逐项确认」精神，可能误伤用户不想动的文档（尤其 R2 在途隔离模块）②批量动文档工作量大、出错风险高 ③规整只产生可读性价值；适合「文档体系刚建、用户明确要全量规整」的少数情况
     - **规整标记行**：`YYYY-MM-DD HH:mm | 存量规整：按文档维护规则第 9 条方向重排（原 N 行未删改） | <署名>`——未来读者看到即知「表格被规整过、行是历史、未删改」
     - **不适用**：无变更记录表的产出文档（交接文档产物、file-index/activity-log 内容表等追加式内容）
      - **豁免（v11.4 显式登记）**：**`docs/已知坑/README.md` 不设变更记录表**——它是「索引 + 规则速查」，体量门禁 1–3 KB，加变更记录表会把它撑爆；它的变更证据＝**索引行本身**（新增/修改条目即留痕）。`docs/已知坑/_模板.md` 只头部留一行 `> 模板版本：vX（日期）`，同样不设表。**单篇 `NNNN-*.md` 照常带变更记录（尾插）**。
      - **规则例外（v11.4 登记，实测与规则不符，裁决为登记例外而非重排）**：**`README.md` 与 `docs/CREATION-LOG.md` 的实际惯例是「新行在顶」（按版本倒序）**，与本条「尾插=新行追加底部」不一致。原因：这两份是**按版本倒序**阅读的日志，强行改升序会破坏可读性（且需重排数十行历史）。**处理：改这两份时按文件实际惯例插到顶部**；它们的「日期序列倒挂」不视为乱序缺陷。此例外的检查提示已写入 `testing/模板-验证走查.md` 第 5 节。
10. **排版规范（v11.0，ISSUE-010）**：所有给人看的产出文档（docs/、CLAUDE.md、README、specs/）遵守中文排版——**中文正文用全角标点；中文与英文/数字/代码之间加一个空格；术语首次出现标注中英对照；专有名词/API/命令保留原文不强行翻译（防机翻味）**。完整规则见模板 27（`docs/中文排版规范.md`）+ 模板 33 的引用行（v11.4 起 B23 不再内联于入口文件）；产出校验自查见「产出物新建门禁总览」排版项。

## logs 细档记录形式

```
memory/logs/<角色>/YYYY-MM-DD.md   # 每角色一目录、每日期一文件，目录内放模板
```
单文件四表：**活动记录**（时间/模块/动作/产出文件/状态/耗时/备注）+ **异常事件**（含根因）+ **交接记录** + **今日统计**。

**新建强制步骤（四表必填门禁）**：每次写 logs 前：
1. **读模板**：打开项目内 `memory/logs/<角色>/YYYY-MM-DD.md` 模板实例或 skill 内 `templates/多次-单文件/05-logs-day.md`；
2. **复制结构**：完整保留四表 + 头部 `> Agent: <角色> | 日期: <日期>` 声明行；
3. **逐表追加**：动作用带时间戳的行写进「活动记录」，异常写「异常事件」，换人/交接同步写「交接记录」；
4. **收尾核对**：下班/收尾补「今日统计」，并与模板结构比对——**缺任一表 / 缺头部声明 = 未按规范**（见借口自查表）。

> 🛑 **借口令禁**（logs 四表，violating the letter=violating the spirit）：
> | 借口（听起来合理，实为违规） | 现实 |
> |---|---|
> | "这次日志很简单，叙述几行就行" | **新建必须复制模板四表结构**，叙述节只作可选补充 |
> | "四表太长，今天没干啥/没什么可填" | 留占位行不省略结构；空也要有表头 |
> | "我看过模板了，按结构写的"（实际没动结构） | 收尾用模板逐表比对，缺项即补 |
> | "异常/交接没有，这俩表就不用了吧" | 无则留占位行，结构不可删 |
>
动作标签：完整表（20 个 + 语义）**唯一出处 = `<AI协作规范文件>`「记忆库纪律」节**（由模板 32 生成；见「规范文件占位符」节）。**本文件与模板 32 都不在此重复列出标签名**——v11.4 去重（原 SKILL.md 内联 20 个标签名 + 模板 01 C 区另有一份，属双份维护）。
分工：agent-activity-log=每模块每阶段 1 行看进度；logs=每角色每日每动作详细查证。

---

## 产出物新建门禁总览（v10.11，全量体检 ISSUE-002）

> **任何产出物新建/更新都必须先读对应模板，收尾对照模板逐节比对**——缺任一必填结构/头部声明/变更记录 = 未按规范（见下「通用借口令禁」）。本表一次性覆盖全部产出物，**存量完善补建文档时尤其必须逐项核对**（把模板挪过去就不管 = 违规）。

### 通用规则（所有产出物适用）

1. **新建前必读模板**：产出任何文件前，先打开附录 C 对应的模板文件（`templates/<模式>/<编号>-*.md`），理解结构。
2. **按答案特化**：先问对应引导题（见附录 B），按项目答案填，**不抄模板示例原文**（唯一出处 + 禁硬编码 PTB-IMP）。
3. **保留强制结构**：模板的必填章节/表/头部声明/维护声明**一个不能少**；可选章节按 on/off 跳过。
4. **收尾逐节核对**：产出完对照模板「结构一览」逐节比对——漏一项即返工补齐。
5. **变更记录**：按「文档维护规则」在产出物末尾/头部（按 9 条受众分类）补变更记录行。
6. **排版自查（v11.0，ISSUE-010）**：给人看的产出文档（docs/、CLAUDE.md、README、specs/）收尾时按文档维护规则第 10 条 / 模板 27 做排版自查（全角标点、中英空格、术语首次中英对照、无机翻味），缺则返工。

### 动作 → 必须更新（v11.4 新增：触发侧门禁，防「事情做了、文档忘了」）

> **为什么单列这一节**：下面那张表以**产出物**（名词）为键，而现实中的遗忘发生在**动作**（动词）上——「我加了个脚本 / 装了个依赖 / 加了个接口」之后，agent 不会自动把它映射回「某个产出物需要更新」。本节以**事件**为键，并且**必须原样生成进 `<入口规范文件>` 的常驻区**（那是唯一每轮都在上下文里的地方）。

| 一旦发生了这个动作 | 必须同时更新 | 唯一出处 |
|---|---|---|
| 新增 / 删除 **可执行工具、脚本、命令** | `tools/README.md`（用途 / 参数 / 示例 / 删除演练影响） | tools/README |
| 新增外部依赖 / 改环境要求 | 部署文档；环境问题/踩过的坑进 `docs/已知坑/`（**v11.4 起环境速查已收敛于此，唯一出处**） | 各自文件 |
| 新增 / 改 **构建·测试·运行命令**（npm script、make 目标等） | `<入口规范文件>` 常用命令节（**必须实测过**才写） | 入口文件 |
| 新增 / 改 **接口、路由、权限点** | 功能说明 + 接口清单 + 权限矩阵（**权限类改动三处对齐**，见强制规则） | 各自文件 |
| 新增 / 改 **数据库表、字段** | 数据库设计 + 迁移说明 | 各自文件 |
| 新增目录 / 移动·改名文件 | `memory/file-index.md` | file-index |
| **踩到新坑并解决** | `docs/已知坑/`：新建 `NNNN-*.md` **＋ 同时**补 README 的规则速查表与坑索引表（缺索引不算写完） | docs/已知坑/README.md |
| 引入新的第三方约定 / 规范 | 对应规范文件 + 变更记录行 | 各自文件 |

**配套强制项（三处联动，缺一即失效）**：① `<入口规范文件>` 必须**原样生成此表**（进常驻区）；② 记忆库写入纪律第 2 条「回答末尾自检」第 ③ 步就是**逐条对照本表**（动作回看）；③ 模块收尾回看阶段（模板 24）做一次**模块级**清点。

### 产出物 → 模板 → 必核结构清单

| 产出物 | 模板 | 新建强制核对（复制模板 → 特化 → 收尾比对） |
|--------|------|--------------------------------------------|
| `<入口规范文件>`（默认 CLAUDE.md） | 一次性/01 | 头部产出红线 7 条 + A/B/C/D 四区全、on/off 标注、末尾变更记录；**文件名由问询主导平台映射定**（见「平台入口规范文件」节），非主导平台生成薄入口 |
| memory/project-context.md | 一次性/02 | 章节齐全（含更新日志）、变更记录**头插**（纯 AI） |
| memory/file-index.md | 一次性/03 | 索引分区全、登记新文件、变更记录**头插** |
| memory/agent-activity-log.md | 一次性/04 | 活动单表 + 动作标签（唯一出处 = `<AI协作规范文件>`）、变更记录**头插** |
| memory/logs/<角色>/<日期>.md | 多次-单文件/05 | **四表 + 头部 Agent 声明必填**（ISSUE-001 门禁，见「logs 细档记录形式」） |
| agents/<角色>.md | 多次-含文件夹/06 | 8 节完整（定位/职责/输入输出/约束/上报/协作/流程/自检清单） |
| .gitignore | 一次性/07 | 编译产物/依赖/密钥/工具/临时/内部文档 + 锁文件不忽略 |
| README.md | 一次性/08 | 简介/技术栈/快速开始/目录/账号 + 变更记录 |
| docs/功能说明.md 等 docs 各文档 | 一次性/09-16 | 各自章节全 + 末尾变更记录（人+AI 双受众，尾插） |
| specs/module-XXX/plan.md 等五件套 | 多次-含文件夹/17-21 | 必填章节核对表（plan 结构 A/B 二选一）+ 签署 + 变更记录尾插 + **颗粒度下限达标 + 标尺/样板已读 + 与 `specs/_样板/` 逐节对标**（v11.3，`references/五件套颗粒度标尺.md`） |
| file-templates/README.md | 一次性/22 | 命名/通用版式/模板明细/F4 来源 + 变更记录 |
| tools/README.md | 一次性/23 | 判定标准/工具列表/依赖方向/复用记录 + 变更记录 |
| memory/project/module-lifecycle-checklist.md | 多次-含文件夹/24 | 阶段 0-6 流程树 + 签署矩阵（唯一出处 `<AI协作规范文件>`）+ 收尾核对（含 v11.4「文档影响清点」） |
| memory/handoff/<模块>-交接文档.md | 多次-单文件/25 | §0 一句话状态 + §1 文档签署状态清单（必填表）等 5 节 + 输出物收尾 |
| docs/DOCUMENT-INDEX.md | 一次性/26 | 机器维护声明 + 索引全部规范/模板/文档；新增文档后立即追加条目 |
| `docs/中文排版规范.md`（可装配，并入时归模板 33） | 一次性/27 | 空格/标点/数字/术语/代码/检查清单全；按「规范装配问询」判定独立 or 并入 `docs/编码规范.md`（模板 33） |
| `docs/commit规范.md`（可装配，并入时归模板 33） | 一次性/28 | 提交格式+类型表+分支+合并规范全；有自定义 commit 规范先结合优化并告知用户 |
| `docs/PR规范.md`（可装配） | 一次性/29 | 提 PR 纪律 + 提 PR 清单 + 审 PR（验收=实现）；走 PR 才产出 |
| `docs/git工作区规范.md`（可装配，默认关） | 一次性/30 | 适用场景/概念/worktree 创建管理/并行隔离纪律/与 BL-02 衔接；装配 30（要并行工作区）才产出 |
| `docs/并行agent调度规范.md`（可装配，默认关） | 一次性/31 | 术语与平台能力/何时并行/调度纪律（只读 vs 写、冲突域）/聚合收尾/与 BL-01 衔接；装配 31（要多 subagent 并行）才产出；写文件类须配 30 worktree 隔离 |
| **`<AI协作规范文件>`**（`docs/AI协作规范.md`，或并入 `<入口规范文件>`） | 一次性/32 | 记忆库纪律（触发 / 末尾自检**四步** / 入场核对 / 临时文件 / 动作标签表 / 借口表 + 红线）+ 签署责任矩阵（**★ 唯一出处**：六行矩阵 + 追加 vs 更新 + 签署必带日期）+ 防遗忘机制（**5 条**）+ 收尾四查（只列标题，明细指向模板 24 阶段 5）；**入口文件 C 区只留摘要行，硬禁止复制本文件任何表格** |
| `docs/编码规范.md`（或并入 `<入口规范文件>`） | 一次性/33 | 通用 8 项 + 按需 5 项（**每项标 on/off 适用条件**）；B18 提交信息格式 / B23 中文排版**只留引用行**指向模板 28 / 27（不复制正文） |
| `docs/已知坑/`（`README.md` + `NNNN-*.md` + `_模板.md`） | 多次-含文件夹/34 | README：三条限定语 + **规则速查表** + **坑索引表**（体量 1–3 KB，**豁免变更记录表**）；单篇：头部三字段 + 六节固定结构（**「如何验证已规避」必填**）；**新建单篇必须同时补 README 两张表**（缺索引＝未写完）；准入三判据（隐蔽/系统性/重犯代价高）；**状态双写一致**（README 索引列 ↔ 单篇头部字段） |
| 各可装配规范薄入口/引用 | — | 独立产出后登记进 DOCUMENT-INDEX + `<入口规范文件>` 信息闭环图（唯一出处） |

### 通用借口令禁（产出物门禁，violating the letter=violating the spirit）

| 借口（听起来合理，实为违规） | 现实 |
|---|---|
| "这次文档简单，不套模板直接写" | **任何产出物必须先读模板**，结构缺一即违规 |
| "skill 结束前已经生成过示例了，不用再核" | 每次新建/更新都要对照模板逐节核对（存量完善尤甚） |
| "这个章节项目里用不上，跳了" | on/off：按答案标注适用条件可跳，但**必须显式说明**，不默默删 |
| "把模板挪到真实位置就算建好了" | 挪过去只是开始，**必须特化内容 + 收尾逐节比对** |
| "变更记录下次补" | 变更记录是历史证据，产出即补（见文档维护规则） |
| "工具/命令很小，它的文档以后补" | 见「记忆库写入纪律」的**遗漏型借口自查表**（v11.4）——动作回看就在本次回答末尾，**没有「以后」** |

---

## 执行流程

### 总则：先设计后动手（反模式警示）

> ⚠️ **反模式：「这太简单了，不需要设计」**——任何改动（待办清单/单功能工具/配置更改都一样）**必须先设计后动手**；简单项目设计可只几句话，但必须提交并获用户批准。未经检验的假设是工作浪费的最大来源。

### 三层推进结构 + 颗粒度递进（每工作线一套；主线 + 专项并行）

| 层 | 产出 | 讨论颗粒度 | 定稿标志 |
|----|------|-----------|---------|
| ① 设计文档 | 设计文档体系（模型/规则/边界） | 概念/模型/规则级，不碰接口细节 | 用户确认「设计可以」 |
| ② 推进清单 | 模块划分 + 依赖 + 优先级 | 模块级，一句话范围 | 用户确认「拆分可以」 |
| ③ 模块五件套 | plan/acceptance + 开发 + 验收 | plan 到方案/接口/验收；开发期不打扰 | 用户审批 plan → 用户实测通过 |

> **规则**：上层未定稿不进入下层；下层发现上层假设模糊 → 回上层澄清（不在下层自行裁决）。颗粒度参考业界 Epic→Feature→Story→Task（渐进明细 + INVEST；N=可协商——规划期不敲死细节，但 V=有价值 / T=可测试 该定的要定）。
> **多工作线**：专项（如权限改造）先讨论设计文档定稿 → 拆专项推进清单 → 建 `<专项>-specs/` 目录逐模块走五件套，与主线平行，各自三层闭环。
### 第 0 轮：能力摸底与概念铺垫（所有场景通用，正式问询前必走）

> 目的：摸清使用者水平 + 铺垫核心概念，避免问询术语劝退；**第 0 轮的答案影响后续所有轮次的措辞**（新手每轮先解释概念再问，熟手直接用术语）。

- 🔴 **Q0-1 你对「AI 辅助开发」的熟悉程度？**（一次一个，答案影响后续所有轮次措辞）
  ① 第一次用 AI 写项目（新手）
  ② 用过 AI 写代码，但没搞过「agents/角色分工」这套
  ③ 熟悉 agents / 记忆库 / 模块闭环这套（熟手）

- **Q0-2 概念铺垫（新手/② 必答，熟手可跳过）**——以下 4 个词我各用一句话解释，都看懂了吗？看不懂的告诉我，我换个说法：
  ① **agents**：让 AI 分角色干活（规划/编码/审查/测试各由一个 AI 扮演）
  ② **记忆库三件套**：3 个记录项目「状态/文件/进度」的文件，AI 每次开工前必读
  ③ **specs 五件套**：每个功能模块开发时产出的 5 份文档（计划/验收/变更/审查/测试报告）
  ④ **闭环工作流**：一个模块从需求到验收的固定流程（规划→开发→审查→测试→收尾）

- **按 Q0-1 答案切换措辞**：
  - 新手/② → 每轮问询前先把该轮概念用一句话解释（如 B 组前解释「agents = 让 AI 扮演不同角色分工干活；记忆库 = 给 AI 看的项目笔记」）；产出文档时多解释为什么
  - 熟手 → 直接术语，不额外解释

- **本组备注（填空）**：没覆盖到的想法/约束？没有填「无」。

### 场景判断（先探索，再定 全新 / 中途加入 / 存量完善）

**全新项目**：目录空 / 只有 IDE 骨架 → 走「全新」问询（11 轮）。
**中途加入**：已有代码/仓库、无规范体系 → 走「中途」问询（7 轮；先探索：git status/log + 目录 + 已有规范）。
**存量完善**：已有文档体系（有 CLAUDE.md/README/docs）但**不规范、或想固化 AI 工作流/agents** → 走「存量完善」问询（4 轮 + 限制规则，见下）。

> 三种场景都先走「第 0 轮」；存量完善场景额外强制遵守下方限制规则。

### 跨平台强门禁（强制，v11.0，解决「skill 只保证 SKILL.md 被看到」）

> 🛑 **加载保证与现实**：skill 系统只保证 **`SKILL.md` 一定被当前 agent 看到**。详细的问询题库与场景执行流程已外置到 `references/场景/*.md` 三文件（Reasonix 会自动折叠进 body，DSH/Claude Code 等不保证）。**本 skill 不依赖任何平台的自动折叠**——以下规则对所有平台一视同仁。

**硬规则（violating the letter=violating the spirit，配借口令禁表）**：
1. **场景判断一旦确定是哪种场景，执行前必须先读对应 `references/场景/` 文件全文，再开始问询/执行**：
   - 全新 → `references/场景/全新-问询.md`（11 轮题库）
   - 中途 → `references/场景/中途-问询.md`（7 轮题库）
   - 存量 → `references/场景/存量-问询.md`（4 轮 + 限制规则 + 冲突消解 A/B/C 流程）
2. **未读对应文件全文 = 违规**：禁止只凭 SKILL.md 下方骨架直接问询/执行（骨架只是步数概览，不含具体题目与裁决规则）；读完后若上下文仍紧张，按场景内「记忆库/交接」纪律处理。
3. **同样适用其他非 SKILL.md 资源**：本 SKILL.md 任何地方提到 `references/*`、`templates/*`、`platforms/*`、`docs/CREATION-LOG.md` 等文件，凡涉及**产出/核对/内容判断**的动作前，都必须先读对应文件相应部分，不依赖记忆或推测。
4. **写/审/改 specs 五件套前必须先读 `references/五件套颗粒度标尺.md` 全文（v11.3，ISSUE-019）**：五件套的产出、审查核对、颗粒度判断，未读标尺 = 违规；项目内已有 `specs/_样板/`（样板固化机制，见「探索与产出」第 3 条）的，还须**先读样板全文再动笔**，收尾与样板逐节颗粒度比对。

| 借口（听起来合理，实为违规） | 现实 |
|---|---|
| "这个场景我问过很多遍，不用再读" | 每次执行前都必须读对应 references 文件全文，题库可能已迭代 |
| "SKILL.md 里骨架已经很清楚了，直接开问" | 骨架只是步数概览；真正题目/限制/裁决规则在 references 文件里 |
| "Reasonix 会自动折叠，我在 body 里已经看到了" | 本门禁对所有平台一视同仁；即便 auto-fold 生效也要按规则确认已读全文 |
| "中途场景和全新大部分一样，看全新那份就行" | 平台适配不同，**必须读本场景自己的那份** references 文件 |
| "模板结构都对，直接开写五件套" | 结构对 ≠ 颗粒度对；标尺 + 项目样板是「写多细」的唯一依据，未读就写按简略返工（v11.3 第 4 条） |

**红线**：上述借口任一个出现 → 停下读对应 references 文件全文再继续。

> **覆盖范围与兜底（v11.0；v11.4 修正一处平台结论）**：本门禁的约束对象 = **已加载 SKILL.md 的调用路径**（skill 入口、或继承了父上下文的子代理，如 DSH `subagent_fork`、Reasonix `-c/--resume`）。对于**后台派发、不继承父上下文的裸子代理**（Reasonix `task`/`subagent`、DSH `subagent`、**DSH `workflow`**——v11.4 对照 DSH 0.2.0-rc.2 源码更正：workflow 的 `agent()` 默认走 `provider: spawn` 且不传 seed，**不继承**父会话上下文，详见 `platforms/dsh/adaptation.md` 2b 表），SKILL.md 文字对它不可见——此时由**生成的 `agents/<role>.md` 里的「跨平台兜底：子代理上下文」条目**（模板 06）保底：强制入场先 read 对应 `references/场景/<场景>-问询.md` 全文，凭残缺上下文现编题目、或流程被精简/题目缺失 → 停下上报父代理或提醒用户。档位明细见 `platforms/<平台>/adaptation.md`「2b 子代理上下文继承档位」。**本兜底不削弱上述硬规则，二者互为补充**：inherit 路径靠门禁、裸子代理路径靠 role 模板（**含 workflow——所以 workflow 脚本里每个 `agent()` 的 prompt 都必须自带 references 必读行**）。

### 存量完善问询（先探索 + 走第 0 轮后进入；谨慎为主）

> 🛑 **强制入口（跨平台强门禁）**：进入本场景问询前，**必须先读 `references/场景/存量-问询.md` 全文**——它包含限制规则 R1-R6、第 1-4 轮题库，以及与下方执行同源的「文档冲突消解与联动核查」完整流程。未读全文直接开问 = 违规。

**骨架（详细规则见 references/场景/存量-问询.md）**：
- **核心一句话**：本场景改已有文档必须谨慎——进度以用户口述为准、在途模块隔离不改、写操作需确认、范围逐项确认、只记录不重构。
- **限制规则**：R1 进度必须用户口述 / R2 在途模块隔离 / R3 工作区谨慎 / R4 写操作确认 / R5 范围逐项确认 / R6 改造边界（只记录不重构）。
- **第 1 轮**现状盘点（复用 M1/M2/M4/M5）→ **第 2 轮**差距诊断（对着目标规范清单逐项勾「有/没有/不规范」）→ **第 3 轮**固化意愿（要不要闭环工作流/agents）→ **第 4 轮**补齐方式（按缺口复用全新/中途对应轮，不全走 11 轮）。

> ⚠️ 以上只是步数概览，具体题目、限制与裁决规则必须读 references 文件全文。

### 存量完善执行：文档冲突消解与联动核查流程（补齐阶段前必读）

> 🛑 **强制入口（跨平台强门禁）**：本流程的完整版（阶段 0 工作流闭环核查 + 阶段 A 冲突消解 + 阶段 B 重复去重 + 阶段 C 索引核查）**在 `references/场景/存量-问询.md`「存量完善执行」段**。执行补齐与核查前必须先读该文件全文，禁止只凭此处骨架执行。

**骨架（详细步骤见 references/场景/存量-问询.md）**：
- **阶段 0** 工作流闭环核查：不只查文档，还查 agents/签署矩阵/记忆纪律/会话管理是否落地闭环。
- **阶段 A** 冲突消解（每份被改造文档）：差异诊断 → 冲突分类 + 裁决（模板 vs 项目实际=以实际为准；新旧文档=以用户口述/代码实测为准）→ 逐项用户确认。
- **阶段 B** 重复去重（跨文档）：重复扫描 → 唯一出处裁定 → 其余位置改为引用不复制。
- **阶段 C** 索引核查（收尾必做）：三层索引核对 + 链接检查 + 变更记录逐文档追加 + 变更记录方向核查（过渡态两档规整）。

### 全新项目问询（按序，每轮 3-5 题，问完一轮再下一轮）

> 🛑 **强制入口（跨平台强门禁）**：开始**全新项目问询**前，**必须先读 `references/场景/全新-问询.md` 全文**——它包含完整的 11 轮题库（A 技术栈 / G 知识面 / B 团队工作流 / C 记忆库 / D 编码规范 / git 上传 / E 文档 / F 其他 / H 会话上下文 / T 工具构建 / U 环境数据）+ 问询节奏（🔴 关键决策一次一个 + 每轮末尾备注填空）。未读全文直接问询 = 违规。

**骨架（详细题库见 references/场景/全新-问询.md）**：
- **第 1 轮 A** 项目与技术栈 → **第 2 轮 G** 知识面/学习目标 → **第 3 轮 B** 团队与工作流 → **第 4 轮 C** 记忆库边界 → **第 5 轮 D** 编码规范
- **第 6 轮 git** 上传规则（3 层）→ **第 7 轮 E** 文档习惯 → **第 8 轮 F** 其他（契约/合规/多仓）→ **第 9 轮 H** 会话上下文 → **第 10 轮 T** 工具构建 → **第 11 轮 U** 环境与数据治理
- **每轮末尾统一「本组备注（填空）」**；用户答不上来给推荐默认并标注「可改」。

> ⚠️ 以上只是 11 轮步数概览，**具体题目与裁决规则必须读 references 文件全文**：技术栈选项细分（A2-1b/c）、🔴 关键题（A0/A2/B1/B2/C1/GIT-1/F2/T1）各自一次一个、U 组答案映射等都在文件里。

### 中途加入问询（先探索：git status/log + 已有规范，再问）
> 🛑 **强制入口（跨平台强门禁）**：开始**中途加入问询**前，**必须先读 `references/场景/中途-问询.md` 全文**——它包含完整 7 轮 M 组题库 + 信息分层原则。未读全文直接问询 = 违规。

> **信息分层原则（中途/存量场景统一，完整版见 references/场景/中途-问询.md）**：**进度状态类信息 → 以用户口述为准**（项目进行到哪、哪个模块在途）；**技术事实类信息 → 以代码实测为准**（版本/结构/能否编译/文档是否过时）。两类权威来源不混用。

**骨架（详细题库见 references/场景/中途-问询.md）**：
- **第 1 轮**现状 → **第 2 轮** git 与上传 → **第 3 轮** 记忆库 → **第 4 轮** 工作流与规范 → **第 5 轮** 文档与协作 → **第 6 轮** 会话上下文 → **第 7 轮** 工具与环境（中途版）
- 每轮末尾备注填空；涉及全新 B 组概念（M16b/M16c）时按全新对应轮次补问。

> ⚠️ 以上只是 7 轮步数概览，**具体题目与裁决规则必须读 references 文件全文**：信息分层原则、🔴 M2/M5a 关键题、M16b 复用全新 B9~B12 等都在文件里。

### 探索与产出
1. **探索**：读 manifest + 目录 + 入口；**实测构建/测试/运行命令**（必须真实跑一遍，不许猜）；按 U10 做环境预检。
2. **逐文档产出**：按附录 C 的模板文件，**先问对应引导题 → 按答案写 → 用户确认 → 下一份**。顺序：README → `<入口规范文件>`（主导平台映射定名，见「平台入口规范文件」节；**其余非主导平台各生成一行薄入口引用它**）→ memory 三件套（+logs + 模板 24 产出物 module-lifecycle-checklist.md）→ agents/（多 agent + 用户要详尽）→ .gitignore → docs/ → specs/ 示例 → file-templates（如有）。**每份产出收尾对照「产出物新建门禁总览」逐节核对**（缺失结构即返工）。
3. **三类产出模式**（模板双部分化的落地，v10.0 按产出模式分目录 `templates/一次性/`、`templates/多次-单文件/`、`templates/多次-含文件夹/`）：
   - **多次创建且含文件夹**（specs 五件套 17-21、agents 06、checklist 24）：skill 结束时在真实位置生成**特化模板文件夹**（如 `specs/module-XXX-示例/` 内含特化五件套骨架，`-示例` 后缀区分），后续 agent 新建模块 = **复制该文件夹改名**（如 `specs/module-005-xxx/`）再逐文件填写；特化模板文件夹登记进 file-index。
   - **五件套样板固化（v11.3，ISSUE-019：特化模板文件夹机制的落地升级）**：项目**首个模块五件套签署完成后**，自动复制一份到 `specs/_样板/<模块名>-样板/`（内容 = 按本项目技术栈特化的**完整五件套**，不是骨架）；后续每个新模块写五件套前**硬门禁：先读样板全文**，收尾与样板**逐节颗粒度比对**（对照 `references/五件套颗粒度标尺.md` 下限表），未对标 = 返工。`specs/_样板/` 登记进 file-index + `<入口规范文件>` 信息闭环图；含文件夹多次创建的其他产出（agents/ 等）同机制处理。跨技术栈对齐原理：样板 = 本项目栈的真实颗粒度（零脱敏、不离开项目），换工作区不失效——内嵌模板的脱敏骨架只作通用参考，样板才是主要对齐机制。
   - **多次创建但不含文件夹**（logs 每日 05、handoff 交接 25）：skill 结束时放**单个特化模板文件**（如 `memory/logs/planner/YYYY-MM-DD.md`、`memory/handoff/交接文档-示例.md`），后续 agent **复制该文件**新建；注意 logs 按「跨天拆分强制规则」每日新建（模板 05）。
   - **只创建一次**（CLAUDE.md 01、docs 各文档 08-16、记忆库三件套 02-04、gitignore 07、file-templates/README 22、tools/README 23、DOCUMENT-INDEX 26）：特化即正式文件；**产出时标注「下次修改注意事项」**——更新式文档（改内容+变更记录+署名）vs 追加式文档（只追加不覆盖，memory/ 三件套），新项目阶段文件结构未定时尤其要写清后续怎么改。
4. **固化与交接**：全部确认后固化；告知维护规则（每模块更新记忆库、末尾自检、入场核对、**模块收尾工具提炼检查按 T6 答案**）；提醒先跑通一个模块再修订；会话交接按 H3/H4 约定（memory/handoff/，看完删或改名归档）。

## 强制规则

- **问不透不写**：每个规范文件必须基于对应问询答案产出，不许拿 PTB-IMP 模板直接套；用户答不上来给默认并标注"可改"
- 构建/测试命令必须**实测**，写错构建命令比不写更糟
- 规范贴合实际代码，**不编造**代码里不存在的约定
- 先骨架后固化：第一版够用，跑通一个模块再修订
- 只搭体系，**不写业务代码**；不保存密钥/敏感信息/内网地址
- **生成期异常处理**：生成文档/规范过程中发现与代码实测或用户答案**不符**（如问询答案与代码现状矛盾、模板结构与项目实际冲突）→ **停下来向用户报告**（现象/依据/建议），不硬套模板继续生成；用户裁决后再继续（借鉴 executing-plans「计划有误 → 停止报告」模式）
- **模板对齐唯一出处原则（v10.0，反馈：对齐 lead 颗粒度时多处维护只留一处）**：同一规范若在多处维护（如签署矩阵在 CLAUDE.md/checklist/agents、动作标签在 C 区/activity-log/logs）→ **只保留一处（唯一出处），其余位置自引用 + 一句话简介**，禁双份维护漂移；对齐 lead 样板（module-004 等）时同样适用——模板内嵌示例只示范结构，不复制成双份规范。
- **模板对齐 lead 颗粒度原则（v10.0，反馈：多次迭代无法对齐 lead）**：specs/agents 等「多次创建」模板的详细规格以 **lead 实际产出**（如 module-004 五件套）为颗粒度基准——子任务必须行号级引用 + 现状→修法→理由、验收必须可执行不猜、测试必须环境归因；产出时若明显短于基准（如 plan <5KB）说明写简了，对照模板示例段逐节补。
- **五件套证据密度（v11.3，ISSUE-019 module-018 颗粒度教训）**：写五件套前**必读 `references/五件套颗粒度标尺.md`**（跨平台强门禁第 4 条）+ 项目 `specs/_样板/`（如有）；每条事实性内容（现状/盘点/计数/行号/权限点）必须有**实测锚**（`文件:行号` / grep 计数 / DDL 引用），**行号与计数写前必须实测确认**——禁止照抄别处 plan 的行号、禁止依赖弱模型产出未经核验（幻实行号实证：菜单项数 29→实为 28、权限码名写反、角色数 10 误写 8）；无证据的行不许写——**证据写满了，详细是副产品**。Reviewer 收尾抽查盘点/Gap 表行号与磁盘一致。
  - **借口自查**：

  | 借口 | 现实 |
  |------|------|
  | 「项目简单，不用写这么细」 | 下限是可核对门禁；简单模块走结构 B 但证据密度不降（缩减下限项须显式说明理由） |
  | 「行号大概对就行，写完再核」 | 幻实行号误导后续所有环节（审查/测试按行号定位落空）；写前实测 + Reviewer 抽查 |
  | 「参照上一个模块的 plan 抄就行」 | 旧模块行号/计数对本模块大概率失效；照抄 = 把幻实写进新 plan |
- **plan 结构以模板为准（v10.1，perm-004 未按子任务拆分教训）**：新模块 plan 结构按模板 17「必填章节核对表」执行（结构 A=复杂模块 §2 模块拆分独立成节 / 结构 B=简单模块可精简但必写理由），**不就近参考同专项旧模块结构**（旧模块可能偏离模板，如 perm-003 的「需求+技术方案主题分区」即结构 B 未说明的变体）；产出后跑「自检四查」（结构核对最优先）。
- **plan 零改动声明须 grep 验证（v10.2，perm-004 SecurityConfig 教训）**：plan 写「某文件零改动/不动」前，必须先实际 grep/读该文件确认既有约束（URL 级权限、注解、拦截器、前端角色白名单等）不会挡本模块——防「计划假设与代码现实冲突」（实例：声称 SecurityConfig 零改动，但既有 URL 级权限锁死目标接口，开发中途被迫改）。
- **plan 新增声明须反查（v10.12，perm-007 双身份建表教训）**：plan/任务清单声明「新建表 / 加字段」前，必须用**目标真实表名/列名**精确 grep **全部**迁移与实体（`sql/V<编号>__*.sql` 全量 V01~当前，**勿只查部分区间**）+ `SHOW COLUMNS`/实体定义核对，确认**确实未建**才写「从零新建」；已建则写「复用/改造（引用迁移号）」——与上一条「零改动须 grep」（perm-004）方向互补：声称不动要查，**声称新建更要反查**。防「误判已建为未建 → 任务清单/plan 写从零建表」（实例：perm-007 只 grep V31~V41 漏 V32，且用 `main_subject` 而非目标表名 `subject_association` 精确查，误判未建）
  - **借口自查**：

  | 借口 | 现实 |
  |------|------|
  | 「这个表肯定没建过，直接建」 | 声明新建前必须用目标真实表名/列名精确 grep 全量迁移（V01~当前）+ 实体核对；已建就写复用 |
  | 「查过几个迁移文件没看到，应该没有」 | 只查部分区间不算查；漏区间的既有建表（如 V32）会被误判为未建 |
- **权限白名单三处对齐（v11.3，ISSUE-029 module-020 教训；升级 v10.2「双处对齐」）**：新增角色 / 放开权限的改动，必须**全量盘点三处**——①URL 级（SecurityConfig/网关路由权限）②**Service/Controller 层角色矩阵**（`RoleEnum.X` / `"ROLE".equals(role)` 等白名单判断，按目标角色**全量 grep**）③前端路由/菜单白名单——逐条判定「**操作者放行**（并入新角色）」vs「**target 侧防御**（如禁封管理员的判断，不能并入，保持不变）」，形成盘点矩阵写进 plan §3；只改 URL 级 + 前端 = 菜单开了、后端 Service 层仍 403/空数据（模块级 Blocking，实测 ~30 文件 60+ 处漏并）。模板 17 §3「权限白名单三处对齐」+ 模板 18 对应验收项联动。
  - **借口自查**：

  | 借口 | 现实 |
  |------|------|
  | 「SecurityConfig 和前端都改了，应该通了」 | 权限校验分散三处；Service 层矩阵不并入 = 接口 403/空数据 |
  | 「grep 到的判断看着都一样，一起放行」 | 逐条分「操作者放行」vs「target 防御」；防御类判断并入新角色 = 越权漏洞 |
- **审查修复必须同步 acceptance（v10.12，ISSUE-004 perm-007 教训）**：Reviewer 审查发现问题并**修代码**后，必须**同步核对 acceptance-criteria.md 的对应验收项**——权限点、返回语义等描述更新为与最终实现一致再签 PASS。**Reviewer 签字 = 验收标准已与最终实现逐条一致**，不允许「代码已改、acceptance 还是旧描述」的脱节（Tester 阶段才发现补改 = 违规）。
  - **借口自查**：

  | 借口 | 现实 |
  |------|------|
  | 「修了代码，验收标准等 Tester 阶段再补」 | 审查修复后必须立即同步 acceptance，Tester 才发现=违规 |
  | 「acceptance 写得差不多，不用逐条对」 | Reviewer 签字=验收标准与最终实现逐条一致，须逐条核对并同步 |
- **Developer 自测通过后必须触发独立审查（v11.3，ISSUE-020 module-019 教训）**：Developer 自测（构建/单测全绿）**不等于流程完成**——必须触发**独立 Reviewer 审查**（平台子代理/review 工具，见 `platforms/<平台>/adaptation.md` 能力映射；裸子代理 prompt 必含 references 必读行）产 review-report，才能进入测试阶段（模板 24 阶段 3→4 gate 强制）。自审发现不了自己的盲点（实证：自测全绿后独立审查仍抓出 2 阻塞 + 5 建议）。
  - **借口自查**：

  | 借口 | 现实 |
  |------|------|
  | 「自测全绿没问题，不用审了」 | 自测 ≠ 独立审查；开发者盲点只有独立 agent 能抓（ISSUE-020 实证 7 项） |
  | 「小改动直接进测试吧」 | 阶段 3→4 gate 无豁免条款；跳审查 = 违规， Tester 阶段拦截后仍要退回重走 |
- **测试账号/步骤基于代码权限矩阵确定（v11.3，ISSUE-022 module-019 教训）**：输出测试步骤（人工测试手册节 / acceptance 验证命令）前，先 grep **前端权限判断**（`v-if`/路由守卫/菜单显隐）+ **后端角色过滤**（URL 级/Service 层/注解），确认「哪些账号能看见并访问目标功能」，**按矩阵选账号**——不凭「admin 肯定能用」经验假设（实证：用平台管理员测「仅企业管理员可见」的按钮，用户找不到按钮白跑一轮测试）。
- **根因分析先做最小对比验证（v11.3，ISSUE-023 module-019 教训）**：遇到「A 有 bug、B 没有」时，**先 diff A 与 B 的实现差异**（找一个不报错/不乱码的参照物对比）再定位根因——不凭第一个假设连修多轮（实证：文件名乱码凭「中文导致」假设修 3 轮，对比参照物一轮定位）。与模板 21 §4b 系统化调试纪律配套执行。
- **DDL 设计前确认数据库类型与版本（v11.3，ISSUE-024 module-019 教训）**：涉库模块开工前用 `SELECT VERSION()`（或等效方式）实测共享库/目标库是 MySQL / MariaDB / 其他，并记入 plan——方言差异（如 MariaDB 不支持 `CAST(... AS JSON)`、JSON 类型是 LONGTEXT 别名）在 DDL 设计时确认，不要等共享库执行报错才发现。模板 24 阶段 0 联动。
- **工具依赖方向为硬规则**：项目代码禁止引用 tools/；固化工具必须通过「删除演练」（删工具后项目照常编译）才允许
  - **借口自查**：

  | 借口 | 现实 |
  |------|------|
  | 「临时脚本不算工具」 | 复用 ≥2 场景就要固化，固化就要过删除演练 |
  | 「就 import 一个工具类，没事」 | 项目 → 工具引用禁止，删工具后编译即断 |
  | 「delete 后项目还能跑，不用演练」 | 删除演练是固化前置，结论记入 tools/README 复用记录 |

- **数据库写操作（DDL/DML/测试数据清理）先展示 SQL 获用户确认再执行**（按 U12 答案；默认需确认）
  - **借口自查**：

  | 借口 | 现实 |
  |------|------|
  | 「这条 SQL 很简单，直接跑」 | DDL/DML/测试数据清理都要先展示 SQL 获确认（U12 默认） |
  | 「用户之前已经同意过了」 | 每次写操作独立确认，不默认沿用 |
  | 「这是恢复基线不是改数据」 | DELETE 也属于写操作，需确认 |
- **模块收尾执行工具与方法提炼检查**（按 T6 答案）：回看 logs + 临时脚本 + tools/ 顺手度 + 问题→解法模式；无产出也要在 logs 记一行检查记录
- **工具构建语言按 T7 答案**：与项目主语言一致，或先检测本机环境后选其他语言；**临时工具无论用什么语言构建都守规范**（依赖方向 / 删除演练 / 含凭据本地保留）
- **临时文件用完即删**（记忆纪律第 7 条）；固化工具前先确认复用场景 ≥2 个
- **文档修改后必填变更记录**（头部有维护声明的文档）：追加 `日期时间|内容|署名` 一行；改完检查引用联动（file-index / 文档索引 / 模板索引）
- **DOCUMENT-INDEX 机器维护**：docs/DOCUMENT-INDEX.md 只能由 AI 添加/修改条目，人类成员需变更时**转述给 AI 改**（禁止人工直接编辑）；新增文档/模板后立即追加条目 + 变更记录
- **人工测试手册节必产（v10.12，ISSUE-005 perm-004/007 教训）**：**每个模块完成前必须在「模块改动与人工测试手册」（模板 14）产出本模块节**（含改了什么页面/涉及代码/人工测试步骤含预期/涉及账号数据/测试数据前置），随收尾四查①强制 gate；不允许「模块验收通过但手册没节」，等到用户实测才发现。
  - **借口自查**：

  | 借口 | 现实 |
  |------|------|
  | 「手册节等用户问再补」 | 模块完成前必产手册节（收尾四查① gate），commit 前置；用户实测才发现=违规 |
  | 「测试通过就不用写手册步骤」 | 人工测试手册是「commit 前置=用户人工测试通过」的依据，节必产 |
- commit/push 需用户明确允许，不主动执行

---

## 附录 A：多 Agent 角色模板（简化版，源自本项目 agents/*.md）

> 用户选多 agent 分工时生成各角色 `agents/<role>.md`；单人+agent 可不建，职责并入 CLAUDE.md 工作流章节。

通用骨架：`## 1.角色定位 / ## 2.核心职责 / ## 3.输出物 / ## 4.工作流程 / ## 5.检查清单`（完整见 templates/多次-含文件夹/06-agents-role.md）

| 角色 | 是否要 | 引导提问 | 职责要点 |
|------|--------|----------|----------|
| Planner | 多 agent 协作/需求拆模块时 | 需要独立 Planner？模块上限 200？ | 需求澄清→拆解→plan+acceptance→维护上下文 |
| Developer | 基本都要（即使单人） | 自测到什么程度？changelog 格式？ | 按 plan 实现→自测→changelog→交接 |
| Reviewer | 多人/高质量时 | 审查重点？轮次上限 3？ | 对照清单审查→review-report→退回/通过 |
| Tester | 质量要求高/要交差时 | 覆盖率 80%？要真实冒烟？ | 按验收写用例→单测/集成/回归→冒烟→test-report |

## 附录 B：规范文件骨架与引导提问（精简版，完整见 templates/）

> 模板分两类：**多次创建文件**（specs/logs 等）模板第二部分含详细规格+示例，可复制生成示例文件；**一次性文档**（CLAUDE.md/docs/README）模板示例写在开头、填写区追加。**CLAUDE.md 模板（01）最详细**——skill 只运行一次，后续开发都从 CLAUDE.md 入手；01 提供 **Java/Web、C++ 后端、嵌入式三方向示例片段**（按 A 组选栈取用）。**所有一次性文档模板均含：头部维护声明 + 末尾变更记录表（`YYYY-MM-DD HH:mm | 内容 | 署名`）**（文档维护规则）。

| 文件 | 骨架 | 引导提问 |
|------|------|----------|
| `<入口规范文件>`（默认 CLAUDE.md） | 见 templates/一次性/01-claude-md.md | D 组 + B 组（含 B9~B12）+ U10 + 平台主导问询 |
| memory 三件套 | 见 templates/一次性/02~04 | C 组 |
| logs | 见 templates/多次-单文件/05 | C3 |
| docs/ 各文档 | 见 templates/一次性/08~16 | E 组 + F 组 |
| specs 五件套 | 见 templates/多次-含文件夹/17~21 | B6 + E8（基准=module-004 样板） |
| file-templates/README | 见 templates/一次性/22 | F4 |
| tools/README | 见 templates/一次性/23 | T 组 |
| 模块生命周期流程树 | 见 templates/多次-含文件夹/24 | B 组（验收门槛）+ 每模块全程执行 |
| 交接文档 | 见 templates/多次-单文件/25 | H3/H4/H4b |
| DOCUMENT-INDEX | 见 templates/一次性/26 | E 组（文档习惯） |

## 附录 C：文档生成内容参考

> 完整章节递归（含 ###/#### 与每节内容说明）见技能目录 `templates/*.md`，运行时按需读取对应模板再生成。**模板只供结构参考，内容按问询答案特化，禁止照抄本项目内容。** 所有模板均双部分化：第一部分章节递归（结构一览），第二部分详细规格（最小标题「写什么/格式/示例」，示例取 PTB-IMP 项目文件脱敏化）。

### 模板产出模式总表（v10.0，templates/ 按模式分目录）

| 产出模式 | 目录 | 模板 | 使用方式（skill 结束后） |
|----------|------|------|--------------------------|
| **只创建一次**（特化即正式文件；更新式改内容+变更记录+署名 / 追加式只加不改） | `templates/一次性/` | 01-04 / 07-16 / 22 / 23 / 26 / **27~34** | skill 特化即正式文件；产出时标注「下次修改注意事项」（新项目文件结构未定时尤其重要）；**27~31 为可装配规范模块（27 中文排版 / 28 commit / 29 PR / 30 git worktrees / 31 并行 agent 调度），按「规范装配问询」决定产出独立文件或并入入口文件；30/31 默认关**；**32 AI协作规范 / 33 编码规范 为 v11.4 从模板 01 外移（按量裁决，默认开）**。**34 已知坑为「多次-含文件夹」类，不在此列** |
| **多次创建-不含文件夹**（复制单模板文件新建） | `templates/多次-单文件/` | 05（logs 每日）、25（handoff 交接） | skill 放特化模板文件（如 `memory/logs/planner/YYYY-MM-DD.md`），复制新建；logs 按跨天拆分规则每日新建 |
| **多次创建-含文件夹**（复制整个特化模板文件夹新建） | `templates/多次-含文件夹/` | 06（agents）、17-21（specs 五件套）、24（checklist 固化） | skill 在真实位置生成 `-示例` 特化模板文件夹（如 `specs/module-XXX-示例/`），复制改名新建 |

| 模板文件 | 产出文档 | 何时用 | 章节要点 |
|----------|----------|--------|----------|
| 01-claude-md.md | `<入口规范文件>`（默认 CLAUDE.md） | 必产 | **最详细模板**：A 区项目身份（简介/开发模式/技术栈/常用命令+环境速查/架构按语言栈/入口表/角色/文档索引引用式/纪律红线）+ B 区硬规范 15 项（命名/分层/注释/异常/日志/长度口径/安全/状态码/版本/提交格式/测试/静态检查/依赖/超时重试，统一骨架四段+on-off 标注）+ C 区 agent 速查（记忆纪律+动作标签 20 语义+签署矩阵唯一出处）+ D 区低频引用（24/25/26）；头部产出红线 7 条（双受众三因素/on-off/语言生成）；**三方向示例：Java/Web、C++ 后端、嵌入式**；**映射定名 + 薄入口见「平台入口规范文件」节** |
| 02-project-context.md | memory/project-context.md | 必产 | 概述/技术栈/团队/用户画像/模块清单/ADR/迭代状态/待办/注意事项/历史教训/更新日志 |
| 03-file-index.md | memory/file-index.md | 必产 | 使用说明/规范文件/模板/记忆库/模块产出/ADR/源码/测试/DDL/查找指南 |
| 04-activity-log.md | memory/agent-activity-log.md | 必产 | 活动单表/动作标签（完整表 20 个唯一出处 = `<AI协作规范文件>`）/异常记录 |
| 05-logs-day.md | memory/logs/<角色>/<日期>.md | C3=启用 | 四表（活动记录/异常事件/交接记录/今日统计）+ 可选叙述节（本日工作/关键技术决策/待办移交）——多次创建，skill 结束时生成示例文件；动作标签见 `<AI协作规范文件>` |
| 06-agents-role.md | agents/<角色>.md | 多 agent | 8 节：定位/职责/输入输出（引用 specs 模板）/约束/上报与状态（何时停下+状态词+上报格式）/协作协议（交接契约+冲突循环引用）/流程/四角色完整自检清单 |
| 07-gitignore.md | .gitignore | 必产 | 编译产物/依赖/密钥/工具/临时/内部文档 + 锁文件不忽略 |
| 08-readme.md | README.md | E3=要 | 简介/技术栈/快速开始/目录结构/账号 |
| 09-功能说明.md | docs/功能说明.md | E1 选 | 概述/角色/功能模块/流程/非功能需求 |
| 10-功能模块设计.md | docs/功能模块设计文档.md | E1 选 | 概述/模块设计(功能+API)/关键流程/权限/异常/性能/安全 |
| 11-人话版说明.md | docs/功能说明-人话版.md | E1 选/交差 | 一句话/角色/关系/每人功能/场景串流程/易懵点 |
| 12-数据库设计.md | docs/数据库设计文档.md | E1 选 | 概述/每表(建表SQL+字段+索引)/关系图/枚举字典 |
| 13-演进任务清单.md | docs/演进任务清单.md | E1 选 | 状态图例/分层规划(0-4层)/技术债务/变更记录 |
| 14-测试手册.md | docs/模块改动与人工测试手册.md | E1 选 | 通用准备(账号+测试前查库确认数据范围)/每模块 4 段扩展版(改了什么页面/涉及代码/人工测试步骤含预期/涉及账号数据) |
| 15-部署文档.md | docs/部署文档.md | E1 选 | 环境/构建产物/打包/部署/配置密钥/启动测试/**已知坑（含固定解法：现象/根因/解法）**/排查；嵌入式项目补烧录/串口/交叉编译提示 |
| 16-分工文档.md | docs/后端功能模块分工文档.md | 多人协作 | 总览/依赖/详细分工/阶段/联调/接口维护/合并规范/风险 |
| 17-spec-plan.md | specs/module-XXX/plan.md | 每模块 | 7 节：0 Agent配置(含审查要点+拆解理由)/1 需求描述(含关键约束不变量)/2 模块拆分(子任务七要素，行号级引用)/3 技术方案(全量实证盘点+改动点汇总)/4 验收/5 风险(含具体应对)/6 变更/7 审批 |
| 18-spec-acceptance.md | specs/module-XXX/acceptance-criteria.md | 每模块 | 0 环境前置(SQL/种子/返回信封/语义)/1 功能 checkbox 清单/2 非功能(安全+代码质量)/3 验证命令表(命令+预期)/4 签署(含实测记录/清理/遗留) |
| 19-spec-changelog.md | specs/module-XXX/changelog.md | 每模块 | 模块信息/变更概述/文件变更列表/设计决策(决策+原因)/自测结果/技术债务登记/变更记录 |
| 20-spec-review.md | specs/module-XXX/review-report.md | 审查后 | 结论先行/问题分级(阻塞+建议，含根因与修复示例)/验收标准逐条核对表/架构/安全/ADR/检查清单/实测验证记录 |
| 21-spec-test.md | specs/module-XXX/test-report.md | 测试后 | 概览/覆盖率/验收逐条核对/失败详情(**环境性失败归因**)/真实冒烟(强制前置含清理记录)/**5.5 测试发现备注(超验收范围行为)**/结论签署 |
| 22-file-templates-readme.md | file-templates/README.md | F4=有 | 命名规范/通用版式/模板明细/导出列格式/存放位置/需求来源 |
| 23-tools-readme.md | tools/README.md（开发工具说明） | T1=有 | 判定标准(≥2 场景复用)/工具列表(用途/用法/参数/输出/依赖/用户确认/复用记录)/分类/安全说明(含凭据本地保留)/**依赖方向与可删除性(删除演练结论)**/**使用注意（固定解法沉淀处 + 构建语言 T7）**/复用记录表 |
| 24-module-lifecycle-flow.md | memory/project/module-lifecycle-checklist.md（产出物） | 每模块全程 | 阶段 0-6 流程树（各阶段看什么/产什么/记忆库写什么；阶段 4 含人工测试反馈闭环、阶段 5 两前置+**集成选项菜单（B4 多分支：合并/推送/保留用户决定）+合并后验证**、**阶段 6 含 v11.4「文档影响清点」**）+ **中断恢复协议 RECOVERY**（R1 恢复三问（含**丢弃确认**）/R2 交接缺失重建/R3 上下文失真/R4 各阶段入口引用）；签署责任矩阵与防遗忘机制（**5 条**）**唯一出处 = `<AI协作规范文件>`**（本文件只引用）；**收尾四查明细唯一出处 = 本文件阶段 5**；流程层语言无关、命令层三方向示例（Java/Web、C++ 后端、嵌入式） |
| 25-handoff-document.md | memory/handoff/<模块>-交接文档.md | 开新会话/跨阶段交接 | §0 **一句话状态（标准化：状态符号+进展+第一动作，与 02 §6 一致）**/§1 **文档签署状态清单（必填表：版本/已签状态/还欠谁/接手动作）**/§2 已同步记忆库要点/§3 下会话必做清单/§4 环境数据现状/§5 遗留风险——防换会话丢失签署状态 |
| 26-document-index.md | docs/DOCUMENT-INDEX.md | 必产 | 机器维护声明（只能 AI 改、人转述 AI 改）+ 索引全部规范/模板/文档（不索引代码，代码索引在 CLAUDE.md）；与 file-index 并存分工（file-index=agent 记忆库、本文档=人+AI 导航） |
| 27-中文排版规范.md | `docs/中文排版规范.md`（可装配，并入时归模板 33） | 装配 27 选要 | 空格/标点/数字/术语（首次中英对照+避免过度翻译）/代码格式/写作检查清单——见 SKILL.md「规范装配问询」；来源 superpowers-zh chinese-documentation |
| 28-commit规范.md | `docs/commit规范.md`（可装配，并入时归模板 33） | 装配 28 选要/自定义 | Conventional Commits 中文版（格式+类型表+好坏示例）+ 分支命名规范 + 合并规范；含「有自定义 commit 规范先结合优化再告知」——见 SKILL.md「规范装配问询」；来源 ISSUE-011 |
| 29-PR规范.md | `docs/PR规范.md`（可装配） | 装配 29=要走 PR | 提 PR 纪律（模板必填/搜重复/真人痕迹/单主题不批量）+ 提 PR 清单 + 审他人 PR（验收=实现）+ PR 模板接续——见 SKILL.md「规范装配问询」；来源 ISSUE-012 |
| 30-git-worktrees规范.md | `docs/git工作区规范.md`（可装配，默认关） | 装配 30=要并行工作区 | 适用场景/概念/worktree 创建与管理/并行隔离纪律/与 BL-02 衔接——见 SKILL.md「规范装配问询」；来源 backlog BL-01 |
| 31-并行agent调度.md | `docs/并行agent调度规范.md`（可装配，默认关） | 装配 31=要多 subagent 并行 | 术语与平台能力/何时并行/调度纪律（只读 vs 写、冲突域）/聚合收尾/与 BL-01 衔接——见 SKILL.md「规范装配问询」；来源 backlog BL-02；**并行场景下 `docs/已知坑/` 的编号由主 agent 统一分配（防撞号）** |
| 32-AI协作规范.md | `docs/AI协作规范.md`（可装配；少则并入 `<入口规范文件>`） | v11.4 默认随入口文件产出 | 记忆库纪律（触发/末尾自检**四步**/入场核对/临时文件/动作标签表 20 个/借口表+红线）+ 签署责任矩阵（**★ 唯一出处**）+ 防遗忘机制（**5 条**）+ 收尾四查指向模板 24 阶段 5 + §4「与入口文件的关系」（入口只留摘要行，硬禁止复制表格）——见 SKILL.md「规范文件占位符」节 |
| 33-编码规范.md | `docs/编码规范.md`（可装配；少则并入 `<入口规范文件>`） | v11.4 默认随入口文件产出 | 通用 8 项（命名/分层/注释/异常/日志/代码长度/版本/测试）+ 按需 5 项（安全/状态码/静态检查/依赖/超时重试，各带 on/off）+ B18/B23 只留引用行指向模板 28/27 |
| 34-已知坑.md | `docs/已知坑/`（`README.md` + `_模板.md` + `NNNN-*.md`） | **默认必建**（入口路由表指向它） | 唯一出处：索引 `README.md`（三条限定语 + 规则速查表 + 坑索引表，1–3 KB，豁免变更记录表）+ 单篇六节（现象/排查过程/根因/固定解法/**如何验证已规避**/提炼规则）；**新建单篇必须同时补 README 两张表**；准入三判据（隐蔽/系统性/重犯代价高）；写入门禁=模板 24 阶段 6 收尾回看 |

## 输出清单

- README.md（E3）· `<入口规范文件>`（映射定名 + 非主导平台薄入口）· **`<AI协作规范文件>`（模板 32，或并入入口文件）** · **`docs/编码规范.md`（模板 33，或并入入口文件）** · **`docs/已知坑/`（模板 34，必建：README + `_模板.md`）** · memory 三件套（+logs）· **memory/project/module-lifecycle-checklist.md（模板 24 产出）** · agents/（多 agent + 用户要详尽才建）· .gitignore
- docs/DOCUMENT-INDEX.md（必产）· docs/（按 E1 多选）· specs/ 目录+module-001 示例（B6/E8）· file-templates/README（F4）· tools/README（T1=有）

## 收尾（结束语四段式）

完成后按以下四段收尾，**不是一句总结就结束**：

1. **总结**：按哪些问询答案特化了哪些文件（一句话清单）。
2. **怎么开始用**：告诉使用者「下一步做什么」——
   - 先跑通一个模块（从 module-001 开始，走完 plan→编码→审查→测试→验收 全流程）
   - 过程中随时回来调整规范（规范是讨论稿，不是铁律）
   - 每个模块结束会触发「收尾回看」（工具/方法/踩坑归纳：**会再犯的坑进 `docs/已知坑/`**，工具进 tools/，方法进记忆库）
3. **日常协作提醒**：新会话入场要读记忆库三件套 + git 核对；commit 需你允许；写库要你确认（按问询定下的纪律）。
4. **求助路径**：任何时候想调整规范/加模板/改流程，直接对 agent 说「用 new-project-init 迭代」即可。

## 版本与变更记录

> 完整历史见 `docs/CREATION-LOG.md`（v3 → v8.0）；此处只留当前版本 + 最近摘要。

> 📌 **存量规整（v10.5）**：本版本表按「文档维护规则第 9 条」尾插规整——原 v10.4→v9.0 倒序重排为 v9.0→v10.4 正序（历史行未删改）；此后新行追加底部。
| 版本 | 日期 | 变更内容 |
|------|------|----------|
| v9.0 | 2026-08-15 | ①frontmatter `description` 精简为纯触发条件（防 agent 跳正文，借鉴 superpowers SDO 发现优化）；②记忆纪律/文档维护/工具依赖硬规则/数据库写操作四处补「借口\|现实」表 + 红线（形式匹配失败类型）；③问询轻重分级：Q0-1/A0/A2 主选/B1/B2/C1/GIT-1/F2/T1/M2/M5a 共 11 项 🔴 一次一个（带推荐+权衡），其余 🟡 批量（带默认+一键全默认）；④中途/存量强化：信息分层原则（进度口述 vs 技术实测）、存量 R6 改造边界（只记录不重构）、强制规则补生成期异常处理（不符即停报告）、文档维护规则补增量标注（变更记录行内标注性质，仅持续文档）；⑤存量完善新增「文档冲突消解与联动核查流程」A/B/C 三阶段（差异诊断/唯一出处去重/三层索引核查 + 入场核对联动）；⑥版本历史拆至 CREATION-LOG.md（新增）；⑦新增「Skill 简介与致谢」节（核心原则/迭代路径 + 致谢 obra/superpowers 与 jnMetaCode/superpowers-zh）；⑧模板批量强化：06 上报机制+四角色自检清单+交接契约+冲突循环引用、17 禁止占位符黑名单+产出后自检三查、19 Developer 四维自审清单、24 集成选项菜单+丢弃确认+合并后验证、25 §0 状态标准化、01 C23 记忆纪律借口表+指令优先级、02 §6 状态符号表+§2 死引用修正、15 CI/CD 可选节（U13 断链修复）、12 敏感字段标注；⑨新增 `testing/` 四个验证走查（全新/中途/存量/模板）——源自 superpowers-zh 设计学习 + 存量完善实际痛点（文档冲突/重复漂移/索引断链），2026-08-14~15 多轮讨论逐条批准 | Reasonix（skill 迭代） |
| v10.0 | 2026-08-15 | ①模板目录按产出模式分 3 子目录（一次性/多次-单文件/多次-含文件夹）+ 头部产出模式标注 ②全 26 模板逐个过：C 组（17-21 五件套+06 agents）内嵌 module-004/agents 脱敏 lead 示例段（17 子任务七要素示范、18 环境前置示范、06 日期纪律），A 组 01 新增 A8b「信息闭环图」节（虚线=按问询可选节点，人+AI 可读）+ C24 签署矩阵补「追加 vs 更新」区分+签署必带日期，B 组（05 跨天拆分强制规则、25 handoff 日期纪律）③存量完善新增「阶段 0 工作流闭环核查」（反馈：文档还行但工作流不闭环）④三类产出模式放置规则明确（含文件夹→特化模板文件夹复制新建/不含文件夹→单模板文件/一次性→标注下次修改注意事项）⑤强制规则补「模板对齐唯一出处原则」+「对齐 lead 颗粒度原则」⑥新增「设计思想速览（全版本）」节（历史 v1-v9 + v10.0 新增共 14 条，使用者先读）——源自 PTB-IMP 存量完善/perm-004 实战反馈（5 条 + 2 mid-turn），2026-08-15 多轮讨论逐条批准 | Reasonix（skill 迭代） |
| v10.1 | 2026-08-15 | ①模板 17 结构强约束：第一部分改「必填章节核对表」（§0-§7 每节必填/选填 + 结构 A/B 二选一：A=复杂模块 §2 模块拆分独立成节[默认]，B=简单模块可精简但必写理由；不就近参考旧模块结构）；产出后自检三查→四查（+0 结构核对最优先）②模板 18-21 各补「产出后核对」提示 ③强制规则补「plan 结构以模板为准」④设计思想速览补作者标注（warm-flame-core + github/gitee 链接）⑤新增根目录 README.md（仿 superpowers-zh：定位/规模/是什么/目录/使用/致谢/许可证 MIT）——perm-004 未按子任务拆分教训（用户 2026-08-15 指出） | warm-flame-core（skill 迭代） |
| v10.2 | 2026-08-15 | ①模板 17 §1 加「不变量合法性检查」（声称零改动文件须先 grep 既有约束：URL 级权限/注解/拦截器/角色白名单）+ §3.2 加「存储宽度约束检查」（新增枚举值/编码前查存储长度约束，语言无关+on/off）+ §3.3 加「权限白名单双处对齐」（后端权限调整同步核对前端路由/菜单 roles）②模板 18 §3 加「字段名/计数实测」（验证命令字段名/计数对照实际数据模型实测）③强制规则补「plan 零改动声明须 grep 验证」——perm-004 三踩坑（SecurityConfig 锁死目标接口/岗位码超列宽静默截断/前端 roles 拦已放开后端），2026-08-15 逐条讨论批准 | Reasonix（skill 迭代） |
| v10.3 | 2026-08-15 | ①文档维护规则新增第 9 条「变更记录方向两类分法」（读最近类=顶部插最新[CLAUDE.md/docs/演进清单/project-context 更新日志/模板自身变更记录] / 读演进类=底部追加[specs 五件套变更记录/logs 当天] / 禁按日期插表格中间 / 存量旧行不重排 / 豁免无变更记录表文档）——防「表格内时间乱序」（曾现「两头新中间旧」）②冲突消解阶段 C 新增第 11 项「变更记录方向核查」（乱序提示用户是否重排，不默认动）③迭代大前提第 3 条措辞对齐（模板自身变更记录=顶部插最新）+ 第 4 条显式引用 testing/ 四走查（可见即可选，解决「不知道有这东西」）④目录用途认知表加 testing/ 行⑤22 个模板头部补「📍 变更记录方向」标注（A 类顶部 14 / B 类底部 8）+ 变更记录区插 v10.3 行⑥02 最后更新字段同步规则（与更新日志最新一行同步）⑦README 扩写为详细版（效果对比/核心特性/三场景表/FAQ/作者头像 GitHub）+ 新建 LICENSE（MIT，消除 `[MIT](LICENSE)` 死链接）⑧CREATION-LOG 补 v10.2 行（v10.2 迭代漏同步修复）——源自用户 2026-08-15 讨论（日期混乱/追加位置/README 太简/创作者标注/两次「读完全了吗」纠错），多轮讨论批准 | Reasonix（skill 迭代） |
| v10.4 | 2026-08-15 | ①**skill 自身过渡态修复**：22 个模板自身变更记录区重排为时间倒序（最新在顶，消除 v10.3 遗留的「顶部最新+旧行正序」过渡态；只调行序不改内容；修复脚本 range 越界 bug）②文档维护规则第 9 条补「**存量规整**」两档机制（解决存量完善「旧行不好动+新行新规矩」的过渡态）：档 1 逐文档（阶段 C 展示过渡态现状→确认→重排+规整标记行）/ 档 2 全查全规整（激进，保留但说明为什么不推荐：违反逐项确认/误伤在途/工作量大出错高/只产生可读性价值）；只调行序不删改任何行；**规整标记行**格式 `存量规整：按第 9 条方向重排（原 N 行未删改）`（给未来读者看懂时间线）；不适用追加式文档/无变更记录表文档③冲突消解阶段 C 第 11 项扩充（展示过渡态→两档选择→不确认保留原样）——源自用户 2026-08-15 讨论（过渡态展示/存量完善帮用户规整好/激进用户需求），讨论批准 | Reasonix（skill 迭代） |
| v10.5 | 2026-08-15 | ①文档维护规则第 9 条重写：v10.3「读最近/读演进」二分法 →「纯 AI=头插（记录区放文档头部+新行插顶）/ 有人看=尾插（记录区放文档尾部+新行追加底）」——用户 2026-08-15 定案（纯 AI 省 token / 人看美观）②第 9 条附 26 模板+主文件分类表逐一指定（头插 6：02/03/04/05/24/25；尾插其余 20 + SKILL.md/README/CREATION-LOG）③补「署名/签字不要求时间排序」（只看经手/过目，与变更记录时间排序解耦）+「模板迭代记录=产出文档变更记录写法的示例」④同步迭代大前提第 3 条 + 冲突消解阶段 C 第 11 项旧术语 | Reasonix（skill 迭代） |
| v10.6 | 2026-08-15 | ①定位重述：以**存量完善**为核心场景（优化已有项目文档/规范、固化 AI 协作工作流），新建脚手架为补充——frontmatter description/「定位」/「这是什么」/适合谁/设计思想三场景顺序全部重排为「存量完善→中途→全新」②README 同步重述定位（中文定位句+英文摘要）+ 三场景表/快速开始/核心特性顺序调整 ③补录 CREATION-LOG v10.5 行（漏同步修复）——发布至 GitHub 前用户反馈「市面上完善多 agent 的 skill 已很多，应主打存量完善差异化」 | warm-flame-core（skill 迭代） |
| v10.7 | 2026-08-16 | ①**DSH 深度适配（跨平台通用）**：新增「平台适配」节 + `references/dsh-adaptation.md`（DSH 能力映射：多 agent 角色→`subagent`/`subagent_fork`/`workflow`、问询→`ask_user_question`、命令实测→`pwsh`、审批纪律与 DSH approval 对齐、产出物 CLAUDE.md 保持原名跨平台、入场核对注意 DSH 不自动读 CLAUDE.md）②frontmatter 补 `whenToUse`（DSH 支持的调用提示字段，其他平台忽略）③README 补 DSH 使用说明 + 变更记录表（README 原缺变更记录表，一并补齐）④安装指引：`$DSH_HOME/cordis.patch.yml` 配 `skill-filesystem.customSkillDirs` 指向本仓库（宿主层，TUI 等 profile）+ `$DSH_HOME/skills/` junction 指向仓库（preset 层，GUI 生效）——用户要求「深度适配 DSH 同时保证其他平台可用」 | DSH 适配（agent） |
| v10.8 | 2026-08-16 | ①**打包为 DSH 插件（npm 包）**：新增 `package.json`（`dsh.bundle` → `cordis.patch.yml`）+ `lib/index.js`（skill provider：把包根目录 `SKILL.md` 注册进 `ctx.skills` host 层，rank 550，resourceBase=包根，`templates/` 等相对引用正常解析）+ `cordis.patch.yml`（插入 `new-project-init` 行）；安装三方式：`dsh plugin --profile web add new-project-init`（npm）/ `dsh plugin --profile web add github:warm-flame-core/new-project-init`（GitHub）/ 本地文件夹 ②README 安装节改「插件安装 + 本地文件安装」双方式，新增「其他平台的使用方式」跨平台表（Claude Code 技能目录等）③`references/dsh-adaptation.md` 安装与发现补插件安装段 —— 用户要求「像其他 DSH 仓库一样提供 npm/GitHub 安装，同时给出其他平台可用方式」 | DSH 适配（agent） |
| v10.9 | 2026-08-16 | ①**Reasonix 深度适配（跨平台通用）**：新增 `references/reasonix-adaptation.md`（Reasonix 能力映射全文：多 agent 角色→原生 `task`/`review`/`wait`/`explore` 工具、子代理→`reasonix subagent`、常驻纪律→项目 `AGENTS.md`、安装→`~/.reasonix/skills/` junction 或 `reasonix.toml` `[skills] paths`（本机 `%APPDATA%\reasonix\config.toml`）、社区发布→reasonix.io/skills 网页表单填仓库 URL）②平台适配节补 Reasonix bullet + 标题补 v10.9 ③README 新增「Reasonix 适配」节 + 跨平台表补 Reasonix 行 + Reasonix 徽章 ④CREATION-LOG 同步 —— 用户要求「适配 Reasonix 并在其社区发布，介绍文档同步更新」 | DSH 适配（agent） |
| v10.10 | 2026-08-17 | ①**仓库布局重组（跨平台规整）**：references/ 按平台拆分 → `platforms/<平台>/`（reasonix/adaptation.md、dsh/adaptation.md、dsh/cordis.patch.yml）；CREATION-LOG.md → docs/；新增 AGENTS.md（开发者入口）②**私密文件加密**：ISSUES.md/ROADMAP.md/DEVELOPER.md → `_private/`（明文 .gitignore 排除、*.enc AES-GCM 密文入库，scripts/secret.ps1）③**npm 停止维护**：发布改为 GitHub 唯一渠道，README npm 安装删除线标注 ④单仓库化（dev 私有仓退役为备份）⑤**logs 四表必填门禁（ISSUE-001）**：记忆库写入纪律第 4 条 + logs 细档记录形式补「新建强制步骤（读模板→复制结构→逐表追加→收尾比对）+ 借口令禁表」，模板 05 同步补新建强制步骤——修 agents 写日志未按模板四表/缺头部声明——用户要求「平台适配按平台名分目录规整、私密文件不公开、双仓库太麻烦」+ ISSUE-001 | warm-flame-core（skill 迭代） |
| v10.11 | 2026-08-17 | **全量体检 + 产出物门禁总览（superpowers-writing-skills 方法论, ISSUE-002）**：①SKILL.md 新增「产出物新建门禁总览」节——通用规则 5 条 + 产出物→模板→必核结构全表（**13 类产出物**：CLAUDE.md/memory 三件套/logs/agents/gitignore/README/docs/specs 五件套/file-templates/tools/checklist/handoff/DOCUMENT-INDEX）+ 通用借口令禁表（5 行，含「把模板挪过去就算建好」「文档简单不套模板」两高发借口）②「探索与产出」第 2 条、「文档维护规则」第 1 条接引门禁核对 ③testing/模板走查加 3b、存量走查加第 6 节「产出物新建门禁核对」（存量完善为重点场景）④RED-GREEN 实测：独立子代理复测确认强制指令可执行、13 类产出物全覆盖、行号一致——修 ISSUE-002（除 logs 外全部产出物缺新建门禁，存量完善补建文档最易暴露）——用 superpowers-writing-skills 对 skill 全量体检 | warm-flame-core（skill 迭代） |
| v10.12 | 2026-08-17 | **iterate ISSUE-003~007 一批合并（perm-007 实战暴露的 5 个流程漏洞）**：①**plan 新增声明须反查（ISSUE-003）**：SKILL.md 强制规则补「声明新建表/加字段前用目标真实表名/列名精确 grep 全量迁移 V01~当前 + SHOW COLUMNS/实体核对，确未建才从零新建」+ 借口表；模板 17 §3 补 3.1b ②**审查修复必须同步 acceptance（ISSUE-004）**：SKILL.md 强制规则补 + 模板 20 §3「验收标准=最终实现」③**人工测试手册节必产（ISSUE-005）**：SKILL.md 强制规则补 + 模板 24 收尾四查① ④**保留冒烟数据影响人工测试（ISSUE-006）**：模板 14 补「测试数据前置/需清理项」+ 模板 24 冒烟影响检查 ⑤**acceptance 预列单测清单（ISSUE-007）**：模板 18 §1 补「单测清单预列」 ⑥ISSUE-003~007 全部关闭（各模板变更记录与本表同步 v10.12）——2026-08-17 一次处理一批、合并升一个版本 | warm-flame-core（skill 迭代） |
| v11.0 | 2026-08-17 | **骨架化 + 强门禁 + 一批迭代（ISSUE-008~014 + backlog BL-01~05）**：①**骨架化 + 跨平台强门禁**：三场景问询外置 `references/场景/*.md`（完整题库），SKILL.md 改骨架 + 「跨平台强门禁」节（硬规则 3 条 + 借口表 4 行 + 红线「借口出现→停下读对应 references 全文再继续」）②**平台入口规范文件（ISSUE-013）**：新增「平台入口规范文件」节（映射表 + 问询 + 生成逻辑：正文唯一 + 非主导平台薄入口引用；产出物名/模板用 `<入口规范文件>` 占位，docs/specs/memory 不映射）③**规范装配问询**：新增「规范装配问询」节（问询驱动不建重框架；27/28/29 + 30/31 可装配模块逐个问）④**新增模板 27~29**：中文排版规范（ISSUE-010）/ commit 规范（ISSUE-011）/ PR 规范（ISSUE-012），均可装配、产出独立文件或并入 01 ⑤**四段式署名（ISSUE-008）**：SKILL.md 文档维护规则第 2/6 条改四段式 实体人-平台-角色@分支 + 时间精度分级表（HH:mm/日期/文件名），模板署名逐文件改 ⑥**排版规范（ISSUE-010）**：文档维护规则补第 10 条 + 产出物门禁通用规则第 6 条 ⑦**BL-03/04/05**：模板 21 加 §4b 系统化调试纪律、模板 20 加 §7b 对外 PR/§7c 收审查反馈/中文审查输出开关 ⑧**BL-01/02 → 模板 30/31**（git worktrees 并行工作区 / 并行 agent 调度，可装配默认关，附录 C/产出物门禁/装配问询登记，模板数 29→31）⑨**平台适配迭代判据（ISSUE-014）**：AGENTS.md 平台适配开发节补三判据（日常迭代免实测/新增平台必实测/平台机制变需复核），SKILL.md/README 同步 ⑩模板 01 补 B23 中文排版精要 + D 区引用模板 27、B18 改 Conventional Commits 中文版——2026-08-17 一批合并，全部不加密不发布待审阅 | Reasonix（skill 迭代） |
| v11.1 | 2026-08-19 | **补录 Codex 平台适配（v11.1）+ 上架计划准备（ISSUE-015 起，日期取系统当天 08-19）**：①**补录 Codex 适配**（git 已提交 platforms/codex/adaptation.md + README/SKILL 同步，此前版本表漏记此行，本次补录）：新增 `platforms/codex/adaptation.md`（Codex 能力映射全文：多 agent 角色→spawn_agent/send_input/wait_agent、问询→equest_user_input（`equest` 系文档乱码，实际为 `request_user_input`）、命令实测→shell_command、审批→sandbox_permissions/equire_escalated（同乱码，应为 require_escalated））+ SKILL.md 平台适配节 + README「Codex 适配」节 ②**上架计划准备（ISSUE-015，仅本机本次做）**：编写 `_private/上架-00~04`（上架执行计划书 DSH 交接 + awesome-dsh-plugin 条目 + 描述文案 + DSH 实测验证清单 + 测试记录模板），ISSUES.md 追加 ISSUE-015（恢复 npm 安装渠道并上架 awesome-dsh-plugin）——**不加密不发布**（npm 恢复/DSH 实测/上架 PR 由 DSH 按计划书 decrypt 后独立执行），本次只落盘 _private + 版本记录 | Reasonix（skill 迭代） |
| v11.2 | 2026-08-19 | **DSH 完全适配复核 + npm 恢复发布 + 插件市场上架（ISSUE-015 由 DSH 执行）**：①**DSH 适配复核**（对照本地官方 deepseek-harness 源码/文档）：`lib/index.js` 与 `@deepseek-ai/dsh-skill` 提供方协议一致（registerProvider 同步工厂 {signal,invalidate}、list/get 返回字段、rank/locator/path/resourceBase/invocation/source/provider）；8 项能力映射核对通过（ask_user_question / subagent·subagent_fork·workflow·goal / approval: ask / customSkillDirs / dsh plugin add / rank 100-550 / profile·$DSH_HOME），命令实测工具名补注（官方通用 `bash`、DSH Desktop 实际 `pwsh`）②**DSH 实测**：`$DSH_HOME/skills/new-project-init` junction 重建指向本仓库（原指向 F:\Software\deepseek-harness\Skill 的死链已清理），watcher 补发现后技能目录渲染出 new-project-init；references/场景/ 三文件、templates/ 31 模板、testing/ 四走查齐备；workspace 外写操作授权机制实测有效 ③**npm 恢复**：README/SKILL/adaptation/AGENTS 四处删除线清除恢复 npm 命令（`dsh plugin --profile web add new-project-init`），package.json 1.0.1→1.1.0 并发布 ④**GitHub 发布**：加 `dsh-plugin` topic + push ⑤**awesome-dsh-plugin 上架 PR**：data/plugins/warm-flame-core__new-project-init.yml + `node scripts/generate-readme.mjs` 重新生成 README——复核/实测/发布记录见 `_private/上架-04` | warm-flame-core-DSH-Developer@main |
| v11.3 | 2026-09-12 | **五件套颗粒度机制 + 流程 gate 一批（ISSUE-019~026/028~032，module-019/020 实战复盘）+ ZCode 平台适配（三判据②需实测，本平台执行）**：①**五件套颗粒度四层机制（ISSUE-019）**：新增 `references/五件套颗粒度标尺.md`（颗粒度下限表·中档按复杂度上浮 / BDD 场景类型覆盖清单 / 脱敏实例节选 / 30 硬验收加粗词表跨栈替换）+ 跨平台强门禁补第 4 条「写五件套前必读标尺」（+借口行）+「探索与产出」升级**五件套样板固化**（首模块五件套签署后复制 `specs/_样板/<模块名>-样板/`，后续模块先读样板再写、收尾逐节对标）+ 强制规则新增「五件套证据密度」（每条事实须实测锚、行号写前实测禁照抄，+借口表）+ 模板 17~21 各引标尺 + 产出物门禁五件套行补核对项 ②**流程 gate 一批**：ISSUE-020 自测后必须独立审查（强制规则+借口表+模板 24 阶段 2/4 gate）、ISSUE-021 多角色 logs 补写（记忆纪律第 4 条+模板 05）、ISSUE-022 测试账号基于代码权限矩阵（强制规则+模板 14）、ISSUE-023 根因先最小对比验证（强制规则+模板 21 §4b）、ISSUE-024 DDL 前实测数据库类型（强制规则+模板 24 阶段 0）、ISSUE-025 BDD 场景类型覆盖清单含「已有数据→修改→重传」（模板 17 §1+标尺+模板 24 阶段 0）、ISSUE-026 环境预检补工具链版本与项目要求一致性（全新 U10+中途 U-M4） ③**权限白名单三处对齐（ISSUE-029）**：模板 17 §3 双处→三处（URL 级+Service/Controller 层矩阵+前端白名单）+ 盘点矩阵（操作者放行 vs target 防御）+ 模板 18 验收项 + 强制规则+借口表；原记录「模板 01 有该规则」经核实不存在、不改 01（守唯一出处） ④**028/030 平台已知坑**：受控环境「验证+写状态」命令拦截绕过决策路径 + 精确替换「唯一上下文锚」技巧——按平台归属下沉各平台 adaptation.md（zcode 新建含 zcode 版；reasonix 收 ISSUE-028 真实案例 `cmd /c` 子进程隔离；dsh 补通用指引），SKILL.md 不加平台特定内容 ⑤**ZCode 平台适配**：新增 `platforms/zcode/adaptation.md`（加载与调用/能力映射表/2b 子代理上下文档位/产出物定位/安装与发现/受控环境执行已知坑/维护说明）+ 新增 `.zcode-plugin/plugin.json` + SKILL.md/README/AGENTS 登记 + package.json 1.1.0→1.2.0；本会话最小实测（AskUserQuestion 问询 / Agent 子代理 / references 读取 / Edit old_string 唯一性报错）+ `~/.agents/skills/`（多工具共享根）junction 发现验证（ZCode 无任意路径技能根字段，`.zcode` 专属根会遮蔽 `.agents`，同技能二选一）⑥**收尾**：.gitignore `_private/*` 全忽略+密文豁免（ISSUE-032：原 `*.md` 规则挡不住子目录明文）；testing 模板/全新走查补条目；ISSUES.md 019~031 关闭、027 标注项目侧落地、018 留 backlog、032 当场关闭 | warm-flame-core-ZCode-Developer@main |
| v11.4 | 2026-09-30 | **入口规范文件瘦身（常驻 vs 按需）+ 防遗忘机制 + DSH 适配复核 + WorkBuddy 适配**：①**入口文件=常驻区**设计原则确立：只放「无论做什么都要遵守 / 都要知道去哪找」，其余按需加载；配供给侧（拆分判据）与需求侧（一个事实只有一个家）两条依据 + **体量门禁 ≤10 KB**（红线⑧，依据各平台自动注入上限：Codex 32 KiB / Claude Code 40k 字符 / DSH 64 KiB；v11.4 内依据端到端实测由 8 KB 放宽，见本行⑬）②**新增「动作 → 必须更新」表（触发侧门禁）**：以事件为键，专治「事情做了、文档忘了」——新增工具/依赖/命令/接口/权限点/表字段/目录、踩坑、引入新规范各有对应必须更新的文档 ③**新增「规范索引」路由表**：按需加载成立的前提（AI 不会读它不知道存在的文件），列出每份规范 + **什么时候必须读** ④**模板 01 重写**（398→287 行）：C 区（记忆纪律/动作标签/借口表/签署矩阵/防遗忘）外移 **模板 32 `docs/AI协作规范.md`**；B 区 15 项减 B18/B23 外移 **模板 33 `docs/编码规范.md`**；环境速查与踩坑落点收敛为 **模板 34 `docs/已知坑/`**（README 索引+规则速查 / 单篇 NNNN-*.md / _模板.md）；A6+A7 合并；信息闭环图 5→3 条主闭环；产出红线 7→8 条 ⑤**防遗忘三处联动**：入口「动作 → 必须更新」表 + 记忆库写入纪律第 2 条自检升级**三步→四步（新增动作回看）** + 模板 24 阶段 6 新增**「文档影响清点」**；另加**遗漏型借口自查表**（专治无自觉的遗漏）⑥**口径裁决**：「防遗忘机制」统一为 **5 条**（原模板 24 只列 3 条，是 5 条真子集）；记忆自检统一为四步；「收尾四查」明细唯一出处收敛为模板 24 阶段 5；动作标签 19 行 20 个计数口径澄清 ⑦**唯一出处随迁**：全仓「CLAUDE.md C 区」引用改指 `<AI协作规范文件>`（新增占位符，附「规范文件占位符」节）；模板 15/23 的踩坑节收敛为「只写特有项 + 引用 docs/已知坑/」⑧**DSH 适配复核（对照 0.2.0-rc.2 源码）**：修正 2b 表 workflow 行事实错误（默认 spawn **不继承**，原文误写「继承」）、安装段去硬编码版本号、`customSkillDirs` 段落重写（patch 整段替换 config / `~/.agents/skills` 为官方约定根 rank 500 / 两 junction 重复挂载警示）、补 `--profile` 语义警示；`lib/index.js` frontmatter 加固（支持块标量 + 官方 invocation 键，并修复 CRLF 下解析为空）⑨**新增 WorkBuddy 平台适配**（`platforms/workbuddy/adaptation.md`，逐项标注【实测】/【推断】/【待实测】+ 8 条待实测清单；按三判据②待会话级实测）⑩同步：SKILL.md 门禁总览 +3 行、装配问询 +3 行、附录 C +3 行、分类表/输出清单/目录用途；README（DSH 安装语义 + WorkBuddy 节 + 计数 + 3 条核心特性）；AGENTS.md（tag/Release 流程 + 去写死路径）；package.json 1.2.0→1.3.0（补 workbuddy keyword）；testing 走查 +2 组 ⑪**工具**：`publish.ps1` 第 6 项 npm 包内容断言；`secret.ps1` 增量加密（默认跳过已最新的 `.enc`，新增 `-Force`）⑫**发布**：回溯补齐 tag `v1.0.0`~`v1.2.0` + 4 个 Release（约定 tag 跟 npm 版本号）⑬**体量门禁复核（v11.4 内）**：硬门禁 **≤8 KB → ≤10 KB**（保留 >8 KB 预警）——端到端实例化实测：最小 Go 项目生成物落在 **8.0–8.7 KB**，8 KB 属脆门禁；10 KB 仍比最紧平台上限（Codex 32 KiB）小 3.2 倍。同批修：模板 01 外层围栏改 4 反引号（修 GitHub 渲染）、附录与 ★7 去重⑭**仓库机制**：私密密文迁独立 **`vault` 分支**（`main` 整目录忽略 `_private/`；`secret.ps1` 加 `-OutDir`；`publish.ps1` 6→7 项含 vault 无明文检查；发布＝推 main + vault） | warm-flame-core-DSH-Developer@main |