goul4rt/quick-guardrails-ia

Prompt 中的指令是概率性的；而 hook 和门禁是确定性的。本仓库汇集了**可直接复制**的实践、护栏和工件，旨在使用本地规则、OSS 工具和免费资源，安全、可重复且可审计地利用 AI Agent（Claude Code）开发软件。这里唯一假设的付费基础是你已有的 Claude Code 订阅；任何需要付费服务或按 token 计费的内容**都不会包含在模板中**（[文档 09](docs/09-custos.md)）。 这里的所有内容都源于在**三个生产级代码库**中的实际工作：一个移动应用（React Native）、一个 Web 面板（Next.js）和一个 Bot（Node），在这些项目中，AI Agent 开始在阻塞性的 CI 门禁、锁定的供应链、Git 护栏以及带有强制证据的任务流下运行。数据和经验教训都是真实的；内部参考资料已被泛化，以适用于任何项目（[文档 07](docs/07-licoes-aprendidas.md)）。而且这个仓库自己也在“吃狗粮”：这里的 CI 会运行模板护栏的金丝雀测试，并检查没有任何文档引用幽灵路径。 ## 60 秒快速开始 **使用 Agent 审计现有仓库**：将此 skill 作为 Claude Code 插件安装。它会在任何仓库中强制执行正确的流程： ``` /plugin marketplace add goul4rt/quick-guardrails-ia /plugin install guardrails@metodologias # 在任何 repo 中：“应用 guardrails” / “运行 checklist” ``` 如果不使用插件，可以通过 clone + symlink 达到同样的效果（`ln -s /.claude/skills/applying-guardrails ~/.claude/skills/`），或者仅使用[与 AI Agent 一起使用](#usando-com-um-agente-de-ia)章节中的 prompt。 **从零开始采用**：按照[如何在全新仓库中采用](#como-adotar-em-um-repositório-novo)的 6 个步骤操作。 **只想要某个工件**：[`templates/`](templates/) 中的所有内容都是可复制的，每个文件都指向解释每项决策原因的文档。 ## 实际上有何不同 真实测试（创建 skill 时记录的基准）：相同的模型，相同的要求（“在此仓库中应用护栏”），在一个新建的 Node 项目中进行。 | 没有指导原则 | 使用 `applying-guardrails` skill | |---|---| | 一次性实现了 15 个文件，不询问任何问题 | 首先进行审计：填写 CHECKLIST ✅/❌/n-a，并为每个项目提供证据（命令 + 结果） | | 为一个不了解的项目凭空捏造了一整个 `CLAUDE.md`（分支约定，STOP 规则） | 仅提出框架并列出只有项目负责人才能回答的问题 | | 直接提交并合并到 `main` 分支 | 在批准之前连一个文件都没碰 | | 自己决定有成本和权衡的项目 | 停在人工决策门禁前：push 变体、分支保护、install 授权 | 区别不在于模型，而在于护栏强制执行的流程：**审计 → 决策 → 实施**，每个阶段都有强制工件。 ## 原则 1. **要么是阻塞性门禁，要么没有门禁。** 不阻塞合并的检查只是摆设。在创建门禁的*同一个 PR* 中消除阻碍封锁的债务。 2. **护栏在 harness 中，而不是在 prompt 里。** Prompt 中的指令是概率性的；`PreToolUse` hook 是确定性的。不能发生的事情，就用代码拦截。 3. **基于哈希的可重复性。** 依赖项锁定在确切版本；AI skill 通过 lockfile 中的哈希固定。升级是明确的 PR，绝不是副作用。 4. **要证据，不要断言。** 只有在满足验收标准并具有可视化证明（截图 + 日志）时，任务才可关闭。失败了？如实报告失败，不要粉饰。 5. **不要假设，不要捏造。** 没有验收标准就提问。没有打开的 PR 就请求。MCP 断开连接，发出警告并停止。Agent 会公开权衡，而不是在沉默中做出决定。 6. **例外要记录，不要隐藏。** 故意偏离约定？该决策及其原因将记录在 PR 中。 7. **护栏也是代码。** 没有测试，它就会在沉默中失效并继续保持绿灯。每个门禁都有一个在 CI 上运行的金丝雀测试（应该不通过的不良情况，应该通过的良好情况）。 ## 仓库导航 ### 指南 (`docs/`) | 文档 | 内容 | |---|---| | [01. 项目背景](docs/01-contexto-do-projeto.md) | `CLAUDE.md` 作为 Agent 的操作契约：客观规则、坑点、反模式 | | [02. CI 门禁](docs/02-gate-de-ci.md) | 100% 阻塞性的 PR 门禁：检查顺序、并发，以及带有 `paths-ignore` 的必需检查陷阱 | | [03. 供应链](docs/03-supply-chain.md) | 精确的版本锁定、Dependabot、月度审计、规范化的 `npm audit fix` 和 lockfile 偏移 | | [04. Agent 护栏](docs/04-guardrails-do-agente.md) | `PreToolUse`/`PostToolUse` hooks：拦截破坏性 git、lint 自动修复、已知限制 | | [05. 版本化的 Skills](docs/05-skills-versionadas.md) | `skills-lock.json`：通过哈希固定的 AI skill，在 `npm install` 时还原 | | [06. 任务流](docs/06-fluxo-de-task.md) | `/task` 和 `/task close`：从 Jira issue 到带有证据和双重审查的合并 | | [07. 经验教训](docs/07-licoes-aprendidas.md) | 案例研究：这 5 个 PR 教会了我们什么（包括未采用的内容） | | [08. 门禁中的安全](docs/08-seguranca-no-gate.md) | 确定性扫描器拦截，AI 推荐：免费的 gitleaks + 本地审查 + 故障分类 | | [09. 成本与准入规则](docs/09-custos.md) | 默认免费：什么是免费的，什么是“有陷阱的免费”，什么被排除在外以及为什么 | | [10. CI 之外的护栏](docs/10-guardrails-alem-do-ci.md) | 强制执行的范围：hooks、不变量自动化、STOP 规则、分层路由、记忆 | | [11. 测试护栏](docs/11-teste-o-guardrail.md) | 每个门禁的金丝雀测试：CI 中的 must-block/must-pass，因为未经测试的护栏会在沉默中失效 | | [12. 运行时边界](docs/12-fronteira-runtime.md) | 开发护栏与 LLM 运行时护栏：哪些转移了，以及为构建产品的人提供的 OSS 选项（附带注意事项） | | [13. 文献证据](docs/13-evidencias-da-literatura.md) | 支持每份文档的公开数据（Veracode, GitClear, USENIX, DORA, RCTs），以及文献推荐但因成本原因被排除在外的内容 | | [14. 测试强度](docs/14-forca-de-teste.md) | 覆盖率衡量的是执行，而不是验证：mutation testing、property-based testing 以及 PR 中新代码的覆盖率 | ### 即用型工件 (`templates/`) ``` templates/ ├── .github/ │ ├── workflows/ci.yml # gate de PR bloqueante (adapte os checks à sua stack) │ ├── workflows/ci-docs-noop.yml # companheiro do paths-ignore (required check nunca trava) │ ├── workflows/audit.yml # npm audit mensal → abre/atualiza issue │ ├── workflows/security.yml # gitleaks CLI (free, bloqueante): secrets no histórico │ ├── workflows/preview-smoke.yml # valida que o preview de deploy responde (via check_run) │ ├── workflows/close-sub-issues.yml # cascata: pai fechada → fecha sub-issues (cross-repo) │ └── dependabot.yml # semanal, majors excluídos, minor+patch agrupados ├── .claude/ │ ├── settings.json # hooks + plugins versionados (guardrails de time) │ ├── hooks/ │ │ ├── block-dangerous-git.sh # PreToolUse: bloqueia git destrutivo │ │ └── eslint-fix-edited.sh # PostToolUse: auto-fix só no arquivo editado │ └── skills/routing-work/ # skill de roteamento por tiers (copiável; ver ADAPTING.md) ├── .husky/ │ └── pre-commit # disciplina de branch no git, vale p/ humano e agente ├── .mcp.json # tracker plugado no agente: MCP do Jira em Docker, creds via .env ├── scripts/ │ ├── skills-install.mjs # restaura skills do lock (postinstall seguro) │ ├── jira-attach.sh # anexa evidência a issue do Jira via REST │ ├── diff-coverage.mjs # cobertura nas linhas novas do PR (doc 14) │ └── test-guardrails.sh # canário do hook: must-block/must-pass (doc 11) └── .npmrc # save-exact=true ``` ## 护栏检查清单 **[`CHECKLIST.md`](CHECKLIST.md)** 是一份建议的护栏可检查清单，包含客观验证，并指向每个项目的文档/模板。它适用于两个方向：审计现有项目（缺少什么？）和从零开始实现（按什么顺序？）。将其复制到目标项目或粘贴到跟踪 issue 中。 ### 与 AI Agent 一起使用 此流程被打包为 [`.claude/skills/applying-guardrails/`](.claude/skills/applying-guardrails/SKILL.md) 中的 skill：审计（带有证据的 CHECKLIST）→ 人工决策（⚠️/成本项目、push 变体、`CLAUDE.md` 内容）→ 仅通过 PR 实施已批准的内容。安装步骤见[快速开始](#comece-em-60-segundos)。 如果不使用 skill，相同的契约也可以作为 prompt 使用。按以下格式将 Agent 指向这里： 通过这里的 Agent 规则：**验证，不要假设**（每个项目都有客观验证；运行它）；**调整，不要盲目复制**（占位符 `⟨...⟩` 和 `ADAPTING.md` 说明了每个项目的变化）；**成本是人工决策**（未经明确批准不得使用付费服务，[文档 09](docs/09-custos.md)）；**意识到差距要记录下来，不要隐藏**。 ## 如何在全新仓库中采用 1. **背景**：编写一个精简的 `CLAUDE.md`，包含客观的规则（[文档 01](docs/01-contexto-do-projeto.md)）。 2. **护栏**：复制 `templates/.claude/` 并在仓库中进行版本控制（[文档 04](docs/04-guardrails-do-agente.md)），同时包含证明它们有效的金丝雀测试（[文档 11](docs/11-teste-o-guardrail.md)）。 3. **门禁**：根据你的技术栈调整 `templates/.github/workflows/ci.yml`，并在**开启阻塞之前消除债务**（[文档 02](docs/02-gate-de-ci.md)）。 4. **供应链**：带有 `save-exact` 的 `.npmrc`、精确锁定、`dependabot.yml` 和 `audit.yml`（[文档 03](docs/03-supply-chain.md)）。 5. **分支保护**：要求进行 `ci` 检查并禁止直接 push 到主分支。没有这个，门禁什么也挡不住（手动步骤，需要管理员权限）。 6. **流程**：创建一个适配你跟踪工具的 `/task` 命令（[文档 06](docs/06-fluxo-de-task.md)）。 ## 许可证 [MIT](LICENSE)：复制、改编和使用；欢迎注明出处。

标签：AI辅助开发, MITM代理, 开发流程管理, 暗色界面, 请求拦截