# Writing Doc

> 当需要编写或补全前端技术方案、页面级实现方案、页面功能总结或学习小结时使用。适用于把需求、状态流转、组件职责、业务规则和技术知识整理成可评审、可追踪的中文文档。

- Skill: `tomorrowlm/writing-doc` (Agent Skill, multi-file: 29 files)
- Install (CLI): `npx skillmds@latest add tomorrowlm/writing-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomorrowlm/writing-doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: TomorrowLM (https://skillmd.com/u/tomorrowlm)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomorrowlm/writing-doc

---


## 核心原则

1. **只填内容，不改结构**：文档的章节标题必须严格来自模板，禁止新增、合并、拆分、重命名任何标题
2. **上下文驱动**：从用户提供的 UI 图片、API 文档、需求描述等上下文中提取信息填入模板，不编造内容
3. **默认功能模板**：未明确指定模板类型时，使用「前端功能技术文档模板」
4. **缺失即留空**：上下文中没有的信息不推测、不补全，保留占位符或留空
5. **精简聚焦**：文档只记录关键决策、页面状态流转和业务规则，不罗列代码细节。代码是最终真相，文档解释"为什么这样设计"和"状态怎么流转"
6. **技术文档视角**：学习小结说明概念、职责、流程、接口和边界，不按现有代码逐行翻译或机械罗列目录。

## 触发条件

- 用户要求编写前端技术方案、实现方案、开发文档
- 用户要求编写技术难点方案、架构设计、重构方案
- 用户要求编写项目 README、项目说明文档
- 用户提供了需求描述、UI 截图、API 文档并要求整理成文档
- 用户要求补全或完善已有的技术文档
- 用户要求生成学习笔记、学习小结或技术知识总结
- 用户明确调用 `/writing-doc` 命令
- 用户说 **"sync docs"** / **"同步文档"** → 触发「页面功能总结模板」

### 不适用
- 纯组件 API 文档（props/events 说明）→ 直接写组件目录下的 index.md
- 会议纪要、非技术文案
- 已有完整文档只需微小修改（直接改对应段落）

### sync docs 流程

当 sync docs 触发时，执行以下流程：

1. **读取待同步列表**：读取 `docs/pages/.doc-sync-commits`，获取所有待同步的 commit hash
2. **逐个获取 diff**：对每个 hash 执行 `git show --stat <hash>` 和 `git show <hash>` 获取变更信息
3. **匹配受影响文档**：根据变更文件路径，判断 `docs/design/` 和 `docs/prod/` 中哪些文档需要更新：
   - `src/pages/<page>/**` → `docs/design/<对应设计文档>` 和 `docs/prod/<对应生产文档>`
   - `src/components/**` → 引用该组件的页面对应的文档
   - `src/services/**` → 相关功能模块的文档
   - `src/constants/**` → 相关业务领域的文档
   - `src/types/**` → 相关全局类型的文档
4. **编写文档**：使用「页面功能总结模板」更新受影响文档
5. **列出变更方案**：向用户展示本次变更影响哪些文档、建议如何更新
6. **等待确认后执行**：用户确认后逐个更新文档
7. **清空 hash 列表**：所有文档同步完成后，将 `docs/pages/.doc-sync-commits` 恢复为空（仅保留注释头）

> 若 hash 已被垃圾回收，对应的 hash 行跳过并标注 "hash not found"，警告用户该 commit 可能已被 rebase 或清理。

## 模板选择

| 场景 | 模板文件 | 触发关键词 | 输出路径 |
| ---- | -------- | ---------- | -------- |
| 单个功能模块的技术方案（默认） | `references/前端功能技术文档模板.md` | 技术方案、实现方案、开发文档、功能文档 | `docs/design/{模块名}/` |
| 通用技术方案（技术难点导向） | `references/前端通用技术方案文档模板.md` | 技术难点、方案选型、架构设计、重构方案 | `docs/technology/` |
| 整个项目的技术文档 | `references/前端项目技术文档模板.md` | 项目文档、项目级、整体方案 | 项目根目录 `docs/` |
| 页面功能总结（开发完成后持续维护） | `references/页面功能总结模板.md` | 页面总结、sync docs、同步文档 | `docs/pages/{page-path}/index.md` |
| 学习小结 | `references/学习小结模版.md` | 学习笔记、学习小结、知识总结 | 用户指定的 Markdown 文件 |
| 项目 README（面向使用者） | `references/前端README文档模板.md` | README、项目说明、快速开始 | 项目根目录 `README.md` |
| 项目 AGENTS.md（AI 协作规则） | `references/agent/agent.md`（拼装指引） | AGENTS.md、AI 协作规则、agent 规范 | 项目根目录 `AGENTS.md` |

### 模板选择逻辑

1. 用户说 **sync docs / 同步文档** → 强制使用「页面功能总结模板」
2. 用户提到 **方案选型、候选方案对比、技术难点** → 使用「通用技术方案模板」
3. 用户要写 **README、项目说明、快速开始** → 使用「README 模板」
4. 用户要写 **项目级文档、整体方案** → 使用「项目技术文档模板」
5. 用户要写 **学习笔记、学习小结、知识总结** → 使用「学习小结模板」
6. 用户要生成 **AGENTS.md / AI 协作规则 / agent 规范** → 使用「AGENTS.md 拼装指引」
7. 其余情况（需求驱动的功能文档）→ 默认使用「功能技术文档模板」

### 学习小结规则

学习小结严格使用 `references/学习小结模版.md`，保留以下四个固定章节：

1. 概念
2. 使用场景
3. API 说明
4. 示例

标题层级以文档主题标题为基准：用户指定起始级别时，以用户指定级别为准；未指定时，主题标题使用二级标题。其他标题按层级逐级下移一级：固定章节和自定义章节使用主题标题的下一级，API、示例等子标题再下移一级。

在固定章节之后，可按主题需要增加 0～3 个与主题直接相关的自定义章节，不得为了凑结构强行添加。不默认添加“设计与验证”章节。

学习小结必须从技术文档视角组织内容：

- 解释能力边界、组件职责、输入输出、流程和约束
- 示例用于说明通用用法，不逐行复述用户现有代码
- 不根据代码文件数量、目录结构或变量名称扩展章节
- 除模板允许的标题外，不新增其他级别标题；保留主题标题、章节标题和子标题之间的层级关系
- 上下文不足时保留 `{xxx}` 占位符，不虚构实现细节

### AGENTS.md 生成流程

当用户要求生成 AGENTS.md 时，执行以下流程：

1. **读取拼装指引**：读取 `references/agent/agent.md`，获取技术栈识别矩阵和拼接顺序
2. **检测技术栈**：读取目标项目的 `package.json`，按矩阵检测依赖，确定所需模块清单
3. **分三大章节拼接**：
   - `# 一、AI 行为规则` → 读取 `ai-behavior/` 目录下的模块
   - `# 二、项目编写规范` → 读取 `coding-standards/` 目录下的模块
   - `# 三、项目测试规范` → 读取 `testing-standards/` 目录下的模块
4. **按序拼接**：每个模块文件前追加 `## ` 二级标题，模块内容直接拼接
5. **输出 AGENTS.md**：写入项目根目录 `AGENTS.md`

> 模块文件之间零交叉引用，`cat` 即可直接拼接。每个模块文件自带一个 `##` 级标题作为章节入口。

## 流程

1. **读取模板**：根据场景读取对应的模板文件，提取全部章节标题作为允许清单
2. **收集上下文**：从用户消息中识别所有可用信息源（UI 图片、API 文档、需求文本、现有代码）
3. **信息映射**：将上下文信息对号入座到模板的对应章节中
4. **生成文档**：按模板结构输出完整文档，只填充有据可查的内容
5. **标注来源**：对每个关键决策或数据，标注信息来源（如「来自 API 文档」「来自 UI 截图」）

### 章节标题允许清单

> **不在此处硬编码。** 每次执行时从选中的模板文件动态提取各级标题作为允许清单，严格按模板中的顺序和层级，禁止增删改。

> 模板中用 `{占位符}` 标记的位置是可替换内容，不是标题。子章节（### / #### 级别）同样必须来自模板，不得新增。

### 红线

- **禁止新增任何级别的标题**：无论 ## / ### / ####，只允许使用模板中已有的标题。即使你觉得「加个新小节更清晰」，也不允许
- **禁止合并相邻章节**：例如不允许把「风险评估与应对」和「工作量评估」合并为「风险与工作量」
- **禁止拆分已有章节**：例如不允许把「需求概述」拆成「业务需求」和「技术需求」
- **禁止重命名标题**：即使只是措辞微调（如「非功能性需求」改成「非功能需求」），也不允许
- **禁止为了凑内容而虚构**：没有上下文支撑的章节保留模板原始占位符

### 常见借口与反击

| 借口 | 反击 |
| ---- | ---- |
| "这个需求比较特殊，需要额外的章节" | 在已有章节内用段落和列表表达特殊性，不要新增标题 |
| "模板缺少 XX 章节，加上更完整" | 模板的完整性由模板维护者负责，本次执行只填内容不改结构 |
| "我合并了两个章节，内容更紧凑" | 合并标题就是改结构，保持原样分别填写 |
| "我只是微调了标题措辞，意思一样" | 逐字一致才是遵守，微调也是违规 |
| "这个章节内容太少，可以合并" | 内容少就留少，不能因此改结构 |

## 信息映射规则

| 上下文来源 | 映射目标章节 |
| ---------- | ------------ |
| 需求描述文本 | 需求概述 → 背景 / 需求和任务 |
| UI 截图 / Figma | 核心功能模块 → 页面架构 / 交互规则 / 字段说明 |
| API 文档（swagger 等） | 接口与数据定义 → API 接口规划 / 字段说明 / Mock 数据模板 |
| 现有代码结构 | 架构设计 → 目录结构 |
| 业务流程说明 | 核心功能模块 → 流程图和数据流 |
| 技术约束说明 | 非功能性需求 / 核心技术设计 |
| 已知风险 | 风险评估与应对 |
| 技术痛点 / 现有实现问题 | 方案概述 → 背景与问题 |
| 候选方案对比 / 选型结论 | 方案选型 |
| 项目 `package.json` / 现有目录结构 | 项目概述 → 技术栈、快速启动、目录结构 |

## 输出规范

- 文件格式：Markdown
- 语言：中文
- 代码块标注语言类型（tsx / less / typescript 等）
- 表格对齐，不留多余空行
- 占位符 `{xxx}` 在有信息时替换为实际内容，无信息时保留原样
- ASCII 页面布局图用等宽字符绘制，标注区域名称
- 流程图用文字箭头链或 Mermaid 语法

### 文件路径规范

- **页面文档路径必须镜像 `src/pages/` 的目录结构**：`src/pages/<page-path>/index.tsx` → `docs/pages/<page-path>/index.md`
- 例：`src/pages/event-rectification/detail/index.tsx` → `docs/pages/event-rectification/detail/index.md`
- 例：`src/pages/home/index.tsx` → `docs/pages/home/index.md`