Skip to content

docs(agents): Remove duplicated agent rule files - #5930

Merged
runningcode merged 4 commits into
mainfrom
no/dedupe-agent-rule-files
Aug 12, 2026
Merged

docs(agents): Remove duplicated agent rule files#5930
runningcode merged 4 commits into
mainfrom
no/dedupe-agent-rule-files

Conversation

@runningcode

@runningcode runningcode commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

📜 Description

Removes two redundant agent rule files and consolidates the rule index into AGENTS.md.

  • .cursor/rules/coding.mdc — reduced to a pointer at AGENTS.md. Its "Contributing Guidelines", "Coding rules", "Useful Resources", and "Key Commands" sections were near-verbatim duplicates of sections already in AGENTS.md, including the Google Truth paragraph in full. The file stays (with alwaysApply: true) so Cursor still has an entry point.
  • .cursor/rules/overview_dev.mdc — deleted. It described each rule twice (a bullet list per rule, then a keyword→rule table), while every rule file already carries the same information in its own frontmatter description, which is what Cursor uses for auto-selection. It also instructed agents to use fetch_rules, a Cursor-only tool unavailable to other agents.
  • AGENTS.md — the "STOP — Required Reading" block is replaced by a single table mapping each rule to when it applies.
  • CLAUDE.md — updated to match, since it referenced the removed section.

Agents now read one file to get oriented instead of three.

💡 Motivation and Context

The required-reading chain made every session load AGENTS.mdcoding.mdcoverview_dev.mdc before doing anything, and two of those three reads added no information. Duplicated guidance across files also drifts: the same rules were maintained in several places at once.

💚 How did you test it?

I did what Alex suggested, asked claude code which otel modes exist for java sdk? and then which context files did you use so far?, it printed

Two, both read in full at the start of this turn:

1. AGENTS.md — loaded per the instruction in CLAUDE.md (the project CLAUDE.md is injected into context automatically; I read AGENTS.md with the Read tool). It's what pointed me at the opentelemetry rule.
2. .cursor/rules/opentelemetry.mdc — the domain rule for sentry-opentelemetry-*, agent vs agentless, span processing, and OTLP.

📝 Checklist

  • I added GH Issue ID & Linear ID
  • I added tests to verify the changes.
  • No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
  • I updated the docs if needed.
  • I updated the wizard if needed.
  • Review from the native team if needed.
  • No breaking change or entry added to the changelog.
  • No breaking change for hybrid SDKs or communicated to hybrid SDKs.

#skip-changelog

coding.mdc was almost entirely a subset of AGENTS.md: the contributing
guidelines, coding rules, useful resources, and key commands sections were
near-verbatim copies. overview_dev.mdc re-described every rule three times
(once per rule bullet list, once in a keyword table) even though each rule
file already carries the same information in its frontmatter description,
and it pointed agents at fetch_rules, a Cursor-only tool.

Reduce coding.mdc to a pointer, delete overview_dev.mdc, and move the rule
index into AGENTS.md as a single table. Agents now read one file to get
started instead of three.
@sentry

sentry Bot commented Aug 11, 2026

Copy link
Copy Markdown

📲 Install Builds

Android

🔗 App Name App ID Version Configuration
SDK Size io.sentry.tests.size 8.52.0 (1) release

⚙️ sentry-android Build Distribution Settings

Comment thread CLAUDE.md Outdated
@runningcode runningcode added the sanity-check PR needs a lightweight review for obvious issues label Aug 11, 2026
@runningcode
runningcode marked this pull request as ready for review August 11, 2026 10:02
runningcode and others added 2 commits August 11, 2026 14:14
The dedupe commit softened the "STOP — Required Reading" block into a plain
descriptive sentence. In practice an agent then treats AGENTS.md as optional
background and answers questions without ever loading it, which is exactly
what the original wording was there to prevent.

Restore the imperative framing for AGENTS.md only. The old block also listed
coding.mdc and overview_dev.mdc as required reading; those are gone, and the
per-area rule files stay opt-in via the index table in AGENTS.md.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
coding.mdc is alwaysApply: true, making it Cursor's auto-injected entry point —
the same role CLAUDE.md plays for Claude Code. Leaving it descriptive while
CLAUDE.md is imperative means only one of the two agents is actually told to
load AGENTS.md before doing anything.

Phrased tool-neutrally rather than naming the Read tool, since Cursor's
equivalent is read_file.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Comment thread .cursor/rules/coding.mdc Outdated
Comment thread AGENTS.md
Cursor reads a root AGENTS.md automatically, so a .cursor/rules entry
whose only content is 'go read AGENTS.md' instructs Cursor to load a
file it has already merged into context. The domain-specific rules in
.cursor/rules/ are unaffected — they are alwaysApply: false and are
fetched on demand via the index table in AGENTS.md.

CLAUDE.md stays: Claude Code does not read AGENTS.md natively.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@runningcode
runningcode merged commit 4b05f90 into main Aug 12, 2026
69 checks passed
@runningcode
runningcode deleted the no/dedupe-agent-rule-files branch August 12, 2026 08:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

sanity-check PR needs a lightweight review for obvious issues

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants