AI Coding Workflows 中的 Software Feature Validator：为 AI 编码助手构建自动化测试验证代理的完整指南

AI Coding Workflows 中的 Software Feature Validator为 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导读本文基于 use-cases/ai-coding-workflows-foundation/agents/validator.md 中的子代理定义系统讲解如何让 AI 编码助手在功能实现后自动完成单元测试创建、功能验证与就绪确认。你将掌握 Validator 的角色定位、测试结构规范、执行流程、验证边界与标准输出格式并看到它在本仓库的 AI Coding Workflows 框架 三阶段流程与真实测试代码中的落地方式。Validator 在三阶段工作流中的定位本仓库的 AI Coding Workflows 框架 围绕Context Engineering理念将 AI 辅助编码组织为三个阶段Phase 1 Planning通过/primer、/create-plan等命令完成需求分析与计划制定Phase 2 Implementation通过/execute-plan按计划逐步实现功能Phase 3 Validation对实现结果进行代码评审与验证。Validator 子代理正是 Phase 3 Validation 的核心执行者。框架中定义的 AI 侧验证流程为由 Validator 子代理执行自动化代码评审、运行单元测试、运行集成测试而人类则负责战略性监督与手动测试形成 Trust but Verify信任但验证的双层保障。Validator 与同目录下的 codebase-analyst.md 构成两个互补的子代理Codebase Analyst 在规划阶段负责看懂代码库Validator 在验证阶段负责证明代码可用。前者回答代码该怎么写后者回答代码写对了吗。子代理元数据一次调用便知职责边界validator.md 的 YAML frontmatter 定义了该子代理的关键元数据--- name: validator description: Testing specialist for software features. USE AUTOMATICALLY after implementation to create simple unit tests, validate functionality, and ensure readiness. IMPORTANT - You must pass exactly what was built as part of the prompt so the validator knows what features to test. tools: Read, Write, Grep, Glob, Bash, TodoWrite color: green ---其中值得注意的设计意图description 即触发指令明确要求实现后自动使用且强调调用方必须把实际构建的内容作为 prompt 的一部分传入否则 Validator 不知道要测什么功能——这是本子代理可用性的第一前提tools 白名单只授予Read, Write, Grep, Glob, Bash, TodoWrite六项工具即读代码、写测试、搜索定位、执行测试、跟踪任务的最小权限集不授予任何危险或无关能力color: green在支持子代理颜色标识的客户端中用于视觉区分绿色通常代表通过/就绪语义与验证角色呼应。核心职责一先理解构建了什么再动手Validator 的首要职责不是写测试而是理解被测对象。文档要求按以下顺序建立认知阅读相关代码文件Read、Grep、Glob定位并通读实现识别创建的主要函数/组件理解预期的输入与输出记录外部依赖与集成点数据库、API、第三方库等。这一步骤与 codebase-analyst.md 的分析方法论一脉相承——只有先弄清是什么和应当怎样才能写出有意义的断言而非机械地堆砌assert True。核心职责二创建简单、聚焦的单元测试Validator 的测试观可以概括为一句话测试行为不测试实现细节35 个好测试胜过 20 个重复测试。具体测试对象分为三类Happy path快乐路径验证功能在正常、符合预期的输入下工作关键边界情况critical edge cases空输入、null值、边界条件错误处理确保错误被优雅处理不会导致应用崩溃。文档明确给出了每个特性的测试数量建议3-5 tests per feature is often sufficient并强调关注功能本身而非覆盖率百分比。测试结构指南JS/TS 与 Python 双语言模板JavaScript / TypeScript 项目// Simple test example describe(FeatureName, () { test(should handle normal input correctly, () { const result myFunction(normal input); expect(result).toBe(expected output); }); test(should handle empty input, () { const result myFunction(); expect(result).toBe(null); }); test(should throw error for invalid input, () { expect(() myFunction(null)).toThrow(); }); });三个用例依次覆盖正常输入、空输入、非法输入抛错——正是happy path 边界 错误处理的最小完备组合。Python 项目# Simple test example import unittest from my_module import my_function class TestFeature(unittest.TestCase): def test_normal_input(self): result my_function(normal input) self.assertEqual(result, expected output) def test_empty_input(self): result my_function() self.assertIsNone(result) def test_invalid_input(self): with self.assertRaises(ValueError): my_function(None)注意两种语言模板的结构差异JS 用describe/test组织Python 用unittest.TestCase类与方法组织但覆盖维度完全一致。测试执行流程五步闭环文档给出的执行流程是一个完整闭环识别测试框架检查package.json、requirements.txt或项目配置文件创建测试文件放入合适的测试目录tests/、__tests__、spec/编写简单测试聚焦功能不追求覆盖率数字运行测试使用项目测试命令npm test、pytest等修复问题测试失败时判断是测试本身的问题还是代码的问题并给出结论。在仓库的真实项目中这套流程有直接对应物。例如 use-cases/agent-factory-with-subagents/examples/testing_examples/pytest.ini 就是一个被 Validator 识别并遵循的 pytest 配置[tool:pytest] testpaths . python_files test_*.py python_classes Test* python_functions test_* addopts -v --tbshort --strict-markers --disable-warnings markers integration: Integration tests slow: Slow running tests asyncio: Async tests filterwarnings ignore::DeprecationWarning ignore::PendingDeprecationWarning asyncio_mode auto从这份配置可以提炼出 Validator 在 Python 项目中应当遵循的具体约定测试文件以test_*.py命名、测试类以Test*开头、测试函数以test_*开头、异步测试通过asyncio_mode auto直接编写自定义标记integration、slow、asyncio必须在markers中声明否则--strict-markers会直接报错。验证方法保持简单的三条铁律文档将验证哲学凝练为四条原则不要过度设计测试Dont over-engineer tests聚焦能否工作而非每行是否被覆盖Focus on does it work? not is every line covered?35 个好测试优于 20 个重复测试测试行为而非实现细节Test behavior, not implementation details。该测什么✅项目说明主功能按预期工作核心功能的正向验证常见边界情况被处理空值、空串、边界条件错误不会让应用崩溃异常路径的优雅降级API 契约得到遵守如适用接口状态码、字段、结构数据转换正确输入到输出的变换准确性不该测什么❌项目说明所有可能的输入组合组合爆炸收益递减内部实现细节重构即碎绑定实现第三方库的功能信任依赖测试集成点即可琐碎的 getter/setter无业务逻辑测之无益配置值配置变更不应导致测试失败常见测试模式三种典型场景API 端点测试JStest(API returns correct data, async () { const response await fetch(/api/endpoint); const data await response.json(); expect(response.status).toBe(200); expect(data).toHaveProperty(expectedField); });验证 HTTP 状态码与返回结构中的关键字段属于典型的API 契约验证。数据处理测试Pythondef test_data_transformation(): input_data {key: value} result transform_data(input_data) assert result[key] TRANSFORMED_VALUE直接对纯函数做输入-输出断言是最简单也最稳定的测试形式。UI 组件测试JS React Testing Librarytest(Button triggers action, () { const onClick jest.fn(); render(Button onClick{onClick}Click me/Button); fireEvent.click(screen.getByText(Click me)); expect(onClick).toHaveBeenCalled(); });通过 mock 回调函数验证交互行为避免依赖真实组件树的复杂度。在真实仓库中验证模式如何落地仓库提供了大量可对照的测试实现可作为 Validator 生成测试时的模式参考。依赖注入与 Mock 化conftest.py 的实践use-cases/agent-factory-with-subagents/agents/rag_agent/tests/conftest.py 展示了 Validator 在 Python 项目中常用的 fixture 策略用AsyncMock/MagicMock隔离外部服务数据库连接池、OpenAI 客户端用TestModel/FunctionModel替代真实大模型例如pytest.fixture def mock_db_pool(): Create mock database pool. pool AsyncMock() connection AsyncMock() pool.acquire.return_value.__aenter__.return_value connection pool.acquire.return_value.__aexit__.return_value None return pool, connection这种mock 掉所有外部依赖只测自身逻辑的做法与 validator.md 中测试功能而非第三方库的原则完全一致。边界与错误处理的真实用例use-cases/agent-factory-with-subagents/examples/testing_examples/test_agent_patterns.py 中包含了文档所要求的全部三类用例。例如错误处理测试通过side_effect注入异常验证工具能优雅降级pytest.mark.asyncio async def test_database_tool_error(self, mock_dependencies): Test database tool with error handling. # Configure mock to raise exception mock_dependencies.database.execute_query.side_effect Exception(Connection failed) test_model TestModel(call_tools[mock_database_query]) with test_agent.override(modeltest_model): result await test_agent.run( Query the database, depsmock_dependencies ) # Tool should handle the error gracefully assert mock_database_query in result.data.message该文件还演示了结构化输出校验Pydantic 模型字段过滤、无效输出处理、缺失必填字段等边界场景——这些正是 validator.md 中critical edge cases的具体形态。最终验证清单完成验证前Validator 需逐项自查测试简单且可读主功能已被测试关键边界情况已覆盖测试真实运行且通过没有过度复杂的测试搭建测试名称清楚描述其测试内容标准输出格式让结果可被机器与人共同消费文档规定验证完成后必须按固定模板输出结构化报告这是 Validator 与主代理/人协作的关键契约# Validation Complete ## Tests Created - [Test file name]: [Number] tests - Total tests: [X] - All passing: [Yes/No] ## What Was Tested - ✅ [Feature 1]: Working correctly - ✅ [Feature 2]: Handles edge cases - ⚠️ [Feature 3]: [Any issues found] ## Test Commands Run tests with: [command used] ## Notes [Any important observations or recommendations]这套格式的价值在于主代理无需解析自由文本即可从结构化字段中提取测试数量、通过状态、风险点与可复现命令从而决定后续任务是否标记为完成。在完整工作流中调用 Validatorcommands/execute-plan.md 给出了 Validator 的正式调用方式与前置条件所有任务实现完毕并处于review状态后进入验证阶段使用 Task 工具启动 validator 代理并传入详细描述——包括已实现功能清单与修改的文件列表Validator 创建聚焦的单元测试、测试关键边界与错误处理、用项目测试框架运行、报告测试内容与发现的问题主代理补充检查组件间集成问题与计划验收标准对通过单元测试覆盖的任务从review状态推进到done无测试覆盖的任务留在review并记录原因如 Awaiting integration tests。这一调用契约与 validator.md frontmatter 中的 You must pass exactly what was built as part of the prompt 完全对齐——调用方有责任提供足够的实现上下文Validator 才有资格产出有效的测试。与验证命令体系的衔接在更宏观的层面本仓库的 validation/README.md 描述了另一层自动化通过/ultimate_validate_command一键分析代码库并生成定制化的.claude/commands/validate.md随后/validate一次性执行 linting、类型检查、风格检查、单元测试与端到端测试。example-validate.md 展示了一份针对 React FastAPI PostgreSQL 应用生成的示例验证命令其中单元测试阶段为!cd frontend npm test -- --coverage !cd backend pytest tests/unit -v --covsrcValidator 创建的单元测试正是这条流水线中 Phase 4: Unit Testing 的直接输入而当 Validator 判断单测不足以覆盖完整链路时端到端阶段Playwright 用户流程、Docker 后端、curl API、直查数据库会接手兜底。两者共同构成 If/validatepasses, your app works 的信心来源。关键要点回顾角色Validator 是 AI Coding Workflows 验证阶段的自动化测试专家子代理仅在实现完成后被调用输入契约调用方必须把实际构建了什么完整传给 Validator测试哲学简单 复杂功能 覆盖率行为 实现细节35 个用例/特性通常足够覆盖维度happy path 关键边界 错误处理外加 API 契约与数据转换如适用执行闭环识别框架 → 建文件 → 写用例 → 运行 → 修复并定性协作契约以结构化 Markdown 报告测试清单、通过状态、命令、备注回传结果支撑任务状态流转仓库佐证pytest 配置、conftest mock 策略、测试模式文件与验证命令示例共同印证了这些规范在本框架中的真实可运行性。Validator 的意义不在于多写测试而在于用最少、最有效的断言为 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考