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.
Workflow
- Inspect the latest change set.
- Compare the change against the current guidance in the project's documentation files.
- Decide whether the change introduced new high-level knowledge that future contributors need.
- Update only the appropriate document and only at the correct level of abstraction.
- Summarize what changed or explicitly say no doc update is needed.
Inspect The Change Set
Check the local diff first. Prefer the smallest scope that answers the question:
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.
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.
Choose The Right File
Update
(or
) 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.
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.
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.
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
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
- Would this still matter in a month?
- Does this affect more than one file, feature, or future task?
- Would a contributor who skips this guidance likely make a real mistake?
- Is the rule already captured clearly in one of the docs?
- 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.