项目知识维护专家

项目知识维护专家 是做什么的？

目的

使用此技能初始化、维护和演化项目级知识库，供AI编程代理使用。知识库帮助未来的代理会话理解项目目的、架构、接口、决策、Bug和近期变更，而无需从头重新发现所有信息。

保持工作流工具无关性。应能被Codex、Claude Code、Cursor、Gemini CLI及其他可读取项目文件并遵循仓库本地指令的编程代理使用。

何时使用

当用户要求以下操作时使用此技能：

• 初始化项目知识库
• 总结或文档化项目
• 修复Bug并保留修复经验
• 添加或更改功能
• 添加或更改API、模式、命令或数据格式
• 记录技术决策或权衡
• 将原始项目材料组织为结构化知识
• 回顾或复盘已完成的开发会话
• 更新AGENTS.md或knowledge/下的文件

输入

常见输入包括：

• 当前仓库或目标项目路径。
• 现有项目文件、源代码、文档、问题、日志或原始材料。
• 用户的当前任务以及会话期间所做的任何实现更改。
• 已有的AGENTS.md、knowledge/、raw/或skills/内容（如存在）。

输出

预期输出包括：

• AGENTS.md项目规则。
• knowledge/overview.md项目概述。
• knowledge/business.md业务逻辑和使用场景。
• knowledge/architecture.md系统架构和数据流。
• knowledge/api.md接口、模式、命令和数据结构。
• knowledge/decisions.md技术决策和权衡。
• knowledge/bugs.mdBug历史、根本原因、修复和预防规则。
• knowledge/changelog.md会话级变更记录。
• 可选的raw/和项目本地skills/文件夹。
• 一份简短的最终报告，列出已更新的内容和仍需验证的内容。

工作流程

1. 首先读取项目规则：
   • AGENTS.md（如存在）。
   • knowledge/overview.md
   • knowledge/architecture.md
   • knowledge/decisions.md
   • knowledge/bugs.md
2. 如果初始化仓库，请使用references/templates/中的模板或运行此包中的初始化脚本。
3. 理解当前任务并识别已更改的内容：
   • 项目目标或业务逻辑
   • 架构或模块边界
   • API、命令、数据文件、模式或返回结构
   • Bug症状、根本原因、修复或预防规则
   • 技术决策或权衡
   • 用户可见行为或UI约定
4. 仅更新相关的知识文件。
5. 删除或调和重复、过时或矛盾的内容。
6. 完成重要工作后始终更新knowledge/changelog.md。
7. 报告已更新的文件和任何缺失的验证。

有关更详细的维护指南，请阅读references/playbook.md。

更新knowledge/

使用与变更匹配的最小文件：

• 更新overview.md以涵盖长期项目目的、范围、主要模块和主要输出。
• 更新business.md以涵盖用户场景、工作流、领域规则和安全边界。
• 更新architecture.md以涵盖模块关系、数据流、运行时模式和集成边界。
• 更新api.md以涵盖端点、函数、命令、事件、数据文件、模式和返回结构。
• 更新decisions.md以涵盖有意义的技术选择和权衡。
• 更新bugs.md以涵盖已确认的Bug和经验教训。
• 每次重要任务总结后更新changelog.md。

不要将临时推理内容转储到知识库中。优先保存稳定的事实、经过验证的决策和可复用的经验。

Bug回顾

当Bug修复后，更新knowledge/bugs.md，包含：

• 问题症状。
• 根本原因。
• 修复方法。
• 影响范围。
• 执行的验证。
• 防止复发的规则。

如果根本原因不确定，请标记为“待验证”，而非猜测。

接口变更

当API、命令、函数、模式、CSV、事件或文件格式变更时，更新knowledge/api.md，包含：

• 接口名称。
• 请求方法或调用方式。
• 路径、命令、函数名称或文件路径。
• 输入和参数。
• 响应或输出格式。
• 注释、约束和示例。

使用准确的名称和字段拼写。

技术决策

当做出有意义的技术选择时，更新knowledge/decisions.md，包含：

• 决策背景。
• 考虑的选项。
• 最终选择。
• 选择理由。
• 后果和后续工作。

记录有助于未来代理避免重新讨论已定问题的决策。

避免知识腐烂

• 优先编辑现有条目，而非添加近似重复条目。
• 将过时内容标记为已取代，或用当前事实替换。
• 将项目事实与推测分离。
• 对决策、Bug和变更日志条目使用日期。
• 保持措辞代理中立，除非特定工具集成需要工具特定注释。
• 未经明确请求，不要覆盖用户编写的项目规则。

最终响应

保持最终响应简洁。包含：

• 已更新的文件。
• 执行的验证。
• 任何剩余的检查项。