126 lines
4.5 KiB
Markdown
126 lines
4.5 KiB
Markdown
---
|
||
name: write-development-docs
|
||
description: 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
|
||
|
||
## 目标
|
||
|
||
把一个功能、重构、算法、页面或业务能力沉淀为项目标准开发文档。
|
||
默认落点固定为：
|
||
|
||
```text
|
||
document/development/<YYYY-MM-DD>/feature/<具体功能点目录>/
|
||
├── CONCEPT.md
|
||
└── TODO.md
|
||
```
|
||
|
||
如果用户说 `concept.md` / `todo.md`，也按仓库现有规范使用大写文件名
|
||
`CONCEPT.md` 和 `TODO.md`。
|
||
|
||
## 工作流
|
||
|
||
1. 先读取当前日期，默认使用本地日期 `YYYY-MM-DD` 作为第一层目录。
|
||
2. 先阅读 `document/development` 中 2-3 组相邻或同类样例。
|
||
3. 再读取本次能力相关的代码、接口、页面、测试或历史文档。
|
||
4. 创建或更新 `CONCEPT.md`，先写清业务边界，再写方案和验收。
|
||
5. 创建或更新 `TODO.md`，每个任务都要回链到 `CONCEPT.md` 的章节。
|
||
6. 已实现或已验证的 TODO 可以勾选 `[x]`，但必须写证据。
|
||
7. 交付前检查两份文档互相一致，不额外创建 README、CHANGELOG、SUMMARY。
|
||
|
||
## 路径规则
|
||
|
||
- 第一层必须是日期目录，例如 `document/development/2026-06-25/`。
|
||
- 第二层固定是 `feature/`，表示当天沉淀的功能点集合。
|
||
- 第三层是具体功能点目录，每个独立功能点一个目录。
|
||
- 每个具体功能点目录内只放 `CONCEPT.md` 和 `TODO.md` 两个核心文件。
|
||
- 如果一次请求包含多个互不依赖的功能点，拆成多个兄弟目录：
|
||
|
||
```text
|
||
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>`、`待补充`。
|