코딩 에이전트 만드는 법

(ghuntley.com)

62P by GN⁺ 11달전 | ★ favorite | 댓글 4개

2025년 현재 코딩 에이전트를 직접 만드는 것은 개인 개발자가 해볼수 있는 가장 좋은 프로젝트중 하나
에이전트는 300줄 코드와 LLM 토큰 루프만으로 동작하며, 이를 만들어 봄으로써 소비자가 아닌 AI 생산자로 전환할 기회를 제공
기본 구성 요소는 파일 읽기, 파일 목록, Bash 실행, 파일 편집, 코드 검색 같은 툴이며 이를 통해 실제 자동화 기능을 구현
모델 선택에서는 Claude Sonnet, Kimi K2 같은 agentic 모델이 적합하며, 필요 시 GPT 같은 오라클 모델을 도구로 연결해 고차원적 검증을 수행함
실제로 Amp, Cursor, Claude Code, GitHub Copilot 등 상용 제품들도 유사한 구조임

워크숍 개요

Geoffrey Huntley가 진행한 무료 워크숍으로, 코딩 에이전트를 직접 만드는 방법과 원리를 실습 중심으로 안내
Roo code, Cline, Amp, Cursor, Windsurf, OpenCode 같은 기존 상용 AI 도우미들과 구조 및 원리를 비교하며, 직접 구현해 보는 기회 제공
제작 경험을 통해 단순 AI사용자에서 벗어나 직접 AI를 활용해 자동화 도구를 제작하는 개발자로 성장할 수 있음
핵심 구조는 300줄 가량의 코드에서 LLM 토큰을 루프 방식으로 활용해 에이전트 기능을 만드는 것
각 도구별 프리미티브(읽기, 파일 목록, 실행, 편집, 코드 검색) 기능을 추가하며 실제 동작 예시 및 코드는 GitHub 저장소에 공개

에이전트란 무엇인가

최근 "에이전트"라는 용어가 광범위하게 사용되나, 실질적 의미와 내부 동작 원리는 명확하지 않음
에이전트 제작의 진입장벽이 낮아짐에 따라, AI 소비자를 넘어 업무 자동화를 주도할 수 있는 생산자로 성장 가능함
2025년 기준으로, 기본 데이터베이스 개념(Primary key)처럼 에이전트 제작 원리가 필수 지식으로 자리 잡음
Canva 등 기업들은 이미 면접 과정에서 AI 사용을 권장하고 있으며, AI 자동화 역량은 채용의 핵심 요소가 됨
이제 뒤처지는 이유는 AI 때문이 아니라, 자기 계발을 통해 새로운 도구를 익히지 않는 것임

코딩 에이전트의 핵심 원리

코딩 에이전트는 300줄 코드와 LLM 토큰 루프만으로 구성되며, 반복적인 토큰 입력을 통해 기능 수행
동시 작업(concurrent work) 개념이 중요
- 예: Zoom 회의 중에도 에이전트가 병렬로 작업을 진행할 수 있어 업무 효율이 크게 향상됨
모든 LLM이 에이전틱한 것은 아님
- '고안전' (예: Anthropic, OpenAI)
- '저안전' (예: Grok)
- '오라클' (요약·고차사고에 유리)
- '에이전틱' (행동 편향, 빠른 반복·도구 호출)
개발자는 모델별 특성을 이해하고 목적에 따라 활용 모델을 선택함
무조건적인 컨텍스트 윈도우 할당은 성능 저하 요인이며, "적게 할당할수록 결과가 좋음"을 유념해야 함
- 과도한 MCP 툴 등록은 성능 저하로 이어짐
규칙: “Less is more” → 필요한 만큼만 도구와 데이터를 맥락에 배치해야 최적 성능 확보

코딩 에이전트 구축 과정의 흐름

1. 툴 등록 및 함수 호출
- LLM에 예를 들어 날씨 조회 툴을 등록하고, LLM이 적합한 상황에 함수 호출 형식으로 대응할 수 있게 함
- MCP(Model Context Protocol)는 "함수에 대한 정보 배너"와 유사하며, 함수 설명만 등록해도 자동 호츨 가능함
2. 프리미티브 툴별 핵심기능
- 파일 읽기(ReadFile): 경로 전달시 파일 내용을 컨텍스트로 읽어옴
- 파일 목록(ListFiles): 디렉터리 내 파일·폴더 리스트 제공
- 명령어 실행(Bash): LLM이 시스템 셸 명령어 실행 및 결과 반환
- 파일 편집(Edit): 지정 파일을 생성·수정하는 행위 자동화
- 코드 검색(CodeSearch): 패턴이나 키워드, 함수명을 기준으로 코드베이스 전체를 신속 검색함 (ripgrep 활용)
3. 예시 및 결과 흐름
- 각 툴을 LLM에 통합하여 자연어 프로프트만으로 연속적 업무(예: FizzBuzz 코드 생성→실행 확인, 디렉터리 탐색→내용 분석 등) 자동화
- 툴 함수는 사용자 입력이나 시나리오에 맞춰 순차적으로 호출 및 결과 반환을 루프 내에서 반복
- 에이전트의 주요 동작 시퀀스: 사용자 입력→툴 호출 여부 판단→툴 실행→결과 컨텍스트에 할당→반복

확장 가능성과 오픈소스

현재 대부분의 코딩 에이전트는 ripgrep 등 기존 오픈소스 도구를 기반으로 동작
GitHub에는 SST Open Code, mini-swe-agent 등 단 100줄로 구현된 간단하지만 강력한 에이전트 프로젝트들이 존재하므로 성능 및 구조 참고 가능
개발자들은 기존 제품 비교 대신 직접 제작을 통해 원리를 이해하고 활용할 것을 권장
실제 업무·자동화에 적용 시, 자체 에이전트 생성 및 조직 내 확산이 경쟁력으로 연결됨

결론과 시사점

코딩 에이전트는 복잡한 기술이 아닌 간단한 루프 구조와 도구 조합으로 구성
코딩 에이전트 제작의 핵심은 구조이해와 신속실행 능력이며, 직접 제작 경험을 통해 AI 기술 변화에 적극적으로 대응 가능
중요한 것은 AI 그 자체보다 꾸준한 자기 계발과 도구 제작 역량 확보등의 자기 투자가 현시점에서 가장 중요한 개인 성장 전략임
“AI가 당신의 일을 빼앗는 것이 아니라, 당신의 동료가 에이전트로 무장해 자동화하며 더 빠르게 일하는 것이 위협”

GeekNews Weekly에 포함된 글입니다. 에디터 코멘트 보기

GN⁺ 11달전 [-]

Hacker News 의견

저희 Princeton SWE-bench 팀에서 약 100줄 코드로 SWE-bench에서 좋은 성과를 내는 에이전트를 만들었음, 관심 있으면 한 번 살펴보면 좋겠음 mini-swe-agent
- 진짜로 꽤 간단한 구조임에 놀람, 이런 정보를 공유해줘서 고마움
  전체 코드는 사실 이 프롬프트들로 돌아감 에이전트 기본 프롬프트 소스코드
```
Your task: {{task}}. Please reply
with a single shell command in
triple backticks.

To finish, the first line of the
output of the shell command must be
'COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT'.
```
- 에이전트 샘플 프롬프트 중 “1. 코드베이스에서 관련 파일 찾기 및 읽기 2. 이슈 재현 스크립트 만들기 3. 이슈 수정 4. 스크립트로 수정 확인 5. 엣지 케이스 테스트” 부분이 유용함
  나도 디버깅 루프에서 이런 식의 프롬프트를 유사하게 사용함
  “코드베이스 분석 후 원인 후보를 리스트업하고, 가능성 높은 순으로 랭크하고, 스크립트나 디버그 로깅으로 가설을 검증” 방식이 나만의 문제 해결 루틴에 큰 도움이 됨
- 문제가 하나의 파일에 자족적으로 있을 때 LLM을 이용해 수정하는 것은 매우 쉬움
  그러나 일반적인 코드베이스에서는 파일과 맥락이 여기저기 흩어져 있어서, 개발자의 구조화된 설계 의도와 조직화에 맞춰 파악하기가 쉽지 않음
- 멋진 시도에 박수를 보냄, 다만 아쉬운 점은 도구가 많지 않다는 것임
  대부분의 코드는 에이전트 프레임워크에 해당되고 SWE만을 위한 특화 코드는 생각보다 많지 않음
  나도 재미로 SWE 에이전트를 만들어봤으니 autocode도 참고해보면 좋겠음
- 고맙다는 의미에서 참고 자료에 추가함
Thorsten Ball이 작성한 매우 유사한 “에이전트 빌드 방법 가이드”가 AmpCode How To Guide에도 존재함
전반적으로 Amp도 꽤 흥미로움
이제는 더 이상 비밀스러운 서비스가 아니지만, 에이전트 코딩 관련 도구가 계속 공개되는 것이 반가움
앞으로 다양한 소프트웨어에서 이러한 에이전트 모델이 기본적으로 포함될 것이라 생각함
- 이게 훨씬 보기 좋아서 고마움을 느낌
- 저자 본인이 Amp에서 근무한다는 내용도 언급됨
- Ghuntley 또한 Amp에서 일함
그림 한 장이 보통 1000단어의 가치라는데, 이 자료에선 그림들의 가치가 99.6% 할인된 느낌임
이게 뭔지 궁금함
- 컨퍼런스 워크숍용 슬라이드 자료임
  텍스트는 실제 발표에서의 워딩을 딕테이션한 것임
혹시 누군가가 툴 활용 방식에 대해 확인해줄 수 있는지 궁금함
Claude, ChatGPT 등에서 API로 "툴"을 제공하며 툴 호출 요청이 들어오면 응답자로서 툴을 실제로 실행하고 결과를 다시 전달하는 형태로 이해하고 있음
근데 실제로 모델은 엄밀히 말해 문자 기반이니, API에서 어떻게 모델 응답을 여러 구조로 바꾸는지 궁금함
분명히 파인튜닝 과정에서 특정 툴 호출을 특수한 블록 형태로 넣은 예제를 통해 모델이 이해하고, Claude/ChatGPT 서버에서 그걸 해석한다는 과정이 있었을 거라 추정함
이와 관련해 문서나 내부적으로 쓰는 특수 토큰에 대한 정보가 있는지, 또 유저 입력이 이 “의미 담당” 토큰을 악용하지 못하게 어떻게 막는지 궁금함
- Anthropic에서 공개한 구현 문서가 있음
  Anthropic Tool Use Documentation
  여기서 모델은 사실 “텍스트”가 아니라 토큰 단위로 동작함을 명확히 알 수 있음
  컴파일러가 소스코드를 파싱해서 키워드, 괄호, 구조 등 “토큰” 시퀀스를 만든다는 점과 비슷함
  출력물에는 실제 단어와 함께 메타데이터도 포함될 수 있음
- 개념적으로는 맞게 이해했음
  오직 LLM과의 진짜 인터페이스는 “토큰” 뿐이고, 제어와 데이터 채널이 분리되어 있지 않음
  모델 API 계층에서 툴 호출용 인스트럭션 및 사용 가능한 툴 목록을 프롬프트에 삽입, 각각에 대한 설명도 같이 제공
  툴 호출이 필요할 때 모델은 응답에 특수 블록(특수 토큰 포함, 툴 이름 및 파라미터 명시)을 삽입하면, API 계층이 이를 추출해 JSON 형태로 변환함
  툴 실행 결과도 특수 토큰으로 인코딩되어 삽입
  사용자 입력에서 자체적으로 이런 토큰을 주입하지 못하도록 API 계층이 막고 있음
  최신(SoTA) 모델들은 툴 호출에 대해 상당한 파인튜닝이 이루어졌음, 범용 툴 호출/특정 툴 케이스(예: Claude Sonnet 모델이 Claude Code 툴에 특화)에 대한 파인튜닝 모두 포함
  모든 게 잘 작동하는 게 신기할 정도임, 툴 호출에선 파인튜닝이 정말 핵심적인 역할임
  파인튜닝 없이도 동작은 가능하지만, 성공률이 크게 떨어짐
- “툴 호출이 필요한 예시를 특수한 블록으로 반환하는 방식으로 파인튜닝했다”는 추측은 맞다고 생각함
  답을 잘 모를 때나 지시를 받으면 툴 호출 포맷으로 응답하도록 학습됨
  포맷을 따르는 툴 호출 예시(포맷 자체)와 일부 도구에 특화된 학습 둘 다 진행됨
  예를 들어 gpt-oss는 아무리 언급이 없어도 검색 도구를 쓰려는 경향
  Anthropic 문서엔 친숙한 도구(예: text_editor, bash) 목록도 따로 있고, 이 도구들은 사용법에 대한 깊은 의미까지 따로 학습됐을 확률이 높음
  실제론 구조가 꽤 깨지기 쉽고, “특수 토큰이나 토큰 시퀀스”라는 낮은 수준의 신호를 통해 이뤄짐
“토큰을 계속 루프에 던지면 에이전트가 생긴다”는 말에 “토큰”을 “돈”으로 바꿔서 보면 현실적인 풍자가 느껴짐
결국 돈을 계속 태우면 에이전트가 생긴다는 셈임
- 토큰이 전부 돈이라고 말하긴 어렵다고 생각함
  로컬 모델들도 계속 좋아지고 있음
  아직까지는 최고의 결과를 내려면 토큰(=돈)이 필요하지만 미래에는 달라질 가능성이 높음
이렇게 이미지만 가득하면 너무 읽기 힘들어짐
스크롤 시뮬레이터를 보는 것 같은 느낌임
bash 툴 말고 굳이 다른 툴이 왜 필요한지 궁금함
파일 목록조회라든지, 레포 찾기 및 탐색, 파일 내용 편집 같은 건 bash만으로도 다 할 수 있지 않나
아니면 위의 mini-swe-agent 예시에서 보여주는 케이스인지 궁금함
- 기술적으로 봤을 때 bash 하나만으로도 충분히 다양한 작업이 가능하고, 실제로 그렇게 성공한 경험도 있음
  흥미로운 점은 도구를 제한할수록 에이전트가 더 창의적으로 접근한다는 점임
  하지만 학습된 다양한 도구를 제공하면, 모델이 각 도구의 사용법을 이미 잘 알고 있어서 토큰 사용량도 효율적이고 전반적으로 성공률도 높아짐
  Bash만 쓸 경우 bashism이나 인수 처리, 공백 처리 같은 부분에서 자주 헤매는 문제도 있음
- 별도의 도구를 쓰는 게 bash 하나에 몰아넣는 것보다 훨씬 단순함
  만약 모든 것을 bash로 처리하면, 무조건 안전하게 실행 가능한 명령어(예: 파일 목록)는 바로 실행하고, 그 외 위험한 명령은 사용자 승인 받는 체계를 별도로 구현해야 함
  파일 목록조회를 별도 툴로 제공하면 프로젝트 디렉터리 외부 파일 노출도 막을 수 있음
- 사실상 bash 툴과 Edit 툴만으로 코딩 에이전트 작동은 충분히 가능함 (Edit는 필수까진 아니지만 비효율성 커짐)
  다만 코드 검색 같은 부분에서 어려울 수 있음
  예를 들어 ripgrep을 bash에서 쓰게 프롬프트를 조정하는 식으로 커버도 가능할 듯함
- 왜 IDE가 필요한가? 쉘에서 모든 걸 할 수 있음에도 왜 굳이 쓰는가?
  UI(인터페이스)란 건 바로 그 순간 필요한 정보와 액션을 제공해주는 역할임
- 왜 bash 툴 외에 다른 게 들어갔냐는 질문에는 처음엔 최소한의 도구만 주고 시작해서, 나중에 bash를 추가해도 되는 거라는 점 때문일 것 같음
“에이전트 만드는 법”을 장황히 설명하기보단, 에이전트가 실제로 만든 프로젝트를 보여주길 바라는 마음임
- 직접 에이전트를 만들어서 HN에 “Show HN”으로 공유해주면 너무 좋겠음
Oracle, Agent, high safety, low safety라는 축이 뭘 의미하는지 설명 가능한 사람 있는지 질문함
edge와 chrome의 온디바이스 모델(phi4-mini, gemini nano)로 직접 시도해봤는데, 모델 크기에 비해 꽤 잘 동작해서 놀람
how to build an agent on device 실험 사례