From c8e8117060b0717ad5527a0849a357104b560778 Mon Sep 17 00:00:00 2001 From: lym953 <10097700+lym953@users.noreply.github.com> Date: Wed, 28 Oct 2026 16:32:02 -0400 Subject: [PATCH 1/5] docs: add AGENTS.md with PR quality rules Add guidance for coding agents and review bots on PR size, duplicate tests, defensive checks, and settings shared with the Lambda Extension and the Go Agent. Stop ignoring /AGENTS.md so the file can be committed. Co-Authored-By: Claude Opus 5.5 --- .gitignore | 1 - AGENTS.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/.gitignore b/.gitignore index a0015fc7..10264bf1 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,3 @@ /.idea /.vscode /CLAUDE.md -/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..94ec79a2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,80 @@ +# AGENTS.md + +This file gives guidance to coding agents and review bots that work in this repository. + +## Who uses this code + +This repository has libraries and binaries for serverless monitoring. Changes here can reach +more than one product: + +- `datadog-serverless-compat` is the binary for Azure Functions, Azure Spring Apps and + Google Cloud Functions. It uses the crates in this repository directly. +- The Datadog Lambda Extension (`DataDog/datadog-lambda-extension`, also called bottlecap) + pins crates from this repository by Git revision. These include `dogstatsd`, + `datadog-fips`, `datadog-agent-config` and `datadog-agent-trace-sampler`. +- Much of the trace and metrics logic ports behavior from the Go Datadog Agent + (`DataDog/datadog-agent`, mostly `pkg/trace`). + +## Code style + +- Do not add a defensive check unless you can name the input that makes it fail. For example, + do not check that an index is in range when the function that returns it cannot return an + index out of range. +- Keep comments concise. Describe the code as it is, not the history of the change. +- Describe a rule in one place. Do not repeat the same rule in several doc comments. +- Before you write a helper, search the repository for one that does the same job. For + example, `datadog-agent-config` already parses comma-separated and space-separated lists. + +## Settings + +An environment variable is a contract with users, so treat a new one as a design decision. + +- Before you add an environment variable, search the Go Agent and the Lambda Extension for one + that does the same job. Use the same name and the same meaning when you can. +- When this repository and the Lambda Extension configure the same shared crate, use the same + settings in both. If they must differ, say why in the PR description. +- When a change turns on a new behavior by default, say so in the PR description. Also say how + a user turns it off. + +## Tests + +Tests are code that reviewers must read and maintainers must keep. Add a test only when it +checks something that no other test checks. + +- Before you add a test for one case, look for a table test that covers it. Add the case to + that table instead. +- When a pure function makes a decision, test the decision with a table of inputs that calls + the function directly. Then tests through the full request path need only one or two cases, + for the part that they add. +- Do not test the behavior of another crate again. For example, the sampler crate has its own + tests for its rate limits, so a test in the trace agent checks only how the trace agent + calls the sampler. +- Do not compute the expected result with the same expression as the code under test. Write + the expected values in the test. +- Do not add a test for a setting that no code reads, or a loop over an input that the code + does not read. +- Do not repeat the same environment setup in many tests. Put the parsing in a function that + takes the raw values, test that function with a table, and use one test for the + environment. + +## Pull requests + +- Keep PRs small, so that a reviewer can read all of the PR: usually no more than 300 lines of + core code. Tests, lock files and generated files are not core code. +- If a PR has more than one behavior change, put each one in a separate PR. +- Keep the number of test lines in proportion to the core code. Many more test lines than core + lines usually means duplicate tests. Before you open the PR, read the tests again for the + problems in [Tests](#tests). +- Make sure that the PR description agrees with the code. When you change the code, update the + title and the description. + +## Reviewing a pull request + +- Read the code before the PR description. Then check that the description agrees with the + code. +- Report the number of core lines and the number of test lines. If the PR is larger than the + size in [Pull requests](#pull-requests), suggest how to split it. +- Look for duplicates outside the diff, such as a helper that the repository already has or a + test that another crate already has. +- For each new setting and each new default, check the rules in [Settings](#settings). +- Mark each finding as important, minor or nit. From 236a4e4c343f5780231f69b5e85a4104dddd59f6 Mon Sep 17 00:00:00 2001 From: lym953 <10097700+lym953@users.noreply.github.com> Date: Thu, 29 Oct 2026 10:47:50 -0400 Subject: [PATCH 2/5] docs: add CLAUDE.md that loads AGENTS.md and CLAUDE_PERSONAL.md Follow the Lambda Extension setup: commit CLAUDE.md, and ignore /CLAUDE_PERSONAL.md for personal instructions. Co-Authored-By: Claude Opus 5.5 --- .gitignore | 2 +- CLAUDE.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index 10264bf1..bfc78eec 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ /target /.idea /.vscode -/CLAUDE.md +/CLAUDE_PERSONAL.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..01675dfa --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md @CLAUDE_PERSONAL.md From 534bd7dec45ff68ea3fc25e59d4645b2c9e11700 Mon Sep 17 00:00:00 2001 From: lym953 <10097700+lym953@users.noreply.github.com> Date: Thu, 29 Oct 2026 10:57:21 -0400 Subject: [PATCH 3/5] docs: drop helper example from AGENTS.md Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 94ec79a2..3680a30b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,8 +22,7 @@ more than one product: index out of range. - Keep comments concise. Describe the code as it is, not the history of the change. - Describe a rule in one place. Do not repeat the same rule in several doc comments. -- Before you write a helper, search the repository for one that does the same job. For - example, `datadog-agent-config` already parses comma-separated and space-separated lists. +- Before you write a helper, search the repository for one that does the same job. ## Settings From 57bffa94c1638862a50695182cdb74f4b1730f3e Mon Sep 17 00:00:00 2001 From: lym953 <10097700+lym953@users.noreply.github.com> Date: Thu, 29 Oct 2026 11:11:30 -0400 Subject: [PATCH 4/5] docs: drop defensive-check rule from AGENTS.md Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3680a30b..efd994c5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,9 +17,6 @@ more than one product: ## Code style -- Do not add a defensive check unless you can name the input that makes it fail. For example, - do not check that an index is in range when the function that returns it cannot return an - index out of range. - Keep comments concise. Describe the code as it is, not the history of the change. - Describe a rule in one place. Do not repeat the same rule in several doc comments. - Before you write a helper, search the repository for one that does the same job. From c42b05b86262ca54e0b995e4819a9e04124326ff Mon Sep 17 00:00:00 2001 From: lym953 <10097700+lym953@users.noreply.github.com> Date: Thu, 29 Oct 2026 11:12:44 -0400 Subject: [PATCH 5/5] docs: drop read-code-first rule from AGENTS.md Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index efd994c5..f42ba424 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -66,8 +66,7 @@ checks something that no other test checks. ## Reviewing a pull request -- Read the code before the PR description. Then check that the description agrees with the - code. +- Check that the PR description agrees with the code. - Report the number of core lines and the number of test lines. If the PR is larger than the size in [Pull requests](#pull-requests), suggest how to split it. - Look for duplicates outside the diff, such as a helper that the repository already has or a