Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
description: "Type design, idioms, errors and observability, performance, and tests." paths: - "crates//*.rs" - "services//.rs" - "tooling/**/.rs" globs: "crates//*.rs,services//.rs,tooling/**/.rs" alwaysApply: false
Rust code
Type design, idioms, errors and observability, performance, and tests.
- CS-10 Newtype your identifiers and tokens — wrap raw
Stringids/tokens/model-ids in a validated newtype that checks shape at construction. - CS-11 A closed set of string values is an enum, not a
String— implDisplay/FromStras needed. - CS-12 Optional means
Option<T>— don't rely on sentinel values or convention to express absence. - CS-13 Model tri-state data (not-loaded / missing / present) as one flat
enum, not nested
Options or ad-hoc flags. - CS-19 Give third-party errors their own variant — don't collapse e.g. a
jsonwebtokenfailure into a generic internal error. A provider outage (5xx, 429, unreachable, undecodable) is anupstream_error::UpstreamError, answered 502/503 — seecrates/upstream_error. - CS-20 Depending on a rate-limited external provider requires a fallback (fallback model, retry story, or documented degradation).
- CS-21 Wire usage metering on every invocation path — MCP-triggered tool calls count too, not just the primary path.
- CS-22 When adding
#[tracing::instrument], includeerronResultfunctions and omit it on other return types. Never setlevel = "info"on the attribute. Log errors as structured fields (tracing::error!(error=?e, "msg")); prefer.inspect_erroverif let Err(e)for logging. - CS-40 Repeated literals become named consts.
- CS-41 Don't use
#[allow(...)]— use#[expect(..., reason = "...")]on the narrowest item it applies to;allowsilently rots when the lint stops firing,expectwarns. - CS-42 Don't re-state trait bounds already implied by a supertrait.
- CS-43 Use the smallest type that makes invalid states unrepresentable: a
counter that can't go negative is unsigned, one that can't plausibly pass 255
is a
u8. - CS-44 Large inline strings belong in files — use
include_str!. - CS-45 CLI binaries use
clap, not hand-rolled arg parsing. - CS-46 Use
rootcausefor error handling in new code — it's preferred overanyhowthese days. In code that's still on anyhow, preferbail!for early error returns. - CS-47 Keep latency-critical services thin: push bytes directly instead of
round-tripping through presigned URLs or extra services; dispatch non-blocking
background work with
wait_until. - CS-48 Don't do per-message work on hot websocket paths — accumulate and flush on a timer/alarm.
- CS-49 Tests live in a sibling
test.rs, not inline#[cfg(test)]blocks in the implementation file. See the Rust guide. - CS-50 Update affected tests for db-crate changes. Refresh SQLx metadata
when queries/schema change or required cache data is missing, not for
unrelated Rust-only edits. Run affected tests with
SQLX_OFFLINEunset. See the database guide. - CS-54 New library crates (not service binaries) put
#![deny(missing_docs)]inlib.rsand document all public items. Do not mark documentation code blocksignoreto skip doctests unless explicitly directed. - CS-55 AI spans follow the OpenTelemetry GenAI conventions (
gen_ai.*, seecrates/genai_telemetry). Agent sessions of every harness are traced in one place: the session actor projects each session's ACP frames ontoinvoke_agent/execute_toolspans (crates/agent_session/src/domain/session/telemetry.rs), so do not add GenAI spans to a harness runtime —agent_inmemruns its agent loop withwith_genai_telemetry(false)for that reason. Outside sessions (chat inagent_harness_service::cognition), the agent loop andai_toolset::ToolSet::try_tool_callemit and enrich theinvoke_agent/chat/execute_toolspans; do not open tool spans in tools or toolsets, and never record prompts, tool arguments or tool results as span fields or logs — they are content, recorded on the spans under theOTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTpolicy and a size budget. - CS-73 A function that reaches a service's router or composition root is
never a non-generic
pub async fn, even in a private module: rustc compiles the body of every such function in every build, so the lib test compiles the whole service. Usepub(crate) async fn, orpub fn run() -> impl Futureover a privateasync fnwhen another crate calls it. - CS-68 Don't mark types
#[non_exhaustive]by default. Exhaustive matches are how a new variant reaches every place that must handle it; reserve the attribute for types published outside the workspace. - CS-69 Derive serde, schema, and other traits on the type itself. Don't
keep parallel copies (a
wire.rsmirror of domain types) just to carry derives; add a separate type only when the wire shape genuinely differs.