chore(ai): Add AGENTS.md and testing guidelines by giortzisg · Pull Request #1216 · getsentry/sentry-go

giortzisg · 2026-03-03T10:01:30Z

Description

Add agent configuration files to guide AI-assisted development on the Go SDK.

AGENTS.md — Entry point for coding agents working on this repo. Covers:

Build commands and setup
SDK architecture (core package, internal packages, integration sub-modules)
Transport layer documentation (current HTTPTransport and upcoming internal/telemetry processor)
Key interfaces (Transport, Integration, EventProcessor)
Coding standards and reference links
Testing guidelines

.claude/settings.json — Extended allow list with Go toolchain commands
(go test, go vet, gofmt, golangci-lint, make).

Also registers the create-pr skill in dotagents and adds the generated CLAUDE.md.

Issues

resolves Add AGENTS #1215
resolves GO-123

…ands Add AGENTS.md with SDK architecture overview, coding standards, transport layer documentation (current HTTPTransport and upcoming telemetry processor), and references to project skills and docs. Add .agents/TESTING.md with testing guidelines that prioritize integration tests exercising real user-facing APIs over isolated unit tests. Extend .claude/settings.json with Go toolchain and Makefile commands. Co-Authored-By: Claude <noreply@anthropic.com>

Register the create-pr skill in dotagents configuration and add the generated CLAUDE.md for agent context. Co-Authored-By: Claude <noreply@anthropic.com>

github-actions · 2026-03-03T10:01:47Z

Semver Impact of This PR

🟢 Patch (bug fixes)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

New Features ✨

Add support for client reports by giortzisg in #1192
add org id propagation in sentry_baggage by giortzisg in #1210
add OrgID and StrictTraceContinuation client options. by giortzisg in #1210
Add the option to set attributes on the scope by giortzisg in #1208

Bug Fixes 🐛

(serialization) Pre-serialize mutable event fields to prevent race panics by giortzisg in #1214
Use HEROKU_BUILD_COMMIT with HEROKU_SLUG_COMMIT as fallback by ericapisani in #1220

Internal Changes 🔧

Ai

Add AGENTS.md and testing guidelines by giortzisg in #1216

Add dotagents configuration by giortzisg in #1211

Deps

Bump getsentry/craft from 2.20.1 to 2.23.1 by dependabot in #1213
Bump github.com/gofiber/fiber/v2 from 2.52.11 to 2.52.12 in /fiber by dependabot in #1209

Other

Fix processor MutationAfterAdd test by giortzisg in #1219
Handle independent go module versions for integrations by giortzisg in #1217

_{🤖 This preview updates automatically when you update the PR.}

linear · 2026-03-03T12:00:22Z

GO-123 Add AGENTS

ericapisani

This is a great start! Let me know if it'd be helpful to have a chat about some of the notes I left here.

The general theme for me in the comments I've left is that there's information here that could likely live in the CONTRIBUTING.md file, and have that file be listed as a reference within AGENTS.md so that the agent could grab it when needed, and not have that info in the context at all times.

ericapisani · 2026-03-04T11:48:16Z

AGENTS.md

+- Requires **Go 1.24+** (tested on 1.24, 1.25, 1.26)
+- After cloning: `make build`


These are things that the AI will be able to infer from the README, so I think they can be removed to reduce the duplication of information within the context

ericapisani · 2026-03-04T11:50:40Z

AGENTS.md

+
+- Requires **Go 1.24+** (tested on 1.24, 1.25, 1.26)
+- After cloning: `make build`
+- Never change Go version constraints in `go.mod` unless explicitly asked


Negative instructions don't seem to work as effectively as positive ones for AIs, so I think it might be worth trying to reframe this in a positive way. Maybe "maintain the Go versions that are in the go.mod unless explicitly asked"?

ericapisani · 2026-03-04T11:53:39Z

AGENTS.md

+- `sentry.go` — `Init`, `CaptureException`, `CaptureMessage`, `Flush`
+- `client.go` — `Client`, `ClientOptions`
+- `hub.go` — `Hub` manages a stack of `Scope`/`Client` pairs; thread-safe
+- `scope.go` — `Scope` holds contextual data (tags, user, breadcrumbs, spans)
+- `tracing.go` — `Span`, `StartSpan`, `StartTransaction`; W3C Trace Context
+- `transport.go` — `Transport` interface and `HTTPTransport`/`HTTPSyncTransport`
+- `interfaces.go` — `Event`, `Breadcrumb`, `User`, `Request`, `Exception`


Are these details necessary in this context?

I see the value in keeping theThe root package sentry contains the entire public API part, but I suspect the AI would be able to infer the rest of these details by exploring the codebase.

In case we've seen mixed results in letting it go off on it's own, maybe we could move this into a references file that the AI can load into its context if needed?

yeah that's a good suggestion. In most cases it would need to explore the codebase anyways.

ericapisani · 2026-03-04T11:55:01Z

AGENTS.md

+
+### Internal Packages (`/internal/`)
+
+Private implementation. Do not export types from these packages.


Have we seen instances in the past where it attempts to export things from internal? I'm curious if the AI would naturally follow Go conventions here (in which case we could remove this line) 🤔

Not really, in attempting to export things, but in many cases it doesn't like putting private things under internal. Maybe it makes sense to mention it on coding standards and not here.

ericapisani · 2026-03-04T12:11:05Z

AGENTS.md

+
+### Transport Architecture
+
+**Current: `transport.go` (active)** — `HTTPTransport` uses a batch-channel model with a single worker goroutine. `HTTPSyncTransport` is the blocking variant for serverless.


I wonder if the AI will be able to infer the approach used (the "uses a batch-channel model with a single worker goroutine" part), but imagine it won't with regards to the HTTPTransport being the architecture that's "active" within the project, or that the HTTPSyncTransport is the variant for serverless environments.

I'd keep the latter information, but wonder if we could potentially get rid of the "uses a batch-channel model with a single worker goroutine" part.

ericapisani · 2026-03-04T12:15:53Z

AGENTS.md

+## Coding Standards
+
+- Follow existing conventions — check neighboring files first
+- Do not add new dependencies without asking
+- `gofmt -s` formatting, doc comments on exports
+- Public API in root package; internals in `/internal`
+- Thread safety required — guard shared state with mutexes
+- Update tests when modifying behavior


This looks like something that would already exist within a CONTRIBUTING.md file and we might be able to remove this list and direct the agent to look at that file as a reference further below in this file.

Aside from the duplicate information being added to the AI context, I worry that the information could get out of sync between the two places.

Wanted to minimize context, since the Contributing md file would include information that we don't want to include to the agent.

ericapisani · 2026-03-04T12:16:09Z

AGENTS.md

+
+## Testing
+
+**Prefer tests that exercise real user-facing behavior over isolated unit tests.** Call the same APIs users call — `sentry.Init`, `CaptureException`, `Flush`, framework middleware — rather than mocking internal components.


To cut down on the tokens used in the context here, this could likely be removed since you have the test tier preference just below

CLAUDE.md

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is kicking off a free cloud agent to fix this issue. This run is complimentary, but you can enable autofix for all future PRs in the Cursor dashboard.}

CLAUDE.md

giortzisg and others added 2 commits March 3, 2026 10:59

chore(ai): Add create-pr skill and CLAUDE.md

98b805f

Register the create-pr skill in dotagents configuration and add the generated CLAUDE.md for agent context. Co-Authored-By: Claude <noreply@anthropic.com>

giortzisg added 3 commits March 3, 2026 11:17

simplify AGENTS.md file

218fb56

remove commands table

d23a1d8

feat: inline most important testing guidelines and simplify guidelines

7451a95

giortzisg force-pushed the chore/agents-md branch from e9af7cf to 7451a95 Compare March 3, 2026 10:41

giortzisg marked this pull request as ready for review March 3, 2026 10:42

giortzisg requested review from Litarnus and sl0thentr0py March 3, 2026 10:43

ericapisani reviewed Mar 4, 2026

View reviewed changes

Flash0ver reviewed Mar 5, 2026

View reviewed changes

CLAUDE.md Show resolved Hide resolved

giortzisg added 3 commits March 5, 2026 12:00

change CLAUDE.md to symlink to AGENTS.md

8104ebc

Merge branch 'master' into chore/agents-md

0952ff1

review changes

5eb9707

cursor bot reviewed Mar 9, 2026

View reviewed changes

CLAUDE.md Show resolved Hide resolved

ericapisani approved these changes Mar 9, 2026

View reviewed changes

giortzisg merged commit d1edaf4 into master Mar 9, 2026
27 of 28 checks passed

giortzisg deleted the chore/agents-md branch March 9, 2026 13:05

giortzisg mentioned this pull request Mar 13, 2026

feat(agents): Add AGENTS.md and CLAUDE.md (symlinked) getsentry/sentry-symfony#1003

Merged

		- Requires Go 1.24+ (tested on 1.24, 1.25, 1.26)
		- After cloning: `make build`


		### Internal Packages (`/internal/`)

		Private implementation. Do not export types from these packages.


		### Transport Architecture

		Current: `transport.go` (active) — `HTTPTransport` uses a batch-channel model with a single worker goroutine. `HTTPSyncTransport` is the blocking variant for serverless.


		## Testing

		Prefer tests that exercise real user-facing behavior over isolated unit tests. Call the same APIs users call — `sentry.Init`, `CaptureException`, `Flush`, framework middleware — rather than mocking internal components.

Conversation

giortzisg commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issues

Uh oh!

github-actions bot commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Semver Impact of This PR

New Features ✨

Bug Fixes 🐛

Internal Changes 🔧

Ai

Deps

Other

Uh oh!

linear bot commented Mar 3, 2026

Uh oh!

ericapisani left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

giortzisg commented Mar 3, 2026 •

edited

Loading

github-actions bot commented Mar 3, 2026 •

edited

Loading