Back to Details

guardrails

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Guardrails

Guardrails

Verification gates that block the agent from proceeding until checks pass. The agent already knows what linting, testing, type checking, and security scanning are. This skill doesn't re-teach those concepts. Instead, it specifies:
  • When each check runs in the agent lifecycle (hooks that block progress)
  • What to do when stuck (diagnostic escalation instead of retrying)
  • What not to touch (config protection, high-risk action gating)
  • How to accumulate knowledge (lessons learned, agent tool library)
These are the behaviors a coding agent wouldn't exhibit without being told. Everything else — which linter to use, how to structure a unit test — the agent already knows from training and discovers from the project's existing config.
Bundled resources: 
references/tool-building.md
contains the diagnostic tool and notation catalogs with worked examples. 
references/language-defaults.md
is a lookup table for tool selection by ecosystem. Read these when directed, not proactively.
这是一类验证关卡，只有通过所有检查后，Agent才能继续执行。Agent已了解代码检查（linting）、测试、类型检查和安全扫描的概念，本技能不会重复讲解这些内容，而是明确规定：
  • 检查时机：各项检查在Agent生命周期中的触发节点（会阻断流程的钩子）
  • 卡顿时的处理方式：转为诊断排查而非重复重试
  • 禁止修改内容：配置保护、高风险操作管控
  • 知识积累方式：经验总结、Agent工具库
这些是未经告知时，编码Agent不会主动展现的行为。其他内容——比如使用哪个代码检查工具、如何编写单元测试结构——Agent已通过训练掌握，也可从项目现有配置中自动发现。
配套资源：
references/tool-building.md
包含诊断工具和符号目录，并附实例说明。
references/language-defaults.md
是按生态系统划分的工具选择对照表。仅在需要时查阅，无需主动阅读。

Scope

适用范围

Not every check applies to every project. The common base applies everywhere: lint, format, types, SAST, dependency audit, secrets scan, dead code detection, duplicate code detection, coverage, unit tests. Beyond that, add layers by project type:
  • Backend / API: integration tests. Usually: property-based, contract, performance.
  • Frontend: integration tests. Usually: screenshot, E2E, accessibility.
  • Full-stack: integration tests. Usually: screenshot, E2E, contract, accessibility.
  • Library / SDK: Usually: property-based, mutation.
  • Data pipeline: integration tests. Usually: property-based, performance.
  • Infrastructure / IaC: integration tests (plan/apply validation).
Scale up as the project matures. A prototype needs the common base. A production system serving users needs the full suite.
Common base: lint, format, types, SAST, dependency audit, secrets scan, dead code detection, duplicate code detection, coverage, unit tests. Dead code and duplicate code tools by ecosystem are listed in 
references/language-defaults.md
.
并非所有检查都适用于所有项目。通用基础检查适用于所有场景：代码检查、格式化、类型检查、静态应用安全测试（SAST）、依赖审计、密钥扫描、死代码检测、重复代码检测、覆盖率检查、单元测试。除此之外，可根据项目类型增加额外检查层：
  • 后端/API：集成测试。通常包括：基于属性的测试、契约测试、性能测试。
  • 前端：集成测试。通常包括：截图测试、端到端（E2E）测试、可访问性测试。
  • 全栈：集成测试。通常包括：截图测试、端到端（E2E）测试、契约测试、可访问性测试。
  • 库/SDK：通常包括：基于属性的测试、突变测试。
  • 数据流水线：集成测试。通常包括：基于属性的测试、性能测试。
  • 基础设施/IaC：集成测试（计划/应用验证）。
可随项目成熟度逐步扩展检查范围。原型项目只需通用基础检查，面向用户的生产系统则需要完整的检查套件。
通用基础检查：代码检查、格式化、类型检查、静态应用安全测试（SAST）、依赖审计、密钥扫描、死代码检测、重复代码检测、覆盖率检查、单元测试。各生态系统对应的死代码和重复代码工具可查阅
references/language-defaults.md
。

Lifecycle Hooks

生命周期钩子

Everything above is just guidance — the agent might follow it, might not. The hooks below are what make guardrails real. They block the agent from proceeding until checks pass. The distinction matters: a lint rule that runs in 20ms and fails the build gives the agent concrete, unambiguous feedback. A prose instruction in a skill file sits in the context window competing for attention with everything else.
以上内容仅为指导——Agent可选择遵循或不遵循。而下面的钩子是让防护机制生效的核心，它们会在检查未通过时阻断Agent流程。两者的区别在于：一个耗时20毫秒的代码检查规则若失败会直接终止构建，为Agent提供明确、无歧义的反馈；而技能文件中的文字说明只是在上下文窗口中与其他内容竞争注意力。

Test Runner Discovery

测试运行器发现

The enforcement system needs two commands in the target project — one fast, one full:
Fast check — Runs in seconds. Fires on every agent stop. Covers: format check, lint, type check, unit tests.
Full suite — Runs before every commit. Covers: everything in the fast check plus integration tests, property tests, secrets scan, dead code detection, duplicate code detection, coverage floor.
Discover, don't impose. Every ecosystem has its own convention: npm scripts (
npm test
, 
npm run test:unit
), Makefile targets (
make test
, 
make check
), Go commands (
go test ./...
), pytest (
pytest tests/unit
), bun scripts, Cargo, etc. During SessionStart, find what the project already uses by inspecting package.json scripts, Makefile targets, CI workflow steps, and README instructions. Adapt to the project's existing runner — don't create a new one alongside it.
If no test runner exists at all, create one using the project's native tooling. Consult 
references/language-defaults.md
for tool selection. The runner must exit non-zero on failure.
执行系统需要目标项目中的两个命令——一个快速检查命令，一个完整检查命令：
快速检查：耗时数秒，每次Agent停止执行时触发。覆盖范围：格式检查、代码检查、类型检查、单元测试。
完整套件检查：每次提交前触发。覆盖范围：快速检查的所有内容，加上集成测试、基于属性的测试、密钥扫描、死代码检测、重复代码检测、覆盖率下限检查。
自动发现，而非强制植入：每个生态系统都有自己的约定：npm脚本（
npm test
、
npm run test:unit
）、Makefile目标（
make test
、
make check
）、Go命令（
go test ./...
）、pytest（
pytest tests/unit
）、bun脚本、Cargo等。在SessionStart阶段，通过检查package.json脚本、Makefile目标、CI工作流步骤和README说明，找到项目已在使用的工具。适配项目现有运行器——不要在其旁新建一个运行器。
如果项目完全没有测试运行器，则使用项目原生工具创建一个。可查阅
references/language-defaults.md
选择工具。运行器必须在失败时返回非零退出码。

SessionStart

SessionStart

Fires when the agent boots up. Discovery and baseline before touching anything.
  • Record git state (HEAD SHA, working tree status) as a session baseline.
  • Discover existing guardrails: inspect config files, CI pipelines, test directories. Identify the project type (Scope section) and determine which checks apply.
  • Read existing test files to learn conventions — naming, structure, assertion style, mocking, fixtures. Match them.
  • Read 
    LESSONS_LEARNED.md
    if it exists. Apply project-specific lessons.
  • Check for 
    script/agent-tools/
    . Read the directory and description comments to know what diagnostic tools are available from previous sessions.
Defer to existing conventions. When the project has tooling or patterns in place, follow them — even when they conflict with this skill. Do not switch tools or frameworks without explicit user approval.
在Agent启动时触发。在进行任何操作前先完成发现和基线检查。
  • 记录git状态（HEAD SHA、工作区状态）作为会话基线。
  • 发现现有防护机制：检查配置文件、CI流水线、测试目录。确定项目类型（参考适用范围章节）并明确适用的检查项。
  • 阅读现有测试文件，了解约定——命名规则、结构、断言风格、模拟、夹具。遵循这些约定。
  • 如果存在
    LESSONS_LEARNED.md
    ，请阅读。应用项目特定的经验总结。
  • 检查
    script/agent-tools/
    目录。阅读该目录及描述注释，了解之前会话中可用的诊断工具。
优先遵循现有约定：当项目已有工具或模式时，遵循它们——即使与本技能冲突。未经用户明确批准，不得切换工具或框架。

Stop

Stop

Fires every time the agent returns control. Prevents declaring success without verification.
  • Run the fast check. Block if it fails.
  • If production code changed, verify tests also changed. Untested code is unverified code, regardless of whether it "looks right."
Thrashing circuit breaker. If the fast check fails and the agent has already attempted the same fix twice, it cannot try a third direct fix:
  1. After attempt 1 fails: Try a direct fix. Normal.
  2. After attempt 2 fails: Stop. Build a diagnostic tool or switch to a notation (read 
    references/tool-building.md
    ). Two failed attempts means the agent's model of the problem is wrong — re-reading the same code produces the same wrong model. New information or a different representation breaks the loop.
  3. After attempt 3 fails (with diagnostic): Stop entirely. Report to the user: what's failing, what was tried, what the diagnostic revealed, why it isn't converging.
The breaker resets when the user provides new direction. Persist useful diagnostics to 
script/agent-tools/
.
Work in slices. Stop frequently. A good slice is 1-3 production files plus tests. An agent that writes 15 files then discovers a type error in file 3 has wasted 4-15.
每次Agent交回控制权时触发。防止未经验证就宣告成功。
  • 运行快速检查。若失败则阻断流程。
  • 如果生产代码发生变更，需验证测试代码也已同步变更。未经过测试的代码即为未验证代码，无论其「看起来是否正确」。
震荡断路器：如果快速检查失败，且Agent已尝试相同修复两次，则不能进行第三次直接修复：
  1. 第一次尝试失败后：尝试直接修复。正常流程。
  2. 第二次尝试失败后：停止直接修复。构建诊断工具或切换为符号表示（阅读
    references/tool-building.md
    ）。两次失败意味着Agent对问题的模型认知错误——重复阅读相同代码会产生相同错误模型。新信息或不同的表示方式可打破循环。
  3. 第三次尝试（含诊断）失败后：完全停止。向用户报告：失败内容、已尝试的操作、诊断结果、无法收敛的原因。
当用户提供新的指导方向后，断路器重置。将有用的诊断工具保存到
script/agent-tools/
目录。
分块工作：频繁停止。一个合理的工作块是1-3个生产文件加对应的测试文件。如果Agent编写了15个文件后才发现第3个文件存在类型错误，那么4-15号文件的工作都白费了。

Commit (PreToolUse + git hooks)

Commit阶段（PreToolUse + git hooks）

Fires on any 
git commit
, whether from the agent or a human. Same enforcement for both.
  • Run the full suite. Block if it fails.
  • Secrets scan on staged files.
  • Verify commit message follows project conventions.
  • Integration/deployment check: Verify the change is reachable, not just correct. Code that passes tests but isn't wired into the application is a deployment gap. Confirm: new modules imported? Routes registered? Migrations included? Entry points updated? If nothing invokes the new code, that's a failure even with passing tests.
在任何
git commit
操作时触发，无论操作来自Agent还是人类。对两者执行相同的检查规则。
  • 运行完整套件检查。若失败则阻断流程。
  • 对暂存文件进行密钥扫描。
  • 验证提交信息是否符合项目约定。
  • 集成/部署检查：验证变更是否可被调用，而非仅逻辑正确。通过测试但未接入应用的代码存在部署缺口。确认：新模块是否已导入？路由是否已注册？迁移脚本是否已包含？入口文件是否已更新？如果没有任何代码调用新功能，即使测试全部通过，也视为失败。

Tool Building and Notation

工具构建与符号表示

When direct fixes fail, the agent needs new information or a different problem representation. Read 
references/tool-building.md
 for the full catalog of diagnostic tools, notations, and three worked examples.
The circuit breaker (Stop hook) mandates reading this reference after 2 failed attempts. But the best use is proactive: recognize the problem shape during planning and build scaffolding before writing code. Common patterns:
  • Modifying a function's interface → build a call site inventory first
  • Complex conditional logic (>3 booleans or >4 branches) → build a decision matrix
  • State machine behavior → build a state transition table
  • Data transformation pipeline → trace sample values through each stage
  • Unfamiliar codebase area → build a codebase index before editing
Diagnostic tools often graduate into permanent infrastructure — reproduction scripts become test cases, schema checkers become health checks, dependency mappers feed the integration check. Building a diagnostic tool is not a detour; it's often the most direct path to completing the task.
当直接修复失败时，Agent需要新信息或不同的问题表示方式。**阅读
references/tool-building.md
**获取完整的诊断工具、符号表示目录及三个实例。
震荡断路器（Stop钩子）要求在两次尝试失败后查阅此参考文档。但最佳使用方式是主动预判：在规划阶段识别问题类型，在编写代码前搭建脚手架。常见模式：
  • 修改函数接口 → 先构建调用站点清单
  • 复杂条件逻辑（>3个布尔判断或>4个分支）→ 构建决策矩阵
  • 状态机行为 → 构建状态转换表
  • 数据转换流水线 → 跟踪样本值在每个阶段的流转
  • 不熟悉的代码区域 → 在编辑前先构建代码库索引
诊断工具通常会逐步演变为永久基础设施——复现脚本成为测试用例，Schema检查器成为健康检查，依赖映射器为集成检查提供数据。构建诊断工具并非绕路，往往是完成任务最直接的路径。

Config Protection

配置保护

The agent does not edit its own guardrail configuration. An agent under pressure to make tests pass has an incentive to weaken the tests rather than fix the code. Block the agent from modifying: test scripts, lint/format/type config, CI definitions, pre-commit config, and coverage thresholds. If config needs changing, propose it to the user.
Agent不得修改自身的防护机制配置。当Agent面临必须通过测试的压力时，可能会倾向于弱化测试而非修复代码。禁止Agent修改：测试脚本、代码检查/格式化/类型配置、CI定义、提交前（pre-commit）配置、覆盖率阈值。如果需要修改配置，需向用户提出建议。

High-Risk Action Gating

高风险操作管控

Some operations have blast radius beyond the current code change. Even if the user's request implies them, the agent stops and asks because these are irreversible or affect systems beyond the codebase:
  • Destructive data operations (DROP TABLE, deleting records, truncating logs)
  • Permission and access changes (auth rules, IAM policies, CORS)
  • Deployment actions (pushing to production, triggering deploys, scaling)
  • Bulk or irreversible operations (mass updates, migrations, force-pushes)
  • Financial or billing changes (anything committing to spend)
Describe the operation and blast radius, then wait for confirmation.
某些操作的影响范围超出当前代码变更。即使用户的请求隐含这些操作，Agent也需停止并询问，因为这些操作不可逆或会影响代码库之外的系统：
  • 破坏性数据操作（DROP TABLE、删除记录、截断日志）
  • 权限和访问变更（认证规则、IAM策略、CORS）
  • 部署操作（推送到生产环境、触发部署、扩容）
  • 批量或不可逆操作（批量更新、迁移、强制推送）
  • 财务或计费变更（任何涉及支出的操作）
描述操作内容及其影响范围，然后等待用户确认。

Lessons Learned

经验总结

The agent accumulates project-specific knowledge across sessions. Without a persistent record, each session starts from zero and risks repeating the same mistakes.
Maintain 
LESSONS_LEARNED.md
in the project root. Append an entry when encountering: a guardrail failure requiring multiple attempts, a non-obvious project convention, a surprising tool behavior, a deployment gap tests didn't catch, a thrashing episode, or a diagnostic tool that proved useful. Each entry: Date, Context, What happened, Resolution, Rule (concise directive for future sessions).
Commit to version control. If a lesson reveals a missing guardrail, propose adding one — don't just document the workaround.
Agent跨会话积累项目特定知识。如果没有持久化记录，每个会话都从零开始，可能重复相同的错误。
在项目根目录维护
LESSONS_LEARNED.md
。当遇到以下情况时追加条目：需要多次尝试才能解决的防护机制失败问题、非显而易见的项目约定、意外的工具行为、测试未覆盖的部署缺口、震荡场景、证明有效的诊断工具。每个条目需包含：日期、场景、发生情况、解决方法、规则（供未来会话遵循的简洁指令）。
提交到版本控制。如果经验总结揭示了缺失的防护机制，建议添加该机制——不要仅记录解决方法。

Agent Responsibilities (Not Hookable)

Agent职责（无钩子触发）

Behaviors the agent follows because the reasoning is sound, not because a hook enforces them.
Planning: Decide testing layers before writing code. Check problem shape against the proactive table in 
references/tool-building.md
. Assess security relevance.
Code writing: Format and type-check incrementally. If the same type error reappears after one fix, that signals a structural misunderstanding — switch to a notation rather than continuing to guess.
Handoff / PR: Report what was verified, which layers were skipped and why, security findings, and coverage delta. Do not present work as complete if any hook failed.
这些是Agent基于合理逻辑主动遵循的行为，而非由钩子强制执行。
规划：在编写代码前确定测试层级。对照
references/tool-building.md
中的主动预判表检查问题类型。评估安全相关性。
代码编写：逐步进行格式化和类型检查。如果同一类型错误在修复后再次出现，表明存在结构性误解——应切换为符号表示而非继续猜测。
交接/PR：报告已验证的内容、跳过的检查层及原因、安全发现、覆盖率变化。如果任何钩子检查失败，不得将工作成果呈现为已完成。