chore(agent): 新增变更日志/checkpoint skill 与 post-commit hook
- AGENTS.md 新增变更日志 Skill 规范:变更后增量更新 document/work-log,更新前先做 Git 拉取检查 - 新增 .codex/skills 下 agent-change-log、git-checkpoint-commit 两个 skill - 新增 .githooks/post-commit 与 tools/agent-change-log 自动化脚本,提供提交后最低限度日志追加
This commit is contained in:
109
hermes/skills/domain/write-development-docs/SKILL.md
Normal file
109
hermes/skills/domain/write-development-docs/SKILL.md
Normal file
@@ -0,0 +1,109 @@
|
||||
---
|
||||
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/<feature-slug>/
|
||||
├── 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/<feature-slug>/`。
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "开发文档落地"
|
||||
short_description: "按项目格式生成 CONCEPT 和 TODO 文档"
|
||||
default_prompt: "Use $write-development-docs to create a development CONCEPT and TODO document for a new X-Financial feature."
|
||||
132
hermes/skills/domain/write-development-docs/assets/CONCEPT.md
Normal file
132
hermes/skills/domain/write-development-docs/assets/CONCEPT.md
Normal file
@@ -0,0 +1,132 @@
|
||||
# <功能名> 概念文档
|
||||
|
||||
更新时间:<YYYY-MM-DD>
|
||||
|
||||
## 功能一句话
|
||||
|
||||
用一句话说明这个能力解决什么问题、服务谁、交付什么结果。
|
||||
|
||||
## 背景与问题
|
||||
|
||||
- 当前现状:
|
||||
- 用户痛点:
|
||||
- 业务影响:
|
||||
- 为什么现在需要做:
|
||||
|
||||
## 目标与非目标
|
||||
|
||||
### 目标
|
||||
|
||||
- [G1]
|
||||
- [G2]
|
||||
- [G3]
|
||||
|
||||
### 非目标
|
||||
|
||||
- [NG1] 本轮不做:
|
||||
- [NG2] 本轮不改变:
|
||||
- [NG3] 后续再评估:
|
||||
|
||||
## 用户与场景
|
||||
|
||||
- 目标用户:
|
||||
- 使用入口:
|
||||
- 核心场景:
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
- 异常场景:
|
||||
-
|
||||
|
||||
## 功能能力
|
||||
|
||||
- [C1] 输入能力:
|
||||
- [C2] 处理能力:
|
||||
- [C3] 输出能力:
|
||||
- [C4] 状态与权限:
|
||||
- [C5] 边界与降级:
|
||||
|
||||
## 方案设计
|
||||
|
||||
### 前端
|
||||
|
||||
- 页面/组件:
|
||||
- 交互状态:
|
||||
- 展示规则:
|
||||
- 降级处理:
|
||||
|
||||
### 后端
|
||||
|
||||
- 接口/服务:
|
||||
- 权限与校验:
|
||||
- 持久化:
|
||||
- 降级处理:
|
||||
|
||||
### 算法与规则
|
||||
|
||||
- 输入:
|
||||
- 流程:
|
||||
- 输出:
|
||||
- 解释:
|
||||
|
||||
### 数据与契约
|
||||
|
||||
- 核心字段:
|
||||
- 状态枚举:
|
||||
- 兼容策略:
|
||||
- 版本/审计:
|
||||
|
||||
## 算法与公式
|
||||
|
||||
如果当前功能不涉及公式,写明:
|
||||
|
||||
当前功能不涉及显式数学公式。
|
||||
|
||||
如果涉及公式,使用如下格式:
|
||||
|
||||
$$
|
||||
metric = input_a + input_b
|
||||
$$
|
||||
|
||||
变量说明:
|
||||
|
||||
- $metric$:
|
||||
- $input_a$:
|
||||
- $input_b$:
|
||||
|
||||
## 测试方案
|
||||
|
||||
后端:
|
||||
|
||||
-
|
||||
|
||||
前端:
|
||||
|
||||
-
|
||||
|
||||
集成:
|
||||
|
||||
-
|
||||
|
||||
手工验证:
|
||||
|
||||
-
|
||||
|
||||
## 指标与验收
|
||||
|
||||
- [A1] 功能验收:
|
||||
- [A2] 性能指标:
|
||||
- [A3] 质量指标:
|
||||
- [A4] 安全/权限指标:
|
||||
- [A5] 可观测性:
|
||||
|
||||
## 风险与开放问题
|
||||
|
||||
- 风险:
|
||||
- 已处理依赖:
|
||||
- 待确认:
|
||||
- 降级策略:
|
||||
|
||||
## 本轮实现记录
|
||||
|
||||
-
|
||||
71
hermes/skills/domain/write-development-docs/assets/TODO.md
Normal file
71
hermes/skills/domain/write-development-docs/assets/TODO.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# <功能名> 开发 TODO
|
||||
|
||||
更新时间:<YYYY-MM-DD>
|
||||
|
||||
## 使用规则
|
||||
|
||||
- 每个 TODO 必须对应 `CONCEPT.md` 中的目标、能力、方案或验收点。
|
||||
- 只有完成并验证后,才能把 `[ ]` 改成 `[x]`。
|
||||
- 勾选时在任务后补充简短证据,例如文件、接口、命令或验证结果。
|
||||
- 如果需求发生变化,先更新 `CONCEPT.md`,再调整本 TODO。
|
||||
|
||||
## 1. 调研与边界
|
||||
|
||||
- [ ] [CONCEPT: 背景与问题] 阅读相关页面、接口、服务、测试和历史文档,记录当前实现事实。
|
||||
证据:
|
||||
- [ ] [CONCEPT: 目标与非目标] 确认本轮开发范围,写清楚不做项。
|
||||
证据:
|
||||
- [ ] [CONCEPT: 风险与开放问题] 标记无法立即确认的依赖、风险和假设。
|
||||
证据:
|
||||
|
||||
## 2. 契约与设计
|
||||
|
||||
- [ ] [CONCEPT: 功能能力] 定义输入、输出、状态、权限和边界条件。
|
||||
证据:
|
||||
- [ ] [CONCEPT: 方案设计] 明确前端、后端、算法、数据的职责边界。
|
||||
证据:
|
||||
- [ ] [CONCEPT: 算法与公式] 补全公式、变量解释或明确当前不涉及公式。
|
||||
证据:
|
||||
- [ ] [CONCEPT: 指标与验收] 把验收标准转成可验证的检查点。
|
||||
证据:
|
||||
|
||||
## 3. 后端实现
|
||||
|
||||
- [ ] [CONCEPT: 后端] 新增或调整 schema、service、endpoint、权限和持久化逻辑。
|
||||
证据:
|
||||
- [ ] [CONCEPT: 数据与契约] 保持响应结构、状态枚举和兼容策略清晰。
|
||||
证据:
|
||||
|
||||
## 4. 算法/规则实现
|
||||
|
||||
- [ ] [CONCEPT: 算法与规则] 实现核心处理流程、规则判断或计算逻辑。
|
||||
证据:
|
||||
- [ ] [CONCEPT: 结果解释] 输出可读解释、证据链、贡献项或降级原因。
|
||||
证据:
|
||||
|
||||
## 5. 前端实现
|
||||
|
||||
- [ ] [CONCEPT: 前端] 新增或调整页面、组件、服务 API 和视图模型。
|
||||
证据:
|
||||
- [ ] [CONCEPT: 前端] 实现加载、空态、错误态、权限态和刷新。
|
||||
证据:
|
||||
- [ ] [CONCEPT: 前端] 对齐现有企业级直角、低饱和、密集信息风格。
|
||||
证据:
|
||||
|
||||
## 6. 测试与验证
|
||||
|
||||
- [ ] [CONCEPT: 测试方案] 补充后端 service/API 定向测试,容器内运行,超时控制在 60s 内。
|
||||
证据:
|
||||
- [ ] [CONCEPT: 测试方案] 补充前端视图模型、路由、组件或构建验证。
|
||||
证据:
|
||||
- [ ] [CONCEPT: 指标与验收] 记录验证命令、结果和未覆盖风险。
|
||||
证据:
|
||||
|
||||
## 7. 文档收尾
|
||||
|
||||
- [ ] [CONCEPT: 指标与验收] 回看所有验收点,确认均有实现或验证证据。
|
||||
证据:
|
||||
- [ ] [CONCEPT: 风险与开放问题] 更新剩余风险、后续任务和明确不做项。
|
||||
证据:
|
||||
- [ ] [CONCEPT: 功能一句话] 确认最终实现没有偏离原始目标。
|
||||
证据:
|
||||
Reference in New Issue
Block a user