Security privacy
Secrets, capabilities, unsafe code, diagnostic data, and other trust-boundary concerns.
21 items in this guidance cluster.
Tagged guidance
Guide item
Agent workflow rules
Encode nonfunctional requirementsPut invisible constraints such as security, accessibility, latency, and compatibility near the task. Encoding them upfront makes those requirements part of the implementation target.Grant scoped capabilitiesGive agents only the permissions and external authority the task actually needs. Scoped capability keeps progress possible while reducing accidental mutation, publication, or exposure.Keep secrets out of contextAvoid putting real credentials or sensitive values into prompts, docs, logs, and tests. Keeping secrets out of context reduces leakage through retained, repeated, or committed text.Prove security impactSeparate security hypotheses from proof of reachability, exploitability, assets, and user impact. This keeps prioritization and mitigation tied to demonstrated risk.
Boundary rules
Give tools identity policy and limitsGive effectful callable units typed identity, authorization policy, cancellation, and bounded output. The added ceremony is reserved for real tool boundaries where auditability, recovery, and blast-radius control matter.Make policy boundaries explicitRoute writes, network calls, shell execution, publication, telemetry, redaction, and credential use through a visible policy decision before effects run. Callers can then understand allowed, denied, redacted, fallback, preserved, and unsupported outcomes.
Observability rules
Keep diagnostics retention safeMatch diagnostic detail to its audience and retention period. Redact or summarize sensitive values while preserving enough operation context to debug.Keep recovery advice safe and honestGive recovery advice only when the program knows enough to make it safe. Report observed facts, label uncertainty, and avoid destructive, security-weakening, or policy-bypassing next steps unless the current state proves they are appropriate.Log at owned boundariesEmit logs where the code still knows the operation, intent, input class, and external boundary. That placement gives useful context without duplicating noise through every layer.
Rust rules
Contain unsafeKeep unsafe blocks small, wrapped by safe APIs, documented, and tested through safe behavior. Localized obligations make the safety argument auditable.Deny accidental unsafeUse a crate-level lint when a crate intends to avoid unsafe code entirely. Executable policy catches accidental unsafe before it becomes normal implementation detail.Implement debug for public typesProvide Debug for public types unless it would expose secrets or mislead callers. The trait is baseline support for tests, assertions, logs, and downstream diagnostics.Validate unsafe through safe APITest unsafe internals through the safe API wrapper that callers rely on. Internal unsafe tests and tools such as Miri should support, not replace, proof that safe calls uphold the contract.
Pattern items
Avoid secret or private log contextDiagnostics can outlive their request and move through systems with different access rules. Record safe identifiers and classifications at the boundary that understands data sensitivity, using explicit protected workflows for rare sensitive evidence.Contain observability policyLogging, metrics, tracing, and privacy choices become inconsistent when every call site invents its own policy. Put observability decisions at owned boundaries so lower layers expose facts without duplicating policy.Document errors panics safetyCallers need to know which failures are recoverable, which conditions panic, and what safety obligations an API imposes. Document those contracts at the public boundary so users can compose the API deliberately.Encode nonfunctional requirementsPerformance, security, accessibility, privacy, and reliability expectations are easy to lose when they live only in prose. Encode important requirements in tests, budgets, schemas, automation, or review gates where the system can keep enforcing them.Grant scoped agent capabilitiesBroad tool access increases the blast radius of agent mistakes and makes review harder. Grant the smallest capabilities needed for the current task, then expand deliberately when the work proves it needs more reach.Keep secrets out of contextSecrets and private data can leak through prompts, transcripts, logs, and generated artifacts even when the code change is harmless. Redact or replace sensitive values before they enter shared context, and use controlled channels when real secrets are required.Prove security impactSecurity reports create noise when they imply exploitability without showing reachability or consequence. Prove the attacker path and impact, or clearly label the finding as an unproven hypothesis.