chore: update AGENTS.md for improved types and assertions (#7209)

Author: BridgeAR

AGENTS.md

@@ -17,6 +17,7 @@
 dd-trace is the Datadog client library for Node.js.
 
 **Key Directories:**
+
 - `packages/dd-trace/` - Main library (APM, profiling, debugger, appsec, llmobs, CI visibility, etc)
 - `packages/datadog-core/` - Async context storage, shared utilities
 - `packages/datadog-instrumentations/` - Instrumentation implementations
@@ -27,6 +28,7 @@ dd-trace is the Datadog client library for Node.js.
 **Package Structure:**
 
 Each package under `packages/` follows a consistent structure:
+
 - `src/` - Source code for the package
 - `test/` - Unit tests for the package
 - Unit test files always follow the `*.spec.js` naming convention
@@ -36,38 +38,56 @@ Each package under `packages/` follows a consistent structure:
 
 ### Running Individual Tests
 
-**IMPORTANT**: Never run `yarn test` directly. Use `mocha` directly on test files.
+**IMPORTANT**: Never run the root `npm test`. Run specific related test files directly or run targeted related `npm run test:<area>` scripts.
+
+**Unit tests:**
 
-**Mocha unit tests:**
 ```bash
 ./node_modules/.bin/mocha -r "packages/dd-trace/test/setup/mocha.js" path/to/test.spec.js
 ```
 
 **Integration tests:**
+
 ```bash
 ./node_modules/.bin/mocha --timeout 60000 -r "packages/dd-trace/test/setup/core.js" path/to/test.spec.js
 ```
 
+**If a test expects “spec file is entrypoint” semantics (tap-like):**
+
+```bash
+node scripts/mocha-run-file.js path/to/test.spec.js
+```
+
+You can inject mocha options via `MOCHA_RUN_FILE_CONFIG` (JSON), including `require` hooks.
+
 **Target specific tests:**
+
 - Add `--grep "test name pattern"` flag
 
 **Enable debug logging:**
+
 - Prefix with `DD_TRACE_DEBUG=true`
 
 ### Plugin Tests
 
 **Use `PLUGINS` env var:**
+
 ```bash
-PLUGINS="amqplib" yarn test:plugins
-PLUGINS="amqplib|bluebird" yarn test:plugins  # pipe-delimited for multiple
+PLUGINS="amqplib" npm run test:plugins
+PLUGINS="amqplib|bluebird" npm run test:plugins  # pipe-delimited for multiple
 ./node_modules/.bin/mocha -r "packages/dd-trace/test/setup/mocha.js" packages/datadog-plugin-amqplib/test/index.spec.js
 ```
 
+**Narrow within plugin tests (optional):**
+
+- Use `SPEC` to filter which `*.spec.js` files run within the selected plugins.
+
 **With external services** (check `.github/workflows/apm-integrations.yml` for `SERVICES`):
+
 ```bash
 export SERVICES="rabbitmq" PLUGINS="amqplib"
 docker compose up -d $SERVICES
-yarn services && yarn test:plugins
+yarn services && npm run test:plugins
 ```
 
 **ARM64 incompatible:** `aerospike`, `couchbase`, `grpc`, `oracledb`
@@ -81,6 +101,7 @@ yarn services && yarn test:plugins
 ```
 
 **Philosophy:**
+
 - Integration tests (running in sandboxes) don't count towards nyc coverage metrics
 - Don't add redundant unit tests solely to improve coverage numbers
 - Focus on covering important production code paths with whichever test type makes sense
@@ -98,23 +119,35 @@ assert.equal(actual, expected)
 assertObjectContains(response, { status: 200, body: { user: { name: 'Alice' } } })
 ```
 
+Favor fewer `assert.deepStrictEqual`/`assertObjectContains` calls over many `assert.strictEqual` calls. Combine with existing `assert.strictEqual` calls, if possible.
+
+Never use the `doesNotThrow()` assertion. Instead, execute the method directly.
+
 ### Time-Based Testing
 
 **Never rely on actual time passing in unit tests.** Use sinon's fake timers to mock time and make tests deterministic and fast.
 
 ## Code Style & Linting
 
 ### Linting & Naming
-- Lint: `yarn lint` / `yarn lint:fix`
+
+- Lint: `npm run lint` / `npm run lint:fix`
 - Files: kebab-case
 
 ### JSDoc
+
 - Use TypeScript-compatible syntax (`@param {string}`, `@returns {Promise<void>}`, `@typedef`)
 - Never use `any` (be specific or use `unknown` if type is truly unknown)
+- Write the most specific types possible by reading the overall context
+- Always define types for method arguments as method params
+- Never define argument types inside of a method
+- Only define types inside of a method, if it can not be inferred otherwise
+- Only rewrite code for better types in case it was explicitly requested by the user
 
 ### Import Ordering
 
 Separate groups with empty line, sort alphabetically within each:
+
 1. Node.js core modules (with `node:` prefix)
 2. Third-party modules
 3. Internal imports (by path proximity, then alpha)
@@ -134,8 +167,11 @@ const log = require('../log')
 ### ECMAScript and Node.js API Standards
 
 **Target Node.js 18.0.0 compatibility:**
+
 - Use modern JS features supported by Node.js (e.g., optional chaining `?.`, nullish coalescing `??`)
+- Use `undefined` over `null`, if not required otherwise
 - Guard newer APIs with version checks using [`version.js`](./version.js):
+
   ```js
   const { NODE_MAJOR } = require('./version')
   if (NODE_MAJOR >= 20) { /* Use Node.js 20+ API */ }
@@ -145,12 +181,18 @@ const log = require('../log')
 
 **CRITICAL: Tracer runs in application hot paths - every operation counts.**
 
+- Use fast paths to skip unnecessary steps
+- Use most performant APIs
+- Understand the use case to write ideal CPU and memory performant code
+
 **Async/Await:**
+
 - Do NOT use `async/await` or promises in production code (npm package)
 - Allowed ONLY in: test files, worker threads (e.g., `packages/dd-trace/src/debugger/devtools_client/`)
 - Use callbacks or synchronous patterns instead
 
 **Memory:**
+
 - Minimize allocations in frequently-called paths
 - Avoid unnecessary objects, closures, arrays
 - Reuse objects and buffers
@@ -159,16 +201,19 @@ const log = require('../log')
 #### Array Iteration
 
 **Prefer `for-of`, `for`, `while` loops over functional methods (`map()`, `forEach()`, `filter()`):**
+
 - Avoid `items.forEach(item => process(item))` → use `for (const item of items) { process(item) }`
 - Avoid chaining `items.filter(...).map(...)` → use single loop with conditional push
 - Functional methods create closures and intermediate arrays
 
 **Functional methods acceptable in:**
+
 - Test files
 - Non-hot-path code where readability benefits
 - One-time initialization code
 
 **Loop selection:**
+
 - `for-of` - Simple iteration
 - `for` with index - Need index or better performance in hot paths
 - `while` - Custom iteration logic
@@ -195,29 +240,34 @@ Avoid try/catch in hot paths - validate inputs early
 ## Development Workflow
 
 ### Core Principles
+
 - **Search first**: Check for existing utilities/patterns before creating new code
 - **Small PRs**: Break large efforts into incremental, reviewable changes
 - **Descriptive code**: Self-documenting with verbs in function names; comment when needed
 - **Readable formatting**: Empty lines for grouping, split complex objects, extract variables
 - **Avoid large refactors**: Iterative changes, gradual pattern introduction
-- **Test changes**: Test logic (not mocks), failure cases, edge cases - always update tests
+- **Test changes**: Test logic (not mocks), failure cases, edge cases - always update tests. Write blackbox tests instead of testing internal exports directly
 
 ### Implementation and Testing Workflow
 
 **When making any code or type change, the following MUST be followed:**
 
 1. **Understand** - Read relevant code and tests to understand the current implementation
-2. **Implement** - Make the necessary code changes
-3. **Update Tests** - Modify or add tests to cover the changes
-4. **Run Tests** - Execute the relevant test files to verify everything works
-5. **Verify** - Confirm all tests pass before marking the task as complete
+2. **Optimize** - Identify the cleanest architectural approach to solve the request
+3. **Ask** - Make a proposal with the two best solutions to the user and let them choose. Explain trade-offs
+4. **Implement** - Make the necessary code changes
+5. **Update Tests** - Modify or add tests to cover the changes
+6. **Run Tests** - Execute the relevant test files to verify everything works
+7. **Verify** - Confirm all tests pass before marking the task as complete
 
 ### Always Consider Backportability
 
 **We always backport `master` to older versions.**
+
 - Keep breaking changes to a minimum
 - Don't use language/runtime features that are too new
 - **Guard breaking changes with version checks** using [`version.js`](./version.js):
+
   ```js
   const { DD_MAJOR } = require('./version')
   if (DD_MAJOR >= 6) {
@@ -239,6 +289,10 @@ Avoid try/catch in hot paths - validate inputs early
 
 **Naming Convention:** Size/time-based config options should have unit suffixes (e.g., `timeoutMs`, `maxBytes`, `intervalSeconds`).
 
+## Upstream changes
+
+In case an issue is actually happening outside of dd-trace, suggest to fix it upstream instead of creating a work-around.
+
 ## Adding New Instrumentation
 
 **New instrumentations go in `packages/datadog-instrumentations/`.** The instrumentation system uses diagnostic channels for communication.
@@ -248,21 +302,25 @@ Many integrations have corresponding plugins in `packages/datadog-plugin-*/` tha
 ### What Are Plugins?
 
 Plugins are modular code components in `packages/datadog-plugin-*/` directories that:
+
 - Subscribe to diagnostic channels to receive instrumentation events
 - Handle APM tracing logic (spans, metadata, error tracking)
 - Manage feature-specific logic (e.g., code origin tracking, LLM observability)
 
 **Plugin Base Classes:**
+
 - **`Plugin`** - Base class with diagnostic channel subscription, storage binding, enable/disable lifecycle. Use for non-tracing functionality.
 - **`TracingPlugin`** - Extends `Plugin` with APM tracing helpers (`startSpan()`, automatic trace events, `activeSpan` getter). Use for plugins creating trace spans.
 - **`CompositePlugin`** - Extends `Plugin` to compose multiple sub-plugins. Use when one integration needs multiple feature plugins (e.g., `express` combines tracing and code origin plugins).
 
 **Plugin Loading:**
+
 - Plugins load lazily when application `require()`s the corresponding library
 - Disable with `DD_TRACE_DISABLED_PLUGINS` or `DD_TRACE_<PLUGIN>_ENABLED=false`
 - Test framework plugins only load when Test Optimization mode (`isCiVisibility`) is enabled
 
 **When to Create a New Plugin:**
+
 1. Adding support for a new third-party library/framework
 2. Adding a new product feature that integrates with existing libraries (use `CompositePlugin`)