docs: require checking comment-policy.md before editing comments#3202
Conversation
Strengthens the existing reminder so agents look for comment-policy.md explicitly and run /comment-audit to validate changes, instead of relying on the bare 'follow comment-policy.md' wording.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2574935786
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| ## Comments | ||
|
|
||
| Follow `comment-policy.md`. Short version: write comments only when they encode information the code cannot express (invariants, business rules, non-local coupling, refactor-sensitive rationale). Don't paraphrase the next line. Use `AIDEV-NOTE:` anchors for rules that must survive future agent edits. Treat stale comments as bugs. | ||
| **Always check for `comment-policy.md` at the repo root (or any ancestor of files you're touching) before adding, removing, or rewording comments.** The policy overrides defaults. Run `/comment-audit` to validate comment changes against it before commit. |
There was a problem hiding this comment.
When an agent edits comments in a fresh checkout, this new instruction makes /comment-audit a required pre-commit validation step, but I searched the repo for comment-audit and for project slash-command directories and found no command or script defining it. Agents following the policy will either fail the requested validation or have to ignore a root instruction; add the project command/script or make the validation wording point to an available check.
Useful? React with 👍 / 👎.
1 participant
Strengthens the agent-facing reminder in
CLAUDE.md(andAGENTS.md, which is a symlink) so agents look forcomment-policy.mdexplicitly and run/comment-auditto validate changes, instead of relying on the bare "follow comment-policy.md" wording.Same pattern we use for
brand.md("always follow brand.md when a project has one") - having the policy file is only useful if agents reliably read it before touching comments.