guardrails

用途

Guardrails 是一套接入智能体生命周期的代码质量验证门禁。它假设编码智能体本身已经了解 lint、测试、类型检查和漏洞扫描等概念，因此不重复教学，而是明确规定这些检查在智能体工作流程中于何时运行、遇到卡点如何处理、哪些内容不能改动，以及如何跨会话积累经验。这些被规范的行为，通常是智能体在无人告知时不会主动执行的部分；至于选用哪种 linter、如何组织单元测试，智能体可由训练知识及项目现有配置自行判断。

主要能力

范围与分层检查：提供一套通用基础检查，包括 lint、格式化、类型、SAST、依赖审计、密钥扫描、死代码/重复代码检测、覆盖率与单元测试。并可按项目类型叠加层次：后端/API、前端、全栈、库/SDK、数据管道、基础设施/IaC 各有相应的推荐测试层。项目越成熟，检查层越完整；原型只需通用基础，面向用户的生产系统则需要完整套件。

生命周期钩子：让门禁真正生效，检查未通过时直接阻断智能体推进，并给出具体、无歧义的反馈。

• SessionStart：智能体启动时记录 git 状态（HEAD SHA、工作区状态）作为基线；发现现有护栏（配置文件、CI 流水线、测试目录）；判断项目类型与适用检查；阅读现有测试文件以学习命名、结构、断言风格、mock、fixture 等约定并保持一致；读取 LESSONS_LEARNED.md 应用项目专属经验；检查 script/agent-tools/ 了解此前会话留下的诊断工具。遵循既有约定，未经用户明确同意不切换工具或框架。

• Stop：每次交还控制权时触发，防止未经验证就宣告成功。返回带证据的决策：仅在快速检查通过且代码/测试改动被覆盖时 ALLOW；当快速检查缺失或失败、生产代码有变更但缺少对应测试、或跳过了熔断机制时 BLOCK。需要引用证据，包括快速检查命令与状态（格式化、lint、类型、单元测试）、生产文件改动、测试改动或非生产性原因，以及所需的下一步动作。仅给出一个“BLOCK”标签不算充分证据。

• Commit（PreToolUse + git 钩子）：任何提交都会触发，无论来自智能体还是人类，执行同等检查。运行完整套件并在失败时阻断；对暂存文件进行密钥扫描；校验提交信息是否符合项目约定；进行集成/部署检查，确认改动不仅正确而且可达（新模块是否被导入、路由是否注册、迁移是否包含、入口点是否更新），代码通过测试但未接入应用属于部署缺口；当提交用于修复缺陷时，须在提交前回答三个问题：检测缺口（为什么既有测试或检查没发现）、预防措施（新增了何种具体产物以防复发，如新测试用例、类型约束、断言或 lint 规则，而非仅文字记录）、模式扫描（在代码库中搜索同类错误模式，若存在同类问题须在同一提交中修复或明确记录）。任一问题未回答则阻断提交。

测试运行器发现与双命令机制：执行系统需要在目标项目中找到两条命令——快速检查（数秒内运行，覆盖格式化检查、lint、类型检查、单元测试，每次智能体停止时触发）与完整套件（每次提交前运行，覆盖快速检查的全部内容外加集成测试、属性测试、密钥扫描、死代码检测、重复代码检测、覆盖率下限）。强调“发现而非强加”：各生态有各自约定（npm scripts、Makefile 目标、Go 命令、pytest、bun、Cargo 等），应在 SessionStart 期间检查 package.json scripts、Makefile 目标、CI 工作流步骤与 README 说明，适配项目现有运行器而不另建一套，并使运行器在失败时以非零状态退出。若项目完全没有测试运行器，则使用项目原生工具创建。

颠簸熔断机制：若快速检查失败且智能体已尝试同一修复两次，则不能进行第三次直接修复。第一次失败后可直接修复；第二次失败后须停下，构建诊断工具或切换到某种记号表示（notation）；第三次失败（且已使用诊断）后完全停止，向用户报告失败内容、已尝试内容、诊断所揭示的信息以及为何不收敛。当用户提供新方向时熔断重置，有用的诊断结果应持久化到 script/agent-tools/。

完成度检查：快速检查通过后检查任务列表；若存在未完成的计划工作项且未被阻断，应继续下一片，而非交还。仅在全部完成、熔断触发或上下文不足时才交还用户（此时应提交已完成切片并报告剩余项）。建议按片工作：一片为 1-3 个生产文件加测试，频繁验证，但验证一片不等于完成整个任务。

工具构建与记号表示：当直接修复失败时，智能体需要新信息或不同的问题表示。references/tool-building.md 包含诊断工具与记号的完整目录及三个示例。熔断机制强制在两次失败后阅读该参考；但最佳用法是主动使用：在规划阶段识别问题形态并预先搭建脚手架。常见模式包括：修改函数接口前先建立调用点清单；复杂条件逻辑（超过 3 个布尔值或 4 个分支）建立决策矩阵；状态机行为建立状态转移表；数据转换管道追踪样本值经过每个阶段；不熟悉的代码区域先建立代码库索引。诊断工具常会演变为永久基础设施——复现脚本成为测试用例、schema 检查器成为健康检查、依赖映射供集成检查使用。

配置保护：智能体不得编辑自身的护栏配置。在“让测试通过”的压力下，智能体有动机削弱测试而非修复代码，因此须阻断智能体修改测试脚本、lint/格式化/类型配置、CI 定义、pre-commit 配置与覆盖率阈值。若配置需要变更，应向用户提出建议。

高风险操作门禁：某些操作的影响范围超出当前代码改动，即使请求隐含了它们，智能体也应停下询问，因为其不可逆或影响代码库之外的系统。包括破坏性数据操作（DROP TABLE、删除记录、截断日志）、权限与访问变更（认证规则、IAM 策略、CORS）、部署动作（推送生产、触发部署、扩缩容）、批量或不可逆操作（大规模更新、迁移、强制推送）、财务或计费变更（任何承诺支出的行为）。须描述操作与其影响范围，然后等待确认。

经验积累（Lessons Learned）：在项目根目录维护 LESSONS_LEARNED.md，遇到以下情况时追加条目：需要多次尝试的护栏失败、不明显的项目约定、令人意外的工具行为、测试未捕获的部署缺口、揭示检测缺口的缺陷修复复盘、颠簸事件，或证明有用的诊断工具。条目模板包含标题、上下文、发生的事、解决方式、规则，并附有示例。应纳入版本控制；若某条经验揭示缺少某项护栏，应提议新增而非仅记录变通方式。

智能体职责（不可钩子化的部分）：规划时定义完成标准（改动哪些文件、新增哪些测试、接好哪些路由），在写代码前决定测试层，对照 tool-building.md 中的主动表检查问题形态，评估安全相关性。写代码时增量地进行格式化与类型检查；若同一类型错误在一次修复后再次出现，说明结构性理解有误，应切换记号表示而不是继续猜测。交接/PR 时报告已验证内容、跳过了哪些层及原因、安全发现与覆盖率变化。若任何钩子失败，不得将工作呈现为已完成。

使用方式

该技能以技能（skill）形式接入编码智能体，通过生命周期钩子在 SessionStart、Stop、Commit 等节点施加阻断式检查。使用者需要让智能体在目标项目中发现现有的测试运行器与约定，并据此配置快速检查与完整套件两条命令。配套资源包括 references/tool-building.md（诊断工具与记号目录及示例）和 references/language-defaults.md（按生态选择工具的查找表），应在被指示时阅读而非主动阅读。项目根目录可出现 LESSONS_LEARNED.md 与 script/agent-tools/ 两个持久化位置。

适用场景

凡在编写、修改、审查或调试代码时均可使用，尤其适合需要让智能体在推进前必须通过验证的开发流程。不同项目类型（后端/API、前端、全栈、库/SDK、数据管道、基础设施/IaC）可叠加相应的额外测试层；原型只需通用基础检查，生产系统则适用完整套件。

限制

并非每项检查都适用于每个项目，需按项目类型与成熟度选择分层。该技能不教授 lint、测试、类型检查、安全扫描本身的概念与具体工具用法，工具选择需参考项目现有配置与配套查找表。关于具体的安装命令、收费与价格信息，资料中暂未提供。