-
-
Notifications
You must be signed in to change notification settings - Fork 380
Conversation
Member
Summary
Restructure and significantly expand LLM agent instructions for the Sentry Cocoa SDK.
AGENTS.md migration to nested files
Split the monolithic root AGENTS.md (~1,150 lines) into scoped, nested files so agents working in a specific directory automatically pick up the relevant conventions:
| File | Scope |
|---|---|
Tests/AGENTS.md |
Testing conventions, naming, code style, error handling |
Sources/AGENTS.md |
ObjC/Swift coding conventions, public API surface, thread safety, SentryCrash C/C++ rules |
.github/AGENTS.md |
Workflow naming, concurrency strategy, file filters |
Samples/AGENTS.md |
Sample app structure, build and regeneration commands |
scripts/AGENTS.md |
Shell script conventions, named-parameter template |
develop-docs/AGENTS.md |
Internal dev docs index, conventions, when to update |
REVIEWS.md |
Shared code review priorities and SDK-specific concerns |
BUGBOT.md |
Cursor Bugbot-specific review behavior |
The root AGENTS.md becomes a lightweight index (~200 lines) with cross-cutting concerns. CLAUDE.md is now a symlink to AGENTS.md.
New content added
- Architecture overview -- event flow diagram, key classes table, module layout
- Swift conventions -- naming, access control,
finalclasses, error handling, closures - Public API surface rules --
@objc,@_spi(Private), deprecation, backward compat - Thread safety patterns -- table of primitives in use, rules for queue usage
- SentryCrash C/C++ rules -- signal safety, buffer safety, key components
- PR workflow -- branch naming, title format,
ready-to-mergelabel, reviewers, changelog - Platform decision tree -- which platforms to build/test based on change scope
- Sentry MCP validation -- how to use
search_events/get_eventto verify changes - Command execution guidelines --
cdonce, wildcard permissions,jqfor JSON - No AI references override -- explicitly overrides the
commitskill's Co-Authored-By template - LLM preamble on all nested files -- states audience and links to
/agents-mdskill
dotagents support
- Added
agents.tomlwith skill sources and MCP server declarations - Generated
.cursor/mcp.jsonand updated.mcp.jsonfromagents.toml .claude/skillssymlink to.agents/skills
Other changes
- Sample project restructuring (
SentrySampleSharedsynced folders) - SwiftLint fix: exclude
DerivedDataandSourcePackages - Added utils to workspace
Test plan
- Verify all
AGENTS.mdfiles render correctly on GitHub - Confirm
CLAUDE.mdsymlink resolves toAGENTS.md - Validate
npx @sentry/dotagents installworks after cloning - Check
.cursor/mcp.jsonand.mcp.jsonare valid JSON
#skip-changelog
Closes #7567
Use defaultSourceDirectoryType syncedFolder and exclude Info.plist
from source groups.
(cherry picked from commit 09a12c8)
from source groups.
(cherry picked from commit 09a12c8)
(cherry picked from commit 859eb9a)
Document TargetName/Sources, Resources, Configuration structure,
Info.plist/entitlements in Configuration, .gitkeep for empty dirs,
and make build-samples / xcode-ci commands.
(cherry picked from commit a3f973d)
Info.plist/entitlements in Configuration, .gitkeep for empty dirs,
and make build-samples / xcode-ci commands.
(cherry picked from commit a3f973d)
SwiftLint run script phase in Sentry target was linting SPM checkouts
(DerivedData/SourcePackages/checkouts), causing build failures due to
third-party code violations (e.g. Regex __allTests). Exclude these paths
so SwiftLint only lints project source code.
(cherry picked from commit 4dba810)
(DerivedData/SourcePackages/checkouts), causing build failures due to
third-party code violations (e.g. Regex __allTests). Exclude these paths
so SwiftLint only lints project source code.
(cherry picked from commit 4dba810)
Split the monolithic root AGENTS.md into scoped nested files so agents
working in a directory automatically pick up relevant conventions:
- Tests/AGENTS.md: testing conventions, naming, code style
- Sources/AGENTS.md: Objective-C/Swift coding conventions
- .github/AGENTS.md: workflow naming, concurrency, file filters
- Samples/AGENTS.md: sample app structure, build commands
Root AGENTS.md is now a lightweight index with cross-cutting concerns
(commits, Makefile, MCP, compilation). CLAUDE.md is a symlink to
AGENTS.md to eliminate drift between the two files.
working in a directory automatically pick up relevant conventions:
- Tests/AGENTS.md: testing conventions, naming, code style
- Sources/AGENTS.md: Objective-C/Swift coding conventions
- .github/AGENTS.md: workflow naming, concurrency, file filters
- Samples/AGENTS.md: sample app structure, build commands
Root AGENTS.md is now a lightweight index with cross-cutting concerns
(commits, Makefile, MCP, compilation). CLAUDE.md is a symlink to
AGENTS.md to eliminate drift between the two files.
Contributor
Semver Impact of This PRPatch (bug fixes) Changelog PreviewThis is how your changes will appear in the changelog. This PR will not appear in the changelog. This preview updates automatically when you update the PR. |
Rewrite all AGENTS.md files to follow the agents-md skill style:
headers+bullets, no prose, no filler. Add a clear verification
loop to the root AGENTS.md and CLI command table. Create BUGBOT.md
with Cursor Bugbot PR review instructions covering thread safety,
memory management, public API, and SDK-specific concerns.
headers+bullets, no prose, no filler. Add a clear verification
loop to the root AGENTS.md and CLI command table. Create BUGBOT.md
with Cursor Bugbot PR review instructions covering thread safety,
memory management, public API, and SDK-specific concerns.
Move review priorities, SDK-specific concerns, conventions to enforce,
and "what not to flag" into REVIEWS.md as the single source of review
knowledge. BUGBOT.md now references it and only adds Bugbot-specific
behavior (actionable comments, no speculative warnings, no style
nitpicks). Added REVIEWS.md to the root AGENTS.md index.
and "what not to flag" into REVIEWS.md as the single source of review
knowledge. BUGBOT.md now references it and only adds Bugbot-specific
behavior (actionable comments, no speculative warnings, no style
nitpicks). Added REVIEWS.md to the root AGENTS.md index.
Adopt dotagents for skill and MCP server management. Add
agents.toml with wildcard skills from getsentry/dotagents and
MCP server declarations for XcodeBuildMCP and Sentry.
Create scripts/AGENTS.md with named-parameter template and
conventions for new shell scripts. Update root AGENTS.md to
reference both.
agents.toml with wildcard skills from getsentry/dotagents and
MCP server declarations for XcodeBuildMCP and Sentry.
Create scripts/AGENTS.md with named-parameter template and
conventions for new shell scripts. Update root AGENTS.md to
reference both.
Add LLM-audience preamble, command execution rules (cd once,
wildcard permission matching, small commands, jq for JSON),
docs-sync reminder, and agents-md skill reference.
wildcard permission matching, small commands, jq for JSON),
docs-sync reminder, and agents-md skill reference.
...tructuring-1
# Conflicts:
# AGENTS.md
# Conflicts:
# AGENTS.md
...R workflow
Add architecture overview, key classes, and module layout to root
AGENTS.md. Expand Sources/AGENTS.md with Swift conventions, public
API rules, thread safety patterns, and SentryCrash C/C++ rules.
Add PR workflow, platform decision tree, and Sentry MCP validation
examples. Create develop-docs/AGENTS.md. Add LLM preamble to all
nested instruction files.
Add architecture overview, key classes, and module layout to root
AGENTS.md. Expand Sources/AGENTS.md with Swift conventions, public
API rules, thread safety patterns, and SentryCrash C/C++ rules.
Add PR workflow, platform decision tree, and Sentry MCP validation
examples. Create develop-docs/AGENTS.md. Add LLM preamble to all
nested instruction files.
philprime
requested review from
itaybre,
noahsmartin and
philipphofmann
as code owners
March 2, 2026 15:16
4 tasks
Codecov Report All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #7563 +/- ## ============================================= + Coverage 85.328% 85.338% +0.009% ============================================= Files 483 483 Lines 28750 28749 -1 Branches 12489 12496 +7 ============================================= + Hits 24532 24534 +2 + Misses 4170 4169 -1 + Partials 48 46 -2 see 8 files with indirect coverage changes Continue to review full report in Codecov by Sentry.
|
Contributor
Performance metrics
|
| Revision | Plain | With Sentry | Diff |
|---|---|---|---|
| bcabca0 | 1223.57 ms | 1245.36 ms | 21.79 ms |
| 26ae2f8 | 1221.61 ms | 1250.76 ms | 29.14 ms |
| c9976e2 | 1219.31 ms | 1245.44 ms | 26.13 ms |
| bb418da | 1227.60 ms | 1265.90 ms | 38.30 ms |
| bed2eb7 | 1215.88 ms | 1247.14 ms | 31.27 ms |
| d29a425 | 1209.96 ms | 1239.00 ms | 29.04 ms |
| 5d67f5d | 1225.33 ms | 1262.76 ms | 37.43 ms |
| 013f2a8 | 1225.68 ms | 1247.26 ms | 21.58 ms |
| b984142 | 1222.18 ms | 1257.77 ms | 35.59 ms |
| 680923d | 1211.40 ms | 1241.00 ms | 29.60 ms |
App size
| Revision | Plain | With Sentry | Diff |
|---|---|---|---|
| bcabca0 | 24.14 KiB | 1.11 MiB | 1.09 MiB |
| 26ae2f8 | 24.14 KiB | 1.11 MiB | 1.09 MiB |
| c9976e2 | 24.14 KiB | 1.11 MiB | 1.09 MiB |
| bb418da | 24.14 KiB | 1.04 MiB | 1.02 MiB |
| bed2eb7 | 24.14 KiB | 1.07 MiB | 1.04 MiB |
| d29a425 | 24.14 KiB | 1.04 MiB | 1.02 MiB |
| 5d67f5d | 24.14 KiB | 1.06 MiB | 1.04 MiB |
| 013f2a8 | 24.14 KiB | 1.11 MiB | 1.09 MiB |
| b984142 | 24.14 KiB | 1.11 MiB | 1.09 MiB |
| 680923d | 24.14 KiB | 1.10 MiB | 1.08 MiB |
Previous results on branch: philprime/project-restructuring-1
Startup times
| Revision | Plain | With Sentry | Diff |
|---|---|---|---|
| 3720397 | 1231.90 ms | 1264.02 ms | 32.12 ms |
| 8073821 | 1222.22 ms | 1251.70 ms | 29.48 ms |
| 01ecf83 | 1218.47 ms | 1252.81 ms | 34.35 ms |
App size
| Revision | Plain | With Sentry | Diff |
|---|---|---|---|
| 3720397 | 24.14 KiB | 1.12 MiB | 1.09 MiB |
| 8073821 | 24.14 KiB | 1.12 MiB | 1.09 MiB |
| 01ecf83 | 24.14 KiB | 1.12 MiB | 1.09 MiB |
philipphofmann
reviewed
Mar 2, 2026
Member
philipphofmann
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for tackling this.
It was difficult for me to clearly distinguish between newly introduced changes and pure refactoring in this PR. That said, I believe the comments I left are still valid. Even if some of them relate to code that was only refactored rather than newly added, I think the underlying issues should still be addressed.
- Clarify dotagents generates .mcp.json and .cursor/mcp.json; do not edit manually
- Add prefer gh CLI over web scraping for GitHub interactions
- Simplify CLI section to point to Makefile
- Add prefer Swift over ObjC, protocol-oriented design with inline example
- Add Locks.swift extensions, KSCrash fork note, signal-safety links
- Add ci-utils.sh for CI logging in scripts/AGENTS.md
- Link nested AGENTS.md files in REVIEWS.md for review bot alignment
- Add prefer gh CLI over web scraping for GitHub interactions
- Simplify CLI section to point to Makefile
- Add prefer Swift over ObjC, protocol-oriented design with inline example
- Add Locks.swift extensions, KSCrash fork note, signal-safety links
- Add ci-utils.sh for CI logging in scripts/AGENTS.md
- Link nested AGENTS.md files in REVIEWS.md for review bot alignment
philipphofmann
approved these changes
Mar 3, 2026
Member
philipphofmann
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks a lot
Update the template in scripts/AGENTS.md to use ci-utils.sh functions
(log_notice, log_error) instead of echo for proper CI logging output.
Co-Authored-By: Claude Sonnet 4.5
(log_notice, log_error) instead of echo for proper CI logging output.
Co-Authored-By: Claude Sonnet 4.5
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.