企业官网建设流程全解析

深入解读 Claude Code 实现代理子代理（implementation-agent）：从规范到端到端交付的实战指南

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto

导读

在 Claude Code 的 Subagents 体系中，实现代理（Implementation Agent）是承担「从需求到代码」全流程落地的专职子代理：它既能读取规格说明与既有代码，也能直接编写、编辑文件并运行构建与测试命令。本文以claude-howto仓库中的implementation-agent.md为骨架，结合仓库的 Subagents 完整参考指南与代码质量实践，讲解如何理解、配置、调用这类 full-stack 实现子代理，以及如何围绕它构建可靠的交付流程。读完本文，你将掌握实现代理的能力边界、六步实现流程、代码质量与错误处理规范、结构化输出格式与完成检查清单，并能将其部署到自己的项目中。

一、什么是实现代理：子代理体系中的「执行者」

claude-howto仓库的 04-subagents/README.md 明确指出：Subagents 是 Claude Code 可以委托任务的专职 AI 助手，每个子代理拥有独立的上下文窗口、定制系统提示词和受控的工具权限，从而避免复杂任务污染主对话上下文。

在这个体系中，implementation-agent.md（英文原版）与uk/04-subagents/implementation-agent.md（乌克兰语翻译版）定义了一个定位清晰的「执行者」角色：

你是一名资深开发者，负责根据规格说明（specifications）实现功能。

它的核心定位可以概括为一句话：把规格变成可运行的代码。与code-reviewer.md（只读审查）、documentation-writer.md（产出文档）不同，实现代理拥有写入与执行能力，是端到端（end-to-end）功能开发的主力。

二、实现代理的能力边界：frontmatter 中的工具矩阵

implementation-agent.md的文件头以 YAML frontmatter 声明了代理的元信息：

--- name: implementation-agent description: Full-stack implementation specialist for feature development. Has complete tool access for end-to-end implementation. tools: Read, Write, Edit, Bash, Grep, Glob model: inherit ---

这六个字段决定了子代理的行为边界：

对照 04-subagents/README.md 的「Configuration Fields」表，tools还可以使用disallowedTools显式排除工具，permissionMode、maxTurns、skills、mcpServers等字段均按需可加。实现代理的六项能力对应关系如下：

• Read—— 读取规格说明（specifications）与既有代码；
• Write—— 创建新的代码文件；
• Edit—— 修改既有文件；
• Bash—— 运行构建命令（build commands）与测试；
• Grep—— 在代码库中进行正则搜索；
• Glob—— 按模式查找文件。

这套「读写改 + 执行 + 搜索」的组合正是 full-stack 实现所需的完整闭环，也是它区别于只读审查类子代理（如仅Read, Grep的secure-reviewer.md）的关键。

三、六步实现流程：从需求到交付的标准动作

implementation-agent.md规定了被调用时的标准化流程：

1. 完全理解需求（Understand the requirements fully）；
2. 分析既有代码库模式（Analyze existing codebase patterns）；
3. 规划实现方案（Plan the implementation approach）；
4. 增量实现（Implement incrementally）；
5. 边实现边测试（Test as you go）；
6. 清理与重构（Clean up and refactor）。

这套流程隐含了三个工程原则：

• 先理解后动手：步骤 1–2 强调在写代码之前先吃透需求并研究项目既有约定，避免「按自己习惯写、与代码库风格脱节」；
• 小步快跑：步骤 4–5 将大型功能拆解为可独立验证的增量，每完成一部分立即用测试确认，而不是一次性提交大量未经验证的代码；
• 收尾治理：步骤 6 要求删除调试残留、整理代码并做必要的重构，保证交付物干净。

以本仓库为例，CLAUDE.md 中定义的质量门禁（pre-commit run --all-files、pytest scripts/tests/ -v、ruff check scripts/）正是「测试与构建」步骤的落地工具；scripts/tests/下的test_build_website.py、test_check_markdown_rendering.py等测试用例，则示范了「功能实现后立即编写对应测试」的项目实践。

四、实现指南：四个维度的质量规范

4.1 代码质量（Code Quality）

• 遵循项目既有约定（follow existing project conventions）；
• 编写自文档化代码（self-documenting code），即通过命名与结构表达意图；
• 仅在逻辑复杂处添加注释，避免噪音注释；
• 保持函数小且聚焦（small and focused）；
• 使用有意义的变量名（meaningful variable names）。

这些原则与仓库根目录的 clean-code-rules.md 一脉相承，也与 04-subagents/clean-code-reviewer.md 的审查维度（命名、函数长度、重复代码、注释质量）互为表里——实现代理负责「写对」，清理代码审查代理负责「写美」。

4.2 文件组织（File Organization）

• 按照项目结构放置文件；
• 将相关功能分组（group related functionality）；
• 遵循命名约定；
• 避免深层嵌套目录。

以本仓库的03-skills/目录为例，每个技能（如code-review-specialist/、refactor/）都按「SKILL.md + templates/ + scripts/ + references/」的扁平结构组织，这正是「避免深层嵌套」的直观示范。

4.3 错误处理（Error Handling）

• 处理所有错误场景（handle all error cases）；
• 提供有意义的错误消息（meaningful error messages）；
• 恰当记录错误日志（log errors appropriately）；
• 优雅失败（fail gracefully），即异常时正常收尾而非崩溃或静默吞错。

4.4 测试（Testing）

• 为新功能编写测试；
• 确保既有测试全部通过；
• 覆盖边界情况（edge cases）；
• 为 API 编写集成测试（integration tests）。

对照 04-subagents/test-engineer.md，该测试工程师子代理要求「最低 80% 代码覆盖率、关键路径（认证、支付、数据处理）100% 覆盖」，可作为实现代理在「边实现边测试」阶段的可选协作伙伴——实现代理交付代码后，由测试工程师子代理补全覆盖率。

五、结构化输出格式：让交付可审计

implementation-agent.md规定，每个实现任务完成后必须以固定结构汇报：

• 创建的文件（Files Created）：新文件清单；
• 修改的文件（Files Modified）：改动文件清单；
• 新增的测试（Tests Added）：测试文件路径；
• 构建状态（Build Status）：Pass / Fail；
• 备注（Notes）：重要考量与决策说明。

这一格式的价值在于「可审计性」：主代理（或开发者）无需逐行 diff 即可快速确认改了什么、测了什么、构建是否通过，并能据备注评估设计取舍。这也是 04-subagents/README.md 所述「子代理返回结果给主代理进行合成」的最佳实践形态。

六、完成检查清单：交付前的自检门禁

在标记任务完成之前，实现代理必须逐项核对：

• 代码符合项目约定；
• 所有测试通过；
• 构建成功；
• 无 lint 错误；
• 边界情况已处理；
• 错误处理已实现。

这份清单实际上是仓库质量门禁的代理化表达：CLAUDE.md中的 pre-commit 五项文档检查（markdown-lint、交叉引用、mermaid 语法、链接检查、渲染检查）、ruff/mypy/bandit静态检查，均可视为清单中「构建成功、无 lint 错误」在具体项目中的落地形式。

七、如何部署与调用实现代理

7.1 安装方式

参考 04-subagents/README.md 的安装说明，将实现代理部署到项目有两种常见路径：

# 方式一：复制到项目级（仅当前项目可用） mkdir -p .claude/agents cp /path/to/claude-howto/04-subagents/implementation-agent.md .claude/agents/ # 方式二：复制到用户级（所有项目可用） mkdir -p ~/.claude/agents cp /path/to/claude-howto/04-subagents/implementation-agent.md ~/.claude/agents/

注意：自 v2.1.198 起/agents交互式创建向导已移除，创建与管理子代理通过「直接让 Claude 生成文件」或「手动编辑.claude/agents/」两种方式完成。

7.2 调用方式

实现代理支持三种触发路径：

1. 显式指令：直接点名委托——Use the implementation-agent to build this feature from the spec；
2. 自动委托：当description字段与任务匹配时，主代理会自动分发任务；
3. @提及：用@"implementation-agent (agent)" …保证特定子代理被调用，绕过自动分发的启发式判断。

7.3 与兄弟子代理的协作编排

在真实项目中，实现代理很少单打独斗，典型链条为：

1. implementation-agent依据规格实现功能；
2. test-engineer补齐测试并验证覆盖率；
3. code-reviewer或clean-code-reviewer做质量与安全审查；
4. documentation-writer补文档。

这正是 04-subagents/README.md「Architecture」小节描绘的委托模型：主代理作为协调者，将不同专长委托给各自拥有独立上下文的子代理，再把结果综合返回给用户。

八、从源码结构看实现代理的定位

从仓库结构可以推断，04-subagents/下的九个示例子代理构成了一个完整的开发协作矩阵：

值得注意的是，实现代理与调试代理（debugger.md）工具集完全一致（Read, Edit, Bash, Grep, Glob），但系统提示词分工不同：前者面向「从零到一的构建」，后者面向「故障定位与最小修复」。这说明Subagents 的分工由系统提示词主导，而非仅由工具集决定——这是理解整套子代理体系的关键认知。

九、最佳实践：用好实现代理的四条建议

综合implementation-agent.md与 04-subagents/README.md 的「Best Practices」，建议如下：

1. 提供明确的规格输入：调用前给出需求文档、验收标准与约束（如技术栈、目录位置），减少代理「猜测需求」的成本；
2. 限定工具与权限：如无需写文件则不要授予Write/Edit，遵循「只读优先」的权限最小化原则；
3. 配合检查清单验收：要求代理按第六节清单逐项汇报，而不是只交代码；
4. 与其他子代理结对：实现完成后自动串联test-engineer与code-reviewer，形成「实现—测试—审查」流水线。

版本说明：本文基于claude-howto仓库当前的implementation-agent.md（含英文原版与乌克兰语翻译版）及 04-subagents/README.md（Claude Code v2.1.235）撰写；乌克兰语版本文档最后更新于 2026 年 4 月 9 日，英文版本更新于 2026 年 8 月 4 日（Claude Code 2.1.220）。具体行为以你所使用的 Claude Code 版本官方文档为准。

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto