docs: scope AGENTS instructions by directory (#2083)

crates/AGENTS.md

@@ -0,0 +1,20 @@
+# Crates Instructions
+
+Applies to all paths under `crates/`.
+
+## Library Design
+
+- Treat crate code as reusable library code by default.
+- Prefer `thiserror` for library-facing error types.
+- Do not use `unwrap()`, `expect()`, or panic-driven control flow outside tests.
+
+## Testing
+
+- Keep unit tests close to the module they test.
+- Keep integration tests under each crate's `tests/` directory.
+- Add regression tests for bug fixes and behavior changes.
+
+## Async and Performance
+
+- Keep async paths non-blocking.
+- Move CPU-heavy operations out of async hot paths with `tokio::task::spawn_blocking` when appropriate.

crates/config/AGENTS.md

@@ -0,0 +1,28 @@
+# Config Crate Instructions
+
+Applies to `crates/config/`.
+
+## Environment Variable Naming
+
+- Global configuration variables must use flat `RUSTFS_*` names.
+- Do not introduce module-segmented names such as `RUSTFS_CONFIG_*`.
+
+Canonical examples:
+
+- `RUSTFS_REGION`
+- `RUSTFS_ADDRESS`
+- `RUSTFS_VOLUMES`
+- `RUSTFS_LICENSE`
+- `RUSTFS_SCANNER_ENABLED`
+- `RUSTFS_HEAL_ENABLED`
+
+## Compatibility
+
+- Deprecated aliases must keep warning behavior.
+- Document aliases in `crates/config/README.md`.
+- Any alias change should include tests for both canonical and deprecated forms.
+
+## Source of Truth
+
+- Constants: `crates/config/src/constants/app.rs`
+- Naming conventions: `crates/config/README.md#environment-variable-naming-conventions`

crates/e2e_test/AGENTS.md

@@ -0,0 +1,26 @@
+# E2E Test Crate Instructions
+
+Applies to `crates/e2e_test/`.
+
+## Test Reliability
+
+- Keep end-to-end tests deterministic and environment-aware.
+- Prefer readiness checks and explicit polling over fixed sleep-based timing assumptions.
+- Ensure tests isolate resources and clean up temporary state.
+
+## Environment Safety
+
+- For local KMS-related E2E runs, keep proxy bypass settings:
+  - `NO_PROXY=127.0.0.1,localhost`
+  - clear `HTTP_PROXY` and `HTTPS_PROXY`
+- Do not hardcode machine-specific paths or credentials.
+
+## Scope and Cost
+
+- Place exhaustive integration behavior here; keep unit behavior in source crates.
+- Keep new E2E scenarios focused and avoid redundant overlap with existing suites.
+
+## Suggested Validation
+
+- `cargo test --package e2e_test`
+- Full gate before commit: `make pre-commit`

crates/ecstore/AGENTS.md

@@ -0,0 +1,28 @@
+# ECStore Crate Instructions
+
+Applies to `crates/ecstore/`.
+
+## Data Durability and Integrity
+
+- Do not weaken quorum checks, bitrot checks, or metadata validation paths.
+- Treat any change affecting read/write/repair correctness as high risk and test accordingly.
+- Prefer explicit failure over silent data corruption or implicit success.
+
+## Performance-Critical Paths
+
+- Be careful with allocations and locking in hot paths.
+- Keep network and disk operations async-friendly; avoid introducing unnecessary blocking.
+- Benchmark-sensitive changes should include measurable rationale.
+
+## Cross-Module Coordination
+
+- Validate behavior impacts on:
+  - `rustfs/src/storage/`
+  - `crates/filemeta/`
+  - `crates/heal/`
+  - `crates/checksums/`
+
+## Suggested Validation
+
+- `cargo test -p rustfs-ecstore`
+- Full gate before commit: `make pre-commit`

crates/iam/AGENTS.md

@@ -0,0 +1,27 @@
+# IAM Crate Instructions
+
+Applies to `crates/iam/`.
+
+## Security Boundaries
+
+- Treat IAM changes as security-sensitive by default.
+- Never log secrets, tokens, private claims, or credential material.
+- Keep deny/allow evaluation behavior consistent with existing tests unless explicitly changing policy semantics.
+
+## Contract Stability
+
+- Preserve compatibility of user/group/policy attachment behavior and token claim handling.
+- When changing IAM interfaces, verify impacted call sites in:
+  - `rustfs/src/auth.rs`
+  - `rustfs/src/admin/`
+  - `crates/policy/`
+
+## Error Handling
+
+- Return explicit errors; do not use panic-driven control flow outside tests.
+- Keep error messages actionable but avoid leaking sensitive context.
+
+## Suggested Validation
+
+- `cargo test -p rustfs-iam`
+- Full gate before commit: `make pre-commit`

crates/kms/AGENTS.md

@@ -0,0 +1,27 @@
+# KMS Crate Instructions
+
+Applies to `crates/kms/`.
+
+## Change Coordination
+
+When changing key-management behavior, verify compatibility with:
+
+- `rustfs/src/storage/ecfs.rs`
+- `rustfs/src/admin/handlers/kms.rs`
+- `rustfs/src/admin/handlers/kms_dynamic.rs`
+- `rustfs/src/admin/handlers/kms_keys.rs`
+- `rustfs/src/admin/handlers/kms_management.rs`
+
+## Security
+
+- Never log plaintext keys, key material, or sensitive request payloads.
+- Prefer explicit error propagation over panic paths.
+
+## Testing
+
+For local KMS end-to-end tests, keep proxy bypass settings:
+
+```bash
+NO_PROXY=127.0.0.1,localhost HTTP_PROXY= HTTPS_PROXY= http_proxy= https_proxy= \
+cargo test --package e2e_test test_local_kms_end_to_end -- --nocapture --test-threads=1
+```

crates/policy/AGENTS.md

@@ -0,0 +1,26 @@
+# Policy Crate Instructions
+
+Applies to `crates/policy/`.
+
+## Policy Semantics
+
+- Keep action/resource/condition evaluation semantics stable unless compatibility changes are explicitly requested.
+- Avoid introducing permissive fallbacks that may expand access unexpectedly.
+- Any semantic change must include focused regression tests.
+
+## Integration Awareness
+
+- Validate compatibility with IAM and request-auth call sites:
+  - `crates/iam/`
+  - `rustfs/src/auth.rs`
+  - `rustfs/src/storage/access.rs`
+
+## Error and Observability
+
+- Prefer explicit, typed errors over implicit fallback behavior.
+- Log policy evaluation diagnostics without exposing sensitive credential content.
+
+## Suggested Validation
+
+- `cargo test -p rustfs-policy`
+- Full gate before commit: `make pre-commit`