From e2d29f60056b8de01dd04089bcc2251ffaa2f9c3 Mon Sep 17 00:00:00 2001 From: "zhiye.sun" Date: Thu, 3 Sep 2026 15:54:44 +0800 Subject: [PATCH] =?UTF-8?q?docs(workflow):=20=E8=A1=A5=E5=85=A8=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E6=8C=81=E7=BB=AD=E7=BB=B4=E6=8A=A4=E6=B5=81=E7=A8=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 4 ++++ README.md | 36 +++++++++++++++++++++--------------- WORKFLOW.md | 9 +++++++-- 3 files changed, 32 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cd1a5d7..5b77e3a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ - `knowledge:document-output` 增加 `register` 与 `close` 模式，使用 `workRoot//task.json` 记录任务状态、文件归属、可见性和关闭处置。 - 增加“保留、沉淀、归档、删除、延后”五类关闭清单，以及共享文件逐项评审、断链检查和精确路径删除门禁。 +- 增加长期文档 `pending`、`approved`、`outdated` 审核状态，以及项目级文档持续维护规范。 ### Planned @@ -31,6 +32,9 @@ - 需求、变更计划、技术设计与 Bug 分析 Skill 统一按项目文档配置选择任务目录；缺少配置时，过程文档回退到 `.craftkit/local/tasks/`，不再根据根目录说明文件推断落点。 - 项目初始化增加文档生命周期默认策略；本地保留天数只用于提示，任务完成默认生成关闭预览，不自动删除文件。 - 需求、计划、设计和分析 Skill 写入文档后登记本地任务记录；沉淀、交接、归档和 Worktree 清理按任务状态联动。 +- 需求与设计 Skill 优先更新已有权威文档；实现、升级和代码审核流程检查留存文档是否因代码或契约变化而需要同步。 +- `task.json` 使用 `created`、`updated`、`referenced` 区分任务关系，关联旧文档不转移所有权，也不产生删除权限。 +- README 的 Skill 说明同步覆盖文档创建、审核、持续更新、历史归档和关闭职责。 ## [1.3.0] - 2026-08-31 diff --git a/README.md b/README.md index 07a21d4..6784062 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,12 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档 - [新项目初始化与应用拆分工作流](NEW-PROJECT-INITIALIZATION-AND-APPLICATION-SPLIT.md)：适用于空目录、新仓库或尚未形成有效源码结构的项目。 - [已有项目初始化与应用拆分工作流](EXISTING-PROJECT-INITIALIZATION-AND-APPLICATION-SPLIT.md)：适用于已有源码、数据、接口和部署形态，需要基于现状渐进拆分的项目。 +## 文档维护流程 + +CraftKit 按“初始化约定 → 创建或更新 → 审核生效 → 随实现持续维护 → 关闭时分类处置”管理项目文档。过程材料默认保存在本地任务目录；正式需求、生效设计、项目规范和长期知识保存审核状态，后续任务优先更新已有权威文档。 + +长期文档使用 `pending`、`approved`、`outdated` 表示待审核、当前有效和已知过期。任务关闭不结束文档维护；实现、接口、数据模型或业务行为变化时，需要检查并同步相关留存文档。详细规则由项目 `.craftkit/standards/document-maintenance.md` 维护。 + ## 插件组成 | 插件 | 用途 | @@ -31,20 +37,20 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档 | Skill | 用途 | | --- | --- | -| `plan-change` | 分析需求或问题的影响范围、依赖、风险和验证方式，形成可执行的变更计划。 | -| `design-backend` | 设计后端模块边界、服务职责、事务、错误处理及数据影响。 | -| `design-frontend` | 设计前端页面、路由、状态、交互、组件组合和数据流。 | -| `design-api` | 设计或评审 HTTP API 的资源、方法、状态码和请求响应契约。 | -| `design-db` | 设计或评审数据库表、约束、索引及变更与回滚方案。 | +| `plan-change` | 分析影响范围并创建或更新可执行的变更计划，登记关联文档。 | +| `design-backend` | 创建或更新后端设计，覆盖模块边界、事务、错误处理及数据影响。 | +| `design-frontend` | 创建或更新前端设计，覆盖页面、路由、状态、交互和数据流。 | +| `design-api` | 创建、更新或评审 HTTP API 契约，并维护其审核状态。 | +| `design-db` | 创建、更新或评审数据设计及变更与回滚方案。 | | `design-frontend-data` | 设计前端请求边界、视图模型、状态所有权、缓存和并发处理。 | | `design-workflow` | 设计业务流程的任务、状态转换、权限、回退、撤回和审计规则。 | | `prepare-api` | 整理前后端接口清单、字段映射、类型转换、缺失项和联调风险。 | | `component` | 根据项目依赖和现有用法选择组件，查证 props、events 和 slots。 | | `form` | 设计或检查表单分组、布局、条件字段、错误展示和可访问性。 | | `style` | 根据项目视觉基线设计颜色、排版、间距、主题和响应式样式。 | -| `implement-backend` | 按项目语言、框架和规范编写或修改后端代码。 | -| `implement-frontend` | 按项目框架、组件契约和请求封装编写或修改前端代码。 | -| `review-code` | 审查工作区、提交或分支变更中的正确性、兼容、安全、性能和测试问题。 | +| `implement-backend` | 修改后端代码，并同步检查受影响的需求、设计、规范和知识。 | +| `implement-frontend` | 修改前端代码，并同步检查受影响的需求、设计、规范和知识。 | +| `review-code` | 审查代码质量，以及实现与当前有效文档的一致性。 | | `review-java` | 专项评审 Java 代码的资源管理、并发、异常和可维护性。 | | `review-mybatis` | 专项评审 Mapper、动态 SQL、参数映射、事务边界和查询性能。 | | `review-frontend` | 专项评审前端组件边界、状态、渲染、交互、可访问性和性能。 | @@ -64,8 +70,8 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档 | `md-to-docx` | 将 Markdown 转换为可编辑的 Word `.docx` 文档。 | | `xlsx-to-md` | 将 Excel `.xlsx` 工作簿按工作表转换为 Markdown 表格。 | | `format-md` | 修正 Markdown 的标题、空行、列表、代码块、表格和链接格式。 | -| `archive` | 按明确规则复制、重命名、清理或拆分项目文档并生成报告。 | -| `requirements` | 将技术说明、会议材料或问题描述整理成可确认的需求说明。 | +| `archive` | 按明确规则归档历史快照，保留勘误和当前版本链接。 | +| `requirements` | 创建或更新可审核的需求说明，避免产生冲突的平行文档。 | | `report` | 根据事实、Git 记录和任务状态撰写工作汇报或阶段总结。 | | `message` | 根据事件、受众和行动要求起草通知、提醒、确认或故障沟通消息。 | @@ -88,11 +94,11 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档 | Skill | 用途 | | --- | --- | -| `init` | 初始化或更新项目的 `AGENTS.md` 与 `.craftkit/` 项目资料。 | -| `document-output` | 查看或维护文档配置，登记任务文档，并在完成时预览沉淀、归档与清理。 | +| `init` | 初始化或更新项目上下文、文档目录和持续维护约定。 | +| `document-output` | 管理文档落盘、任务关联、审核状态、持续更新和关闭处置。 | | `handoff` | 生成可持续更新的任务交接文档和新任务接续提示词。 | -| `distill` | 从任务证据中提炼可复用结论、决策和问题经验。 | -| `lessons` | 初始化、维护和审计项目问题经验库。 | +| `distill` | 从任务证据提炼知识，并更新、替代或标记已有结论。 | +| `lessons` | 初始化、修订、标记过时和审计项目问题经验库。 | | `trace` | 复盘 Agent 的偏离、漏读或规则失效，并提出改进建议。 | | `worklog` | 根据指定日期、时区和作者的 Git 提交生成工作日志。 | @@ -102,7 +108,7 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档 | Skill | 用途 | | --- | --- | -| `guidance` | 检索项目协作说明、项目资料和公共基线，返回可追溯的规则、冲突与缺口。 | +| `guidance` | 检索当前有效的项目规则和知识，区分待审核、过时与历史材料。 | | `guidance-edit` | 建立、检查和维护 `.craftkit/standards/` 规范索引。 | ## 目录结构 diff --git a/WORKFLOW.md b/WORKFLOW.md index 6b61768..fb013cc 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -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、合并、发布、生产操作或历史改写。