repo-doc-maintainer

Repo 文档维护者

概述

审查最新的本地更改，判断这些更改是否引入了稳定且影响整个仓库的知识，并且仅在这些知识有助于下一位贡献者安全地开展工作时，才更新项目级文档（AGENTS.md、CLAUDE.md 或同类文档）。

文档应简洁、信息密度高。不要把任何文件写成变更日志、功能介绍或实现细节汇总。

工作流

1. 检查最新的变更集。
2. 对照项目文档中的现有指南，检查这些变更。
3. 判断这些变更是否引入了未来贡献者需要了解的高层知识。
4. 仅在适当的文档中，以恰当的抽象层级进行更新。
5. 总结更改内容，或明确说明无需更新文档。

检查变更集

先检查本地差异。优先采用能回答问题的最小范围：

• git status --short
• git diff --stat
• git diff -- <path>
• git log -1 --stat

如果用户询问的是已合并或已提交的工作，请检查相关提交或提交范围。

编辑文档前，先阅读受影响的代码。不要仅凭文件名推断新规则。

判断是否需要更新文档

仅针对持久、可复用的指南更新文档，例如：

• 新的架构模式或分层规则
• 新的依赖项或整个仓库采用的新技术
• 新的必需验证步骤或工作流步骤
• 新的 DI、路由、状态、API、持久化或测试约定
• 细微、可重复且可能导致回归的新注意事项
• 重要行为的新权威来源位置

以下情况不要更新文档：

• 单次功能的细节
• 临时变通方案，除非它是当前仓库的约束
• 逐文件摘要
• 命名方面的琐事
• 从代码中显而易见的底层实现细节
• 现有文档已充分涵盖的更改

使用以下标准进行判断：如果下一位具备相应能力的贡献者在不了解这些信息时很可能会犯错，而且这条指南在单个功能之外仍然有用，就将其写入文档。

选择合适的文件

当指南需要出现在最精简、最易查阅的仓库概览中时，更新 AGENTS.md（或 CLAUDE.md）：

• 稳定的架构约束
• 仓库级规则
• 强制验证命令
• 简短的「重要事项」提醒

如果既没有 AGENTS.md 也没有 CLAUDE.md，且确实需要更新文档，则在仓库根目录创建 AGENTS.md，仅包含符合上述标准的指南。不要为不够重要的内容创建该文件。

新增内容应简洁。优先使用单条项目符号或短句。

如果指南需要更多说明，则更新入门文档或开发者文档：

• 决策规则
• 示例
• 注意事项
• 工作流细节
• 有助于新贡献者正确应用规则的理由

如果某条规则同时适用于两个文件，则在 AGENTS.md 中放置最精简的提醒，并在入门文档中提供更完整的说明。

编辑规则

• 保持文档高层、避免重复。
• 保留现有语气和结构。
• 将新指南整合到最相关的现有章节，不要随意追加备注。
• 如果某个概念已有相关项目符号，优先修改或精简该条，而不是新增内容。
• 避免在同一文件的多个章节重复同一规则。
• 不要记录推测性的模式。规则必须已在代码或工作流中体现。

输出要求

审查后，报告以下结果之一：

• 无需更新文档，并简要说明原因
• 已更新 AGENTS.md / CLAUDE.md
• 已更新入门文档
• 两者均已更新

更新文档时，请描述新增的、影响整个仓库的指南，而不是逐文件罗列差异。

文档更新标准

使用此标准评估近期更改是否值得写入项目级文档。

合适的候选内容

• 新的全仓库 API 或数据访问模式
• 影响多个功能的新状态管理规则
• 新的依赖注入注册要求
• 新的路由或引导约束
• 新的持久化、本地化或测试约定
• 新的验证命令、CI 要求或测试约定
• 通过实际工作发现的、新的隐蔽回归陷阱

不合适的候选内容

• 单个屏幕的实现细节
• 私有辅助函数的提取
• 不改变行为的重命名或代码移动
• 临时实验
• 特定功能的文案或资源更改
• 不能代表更广泛仓库约定的仅测试细节

要问的问题

1. 一个月后这仍然重要吗？
2. 这会影响多个文件、功能或未来任务吗？
3. 跳过这条指引的贡献者是否很可能会犯下实际错误？
4. 这条规则是否已在某份文档中清晰说明？
5. 能否在不讲解实现方式的前提下，概括地说明这条规则？

如果前三个问题的答案大多是肯定的，就记录下来。如果最后两个问题的答案是否定的，就谨慎而简洁地记录。