본문으로 건너뛰기
에이전트 Skills 전체 목록

Planning with Files

  • 추천0
  • GitHub 별28K
  • 개발라이선스MIT

task_plan·findings·progress 3파일을 디스크에 두고 훅으로 매 턴 주입해, /clear·압축·충돌 뒤에도 계획을 이어 가는 스킬

원본:OthmanAdi/planning-with-files

요약

task_plan·findings·progress 3파일을 디스크에 두고 훅으로 매 턴 주입해, /clear·압축·충돌 뒤에도 계획을 이어 가는 스킬

설명

Planning with Files

PWF: 모든 작업, 모든 단계. 아치 아래 황동 받침 위에 놓인 계획 파일 세 개

에이전트가 무시할 수 없는 계획 스킬. 따를지 말지 모르는 프롬프트가 아닙니다. 매 턴 실행되는 훅, /clear 뒤에도 남는 디스크 위의 계획, 그리고 블라인드 A/B 3전 3승이 효과를 보여 줍니다.

에이전트의 컨텍스트 창은 사라져도 계획은 남습니다.

AI 코딩 에이전트와 장시간 에이전트 작업을 위한 파일 기반 계획 스킬입니다. task_plan.md, findings.md, progress.md를 디스크에 두고, 활성화된 수명 주기 훅이 프로젝트 계획 맥락을 골라 주입합니다. 그래서 컨텍스트 손실, /clear, 충돌, 압축을 거쳐도 계획이 살아남습니다. 자동 복구는 프로젝트 파일만 읽습니다. 같은 프로젝트의 로컬 에이전트 세션 기록을 읽어 집계 수를 내거나 제한된 재생을 하려면 명시적인 catchup 모드가 필요합니다. Agent Skills 표준으로 60개 이상의 에이전트에 설치할 수 있고, Claude Code · Codex CLI · Qoder CLI · Pi · Hermes Agent · OpenCode · DeepSeek Harness용 네이티브 플러그인이 있습니다.

후원 · 지원

  • Scrape.ly: 에이전트는 계획을 지키고, Scrape.ly는 웹 데이터를 가져옵니다.
  • Swiftproxy: 브라우저 자동화를 위한 주거용 프록시.
  • CodeRabbit의 오픈소스 프로그램이 코드 리뷰를 지원합니다.

기여자

코드 · 문서 · 이슈 기여자 목록은 CONTRIBUTORS.md에 있습니다.

포크와 확장

포크작성자만든 것
devis@st01cs인터뷰 우선 워크플로우, /devis:intv · /devis:impl 명령, 확실한 활성화
multi-manus-planning@kmichels다중 프로젝트 지원, SessionStart git 동기화
plan-cascade@Taoidle다단계 작업 오케스트레이션, 병렬 실행, 멀티 에이전트 협업
agentfund-skill@RioTheGreat-ai마일스톤 에스크로 기반 AI 에이전트 크라우드펀딩(Base)
openclaw-github-repo-commander@wd041216-bitOpenClaw용 7단계 GitHub 저장소 감사 · 최적화 · 정리 워크플로우
planning-with-sysspec@tianshan모듈 명세 · 명세 델타 · 검증 매트릭스를 더한 명세 우선 확장

실제 사용 사례

프로젝트설명
lincolnwan/Planning-with-files-copilot-agentplanning-with-files 스킬을 중심으로 만든 Copilot 에이전트 저장소
cooragent/ClarityFinanceAI 금융 에이전트 프레임워크, Planning-with-Files 방식을 직접 인용
oeftimie/vv-claude-harnessManus 방식의 영속 마크다운 계획 위에 만든 Claude Code 하니스
jessepwj/CCteam-creator파일 기반 계획을 쓰는 멀티 에이전트 팀 오케스트레이션 스킬
smallnest/langgraphgo: Manus Agent영속 작업 계획 · 조사 노트 · 산출물 파일을 갖춘 planning-with-files 패턴의 Go 구현
a5c-ai/babysitterplanning-with-files에서 가져온 계획 · 실행 · 세션 복구 · 검증 프로세스

만든 것이 있나요? 이슈를 열면 목록에 올려 드립니다.

빠른 설치

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

모든 설치 방법은 docs/installation.md에 있습니다.

/clear 전과 후

모든 코딩 에이전트는 컨텍스트 창이 초기화되면 작업 기억을 잃습니다. 하지만 계획까지 함께 사라질 필요는 없습니다.

일러스트 워크플로우: 컨텍스트가 초기화돼도 계획 파일이 작업 상태를 보존한다

장시간 에이전트 작업을 위해

💡 대부분의 하니스는 컨텍스트 창 안에 사는 할 일 목록을 제공합니다. planning-with-files는 디스크에 있고, 매 턴 다시 주입되고, 해시로 증명되고, 계획이 완료로 보고될 때까지 에이전트의 멈춤을 붙잡아 둘 수 있는 계획을 제공합니다.

이것이 /clear, 압축, 충돌 뒤에 잊어버리는 에이전트와 현재 단계에서 다시 시작하는 에이전트의 차이입니다. 프로젝트 자체 측정에서 디스크의 계획은 13.3턴이 걸리던 재정렬을 5.0턴으로 줄였고, 블라인드 A/B 비교 3번 모두 이겼습니다. 아래의 모든 장치는 파일과 훅 하나이므로 10시간째에도 첫 턴과 똑같이 동작합니다.

3파일 패턴

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

→ Anything important gets written to disk.

스킬은 계획 · 조사 결과 · 진행 상황을 프로젝트 안에 둡니다.

your-project/
├── task_plan.md   ← phases + checkboxes; the resume point after /clear
├── findings.md    ← research notes and decisions, appended as you go
└── progress.md    ← session log and test results

병렬 작업은 대신 .planning/YYYY-MM-DD-slug/ 격리 디렉터리에 같은 세 파일을 두고 .active_plan으로 선택합니다(v2.36.0 이상). 일반 마크다운이며 기본으로 gitignore 처리되고, 그 밖에 런타임 상태는 어디에도 없습니다.

이 패턴은 Manus가 Meta에 인수되기 전에 설명한 방식입니다(2025년 12월 29일, 약 20억 달러, 출시 8개월 · 매출 1억 달러 이상).

"마크다운은 나의 디스크 위 '작업 기억'이다. 나는 정보를 반복해서 처리하고 활성 컨텍스트에는 한계가 있으므로, 마크다운 파일이 메모장, 진행 체크포인트, 최종 산출물의 구성 요소 역할을 한다." — Manus AI

1급 호스트: 네이티브 플러그인

💡 네이티브 통합은 계획 맥락을 불러오고, 진행 알림을 주고, 완료 게이트를 지원합니다. 명령과 모델 호출 도구는 호스트에 따라 다르며, Qoder CLI는 Claude 전용 명령 프롬프트 없이 스킬과 수명 주기 훅을 불러옵니다.

5개 다른 언어

번역은 설명만 번역한 것이 아니라 SKILL.md 본문 · 템플릿 · check-complete · init-session · session-catchup의 출력까지 모두 현지화돼 있습니다. 상태 토큰(**Status:** complete)은 check-complete.sh가 grep -F로 비교하므로 일부러 영어 그대로 둡니다. 번역하면 완료 게이트가 꺼집니다.

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-ar -g

-ar(아랍어) · -de(독일어) · -es(스페인어) · -zh(중국어 간체) · -zht(중국어 번체)를 같은 방식으로 설치합니다. v3.10.0부터 변형본도 전체 스크립트(증명 · Stop 게이트 · 원장 · 단계 상태 · plan-doctor)를 함께 제공합니다. 자세한 내용은 docs/languages.md에 있습니다.

IDE별 설정 안내

IDE통합 방식
Claude Code플러그인 + SKILL.md + 훅
Cursor스킬 + hooks.json
GitHub Copilot훅(errorOccurred 포함)
Mastra Code스킬 + 훅
Gemini CLI스킬 + 훅
KiroAgent Skills
Codex스킬 + 훅
Qoder CLI스킬 + 수명 주기 훅 7개, Bash와 Python 3.10+ 필요
Hermes Agent스킬 + 네이티브 플러그인(도구, /pwf, pre_llm_call, post_tool_call, pre_verify 게이트), CLI와 Desktop
CodeBuddy스킬 + 훅
FactoryAI Droid스킬 + 훅
OpenCode네이티브 플러그인 opencode-planning-with-files(메시지 주입, 쓰기 알림, 압축 flush, session.idle 게이트, pwf_* 도구, /pwf 명령) + 스킬
DeepSeek Harness네이티브 플러그인 dsh-planning-with-files(사전 단계 주입, 쓰기 알림, 압축 후 복원, 턴 종료 게이트, pwf_* 도구, /pwf 명령) + 스킬

표준 Agent Skills: 발견 경로

IDE스킬 발견 경로
Continue.continue/skills/ + .prompt 파일
Pi Agent.pi/skills/(npm 패키지)
OpenClaw.openclaw/skills/
Autohand Code~/.autohand/skills/ 또는 .autohand/skills/
Antigravity.agent/skills/
Kilocode.kilocode/skills/
AdaL CLI (Sylph AI).adal/skills/

💡 IDE가 스킬이 아닌 예전 Rules 시스템을 쓴다면 legacy-rules-support 브랜치를 보세요.

샌드박스 런타임

런타임상태비고
BoxLite✅ 문서화됨하드웨어 격리 마이크로 VM 안에서 Claude Code + planning-with-files 실행

BoxLite는 IDE가 아니라 샌드박스 런타임입니다. 스킬은 BoxLite의 공식 Claude Code 통합 계층인 ClaudeBox로 불러옵니다.

자주 묻는 질문

/clear나 충돌 뒤에 코딩 에이전트가 계획을 잃지 않게 하려면?

계획은 컨텍스트 창에만 있지 않고 디스크의 task_plan.md, findings.md, progress.md에 있습니다. 매 턴 시작에 UserPromptSubmit 훅이 활성 계획 맥락을 골라 다시 주입하고, /clear나 새 세션 뒤에는 스킬이 디스크의 프로젝트 파일을 다시 읽습니다. 이 자동 경로는 에이전트 대화 기록 저장소를 열어 보지 않습니다.

planning-with-files와 에이전트 메모리 도구는 무엇이 다른가요?

메모리 도구(벡터 저장소, 지식 그래프)는 과거 세션의 사실을 떠올리게 돕습니다. planning-with-files는 지금 하고 있는 작업의 단계 · 상태 · 의존성 · 완료 점검, 즉 실행 상태를 관리합니다. 풀려는 문제는 검색이 아니라 계획의 연속성이며, 둘은 서로 보완합니다.

컨텍스트 부패(context rot)는 어떻게 막나요?

컨텍스트 창이 차면서 앞선 지시가 밀려나는 현상이 컨텍스트 부패입니다. 계획을 매 턴 시작에 디스크에서 다시 주입하므로 대화가 길어져도 목표와 단계 상태가 모델의 주의 범위에 머뭅니다. Anthropic이 말하는 구조화된 노트 작성, 곧 창 밖 파일에 영속 상태를 쓰고 필요할 때 다시 읽어 오는 방식의 구현입니다.

어떤 코딩 에이전트에서 쓸 수 있나요?

Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, Pi, Hermes Agent, CodeBuddy, Factory, Mastra, 그리고 SKILL.md 공개 표준을 통한 70개 이상의 도구입니다. v3.7.0부터 .agents/skills/planning-with-files/ 구조도 저장소에 들어 있어 Zed · Amp · Warp · Devin · Antigravity · Gemini CLI · Cursor는 git clone만으로 현재 스킬을 찾습니다.

Claude Code의 plan 모드와 함께 쓰면?

대안이 아니라 서로 이어지는 단계입니다. plan 모드는 접근 방식을 설계하고 승인하는 곳이고, planning-with-files는 작업이 도는 동안 실행 상태(단계 · 조사 결과 · 오류 · 진행)를 디스크에 두고 매 턴 다시 주입합니다. plan 모드 계획을 승인한 뒤 에이전트에게 task_plan.md에 단계로 옮겨 쓰게 하거나 /plan을 호출한 다음 일반 모드로 실행하세요.

작업이 끝나면 계획 파일은 어떻게 되나요?

작업 기억일 뿐 추적하는 산출물이 아닙니다. task_plan.md, findings.md, progress.md, .planning/은 기본으로 gitignore 대상이고 자동 보관되지 않습니다. 남길 가치가 있는 것은 코드 · 커밋 · 문서로 옮기세요. 끝난 이름 있는 계획은 set-active-plan.sh --archive로 .planning/.archive/에 옮기고(--yes로 적용), --restore로 되돌립니다.

훅은 얼마나 빠른가요?

훅 한 번 실행이 v3.6.0 최적화 뒤 289ms로, 이전의 2.0~2.4초에서 줄었습니다. 주입되는 계획 블록은 구조상 KV 캐시에 안정적입니다.

릴리스

최신은 v3.28.2이며, 아래는 최근 릴리스 요지입니다.

버전요지
v3.28.2셸 · PowerShell 도움말 처리를 마무리하고, 복구 채점기와 npm README 점검을 pytest에 추가했으며, 압축 · 복구 동작 설명을 명확히 했습니다.
v3.28.1attest-plan이 두 경로 모두에서 원인을 밝힌 한 번의 거절을 보고하고, PowerShell에 -Target을 추가했습니다. init-session은 잘못 입력한 스위치를 거부합니다.
v3.28.0끝난 이름 있는 계획의 보관 · 복원(--archive / --restore)을 추가했습니다. 미리 보기가 먼저이고 아무것도 지우지 않습니다.
v3.27.0경로 · 단계 메타데이터 · 선택 불확실성을 담은 에이전트용 계획 목록(--list --json)을 추가했습니다.
v3.26.0Claude Code 서브에이전트 도구 훅 격리(PWF_SKIP_SUBAGENTS=1)를 선택 사항으로 추가했습니다.
v3.24.0Qoder CLI 네이티브 플러그인과 CLI 완료 게이트를 추가했습니다.
v3.22.0OpenCode 2 지원(네이티브 플러그인 등록, 맥락 주입, 계획 도구, 완료 게이트).
v3.20.0DeepSeek Harness가 1급 호스트가 되었습니다(dsh-planning-with-files).
v3.17.0Claude Code 훅이 한 번에 약 130개 프로세스를 띄우던 문제를 단일 Python 프로세스로 합쳐 프롬프트당 0.3초로 줄였습니다.
v3.14.0OpenCode가 자체 플러그인 시스템으로 1급 호스트가 되었습니다(opencode-planning-with-files).
v3.13.0Hermes Agent가 1급 호스트가 되었습니다(CLI와 Desktop).
v3.7.0Agent Skills 표준 구조(.agents/skills/planning-with-files/)를 저장소에 포함했습니다.

명령

명령하는 일
/plan활성 계획을 시작하거나 보여 줍니다
/plan-status현재 단계와 완료 상태를 보여 줍니다
/plan-attestSHA-256 해시로 계획을 잠급니다
/plan-goal활성 계획에서 종료 조건을 도출합니다
/plan-loop재주입을 하는 10분 간격 자율 루프를 켭니다
/plan-doctor계획 인식 · 주입 · 증명 · 지연 시간을 자가 점검합니다

언어 변형 명령으로 /plan-ar, /plan-de, /plan-es, /plan-zh, /plan-zht가 있습니다. Pi · OpenCode · Hermes에는 /pwf, /pwf-status 계열 명령이 있습니다.

동작 방식

세 개의 마크다운 파일이 디스크에 있고, 수명 주기 훅이 매 턴 시작에 계획 맥락을 다시 주입합니다. 병렬 작업은 .planning/YYYY-MM-DD-slug/ 격리 디렉터리와 공유 .active_plan 포인터로 상태를 나눕니다.

세션 복구

/clear나 충돌 뒤에는 수동으로 세션을 재구성하지 않아도 훅이 디스크의 계획 파일을 자동으로 다시 읽습니다. 영속 상태를 창 밖 파일에 두고 필요할 때 다시 불러오는 구조화된 노트 작성 패턴입니다.

멀티 에이전트 실행

워커는 각자의 원장 파일에 JSON 이벤트를 추가하고, 오케스트레이터가 공유 task_plan.md를 소유합니다. 독립 작업마다 init-session.sh로 자기 .planning/ 디렉터리를 받습니다. PWF_PLAN_ROOT 환경 변수는 모호한 작업 디렉터리를 특정 프로젝트에 묶고, PLAN_ID는 터미널 하나를 이름 있는 계획에 고정합니다.

환경 변수

변수뜻
PWF_PLAN_ROOT공유 상위 디렉터리에서 쓰는 절대 경로 바인딩
PLAN_ID병렬 작업용 명시적 계획 선택자
PLANNING_DISABLED=1호출 단위 해제, 같은 디렉터리의 미완료 계획이 한 번짜리 작업을 가로채지 않게 합니다
PWF_INJECT=smart구조를 인식하는 주입으로 목표와 활성 단계를 창에 유지합니다
PWF_FAST_PATH=0Python 최적화 대신 셸 체인을 강제합니다

벤치마크

  • 스킬을 켰을 때 단언 통과율 96.7%
  • 블라인드 A/B 비교 3전 3승
  • /clear 뒤 계획 재정렬 13.3턴 → 5.0턴
  • 훅 지연 회당 289ms(이전 2.0~2.4초)

더 알아보기

원문 README에는 다음 절이 더 있습니다. 자세한 내용은 저장소에서 확인하세요.

  • v3 장시간 에이전트 기능: 해시 증명, 완료 게이트(Stop 훅), 원장, 자율 루프 등.
  • 19개 이상 플랫폼 지원 표: 향상 지원 · 표준 스킬 · 저장소 내 발견 세 단계.
  • Pi · OpenCode · Hermes 전용 명령과 호스트별 설정 문서(docs/).
  • 전체 릴리스 기록: CHANGELOG.md.

저장소: OthmanAdi/planning-with-files · 라이선스: MIT

평점

–평가 0개 기준
5점
0
4점
0
3점
0
2점
0
1점
0