Skip to content

docs(agents): tighten code comment rules against stale anchors - #35

Merged
sha1n merged 1 commit into
masterfrom
docs/comment-anchoring-rules
Aug 4, 2026
Merged

docs(agents): tighten code comment rules against stale anchors#35
sha1n merged 1 commit into
masterfrom
docs/comment-anchoring-rules

Conversation

@sha1n

@sha1n sha1n commented Aug 4, 2026

Copy link
Copy Markdown
Owner

Summary

Rewrites the Code Comments section of the global agent instructions to address a recurring problem: agents adding comments anchored to line numbers, positions, and other volatile references that go stale as the code moves.

Changes

  • Flips the default from "comments must earn their place" to "no comment by default", so the burden is explicitly on adding one.
  • Adds an enumerated never-anchor list (line numbers, position words, other modules' internals, versions/tickets, the change itself). The previous abstract phrasing wasn't binding — an agent doesn't recognize // see the guard above as an instance of "avoid volatile references".
  • Exempts public-interface doc comments (JSDoc, docstrings, godoc) from the default, so the stricter rule doesn't suppress API documentation on exported surfaces.
  • Kept to ~195 words. This file loads into every session, so section length competes with the other rules for attention.

Two clauses to watch in practice: the above/below bullet may misfire on legitimate prose, and the doc-comment exemption is the most stretchable escape hatch.

@sha1n sha1n added the documentation Improvements or additions to documentation label Aug 4, 2026
@sha1n sha1n self-assigned this Aug 4, 2026
@sha1n
sha1n merged commit b1adf5a into master Aug 4, 2026
2 checks passed
@sha1n
sha1n deleted the docs/comment-anchoring-rules branch August 4, 2026 05:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant