主题
skill分享 - 大型设计文档规范
简介
这是一个专为大型功能开发或长期项目设计的文档规范 skill。它定义了一套标准的文档结构（plan.md、model.md、task.md、changelog.md），确保在复杂的、可能中断的项目中，用户和 AI 都能快速恢复上下文，避免信息丢失和重复工作。
核心价值
- ✅ 上下文可恢复：即使项目中断或交接，也能快速重建完整背景
- ✅ 职责清晰分离：设计、模型、任务、历史各司其职，避免信息混乱
- ✅ 强制规范约束：明确何时必须更新哪些文档，防止遗漏
- ✅ 支持长期演进：通过 changelog 追溯历史，通过 task 跟踪当前状态
- ✅ 适配中断恢复：长时间项目或多人协作时，保证信息连续性
如何使用
方法一：直接复制使用（推荐）
将下面【Skill 完整内容】章节的完整文本内容复制，发送给 Codex，告诉它"请帮我制作成 skill"即可。
方法二：手动创建 skill
如果你熟悉 skill 的创建流程，可以手动创建一个名为 large-scope-design-documentation-protocol 的 skill，并将下面的内容作为 skill 的配置。
Skill 完整内容
**Skill 名称：** `large-scope-design-documentation-protocol`
**Skill 描述：** 为大型或长期设计变更定义强制性文档结构、位置规则和更新约束，确保人类和 AI 可恢复上下文。
---
### 目录结构（必须遵守）
docs/<feature>/
├── plan.md # 功能背景和实施计划（入口文档）
├── model.md # API / 数据模型 / Schema / 契约定义
├── task.md # 动态任务跟踪和当前执行状态
└── changelog.md # 时间顺序的实施记录
---
### plan.md — 设计上下文和计划（必须）
**目的：**
- 为人类或 AI 提供单一入口点
- 解释功能存在的原因以及正在改变什么
**必须包含：**
- 问题陈述和动机
- 范围和非目标
- 设计边界和约束
- 高层实施计划
**禁止包含：**
- API 字段级细节
- 逐步实施日志
- 任务状态更新
---
### model.md — API 和数据模型（如适用则必须）
**目的：**
- 作为外部或内部契约的唯一真实来源
**必须包含：**
- API 端点或消息
- 请求/响应 schema
- 数据模型和关系
- 验证规则和不变量
**禁止包含：**
- 业务逻辑解释
- 实施步骤
- 任务或进度信息
---
### task.md — 任务跟踪（必须）
**目的：**
- 在长期运行或中断的工作期间跟踪当前执行状态
- 在上下文丢失后实现快速恢复
**必须包含：**
- 当前阶段或里程碑
- 已完成项
- 进行中项
- 阻塞因素和未决风险
- 下一步可执行步骤
**规则：**
- 这是一个动态文档，可能会频繁覆盖
- 仅当前状态重要
- **禁止包含**：历史日志、设计理由、详细代码差异
---
### changelog.md — 实施记录（必须）
**目的：**
- 提供简洁的、仅追加的历史记录，记录随时间变化的内容
**每条记录必须包含：**
- 时间戳或版本
- 修改的文件或模块
- 添加或更改的行为简短描述
**规则：**
- 仅追加
- 每个有意义的变更一条记录
- **禁止包含**：任务状态、未来计划、推测性设计想法
---
### 使用规则（必须遵守）
- **文档内容默认使用简体中文**，除非明确要求其他语言
- `plan.md` 必须在任何大型设计变更之前或同时存在
- `model.md` 必须在任何 API / 数据 / 契约修改的同一变更中更新
- `task.md` 必须在活跃工作期间始终反映最新的执行状态
- `changelog.md` 必须随着实施进展逐步更新
---
### 触发矩阵（必须遵守）
| 变更类型 | plan.md | model.md | task.md | changelog.md |
|---------|---------|----------|---------|--------------|
| 新功能 / 大型重构 | **必须** | **如适用** | **必须** | **必须** |
| API 或数据模型变更 | 应该 | **必须** | 应该 | **必须** |
| 长期运行的实施 | 应该 | 可选 | **必须** | **必须** |
| 小型局部代码变更 | 否 | 否 | 可选 | 可选 |
---
### 最小模板示例
**plan.md 示例：**
- 背景/问题：本功能用于解决订单在跨系统同步时状态不一致的问题
- 范围：仅覆盖订单创建与取消流程
- 非目标：不重构历史订单数据
- 约束：需保持与旧 API 的向后兼容
- 高层计划：新增状态机层，逐步切换流量
**model.md 示例：**
- 实体/Schema：Order、OrderStatus
- 字段和类型：status:string，updated_at:timestamp
- 契约（API/事件）：POST /orders，ORDER_STATUS_CHANGED
- 不变量：订单状态只能单向流转
**task.md 示例：**
- 当前阶段：实现中
- 已完成：设计文档完成，基础 schema 已定义
- 进行中：订单状态机代码实现
- 阻塞因素：下游系统状态回调未确认
- 下一步：实现状态变更事件发布
**changelog.md 示例：**
- 日期或版本：2026-01-05
- 变更的文件/模块：order_service/, api/orders
- 行为摘要：新增订单状态机与状态校验逻辑
---
### 文档位置规则（必须遵守）
**如果变更仅影响单个模块**，将文档存储在：
/<module-root>/docs/<feature>/
**如果变更影响多个模块或引入跨模块行为**，将文档存储在：
/docs/<feature>/ （项目根目录）
**规则：**
- 位置决策基于影响范围，而非代码所有权
- 不要在多个位置重复相同的功能文档
- 在项目根目录记录的功能不得在模块文件夹中有并行副本
---
### 何时创建 docs/<feature>/（必须遵守）
当以下任一条件为真时，创建（或显著更新）文档：
- ✅ 新的或变更的 **API / 契约**（HTTP/gRPC/事件、载荷、错误模型、幂等性）
- ✅ 新的或变更的 **数据模型 / 持久化**（schema、迁移、事务边界）
- ✅ 新的或变更的 **配置**（键、默认值、必需的密钥/变量）
- ✅ 新的 **跨模块编排**（重试、排序、部分失败处理、异步流程）
- ✅ **运营风险增加**（速率限制、不可逆写入、向后兼容性风险）
- ✅ 工作是 **多步骤 / 长期运行的**（可能被中断、交接或上下文压缩）
**不要为以下情况创建新文件夹：**
- ❌ 纯重构（无行为/契约变更）
- ❌ 本地代码清理、格式化、重命名（无外部影响）
- ❌ 微小变更（从代码和测试中完全明显）
---
### 变更类型 → 必需文档矩阵（必须遵守）
规则是累加的：
- **API/契约变更** → `model.md` + `plan.md` + `changelog.md`
- **数据/持久化变更** → `model.md` + `plan.md` + `changelog.md`（如需要，在 `model.md` 中添加迁移说明）
- **配置变更** → `plan.md` + `model.md`（配置部分）+ `changelog.md`
- **跨模块行为变更** → `plan.md` + `task.md` + `changelog.md`（如果影响契约，还需 `model.md`）
- **运营风险变更** → `plan.md` + `task.md` + `changelog.md`（在 `plan.md` 中包含回滚/验证）
- **长期运行计划** → 所有四个文件
---
### 何时仅允许更新 task.md（必须遵守）
在以下情况下可以仅更新 `task.md`：
- ✅ 当前步骤中未引入契约/模型/配置变更
- ✅ 工作严格是实施进展（例如，边界内的连接、重构）
- ✅ 在中断后恢复并需要重新建立执行状态
**如果发生任何契约/模型/配置变更，必须在同一变更中同时更新 `model.md` 并添加 `changelog.md` 条目。**
---
### model.md 契约格式（必须遵守）
使用以下格式之一，选择最简单且适合的：
**表格格式（推荐）：**
| 字段 | 类型 | 必需 | 约束 | 备注 |
|------|------|------|------|------|
| ... | ... | ... | ... | ... |
**JSON schema 片段（允许）：** 保持示例最小化
**规则：**
- 保持 `model.md` 事实性（无理由说明）
- 为每个公共契约至少包含一个示例载荷
- 在更改默认值或进行向后不兼容的变更时记录兼容性说明
---
### plan.md 必需的运营插槽（必须遵守）
当存在风险时，添加这两个部分：
- **验证**：证明变更有效的最小步骤（测试、指标、端点）
- **回滚**：如何安全回退（功能标志、配置恢复、迁移策略）
---
### changelog.md 条目格式（必须遵守）
每条记录使用此结构：
- 日期：YYYY-MM-DD
- 摘要：一行描述
- 接触点：变更的文件/模块
- 行为：变更了什么（可观察的）
保持条目简短。
---
### 审查检查清单（必须遵守）
- ☑ 文档语言默认为简体中文，除非要求其他语言
- ☑ `plan.md` 存在且范围/非目标明确
- ☑ 任何契约/模型/配置变更已反映在 `model.md` 中
- ☑ `task.md` 反映当前状态和下一步
- ☑ `changelog.md` 对有意义的行为变更有新条目
- ☑ 任何文档中均无密钥/PII
- ☑ 文件间无重复内容（每个文件保持其单一职责）
---
### 非目标
此 skill **不定义**：
- 代码注释标准
- 仓库级文档政策
- 面向用户的文档格式使用建议
适用场景：
- 大型功能开发或重构
- 跨模块的系统性变更
- 长期运行的项目（可能中断或交接）
- 涉及 API、数据模型、配置的关键变更
调用方式：在对话中告诉 Codex"使用 large-scope-design-documentation-protocol skill"
最佳实践：
- 项目启动时就创建
docs/<feature>/文件夹 - 严格遵守文档职责分离，避免信息混杂
- 定期更新
task.md和changelog.md - 在中断恢复时优先查看
task.md快速重建上下文
- 项目启动时就创建
相关资源
- skill 介绍 - 了解 skill 的基本概念
- 进阶教程 - skill 使用指南 - 详细的 skill 教程