文档教程提示工程人工智能【免费下载链接】context-engineering-introContext engineering is the new vibe coding - its the way to actually make AI coding assistants work. Claude Code is the best for this so thats what this repo is centered around, but you can apply this strategy with any AI coding assistant!项目地址https://gitcode.com/gh_mirrors/co/context-engineering-intro点击查看免费下载导读本文围绕本仓库 claude-code-full-guide/.claude/agents/validation-gates.md 展开完整讲解如何定义并落地一个「验证与测试专家」子代理它会在功能实现后主动运行测试、执行 lint/类型检查/构建校验并迭代修复直到全部质量门禁通过。读完本文你将掌握 Claude Code 子代理 frontmatter 的写法与工具约束、五类核心职责的落实方式、跨语言验证命令矩阵以及如何把验证子代理与 PRP 验证循环、仓库级开发规范CLAUDE.md组合成一套端到端的自动化质量体系。一、validation-gates 子代理是什么在本仓库的 Claude Code 使用指南 claude-code-full-guide/README.md 中「Validation Gates」被定位为推荐实践的两大关键子代理之一另一个是文档经理。其定位是验证与测试专家validation and testing specialist作为质量把关人quality gatekeeper在任何代码变更被标记为完成之前确保其满足项目标准。从仓库的目录结构看该子代理以 Markdown 文件形式存放在claude-code-full-guide/.claude/agents/目录下与documentation-manager.md同级。Claude Code 约定.claude/agents/目录中的每个 Markdown 文件即一个可被调用的子代理文件本身即定义本身——这正是「以文件即配置」的方式为 AI 编码助手注入专业化能力。1.1 frontmatter子代理的身份与能力边界该文档开头的 YAML frontmatter 定义了子代理的关键元数据--- name: validation-gates description: Testing and validation specialist. Proactively runs tests, validates code changes, ensures quality gates are met, and iterates on fixes until all tests pass. Call this agent after you implement features and need to validate that they were implemented correctly. Be very specific with the features that were implemented and a general idea of what needs to be tested. tools: Bash, Read, Edit, MultiEdit, Grep, Glob, TodoWrite ---name子代理的唯一标识也是主代理primary agent调用它的句柄。description这是整个子代理定义中最关键的一段文本。它同时承担两个职能告知主代理何时调用——Call this agent after you implement features and need to validate that they were implemented correctly实现功能后调用以验证正确性告知主代理如何调用——Be very specific with the features that were implemented and a general idea of what needs to be tested要非常具体地说明实现了哪些功能以及大致需要测试什么。这与本仓库 claude-code-full-guide/README.md 中「Subagent Best Practices」强调的信息流设计一致子代理描述决定了主代理何时、以何种提示词调用它。此外描述中以Proactively主动开头属于本仓库 README 提到的「Power Keywords」可促使 Claude 主动发起调用。tools能力边界白名单仅授予Bash, Read, Edit, MultiEdit, Grep, Glob, TodoWrite。注意它不含 WebFetch 等联网能力且拥有Edit/MultiEdit用于修复测试失败时改代码与Bash用于运行测试命令——这是「测试 修复」闭环所必需的最小工具集。此设计呼应了 README 中「只给子代理所需工具」的实践审阅型子代理只给Read, Grep而验证型子代理则需要读写与执行权。二、五大核心职责验证子代理的完整工作内容2.1 自动化测试执行Automated Testing Execution任何代码变更之后子代理应运行全部相关校验运行所有相关测试Run all relevant tests after code changes执行 lint 与格式化检查Execute linting and formatting checks在适用时运行类型检查Run type checking where applicable执行构建验证Perform build validation检查安全漏洞Check for security vulnerabilities这里的「校验链」不是可选套餐而是逐层递进的把关序列lint → 类型 → 测试 → 构建 → 安全。仓库的 claude-code-full-guide/CLAUDE.md 给出了这套链在 Python 项目中的落地命令详见下文第四节两者可直接对接。2.2 测试覆盖率管理Test Coverage Management覆盖率不是「凑数字」而是围绕未覆盖代码路径的反向驱动确保新代码有适当的测试覆盖Ensure new code has appropriate test coverage为未覆盖的代码路径补写缺失测试Write missing tests for uncovered code paths验证测试是否真的测了有意义的场景Validate that tests actually test meaningful scenarios维持或提升整体覆盖率指标Maintain or improve overall test coverage metrics其中「测试是否真的测了有意义场景」这一点与仓库中另一份验证代理文档 use-cases/ai-coding-workflows-foundation/agents/validator.md 的核心主张互为印证Test behavior, not implementation details测行为而非实现细节、Focus on does it work? not is every line covered?。覆盖率是手段行为正确性才是目的。2.3 迭代修复流程Iterative Fix Process当测试失败时按照固定循环处理仔细分析失败原因Analyze the failure carefully定位根因Identify the root cause实施修复Implement a fix重跑测试验证修复Re-run tests to verify the fix持续迭代直到全部测试通过Continue iterating until all tests pass记录任何不显而易见的修复Document any non-obvious fixes这个「分析 → 定位 → 修复 → 重验 → 迭代 → 记录」六步循环与本仓库 PRP 模板 PRPs/templates/prp_base.md 中 Validation Loop 的指导思想同源If failing: Read error, understand root cause, fix code, re-run (never mock to pass)——读错误、理解根因、修复代码、重跑绝不通过 mock 让测试假通过。2.4 验证门禁检查清单Validation Gates Checklist在任何任务被标记完成之前必须逐项确认全部单元测试通过All unit tests pass集成测试通过如适用Integration tests pass, if applicableLint 无错误Linting produces no errors类型检查通过针对类型化语言Type checking passes, for typed languages代码格式正确Code formatting is correct构建成功且无警告Build succeeds without warnings未检测到安全漏洞No security vulnerabilities detected性能基准达标如适用Performance benchmarks met, if applicable这份清单是子代理「不达标即不完成」的行为契约。它与 claude-code-full-guide/README.md 中对 Validation Gates 子代理的描述完全一致「Runs all tests after changes, iterates on fixes until tests pass, enforces code quality standards,never marks tasks complete with failing tests绝不在测试失败时标记任务完成」。2.5 测试编写标准Test Writing Standards创建新测试时应遵循编写能说明被测对象的描述性测试名Write descriptive test names that explain what is being tested至少覆盖四类用例快乐路径Happy path test cases边界场景Edge case scenarios错误/失败用例Error/failure cases边界条件测试Boundary condition tests使用恰当的测试模式AAAArrange, Act, Assert——准备、执行、断言恰当 mock 外部依赖Mock external dependencies appropriately保持测试快速且确定性Keep tests fast and deterministic这一标准在仓库代码中能直接找到范例。例如use-cases/agent-factory-with-subagents/agents/rag_agent/tests/test_agent.py、test_cli.py等测试文件即按「正常路径 错误路径」组织claude-code-full-guide/CLAUDE.md 中给出的test_user_can_update_email_when_valid与test_user_update_email_fails_with_invalid_format也分别对应 happy path 与 error case 的命名规范。三、验证流程工作流从评估到终验的五步闭环1. Initial Assessment初始评估 ↓ 2. Execute Validation执行验证 ↓ 3. Handle Failures处理失败 ↓ 4. Iterate Until Success迭代至成功 ↓ 5. Final Verification最终验证第 1 步初始评估Initial Assessment判断需要何种类型的验证Identify what type of validation is needed决定应运行哪些测试Determine which tests should be run检查已有测试套件Check for existing test suites第 2 步执行验证Execute Validation文档给出了通用验证序列按项目适配# Example validation sequence (adapt based on project) npm run lint npm run typecheck npm run test npm run build第 3 步处理失败Handle Failures仔细阅读错误信息Read error messages carefully用 grep/search 定位相关代码Use grep/search to find related code一次只修一个问题Fix issues one at a time每次修复后重跑失败的测试Re-run failed tests after each fix第 4 步迭代直到成功Iterate Until Success继续「修复 测试」循环Continue fixing and testing第一次失败不要放弃Dont give up after first attempt必要时尝试不同方案Try different approaches if needed真正被阻塞时请求帮助Ask for help if truly blocked第 5 步最终验证Final Verification最后完整跑一遍整个测试套件Run complete test suite one final time确认没有引入回归Verify no regressions were introduced确保所有验证门禁通过Ensure all validation gates pass这套五步闭环的价值在于把「测试失败」从意外事故变成可预期、可管理的标准流程先快速评估再执行失败后小步修复最终以全量回归收尾杜绝「改一处坏一片」后仍被标记完成的情况。四、按语言的常用验证命令矩阵原文档给出了 JavaScript/TypeScript、Python、Go 三大主流语言的命令对照这是子代理实际执行Bash工具时的操作手册。JavaScript / TypeScriptnpm run lint # or: npx eslint . npm run typecheck # or: npx tsc --noEmit npm run test # or: npx jest npm run test:coverage # Check coverage npm run build # Verify build对应关系eslint 做 lint、tsc --noEmit 做类型检查、jest 跑测试、test:coverage查覆盖率、build 做构建验证。这类npm run *命令与本仓库权限配置 claude-code-full-guide/.claude/settings.local.json 中的Bash(pytest:*)、Bash(python -m pytest:*)等白名单思路一致——用精确的命令前缀代替放开的Bash(*)兼顾效率与安全。Pythonruff check . # Linting mypy . # Type checking pytest # Run tests pytest --cov # With coverage python -m build # Build check这条 Python 命令链与本仓库的工程规范完全对应claude-code-full-guide/CLAUDE.md 规定项目使用 UV 管理环境、Ruff 做 lint/格式化、Mypy 做类型检查、pytest 做测试并将「行宽 100 字符Ruff 规则」「使用 venv_linux 虚拟环境执行 Python 命令包括单元测试」写为强制规范。实际落地命令为uv run pytest # 运行全部测试 uv run pytest tests/test_module.py -v # 指定模块 verbose uv run pytest --covsrc --cov-reporthtml # 带覆盖率报告 uv run ruff check . # lint 检查 uv run ruff check --fix . # 自动修复 uv run mypy src/ # 类型检查 uv run pre-commit run --all-files # 钩子检查子代理在执行 Python 验证时应优先采用上述uv run形式而非裸命令以贴合仓库既有开发环境。同时 claude-code-full-guide/CLAUDE.md 的测试策略TDD先写测试 → 看它失败 → 写最小实现 → 重构 → 重复与本文档的「先验证后实现」互为表里一个负责驱动实现一个负责守卫质量。Gogo fmt ./... # Format go vet ./... # Linting go test ./... # Run tests go build . # Build validationGo 的工具链约定俗成地使用内置命令go fmt负责格式化、go vet承担静态检查、go test跑测试、go build验证构建无需额外安装第三方工具。五、需要跟踪的质量指标为了让「质量」可度量、可审计原文档定义了五类核心指标指标目标值测试成功率Test success rate必须 100%must be 100%代码覆盖率Code coverage目标 80%aim for 80%Lint 警告/错误数Linting warnings/errors应为 0should be 0构建时间Build time不应显著增加shouldnt increase significantly测试执行时间Test execution time保持在合理上限内keep under reasonable limits其中「覆盖率 80%」与 claude-code-full-guide/CLAUDE.md 中「Aim for 80% code coverage, but focus on critical paths」的表述一致而「构建/测试时间不能失控」则呼应了 2.5 节「Keep tests fast and deterministic」的原则——质量门禁不能以拖慢研发速度为代价否则团队会本能地绕过它。六、不可妥协的五大原则绝不跳过验证Never Skip Validation即使对「简单」的改动也要验证——简单改动往往是回归的高发区。修复而非禁用Fix, Dont Disable修复失败的测试而不是把测试 disable 掉这等价于「不达标就不放行」。测行为而非实现Test Behavior, Not Implementation关注代码「做什么」而非「怎么做的」测试与实现细节解耦后重构才不会连带大规模改测试。快速反馈Fast Feedback先跑快速测试再跑全面测试让失败尽早暴露降低定位成本。记录失败Document Failures测试暴露 bug 时把修复过程记录下来这与 2.3 节「Document any non-obvious fixes」一脉相承。七、把验证子代理嵌入更大的上下文工程体系validation-gates 不是孤立的文件它与本仓库的上下文工程体系Context Engineering其他组件深度咬合7.1 与 PRP 验证循环配合本仓库的 PRPProduct Requirements Prompt模板 PRPs/templates/prp_base.md 内置了三级 Validation LoopLevel 1 语法与风格ruff check src/new_feature.py --fix、mypy src/new_feature.pyLevel 2 单元测试为每个新文件创建测试happy path、validation error、external API timeoutuv run pytest test_new_feature.py -v迭代至通过Level 3 集成测试启动服务、curl 端点验证检查日志定位问题PRP 负责在实现前把验证门禁写进需求蓝图validation-gates 子代理负责在实现后把门禁变成实际执行的动作——两者构成「先立规矩再守规矩」的完整闭环。README 中「Validation Gates: Ensure comprehensive testing and iteration until all tests pass」正是对这一协同的概括。7.2 与同类验证代理的定位差异仓库中还有一份更轻量的验证代理 use-cases/ai-coding-workflows-foundation/agents/validator.md两者的侧重点不同可对比理解维度validation-gates本文validatorworkflows-foundation触发方式功能实现后主动调用Proactively实现后自动使用USE AUTOMATICALLY核心动作全量质量门禁lint/类型/构建/安全/回归创建简单聚焦的单元测试3-5 个心智模型全面把关quality gatekeeper快速验证does it work?测试哲学覆盖率管理 行为测试简单胜过复杂功能优先于覆盖数字实际团队可依据变更规模选择小改动交给轻量 validator 快速出测试重要功能交给 validation-gates 走完整门禁链。7.3 与文档经理的接力本仓库 claude-code-full-guide/.claude/agents/documentation-manager.md 是 validation-gates 的「下游搭档」代码变更后验证子代理保证「代码是对的」文档经理保证「文档是新的」校验文档链接有效性、代码示例可编译可运行。README 的建议是代码变更后依次调用两者形成「实现 → 验证 → 记录」的完整交付链。八、如何在自己的项目中启用该子代理参照本仓库结构即可启用放置文件在项目根目录创建.claude/agents/目录将本仓库的 validation-gates.md 复制过去或基于它改造。授予权限确保项目的.claude/settings.local.json放行测试相关命令。仓库示例 claude-code-full-guide/.claude/settings.local.json 采用了「白名单前缀」模式如Bash(pytest:*)、Bash(python -m pytest:*)、Bash(ruff:*)并可用deny数组显式禁止危险命令。按语言调整命令根据项目技术栈将第四节命令矩阵中的npm run */uv run */go *换成项目实际脚本。调用方式在功能实现完成后向主代理明确交代「实现了哪些功能、需要测试什么」对应 frontmatter 中 Be very specific... 的要求主代理便会把任务连同上下文委托给 validation-gates 子代理。由于子代理拥有独立上下文窗口主对话的冗长历史不会污染其判断。与其他代理组合将验证子代理接入 PRP 执行流程或与文档经理配对使用形成「实现 → 验证 → 记录」的交付流水线。提示仓库是只读的启用方式仅为「复制文件到自有项目的 .claude/agents/ 目录并按需修改」不建议直接改动本仓库内容。结语validation-gates 的价值不在一份测试命令清单而在于它把「质量」从一句口号变成了可执行、可迭代、不放水的行为契约明确的五类职责、八项门禁清单、五步闭环工作流、跨语言命令矩阵与五条不可妥协的原则共同构成一个自驱的 QA 子代理。当它与本仓库的 PRP 验证循环、CLAUDE.md 工程规范以及文档经理子代理协同运转时Claude Code 便真正具备了「既能写代码也能对自己写的代码负责」的闭环能力——这正是上下文工程Context Engineering从「让 AI 干活」走向「让 AI 把活干对」的关键一步。赞分享文档教程提示工程人工智能【免费下载链接】context-engineering-introContext engineering is the new vibe coding - its the way to actually make AI coding assistants work. Claude Code is the best for this so thats what this repo is centered around, but you can apply this strategy with any AI coding assistant!项目地址https://gitcode.com/gh_mirrors/co/context-engineering-intro点击查看免费下载相关推荐ECC Swift 钩子规则实战用 SwiftFormat、SwiftLint 与 swift build 构建 Claude Code 自动化代码质量门禁ECC Swift 钩子规则实战用 SwiftFormat、SwiftLint 与 swift build 构建 Claude Code 自动化代码质量门禁人工智能AI 技能AI 插件AI 评测Agent 评测MCP Clients开发工具NVIDIA ESM-2安全与伦理蛋白质AI模型的负责任使用指南NVIDIA ESM 2安全与伦理蛋白质AI模型的负责任使用指南 NVIDIA ESM 2esm2_t33_650M_UR50D作为先进的蛋白质结构预测ADLSS Swapper 完整教程5 步完成游戏 DLSS 版本切换附一键回退方法DLSS Swapper 完整教程5 步完成游戏 DLSS 版本切换附一键回退方法 DLSS Swapper 是一款运行在 Windows 上的 DLSS桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考