Planning with Files: Markdown 파일을 에이전트의 작업 기억으로 사용하는 Manus의 동작 방식을 Claude에 적용한 Skill

9bow · 1월 15, 2026, 3:30오전

Planning with Files 프로젝트 소개

Planning with Files는 Claude Code 환경에서 실행되는 오픈소스 스킬(Skill)로, AI 에이전트가 복잡한 작업을 수행할 때 '기억 상실'이나 '목표 이탈'을 방지하기 위해 설계된 워크플로우 구현체입니다.

Planning with Files 프로젝트는 최근 메타(Meta)가 $2B 가치로 인수하며 주목받은 AI 스타트업 Manus의 에이전트 동작 방식을 역공학(Reverse-engineering)하여 구현했다고 알려져 화제를 모았습니다. Planning with Files의 핵심 아이디어는 마크다운(Markdown) 파일을 에이전트의 작업 기억(Working Memory)으로 사용하는 것입니다.

일반적인 AI 에이전트는 도구 사용(Tool Use)이 반복되면 컨텍스트 창(Context Window)이 길어져 초기 목표를 잊거나, 불필요한 정보로 인해 성능이 저하되는 문제가 발생합니다. 이해 비해, Planning with Files는 이러한 문제를 해결하기 위해 에이전트의 상태, 계획, 연구 노트를 메모리가 아닌 plan.md나 notes.md 등과 같은 물리적인 파일에 기록하고 관리하게 합니다. 이를 통해 에이전트는 장기적인 목표를 유지하면서도 컨텍스트를 효율적으로 관리할 수 있습니다.

Planning with Files와 Claude Code의 기본 Plan Mode 비교

특징	Claude Code 기본 Plan Mode	Planning with Files 프로젝트
저장 방식	일시적, 혹은 숨겨진 폴더에 저장됨	사용자가 볼 수 있는 루트 경로의 명시적 파일 (`.md`)
접근성	에이전트 내부 상태에 가까움	사용자가 직접 수정/개입하기 매우 용이함
컨텍스트 관리	대화 기록(Context History)에 의존적	파일(`notes.md`)로 분리하여 메인 컨텍스트 절약
지속성	세션 종료 시 정보가 휘발될 수 있음	프로젝트 파일로 남아있어 세션이 바뀌어도 유지됨

Planning with Files 프로젝트는 단순히 계획을 세우는 것을 넘어, 파일 시스템을 '외부 뇌(External Brain)'로 활용함으로써 에이전트의 추론 능력을 보조하는 강력한 패턴입니다.

Planning with Files의 주요 특징

Planning with Files 프로젝트의 핵심은 에이전트가 행동하기 전후에 강제로 특정 파일을 참조하고 업데이트하도록 만드는 훅(Hook) 시스템과 파일 구조에 있습니다.

3가지 핵심 파일 구조

에이전트는 모든 상태를 종류에 따라 다음 3가지 파일에 나누어 저장합니다:

plan.md (또는 task_plan.md): 전체 프로젝트의 로드맵과 현재 진행 상황을 추적합니다. 체크박스 형태로 작업의 완료 여부를 관리합니다.
notes.md: 연구 내용, 검색 결과, 임시 데이터를 저장합니다. 에이전트의 메인 컨텍스트를 오염시키지 않고 필요한 정보만 따로 보관하는 '스크래치 패드' 역할을 합니다.
history.md: 수행한 작업의 로그를 남겨 에이전트가 과거의 실수를 반복하지 않도록 돕습니다. 이 파일은 선택적으로 사용하거나 사용하지 않을 수 있습니다.

자동화된 훅 (Hooks) 시스템

Planning with Files 프로젝트는 Claude Code의 확장 기능을 활용하여 에이전트의 행동 패턴을 제어합니다. 다음과 같은 Claude Code에서 제공하는 훅(Hook)들을 사용합니다.

SessionStart Hook: 세션이 시작될 때 현재 진행 상황을 요약하여 알려줍니다.
PreToolUse Hook: 에이전트가 코드를 작성하거나 터미널 명령을 실행하기(Write, Edit, Bash 등) 직전에 자동으로 plan.md를 다시 읽게 합니다. 이는 에이전트가 "지금 내가 무엇을 위해 이 명령을 실행하는가?"를 상기하게 만들어 목표 이탈을 막습니다.
PostToolUse Hook: 작업이 완료된 후 상태를 업데이트하도록 유도합니다.
Stop Hook: 모든 단계가 완료되지 않았다면 세션 종료를 막습니다.

라이선스

Planning with Files 프로젝트는 MIT 라이선스로 배포되고 있습니다. 상업적인 용도로 사용 및 재배포가 가능하며, 상세한 내용은 라이선스 원문을 참고해주세요.

planning-with-files 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~