diff --git a/.codex/skills/write-development-docs/SKILL.md b/.codex/skills/write-development-docs/SKILL.md index 7d040f0..f009c7d 100644 --- a/.codex/skills/write-development-docs/SKILL.md +++ b/.codex/skills/write-development-docs/SKILL.md @@ -11,7 +11,7 @@ description: Use when working in X-Financial and the user asks to 落文档, 写 默认落点固定为： ```text -document/development/<功能目录>/ +document/development//feature/<具体功能点目录>/ ├── CONCEPT.md └── TODO.md ``` @@ -21,12 +21,34 @@ document/development/<功能目录>/ ## 工作流 -1. 先阅读 `document/development` 中 2-3 组相邻或同类样例。 -2. 再读取本次能力相关的代码、接口、页面、测试或历史文档。 -3. 创建或更新 `CONCEPT.md`，先写清业务边界，再写方案和验收。 -4. 创建或更新 `TODO.md`，每个任务都要回链到 `CONCEPT.md` 的章节。 -5. 已实现或已验证的 TODO 可以勾选 `[x]`，但必须写证据。 -6. 交付前检查两份文档互相一致，不额外创建 README、CHANGELOG、SUMMARY。 +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 +``` + +- 如果用户明确指定日期，使用用户指定日期；否则使用当前本地日期。 +- 如果是更新历史文档，先查找已有目录并原地更新，不自动迁移旧路径。 ## 目录命名 @@ -96,8 +118,8 @@ TODO 条目规则： ## 验收检查 -- 两个文件都位于 `document/development/<功能目录>/`。 -- `CONCEPT.md` 和 `TODO.md` 都存在。 +- 新建文档路径符合 `document/development//feature/<具体功能点目录>/`。 +- `CONCEPT.md` 和 `TODO.md` 都存在于同一个具体功能点目录。 - TODO 的 `[CONCEPT: ...]` 都能在 CONCEPT 中找到对应章节或语义段落。 - 已勾选项都有证据。 - 文档没有遗留模板占位符，例如 `<功能名>`、``、`待补充`。 diff --git a/.codex/skills/write-development-docs/agents/openai.yaml b/.codex/skills/write-development-docs/agents/openai.yaml index b5562d6..73b4231 100644 --- a/.codex/skills/write-development-docs/agents/openai.yaml +++ b/.codex/skills/write-development-docs/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "开发文档落地" - short_description: "按项目格式生成 CONCEPT 和 TODO 文档" - default_prompt: "Use $write-development-docs to create CONCEPT.md and TODO.md under document/development for an X-Financial feature." + short_description: "按日期和功能点生成 CONCEPT/TODO" + default_prompt: "Use $write-development-docs to create CONCEPT.md and TODO.md under document/development//feature/ for an X-Financial feature." diff --git a/.codex/skills/write-development-docs/assets/CONCEPT.md b/.codex/skills/write-development-docs/assets/CONCEPT.md index 995a127..3668431 100644 --- a/.codex/skills/write-development-docs/assets/CONCEPT.md +++ b/.codex/skills/write-development-docs/assets/CONCEPT.md @@ -2,6 +2,8 @@ 更新时间： +文档路径：document/development//feature/<具体功能点目录>/CONCEPT.md + ## 功能一句话 用一句话说明这个能力解决什么问题、服务谁、交付什么结果。 diff --git a/.codex/skills/write-development-docs/assets/TODO.md b/.codex/skills/write-development-docs/assets/TODO.md index 2092a7d..76a29cb 100644 --- a/.codex/skills/write-development-docs/assets/TODO.md +++ b/.codex/skills/write-development-docs/assets/TODO.md @@ -2,6 +2,8 @@ 更新时间： +文档路径：document/development//feature/<具体功能点目录>/TODO.md + ## 使用规则 - 每个 TODO 必须对应 `CONCEPT.md` 中的目标、能力、方案或验收点。 diff --git a/document/work-log/2026-06-25.md b/document/work-log/2026-06-25.md index c328cde..472cccb 100644 --- a/document/work-log/2026-06-25.md +++ b/document/work-log/2026-06-25.md @@ -10,9 +10,18 @@ - 验证：`frontmatter ok`、`required files ok`、`.codex/skills/write-development-docs` 无 `[TODO:]` 初始化占位符，`git diff --check -- .codex/skills/write-development-docs .gitignore` 通过。 - 影响：以后用户说“落文档 / 写开发文档 / 补 concept 和 todo”时，可以优先触发仓库级技能，按项目格式生成两份开发文档。 +- 09:23：我按新的目录约定升级了 `write-development-docs` 技能。 + - Git 提交检查：`git fetch --all --prune` 后未发现 upstream 新提交；本地 ahead 1 个提交，为本会话前一步生成的 `23f7de6c chore(skills): add development docs writer`。 + - 修改：`.codex/skills/write-development-docs` 和 `hermes/skills/domain/write-development-docs` 同步新增路径规则，默认落点调整为 `document/development//feature/<具体功能点目录>/CONCEPT.md + TODO.md`。 + - 修改：两个技能副本的 `agents/openai.yaml`、`assets/CONCEPT.md`、`assets/TODO.md` 同步补充日期、`feature` 聚合层和具体功能点目录提示。 + - 操作：保留历史文档原地更新规则，避免把 `document/development` 既有旧路径自动搬迁。 + - 验证：两个 `SKILL.md` frontmatter 分别校验通过，路径规则检索命中，两个技能副本的模板和 UI 元数据 diff 一致，`git diff --check -- .codex/skills/write-development-docs hermes/skills/domain/write-development-docs` 通过。 + - 影响：后续新功能落文档会先按日期建目录，再进入 `feature`，最后按具体功能点独立建目录，便于按天回溯和按功能点拆分。 + ## 遗留问题 - 09:18：官方 `quick_validate.py` 仍因当前 Python 环境缺少 `PyYAML` 无法运行，已用 frontmatter、必需文件、占位符和 diff check 做人工兜底。建议后续统一为 skill 校验脚本补齐依赖或增加无 PyYAML 的轻量校验路径。 +- 09:23：当前环境没有找到 Skill Creator 的 `quick_validate.py` 脚本文件本体，因此本次继续采用人工兜底校验。建议后续恢复系统 Skill Creator 脚本路径，或把轻量校验脚本纳入仓库级工具。 ## TODO diff --git a/hermes/skills/domain/write-development-docs/SKILL.md b/hermes/skills/domain/write-development-docs/SKILL.md index bfdbd0d..53f2375 100644 --- a/hermes/skills/domain/write-development-docs/SKILL.md +++ b/hermes/skills/domain/write-development-docs/SKILL.md @@ -1,33 +1,60 @@ --- 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. +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// +document/development//feature/<具体功能点目录>/ ├── CONCEPT.md └── TODO.md ``` +如果用户说 `concept.md` / `todo.md`，也按仓库现有规范使用大写文件名 +`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 没定义的能力。 +1. 先读取当前日期，默认使用本地日期 `YYYY-MM-DD` 作为第一层目录。 +2. 先阅读 `document/development` 中 2-3 组相邻或同类样例。 +3. 再读取本次能力相关的代码、接口、页面、测试或历史文档，不凭空写实现细节。 +4. 创建或更新 `CONCEPT.md`，先写清能力边界，再写方案和验收。 +5. 创建或更新 `TODO.md`，每个任务必须能回链到 `CONCEPT.md` 的章节。 +6. 如果已有实现，TODO 可以勾选 `[x]`，但必须写证据；没有验证的任务保持 `[ ]`。 +7. 完成后检查两份文档是否互相一致，避免 TODO 承诺了 CONCEPT 没定义的能力。 + +## 路径规则 + +- 第一层必须是日期目录，例如 `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`、`agent-trace-center`。 +- 优先复用用户指定目录名或已有目录名。 +- 新增英文目录用小写 kebab-case，例如 `receipt-folder`、`agent-trace-center`。 +- 新增中文目录可直接用清晰中文能力名，例如“费用审批动态路由”。 - 能力名在正文中使用清晰中文，例如“票据夹功能”“Agent 链路追踪中心”。 - 两个文件名固定为 `CONCEPT.md` 和 `TODO.md`。 - 不额外创建 README、CHANGELOG、SUMMARY 等文件，除非用户明确要求。 @@ -102,8 +129,8 @@ TODO 条目规则： 交付前检查： +- 新建文档路径符合 `document/development//feature/<具体功能点目录>/`。 - `CONCEPT.md` 和 `TODO.md` 都存在。 - TODO 的 `[CONCEPT: ...]` 都能在 `CONCEPT.md` 找到对应章节或语义段落。 - 已勾选项都有证据。 - 文档没有遗留模板占位符，例如 `<功能名>`、`TODO`、`待补充`。 -- 文档路径位于 `document/development//`。 diff --git a/hermes/skills/domain/write-development-docs/agents/openai.yaml b/hermes/skills/domain/write-development-docs/agents/openai.yaml index 8e6ae5f..73b4231 100644 --- a/hermes/skills/domain/write-development-docs/agents/openai.yaml +++ b/hermes/skills/domain/write-development-docs/agents/openai.yaml @@ -1,4 +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." + short_description: "按日期和功能点生成 CONCEPT/TODO" + default_prompt: "Use $write-development-docs to create CONCEPT.md and TODO.md under document/development//feature/ for an X-Financial feature." diff --git a/hermes/skills/domain/write-development-docs/assets/CONCEPT.md b/hermes/skills/domain/write-development-docs/assets/CONCEPT.md index baea3f4..3668431 100644 --- a/hermes/skills/domain/write-development-docs/assets/CONCEPT.md +++ b/hermes/skills/domain/write-development-docs/assets/CONCEPT.md @@ -2,6 +2,8 @@ 更新时间： +文档路径：document/development//feature/<具体功能点目录>/CONCEPT.md + ## 功能一句话 用一句话说明这个能力解决什么问题、服务谁、交付什么结果。 @@ -17,9 +19,9 @@ ### 目标 -- [G1] -- [G2] -- [G3] +- [G1] +- [G2] +- [G3] ### 非目标 @@ -32,11 +34,11 @@ - 目标用户： - 使用入口： - 核心场景： - 1. - 2. - 3. + 1. + 2. + 3. - 异常场景： - - + - ## 功能能力 @@ -78,39 +80,37 @@ ## 算法与公式 -如果当前功能不涉及公式，写明： - 当前功能不涉及显式数学公式。 -如果涉及公式，使用如下格式： +如涉及公式，使用如下格式： -$$ +```text metric = input_a + input_b -$$ +``` 变量说明： -- $metric$： -- $input_a$： -- $input_b$： +- metric： +- input_a： +- input_b： ## 测试方案 后端： -- +- 前端： -- +- 集成： -- +- 手工验证： -- +- ## 指标与验收 @@ -129,4 +129,4 @@ $$ ## 本轮实现记录 -- +- diff --git a/hermes/skills/domain/write-development-docs/assets/TODO.md b/hermes/skills/domain/write-development-docs/assets/TODO.md index dc6b2ac..76a29cb 100644 --- a/hermes/skills/domain/write-development-docs/assets/TODO.md +++ b/hermes/skills/domain/write-development-docs/assets/TODO.md @@ -2,6 +2,8 @@ 更新时间： +文档路径：document/development//feature/<具体功能点目录>/TODO.md + ## 使用规则 - 每个 TODO 必须对应 `CONCEPT.md` 中的目标、能力、方案或验收点。 @@ -49,7 +51,7 @@ 证据： - [ ] [CONCEPT: 前端] 实现加载、空态、错误态、权限态和刷新。 证据： -- [ ] [CONCEPT: 前端] 对齐现有企业级直角、低饱和、密集信息风格。 +- [ ] [CONCEPT: 前端] 对齐现有企业后台风格，避免营销页或花哨卡片感。 证据： ## 6. 测试与验证