diff --git a/.agents/skills/open-pr/SKILL.md b/.agents/skills/open-pr/SKILL.md index 64b741287..1a5a87f0a 100644 --- a/.agents/skills/open-pr/SKILL.md +++ b/.agents/skills/open-pr/SKILL.md @@ -12,6 +12,7 @@ Release Drafter turns PR titles into release notes and labels into the version b - Branch from an up-to-date `main`. - Run the checks in AGENTS.md "Verification". For bug fixes, keep the red-green output. - Check that `git diff --stat main...HEAD` shows only the files you intended, and that the lockfile changes only the entries you intended. +- If the diff touches `docs/`, AGENTS.md or a skill, check it against AGENTS.md "API and docs": docs only for a user-facing change and only how to use it, and no lines about your own feature in AGENTS.md or a skill. ## Commit and push diff --git a/.agents/skills/review-pr/SKILL.md b/.agents/skills/review-pr/SKILL.md index 81069152b..ee114e8bf 100644 --- a/.agents/skills/review-pr/SKILL.md +++ b/.agents/skills/review-pr/SKILL.md @@ -35,7 +35,9 @@ gh pr checks - **Concurrency:** no shared containers, `process.env` or spies without `{ concurrent: false }`. Use `await using`. No skipping when Docker is unavailable. - **Root cause:** a fix removes the cause of the failure. Added sleeps, retries or longer timeouts only make it less likely (AGENTS.md). - **Completeness:** a fix applied to one path is also applied to its siblings, for example `restart()` next to `start()`, or the reuse path next to the create path. -- **Docs:** public API changes are documented, and module examples use `codeinclude`. Check that each marker name appears only once in its test file; CI can't catch a collision (AGENTS.md). +- **Docs:** + - User-facing API changes are documented. Flag docs for helpers that only modules use, and docs that explain how a feature is implemented instead of how to use it (AGENTS.md "API and docs"). + - Module examples use `codeinclude`. Check that each marker name appears only once in its test file; CI can't catch a collision (AGENTS.md). - **Design:** - Zero-config defaults work, and invalid or half-set config fails fast. - The wait strategy is set in the constructor, and waits are robust (listening ports, health check or HTTP rather than log regexes). @@ -45,6 +47,7 @@ gh pr checks - Flag new files for a few lines of logic, dead fallbacks, duplicated constants, getters that exist only for tests, and tests of third-party behaviour. - Flag unrelated dependency bumps; leave those to Dependabot. - Flag code comments that restate the code or describe the change (AGENTS.md). + - Flag lines added to AGENTS.md or a skill that only describe the PR's own feature (AGENTS.md "Purpose"). - **Dependencies:** runtime dependencies load from CommonJS (AGENTS.md), and well-established libraries or built-ins are preferred. - **Breaking changes:** renamed exports, changed defaults and lowered timeouts all count. They need `major` or a non-breaking alternative. - **Claims:** check root-cause explanations, and claims about what another Testcontainers implementation does, against the actual code. AI-written PR descriptions are often confidently wrong. diff --git a/.agents/skills/write-code/SKILL.md b/.agents/skills/write-code/SKILL.md index a5ee2dcb9..b8b41812f 100644 --- a/.agents/skills/write-code/SKILL.md +++ b/.agents/skills/write-code/SKILL.md @@ -16,7 +16,13 @@ Biome enforces the lint and formatting rules (`biome.json`). This skill covers w - In one file, extract a helper: a private method, or a function the file doesn't export. Define it below the first function that calls it. - Across files in a package, move it into a function in its own file. -- Across modules, it belongs in core, exported from `testcontainers`, because modules can't import each other. That adds public API, so propose it instead of copying the code. +- Across modules, it belongs in core, exported from `testcontainers`, because modules can't import each other. That adds public API, so propose it instead of copying the code. A helper exported for modules gets no docs. + +## Before touching docs + +- Change `docs/` only when what a user calls changes: a new option, method or module, or behaviour they have to account for (AGENTS.md "API and docs"). +- Show how to use it and stop. How it works and why it changed go in the PR body. +- Don't add a line about your change to AGENTS.md or a skill. ## Use what core provides diff --git a/AGENTS.md b/AGENTS.md index 69e5a2d25..f389292bb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,6 +7,7 @@ It captures practical rules that prevent avoidable CI and PR churn. This file holds the rules for every task. Workflows live in skills under `.agents/skills/`, which Claude Code reads through symlinks in `.claude/skills/`. They cover writing code, opening and reviewing PRs, adding modules, issue triage, CI and dependency maintenance, and release review. If a skill or this file turns out to be wrong or incomplete, update it in the same PR. +Wrong or incomplete means a rule misled you, or a mistake keeps recurring that no rule covers. Adding a feature, helper or option is not a reason to add a line about it here or in a skill. ## Repository Layout @@ -22,7 +23,11 @@ If a skill or this file turns out to be wrong or incomplete, update it in the sa ### API and docs -- If a public API changes, update the relevant docs in the same PR. +- If a user-facing API changes, update the relevant docs in the same PR. + - User-facing means what someone testing against a container uses: containers, images, networks, Compose, wait strategies, and modules and their options. + - Don't document helpers that `index.ts` exports so that modules can import them (for example `log`, `RandomUuid`, `BoundPorts`). Being exported makes them public API, not a docs topic. +- Docs tell a user how to use a feature: what to call, a short example, and anything they have to account for. + - Leave out how it is implemented: which Docker calls are made, timing and retry mechanics, and why the change was made. That belongs in the PR body. - If new types are made part of the public API, export them from the package's `index.ts` in the same PR. - Only what a package's `index.ts` exports is public API. `npm run knip` fails on any other export that no other file uses: drop the `export` keyword, or export it from `index.ts` if consumers need it. - In docs Markdown, keep `` blocks tight with no blank lines between the markers and the include line, or the rendered snippet will contain blank lines between code lines.