rustfs/AGENTS.md

RustFS Agent Instructions

This file contains repository-wide rules. Use the nearest subdirectory AGENTS.md for path-specific invariants.

Precedence

1. System/developer instructions.
2. The current user request.
3. The nearest AGENTS.md.
4. This file.

Operating Model

• Inquiry, diagnosis, review, and planning tasks are read-only unless the user explicitly requests changes.
• For implementation, read the relevant code, tests, and local guidance, then make the smallest change that satisfies the request.
• State assumptions only when they affect behavior or verification. Ask only when a wrong assumption would materially change the result.
• Do not load every skill or inspect unrelated modules preemptively. Select a skill only when its description directly matches the request or changed surface.
• Avoid repeated reads and equivalent verification commands once enough evidence exists.

Worktree and Disk Hygiene

• Start implementation from the latest origin/main and confirm the requested change is not already present.
• An existing clean, isolated task worktree is sufficient. Create another worktree only when the current checkout is shared, dirty with unrelated work, or belongs to another task.
• Never commit from a shared checkout. Use an overtrue/ feature branch unless the user requests another name.
• Check free space before artifact-heavy builds, tests, coverage, or downloads. Re-check before a broad gate when space is tight.
• Remove only task-owned temporary/build artifacts. Never delete another task's worktree or uncommitted data.
• At handoff, mention disk or cleanup details only when they affected execution or artifacts/worktrees remain intentionally.

Change Style

• Preserve existing control flow unless changing it is required for correctness.
• Prefer a direct local edit over new files, wrappers, managers, or speculative abstractions.
• Add a helper only when it removes current duplication, names a real domain boundary, or isolates a non-trivial invariant.
• Remove an in-scope path superseded by the change. If compatibility requires it, adapt at the boundary to one canonical core and use the repository's RUSTFS_COMPAT_TODO policy.
• Comments explain non-obvious invariants or reasons. Do not narrate code or record change history.
• Mention unrelated problems when useful; do not fix them in a narrow task.

Reuse and Boundary Rules

• Before adding helpers, constants, fixtures, or wrappers, search the touched crate, the domain-owning crate, crates/utils, crates/common, and relevant direct dependencies.
• Reuse requires matching semantics: normalization, error types, deadlines, durability, and compatibility must fit the call site. A narrowly named local helper is better than forced reuse with different semantics.
• Validate untrusted input at its trust boundary, then trust the validated type. Values crossing disk, RPC, persistence, or version boundaries remain untrusted at every consumer.
• Re-check boundary values immediately before destructive actions such as delete, overwrite, or quorum decisions.
• Every new branch needs a concrete triggering input/state. For decoded or peer data, corruption and mixed-version input are valid triggers.
• Required values must return a typed error when absent or corrupt; do not use a default that converts corruption into a plausible result.
• Attach error context once where it is actionable. Do not erase typed errors below aggregation or quorum layers.

Sources of Truth

• Workspace membership: Cargo.toml.
• Local gates: Makefile and .config/make/.
• CI gates: .github/workflows/ci.yml.
• PR format: .github/pull_request_template.md.
• Architecture routing: ARCHITECTURE.md and docs/architecture/README.md.
• Agent skills: .agents/skills/*/SKILL.md.

Do not commit one-shot plans, trackers, migration ledgers, benchmark snapshots, or agent scratch notes. Durable architecture belongs under docs/architecture/, operations under docs/operations/, and testing references under docs/testing/. scripts/check_no_planning_docs.sh enforces this boundary.

Verification

Select checks from the final task-owned diff. Scoped AGENTS.md files may add a concrete path-specific check, but must not replace this tiering with a generic full-workspace gate.

Documentation and Instructions

For prose, comments, agent instructions, and skill metadata that cannot affect runtime/build output:

• Run git diff --check.
• Run the relevant documentation guard or skill validator when applicable.
• Skip Cargo formatting, compilation, Clippy, tests, make pre-commit, and make pre-pr.

Non-Behavioral Source Changes

• Run the formatter/validator for the changed language.
• Add compilation or doctests only when syntax or executable examples changed.

Localized Behavior Changes

• Run cargo fmt --all --check for Rust changes.
• Run the narrowest test that exercises the changed behavior.
• Add package-scoped cargo check or Clippy only for targets, features, public APIs, error handling, or control flow not compiled by the focused test.
• Use make pre-commit only when its repository-wide fast checks add confidence beyond the focused checks.

Broad or High-Risk Changes

After the required adversarial review, run make pre-pr when targeted coverage cannot bound the impact, including dependency/toolchain/build-matrix changes, unbounded cross-crate APIs, or locking, durability, erasure coding, replication, RPC, IAM/KMS/auth, cryptography, on-disk/on-wire, and S3-visible behavior.

make pre-pr includes make pre-commit; never run both for the same unchanged diff. Do not repeat a check already covered by a successful umbrella gate. Rerun only checks affected by later edits.

Never weaken a gate to get green: do not add baselines/allowances, suppress lints, ignore tests, or relax assertions unless changing that policy is itself the reviewed task. Follow docs/testing/README.md for flaky tests.

Adversarial Validation

Adversarial validation applies to final implementation diffs, explicitly requested adversarial/design reviews, and agent-instruction changes that alter execution. Ordinary questions, diagnoses, status reports, non-adversarial code reviews, and low-risk planning do not trigger it.

Risk and review shape:

• Exempt: documentation, comments, formatting, or typos with no runtime, build, test, or agent-execution effect.
• Mechanical: renames, moves, test/tooling-only changes, and agent-rule changes. Run correctness and simplicity lenses.
• Standard: localized behavior changes. Run one integrated final-diff pass covering correctness, simplicity, and test coverage; add only domain lenses matched by the diff.
• High risk / substantial PR review: high risk includes locking, erasure/quorum/heal, replication, multipart, RPC, lifecycle/tiering, persistence/fsync, IAM/KMS/auth, cryptography, on-disk/on-wire formats, and S3-visible semantics. Cover all applicable lenses using exactly two independent reviewers when delegation is explicitly authorized. Split the lenses between them. Otherwise perform two fresh sequential passes.

Available domain lenses are security, concurrency/durability, compatibility, and performance. Select .agents/skills/adversarial-validation/SKILL.md for an explicit adversarial request, a high-risk change, or a substantial PR review; then read only its matching role references. A routine standard pass does not load the playbook unless the reviewer needs a RustFS-specific probe.

A finding must name a concrete input/state/interleaving and wrong outcome, or a specific missing regression check, with file:line. Resolve it by fixing the diff or rebutting it with code-path/test/invariant evidence. After a non-trivial fix, rerun only affected lenses.

For high-risk PRs, record one concise verdict per covered lens in the PR body.

Pull Request Lifecycle

• Creating or updating a PR includes one immediate snapshot of checks, mergeability, reviews, and unresolved threads.
• Unless the user explicitly requests monitoring, a release workflow requires it, or an automation already owns it, hand off after the PR is open with the current state and next event to watch. Do not delay ordinary handoff with fixed quiet-period sleeps.
• For requested monitoring, use event-driven or bounded waits. Report only state changes, actionable failures, or a meaningful prolonged delay.
• Investigate failures/comments before changing code. Fix task-attributable issues, rerun affected verification, push, reply or resolve the thread, then resume the requested monitor.
• Never merge without required reviewer approval or explicit authority.
• After an observed merge, verify the commit reached the base, then clean the task worktree/branch when safe. Preserve unmerged work for closed PRs unless deletion was explicitly authorized.

Git and PR Baseline

• Follow Conventional Commits; keep the subject at most 72 characters.
• Source comments, commits, PR titles, and PR bodies are in English.
• Keep every heading from .github/pull_request_template.md; use N/A where needed and include commands actually run.
• Use --body-file for multiline gh pr create/gh pr edit content.
• PR/issue/discussion content must not contain the literal sequence \n or hard-wrapped prose paragraphs.
• Do not include local absolute paths or tool-specific labels/prefixes in GitHub content.
• Resolve review threads after the underlying issue is fixed. If declining a suggestion, reply with a short evidence-based reason.

Security Baseline

• Never commit secrets, credentials, or key material.
• Use environment variables or vault tooling for sensitive configuration.
• For localhost-sensitive tests, bypass proxies explicitly.
• Untrusted S3 XML/JSON, lifecycle, policy, replication, and RPC structures use strict deserialization where compatibility permits. Security-critical defaults require explicit validation.

Logging

For every added or edited tracing call:

• Reuse the module's EVENT_*, LOG_COMPONENT_*, and LOG_SUBSYSTEM_* constants and field shape.
• Put fields first and a short label last.
• Use error for behavior/security failure, warn for degradation/fallback, info for low-frequency lifecycle, debug for diagnostics, and trace for repetitive request/object success paths.
• Never log secrets, credential payloads, or merged configs.

Use .agents/skills/rustfs-logging-governance/SKILL.md for logging changes.

Cross-Cutting Storage Invariants

• Write internal object metadata under both x-rustfs-internal-<suffix> and x-minio-internal-<suffix> using crates/utils/src/http/metadata_compat.rs helpers.
• Read binary UUID metadata with .and_then(|v| Uuid::from_slice(&v).ok()).filter(|u| !u.is_nil()); absent, empty, and nil all mean no value.
• Remote-tier version None or "" means an unversioned bucket; send no versionId on tier GET/DELETE.
• DataUsageCacheInfo and DataUsageEntry keep their hand-written map serialization and new fields remain #[serde(default)] for older readers.

Naming

Use Rust API naming: SCREAMING_SNAKE_CASE constants/statics, snake_case functions/variables, and PascalCase types. Do not rename unrelated existing violations.

Scoped Guidance

Before editing, locate the nearest instructions with:

git ls-files '*AGENTS.md'

The nearest file wins for domain invariants. Keep generic workflow and validation policy in this root file.