Build a Basic AI Agent from Scratch: Long Task Planning
TL;DR Highlight
AI Agent가 긴 작업을 계획하고 실행하는 방법을 스크래치 코드로 설명한 튜토리얼인데, 댓글에서 실전 플래닝 전략에 대한 풍부한 경험담이 오갔다.
Who Should Read
LLM 기반 Agent를 직접 구현해보고 싶은 백엔드 또는 풀스택 개발자, 특히 복잡한 멀티스텝 태스크를 Agent에게 맡기는 방법을 찾고 있는 개발자.
Core Mechanics
- 원문은 Medium에 게시된 튜토리얼로, AI Agent가 긴 작업(long task)을 어떻게 계획하고 단계적으로 실행하는지를 스크립트 형태의 코드로 보여주는 내용이다.
- 튜토리얼에서 'scratchpad(메모장)'를 활용해 Agent가 중간 상태를 기록하고 참조하도록 하는 방식을 소개했는데, 이는 컨텍스트가 길어질수록 초반 정보를 잊는 LLM의 특성을 보완하려는 시도다.
- to-do list 도구를 Agent에게 제공해 작업 완료 여부를 추적하게 하는 패턴도 포함됐다. 단, 최신 모델에서는 이런 보조 수단 없이도 텍스트 계획만으로 잘 따라간다는 반론이 댓글에서 제기됐다.
- 시스템 프롬프트에 '작업 시작 전에 먼저 계획을 세워라'는 지시를 포함하는 방식도 소개됐다. 이는 현장에서도 유효하다는 공감대가 댓글에 형성됐다.
- 튜토리얼은 실제 설계 원칙(에러 핸들링, 정책, 경계 등)보다는 동작하는 간단한 스크립트 수준으로 의도적으로 단순화됐다. 블로그 포스트의 한계상 불가피한 선택이라는 옹호 의견도 있었다.
- 원문 접근이 JavaScript/쿠키가 필요한 Medium 페이지라 본문 전체를 확인하기 어려웠으며, 실제 코드 상세 내용은 댓글 토론에서 간접적으로 유추할 수 있는 수준이다.
Evidence
- 1년 넘게 다양한 플래닝 방식(AGENTS.md, dev/plan 파일, todo 도구, SQLite DB 등)을 써본 개발자가 '요즘 모델들은 텍스트 계획만으로도 잘 따라간다'고 했다. 복잡도에 따라 ①그냥 시키기 → ②계획 세우고 실행 → ③계획 파일 작성 후 서브에이전트 리뷰 → ④감독자 Agent + 서브에이전트 분업 + handoff.md 넘기기 순으로 에스컬레이션한다는 본인만의 체계를 공유했다.
- 'scratchpad가 무슨 소용이냐, 어차피 같은 데이터가 컨텍스트에 있는 거 아니냐'는 의문이 제기됐다. 컨텍스트가 lossy(손실 있음)해서 앞뒤 정보에 편향되는 특성 때문에 도움이 될 수도 있지만, 최신 모델에선 효과가 줄었을 것이고 작은 모델에는 여전히 유효할 수 있다는 분석이 이어졌다.
- 튜토리얼에서 Eleventy → Hugo 사이트 마이그레이션을 예시로 들었는데, '근데 이 블로그는 Medium에 있잖아요, 마이그레이션 실패한 거 아닌가요'라는 농담 댓글이 달렸다. 악의 없이 웃자고 한 말이지만 콘텐츠 자체에 대한 호의적인 반응도 함께 달렸다.
- 튜토리얼의 코드 품질이 낮다는 비판에 대해, '블로그 포스트는 에러 처리·정책·경계 같은 실제 설계까지 담으면 너무 복잡해지기 때문에 의도적으로 단순한 실행 가능 스크립트로 제한할 수밖에 없다'는 옹호 댓글이 달렸다.
- RL 논문에서 말하는 'long-term planning'과 이 튜토리얼에서 쓰는 같은 단어의 의미가 전혀 다르다는 비판이 있었다. AI 용어가 맥락마다 다르게 쓰여 혼란을 준다는 지적으로, 학술 커뮤니티와 엔지니어링 커뮤니티 간의 용어 괴리를 보여주는 댓글이다.
How to Apply
- 복잡도가 높은 Agent 태스크를 줄 때는 '계획부터 세우고 실행해라'는 지시를 시스템 프롬프트에 넣어라. 단순히 지시만 하는 것보다 Agent가 단계를 나눠 실행하면서 오류가 줄고 추적이 쉬워진다.
- 멀티스텝 작업에서 컨텍스트가 길어질 경우, 감독자 Agent가 handoff.md 파일을 작성해 서브 Agent에게 넘기는 방식을 쓰면 컨텍스트 손실 문제를 완화할 수 있다. 이 패턴은 준비된 프롬프트(sigil)로 저장해두면 몇 번의 키 입력만으로 재사용 가능하다.
- 최신 GPT-4급 이상 모델을 쓰고 있다면 scratchpad나 외부 todo 도구 없이 텍스트 계획만으로도 충분할 수 있다. 오히려 작은 로컬 모델(예: 7B~13B급)을 쓸 때 scratchpad 기록이 효과적이므로, 모델 크기에 따라 도구 필요성을 판단하라.
- 이 튜토리얼처럼 스크립트 수준의 Agent 코드를 프로덕션에 적용하려면 에러 핸들링, 재시도 정책, Agent 행동 범위 제한(guardrail) 등을 별도로 설계해야 한다. 튜토리얼 코드는 개념 검증(PoC) 용도로만 참고하라.
Terminology
Related Papers
Ask HN: How do you get into a flow state when using AI to code?
Claude 같은 에이전트 기반 AI 코딩 도구가 보편화되면서 개발자들이 기존의 몰입 상태(flow state)를 잃어버리고 있다는 문제를 공유하고, 커뮤니티에서 각자의 대처 방법을 논의한 스레드.
Claude Desktop spawns 1.8 GB Hyper-V VM on every launch, even for chat-only use
Claude Desktop Windows 앱이 사용자가 AI 코드 실행 기능(Cowork)을 쓰지 않아도 실행 시마다 자동으로 1.8GB짜리 Hyper-V 가상머신을 생성해 메모리를 잡아먹는 버그가 보고됐다.
Apache Burr: Build reliable AI agents and applications
LangChain 같은 복잡한 프레임워크에 지친 개발자들을 위해 순수 Python으로 AI 에이전트와 상태 머신을 만들 수 있는 Apache 인큐베이팅 프레임워크다. 상태 관리, 관측성, Human-in-the-Loop 등을 DSL 없이 제공한다는 점이 특징이다.
A €0.01 bank transfer could compromise a banking AI agent
유럽 2위 디지털 뱅크 Bunq의 AI 어시스턴트에서 발견된 간접 프롬프트 인젝션 취약점으로, 단돈 €0.02 송금만으로 사용자에게 피싱 공격을 자동 실행할 수 있었다.
Grit: Rewriting Git in Rust with agents
GitButler 팀이 AI 에이전트 스웜을 활용해 Git을 Rust로 처음부터 재작성한 Grit 프로젝트를 공개했는데, GPL 라이선스 문제와 실용성 논란이 커뮤니티에서 크게 일고 있다.
Show HN: Claw Patrol, a security firewall for agents
AI 에이전트가 실행하는 SQL, kubectl, HTTP 요청을 프록시에서 가로채 HCL 규칙으로 허용/차단/사람 승인 요청을 할 수 있는 오픈소스 보안 게이트웨이. 에이전트가 프로덕션 환경에서 위험한 작업을 실행하기 전에 제어할 수 있어 중요하다.