agent-guardrails（Agent 护栏）

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 .env is 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.