docs: add AGENTS.md for coding agents by bengl · Pull Request #42 · nodejs/microtel

bengl · 2026-11-04T17:44:40Z

Adds AGENTS.md with guidance for coding agents working in this repository, and a CLAUDE.md that imports it with @AGENTS.md, so Claude Code reads the same file.

It covers what agents need that isn't written down anywhere:

what the package is and how its code is shaped, including that it's written the way Node.js core code is
the layout, including the generated bundle and the collector smoke test
the commands, and which CI jobs run them
the code conventions: core's error shapes, the validator parity battery, validating init() options before any state changes, guard() for everything handed to Node, exports always settling, and Prettier's scope
how the tests work around tracing activating once per process, including spawnMicrotel() and its timeout
how the CI benchmark comparison judges a change, and how to measure by hand
the PR rules that already exist in CONTRIBUTING.md, the conventional commit subjects the history uses, and the maintainer conventions: no vendor names, self-contained TODO(handle): items, and README updates for user-facing changes

Every claim in the file was checked against the code, the workflows, and the commit history.

AGENTS.md tells coding agents how this repository works: its layout and commands, the Node.js core and OpenTelemetry conventions the code follows, how the tests are built around init() activating once per process, how to measure changes to the traced path, and the rules for pull requests. CLAUDE.md imports it, so Claude Code reads the same file. Signed-off-by: Bryan English <bryan@bryanenglish.com>

jsumners-nr

In my experience, these barely have an effect. But 🤷‍♂️

bengl · 2026-11-04T19:50:23Z

YMMV 🤷

AbhiPrasad

In my experience, these barely have an effect. But 🤷‍♂️

I think they do! I would recommend running evals on your coding agent traces to see for yourself, I've done a bunch and I can see a noticeable difference, even with frontier models.

AbhiPrasad · 2026-11-05T02:30:33Z

+## Layout
+
+| Path | What it holds |
+|---|---|
+| `index.js` | The public API. |
+| `lib/core.js` | `init()` option validation and the state it sets. |
+| `lib/instrumentations.js` | The `diagnostics_channel` subscribers that create spans and propagate context. |
+| `lib/span.js` | The `Span` class, trace flags, and `traceparent` parsing and formatting. |
+| `lib/sampler.js` | The root sampling decision for `sampleRatio`. |
+| `lib/id.js` | Trace and span ID generation. |
+| `lib/flush.js` | The span buffer, OTLP JSON serialization, the export, and `flush()`. |
+| `lib/guard.js` | `guard()`, which keeps a bug in microtel from breaking the app it traces. |
+| `lib/validate.js` | Ports of Node.js core's argument validators and error helpers. |
+| `scripts/` | The bundle build and the benchmark comparison that CI runs. |
+| `test/` | The tests (`test-*.js`), shared helpers in `test/common/`, and child process fixtures in `test/fixtures/`. |
+| `test/collector/` | A smoke test against a real OpenTelemetry Collector, which runs in its own CI job. |
+| `benchmark/` | The `node:bench` benchmarks. |
+| `dist/microtel.js` | The generated CommonJS bundle from `npm run build`. It's ignored, and `test/test-bundle.js` loads and tests it. |


I would shorten this down to just explaining the main folders. Once you've established that, it's often more effective to just have them grep files, or just navigate the files via following exports/imports.

Suggested change

## Layout

| Path | What it holds |

|---|---|

| `index.js` | The public API. |

| `lib/core.js` | `init()` option validation and the state it sets. |

| `lib/instrumentations.js` | The `diagnostics_channel` subscribers that create spans and propagate context. |

| `lib/span.js` | The `Span` class, trace flags, and `traceparent` parsing and formatting. |

| `lib/sampler.js` | The root sampling decision for `sampleRatio`. |

| `lib/id.js` | Trace and span ID generation. |

| `lib/flush.js` | The span buffer, OTLP JSON serialization, the export, and `flush()`. |

| `lib/guard.js` | `guard()`, which keeps a bug in microtel from breaking the app it traces. |

| `lib/validate.js` | Ports of Node.js core's argument validators and error helpers. |

| `scripts/` | The bundle build and the benchmark comparison that CI runs. |

| `test/` | The tests (`test-*.js`), shared helpers in `test/common/`, and child process fixtures in `test/fixtures/`. |

| `test/collector/` | A smoke test against a real OpenTelemetry Collector, which runs in its own CI job. |

| `benchmark/` | The `node:bench` benchmarks. |

| `dist/microtel.js` | The generated CommonJS bundle from `npm run build`. It's ignored, and `test/test-bundle.js` loads and tests it. |

## Layout

| Path | What it holds |

|---|---|

| `index.js` | The public API. |

| `lib/` | The implementation of microtel. |

| `scripts/` | The bundle build and the benchmark comparison that CI runs. |

| `test/` | The tests (`test-*.js`), shared helpers in `test/common/`, and child process fixtures in `test/fixtures/`. |

| `benchmark/` | The `node:bench` benchmarks. |

| `dist/microtel.js` | The generated CommonJS bundle from `npm run build`. It's ignored, and `test/test-bundle.js` loads and tests it. |

Agree, I always don't like agent generated document that over-documents the details, and making any change would require additional document tailoring.

AbhiPrasad · 2026-11-05T02:31:20Z

+CI runs separate `build`, `test`, `prettier`, and `collector` jobs, and the
+benchmark workflow runs the benchmarks on every push and compares them against
+the base branch on pull requests.


we should just say, "read the github action workflow to see what CI runs". This saves us context window, but also makes it easier for the agent to find exactly what they need to understand the problem.

AbhiPrasad · 2026-11-05T02:32:39Z

+
+## OpenTelemetry behavior
+
+Follow the OpenTelemetry specification and semantic conventions, and match what


I wonder if we should say if agents have confusion over the spec to look it up directly (link to it). Otherwise we risk them hallucinating the spec from memory.

Agree. For behavior matching the spec, the code should be companioned with a link to the spec.

legendecas · 2026-11-05T04:39:34Z

+- `init()` validates every option before it changes any state, and it copies
+  any object it keeps, so a caller changing that object later has no effect.


I don't think this is "code conventions". This belongs to it's own code document.

legendecas · 2026-11-05T04:39:55Z

+- Every export settles, on every path, by its `exportTimeout` deadline at the
+  latest. `flush()` never rejects for a failed export. Failures are reported as
+  throttled `OTelExportWarning` process warnings instead.


Ditto, this should be in the code inline doc rather than in the agents.md

legendecas · 2026-11-05T04:41:13Z

+
+## OpenTelemetry behavior
+
+Follow the OpenTelemetry specification and semantic conventions, and match what


Agree. For behavior matching the spec, the code should be companioned with a link to the spec.

legendecas · 2026-11-05T04:42:53Z

+## Performance
+
+For pull requests, CI compares the benchmarks of the change and its base over
+five interleaved rounds. It reports the mean of each run's mean rate and the


5-round was my back-then result pick. It could change and I don't want to update multiple places to change the round number :)

Suggested change

five interleaved rounds. It reports the mean of each run's mean rate and the

interleaved rounds. It reports the mean of each run's mean rate and the

legendecas · 2026-11-05T04:44:01Z

+spread, and highlights a change only when every run on one side is faster or
+slower than every run on the other.
+
+When measuring by hand, interleave runs of main and the change on the same


Suggested change

When measuring by hand, interleave runs of main and the change on the same

When measuring by hand, use ./scripts/compare-benchmarks.js to interleave runs of main and the change on the same

legendecas · 2026-11-05T04:44:48Z

+  `ci:`, `chore:`, and `docs:`.
+- Contributions are made under the Developer's Certificate of Origin in
+  CONTRIBUTING.md.
+- A pull request stays open for at least 24 hours before it merges, unless the


Please don't duplicate the policies here.

jsumners-nr · 2026-11-05T12:31:13Z

In my experience, these barely have an effect. But 🤷‍♂️

I think they do! I would recommend running evals on your coding agent traces to see for yourself, I've done a bunch and I can see a noticeable difference, even with frontier models.

https://bsky.app/profile/did:plc:4v3uz6xgigawvz64fede7ly7/post/3mydaspu3gs2d

Same nonsense every single day.

bengl marked this pull request as ready for review November 4, 2026 19:10

bengl requested a review from a team November 4, 2026 19:10

jsumners-nr approved these changes Nov 4, 2026

View reviewed changes

AbhiPrasad reviewed Nov 5, 2026

View reviewed changes

legendecas reviewed Nov 5, 2026

View reviewed changes


		## OpenTelemetry behavior

		Follow the OpenTelemetry specification and semantic conventions, and match what

		- `init()` validates every option before it changes any state, and it copies
		any object it keeps, so a caller changing that object later has no effect.

	five interleaved rounds. It reports the mean of each run's mean rate and the
	interleaved rounds. It reports the mean of each run's mean rate and the

	When measuring by hand, interleave runs of main and the change on the same
	When measuring by hand, use ./scripts/compare-benchmarks.js to interleave runs of main and the change on the same

Conversation

bengl commented Nov 4, 2026

Uh oh!

jsumners-nr left a comment

Choose a reason for hiding this comment

Uh oh!

bengl commented Nov 4, 2026

Uh oh!

AbhiPrasad 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!

Choose a reason for hiding this comment

Uh oh!

jsumners-nr commented Nov 5, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants