--- name: write-development-docs description: 为 X-Financial 落地开发文档。Use when a task asks to write, create, update, or standardize planning/development documentation under document/development, especially when the expected output is a CONCEPT.md capability document plus a TODO.md implementation checklist following this repository's existing development-doc format. --- # Write Development Docs ## 目标 使用本技能为一个功能、重构、算法、页面或业务能力创建标准开发文档。 默认输出位置： ```text document/development// ├── CONCEPT.md └── TODO.md ``` ## 工作流 1. 先阅读相邻或同类文档，优先参考 `document/development/*/CONCEPT.md` 和 `document/development/*/TODO.md`。 2. 读取与本次能力相关的代码、接口、页面、测试或历史文档，不凭空写实现细节。 3. 创建或更新 `CONCEPT.md`，先写清能力边界，再写方案和验收。 4. 创建或更新 `TODO.md`，每个任务必须能回链到 `CONCEPT.md` 的章节。 5. 如果已有实现，TODO 可以勾选 `[x]`，但必须写证据；没有验证的任务保持 `[ ]`。 6. 完成后检查两份文档是否互相一致，避免 TODO 承诺了 CONCEPT 没定义的能力。 ## 命名规则 - 目录名使用小写 kebab-case，例如 `receipt-folder`、`agent-trace-center`。 - 能力名在正文中使用清晰中文，例如“票据夹功能”“Agent 链路追踪中心”。 - 两个文件名固定为 `CONCEPT.md` 和 `TODO.md`。 - 不额外创建 README、CHANGELOG、SUMMARY 等文件，除非用户明确要求。 ## 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`。 - 如果实现发生变化，同步更新“非目标”“风险与开放问题”“本轮实现记录”。 - 不删除历史证据；除非证据已经明显错误，才替换为新证据。 ## 验收检查 交付前检查： - `CONCEPT.md` 和 `TODO.md` 都存在。 - TODO 的 `[CONCEPT: ...]` 都能在 `CONCEPT.md` 找到对应章节或语义段落。 - 已勾选项都有证据。 - 文档没有遗留模板占位符，例如 `<功能名>`、`TODO`、`待补充`。 - 文档路径位于 `document/development//`。