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

ghuntley/how-to-build-a-coding-agent – 로컬 Claude 기반 코딩 어시스턴트를 구축하는 워크숍

무엇인가요 – Anthropic의 Claude 모델을 로컬 "코딩 에이전트"로 전환하는 단계별 튜토리얼 (실행 가능한 Go 소스 파일 포함). 이 리포지토리는 파일 읽기, 디렉터리 목록, 쉘 실행, 파일 편집, 코드 검색 등의 새로운 도구를 순차적으로 추가하는 6단계 버전을 안내하며, 전형적인 에이전트-도구 루프를 보여줍니다.

왜 중요한가요 – 대규모 언어 모델을 가볍게 유지하고, 파일 시스템 접근, 명령 실행, grep 스타일 검색과 같은 무거운 작업은 명시적이고 사전에 격리된 도구가 처리하는 새로운 패턴에 대한 구체적이고 실습 중심의 예시를 제공합니다. 사용자는 전체 아키텍처, Go 기반의 도구 레지스트리, 그리고 Claude의 JSON 구조화된 도구 호출을 실제 함수에 연결하는 방법을 확인할 수 있습니다.

---

주요 기능 (README에 설명됨)

기능	제공되는 내용
Claude 통합	사용자 메시지를 Anthropic API로 전송하고 응답을 수신하는 간단한 Go 클라이언트.
단계적 에이전트	6개의 실행 가능한 프로그램(chat.go, read.go, list_files.go, bash_tool.go, edit_tool.go, code_search_tool.go)을 제공하며, 각각 새로운 기능을 추가합니다.
도구 시스템	이름, 설명, 입력 스키마, Go 함수로 구성된 일관된 도구 정의를 통해 Claude가 도구 사용 프로토콜로 호출할 수 있습니다.
파일 작업	임의의 파일을 안전하게 읽고, 디렉터리 내용을 목록화하며, 파일을 편집하거나 생성합니다.
쉘 명령 실행	제한된 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에 피드백하여 최종 응답을 생성하거나 더 많은 도구를 요청할 수 있도록 합니다.
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     # 쉘 명령 도구 추가
   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 (JSON 스키마 생성에 Go 구조체 활용).
• LLM – 공개 API를 통해 접근하는 Anthropic Claude.
• 도구 – 빠른 코드 검색에 ripgrep, 명령 실행에 표준 OS 쉘.
• 선택적 개발 환경 – devenv (다중 언어 런타임 및 도구 제공).

---

누구에게 적합한가

• LLM 기반 에이전트에 관심이 있고, 시스템 기능을 안전하게 노출하는 방법을 알고 싶은 개발자.
• Claude와의 도구 사용 통합을 구체적으로 보고 싶은 Go 프로그래머.
• 즉시 사용 가능한 단계적 튜토리얼을 찾는 교육자 또는 워크숍 주최자.

---

저자가 제안하는 다음 단계

• 사용자 정의 도구 추가 (예: HTTP API 호출기, 웹 스크래퍼).
• 도구를 연결하여 더 복잡한 워크플로우 구축.
• 세션 간 지속적 메모리 구현.
• 웹 UI 프론트엔드 구축.
• 다른 LLM 제공업체 실험.

---

결론 – 이 리포지토리는 Claude와 Go를 사용하여 로컬 AI 코딩 어시스턴트를 구축하는 실용적이고 실습 중심의 가이드이며, 명확하고 단계적으로 현대적인 에이전트-도구 패턴을 보여줍니다.