mirror of
https://github.com/containerd/containerd.git
synced 2026-11-06 05:17:02 +00:00
Chris Henzie
4659359aae
Give coding agents an entry point to the contribution, build, and subsystem documentation. Require security findings to meet the documented scope and evidence requirements before calling them vulnerabilities. Link CLAUDE.md to AGENTS.md so both filenames provide the same guidance. Assisted-by: Claude Code Signed-off-by: Chris Henzie <chrishenzie@gmail.com>
53 lines
4.4 KiB
Markdown
53 lines
4.4 KiB
Markdown
# 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.
|