4.5 KiB
4.5 KiB
name, description
| name | description |
|---|---|
| write-development-docs | Use when working in X-Financial and the user asks to 落文档, 写开发文档, 沉淀方案, 补 concept/todo, or create/update planning documentation under document/development for a feature, refactor, page, algorithm, rule, or business capability. |
Write Development Docs
目标
把一个功能、重构、算法、页面或业务能力沉淀为项目标准开发文档。 默认落点固定为：
document/development/<YYYY-MM-DD>/feature/<具体功能点目录>/
├── CONCEPT.md
└── TODO.md
如果用户说 concept.md / todo.md，也按仓库现有规范使用大写文件名
CONCEPT.md 和 TODO.md。
工作流
- 先读取当前日期，默认使用本地日期
YYYY-MM-DD作为第一层目录。 - 先阅读
document/development中 2-3 组相邻或同类样例。 - 再读取本次能力相关的代码、接口、页面、测试或历史文档。
- 创建或更新
CONCEPT.md，先写清业务边界，再写方案和验收。 - 创建或更新
TODO.md，每个任务都要回链到CONCEPT.md的章节。 - 已实现或已验证的 TODO 可以勾选
[x]，但必须写证据。 - 交付前检查两份文档互相一致，不额外创建 README、CHANGELOG、SUMMARY。
路径规则
- 第一层必须是日期目录，例如
document/development/2026-06-25/。 - 第二层固定是
feature/，表示当天沉淀的功能点集合。 - 第三层是具体功能点目录，每个独立功能点一个目录。
- 每个具体功能点目录内只放
CONCEPT.md和TODO.md两个核心文件。 - 如果一次请求包含多个互不依赖的功能点，拆成多个兄弟目录：
document/development/2026-06-25/feature/
├── receipt-folder-ocr/
│ ├── CONCEPT.md
│ └── TODO.md
└── risk-review-nudge/
├── CONCEPT.md
└── TODO.md
- 如果用户明确指定日期，使用用户指定日期；否则使用当前本地日期。
- 如果是更新历史文档，先查找已有目录并原地更新，不自动迁移旧路径。
目录命名
- 优先复用用户指定目录名或已有目录名。
- 新增英文目录用小写 kebab-case，例如
receipt-folder。 - 新增中文目录可直接用清晰中文能力名，例如
费用审批动态路由。 - 同一能力已有目录时更新原目录，不新建近义目录。
CONCEPT.md 要求
可参考 assets/CONCEPT.md 模板。必须包含：
- 标题：
# <功能名> 概念文档 更新时间：YYYY-MM-DD## 功能一句话## 背景与问题## 目标与非目标## 用户与场景## 功能能力## 方案设计## 算法与公式## 测试方案## 指标与验收## 风险与开放问题
写法要求：
- 先讲业务问题和边界，再讲技术方案。
- 目标与非目标分开写，避免需求无限扩张。
- 方案设计按前端、后端、算法/规则、数据、权限、降级策略分块； 不涉及的块明确写“当前不涉及”。
- 算法与公式必须明确“不涉及”或写出公式、变量说明和适用边界。
- 验收标准必须可验证，不写空泛口号。
TODO.md 要求
可参考 assets/TODO.md 模板。必须包含：
- 标题：
# <功能名> 开发 TODO 更新时间：YYYY-MM-DD## 使用规则- 分阶段 checklist
TODO 条目规则：
- 每条用
- [ ]或- [x]。 - 每条必须包含
[CONCEPT: <章节名>]。 - 已完成项必须补证据，格式为
证据：<文件、接口、命令或验证结果>。 - 没有真实证据时不得勾选
[x]。
建议阶段：
## 1. 调研与边界## 2. 契约与设计## 3. 后端实现## 4. 算法/规则实现## 5. 前端实现## 6. 测试与验证## 7. 文档收尾
更新既有文档
- 先读现有
CONCEPT.md和TODO.md全文。 - 新需求先补
CONCEPT.md，再补TODO.md。 - 实现变化时同步更新“非目标”“风险与开放问题”“本轮实现记录”。
- 不删除历史证据；除非证据明显错误，才替换为新证据。
验收检查
- 新建文档路径符合
document/development/<YYYY-MM-DD>/feature/<具体功能点目录>/。 CONCEPT.md和TODO.md都存在于同一个具体功能点目录。- TODO 的
[CONCEPT: ...]都能在 CONCEPT 中找到对应章节或语义段落。 - 已勾选项都有证据。
- 文档没有遗留模板占位符，例如
<功能名>、<YYYY-MM-DD>、待补充。