docs(workflow): 补全文档持续维护流程

This commit is contained in:
zhiye.sun
2026-09-03 15:54:44 +08:00
parent 8cdb91c225
commit e2d29f6005
3 changed files with 32 additions and 17 deletions
+7 -2
View File
@@ -163,7 +163,7 @@
1. 确定项目根目录和需求材料范围。
2. 读取所有适用的 `AGENTS.md`。
3. 检查 `.craftkit/project.json`、规范索引、构建文件、依赖锁文件和主要源码目录。
3. 检查 `.craftkit/project.json`、规范索引、文档维护规范、构建文件、依赖锁文件和主要源码目录。
4. 使用 `guidance` 获取本任务适用的项目规则,并区分明确规则、公共建议和代码现状。
5. 执行只读 Git 检查,记录当前分支、HEAD、工作树状态、远程引用现状和 worktree 占用情况。
6. 若项目上下文缺失,只在确有必要时提出 `init`;初始化写入仍遵守该 Skill 的确认步骤。
@@ -173,7 +173,7 @@
### S1:需求归集与落表
使用 `requirements` 处理原始需求。输入可以是完整需求文档,也可以是聊天记录、口头描述转写、邮件、会议纪要、Bug 描述、截图文字或零散技术说明。
使用 `requirements` 处理原始需求。先检索同主题的现有需求并更新权威文档;只有不存在可维护的当前文档时才新建。输入可以是完整需求文档,也可以是聊天记录、口头描述转写、邮件、会议纪要、Bug 描述、截图文字或零散技术说明。
需求文档至少包含:
@@ -227,6 +227,8 @@
设计产物应使用 `REQ-*` 关联需求,并为关键方案使用 `DES-*` 编号。数据库、API、前端和后端设计相互引用,不能产生字段、枚举、状态或错误语义冲突。
设计前检索相关已有文档,优先更新当前权威设计。共享长期文档的新建或实质修改应进入 `pending`;G2 批准可作为审核依据,将其更新为 `approved`。旧文档被替代时同步索引、引用和替代关系。
落盘前读取 `.craftkit/project.json` 的 `documents`:开发中的需求、计划、设计和验证记录使用 `workRoot`,用户明确要求共享或正式交付时使用 `designRoot`。缺少 `workRoot` 时回退到 `.craftkit/local/tasks/`;共享目录缺失或规则冲突时,在 G2 前提出建议路径并取得确认。`archiveRoot` 只用于另行授权的归档。
### S4:创建开发分支
@@ -250,6 +252,7 @@
- 延续现有目录、命名、注释、异常、日志、事务、组件、请求和测试风格;
- 追踪真实入口、调用方和数据落点;
- 只实现批准范围内的最小完整变更;
- 检查接口、数据模型、业务行为和验证结论变化是否影响已有需求、设计、规范或知识,同步更新受影响的权威文档;
- 在代码和测试映射中引用相关 `REQ-*`、`DES-*`,但不为追踪编号制造不符合项目风格的代码注释;
- 不虚构内部依赖、组件属性、接口、数据库行为或业务校验;
- 不修改凭据、部署参数和生产配置;
@@ -288,6 +291,7 @@
- 正确性、兼容、安全、性能、并发、事务、权限和数据风险;
- 测试充分性和未验证边界;
- staged、unstaged 和 untracked 的准确区分。
- 实现与当前有效文档的一致性,以及本次影响的长期文档是否已经同步;待审核、过时和历史材料不能冒充当前基线。
对于审核发现:
@@ -441,6 +445,7 @@ G5 批准后:
- 代码效果已通过 G4;
- 提交范围与信息已通过 G5;
- 本地提交已创建并核对内容;
- 本次影响的长期文档已同步,需要作为当前依据的文档审核状态为 `approved`;
- 任务文档已生成关闭预览;已确认的沉淀、归档和删除均已验证,延后项已明确记录;
- 使用独立 Worktree 时,其生命周期已经结束并安全移除;若用户明确要求保留现场,则任务状态应说明生命周期尚未结束及分支占用路径;
- 未发生未经授权的 push、合并、发布、生产操作或历史改写。