TL;DR

planning-with-files는 task_plan.md, findings.md, progress.md의 세 파일을 디스크에 영구 저장해 에이전트의 컨텍스트 손실과 /clear, 크래시 상황에서도 계획과 진행 상태를 복구하는 스킬이다. 각 턴 시작과 훅 트리거 시 파일을 재주입하고 PostToolUse·Stop 훅으로 상태 동기화와 완료 검증을 수행하며 v3에서는 완료 게이트, append-only JSONL 레저, SHA-256 기반 attestation을 도입해 병렬 세션과 무결성을 관리한다. README가 제시한 v2.21.0 평가에서는 파일 패턴 준수율 96.7%를 보고했으며 설치는 SKILL.md 표준을 통해 60개 이상의 에이전트에 걸쳐 이루어진다. 이 접근은 기억 회수를 담당하는 벡터 저장소와는 역할을 분리해 계획의 연속성에 집중하지만, 평가 수치는 파일 패턴 준수에 국한되고 장기적인 목표 달성률은 별도 검증이 필요하다.

주요 기능

• 자동으로 task_plan.md, findings.md, progress.md 파일을 생성하고 프로젝트 디렉터리에 지속적으로 기록한다. 설치 후 에이전트는 파일을 읽고 쓰며 진행 상태와 발견 사항을 디스크에 보존한다. 결과적으로 컨텍스트 제한이나 크래시가 발생해도 계획이 유지된다.
• 각 IDE와 런타임의 훅을 통해 계획을 재주입하고 세션을 복구하는 동작을 제공한다. PreToolUse, PostToolUse, Stop 같은 훅이 활성화되면 에이전트가 주요 결정 전에 최신 플랜을 다시 로드하고 쓰기 후 상태를 동기화한다. 이 동작은 컨텍스트 로스와 /clear 이후에도 목표와 단계 상태를 모델의 주의창에 유지하게 한다.
• 옵션형 완료 검증과 append-only JSONL 레저를 제공해 장기 실행에서 상태 추적과 결정 차단을 구현한다. gated 모드는 Stop 훅과 다수의 검사 조건을 결합해 플랜이 실제 완료될 때까지 세션의 자동 종료를 방지한다. v3에서 도입된 레저와 SHA 캐시, nonce 구분자가 병렬 세션 환경에서 일관성을 높였다.
• SKILL.md 표준을 통해 60개 이상 에이전트와 호환되어 다양한 IDE에서 동일한 설치 및 훅 통합을 지원한다. README와 다수의 IDE별 SKILL.md 변종을 통해 Claude Code, Codex, Cursor, GitHub Copilot, Kiro, OpenCode 등에서 동작하도록 구성되어 있다. 이식성 확보를 위해 각 IDE별 훅 스크립트와 PowerShell 등 플랫폼별 대체 스크립트를 포함한다.

어떻게 동작하는가

스킬은 세 가지 파일(task_plan.md, findings.md, progress.md)에 현재 작업의 단계와 발견사항, 세션 로그를 영구 저장한다. 각 턴의 시작이나 훅 트리거 시 파일을 다시 읽어 모델 입력에 플랜을 주입하며 Stop 훅과 체크스크립트(check-complete.sh 등)를 통해 단계별 완료 여부를 검증한다. v3에서는 append-only JSONL 런 레저와 SHA-256 기반 attestation, autonomous/gated 모드를 도입해 재현성·무결성·차단 정책을 관리한다.

해결 문제

에이전트가 컨텍스트 윈도우 한계나 /clear로 인해 진행 중인 작업을 잃는 문제를 해결한다. 파일 기반의 영구 저장으로 목표·진행·오류 로그를 디스크에 보존해 세션 복구와 목표 일관성을 확보한다. 또한 실행 도중 발생한 오류를 기록해 같은 실패가 반복되지 않도록 상태를 남긴다.

지금 주목받는 이유

이 스킬은 Manus 스타일의 영구 마크다운 기반 계획 패턴을 채택해 빠르게 확산되었고 README가 60개 이상의 에이전트 호환성과 v3의 완료 게이트를 강조하면서 주목을 받았다. 저장소의 높은 스타 수와 다수의 포크 및 커뮤니티 확장 사례가 인용되어 널리 채택된 증거를 제공한다. 또한 README에서 v2.21.0 기준 96.7%의 파일 패턴 준수 벤치마크를 제시해 실무 신뢰도를 보였다.

차별점

• 전통적 메모리 도구(벡터 DB 등)와 달리 active execution state를 파일로 관리해 플랜의 단계·의존성·완료 검증을 우선한다. README는 이 접근을 기억 회수용 메모리와 구분하여 '계획 연속성'을 해결하는 것으로 규정했다. 따라서 검색 기반 기억장치와 보완적으로 동작하도록 설계되었다.
• SKILL.md 표준과 다수 IDE용 훅 구현으로 한 번의 설치로 Claude Code, Codex, Cursor, GitHub Copilot 등 60개 이상 런타임에 걸쳐 동일한 동작을 제공한다. README에는 각 IDE별 설치·훅 구성 예시와 IDE별 스크립트 동기화 이력이 상세히 포함되어 있다. 이식성과 런타임 호환성 측면에서 확장성이 차별점으로 드러난다.
• v3에서 도입된 gated 모드와 append-only JSONL 런 레저, SHA 캐시 기반 attestation은 장기·병렬 실행 환경에서 무결성과 차단 정책을 구현한다. README는 gated 모드의 차단 조건과 레저 명령(ledger-append 등)을 기술하며 변경 불가능한 기록과 검증 가능한 완료 상태를 강조했다. 이 메커니즘은 단순 파일 쓰기 이상의 실행 보장 장치를 제공한다.

사용 사례

• 여러 단계로 구성된 장기 작업에서 진행 상태와 검증 조건을 보존하는 데 사용된다. 에이전트가 수십 회의 도구 호출 후에도 원래 목표와 단계 상태를 잃지 않도록 파일을 통해 반복적으로 플랜을 재주입한다. 이 방식은 배포 전 단계 검증이나 대규모 리팩터링 같은 연속 작업에 적합하다.
• 조사·리서치 작업에서 발견사항과 증거를 findings.md에 누적해 컨텍스트 창을 넘는 지식을 유지하는 데 쓰인다. 에이전트가 웹 조회나 실험 결과를 즉시 컨텍스트에 쌓지 않고 파일에 기록하므로 재현성 있는 조사 로그를 확보한다. 결과적으로 추후 검토와 감사에 필요한 기록을 일관되게 유지한다.
• 멀티에이전트 협업이나 병렬 세션에서 충돌을 줄이고 상태를 동기화하는 데 활용된다. append-only JSONL 런 레저와 attestation은 병렬 실행 시 발생할 수 있는 교착과 변조 문제를 경감한다. README는 multi-manus-planning 등 커뮤니티 확장 사례를 통해 멀티 프로젝트·다중 에이전트 활용 예시를 제시했다.

시작하기

공식 빠른 설치 명령은 npx를 통한 SKILL.md 표준 설치이며 한 줄로 스킬을 전역 등록한다. 설치 후 각 IDE의 설치 가이드나 Claude Code 전용 플러그인 설치 절차를 따라 훅과 명령 자동 등록을 활성화하면 된다. 로컬 수동 설치가 필요한 경우 README에 제시된 cp 또는 Copy-Item 명령을 사용해 스킬을 사용자 스킬 디렉터리로 복사하면 prefix 없이 호출 가능하다.

요구사항

• 레포지토리는 주로 Python 코드와 POSIX·PowerShell 훅 스크립트를 포함하므로 유사한 런타임 환경과 셸 실행 권한이 필요하다. README는 POSIX 호환 쉘과 Windows PowerShell 양쪽을 위한 스크립트 변형을 제공해 호환성을 확보했다. 특정 IDE 통합은 해당 IDE의 SKILL.md나 훅 인터페이스를 지원해야 하므로 설치 전 대상 IDE의 훅 지원 여부를 확인해야 한다.

벤치마크