Merge pull request #13980 from chrishenzie/agents-md

Add AGENTS.md guidance for AI coding agents

AGENTS.md

@@ -0,0 +1,52 @@
+# AGENTS.md
+
+## Preparing changes
+
+Before contributing, read [CONTRIBUTING.md](CONTRIBUTING.md) and the [org-wide contribution guide](https://github.com/containerd/project/blob/main/CONTRIBUTING.md). They cover change scope, tests, license headers, commit sign-offs, and AI attribution.
+
+For AI-assisted work, follow the org guide's [Coding Agent Usage](https://github.com/containerd/project/blob/main/CONTRIBUTING.md#coding-agent-usage) policy and the repository's [submission requirements](CONTRIBUTING.md#automated-and-ai-generated-contributions). The human contributor reviews all content before submission and writes replies to review comments and issue discussions. Automated PR creation requires prior maintainer approval.
+
+- Before adding a capability, check [SCOPE.md](SCOPE.md). Its allow-list governs features and components.
+- Before adding packages or source files, read [Where to put packages](CONTRIBUTING.md#where-to-put-packages).
+- Before changing a public API or protobuf definition, read [Public API Stability](RELEASES.md#public-api-stability).
+- Before changing daemon configuration, read [Daemon Configuration](RELEASES.md#daemon-configuration) for compatibility and migration requirements.
+
+When requirements leave behavior or API names ambiguous, resolve them with the human contributor before implementing the change.
+
+## Build and validation
+
+- **Builds and dependencies:** read [BUILDING.md](BUILDING.md) for prerequisites, binary targets, build tags, and vendoring. Regenerate `vendor/` with `make vendor`; never hand-edit vendored files.
+- **Protobuf changes:** follow [Updating protobuf files](CONTRIBUTING.md#updating-protobuf-files) to regenerate code and check formatting. Never hand-edit generated protobuf code.
+- **Lint:** run `make check` with the tools from [Setting up your local environment](CONTRIBUTING.md#setting-up-your-local-environment). If prerequisites are unavailable, report the blocker.
+- **Tests:** use [Testing containerd](BUILDING.md#testing-containerd) to select the suite and privileges needed for the changed behavior. Check for skipped tests before reporting coverage. For CRI changes, also read [CRI Plugin Testing Guide](docs/cri/testing.md).
+
+Run `make clean-test` only on a dedicated test host: it kills every `containerd` and `runc` process and removes runtime state.
+
+Fix failing checks at the cause, or explain to the human contributor why the check is wrong. Never delete or weaken tests, add `//nolint`, or bypass a check just to make CI pass.
+
+## Subsystem context
+
+Read the relevant docs before changing a subsystem:
+
+| Area                                      | Reference                                        |
+| ----------------------------------------- | ------------------------------------------------ |
+| Plugin registration and dependencies      | [Plugin model](docs/PLUGINS.md)                  |
+| Task execution and shim lifecycle         | [Runtime v2](docs/runtime-v2.md)                 |
+| Sandbox controllers                       | [Sandbox API](docs/sandbox-api.md)               |
+| CRI requests and kubelet integration      | [CRI architecture](docs/cri/architecture.md)     |
+| Content, snapshots, and their labels      | [Content flow](docs/content-flow.md)             |
+| Resource retention and garbage collection | [Garbage collection](docs/garbage-collection.md) |
+| Namespace propagation through context     | [Namespaces](docs/namespaces.md)                 |
+| Daemon-side image transfers               | [Transfer service](docs/transfer.md)             |
+
+## Security findings
+
+Before scanning for security issues, evaluating a suspected vulnerability, or drafting a security report, read all three:
+
+- [Threat model](docs/security/THREAT_MODEL.md): trust boundaries, trusted components, and security exclusions.
+- [Triage guide](docs/security/TRIAGE_GUIDE.md): required evidence and finding classifications.
+- [Operator baseline](docs/security/OPERATOR_GUIDELINES.md#1-baseline-security-requirements): deployment assumptions used in triage.
+
+Apply their scope and evidence requirements before calling a finding a vulnerability. Findings outside the threat model are not vulnerabilities.
+
+Raise suspected non-public vulnerabilities privately with the human contributor, who decides whether to use the [Security Advisories portal](https://github.com/containerd/containerd/security). Never disclose them in issues, PRs, commits, review comments, or public chat; containerd channels in the CNCF Slack are public.

BUILDING.md

@@ -261,6 +261,11 @@ During the automated CI the unit tests and integration tests are run as part of
  - `make integration`: run all tests, including integration tests and those which require `root`. `TESTFLAGS_PARALLEL` can be used to control parallelism. For example, `TESTFLAGS_PARALLEL=1 make integration` will lead a non-parallel execution. The default value of `TESTFLAGS_PARALLEL` is **8**.
  - `make cri-integration`: [CRI Integration Tests](https://github.com/containerd/containerd/blob/main/docs/cri/testing.md#cri-integration-test) run cri integration tests
 
+A test that needs `root` calls `testutil.RequiresRoot`, which skips it unless
+`-test.root` is passed. `make test` skips those tests and still succeeds, so check
+whether the tests covering your change are among them. `make root-test` selects
+the packages that call the helper and runs them with `-test.root`.
+
 To execute a specific test or set of tests you can use the `go test` capabilities
 without using the `Makefile` targets. The following examples show how to specify a test
 name and also how to use the flag directly against `go test` to run root-requiring tests.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.md

@@ -25,6 +25,21 @@ $ script/setup/install-dev-tools
 $ make install-deps
 ```
 
+## Pull request expectations
+
+- Before starting work on an issue, check whether an open pull request already
+  addresses it: look at the issue's linked pull requests and search open pull
+  requests for the issue number.
+- Document features and enhancements, both at the code level and in the
+  user-facing docs under `docs/`.
+- Test at the levels that fit the change: unit, integration, or end-to-end.
+  For failure injection in integration tests, use the failpoint pattern
+  (`internal/failpoint`, `integration/failpoint`).
+- Run `make check` and the tests that cover your change locally before opening
+  or updating a pull request.
+- Monitor your pull request's CI runs and make sure your changes are not
+  responsible for failures.
+
 ## Automated and AI-generated contributions
 
 Pull requests must be opened by a human. Any use of automation to create

docs/cri/testing.md

@@ -8,6 +8,7 @@ Before sending pull requests you should at least make sure your changes have pas
 Follow the [building](../../BUILDING.md) instructions.
 
 ## CRI Integration Test
+The tests need the host dependencies installed by `make install-deps` (see [CONTRIBUTING.md](../../CONTRIBUTING.md#setting-up-your-local-environment)).
 * Run all CRI integration tests:
 ```bash
 make cri-integration