Imported from alessandrobologna/agentcore-rust (AGENTS.md). Install upstream with npx skills add alessandrobologna/agentcore-rust. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

• Core Axum entrypoint lives in src/main.rs; add new routes as submodules under src/ to keep the handler tree cohesive.
• Helper automation sits in scripts/ (Python invokers) and tools/ (bench harness); extend these instead of sprinkling one-off scripts.
• Deployment assets span Makefile, Dockerfile, template.yaml, and samconfig.toml; update them together when altering Lambda packaging.
• Reference design notes in docs/, and drop benchmark artifacts into performance-results/ after each tuning pass.

Build, Test, and Development Commands

• cargo build compiles the service; append --release for perf testing or images.
• cargo run launches the local server on 0.0.0.0:8080 for manual curl checks.
• cargo fmt && cargo clippy --all-targets --all-features enforces style and lint hygiene before any PR.
• make build mirrors CI’s debug build; make test-local spins the ARM64 Docker image for smoke tests.
• make deploy builds, pushes to ECR, and triggers sam deploy; ensure AWS credentials are active.

Coding Style & Naming Conventions

• Follow Rust 2021 defaults: four-space indent, snake_case for modules/functions, UpperCamelCase for types, SHOUTY_SNAKE_CASE for constants.
• Keep handlers async and side-effect free; push shared helpers into dedicated modules.
• Prefer structured logs via tracing; limit startup println! output to essential diagnostics.

Testing Guidelines

• Use cargo test for unit coverage; colocate module tests behind #[cfg(test)] with descriptive names.
• Place integration scenarios under tests/ using tokio::test and fixture payloads from tests/data/.
• Capture latency regressions by rerunning the bench harness in tools/router-bench when touching routing logic.

Commit & Pull Request Guidelines

• Write imperative commits ≤72 characters, e.g., Add sandbox UUID logging.
• PRs must link the tracking issue, describe functional impact, and document manual or automated test evidence.
• Attach curl transcripts or screenshots for API changes and call out any AWS resources touched.
• Request review before merge and verify cargo fmt, cargo clippy, cargo test, and make build are green.

Security & Configuration Tips

• Store secrets outside the repo; rely on AWS Parameter Store or Secrets Manager during deploys.
• Validate IAM tweaks with least-privilege diffs before running make deploy.
• When adding environment variables, mirror them in template.yaml and local .env examples if applicable.