AI 코딩 도구로 복잡한 작업을 진행하다 보면 이런 경험 있으시죠? 처음엔 잘하더니 50번째 작업쯤 되니 원래 목표를 까먹고 엉뚱한 짓을 합니다. 같은 오류를 반복하고, 이미 확인한 내용을 또 찾아보죠. 컨텍스트가 리셋되면 그동안의 진행 상황이 싹 날아가버립니다.
개발자 Ahmad Othman이 만든 오픈소스 도구 Planning with Files는 이 문제를 마크다운 파일 3개로 해결합니다. 흥미로운 건 이 방식이 Meta가 20억 달러에 인수한 AI 에이전트 스타트업 Manus가 사용한 핵심 패턴을 역공학한 것이라는 점이에요. Manus는 8개월 만에 1억 달러 매출을 달성했는데, 그 비결이 바로 “마크다운을 AI의 영구 메모리로 쓰는 컨텍스트 엔지니어링”이었습니다.
출처: Planning with Files – GitHub
AI 에이전트의 고질적 문제
Claude Code나 Cursor 같은 AI 코딩 도구의 가장 큰 약점은 휘발성 메모리입니다. 컨텍스트 윈도우는 제한적이고, 작업이 길어지면 초기 목표를 잊어버리죠. 실패한 시도는 기록되지 않아서 같은 오류를 반복합니다. 모든 정보를 컨텍스트에 우겨넣다 보니 정작 중요한 것에 집중하지 못하고요.
Planning with Files는 이 문제에 대해 명쾌한 해법을 제시합니다.
컨텍스트 윈도우 = RAM (휘발성, 제한적)
파일 시스템 = 디스크 (영구적, 무제한)
→ 중요한 건 전부 디스크에 써라3-파일 패턴의 작동 원리
복잡한 작업을 시작하면 Planning with Files는 자동으로 세 개의 마크다운 파일을 만듭니다.
task_plan.md – 전체 작업을 단계별로 나누고 진행 상황을 체크박스로 표시합니다. 마치 할 일 목록처럼요. AI는 중요한 결정을 내리기 전에 이 파일을 다시 읽어서 원래 목표를 상기합니다.
findings.md – 작업 중 발견한 정보를 저장합니다. 웹에서 찾은 자료, API 문서, 코드 분석 결과 같은 것들이죠. 이걸 컨텍스트에 계속 담고 있으면 금방 한계에 도달하지만, 파일로 빼두면 필요할 때만 불러올 수 있습니다.
progress.md – 각 작업 시도와 결과를 기록합니다. 특히 실패한 시도와 에러 메시지를 남겨서 같은 실수를 반복하지 않게 만들죠.
이 세 파일이 AI의 “외부 두뇌” 역할을 합니다. 컨텍스트 윈도우는 지금 당장 필요한 정보만 담고, 나머지는 파일 시스템에 영구 저장하는 거예요.
Manus가 발견한 핵심 원리
Manus의 창업자 Yichao ‘Peak’ Ji는 자신들의 기술 블로그에서 이렇게 설명했습니다. “마크다운은 디스크에 저장된 나의 작업 메모리입니다. 정보를 반복적으로 처리하고 활성 컨텍스트에는 한계가 있기 때문에, 마크다운 파일은 노트를 위한 스크래치 패드이자 진행 상황의 체크포인트이며 최종 결과물의 빌딩 블록 역할을 합니다.”
특히 흥미로운 건 “주의 조작(attention manipulation)” 기법입니다. AI가 복잡한 작업을 수행할 때 todo.md 파일을 계속 업데이트하고 다시 읽게 만드는데요. 이게 단순히 진행 상황을 기록하는 게 아니라, 전역 목표를 컨텍스트 끝부분에 계속 밀어 넣어서 AI의 주의를 목표에 고정시키는 겁니다. 평균 50번의 도구 호출이 필요한 작업에서 중간에 목표를 잃지 않게 만드는 거죠.
또 하나 중요한 원칙은 “에러를 지우지 말라”는 겁니다. 실패한 시도를 컨텍스트에서 지워버리면 AI는 같은 실수를 반복합니다. 하지만 실패 기록을 남겨두면 AI는 그걸 보고 다른 접근을 시도하죠. Manus 팀은 이 에러 복구 능력이 진정한 에이전트 행동의 핵심 지표라고 봅니다.
실제 사용법
Planning with Files는 Claude Code 플러그인으로 설치할 수 있습니다.
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files설치하면 자동으로 작동합니다. 복잡한 작업을 시작할 때 task_plan.md를 만들고, 파일을 쓸 때마다 상태 업데이트를 알려주며, 작업을 끝내기 전에 모든 단계가 완료됐는지 확인하죠.
수동으로 실행하고 싶다면 /planning-with-files 명령어를 쓰면 됩니다.
언제 쓰면 좋을까요?
- 3단계 이상의 복잡한 작업
- 리서치가 필요한 작업
- 프로젝트 생성이나 대규모 리팩토링
- 여러 파일을 오가며 진행하는 작업
반대로 간단한 질문이나 단일 파일 수정 같은 건 굳이 이 패턴을 쓸 필요가 없습니다.
핵심 규칙 4가지
Planning with Files를 제대로 활용하려면 이 규칙들을 기억하세요.
1. 계획부터 만들어라 – 복잡한 작업은 반드시 task_plan.md부터 시작합니다.
2. 2-작업 규칙 – 파일을 읽거나 브라우저로 정보를 조회하는 작업을 2번 연속으로 하면, 그 결과를 findings.md에 저장합니다. 조회한 내용을 컨텍스트에 계속 담고 있으면 금방 한계에 도달하니까요.
3. 모든 에러를 기록하라 – 실패는 다음 시도를 개선하는 정보입니다.
4. 실패를 반복하지 마라 – 시도를 추적하고, 안 되면 접근법을 바꿉니다.
20억 달러 워크플로우를 내 컴퓨터에
Planning with Files가 보여주는 건 결국 이겁니다. AI 에이전트를 똑똑하게 만드는 비결은 더 큰 모델이 아니라 더 나은 메모리 관리에 있다는 것. Manus가 8개월 만에 1억 달러 매출을 올린 것도, Meta가 20억 달러를 쓴 것도 결국 이 원리 때문이었죠.
이제 누구나 그 방식을 쓸 수 있습니다. 플러그인 하나 설치하면 됩니다. 다음에 Claude Code로 복잡한 작업을 할 때 한번 써보세요. AI가 50번째 작업에서도 처음 목표를 기억하고 있을 겁니다.
참고자료:
답글 남기기