企业官网建设流程全解析

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

【免费下载链接】context-engineering-introContext engineering is the new vibe coding - it's the way to actually make AI coding assistants work. Claude Code is the best for this so that's 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 的首要职责不是写测试，而是理解被测对象。文档要求按以下顺序建立认知：

1. 阅读相关代码文件（Read、Grep、Glob定位并通读实现）；
2. 识别创建的主要函数/组件；
3. 理解预期的输入与输出；
4. 记录外部依赖与集成点（数据库、API、第三方库等）。

这一步骤与 codebase-analyst.md 的分析方法论一脉相承——只有先弄清"是什么"和"应当怎样"，才能写出有意义的断言，而非机械地堆砌assert True。

核心职责二：创建简单、聚焦的单元测试

Validator 的测试观可以概括为一句话：测试行为，不测试实现细节；3～5 个好测试胜过 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类与方法组织，但覆盖维度完全一致。

测试执行流程：五步闭环

文档给出的执行流程是一个完整闭环：

1. 识别测试框架：检查package.json、requirements.txt或项目配置文件；
2. 创建测试文件：放入合适的测试目录（tests/、__tests__、spec/）；
3. 编写简单测试：聚焦功能，不追求覆盖率数字；
4. 运行测试：使用项目测试命令（npm test、pytest等）；
5. 修复问题：测试失败时，判断是测试本身的问题还是代码的问题，并给出结论。

在仓库的真实项目中，这套流程有直接对应物。例如 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 --tb=short --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会直接报错。

验证方法：保持简单的三条铁律

文档将验证哲学凝练为四条原则：

• 不要过度设计测试（Don't over-engineer tests）；
• 聚焦"能否工作"而非"每行是否被覆盖"（Focus on "does it work?" not "is every line covered?"）；
• 3～5 个好测试优于 20 个重复测试；
• 测试行为，而非实现细节（Test behavior, not implementation details）。

该测什么（✅）

不该测什么（❌）

常见测试模式：三种典型场景

API 端点测试（JS）

test('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 契约验证"。

数据处理测试（Python）

def test_data_transformation(): input_data = {"key": "value"} result = transform_data(input_data) assert result["key"] == "TRANSFORMED_VALUE"

直接对纯函数做输入-输出断言，是最简单也最稳定的测试形式。

UI 组件测试（JS + React Testing Library）

test('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(model=test_model): result = await test_agent.run( "Query the database", deps=mock_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]

这套格式的价值在于：主代理无需解析自由文本，即可从结构化字段中提取测试数量、通过状态、风险点与可复现命令，从而决定后续任务是否标记为完成。

在完整工作流中调用 Validator

commands/execute-plan.md 给出了 Validator 的正式调用方式与前置条件：

1. 所有任务实现完毕并处于review状态后进入验证阶段；
2. 使用 Task 工具启动 validator 代理，并传入详细描述——包括已实现功能清单与修改的文件列表；
3. Validator 创建聚焦的单元测试、测试关键边界与错误处理、用项目测试框架运行、报告测试内容与发现的问题；
4. 主代理补充检查组件间集成问题与计划验收标准；
5. 对通过单元测试覆盖的任务，从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 --cov=src`

Validator 创建的单元测试正是这条流水线中 "Phase 4: Unit Testing" 的直接输入；而当 Validator 判断单测不足以覆盖完整链路时，端到端阶段（Playwright 用户流程、Docker 后端、curl API、直查数据库）会接手兜底。两者共同构成 "If/validatepasses, your app works" 的信心来源。

关键要点回顾

• 角色：Validator 是 AI Coding Workflows 验证阶段的自动化测试专家子代理，仅在实现完成后被调用；
• 输入契约：调用方必须把"实际构建了什么"完整传给 Validator；
• 测试哲学：简单 > 复杂，功能 > 覆盖率，行为 > 实现细节，3～5 个用例/特性通常足够；
• 覆盖维度：happy path + 关键边界 + 错误处理，外加 API 契约与数据转换（如适用）；
• 执行闭环：识别框架 → 建文件 → 写用例 → 运行 → 修复并定性；
• 协作契约：以结构化 Markdown 报告（测试清单、通过状态、命令、备注）回传结果，支撑任务状态流转；
• 仓库佐证：pytest 配置、conftest mock 策略、测试模式文件与验证命令示例共同印证了这些规范在本框架中的真实可运行性。

Validator 的意义不在于"多写测试"，而在于用最少、最有效的断言，为 AI 编码助手建立可信的回归保障——让"功能可用"从主观判断变成可执行的、可复现的、可汇报的客观证据。

【免费下载链接】context-engineering-introContext engineering is the new vibe coding - it's the way to actually make AI coding assistants work. Claude Code is the best for this so that's 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