Part 2: Hands-On Guide

2.5 Planning with Files

요약

모든 중요한 상태를 파일에 써서, 컨텍스트가 날아가도 작업을 이어가는 기법입니다.

제작자
내용: Ahmad Othman Ammar Adi (OthmanAdi/planning-with-files)
영감
내용: Manus의 마크다운 기반 워킹 메모리 패턴
(2025년 12월 Meta에 $2B에 인수)
플러그인
내용: Claude Code Plugin Marketplace
지원 플랫폼
내용: Claude Code, Cursor, Gemini CLI 등 15개 플랫폼
핵심 원리
내용: Context Window = RAM(휘발), Filesystem = Disk(영구)
해결하는 문제
내용: Goal Drift (50회+ 툴 호출 후 원래 목표 망각), 컨텍스트 리셋 후 상태 손실
적합한 작업
내용: 3단계 이상 멀티스텝 작업, 리서치, 장기 프로젝트
적합하지 않은 작업
내용: 단순 질문, 단일 파일 편집, 빠른 조회
한 줄 요약
내용: 중요한 건 죄다 파일에 써라

핵심 메커니즘: 3파일 구조

모든 복잡한 작업에 아래 3개 파일을 생성해 상태를 파일 시스템에 저장합니다.

task_plan.md
역할: 목표/단계 트래커
핵심 내용: 단계별 체크박스, 결정 기록, 에러 로그
findings.md
역할: 조사 결과 보관소
핵심 내용: 웹 검색/파일 탐색 결과를 2회마다 반드시 저장
progress.md
역할: 세션 로그
핵심 내용: 완료 액션, 테스트 결과, 다음 세션 재개 포인트

"Lost in the Middle" 문제

Claude는 극도로 자신감 넘치는 신입 개발자다. 엄청난 기억상실증까지 있어서, 30분 전에 같이 세운 계획을 잊고 엉뚱한 방향으로 달려가는 일이 자주 생긴다.

  • 컨텍스트 앞과 끝은 잘 기억하지만, 중간은 주의력이 분산됨 -- LLM의 구조적 한계
  • 50회+ 툴 호출 후 원래 목표를 망각하는 Goal Drift가 발생하는 이유
  • PreToolUse Hook이 매 결정 전 task_plan.md를 재독 → 목표가 항상 컨텍스트 최신 부분에 올라옴

핵심 철학: "중요한 건 죄다 파일에 써라"

"Markdown is my 'working memory' on disk. Since I process information iteratively and my active context has limits, Markdown files serve as scratch pads for notes, checkpoints for progress, building blocks for final deliverables."
-- Manus AI

Manus AI가 $2B에 인수되며 검증된 패턴입니다.

yaml 
Context Window = RAM  (휘발성, 제한적)
Filesystem     = Disk (영구적, 사실상 무제한)

→ 중요한 것은 무조건 디스크에 쓴다

핵심 규칙

계획 먼저
내용: task_plan.md 없이는 절대 시작하지 않는다
2-Action 규칙
내용: view/browser 작업 2회마다 findings.md에 저장
에러 전부 기록
내용: 같은 실수를 반복하지 않기 위해 모든 실패를 로그
실패 패턴 변경
내용: 같은 방법으로 재시도 금지. 접근법 자체를 바꿀 것

플러그인 설치 및 실행

1
Step 1 / 3

플러그인 설치

Claude Code 실행 후 아래 명령어를 입력합니다.

bash 
# repo 등록
/plugin marketplace add OthmanAdi/planning-with-files
# plugin 설치
/plugin install planning-with-files@planning-with-files
2
Step 2 / 3

플러그인 실행

/planning-with-files:plan
용도: 신규 작업 시작
→ Claude: "어떤 작업인지 설명해주세요"
→ 사용자: "AWS VPC 피어링 설정 및 문서화"
→ Claude가 task_plan.md, findings.md, progress.md 자동 생성
/planning-with-files:status
용도: 현재 완료된 단계, 남은 단계 한눈에 표시
/planning-with-files:start
용도: 새 세션에서 이어하기 (/clear 후 또는 다음날)
3
Step 3 / 3

Hook 자동화 확인

플러그인 설치만 하면 자동으로 동작합니다.

PreToolUse
동작 시점: Write/Edit/Bash 실행 전
역할: task_plan.md 재독으로 목표를 attention window에 갱신
PostToolUse
동작 시점: 파일 작업 완료 후
역할: 단계 상태 업데이트 상기
Stop
동작 시점: 세션 종료 시
역할: 모든 단계 완료 여부 검증 후 종료 허가

vs. Dev Docs System

Dev Docs System도 plan/context/tasks 3파일 구조로 컨텍스트 손실을 막는 검증된 방법입니다. "중요한 상태를 파일로 저장한다"는 핵심 철학은 동일합니다.

설치 방법
Dev Docs System: CLAUDE.md에 수동 지침 추가
Planning with Files: 플러그인 한 줄 설치
Hook 자동화
Dev Docs System: 없음
Planning with Files: PreToolUse / PostToolUse / Stop
findings 강제
Dev Docs System: 개발자가 직접 챙겨야 함
Planning with Files: 2-Action 규칙으로 자동 강제
세션 복구
Dev Docs System: 수동으로 context.md 읽기
Planning with Files: session-catchup.py 자동 복원
완료 검증
Dev Docs System: 없음
Planning with Files: Stop 훅이 자동 체크
포크/커뮤니티
Dev Docs System: 없음
Planning with Files: 활발한 포크 생태계 (multi-manus, plan-cascade 등)
ℹ️ 핵심 차이

Dev Docs는 개발자가 모든 것을 직접 챙기는 "명시적 통제" 방식. planning-with-files는 훅으로 중요한 동작을 자동 강제하는 "시스템 통제" 방식입니다. 실수할 여지를 훅이 막아줍니다.

💡 전환 팁

Dev Docs를 이미 쓰고 있다면 전환은 쉽습니다: 파일 이름만 task_plan.md / findings.md / progress.md로 바꾸고 플러그인 설치하면 끝입니다.