企业官网建设流程全解析

• 文档
• 教程
• 提示工程
• 人工智能

导读

本文围绕本仓库 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）

当测试失败时，按照固定循环处理：

1. 仔细分析失败原因（Analyze the failure carefully）
2. 定位根因（Identify the root cause）
3. 实施修复（Implement a fix）
4. 重跑测试验证修复（Re-run tests to verify the fix）
5. 持续迭代直到全部测试通过（Continue iterating until all tests pass）
6. 记录任何不显而易见的修复（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 applicable）
• Lint 无错误（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）
• 使用恰当的测试模式：AAA（Arrange, 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）
• 第一次失败不要放弃（Don't 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 / TypeScript

npm 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(*)，兼顾效率与安全。

Python

ruff 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 --cov=src --cov-report=html # 带覆盖率报告 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：先写测试 → 看它失败 → 写最小实现 → 重构 → 重复）与本文档的「先验证后实现」互为表里：一个负责驱动实现，一个负责守卫质量。

Go

go fmt ./... # Format go vet ./... # Linting go test ./... # Run tests go build . # Build validation

Go 的工具链约定俗成地使用内置命令：go fmt负责格式化、go vet承担静态检查、go test跑测试、go build验证构建，无需额外安装第三方工具。

五、需要跟踪的质量指标

为了让「质量」可度量、可审计，原文档定义了五类核心指标：

其中「覆盖率 >80%」与 claude-code-full-guide/CLAUDE.md 中「Aim for 80%+ code coverage, but focus on critical paths」的表述一致；而「构建/测试时间不能失控」则呼应了 2.5 节「Keep tests fast and deterministic」的原则——质量门禁不能以拖慢研发速度为代价，否则团队会本能地绕过它。

六、不可妥协的五大原则

1. 绝不跳过验证（Never Skip Validation）：即使对「简单」的改动也要验证——简单改动往往是回归的高发区。
2. 修复而非禁用（Fix, Don't Disable）：修复失败的测试，而不是把测试 disable 掉；这等价于「不达标就不放行」。
3. 测行为而非实现（Test Behavior, Not Implementation）：关注代码「做什么」，而非「怎么做的」；测试与实现细节解耦后，重构才不会连带大规模改测试。
4. 快速反馈（Fast Feedback）：先跑快速测试，再跑全面测试；让失败尽早暴露，降低定位成本。
5. 记录失败（Document Failures）：测试暴露 bug 时，把修复过程记录下来；这与 2.3 节「Document any non-obvious fixes」一脉相承。

七、把验证子代理嵌入更大的上下文工程体系

validation-gates 不是孤立的文件，它与本仓库的上下文工程体系（Context Engineering）其他组件深度咬合：

7.1 与 PRP 验证循环配合

本仓库的 PRP（Product Requirements Prompt）模板 PRPs/templates/prp_base.md 内置了三级 Validation Loop：

• Level 1 语法与风格：ruff check src/new_feature.py --fix、mypy src/new_feature.py
• Level 2 单元测试：为每个新文件创建测试（happy path、validation error、external API timeout），uv 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，两者的侧重点不同，可对比理解：

实际团队可依据变更规模选择：小改动交给轻量 validator 快速出测试，重要功能交给 validation-gates 走完整门禁链。

7.3 与文档经理的接力

本仓库 claude-code-full-guide/.claude/agents/documentation-manager.md 是 validation-gates 的「下游搭档」：代码变更后验证子代理保证「代码是对的」，文档经理保证「文档是新的」（校验文档链接有效性、代码示例可编译可运行）。README 的建议是代码变更后依次调用两者，形成「实现 → 验证 → 记录」的完整交付链。

八、如何在自己的项目中启用该子代理

参照本仓库结构即可启用：

1. 放置文件：在项目根目录创建.claude/agents/目录，将本仓库的 validation-gates.md 复制过去（或基于它改造）。
2. 授予权限：确保项目的.claude/settings.local.json放行测试相关命令。仓库示例 claude-code-full-guide/.claude/settings.local.json 采用了「白名单前缀」模式，如Bash(pytest:*)、Bash(python -m pytest:*)、Bash(ruff:*)，并可用deny数组显式禁止危险命令。
3. 按语言调整命令：根据项目技术栈，将第四节命令矩阵中的npm run */uv run */go *换成项目实际脚本。
4. 调用方式：在功能实现完成后，向主代理明确交代「实现了哪些功能、需要测试什么」（对应 frontmatter 中 "Be very specific..." 的要求），主代理便会把任务连同上下文委托给 validation-gates 子代理。由于子代理拥有独立上下文窗口，主对话的冗长历史不会污染其判断。
5. 与其他代理组合：将验证子代理接入 PRP 执行流程或与文档经理配对使用，形成「实现 → 验证 → 记录」的交付流水线。

提示：仓库是只读的，启用方式仅为「复制文件到自有项目的 .claude/agents/ 目录并按需修改」，不建议直接改动本仓库内容。

结语

validation-gates 的价值不在一份测试命令清单，而在于它把「质量」从一句口号变成了可执行、可迭代、不放水的行为契约：明确的五类职责、八项门禁清单、五步闭环工作流、跨语言命令矩阵与五条不可妥协的原则，共同构成一个自驱的 QA 子代理。当它与本仓库的 PRP 验证循环、CLAUDE.md 工程规范以及文档经理子代理协同运转时，Claude Code 便真正具备了「既能写代码，也能对自己写的代码负责」的闭环能力——这正是上下文工程（Context Engineering）从「让 AI 干活」走向「让 AI 把活干对」的关键一步。

• 文档
• 教程
• 提示工程
• 人工智能