- name
- agent-guardrails
- description
- General agent safety and workflow guardrails that prevent high-impact mistakes across tooling, verification, versions, integration layers, environment/config, import-time side effects, and high-risk actions. Use when defining or applying behavioral constraints for coding agents, repo automation rules, or operational safety checklists.
General Agent Guardrails
Purpose
Apply these rules to prevent high-impact agent mistakes (tooling drift, bypassed checks, version mismatches, integration bypasses, env/config corruption, serverless import side effects).
When unsure, consult:
- AGENTS.md for agent behavior and non-negotiables
- CONVENTIONS.md for repo-wide contracts (imports, build/runtime expectations, platform constraints)
If still unclear after checking those docs and existing code patterns: stop and ask.
1) Follow Existing Contracts (don't invent new ones)
- Prefer the repository's existing choices: tooling, frameworks, package manager, test runner, build pipeline, import style, integration patterns.
- Do not introduce "better" alternatives (new frameworks/tools, new config styles, new package managers, new test runners, mass import rewrites) as part of unrelated work.
- Before changing any cross-cutting behavior, confirm the standard by:
1) checking AGENTS.md and CONVENTIONS.md 2) inspecting existing scripts/config (package.json, lockfiles, CI config) 3) mirroring dominant patterns in the codebase
- If a change would affect multiple files/systems or alter how the repo builds/tests/deploys: stop and ask for explicit approval.
(Examples of "contracts": package manager and lockfile, test framework, bundler import rules, gateway/adapter usage, serverless-safe patterns.)
2) Never Bypass Verification or Silence Failures
- Treat verification gates (hooks, CI, tests, lint, typecheck, build steps, security scans) as mandatory.
- Do not bypass, disable, weaken, or work around verification:
- no --no-verify - no skipping steps conditionally to "make builds pass" - no turning errors into warnings without approval
- If a check fails:
1) capture the exact failing command and error output 2) fix the root cause or revert/isolate the change that introduced it 3) re-run until green
- If you suspect it is pre-existing, provide evidence (baseline or prior green reference). Without evidence: treat as yours to fix.
- If the gate is flaky or misconfigured: gather logs and reproduction, then stop and ask.
3) Version and Entry-Point Discipline (APIs, types, imports)
- Match code to the versions installed in the repo (package.json and lockfile).
- Do not copy patterns from other major versions or random examples without verifying compatibility.
- Treat compiler/type errors as signals of mismatch (version, entrypoint, runtime), not noise.
- Prefer canonical entrypoints:
- If the repo provides wrappers/re-exports for typed libs (ORMs, SDK clients, codegen types), use them. - Avoid mixing import paths that create duplicate type identities.
- If multiple patterns exist and it is unclear which is canonical: check CONVENTIONS.md, then stop and ask.
4) Use Canonical Integration Layers (don't bypass platforms/wrappers)
- Use the canonical integration layer already used in the repo.
- Do not bypass it by:
- calling vendor SDKs directly - creating ad-hoc clients/config styles - hardcoding endpoints/keys when centralized routing is expected
- If the abstraction seems insufficient:
- explain why - propose a minimal extension to the canonical layer - stop and ask for approval before implementing a parallel path
(This covers "provider functions vs gateway strings" and similar patterns for auth, payments, analytics, storage, etc.)
5) Environment and Deployment Reality (scope, platforms, reproducibility)
Environment scope
- Keep env/config scoped to the runtime that consumes it (app/service/job), not the repo root.
- Do not assume
.envis shared across apps/services, or that local/CI/prod behave the same. - Identify the consumer runtime, find where it loads env, and apply changes at the narrowest valid scope.
- If scope is unclear: check CONVENTIONS.md, then stop and ask.
Managed platform constraints
- Follow platform defaults and repo lockfile/tooling choices for deploy environments.
- Do not switch package managers/tooling in managed platforms unless explicitly documented and verified.
- Avoid conflicting lockfiles and non-reproducible installs.
Safe config writes
- Treat env/config values as byte-sensitive.
- Do not introduce hidden whitespace/newlines when writing secrets/config.
- Use newline-safe write patterns (for example,
printf) and sanity-check results.
6) Import-Time Purity (safe initialization across contexts)
- Assume imports may run during build/bundling/test discovery/SSR/workflow registration/cold start.
- Do not require runtime-only resources or perform side effects at module scope:
- initializing clients that require secrets/config - opening network connections/listeners - filesystem writes, global patching, background timers
- Defer initialization to explicit runtime boundaries (handlers/jobs/CLI main) or lazy getters/factories.
- If unsure whether import-time code is safe: check CONVENTIONS.md, then stop and ask.
7) High-Risk Actions Require Explicit Approval (AGENTS.md)
- Do not implement or automate high-blast-radius operations by default (money movement, billing changes, permission changes, destructive data ops, bulk actions).
- If requested, check AGENTS.md and CONVENTIONS.md for the approved workflow; if not documented, stop and ask for explicit human approval.