Codex-Engineering-Skills/.agents/skills/update-project-knowledge/SKILL.md

name, description

name	description
update-project-knowledge	检查已完成的项目工作，并仅在产生已确认、长期有效的信息时更新现有项目知识库。仅在用户显式调用 $update-project-knowledge 进行任务结束或每日收尾检查时使用。

更新项目知识库

检查本次任务或当天工作，并按需同步到项目已有的结构化知识文档。

定位项目

1. 如果用户指定了项目路径，优先使用该路径。
2. 否则从当前目录识别 Git 仓库根目录。
3. 如果当前目录不是 Git 仓库，在工作区内浅层查找：
   • 只有一个仓库时，使用该仓库；
   • 存在多个仓库时，让用户选择；
   • 没有仓库时，将当前项目目录作为目标。
4. 记录目标项目的绝对路径，后续检查只针对该项目。
5. 读取该项目适用的 AGENTS.md。

不要根据文件夹名称猜测项目位置。

定位知识库

按照以下顺序确定知识库位置：

1. 优先使用用户明确指定的目录。
2. 检查 AGENTS.md 是否声明了知识库路径。
3. 检查项目中的 docs/INDEX.md、docs/index.md 或其他文档索引。
4. 如果存在多个可能的知识库，先让用户选择。
5. 如果不存在知识库或文档结构无法确认，停止执行并说明需要先建立知识库。

本 Skill 只更新已有知识库，不擅自创建新的知识库结构。

检查当前状态

执行前记录项目和知识文档已有的未提交变更，不覆盖或回退用户原有修改。

以只读方式检查：

• 当前对话中已经完成的工作；
• 当前项目的 git status --short；
• 与本次任务相关的 git diff；
• 本次任务修改过的文件；
• 已执行的编译、测试或验证结果；
• 必要时检查与本次任务相关的最近提交。

如果项目不是 Git 仓库，则根据当前对话、文件修改和验证结果判断。

不要默认扫描整个项目或整个知识库。

判断是否需要更新

只记录已经确认、以后仍然有用的信息，例如：

• 项目目标、业务场景或主要工作流程变化；
• 模块职责、依赖关系、调用关系或数据流变化；
• 接口、协议、数据结构、单位、坐标系或输入输出变化；
• 已经确认的技术决策及其限制；
• 已定位并验证的问题、原因和解决方案；
• 实际完成进度、当前阻塞项和下一步变化。

如果没有产生长期有效的信息，不修改任何文档，并报告“本次无需更新知识库”。

选择文档

优先读取知识库索引，根据索引确定需要修改的文档。

如果项目采用以下常见文档，可以参考对应关系：

• overview.md：项目背景、目标、场景和整体流程；
• architecture.md：目录结构、模块职责、依赖、调用关系和数据流；
• interfaces.md：接口、协议、数据结构、单位和输入输出；
• decisions.md：技术决策、原因、替代方案和限制；
• problems.md：问题现象、根因、解决方法和验证结果；
• progress.md：已完成、进行中、阻塞项和下一步；
• INDEX.md：知识库导航和文档职责。

这些文件名不是强制要求。项目已有其他结构时，遵循现有索引和文档约定。

只读取并修改与本次变化直接相关的文档，不要默认读取整个知识库。

记录原则

• 只记录能够从代码、配置、测试结果、Git 变更或用户确认中得到支持的信息。
• 重要结论尽量标注相关文件路径、模块、类名或方法名。
• 无法确认的信息标记为“待确认”，不得自行补全。
• 区分“已经实施”和“计划采用”。
• 区分“已解决”和“待解决”。
• 只修改相关章节，不重写整个文档。
• 避免在多个文档中重复保存相同内容。
• 进度文档只保存当前状态，不积累成长篇开发日志。
• 保留文档原有语言、结构和写作风格。

不应记录

不要记录：

• 普通聊天和临时想法；
• 尚未验证的猜测；
• 没有长期参考价值的失败尝试；
• 冗长终端输出、编译日志和完整代码；
• 可以直接从代码中轻易查到的低价值细节；
• 密钥、密码、令牌、私有地址和个人路径。

安全限制

• 只允许修改已经确认的知识库目录。
• 不修改业务代码、配置文件、测试和构建脚本。
• 不修改任何 AGENTS.md。
• 不删除、移动或重命名现有文件。
• 不覆盖或回退执行前已经存在的用户改动。
• 不扫描 .git、日志、缓存、编译产物和第三方依赖。
• 不读取或修改目标项目之外的其他项目，除非用户明确要求。
• 发现知识文档与当前代码存在明显冲突时，说明冲突并保留依据，不直接覆盖原结论。

完成检查

完成后检查本次产生的文件差异，并报告：

1. 本次是否需要更新知识库；
2. 修改了哪些知识文档；
3. 新增或修正了哪些长期信息；
4. 哪些信息仍然待确认；
5. 本次 Skill 是否只修改了知识库目录；
6. 工作区中是否存在执行前就已经存在的其他改动。