처음부터 만드는 기본 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

관련 논문

• AI로 코딩할 때 Flow State(몰입 상태)를 유지하는 방법

  Claude 같은 에이전트 기반 AI 코딩 도구가 보편화되면서 개발자들이 기존의 몰입 상태(flow state)를 잃어버리고 있다는 문제를 공유하고, 커뮤니티에서 각자의 대처 방법을 논의한 스레드.

• Claude Desktop, 채팅만 해도 실행할 때마다 1.8GB Hyper-V VM을 띄운다

  Claude Desktop Windows 앱이 사용자가 AI 코드 실행 기능(Cowork)을 쓰지 않아도 실행 시마다 자동으로 1.8GB짜리 Hyper-V 가상머신을 생성해 메모리를 잡아먹는 버그가 보고됐다.

• Apache Burr: 신뢰할 수 있는 AI 에이전트 빌드 프레임워크

  LangChain 같은 복잡한 프레임워크에 지친 개발자들을 위해 순수 Python으로 AI 에이전트와 상태 머신을 만들 수 있는 Apache 인큐베이팅 프레임워크다. 상태 관리, 관측성, Human-in-the-Loop 등을 DSL 없이 제공한다는 점이 특징이다.

• €0.01 송금 한 번으로 뱅킹 AI 에이전트를 해킹하는 방법

  유럽 2위 디지털 뱅크 Bunq의 AI 어시스턴트에서 발견된 간접 프롬프트 인젝션 취약점으로, 단돈 €0.02 송금만으로 사용자에게 피싱 공격을 자동 실행할 수 있었다.

• Grit: AI 에이전트로 Git을 Rust로 처음부터 재작성하기

  GitButler 팀이 AI 에이전트 스웜을 활용해 Git을 Rust로 처음부터 재작성한 Grit 프로젝트를 공개했는데, GPL 라이선스 문제와 실용성 논란이 커뮤니티에서 크게 일고 있다.

• Claw Patrol: AI 에이전트를 위한 보안 방화벽

  AI 에이전트가 실행하는 SQL, kubectl, HTTP 요청을 프록시에서 가로채 HCL 규칙으로 허용/차단/사람 승인 요청을 할 수 있는 오픈소스 보안 게이트웨이. 에이전트가 프로덕션 환경에서 위험한 작업을 실행하기 전에 제어할 수 있어 중요하다.

Related Resources

• 원문: Build a Basic AI Agent from Scratch: Long Task Planning