OthmanAdi/planning-with-files

Meta가 20억 달러에 인수한 AI 에이전트 기업인 Manus처럼 작동합니다.

💬 저자의 노트

이 기술을 Star, Fork 하고 공유해 주신 모든 분께 감사드립니다. 이 프로젝트는 24시간도 채 되지 않아 폭발적으로 성장했으며, 커뮤니티의 지원은 정말 놀라웠습니다.

이 기술이 여러분이 더 스마트하게 일하는 데 도움이 된다면, 그것이 제가 원했던 전부입니다.

🌍 커뮤니티가 출시한 것들

Fork	저자	구축한 내용
devis	@st01cs	인터뷰 우선 워크플로우 (Interview-first workflow), /devis:intv 및 /devis:impl 명령어, 활성화 보장
...
프로젝트	내용
---	---
lincolnwan/Planning-with-files-copilot-agent	planning-with-files 기술을 중심으로 구축된 전체 Copilot 에이전트 저장소
...
무언가를 만드셨나요? 목록에 추가하려면 Issue를 열어주세요!

📦 릴리스 및 세션 복구 (Session Recovery)

버전	주요 내용
v2.37.0
해시 증명 (Hash attestation) + 패리티 범퍼 (parity bumper) (#150, #151 해결): /plan-attest가 task_plan.md를 SHA-256으로 잠금 처리합니다; 변조 시 훅 주입 (hook injection)을 차단합니다. scripts/bump-version.py + 패리티 테스트를 통해 v2.34.1, v2.36.0, v2.36.2, v2.36.3 뒤에 숨어있던 "하나의 변형을 놓침" 회귀 (regression) 클래스를 제거했습니다. (@oaabahussain님 감사합니다!)
v2.36.3
병렬 계획 (Parallel planning) 스크립트가 이제 기술에 포함됩니다: resolve-plan-dir.sh 및 set-active-plan.sh가 v2.36.0 설치된 기술에서 누락되었으나, 이제 정식 버전(canonical) + 모든 IDE 미러 + SKILL.md 문서에 업데이트되었습니다.
v2.36.2
정식 스크립트 동기화 (PR #149): skills/planning-with-files/scripts/init-session.sh가 v2.36.0에서 슬러그 모드 (slug mode)가 누락되었으나, 이제 IDE 미러 + 회귀 테스트와 동기화되었습니다. (@voidborne-d님 감사합니다!)
v2.36.1
보안 강화: Stop hook cache search 제거, ExecutionPolicy Bypass를 RemoteSigned로 변경, 프롬프트 주입 (prompt injection) 구분자 추가. (Gen Agent Trust Hub FAIL 해결)
v2.36.0
병렬 계획 격리 (Parallel plan isolation) + Codex 세션 격리 (#146, #148 해결): init-session.sh 슬러그 모드, set-active-plan.sh, resolve-plan-dir.sh, 모든 Codex 훅이 resolver를 통해 라우팅되며, 세션 부착 게이팅 (session attachment gating)이 적용됩니다.

Hermes docs (closes #147): docs/hermes.md에 통합 노트 (integration notes)가 추가되었습니다. 34개의 새로운 테스트가 추가되었습니다. (thanks @githubYiheng, @09ashishkapoor, @shawnli1874!) |
v2.35.1 |
Shebang 이식성 수정: 훅 스크립트 (hook scripts)에서 /bin/bash를 /usr/bin/env bash로 변경하여, bash가 /bin/bash에 위치하지 않는 NixOS 및 기타 시스템에서의 호환성 문제를 해결했습니다. (thanks @Emin017!) |
v2.35.0 |
Hermes 어댑터 (adapter) + NLPM 감사 강화 (audit hardening): Hermes 플랫폼 17 지원 (thanks @bailob!), NLPM 감사의 Python PATH 해결 방식 수정, 세션 캐치업 (session-catchup) 주입 제한, Pi PowerShell 구문 수정 (thanks @xiaolai!) |
v2.34.1 |
Stop 훅 Windows 이식성 수정 (closes #133): Windows Git Bash 훅 컨텍스트에서 export SD=가 실패하던 문제를 해결했습니다; 플러그인 캐시 구조에 대한 폴백 경로 (fallback path)가 잘못되어 있었습니다. 13개의 모든 SKILL.md 변형에 대해 수정되었습니다. (thanks @nazeshinjite!) |
v2.34.0 |
Codex 훅 (hooks) 완전 복구 (closes #132): .codex/hooks.json + 라이프사이클 스크립트 (lifecycle scripts) 복구 — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop. SKILL.md 품질 검토를 위한 Tessl CI. 실행 비트 (Exec bit) 수정. 누락된 기여자 4명 추가.

(thanks @Leon-Algo, @popey!) |
v2.33.0 |
다국어 확장: 아랍어, 독일어, 스페인어 스킬 (skill) 변체 추가 (커뮤니티 기여자분들께 감사드립니다!) |
v2.32.0 |
Codex 세션 캐치업 (catchup) 재작성 (thanks @ebrevdo!), Loaditout A-grade 보안 배지, Stop hook Git Bash 수정 |
v2.31.0 |
전체 라이프사이클 훅 (lifecycle hooks)을 포함한 Codex hooks.json 통합 (thanks @Leon-Algo!) |
v2.30.1 |
수정: Codex 스크립트 실행 비트 (executable bits) 복구 (thanks @Leon-Algo!) |
v2.30.0 |
CLAUDE_SKILL_DIR 변수, IDE 설정이 각 IDE별 브랜치로 이동, plugin.json이 2.23.0에서 업데이트됨 |
v2.29.0 |
분석 워크플로 (Analytics workflow) 템플릿: 데이터 탐색 세션을 위한 --template analytics 플래그 추가 (thanks @mvanhorn!) |
v2.28.0 |
번체 중국어 (zh-TW) 스킬 (skill) 변체 추가 (thanks @waynelee2048!) |
v2.26.2 |
수정: 훅 (hook) 명령의 ---가 YAML 프론트매터 (frontmatter) 파싱을 방해하던 문제 해결, 이제 훅이 올바르게 등록됨 |
v2.26.1 |
수정: /clear 이후의 세션 캐치업 (session catchup), Windows에서의 경로 정규화 (path sanitization) 및 콘텐츠 인젝션 (content injection) 문제 해결 (thanks @tony-stark-eth!) |
v2.26.0 |
IDE 감사 (audit): Factory 훅, Copilot errorOccurred 훅, Gemini 훅, 버그 수정 |
v2.18.2 |
Mastra Code 훅 (hooks) 수정 (hooks.json + 문서 정확도) |
v2.18.1 |
Copilot 깨진 문자 완전 수정 |
v2.18.0 |
BoxLite 샌드박스 (sandbox) 런타임 통합 |
v2.17.0 |
Mastra Code 지원 + 모든 IDE SKILL.md 사양 (spec) 수정 |
v2.16.1 |
Copilot 깨진 문자 수정: PS1 UTF-8 인코딩 + bash ensure_ascii (thanks @Hexiaopi!) |
v2.16.0 |
GitHub Copilot 훅 (hooks) 지원 (thanks @lincolnwan!) |
v2.27.0 |
Kiro Agent 스킬 (skill) 레이아웃 (thanks @EListenX!) |
v2.15.1 |
세션 캐치업 (session catchup) 오탐 (false-positive) 수정 (thanks @gydx6!) |
v2.15.0 |
/plan:status 명령, OpenCode 호환성 수정 |
v2.14.0 |
Pi Agent 지원, OpenClaw 문서 업데이트, Codex 경로 수정 |
v2.11.0 |
더 쉬운 자동 완성 (autocomplete)을 위한 /plan 명령 |
v2.10.0 |
Kiro 스티어링 (steering) 파일 지원 |
v2.7.0 |
Gemini CLI 지원 |
v2.2.0 |
세션 복구 (session recovery), Windows PowerShell, OS 인식 훅 (hooks) |

병렬 플랜 격리 (Parallel plan isolation) (

.planning/YYYY-MM-DD-slug/

디렉토리) 및 Codex 세션 격리 (session isolation) 기능이 v2.36.0에 출시되었습니다. experimental/isolated-planning 브랜치는 이전 프로토타입이었으며, 현재는 master 브랜치가 정식 위치(canonical location)입니다.

컨텍스트 (context)가 가득 차서 /clear를 실행하면, 이 스킬은 자동으로 이전 세션을 복구합니다.

작동 방식:

• 활성 IDE의 세션 저장소에서 이전 세션 데이터 확인 (Claude Code의 경우 ~/.claude/projects/, Codex의 경우 ~/.codex/sessions/)
• 플래닝 파일 (planning files)이 마지막으로 업데이트된 시점 확인
• 그 이후에 발생한 대화 추출 (잠재적으로 손실된 컨텍스트)
• 동기화를 위해 캐치업 보고서 (catchup report) 표시

프로 팁 (Pro tip): 삭제 전 컨텍스트를 최대화하려면 자동 압축 (auto-compact)을 비활성화하세요:

{ "autoCompact": false }

🛠️ 지원되는 IDE (17개 이상의 플랫폼)

이 IDE들은 도구 사용 전 플랜을 자동으로 다시 읽고, 진행 상황 업데이트를 상기시키며, 중단 전 완료 여부를 확인하는 전용 훅 (hooks) 설정을 갖추고 있습니다:

IDE	설치 가이드	통합 방식
Claude Code	설치	Plugin + SKILL.md + Hooks
...

이 IDE들은 Agent Skills 공개 사양 (open specification)을 구현합니다. npx skills add로 설치하세요. 설치 프로그램이 각 IDE의 탐색 경로 (discovery path)에 스킬을 자동으로 배치합니다:

IDE	설치 가이드	스킬 탐색 경로 (Skill Discovery Path)
Continue	Continue 설정	.continue/skills/ + .prompt 파일
...

참고: 만약 사용 중인 IDE가 Skills 대신 레거시 규칙 (legacy Rules) 시스템을 사용한다면, legacy-rules-support 브랜치를 참조하세요.

🧱 샌드박스 런타임 (Sandbox Runtimes) (1개 플랫폼)

런타임	상태	가이드	비고
BoxLite	✅ 문서화됨	BoxLite 설정	하드웨어 격리 마이크로 VM (micro-VMs) 내부에서 Claude Code + planning-with-files 실행

참고: BoxLite는 샌드박스 런타임이며 IDE가 아닙니다. 스킬은 BoxLite의 공식 Claude Code 통합 레이어인 ClaudeBox를 통해 로드됩니다.

플래닝, 진행 상황 추적 및 지식 저장을 위해 지속 가능한 마크다운 (markdown) 파일을 사용하도록 워크플로우를 변환하는 Claude Code 플러그인입니다. 이는 Manus를 수십억 달러의 가치로 만든 바로 그 패턴입니다.

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

🌐 5개의 다른 언어로 제공 가능

🇸🇦 العربية / Arabic

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

🇩🇪 Deutsch / German

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

🇪🇸 Español / Spanish

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

🇨🇳 中文版 / Chinese (Simplified)

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

🇹🇼 正體中文版 / Chinese (Traditional)

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

Claude Code, Cursor, Codex, Gemini CLI, 그리고 Agent Skills 사양을 지원하는 40개 이상의 에이전트(agents)와 함께 작동합니다.

🔧 Claude Code 플러그인 (고급 기능)

/plan과 같은 Claude Code 전용 기능을 위한 자동 완성(autocomplete) 명령:

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

끝입니다! 이제 Claude Code에서 다음 명령 중 하나를 사용하세요:

명령	자동 완성	설명
/planning-with-files:plan	/plan 입력	플래닝 세션 시작 (v2.11.0+)
/planning-with-files:status	/plan:status 입력	플래닝 진행 상황을 한눈에 확인 (v2.15.0+)
/planning-with-files:start	/planning 입력	기존 시작 명령

대안: 만약 접두사(prefix) 없이 /planning-with-files를 사용하고 싶다면, 스킬(skills)을 로컬 폴더로 복사하세요:

macOS/Linux:

cp -r ~/.claude/plugins/cache/planning-with-files/planning-with-files/*/skills/planning-with-files ~/.claude/skills/

Windows (PowerShell):

Copy-Item -Recurse -Path "$env:USERPROFILE\.claude\plugins\cache\planning-with-files\planning-with-files\*\skills\planning-with-files" -Destination "$env:USERPROFILE\.claude\skills\"

모든 설치 방법은 docs/installation.md를 참조하세요.

2025년 12월 29일, Meta는 Manus를 20억 달러에 인수했습니다. 단 8개월 만에 Manus는 출시 후 매출 1억 달러 이상을 달성했습니다. 그들의 비결은 무엇일까요? 바로 **컨텍스트 엔지니어링 (Context engineering)**입니다.

"Markdown은 디스크 상의 저의 '작업 기억 (working memory)'입니다. 저는 정보를 반복적으로 처리하며 활성 컨텍스트 (active context)에는 제한이 있기 때문에, Markdown 파일은 메모를 위한 연습장, 진행 상황을 위한 체크포인트, 그리고 최종 결과물을 위한 빌딩 블록 역할을 합니다." — Manus AI

Claude Code (및 대부분의 AI 에이전트)는 다음과 같은 문제들을 겪습니다:

휘발성 메모리 (Volatile memory)— 컨텍스트가 리셋되면 TodoWrite 도구가 사라짐
목표 표류 (Goal drift)— 50회 이상의 도구 호출 후, 원래의 목표를 잊어버림
숨겨진 오류 (Hidden errors)— 실패가 추적되지 않아 동일한 실수가 반복됨
컨텍스트 스터핑 (Context stuffing)— 모든 것을 저장하는 대신 컨텍스트에 억지로 밀어 넣음

모든 복잡한 작업에 대해, 세 개의 파일을 생성하세요:

task_plan.md → 단계 및 진행 상황 추적
findings.md → 조사 내용 및 발견 사항 저장
progress.md → 세션 로그 및 테스트 결과

컨텍스트 윈도우 (Context Window) = RAM (휘발성, 제한적)
파일 시스템 (Filesystem) = 디스크 (지속성, 무제한)
→ 중요한 모든 것은 디스크에 기록됩니다.

원칙	구현
메모리로서의 파일 시스템	컨텍스트가 아닌 파일에 저장
...

설치가 완료되면, AI 에이전트는 다음과 같이 동작합니다:

사용자의 작업을 요청합니다 설명이 제공되지 않은 경우
생성합니다 프로젝트 디렉토리에 task_plan.md, findings.md, progress.md를 생성
계획을 다시 읽습니다 주요 결정 전 (PreToolUse 훅을 통해)
상태 업데이트를 상기시킵니다 파일 쓰기 후 (PostToolUse 훅을 통해)
발견 사항을 저장합니다 컨텍스트를 채우는 대신 findings.md에 저장
오류를 기록합니다 향후 참조를 위해
완료를 확인합니다 중단 전 (Stop 훅을 통해)

다음 명령어로 호출하세요:

/planning-with-files:plan

• 자동 완성에서 찾으려면 /plan 입력 (v2.11.0+)

/planning-with-files:start

• 자동 완성에서 찾으려면 /planning 입력

/planning-with-files

• 스킬을 ~/.claude/skills/로 복사한 경우에만 사용 가능

전체 5단계 가이드는 docs/quickstart.md를 참조하세요.

Anthropic의 skill-creator framework (v2.22.0)를 사용하여 공식적으로 평가되었습니다. 10개의 병렬 서브에이전트 (subagents), 5가지 작업 유형 (task types), 30개의 객관적으로 검증 가능한 단언 (assertions), 3회의 블라인드 A/B 비교를 수행했습니다.

테스트	skill 사용 시	skill 미사용 시
통과율 (30개 단언)	96.7% (29/30)	6.7% (2/30)
3개 파일 패턴 준수	5/5 평가	0/5 평가
블라인드 A/B 승리	3/3 (100%)	0/3
평균 루브릭 점수	10.0/10	6.8/10

전체 방법론 및 결과 · 기술 문서 (Technical write-up)

먼저 계획을 수립하세요 (Create Plan First)— task_plan.md 없이 절대 시작하지 마세요.

2-액션 규칙 (The 2-Action Rule)— 매 2회의 조회/브라우저 작업 후에는 발견 사항을 저장하세요.

모든 오류를 기록하세요 (Log ALL Errors)— 오류 기록은 반복을 피하는 데 도움이 됩니다.

실패를 반복하지 마세요 (Never Repeat Failures)— 시도 횟수를 추적하고 접근 방식을 변경하세요.

다음의 경우 이 패턴을 사용하세요:

• 다단계 작업 (3단계 이상)
• 리서치 작업
• 프로젝트 구축/생성
• 많은 도구 호출 (tool calls)이 걸쳐 있는 작업

다음의 경우 건너뛰세요:

• 단순한 질문
• 단일 파일 수정
• 빠른 조회

planning-with-files/
├── commands/ # 플러그인 명령 (Plugin commands)
│ ├── plan.md # /planning-with-files:plan 명령 (v2.11.0+)
...

모든 플랫폼 설정 가이드와 문서는 docs/ 폴더에 있습니다.

Manus AI— 컨텍스트 엔지니어링 (context engineering) 패턴의 개척
Anthropic— Claude Code, 에이전트 스킬 (Agent Skills), 그리고 플러그인 시스템 제공
Lance Martin— 상세한 Manus 아키텍처 분석 제공

• Context Engineering for AI Agents를 기반으로 함

기여(Contributions)를 환영합니다! 다음을 진행해 주세요:

• 저장소 포크 (Fork)
• 기능 브랜치 (feature branch) 생성
• 풀 리퀘스트 (pull request) 제출

MIT License — 자유롭게 사용, 수정 및 배포할 수 있습니다.

저자: Ahmad Othman Ammar Adi