feat(knowledge): 接入文档持续维护约定

2026-09-03 15:54:12 +08:00
parent 0eaccca7cf
commit 9060fe5222
18 changed files with 61 additions and 19 deletions
@@ -17,6 +17,7 @@
 - 项目规范：`.craftkit/standards/index.md`
 - 可复用知识：`.craftkit/knowledge/index.md`
 - 共享设计文档：`.craftkit/designs/`；开发中过程文档使用 `.craftkit/project.json` 配置的 `documents.workRoot`。
+- 文档维护规则：`.craftkit/standards/document-maintenance.md`；修改实现时检查并同步受影响的长期文档。

 ## 工作约束

@@ -2,14 +2,15 @@

 本目录保存当前项目可供 Agent 使用的配置、规范、知识和交接内容。

- `project.json`：项目类型、技术栈、代码边界、依赖标识和命令。
+- `project.json`：项目类型、技术栈、代码边界、依赖标识、命令和文档生命周期默认策略。
 - `agents/`：项目对 Agent 的补充指令。
 - `standards/`：项目自身的开发、测试、文档与 Git 规范。
+- `standards/document-maintenance.md`：长期文档的审核、持续更新、替代和关闭约定。
 - `standards/frontend/components.md`：经确认的前端组件来源、版本和契约证据索引。
 - `knowledge/`：经过验证的技术决策和可复用经验。
 - `designs/`：用户明确要求共享或正式交付的设计文档。
 - `handoff/`：用户明确选择共享的任务交接。
- `local/`：当前工作副本的过程文档和本地上下文，不进入 Git。
+- `local/`：当前工作副本的过程文档、任务记录和本地上下文，不进入 Git。
 - `cache/`：可重新生成的缓存，不进入 Git。

 共享资料不得包含凭据、个人机器绝对路径或无必要的业务数据。
@@ -0,0 +1,31 @@
+---
+reviewStatus: pending
+reviewedAt: null
+replacedBy: null
+---
+
+# 文档维护规范
+
+## 适用范围
+
+本规范适用于项目正式需求、生效设计、项目规范和长期知识。过程草稿按任务需要维护，不强制逐份审核；历史归档保留当时快照，不作为当前依据。
+
+## 创建与更新
+
+- 任务开始时查找相关已有文档，优先更新现有权威内容，不创建同义平行版本。
+- 新建或实质修改长期文档后，将文档自身的 `reviewStatus` 标为 `pending`。
+- 项目已有审批结果可以直接作为审核依据；通过后标为 `approved`。
+- 已知文档与需求、实现或新证据不一致时标为 `outdated`；更新后回到 `pending` 并重新审核。
+- 排版、错字、链接修复和不改变含义的调整不改变审核状态。
+
+## 状态与替代
+
+项目没有既有元数据格式时，在文档 Frontmatter 使用 `reviewStatus`、`reviewedAt` 和 `replacedBy`。旧文档缺少状态时视为尚未确认，只在实际使用或修改时补齐。
+
+新版替代旧版时更新索引和引用，并通过 `replacedBy` 指向当前版本。旧版根据历史价值归档或删除；归档发现错误时补充勘误和新版链接，不改写历史事实。
+
+## 任务关联与关闭
+
+本地 `task.json` 记录本次创建、更新或引用的文档。关联旧文档不转移所有权，也不产生删除权限。
+
+任务关闭前检查本次实现影响的长期文档已经同步。需要作为当前依据的文档必须为 `approved`；`pending` 或 `outdated` 文档应完成处理，无法处理时列入延后清单并说明影响。
@@ -2,6 +2,8 @@

 当前没有已验证的项目知识。只收录有证据、适用范围明确且能够复用的技术决策与经验。

+长期知识按 `.craftkit/standards/document-maintenance.md` 保存审核状态并持续更新；过时或历史材料不得作为当前有效依据。
+
 - 问题经验按需建立在 `pitfalls/`，不预建空分类。
 - 重要技术决策按需建立在 `decisions/`。
 - 其他长期知识应优先并入已有主题，避免同义平行文档。
@@ -1,3 +1,5 @@
 # 项目规范索引

-当前没有项目专属规范。新增规范时记录主题、适用范围、规则文件和优先级；未覆盖主题可由 `guidance` 查询中性公共基线。
+- [文档维护规范](document-maintenance.md)：正式需求、设计、规范和长期知识的创建、审核、更新、替代及任务关闭规则。
+
+新增规范时记录主题、适用范围、规则文件和优先级；未覆盖主题可由 `guidance` 查询中性公共基线。