Back to Details

repo-doc-maintainer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Repo Doc Maintainer

代码仓库文档维护规范

Overview

概述

Review the latest local changes, classify whether they introduced stable repo-shaping knowledge, and update project-level documentation (AGENTS.md, CLAUDE.md, or equivalent) only when that knowledge would help the next contributor work safely.
Keep docs compact and high signal. Do not turn any file into a changelog, feature walkthrough, or implementation dump.
检查最新的本地变更，判断这些变更是否带来了稳定的仓库建设相关知识，仅当这些知识能够帮助后续贡献者安全开展工作时，才更新项目级文档（AGENTS.md、CLAUDE.md或等价文档）。
保持文档精简、高信息量。不要将任何文件变成更新日志、功能讲解或者实现细节堆砌的内容。

Workflow

工作流

  1. Inspect the latest change set.
  2. Compare the change against the current guidance in the project's documentation files.
  3. Decide whether the change introduced new high-level knowledge that future contributors need.
  4. Update only the appropriate document and only at the correct level of abstraction.
  5. Summarize what changed or explicitly say no doc update is needed.
  1. 检查最新的变更集
  2. 将变更与项目文档文件中现有的指引进行比对
  3. 判断变更是否带来了未来贡献者需要了解的新高阶知识
  4. 仅更新对应的文档，且仅保留正确抽象层级的内容
  5. 总结变更内容，或者明确说明无需更新文档

Inspect The Change Set

检查变更集

Check the local diff first. Prefer the smallest scope that answers the question:
  • git status --short
  • git diff --stat
  • git diff -- <path>
  • git log -1 --stat
If the user asks about merged or already committed work, inspect the relevant commit or commit range instead.
Read the affected code before editing docs. Do not infer a new rule from filenames alone.
Check the local diff first. Prefer the smallest scope that answers the question:
  • git status --short
  • git diff --stat
  • git diff -- <path>
  • git log -1 --stat
如果用户询问的是已合并或已提交的工作，则检查对应的提交或提交范围。
编辑文档前先阅读受影响的代码，不要仅通过文件名推断新规则。

Decide Whether Docs Should Change

判断是否需要更新文档

Update docs only for durable, reusable guidance such as:
  • a new architectural pattern or layering rule
  • a new dependency or repo-wide technology choice
  • a new required validation or workflow step
  • a new DI, routing, state, API, persistence, or testing convention
  • a new gotcha that is subtle, repeatable, and likely to cause regressions
  • a new location of truth for important behavior
Do not update docs for:
  • one-off feature details
  • temporary workarounds unless they are active repo constraints
  • file-by-file summaries
  • naming trivia
  • low-level implementation mechanics that are obvious from code
  • changes that are already captured adequately in existing docs
Use this test: if the next competent contributor would likely make a mistake without knowing this, and the guidance remains useful beyond one feature, document it.
仅针对持久、可复用的指引更新文档，比如：
  • 新的架构模式或分层规则
  • 新的依赖或仓库全域技术选型
  • 新的必填校验或工作流步骤
  • 新的DI、路由、状态、API、持久化或测试约定
  • 新的易踩坑点：隐蔽、容易重复触发且可能导致回归问题的内容
  • 重要行为新的权威参考位置
不要为以下内容更新文档：
  • 一次性的功能细节
  • 临时的解决方案，除非它们是当前仓库生效的约束
  • 逐文件的变更总结
  • 命名相关的琐碎内容
  • 从代码就能明显看出的低层级实现机制
  • 现有文档已经充分涵盖的变更
可以用这个测试判断：如果下一位合格的贡献者不知道这个信息就很可能犯错，且该指引的价值不止适用于单个功能，那就记录下来。

Choose The Right File

选择正确的文件

Update 
AGENTS.md
(or 
CLAUDE.md
) when the guidance should be visible in the fastest possible repo brief:
  • stable architectural constraints
  • repo-wide rules
  • mandatory validation commands
  • short "what matters" reminders
Keep additions terse. Prefer a single bullet or short sentence.
Update onboarding or developer docs when the guidance needs more explanation:
  • decision rules
  • examples
  • gotchas
  • workflow detail
  • rationale that helps a new contributor apply the rule correctly
If a rule belongs in both files, put the shortest possible reminder in AGENTS.md and the fuller explanation in the onboarding doc.
当指引需要在最快速的仓库简介中展示时，更新
AGENTS.md
（或
CLAUDE.md
）：
  • 稳定的架构约束
  • 仓库全域规则
  • 强制校验命令
  • 简短的「核心注意事项」提醒
新增内容保持简洁，优先使用单个要点或者短句。
当指引需要更多解释时，更新新人上手文档或开发者文档：
  • 决策规则
  • 示例
  • 易踩坑点
  • 工作流细节
  • 帮助新贡献者正确应用规则的底层逻辑
如果某个规则需要同时出现在两个文件中，在AGENTS.md中放尽可能简短的提醒，在新人上手文档中放完整的解释。

Editing Rules

编辑规则

  • Keep docs high level and DRY.
  • Preserve existing tone and structure.
  • Integrate new guidance into the most relevant existing section instead of appending random notes.
  • Prefer editing or tightening an existing bullet before adding a new one when the concept already exists.
  • Avoid repeating the same rule in multiple sections of the same file.
  • Do not document speculative patterns. The rule should already exist in code or workflow.
  • 保持文档高阶、遵循DRY原则
  • 保留现有的语气和结构
  • 将新指引整合到最相关的现有章节中，不要随意追加零散笔记
  • 当相关概念已经存在时，优先编辑或收紧现有要点，再考虑新增要点
  • 避免在同一个文件的多个章节重复相同规则
  • 不要记录推测性的模式，规则必须已经在代码或工作流中落地

Output Expectations

输出要求

After review, report one of these outcomes:
  • no doc update needed, with a brief reason
  • updated AGENTS.md / CLAUDE.md
  • updated onboarding docs
  • updated both
When you update docs, describe the repo-shaping guidance you added, not a file-by-file diff dump.
评审完成后，反馈以下其中一种结果：
  • 无需更新文档，附带简短理由
  • 已更新AGENTS.md / CLAUDE.md
  • 已更新新人上手文档
  • 已更新两类文档
更新文档时，描述你新增的仓库建设指引，不要输出逐文件的diff详情。

Doc Update Criteria

文档更新判定标准

Use this rubric when deciding whether a recent change deserves documentation in project-level docs.
判断近期变更是否需要记录到项目级文档时使用以下标准：

Good Candidates

合适的更新场景

  • New repo-wide API or data-access pattern
  • New state-management rule that affects multiple features
  • New dependency-injection registration requirement
  • New routing or bootstrap constraint
  • New persistence, localization, or testing convention
  • New validation command, CI expectation, or test convention
  • New subtle regression trap discovered through real work
  • 新的仓库全域API或数据访问模式
  • 影响多个功能的新状态管理规则
  • 新的依赖注入注册要求
  • 新的路由或启动约束
  • 新的持久化、本地化或测试约定
  • 新的校验命令、CI要求或测试约定
  • 实际工作中发现的新的隐蔽回归陷阱

Weak Candidates

不合适的更新场景

  • Single-screen implementation detail
  • Private helper extraction
  • Renaming or code movement with no behavior change
  • Temporary experiment
  • Feature-specific copy or asset changes
  • Test-only detail that does not represent a broader repo convention
  • 单页面的实现细节
  • 私有辅助函数的提取
  • 无行为变更的重命名或代码移动
  • 临时实验
  • 特定功能的文案或资产变更
  • 不代表更广泛仓库约定的仅测试相关细节

Questions To Ask

需要询问的问题

  1. Would this still matter in a month?
  2. Does this affect more than one file, feature, or future task?
  3. Would a contributor who skips this guidance likely make a real mistake?
  4. Is the rule already captured clearly in one of the docs?
  5. Can this be stated at a high level without teaching the implementation?
If the answer to the first three is mostly yes, document it. If the last two are no, document it carefully and concisely.
  1. 一个月后这条规则还有意义吗？
  2. 它会影响不止一个文件、功能或者未来任务吗？
  3. 如果贡献者忽略这条指引，是不是很可能真的犯错误？
  4. 这条规则是不是已经在某份文档中清晰记录了？
  5. 能不能在不讲解实现细节的情况下高阶表述这条规则？
如果前三个问题的答案基本为「是」，就记录下来。如果最后两个答案为「否」，就谨慎、简洁地记录。