docs: Revamp root and nested AGENTS.md - #6666
Open
antonis wants to merge 4 commits into
Open
Conversation
Address #6638. Add the three high-value sections the "great AGENTS.md" checklist calls for and that were missing: a three-tier ✅/⚠️ /🚫 Boundaries section, a Skills-load-on-demand index, and a hybrid-SDK Stack framing that points at live version sources rather than copying rot-prone version strings. Fix a drifted diagnostics example (logger -> debug) and add a skill-precedence pointer in packages/core. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
Semver Impact of This PR⚪ None (no version bump detected) 📋 Changelog PreviewThis is how your changes will appear in the changelog.
Plus 3 more 🤖 This preview updates automatically when you update the PR. |
Contributor
Extend the AGENTS.md revamp to the nested surface files: add a skill-precedence pointer and scoped Boundaries to android/ and ios/, fix drifted bridge examples to the real `SentryReactNative` reject code, and correct/expand the sample run commands (New/Old Arch toggle for RN, real run:ios/run:android scripts for Expo). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the bare pod-install note with the sample's actual `yarn pod-install-<debug|release>-<static|dynamic>[-legacy]` script matrix, mapping each axis to the env it sets (ENABLE_PROD, USE_FRAMEWORKS, ENABLE_NEW_ARCH). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
Author
|
@sentry review |
There was a problem hiding this comment.
🟡 Changes recommended
The Android bridge example says to “catch everything” but only catches Exception, which is inconsistent with the stated boundary guidance and the repo’s own catch (Throwable ...) practice.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Docs-only refresh of the repository’s agent operating manuals (AGENTS.md + nested surface-specific AGENTS.md files) to better capture non-derivable boundaries, stack framing, and when to load each specialist skill, with updated examples aligned to current code.
Changes:
- Added explicit repo-wide and surface-specific “Boundaries” (Always / Ask first / Never) and a “Skills — load on demand” index to guide agent decision-making.
- Updated native-bridge examples (Android/iOS) to use the shared reject error code (
SentryReactNative) and refreshed sample-app run guidance (RN + Expo). - Refined core-package diagnostics guidance to prefer
debug(vslogger) in the TurboModule/bridge hot path.
File summaries
| File | Description |
|---|---|
AGENTS.md |
Reframed as a hybrid SDK, added stack framing, boundaries, and a skills index. |
packages/core/AGENTS.md |
Added skill precedence note and updated diagnostics examples to use debug. |
packages/core/android/AGENTS.md |
Added skill precedence + boundaries; refreshed bridge reject-code example. |
packages/core/ios/AGENTS.md |
Added skill precedence + boundaries; refreshed bridge reject-code example. |
samples/react-native/AGENTS.md |
Documented iOS pod-install build matrix scripts and Android new-arch toggle for verification coverage. |
samples/expo/AGENTS.md |
Clarified dev-client run commands and why Expo Go alone isn’t sufficient for native SDK changes. |
Review details
- Files reviewed: 6/6 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit a6148f7. Configure here.
antonis
changed the title
The example caught Exception while the boundary rule says to catch everything and the module code (RNSentryModuleImpl) catches Throwable throughout — an Error would otherwise crash the app. Flagged by Copilot. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
antonis
marked this pull request as ready for review
September 3, 2026 10:14
antonis
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📢 Type of change
📜 Description
Revamps the agent operating manual (
AGENTS.md, symlinked asCLAUDE.md) and all nestedAGENTS.mdfiles against the "how to write a great AGENTS.md" checklist.Root
AGENTS.md:## Boundaries— a three-tier ✅ Always /## Skills — load on demand— an index mapping each local skill (spec,design-first,code-guidelines,test-guidelines,review,diagnosing-bugs) to when to reach for it, plus a note on the remote specialists pulled viaagents.toml.## Stack— reframes the intro as a hybrid SDK (TS/JS wrapping sentry-cocoa + sentry-android/java via the bridge) and, rather than copying rot-prone version strings, points at the live sources:packages/core/package.jsonfor JS/peer versions and the release-generatedSDK-VERSIONS.mdfor bundled native versions..yalcreference) and refined the CHANGELOG rule so notable internal changes land under### Internalrather than being excluded outright.packages/core/AGENTS.md:logger(the Logs API — recurses in the bridge hot path) todebug, matching the SDK's own source (52 files import{ debug }from@sentry/core) and the file's own TurboModule warning.Nested surface + sample files:
packages/core/android/AGENTS.md&packages/core/ios/AGENTS.md— added the skill-precedence pointer and a scoped Boundaries block (each tailored to its surface), and fixed drifted bridge examples: the real reject error code is the sharedSentryReactNative, not a per-methodOPERATION_FAILED; dropped the iOS[SentryLog logWithMessage:]snippet that appears nowhere in the ObjC layer.src/oldarch/+src/newarch/, catch-and-rejectat every@ReactMethod, gate PII, keep the codegen ABI mirrored/backward-compatible, and don’t hand-bumpio.sentry:sentry-android(usescripts/update-android.sh).Promisehangs the JS caller), catch native exceptions, gate PII, route hybrid-SDK access throughRNSentryInternalinstead ofPrivateSentrySDKOnly, and don’t hand-bump sentry-cocoa (usescripts/update-cocoa.sh).samples/react-native/AGENTS.md— documented the iOSyarn pod-install-<debug|release>-<static|dynamic>[-legacy]build matrix (each script setsENABLE_PROD/USE_FRAMEWORKS/ENABLE_NEW_ARCH) and the AndroidnewArchEnabledtoggle, so a native change gets verified across the combinations it affects.samples/expo/AGENTS.md— added the realrun:ios/run:androidscripts and the dev-client caveat (native code means plain Expo Go isn't enough).💡 Motivation and Context
Closes #6638. The always-loaded manual was missing the highest-value guidance (boundaries, when to load which skill) and had drifted from the code in places. Version numbers are deliberately not copied into prose — they point at existing sources so they can't rot into confident falsehoods in a file agents treat as ground truth.
💚 How did you test it?
Docs-only change. Every factual claim was verified against the codebase: package/peer/native versions against
package.json/RNSentry.podspec/build.gradle; all referenced skills againstagents.toml; every command againstpackage.jsonscripts; theSentryReactNativereject code andNSLog/logger.logidioms against the actual ObjC/Java source; the android arch dirs,RNSentryInternal.swift,scripts/update-{cocoa,android}.sh, and the sample arch toggles against the tree.📝 Checklist
sendDefaultPIIis enabled.🔮 Next steps
None — the revamp now covers the root manual plus every nested
AGENTS.md(packages/core,android,ios,samples/react-native,samples/expo).🤖 Generated with Claude Code