Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Rust development
Read this for backend changes in crates/, services/, or Rust tooling.
Return to the repository guide for other task guides.
Before editing
- The Rust rules in
.agents/rules/rust/own the coding conventions, including errors, tracing, public docs, and test layout; the config rule owns configuration. - Follow the hexagonal architecture skill before changing backend Rust. Keep domain policy and authorization in domain services; inbound adapters call services and outbound adapters implement ports.
- Find the owning crate before adding logic. Do not grow catch-all crates or bypass the owning domain's APIs with direct database access.
- For queries, migrations, or SQLx failures, use database development.
Environment
Run commands from the repository root inside nix develop, unless a guide says
otherwise. Nix supplies Cargo, the Rust toolchain, just, SQLx, and the other
build tools; see local prerequisites.
Database-backed tests need running local Postgres (and Redis where used). Crates with compile-time SQLx macros may need Postgres even to compile their unit tests. Standalone pure-logic crates need no database setup.
- Local machine: use the database guide for test infrastructure, or running locally for the full product.
- Cursor Cloud: use the Cloud entry points, not the local
stack TUI. Run
bash .cursor/infra.shbefore DB-backed tests.
Build and check
| Command | Purpose |
|---|---|
cargo build -p <package> |
Build the affected Cargo package. |
just build |
Build with the workspace's default Cargo selection, using the SQLx cache. |
just rust-check |
Type-check the Rust workspace using the SQLx cache. |
cargo fmt |
Format Rust code. |
just check |
Fast, change-scoped format/lint/code-rule/PII gate; not a type check or test runner. |
just check full |
Add TypeScript checking and Rust clippy to the gate. |
just clippy |
Run workspace Rust lints using the SQLx cache. |
SQLX_OFFLINE=true is allowed for cargo check, cargo build, and cargo clippy
when the cache is current. Do not export it for a session that will run tests.
For deployable Lambda artifacts, use just build_lambdas or the relevant
service's build recipe, e.g. just services/document_text_extractor/build.
Use just --show <recipe> to check prerequisites; do not assume all Lambdas
have the same build requirements.
Command definitions live in rust.just and check.just.
Test the affected packages
Use the package name from the affected Cargo.toml, not a guessed spelling of
its directory name. Run each affected package's tests before committing:
unset SQLX_OFFLINE
cargo test -p <package>
There is no root just test recipe. Tests use the live local schema, not offline
query metadata. If a test reports missing SQLx cache data, follow the
database troubleshooting workflow;
do not enable offline mode to work around it.
CI runs test and check on a 32 vCPU, 64 GiB runner with no build job limit.
Don't lift the job limit on the 8 vCPU, 16 GiB runner by itself: linking many
large test binaries exhausts its memory and can lose the runner.
Keep tests in a sibling test.rs (CS-49). For example, src/user.rs declares:
#[cfg(test)]
mod test;
The tests themselves live in src/user/test.rs and can use use super::*;.
A file module can coexist with its directory; do not convert user.rs to
user/mod.rs just to add tests.
Update regression tests for changed behavior, including allow/deny cases for authorization changes. Run relevant tests between batches of query changes and refresh SQLx metadata as directed by the database guide. If you cannot run a check, report the command and blocker rather than treating it as passed.