docs-driven-workflow

---
name: docs-driven-workflow
description: Use when starting or finishing any coding/editing task in a project that follows a documentation-first AI collaboration workflow — declare scope before editing, log every change afterward with a changelog entry, scaffold a brand-new project with this discipline (AGENTS.md/README/docs skeleton), or audit and reorganize a project's folder structure against its own documented conventions.（中文触发词：初始化新项目/搭 AGENTS.md 骨架、存量项目接入文档驱动规范、整理文件夹/文件归档、改动前声明范围、改动后写 CHANGELOG/留痕）
---

# Docs-Driven Workflow

文档先行的 AI 协作纪律：改前声明范围，改后必须留痕，按需脚手架新项目或整理文件夹。提炼自两个项目实测过的 AGENTS.md 规则。

**本 skill 只有 `SKILL.md` 这一个文件，不允许有任何附属文件夹或模板文件。** 初始化模式需要的六个文件模板全部内嵌在下方「初始化模式」小节里，直接用当前环境提供的文件写入能力按模板内容建文件，不依赖外部骨架目录。

## 强制规则（三种模式共用，不可跳过）

**只要这次调用动过任何文件（代码/文档/资产），结束前必须在 CHANGELOG 追加一条记录。** 没有 CHANGELOG 就先创建一个，用下面「初始化模式」里 `CHANGELOG.md` 模板的格式。

唯一例外：这次调用完全没有修改任何文件、纯讨论/纯方案，此时不写 CHANGELOG，但必须显式声明"本次未修改文件，仅提供方案"——不能什么都不说就结束。

**留档不能事后补写**——必须在同一轮对话内完成，不能"先改完代码，回头再补文档"。用户确认"这次改动完成了"但对应文档没有同步更新，这次任务本身就要按"未完成"处理，不能因为对话已经过去几轮就当作已经交代过去了。

**文档里任何字段/占位符如果问不出来**（用户没提供，也无法从对话推断），必须显式写成 `TBD（原因：…）`，不能删掉整节，也不能编造内容顶替——空着的 TBD 是"需要去问"的信号，不是可以自由发挥的空白。

**决策/方案被后续推翻时，旧记录不删除、不改写**，标注"已被 {{日期}} 的新决策/新记录推翻，当前有效见……"，保留可追溯的完整历史，不能悄悄改写成好像从没犯过错。

| 借口 | 现实 |
|---|---|
| "改动太小，不值得记" | 可追溯性不看改动大小，看有没有改。一行也要记。 |
| "等任务全部做完再一起补" | 中途被打断或忘记，留痕就丢了。当场记，不拖到最后。 |
| "用户没要求写 changelog" | 这是本 skill 的强制规则，不需要用户每次重申。 |
| "用户已经说完成了/这轮对话快结束了" | 文档没同步，按规则就是没做完，需要主动说明或当场补上，不能揣着掖着。 |

## 三种模式

### 1. 初始化模式 — 脚手架新项目

触发：用户要新建一个应遵循文档驱动纪律的项目，或明确要求"初始化"。分两种场景：

**1a. 全新项目**（没有既存代码/历史决策）：

1. 在目标项目目录下建立空目录：`docs/`、`src/`、`assets/design/`、`assets/bug/`、`assets/reference/`、`notes/`、`archive/`（有 shell 的环境用 `mkdir -p` 一次性建好；没有的话在写文件时按路径带出目录即可）。
2. 依次用当前环境的文件写入能力，把下面六个「文件模板」的内容写到对应路径（`AGENTS.md`、`README.md`、`CHANGELOG.md`、`TODO.md`、`docs/decision-log.md`、`docs/project-context.md`），同时把其中 `{{占位符}}`（项目身份、目录规范细节、禁止事项清单等）结合与用户的对话内容改成真实内容，不能留着 `{{...}}` 交给用户；问不出来的按【强制规则】标 TBD，不编造。项目专属的"禁止事项清单"尤其重要——不要套用其他项目的清单，问用户这个项目具体不能做什么。填 `AGENTS.md` 时，还要问用户这个项目会不会有需要 AI 生成或人工审核的素材（图片/图标/插画等）：会的话保留并填实"素材流水线规则"小节；不会的话把整节删掉，不要留占位骨架。
3. 按【强制规则】写第一条 CHANGELOG：`项目初始化，创建 AGENTS.md / README.md / docs 骨架`。

**1b. 存量项目接入**（项目已有代码/文档/历史决策，只是还没有这套骨架）：

1. 步骤同 1a，六个模板照样建。
2. 唯一区别在 `docs/decision-log.md`：不要把项目过去的历史决策强行倒推重写成 ADR 格式，那样容易编造细节。改成在文件开头加一张"历史决策存档索引"表（列"决策项 / 结论 / 完整记录"，"完整记录"指向项目原有的设计文档、README 或其他能找到依据的地方），并注明"自 {{接入日期}} 起，新决策统一用本文件下方的 ADR 格式记录"。历史决策模糊不清的，标 TBD，不替项目编历史。
3. 按【强制规则】写第一条 CHANGELOG：`项目接入 docs-driven-workflow，创建 AGENTS.md / README.md / docs 骨架，decision-log.md 建历史决策索引`。

#### 文件模板：AGENTS.md

```markdown
# 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

```markdown
# {{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](AGENTS.md)。
```

#### 文件模板：CHANGELOG.md

```markdown
# CHANGELOG

> 每次改动后追加一条记录，无论大小。格式：`YYYY-MM-DD — 做了什么（影响的文件/模块）`。不允许事后批量补写——改动完成的同一轮对话内必须记录。如果本次改动中顺手发现并修复了请求范围外的问题，单独写一行说明，不要混进主线描述里。

- {{YYYY-MM-DD}} — 项目初始化，创建 AGENTS.md / README.md / docs 骨架
```

#### 文件模板：TODO.md

```markdown
# TODO

> 开发过程中发现的待办、遗留问题，任务完成后同步更新。不想做/做不了的待办不要直接删掉，用下面的状态词标注原因。

**状态词汇表**（可选，用于标注"暂时不做"的原因，避免和"就是漏掉了"混淆）：

| 状态 | 含义 |
|---|---|
| 已知悉，不修 | 已经评估过，有明确理由不修，如实记录理由 |
| 待用户确认 | 需要人工实测或视觉判断，AI 无法自行决定 |
| 待排期 | 需要用户决定是否值得投入，不是技术阻塞 |

- [ ] {{待办项}}（可选：Blocked by {{原因}}）
```

#### 文件模板：docs/decision-log.md

```markdown
# 架构决策记录（Decision Log）

> 记录架构、类型定义、数据结构相关的重大决策，ADR 格式。改动完成的同一轮对话内必须补齐，不能事后补写。决策被后续新决策推翻时，旧条目不删除、不改写，在旧条目下补一行"已被 {{日期}} 条目推翻，当前有效见……"。

## {{YYYY-MM-DD}} — {{决策标题}}

**背景**：{{为什么需要这个决策}}

**决策**：{{结论}}

**影响**：{{受影响的文件/模块}}

**Affected files**：{{这条决策约束/影响的具体文件路径}}
```

#### 文件模板：docs/project-context.md

```markdown
# 项目上下文（持续维护）

> 当前架构、数据流、进度阶段的最新摘要，供 AI 快速上手时读取。每次架构性改动后同步更新本文件。

## 当前阶段

{{...}}

## 核心架构

{{...}}

## 已知问题

{{...}}

## 关联文档索引

> 列出项目里所有相关文档，标注状态，防止 AI 误信仓库里仍存在但已过期的设计文档。架构大重写后，在本节顶部补一句声明，例如"{{日期}} 起，不要参照 {{旧文档}} 的实现细节，仅供历史参考"。

| 文档 | 状态 |
|---|---|
| {{...}} | 有效 / 历史 / 持续维护 |

## 已确认决策（不得推翻，除非用户明确重新讨论）

| 决策项 | 结论 |
|---|---|
| {{...}} | {{...}} |

## 待定事项（遇到相关任务时必须先提示用户确认方向，不得自行假设）

| 待定项 | 现状 / 建议方向 |
|---|---|
| {{...}} | {{...}} |
```

### 2. 任务纪律模式（默认）

触发：在已有项目里改代码/改文档，且没有更具体的模式匹配。

1. 动手前必须先完整读一遍项目 `docs/` 目录（至少 README 导航表列出的每一份文档）和 `AGENTS.md`，不能跳过文档直接开发；涉及产品需求、设计、架构、素材整理的任务尤其不能省略这一步。
2. **改动前**输出声明：目标 / 将读取的文件 / 将修改的文件 / 不会触碰的文件 / 潜在风险。未经用户确认，不做大范围重写。
3. 遇到需求与已有文档冲突 → 停下来问用户，不自行假设。
4. **改完后**输出结构化汇报：完成内容 / 修改与新增文件（每个改了什么，**顺手发现并修复的范围外问题要单独列出**，不要混进主线描述）/ 是否删除 legacy 代码 / 构建或测试是否通过 / **影响范围**（这次改动波及哪些模块/页面/后续任务）/ **范围核对**（改动前声明过的"不会触碰的文件"或计划里的某部分，事后发现不需要动/没有动，要说清楚，不能因为最终没做就当没声明过）/ 未完成内容与 known issues / 下一步建议。
5. 任务过程中如果发现了范围外的改进机会，不要擅自实现，也不要只丢一句模糊的"建议以后做 X"——在汇报里列成并列的"提案菜单"（每条标注为什么现在不做、大致优先级），交给用户挑选。
6. 按【强制规则】更新对应文档，触发条件：

   | 改动类型 | 留档要求 |
   |---|---|
   | 常规代码/文档改动（不涉及架构） | 追加一条 `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. 整理模式 — 文件夹审计与重组

触发："整理一下文件夹""检查文件有没有放对地方"之类的请求。

1. 找依据：项目自己 `AGENTS.md` 里的目录用途表（如果有）；没有就用默认约定——`src/` 代码、`docs/` 正式文档（命名 `YYYY-MM-DD_主题.md`）、`assets/{design,bug,reference}` 素材分类、`notes/` 非正式笔记、`archive/` 被替换/淘汰文件的归档。
2. 扫描并列出问题：放错目录的文件、无意义命名（如 `截图1.png`、`image.jpg`）、根目录堆积的临时文件、`docs/` 里没被 README 导航表引用的孤儿文档。输出一份整理清单（问题 / 当前位置 / 建议操作 / 依据）。**不要直接移动文件**——移动/重命名是有一定破坏性的操作。
3. **不删除已有目录结构或文件**——哪怕看起来是空目录/没被引用，整理模式只负责"挪位置"，删除需要用户在清单确认时额外明确同意，不能顺手当成整理的一部分执行。需要替换/升级一个已有文件时，优先把旧版本移到 `archive/` 目录（带日期或版本标记命名），而不是直接覆盖或删除，保留可回滚性。
4. 用户确认清单后再执行：git 仓库优先 `git mv`（保留历史），否则普通移动/重命名。
5. 按【强制规则】写 CHANGELOG，记录整理了什么、移动了哪些文件。

## 快速参考

| 用户说 | 触发模式 |
|---|---|
| "初始化一个新项目""搭个 AGENTS.md 骨架" | 初始化模式 |
| （日常改代码/改文档，无特别说明） | 任务纪律模式（默认） |
| "整理一下文件夹""这些文件放得对不对" | 整理模式 |

## Common Mistakes

- 只在对话里口头总结改了什么，没有真的写进 CHANGELOG 文件——汇报和留痕是两件事，都要做。
- 整理模式擅自 `mv`/删除文件后才汇报——必须先出清单，用户确认后再动手。
- 把某个项目专属的"禁止事项"写死进这个通用 skill——那部分永远留给项目自己的 `AGENTS.md`，本 skill 只提供占位结构，内容按当次项目现填。
- 把骨架内容放进独立的模板文件/文件夹——这个 skill 不允许有 `SKILL.md` 以外的任何文件或文件夹，所有模板内容必须内嵌在 `SKILL.md` 里。
- 整理模式或任务纪律模式里顺手删除了看起来没用的目录/文件——删除必须经用户额外明确同意，"反正是空的/没人用"不是删除的理由。
- 占位符问不出来就编个内容顶替，或者干脆删掉那一节——必须显式标 TBD，留一个"需要去问"的信号。
- 决策/方案被后续推翻后，直接删除或悄悄改写旧的 decision-log/change-log 条目——必须保留旧记录并标注"已被推翻"，历史要能追溯。