MNICKZ Docs-Driven Workflow
文档先行的 AI 协作纪律：改前声明范围，改后必须留痕，按需脚手架新项目或整理文件夹。提炼自两个项目实测过的 AGENTS.md 规则。
本 skill 只有 SKILL.md 这一个文件，不允许有任何附属文件夹或模板文件。 初始化模式需要的六个文件模板全部内嵌在下方「初始化模式」小节里，直接用当前环境提供的文件写入能力按模板内容建文件，不依赖外部骨架目录。
强制规则（三种模式共用，不可跳过）
只要这次调用动过任何文件（代码/文档/资产），结束前必须在 CHANGELOG 追加一条记录。 没有 CHANGELOG 就先创建一个，用下面「初始化模式」里 CHANGELOG.md 模板的格式。
唯一例外：这次调用完全没有修改任何文件、纯讨论/纯方案，此时不写 CHANGELOG，但必须显式声明"本次未修改文件，仅提供方案"——不能什么都不说就结束。
留档不能事后补写——必须在同一轮对话内完成，不能"先改完代码，回头再补文档"。用户确认"这次改动完成了"但对应文档没有同步更新，这次任务本身就要按"未完成"处理，不能因为对话已经过去几轮就当作已经交代过去了。
文档里任何字段/占位符如果问不出来（用户没提供，也无法从对话推断），必须显式写成 TBD（原因：…），不能删掉整节，也不能编造内容顶替——空着的 TBD 是"需要去问"的信号，不是可以自由发挥的空白。
决策/方案被后续推翻时，旧记录不删除、不改写，标注"已被 {{日期}} 的新决策/新记录推翻，当前有效见……"，保留可追溯的完整历史，不能悄悄改写成好像从没犯过错。
| 借口 | 现实 |
|---|---|
| "改动太小，不值得记" | 可追溯性不看改动大小，看有没有改。一行也要记。 |
| "等任务全部做完再一起补" | 中途被打断或忘记，留痕就丢了。当场记，不拖到最后。 |
| "用户没要求写 changelog" | 这是本 skill 的强制规则，不需要用户每次重申。 |
| "用户已经说完成了/这轮对话快结束了" | 文档没同步，按规则就是没做完，需要主动说明或当场补上，不能揣着掖着。 |
三种模式
1. 初始化模式 — 脚手架新项目
触发：用户要新建一个应遵循文档驱动纪律的项目，或明确要求"初始化"。分两种场景：
1a. 全新项目（没有既存代码/历史决策）：
- 在目标项目目录下建立空目录：
docs/、src/、assets/design/、assets/bug/、assets/reference/、notes/、archive/（有 shell 的环境用mkdir -p一次性建好；没有的话在写文件时按路径带出目录即可）。 - 依次用当前环境的文件写入能力，把下面六个「文件模板」的内容写到对应路径（
AGENTS.md、README.md、CHANGELOG.md、TODO.md、docs/decision-log.md、docs/project-context.md），同时把其中{{占位符}}（项目身份、目录规范细节、禁止事项清单等）结合与用户的对话内容改成真实内容，不能留着{{...}}交给用户；问不出来的按【强制规则】标 TBD，不编造。项目专属的"禁止事项清单"尤其重要——不要套用其他项目的清单，问用户这个项目具体不能做什么。填AGENTS.md时，还要问用户这个项目会不会有需要 AI 生成或人工审核的素材（图片/图标/插画等）：会的话保留并填实"素材流水线规则"小节；不会的话把整节删掉，不要留占位骨架。 - 按【强制规则】写第一条 CHANGELOG：
项目初始化，创建 AGENTS.md / README.md / docs 骨架。
1b. 存量项目接入（项目已有代码/文档/历史决策，只是还没有这套骨架）：
- 步骤同 1a，六个模板照样建。
- 唯一区别在
docs/decision-log.md：不要把项目过去的历史决策强行倒推重写成 ADR 格式，那样容易编造细节。改成在文件开头加一张"历史决策存档索引"表（列"决策项 / 结论 / 完整记录"，"完整记录"指向项目原有的设计文档、README 或其他能找到依据的地方），并注明"自 {{接入日期}} 起，新决策统一用本文件下方的 ADR 格式记录"。历史决策模糊不清的，标 TBD，不替项目编历史。 - 按【强制规则】写第一条 CHANGELOG：
项目接入 docs-driven-workflow，创建 AGENTS.md / README.md / docs 骨架，decision-log.md 建历史决策索引。
文件模板：AGENTS.md
# AGENTS.md — 开发 AI 工作指南
本文件面向参与此项目的 AI 助手（Claude Code、Copilot、Cursor 等），说明工作区结构、开发规则与设计系统。
---
## 0. 项目边界与核心规则（Project Boundary Rules）
### Project Identity
This repository is only for **{{PROJECT_NAME}}**（{{PROJECT_NAME_CN}}）。
Do not use context from other projects unless the information exists inside this repository. 只读取、分析、修改当前工作区内的文件；不依赖聊天记忆或其他项目经验补设定。
### Source of Truth
> 列出本项目的唯一数据源 / 唯一显示系统 / 唯一权威文件等。例如："XXX.json 是唯一场景数据源，所有渲染/导出必须从它驱动"。
- {{...}}
### 修改前 / 修改后流程（强制）
每次改代码前，必须先输出：本次任务目标、将要读取的文件、将要修改的文件、不会触碰的文件、潜在风险。未经确认，不要大范围重写。
每次改完后，必须输出：修改文件列表、每个文件改了什么、是否删除 legacy 代码、是否更新 docs、构建是否通过、是否还有 known issues。同时更新 `CHANGELOG.md`（实际改动）与 `docs/decision-log.md`（架构决策，如涉及）。
### 禁止事项清单（项目自定义，必填）
> 列出本项目明确禁止 AI 做的事情（视觉风格 / 功能范围 / 技术选型等），不要留空。例如：
> - 改变整体配色 / Design Language
> - 新增未经确认的组件
> - {{...}}
---
## 1. 语言规则
{{回复语言规则，例如：所有回复、计划、说明文档均使用中文，技术术语保留英文原文。}}
---
## 2. 工作区结构
{{PROJECT_NAME}}/ ├── src/ # 所有源代码、配置文件 ├── docs/ # 正式文档：命名 YYYY-MM-DD_主题.md ├── assets/ │ ├── design/ # 效果图、UI 参考图 │ ├── bug/ # 测试报错截图 │ └── reference/ # 参考图、灵感收集 ├── notes/ # 开发笔记：踩坑记录、技术方案 ├── archive/ # 被替换/淘汰文件的归档（带日期或版本标记），不直接删除 ├── AGENTS.md # 本文件 ├── CHANGELOG.md # 实际改动记录（持续维护） ├── TODO.md # 待办事项（持续维护） └── README.md # 项目概览
---
## 3. 各文件夹用途
| 文件夹 | 存放内容 | 不应存放 |
|--------|----------|----------|
| `src/` | 所有源代码、配置文件、package.json 等 | 文档、截图、笔记 |
| `docs/` | PRD、需求文档、架构决策记录 | 代码、截图 |
| `assets/design/` | UI 效果图、设计稿、组件样式参考 | 代码、文档 |
| `assets/bug/` | 复现问题的截图、录屏、错误日志截图 | 代码、文档 |
| `assets/reference/` | 行业参考、灵感图、竞品截图 | 代码、文档 |
| `notes/` | 技术笔记、踩坑总结、调研结论 | 代码、正式文档 |
| `archive/` | 被替换/淘汰的旧文件（带日期或版本标记） | 仍在使用的当前文件 |
---
## 4. 开发规则
### 代码区规则（src/）
- `src/` 是唯一代码区，所有可执行文件、配置文件、依赖声明必须在此目录内。
- 新建代码文件前，先确认是否已有同功能模块可复用。
### 文档规则（docs/）
- 所有正式产品文档必须放入 `docs/`，命名格式：`YYYY-MM-DD_主题.md`。
- **留档不能事后补写**：改动完成的同一轮对话内必须完成留档；用户确认"改动已完成"但文档未同步更新，视为任务未完成。
| 改动类型 | 留档要求 |
|---|---|
| 常规代码/文档改动（不涉及架构） | 追加一条 `CHANGELOG.md` |
| 新建/修改类型定义、数据结构字段 | 在 `docs/decision-log.md` 追加或新建一条 ADR |
| 重大架构调整 | 新建 `docs/decision-log.md` 条目，并同步更新 `docs/project-context.md`；如果导致旧文档的实现细节不再可信，在 `project-context.md`「关联文档索引」顶部显式声明哪些文档已过期，不要求删除旧文档本身 |
| 新增/修改目录结构或命名规则 | 同步更新本文件 §2/§3 |
| 新增 AI 协作规则或开发规则 | 在本文件对应章节追加 |
### 素材规则（assets/）
- 三个子目录各司其职，不混用；文件名清晰描述内容，避免 `截图1.png`、`image.jpg` 这类无意义命名。
### 素材流水线规则（可选——项目有 AI 生成或需要人工审核的素材时启用，没有就删掉本节）
- 素材生产与运行时使用分离：草稿/生成区（draft/staging）→ 人工审核（review）→ 唯一的正式入库步骤（accept）。
- 草稿区/staging 区的文件**不允许**被代码直接引用。
- 只有一个脚本/步骤能写正式素材目录，且必须同步更新素材清单（manifest）文件；其余环节只读或只写 staging。
- 每次素材从草稿区移入正式目录，必须同步更新 manifest。
### 冲突处理
- 如果需求与 `docs/` 文档冲突，**停止执行并询问用户**，不得自行决定或猜测未写明的规范。
---
## 5. 产品规格概要
> 完整需求见 `docs/`。在此摘录 AI 工作时须随时知道的核心约束与决策。
- {{...}}
---
## 6. 给 AI 的协作提示
- 阅读 `docs/` 下的文档了解功能背景，再开始实现。
- 不确定需求时，先提问，不要自行假设并写入代码。
- 修改代码时，只改动与当前任务直接相关的部分，避免无关重构。
文件模板：README.md
# {{PROJECT_NAME}}
{{一句话产品描述}}
## 先读哪个文档
| 我想了解… | 看这个文件 |
|---|---|
| 项目当前架构、数据流、进度阶段（最新状态） | [docs/project-context.md](docs/project-context.md) |
| 作为 AI 助手参与开发的规则与工作区结构（强制边界见 §0） | [AGENTS.md](AGENTS.md) |
| 历史架构决策 / 实际改动记录 / 待办 | [docs/decision-log.md](docs/decision-log.md) · [CHANGELOG.md](CHANGELOG.md) · [TODO.md](TODO.md) |
## 快速开始
```bash
{{安装/启动命令}}
目录结构
src/ {{一句话说明}}
docs/ 设计决策、变更记录等文档
assets/ 设计参考素材（非运行时资产）
架构边界规则详见 AGENTS.md §0。
#### 文件模板：CHANGELOG.md
```markdown
# CHANGELOG
> 每次改动后追加一条记录，无论大小。格式：`YYYY-MM-DD — 做了什么（影响的文件/模块）`。不允许事后批量补写——改动完成的同一轮对话内必须记录。如果本次改动中顺手发现并修复了请求范围外的问题，单独写一行说明，不要混进主线描述里。
- {{YYYY-MM-DD}} — 项目初始化，创建 AGENTS.md / README.md / docs 骨架
文件模板：TODO.md
# TODO
> 开发过程中发现的待办、遗留问题，任务完成后同步更新。不想做/做不了的待办不要直接删掉，用下面的状态词标注原因。
**状态词汇表**（可选，用于标注"暂时不做"的原因，避免和"就是漏掉了"混淆）：
| 状态 | 含义 |
|---|---|
| 已知悉，不修 | 已经评估过，有明确理由不修，如实记录理由 |
| 待用户确认 | 需要人工实测或视觉判断，AI 无法自行决定 |
| 待排期 | 需要用户决定是否值得投入，不是技术阻塞 |
- [ ] {{待办项}}（可选：Blocked by {{原因}}）
文件模板：docs/decision-log.md
# 架构决策记录（Decision Log）
> 记录架构、类型定义、数据结构相关的重大决策，ADR 格式。改动完成的同一轮对话内必须补齐，不能事后补写。决策被后续新决策推翻时，旧条目不删除、不改写，在旧条目下补一行"已被 {{日期}} 条目推翻，当前有效见……"。
## {{YYYY-MM-DD}} — {{决策标题}}
**背景**：{{为什么需要这个决策}}
**决策**：{{结论}}
**影响**：{{受影响的文件/模块}}
**Affected files**：{{这条决策约束/影响的具体文件路径}}
文件模板：docs/project-context.md
# 项目上下文（持续维护）
> 当前架构、数据流、进度阶段的最新摘要，供 AI 快速上手时读取。每次架构性改动后同步更新本文件。
## 当前阶段
{{...}}
## 核心架构
{{...}}
## 已知问题
{{...}}
## 关联文档索引
> 列出项目里所有相关文档，标注状态，防止 AI 误信仓库里仍存在但已过期的设计文档。架构大重写后，在本节顶部补一句声明，例如"{{日期}} 起，不要参照 {{旧文档}} 的实现细节，仅供历史参考"。
| 文档 | 状态 |
|---|---|
| {{...}} | 有效 / 历史 / 持续维护 |
## 已确认决策（不得推翻，除非用户明确重新讨论）
| 决策项 | 结论 |
|---|---|
| {{...}} | {{...}} |
## 待定事项（遇到相关任务时必须先提示用户确认方向，不得自行假设）
| 待定项 | 现状 / 建议方向 |
|---|---|
| {{...}} | {{...}} |
2. 任务纪律模式（默认）
触发：在已有项目里改代码/改文档，且没有更具体的模式匹配。
动手前必须先完整读一遍项目
docs/目录（至少 README 导航表列出的每一份文档）和AGENTS.md，不能跳过文档直接开发；涉及产品需求、设计、架构、素材整理的任务尤其不能省略这一步。改动前输出声明：目标 / 将读取的文件 / 将修改的文件 / 不会触碰的文件 / 潜在风险。未经用户确认，不做大范围重写。
遇到需求与已有文档冲突 → 停下来问用户，不自行假设。
改完后输出结构化汇报：完成内容 / 修改与新增文件（每个改了什么，顺手发现并修复的范围外问题要单独列出，不要混进主线描述）/ 是否删除 legacy 代码 / 构建或测试是否通过 / 影响范围（这次改动波及哪些模块/页面/后续任务）/ 范围核对（改动前声明过的"不会触碰的文件"或计划里的某部分，事后发现不需要动/没有动，要说清楚，不能因为最终没做就当没声明过）/ 未完成内容与 known issues / 下一步建议。
任务过程中如果发现了范围外的改进机会，不要擅自实现，也不要只丢一句模糊的"建议以后做 X"——在汇报里列成并列的"提案菜单"（每条标注为什么现在不做、大致优先级），交给用户挑选。
按【强制规则】更新对应文档，触发条件：
改动类型 留档要求 常规代码/文档改动（不涉及架构） 追加一条 CHANGELOG.md新建/修改类型定义、数据结构字段 在 docs/decision-log.md追加或新建一条 ADR（背景/决策/影响/Affected files）重大架构调整 新建 docs/decision-log.md条目，并同步更新docs/project-context.md；旧文档因此不再可信的，在「关联文档索引」顶部显式声明，不要求删除旧文档新增/修改目录结构或命名规则 同步更新 AGENTS.md§2/§3新增 AI 协作规则或开发规则 在 AGENTS.md对应章节追加出现新的待办则同时更新
TODO.md；决策/方案被本次改动推翻的，按【强制规则】在旧记录上标注"已被推翻"，不删除不改写。
3. 整理模式 — 文件夹审计与重组
触发："整理一下文件夹""检查文件有没有放对地方"之类的请求。
- 找依据：项目自己
AGENTS.md里的目录用途表（如果有）；没有就用默认约定——src/代码、docs/正式文档（命名YYYY-MM-DD_主题.md）、assets/{design,bug,reference}素材分类、notes/非正式笔记、archive/被替换/淘汰文件的归档。 - 扫描并列出问题：放错目录的文件、无意义命名（如
截图1.png、image.jpg）、根目录堆积的临时文件、docs/里没被 README 导航表引用的孤儿文档。输出一份整理清单（问题 / 当前位置 / 建议操作 / 依据）。不要直接移动文件——移动/重命名是有一定破坏性的操作。 - 不删除已有目录结构或文件——哪怕看起来是空目录/没被引用，整理模式只负责"挪位置"，删除需要用户在清单确认时额外明确同意，不能顺手当成整理的一部分执行。需要替换/升级一个已有文件时，优先把旧版本移到
archive/目录（带日期或版本标记命名），而不是直接覆盖或删除，保留可回滚性。 - 用户确认清单后再执行：git 仓库优先
git mv（保留历史），否则普通移动/重命名。 - 按【强制规则】写 CHANGELOG，记录整理了什么、移动了哪些文件。
快速参考
| 用户说 | 触发模式 |
|---|---|
| "初始化一个新项目""搭个 AGENTS.md 骨架" | 初始化模式 |
| （日常改代码/改文档，无特别说明） | 任务纪律模式（默认） |
| "整理一下文件夹""这些文件放得对不对" | 整理模式 |
Common Mistakes
- 只在对话里口头总结改了什么，没有真的写进 CHANGELOG 文件——汇报和留痕是两件事，都要做。
- 整理模式擅自
mv/删除文件后才汇报——必须先出清单，用户确认后再动手。 - 把某个项目专属的"禁止事项"写死进这个通用 skill——那部分永远留给项目自己的
AGENTS.md，本 skill 只提供占位结构，内容按当次项目现填。 - 把骨架内容放进独立的模板文件/文件夹——这个 skill 不允许有
SKILL.md以外的任何文件或文件夹，所有模板内容必须内嵌在SKILL.md里。 - 整理模式或任务纪律模式里顺手删除了看起来没用的目录/文件——删除必须经用户额外明确同意，"反正是空的/没人用"不是删除的理由。
- 占位符问不出来就编个内容顶替，或者干脆删掉那一节——必须显式标 TBD，留一个"需要去问"的信号。
- 决策/方案被后续推翻后，直接删除或悄悄改写旧的 decision-log/change-log 条目——必须保留旧记录并标注"已被推翻"，历史要能追溯。