chore(agents): trim rules to save context overhead (#22923)

isaacs · claude · web-flow · commit 258d20ba2eb1 · 2026-08-07T22:40:44.000+02:00
Found by `claude doctor` as a significant source of context usage,
leading to more frequent compaction.

Trim details out of the AGENTS.md file to only include what agents can't
already infer. This saves a few thousand tokens of context used in every
session.

The package script table, package layout listing, and skill index all
restated things agents read anyway: root `package.json`, the `packages/`
tree, and `.claude/skills/`. Each one costs context on every session and
goes stale on every rename.

Keep only the parts that aren't discoverable: `packages/types` is
deprecated, and an AI provider integration spans three packages.
Everything else points at the source of truth.

Co-authored-by: Claude Opus 5 &lt;noreply@anthropic.com&gt;
diff --git a/AGENTS.md b/AGENTS.md
@@ -24,21 +24,8 @@ After writing or editing code, check LSP diagnostics and fix errors before proce
 
 ## Package Manager
 
-Use **yarn**: `yarn install`, `yarn build:dev`, `yarn test`, `yarn lint`
-
-| Command                               | Purpose                       |
-| ------------------------------------- | ----------------------------- |
-| `yarn build`                          | Full production build         |
-| `yarn build:dev`                      | Dev build (transpile + types) |
-| `yarn build:dev:filter @sentry/<pkg>` | Build one package + deps      |
-| `yarn build:bundle`                   | Browser bundles only          |
-| `yarn test`                           | All unit tests                |
-| `yarn verify`                         | Lint + format check           |
-| `yarn fix`                            | Format + lint fix             |
-| `yarn lint`                           | Lint (Oxlint)                 |
-| `yarn lint:fix`                       | Lint + auto-fix (Oxlint)      |
-| `yarn format`                         | Format files (Oxfmt)          |
-| `yarn format:check`                   | Check formatting (Oxfmt)      |
+Use **yarn**, never npm or pnpm. Scripts live in the root `package.json`.
+`yarn build:dev:filter @sentry/<pkg>` builds one package and its deps.
 
 Single package: `cd packages/<name> && yarn test`
 
@@ -81,42 +68,12 @@ Uses **Git Flow** (see `docs/gitflow.md`).
 
 ## Architecture
 
-### Core
-
-- `packages/core/` — Base SDK: interfaces, types, core functionality
-- `packages/types/` — Shared types (**deprecated, never modify – instead find types in packages/core**)
-- `packages/browser-utils/` — Browser utilities and instrumentation
-
-### Platform SDKs
-
-- `packages/browser/` — Browser SDK + CDN bundles
-- `packages/node/` — Node.js SDK (client, transports, non-OTel integrations, and OTel instrumentation)
-- `packages/bun/`, `packages/deno/`, `packages/cloudflare/`
-
-### Framework Integrations
-
-- `packages/{framework}/` — React, Vue, Angular, Next.js, Nuxt, SvelteKit, Remix, etc.
-- Some have client/server entry points (nextjs, nuxt, sveltekit)
-
-### AI Integrations
-
-- `packages/core/src/tracing/{provider}/` — Core instrumentation
-- `packages/node/src/integrations/tracing/{provider}/` — Node.js integration + OTel
-- `packages/cloudflare/src/integrations/tracing/{provider}.ts` — Edge runtime
-- Use `/add-ai-integration` skill when adding or modifying integrations
-
-### User Experience
-
-- `packages/replay-internal/`, `packages/replay-canvas/`, `packages/replay-worker/` — Session replay
-- `packages/feedback/` — User feedback
-
-### Dev Packages (`dev-packages/`)
-
-- `browser-integration-tests/` — Playwright browser tests
-- `e2e-tests/` — E2E tests (70+ framework combos)
-- `node-integration-tests/` — Node.js integration tests
-- `test-utils/` — Shared test utilities
-- `rollup-utils/` — Build utilities
+- `packages/types/` is **deprecated — never modify it**. Types live in
+  `packages/core/`.
+- An AI provider integration spans three places: core instrumentation in
+  `packages/core/src/tracing/{provider}/`, the Node integration in
+  `packages/node/src/integrations/tracing/{provider}/`, and the edge
+  runtime in `packages/cloudflare/src/integrations/tracing/{provider}.ts`.
 
 ## Linting & Formatting
 
@@ -154,34 +111,5 @@ Before even proposing lazy loading:
 
 ## Skills
 
-### E2E Testing
-
-Use `/e2e` skill to run E2E tests. See `.claude/skills/e2e/SKILL.md`
-
-### Security Vulnerabilities
-
-Use `/fix-security-vulnerability` skill for Dependabot alerts. See `.claude/skills/fix-security-vulnerability/SKILL.md`
-
-### Issue Triage
-
-Use `/triage-issue` skill. See `.claude/skills/triage-issue/SKILL.md`
-
-### CDN Bundles
-
-Use `/add-cdn-bundle` skill. See `.claude/skills/add-cdn-bundle/SKILL.md`
-
-### Publishing a Release
-
-Use `/release` skill. See `.claude/skills/release/SKILL.md`
-
-### Dependency Upgrades
-
-Use `/upgrade-dep` skill. See `.claude/skills/upgrade-dep/SKILL.md`
-
-### Vendor OpenTelemetry Instrumentation
-
-Use `/vendor-otel` skill. See `.claude/skills/vendor-otel/SKILL.md`
-
-### AI Integration
-
-Use `/add-ai-integration` skill. See `.claude/skills/add-ai-integration/SKILL.md`
+Task-specific instructions live in `.claude/skills/`. Each skill lists its
+own trigger, so consult that directory rather than this file.
