从零手把手：如何用 Go 打造你自己的 Coding Agent

ghuntley/how-to-build-a-coding-agent — ⭐ 5.6k · Go 语言 · 教学项目

开篇：一个真实的故事

想象你正在赶一个紧急的功能上线，凌晨两点改 bug，突然意识到：要是有一个 AI 助手能直接帮你读代码、搜函数、跑命令、甚至帮你改文件，那该多好。

别等了。GitHub 上有一个叫 ghuntley/how-to-build-a-coding-agent 的项目，专门教你怎么从零构建这样一个 Coding Agent。项目作者 Geaves Huntley 是个有十多年经验的全栈工程师，他的目标很简单——让你不只是用别人的 AI 编程工具，而是亲手造一个属于你自己的。

这个项目目前在 GitHub 上已经斩获超过 5600 颗星，社区 fork 数超过 600 次，热度远超同类教学项目。

这个项目解决什么问题

市面上的 AI 编程工具——Roo Code、Cline、Amp、Cursor、Windsurf、OpenCode——看起来很强大，但你无法深入理解它们的工作原理，更别说定制自己的需求。

这个 workshop 的核心价值在于：它不是给你一个黑盒让你用，而是带你一步步拆解黑盒、理解原理。你将从最简单的单轮对话开始，逐步为它添加文件读取、目录浏览、Shell 命令执行、代码编辑和正则搜索等工具，最终得到一个功能完整的本地 AI 开发助手。

整个项目使用 Go 1.24.2 作为开发语言，调用 Anthropic Claude API 提供推理能力，代码结构清晰，适合作为学习 Agent 架构的入门教材。

六步构建法：从聊天机器人到 Agent

项目的核心教学思路是渐进式演进，每个 .go 文件代表一个版本的 Agent：

每一步都可以独立运行验证，通过 go run <文件名> 即可启动。添加 --verbose 参数还能看到完整的 API 调用日志，非常适合调试和理解内部机制。

核心架构：Event Loop 的艺术

这个项目的架构核心是一个事件循环（Event Loop），类似这样：

1. 获取用户输入
2. 将输入发送给 Claude API
3. Claude 可能直接回复，也可能请求调用工具
4. Agent 执行对应工具（读文件、跑命令等）
5. 将工具执行结果回传给 Claude
6. Claude 给出最终回复

这个循环持续进行，直到用户主动退出。

工具注册采用了**工具注册表（Tool Registry）**模式，所有工具通过统一的接口注册，Claude 通过名称调用对应函数。代码中的 bash_tool.go 实现了沙盒化的命令执行，限制了可执行的命令范围，降低安全风险。

开发体验：devenv.sh 带来的惊喜

项目的开发环境配置也值得称道：作者选择使用 devenv.sh 管理开发环境，配合 devenv.nix 配置文件，可以一键初始化包含 Go、Rust、Python、Node.js、TypeScript、ripgrep 等工具链的完整开发 shell。

进入开发环境只需要一条命令：

devenv shell

这条命令会自动安装所有依赖并进入配置好的 shell，不需要手动配置 PATH 或安装各个语言的运行时。开发体验的统一性对于教学场景非常有价值。

依赖管理方面，项目使用 Go 官方的 go.mod，直接引入 anthropic-sdk-go v1.26.0，无需自行封装 HTTP 请求。此外还引入了 invopop/jsonschema 用于 JSON Schema 生成和验证。

上手门槛：真的零基础吗

项目 README 声称「不需要 AI 专家背景」，这是真实的。

但前提是你有基本的 Go 语言编程能力——至少能看懂 go run、理解 struct 和接口、会配置环境变量。没有 Go 基础的话，需要额外花几个小时熟悉 Go 语法。

另外，项目要求你有一个 Anthropic API Key（用于调用 Claude），国内用户需要自行解决 API 访问问题。

由于是纯命令行工具，没有 Web UI，适合习惯在终端工作的开发者。

局限与争议

这个项目有几个明显的局限性：

• 纯命令行界面：对于习惯图形界面的用户，上手有一定门槛，没有 Web UI 那种「所见即所得」的体验。
• 需要 API Key：Claude API 是付费的，每次调用都会消耗积分，成本控制需要自行管理。
• 安全性考量：bash_tool.go 虽然做了命令限制，但沙盒能力有限，直接在生产环境使用存在风险，不建议直接部署到服务器。
• 仅支持 Claude：项目硬编码了 Anthropic SDK，不支持 GPT-4、Gemini 等其他大模型，灵活性受限。

行业意义：Agent 时代的入门向导

2025-2026 年，AI Agent 是整个行业最热的方向。从 OpenAI 的 Operator 到各家的 Coding Agent，市场在快速扩张。但大部分开发者只是这些工具的使用者，对底层机制知之甚少。

这个项目的价值在于降低了理解门槛：通过 6 个小文件、1000 多行 Go 代码，把一个复杂的 Agent 系统拆解得清晰可见。无论你是想学习 Agent 架构、还是想基于此定制自己的开发助手，这个项目都是一个优秀的起点。

作者还维护了配套博客 ghuntley.com/agent，提供了更详细的思路讲解，值得延伸阅读。