Planning with Files - Manus 방식으로 AI 에이전트 컨텍스트 문제 해결하기

게시 2026/01/18 업데이트 2026/01/18

By Juho

23 분읽는 시간

개요

AI 코딩 도구(Claude Code, Cursor 등)를 사용하다 보면 장시간 작업 중 AI가 초기 목표를 잊어버리거나, 같은 오류를 반복하는 문제를 경험하게 됩니다. 이 글에서는 Meta가 20억 달러에 인수한 AI 에이전트 스타트업 Manus의 핵심 기술인 “마크다운 기반 메모리 관리” 방식을 소개합니다.

Planning with Files는 마크다운 파일 3개만으로 AI 에이전트의 컨텍스트 문제를 해결하는 실용적인 방법론입니다.

AI 에이전트의 컨텍스트 문제

컨텍스트 윈도우의 한계

AI 에이전트는 컨텍스트 윈도우라는 제한된 메모리 공간을 가지고 있습니다. 이 윈도우가 가득 차면 이전 대화 내용을 잊어버리게 됩니다.

발생하는 문제들

장시간 작업을 진행하다 보면 다음과 같은 문제들이 빈번하게 발생합니다.

초기 목표 망각

프로젝트 시작 시 설정한 목표와 요구사항을 시간이 지나면서 점점 잊어버립니다. 결과적으로 원래 의도와 다른 방향으로 작업이 진행될 수 있습니다.

동일 오류 반복

이전에 시도했던 실패한 방법을 기억하지 못하고, 같은 오류를 반복적으로 발생시킵니다. 이로 인해 시간과 토큰이 낭비됩니다.

컨텍스트 리셋 시 진행 상황 소실

세션이 초기화되거나 컨텍스트가 리셋되면 그동안의 진행 상황이 모두 사라집니다. 다시 처음부터 설명해야 하는 비효율이 발생합니다.

Planning with Files란

Planning with Files는 마크다운 파일을 AI의 외부 메모리로 활용하는 방법론입니다. AI의 컨텍스트 윈도우 제한을 극복하기 위해 “디스크에 저장된 작업 메모리”를 사용합니다.

핵심 원리

마크다운 파일은 AI가 쉽게 읽고 쓸 수 있는 형식입니다. 이 파일들을 통해 AI의 주의를 목표에 고정시키고, 에러 기록을 통해 학습 능력을 높입니다.

Manus의 접근 방식

Manus는 이 방식을 통해 8개월 만에 1억 달러 매출을 달성했습니다. 복잡한 기술이 아닌 단순한 마크다운 파일 관리만으로 AI 에이전트의 성능을 크게 향상시켰습니다.

파일 시스템을 Ultimate Context로 활용

Manus의 핵심 통찰은 파일 시스템을 “Ultimate Context”로 활용한다는 점입니다.

RAM vs 영구 저장소 비유

컨텍스트 윈도우를 컴퓨터의 RAM에 비유할 수 있습니다. RAM은 빠르지만 휘발성이고 용량이 제한적입니다. 반면 파일 시스템은 영구 저장소로서 무제한 크기와 지속성을 갖습니다.

파일 시스템의 장점

파일 시스템을 외부 메모리로 활용하면 다음과 같은 이점이 있습니다.

무제한 크기의 저장 공간
세션 간 정보 영속성 보장
AI 에이전트가 직접 읽고 쓸 수 있는 구조화된 형식
컨텍스트 압축으로 인한 정보 손실 방지

가역적 압축 원칙

Manus는 “가역적 압축”이라는 원칙을 따릅니다. 웹 페이지 내용은 URL만 유지하면 언제든 다시 가져올 수 있습니다. 문서 내용은 파일 경로만 보존하면 샌드박스 환경에서 접근 가능합니다. 이렇게 복원 가능한 형태로 압축하면 정보 손실을 방지할 수 있습니다.

3-파일 패턴 상세

Planning with Files의 핵심은 3개의 마크다운 파일입니다.

task_plan.md

작업의 전체 계획과 진행 상황을 관리하는 파일입니다.

역할

단계별 작업 계획 수립
체크리스트 형태로 진행 상황 추적
현재 목표를 AI에게 지속적으로 상기

예시 형식

  
# Task Plan

## 목표
사용자 인증 시스템 구현

## 단계
- [x] 1. 데이터베이스 스키마 설계
- [x] 2. 사용자 모델 구현
- [ ] 3. 로그인 API 개발
- [ ] 4. 토큰 기반 인증 구현
- [ ] 5. 테스트 작성

## 현재 작업
3단계: 로그인 API 개발 진행 중

findings.md

리서치 결과와 발견한 정보를 영구 저장하는 파일입니다.

역할

조사한 내용 기록
중요한 발견 사항 저장
반복되는 정보 참조용으로 활용

예시 형식

  
# Findings

## 기술 스택 조사
- JWT 라이브러리: PyJWT 권장
- 비밀번호 해싱: bcrypt 사용

## 코드베이스 분석
- 기존 인증 코드 위치: src/auth/
- 사용 중인 ORM: SQLAlchemy

## 참고 자료
- JWT 공식 문서: https://jwt.io/

progress.md

시도한 작업, 결과, 에러를 기록하는 파일입니다.

역할

시도한 방법과 결과 기록
에러 메시지와 해결 과정 저장
실패한 시도 반복 방지

예시 형식

  
# Progress Log

## 2026-01-20

### 시도 1: bcrypt 직접 설치
- 명령어: pip install bcrypt
- 결과: 실패
- 에러: Microsoft Visual C++ 14.0 required
- 해결: conda install bcrypt로 변경하여 성공

### 시도 2: JWT 토큰 생성
- 결과: 성공
- 참고: secret key는 환경변수에서 로드

3-파일 패턴 요약

파일명	목적	주요 내용
task_plan.md	계획 관리	단계별 체크리스트, 현재 목표
findings.md	정보 저장	조사 결과, 발견 사항
progress.md	진행 기록	시도 내역, 에러, 해결 방법

5가지 핵심 규칙

Planning with Files를 효과적으로 사용하기 위한 5가지 규칙입니다.

규칙 1: 계획 먼저 작성 (Plan First)

작업을 시작하기 전에 반드시 task_plan.md에 계획을 먼저 작성합니다. 명확한 계획 없이 시작하면 목표에서 벗어나기 쉽습니다. task_plan.md 없이는 어떤 복잡한 작업도 시작하지 않습니다.

규칙 2: 2-액션 규칙 (2-Action Rule)

매 2번의 조회/브라우저 작업 후에는 반드시 findings.md에 발견한 내용을 저장합니다. 웹 검색이나 파일 탐색 등을 2번 수행하면 그 결과를 즉시 기록합니다. 이를 통해 정보가 컨텍스트에서 사라지기 전에 영구 저장합니다.

규칙 3: 모든 것을 기록 (Log Everything)

발생한 모든 에러와 해결 과정을 progress.md에 기록합니다. 성공한 시도와 실패한 시도 모두 기록하여 학습 데이터로 활용합니다. 이를 통해 같은 실수를 반복하지 않고, 문제 해결 속도를 높입니다.

규칙 4: 실패 시 변형 (Mutate on Failure)

progress.md에 기록된 실패한 방법을 다시 시도하지 않습니다. 같은 방식으로 실패한 접근법은 반드시 다른 방식으로 변형해야 합니다. AI가 이 파일을 확인하고 새로운 접근 방식을 선택하도록 합니다.

규칙 5: 완료 전 검증 (Verify Before Stopping)

작업을 완료하기 전에 task_plan.md의 모든 체크리스트를 확인합니다. 미완료 항목이 있으면 작업을 멈추지 않습니다. 완료 여부를 명시적으로 검증하여 누락을 방지합니다.

Manus의 컨텍스트 엔지니어링 기법

Manus가 공개한 컨텍스트 엔지니어링의 핵심 기법들을 소개합니다.

KV-Cache 최적화

Manus에서 가장 중요하게 여기는 지표는 “KV-cache hit rate”입니다. 프로덕션 AI 에이전트에서 입력 대 출력 토큰 비율은 약 100:1입니다. 캐시 효율성이 직접적으로 지연 시간과 비용에 영향을 미칩니다.

접두사 안정성 (Prefix Stability)

KV-cache를 최대한 활용하려면 접두사를 안정적으로 유지해야 합니다.

시스템 프롬프트에 타임스탬프(특히 초 단위)를 넣지 않습니다.
JSON 키 순서를 언어와 라이브러리 간에 일관되게 유지합니다.
반복 실행 시 결정론적 직렬화를 보장합니다.

액션 스페이스 관리

도구 정의를 동적으로 변경하면 KV-cache가 무효화됩니다.

반복 중간에 도구를 동적으로 제거하지 않습니다.
대신 토큰 로짓을 마스킹하여 특정 액션을 제한합니다.
응답 프리필링을 사용하여 컨텍스트 수정 없이 액션을 제한합니다.

주의(Attention) 조작

AI 모델의 주의를 목표에 고정시키는 기법입니다.

todo.md와 같은 작업 목록을 지속적으로 재생성합니다.
이를 통해 목표가 “모델의 최근 주의 범위” 내에 유지됩니다.
반복 작업에서 패턴 모방을 방지하기 위해 통제된 변형을 도입합니다.

에러 처리 철학

실패한 액션과 에러 트레이스를 컨텍스트에 유지합니다. 에러를 정리하거나 숨기지 않습니다. 모델은 실패한 시도와 그 결과를 관찰하면서 내부 신념을 암묵적으로 업데이트합니다. 에러 복구 능력은 “진정한 에이전트 행동의 가장 명확한 지표”입니다.

언제 사용해야 하는가

Planning with Files는 모든 작업에 필요한 것은 아닙니다.

사용이 권장되는 경우

다음 상황에서는 Planning with Files를 적용하는 것이 효과적입니다.

3단계 이상의 복잡한 작업
리서치 프로젝트
새로운 기능 개발이나 생성 작업
50회 이상의 도구 호출이 예상되는 작업
여러 세션에 걸쳐 진행되는 장기 프로젝트

사용이 불필요한 경우

다음 상황에서는 오버헤드만 추가될 수 있습니다.

단순한 질문에 대한 답변
단일 파일 수정
빠른 정보 조회
1-2단계로 완료되는 간단한 작업

Manus의 성공 사례

Meta의 20억 달러 인수

Manus는 이 단순한 마크다운 기반 메모리 관리 방식을 핵심 기술로 삼아 빠르게 성장했습니다. 결국 Meta에 20억 달러에 인수되었습니다.

8개월 만에 1억 달러 매출

복잡한 기술 스택이 아닌 효과적인 컨텍스트 관리만으로 8개월 만에 1억 달러 매출을 달성했습니다. 이는 AI 에이전트 분야에서 컨텍스트 관리의 중요성을 보여주는 사례입니다.

핵심 성공 요인

Manus의 성공은 다음 요인들에 기인합니다.

AI의 주의를 목표에 고정시키는 명확한 계획 관리
에러 기록을 통한 학습 능력 향상
세션 간 정보 유지를 통한 연속성 확보

실제 적용 방법

Claude Code에서 사용하기

Claude Code에서는 플러그인 형태로 Planning with Files를 자동 실행할 수 있습니다.

플러그인 설치

Claude Code의 마켓플레이스를 통해 플러그인을 설치할 수 있습니다.

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

현재 버전: v2.1.2

플러그인 자동 동작

설치 후 플러그인은 자동으로 다음 작업을 수행합니다.

복잡한 작업 시작 전 task_plan.md 생성
PreToolUse 훅을 통해 주요 결정 전 계획 재확인
PostToolUse 훅을 통해 파일 작성 후 상태 업데이트 알림
에러 발생 시 자동 기록
Stop 훅을 통해 완료 전 검증

수동 설정 방법

플러그인 없이 수동으로 설정하는 방법입니다.

프로젝트 루트에 .planning/ 디렉토리 생성
task_plan.md, findings.md, progress.md 파일 생성
AI에게 이 파일들을 참조하도록 지시

프롬프트 예시

작업을 시작하기 전에 .planning/task_plan.md에 계획을 작성해주세요.
조사한 내용은 .planning/findings.md에 저장하고,
에러가 발생하면 .planning/progress.md에 기록해주세요.

Cursor에서 사용하기

Cursor에서도 동일한 방식으로 적용할 수 있습니다.

Rules 설정

Cursor의 Rules 기능을 활용하여 AI가 자동으로 3-파일 패턴을 따르도록 설정합니다. .cursor/rules/planning-with-files.mdc 파일에 Planning with Files 규칙을 추가합니다.

Cursor Rules 예시

# Planning with Files Rules

## 작업 시작 전
- task_plan.md에 단계별 계획을 먼저 작성합니다.
- 계획 없이 복잡한 작업을 시작하지 않습니다.

## 리서치 중
- 2번의 조회 작업 후 findings.md에 결과를 저장합니다.
- 중요한 발견은 즉시 기록합니다.

## 작업 중
- 모든 시도와 결과를 progress.md에 기록합니다.
- 에러 발생 시 에러 메시지와 해결 과정을 기록합니다.
- 실패한 방법은 다시 시도하지 않고 변형합니다.

## 작업 완료 전
- task_plan.md의 모든 체크리스트를 확인합니다.
- 미완료 항목이 있으면 작업을 멈추지 않습니다.

일반적인 워크플로우

새 작업 시작 시 task_plan.md에 계획 작성
리서치 진행 시 findings.md에 결과 기록 (2-액션 규칙 적용)
작업 진행 중 progress.md에 시도 내역 기록
에러 발생 시 progress.md에 에러와 해결 과정 기록
단계 완료 시 task_plan.md 체크리스트 업데이트
완료 전 모든 체크리스트 검증

결론

Planning with Files는 복잡한 기술이 아닌 단순한 마크다운 파일 관리만으로 AI 에이전트의 컨텍스트 문제를 해결하는 실용적인 방법론입니다.

핵심 아이디어는 파일 시스템을 “Ultimate Context”로 활용하는 것입니다. 컨텍스트 윈도우가 휘발성 RAM이라면, 파일 시스템은 무제한 용량의 영구 저장소입니다.

3개의 마크다운 파일(task_plan.md, findings.md, progress.md)을 활용하여 AI의 외부 메모리를 구축합니다. 5가지 핵심 규칙을 따르면 장시간 작업에서도 일관된 품질을 유지할 수 있습니다.

Manus가 공개한 컨텍스트 엔지니어링 기법들(KV-Cache 최적화, 접두사 안정성, 에러 처리 철학 등)은 대규모 AI 에이전트 시스템의 실전 노하우를 담고 있습니다. 이러한 기법들과 함께 Planning with Files를 적용하면 AI 에이전트의 성능을 크게 향상시킬 수 있습니다.

Manus가 이 방식으로 8개월 만에 1억 달러 매출을 달성하고 Meta에 20억 달러에 인수된 사례는 컨텍스트 관리의 중요성을 잘 보여줍니다. Claude Code, Cursor 등 AI 코딩 도구를 사용하는 개발자라면 이 방법론을 적용해보는 것을 권장합니다.

마크다운 파일 3개로 컨텍스트 엔지니어링 효과를 얻을 수 있다는 점에서 투자 대비 효과가 매우 높은 방법입니다.

참고 자료

Manus

AI LLM Agent Productivity

목차

개요

AI 에이전트의 컨텍스트 문제

컨텍스트 윈도우의 한계

발생하는 문제들

초기 목표 망각

동일 오류 반복

컨텍스트 리셋 시 진행 상황 소실

Planning with Files란

핵심 원리

Manus의 접근 방식

파일 시스템을 Ultimate Context로 활용

RAM vs 영구 저장소 비유

파일 시스템의 장점

가역적 압축 원칙

3-파일 패턴 상세

task_plan.md

역할

예시 형식

findings.md

역할

예시 형식

progress.md

역할

예시 형식

3-파일 패턴 요약

5가지 핵심 규칙

규칙 1: 계획 먼저 작성 (Plan First)

규칙 2: 2-액션 규칙 (2-Action Rule)

규칙 3: 모든 것을 기록 (Log Everything)

규칙 4: 실패 시 변형 (Mutate on Failure)

규칙 5: 완료 전 검증 (Verify Before Stopping)

Manus의 컨텍스트 엔지니어링 기법

KV-Cache 최적화

접두사 안정성 (Prefix Stability)

액션 스페이스 관리

주의(Attention) 조작

에러 처리 철학

언제 사용해야 하는가

사용이 권장되는 경우

사용이 불필요한 경우

Manus의 성공 사례

Meta의 20억 달러 인수

8개월 만에 1억 달러 매출

핵심 성공 요인

실제 적용 방법

Claude Code에서 사용하기

플러그인 설치

플러그인 자동 동작

수동 설정 방법

프롬프트 예시

Cursor에서 사용하기

Rules 설정

Cursor Rules 예시

일반적인 워크플로우

결론

참고 자료

인기 태그