ghuntley/how-to-build-a-coding-agent

ghuntley/how-to-build-a-coding-agent – 建立本地 Claude 驅動型編碼助手的實作工作坊

這是什麼 – 一個逐步式教學（附帶可直接執行的 Go 源碼檔案），展示如何將 Anthropic 的 Claude 模型轉換為本地的「編碼助手」。此專案透過六個逐步進化的版本，每次新增一個新工具（檔案讀取、目錄列出、shell 執行、檔案編輯、程式碼搜尋），並示範經典的 代理-工具 循環。

為何重要 – 它提供了一個具體、實作導向的範例，展現了新興模式：大型語言模型保持輕量，而繁重的工作（檔案系統存取、命令執行、grep 風格搜尋）由明確、沙盒化的工具來處理。讀者可清楚看到完整架構、基於 Go 的工具註冊表，以及如何將 Claude 的 JSON 結構化工具呼叫連結至實際函數。

---

主要功能（如 README 所述）

功能	你將獲得
Claude 整合	簡單的 Go 客戶端，將使用者訊息傳送至 Anthropic API 並接收回應。
逐步式代理	六個可直接執行的程式（chat.go、read.go、list_files.go、bash_tool.go、edit_tool.go、code_search_tool.go），每個都新增一項新功能。
工具系統	一致的工具定義（名稱、描述、輸入模式、Go 函數），讓 Claude 可透過其工具使用協定呼叫。
檔案操作	安全地讀取任意檔案、列出目錄內容、編輯或建立檔案。
Shell 命令執行	執行有限的 bash 命令，並將 stdout/stderr 回傳給 Claude。
程式碼搜尋	使用 ripgrep 在程式碼庫中進行模式搜尋。
詳細日誌	--verbose 標誌可顯示完整的事件迴圈、工具分派與錯誤細節。
範例資料	小型示範檔案（fizzbuzz.js、riddle.txt、AGENT.md），可立即試用工具。
開發環境	可選的 devenv 設定，可自動部署 Go、Node、Python、Rust、.NET 及常見開發工具。

---

架構概覽（來自 README）

1. 使用者輸入 → 透過 Anthropic 客戶端傳送給 Claude。
2. Claude 直接回應或回傳 工具請求（例如 read_file）。
3. 代理在 註冊表 中查找請求的工具，執行 Go 函數，捕獲結果或錯誤。
4. 結果回傳給 Claude，Claude 可產生最終答案或請求更多工具。
5. 此迴圈重複，直到 Claude 回傳純文字回應。

README 中的圖示展示了兩個視角：

• 應用進化 – 每個後續程式如何新增新工具。
• 事件迴圈 – 消息、工具分派與結果處理的執行時流程。

---

開始使用（依 README 操作）

1. 前置條件
   • Go 1.24.2 或更高版本（或使用提供的 devenv 設定）。
   • Anthropic API 金鑰（export ANTHROPIC_API_KEY=…）。
2. 設定
   • 推薦：執行 devenv shell 以載入環境。
   • 或手動在克隆後執行 go mod tidy。
3. 執行第一個版本

   go run chat.go          # 基本 Claude 聊天
   go run read.go          # 新增檔案讀取工具
   go run list_files.go    # 新增目錄列出功能
   go run bash_tool.go     # 新增 shell 命令工具
   go run edit_tool.go     # 新增檔案編輯工具
   go run code_search_tool.go  # 新增基於 ripgrep 的搜尋
   

   • 使用 --verbose 查看詳細日誌。
   • 嘗試 README 中展示的範例提示（如「讀取 fizzbuzz.js」、「執行 git status」）。
4. 故障排除 – 檢查 API 金鑰、執行 go mod tidy、使用 --verbose、驗證檔案權限。

---

技術堆疊

• 語言 – Go（利用 Go 結構體生成 JSON 模式）。
• LLM – 透過公開 API 存取 Anthropic Claude。
• 工具 – 使用 ripgrep 實現快速程式碼搜尋，使用標準 OS shell 執行命令。
• 可選開發環境 – devenv（提供多語言執行時與工具）。

---

適合誰使用

• 對 LLM 驅動的代理 感興趣，並希望安全地暴露系統能力的開發者。
• 希望獲得 Claude 工具使用整合具體範例的 Go 程式員。
• 尋找現成、逐步式教學的教育者或工作坊主辦者。

---

作者建議的下一步

• 新增自訂工具（如 HTTP API 呼叫器、網頁爬蟲）。
• 將工具串聯以實現更複雜的流程。
• 實現跨會話的持久化記憶。
• 建立 Web UI 前端。
• 嘗試其他 LLM 提供商。

---

總結 – 此專案是使用 Claude 與 Go 建立本地 AI 編碼助手的實用、動手實作指南，以清晰、逐步的方式展現現代代理-工具模式。