From 9a696dc2bb64f71a0fdc1c6199e4be56b0c3ce69 Mon Sep 17 00:00:00 2001 From: opieter-aws Date: Thu, 9 Jul 2026 09:11:28 -0400 Subject: [PATCH] docs: improve agent guidance on issue references in regression tests --- AGENTS.md | 3 ++- strands-py/docs/TESTING.md | 2 +- strands-ts/docs/TESTING.md | 4 ++++ 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 301820664d..9a2242067b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,7 +54,8 @@ These rules apply to **both** SDKs. Each sub-guide (`strands-py/AGENTS.md`, `str - **Hook event names are shared** across SDKs (modulo the suffix convention). When you add a hook event in one SDK, add the matching name in the other. - **Public vs internal API**: mark anything exported-but-not-public so consumers don't depend on it — Python keeps it out of `__all__` (and should prefix the module `_`); TypeScript keeps it out of the `index.ts` barrel and tags it `@internal`. - **Structured logging format**: `field=, field= | lowercase human-readable message`, no punctuation, pipe-separate multiple statements. Python interpolates with `%s` (never f-strings; ruff `G` enforces it); TypeScript uses template literals (never printf `%s`/`%d`). -- **Evergreen comments**: comments explain WHAT/WHY, never how the code changed or what it used to be ("improved", "previously", "used to", "which would previously have crashed"). This applies to tests too — a regression test links its issue and states the behavior it guarantees. ("deprecated"/"legacy" is fine when it describes a stable API surface or runtime state; it's forbidden only when narrating how the code itself changed.) +- **Evergreen comments**: comments explain WHAT/WHY, never how the code changed or what it used to be ("improved", "previously", "used to", "which would previously have crashed"). This applies to tests too — a regression test for a discovered bug links the issue it guards against and states the behavior it guarantees; a test written as part of feature development carries no issue reference. ("deprecated"/"legacy" is fine when it describes a stable API surface or runtime state; it's forbidden only when narrating how the code itself changed.) + - **Directory & file naming parity**: subsystem directories use the language-idiomatic separator (`snake_case` in Python, `kebab-case` in TypeScript) but the stem matches word-for-word so they are mechanically translatable (`vended_plugins/` ↔ `vended-plugins/`, `conversation_manager/` ↔ `conversation-manager/`). ### Testing diff --git a/strands-py/docs/TESTING.md b/strands-py/docs/TESTING.md index bebd1217dc..4d59495653 100644 --- a/strands-py/docs/TESTING.md +++ b/strands-py/docs/TESTING.md @@ -79,4 +79,4 @@ assert tru_message == exp_message ## Comments in Tests -The evergreen-comment rule applies here too: a regression test should **link the issue and describe the behavior it now guarantees**, not narrate what the code used to do. Prefer `# guards against unbounded retry on a None tool name (#642)` over `# we used to hang on None here`. +The evergreen-comment rule applies here too. **Only a regression test for a discovered bug carries an issue reference**. It links the issue it guards against and describes the behavior it now guarantees, never narrating what the code used to do. Prefer `# guards against unbounded retry on a None tool name (#642)` over `# we used to hang on None here`. A test written as part of feature development gets no issue reference. diff --git a/strands-ts/docs/TESTING.md b/strands-ts/docs/TESTING.md index ca937c24cd..e3fe94bfc4 100644 --- a/strands-ts/docs/TESTING.md +++ b/strands-ts/docs/TESTING.md @@ -162,6 +162,10 @@ describe('calculateTotal', () => { }) ``` +## Comments in Tests + +The evergreen-comment rule applies here too. **Only a regression test for a discovered bug carries an issue/PR reference** — it links the issue it guards against and describes the behavior it now guarantees, never narrating what the code used to do. Prefer `// guards against unbounded retry on a null tool name (#642)` over `// we used to hang on null here`. A test written as part of feature development gets no issue or PR reference. + ## Test Batching Strategy **Rule**: When test setup cost exceeds test logic cost, you MUST batch related assertions into a single test. Prefer extending an existing test over adding a new one. If a test already arranges the scenario your new behavior needs, add the assertion(s) there rather than duplicating the setup. Reach for a new test only for the cases listed under "You SHOULD keep separate tests for" below.