planning-with-files

# 파일로 계획하기

에이전트가 무시할 수 없는 계획 스킬입니다.

에이전트가 따를지도 모르는 프롬프트가 아닙니다. 매 턴마다 발동하는 훅, `/clear` 후에도 살아남는 디스크 위의 계획, 그리고 실제로 작동함을 보여주는 3전 3승의 블라인드 A/B 결과입니다.

에이전트의 컨텍스트 윈도우는 죽습니다. 계획은 죽지 않습니다.

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용 네이티브 플러그인을 제공합니다.

`/clear`에서 살아남는 모습 보기 · 설치 · 장시간 실행 작업 · 퍼스트클래스 호스트

아래의 Commands, Multi-agent runs, Benchmarks & more 섹션을 열어 레퍼런스를 확인하세요 · 전체 설치 가이드

## 빠른 설치
```
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전 3승을 거두었습니다(수치와 한계). 아래의 모든 메커니즘은 디스크 위의 파일과 훅이므로, 열 번째 시간에도 첫 턴과 동일하게 작동합니다.

## 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

## 퍼스트클래스 호스트: 네이티브 플러그인
팁

네이티브 통합은 계획 컨텍스트를 로드하고, 진행 상황 알림을 제공하며, 완료 게이트를 지원합니다. 명령과 모델 호출 가능 도구는 호스트에 따라 다릅니다. Qoder CLI는 Claude 전용 명령 프롬프트 없이 스킬과 라이프사이클 훅을 로드합니다. 플랫폼 설정 가이드는 각 통합과 표준 Agent Skills 경로를 설명합니다.

## 🌐 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
```
이것들은 설명만 번역된 영어 본문이 아니라 실제 번역입니다: SKILL.md 산문, 템플릿, 그리고 `check-complete`, `init-session`, `session-catchup`의 사용자 대상 출력이 모두 현지화됩니다. 상태 토큰은 의도적으로 리터럴 영어(`**Status:** complete`)로 유지되는데, `check-complete.sh`가 `grep -F`로 이를 매칭하기 때문에 번역하면 완료 게이트가 비활성화되기 때문입니다.

v3.10.0부터 변형들은 전체 스크립트 표면도 제공합니다: 증명(attestation), Stop 게이트, 원장(ledger), 단계 상태, plan-doctor는 이전에 정식 버전 전용이었으며, 이는 모든 비영어 설치를 조용히 부분 설치로 만들었습니다. v3.11.0에서 플러그인 경로에 무엇이 변경되었는지를 포함한 전체 세부 사항은 `docs/languages.md`에 있습니다.

이들은 `skills/i18n/` 아래에 있으며, 정식 스킬보다 한 디렉터리 더 깊습니다. 위의 설치 명령은 변경되지 않았는데, `npx skills add`가 저장소 전체에서 스킬 이름으로 `--skill`을 해석하기 때문입니다. Claude Code 플러그인 스캔은 재귀하지 않고 `skills/*/SKILL.md`를 읽으므로, 플러그인 경로는 정식 스킬만 등록하고 더 이상 모든 세션의 시스템 프롬프트에 다섯 개의 추가 설명을 담지 않습니다. 해당 경로에서 `/plan-ar`, `/plan-de`, `/plan-es`, `/plan-zh`, `/plan-zht` 명령은 이름으로 호출하는 대신 디스크에서 번역된 스킬을 읽습니다.

## 향상된 지원: IDE별 설정 가이드

| IDE | 설치 가이드 | 통합 |
|---|---|---|
| Claude Code | Installation | Plugin + SKILL.md + Hooks |
| Cursor | Cursor Setup | Skills + hooks.json |
| GitHub Copilot | Copilot Setup | Hooks (incl. errorOccurred) |
| Mastra Code | Mastra Setup | Skills + Hooks |
| Gemini CLI | Gemini Setup | Skills + Hooks |
| Kiro | Kiro Setup | Agent Skills |
| Codex | Codex Setup | Skills + Hooks |
| Qoder CLI | Installation | Skill + seven lifecycle hooks; Bash and Python 3.10+ required |
| Hermes Agent | Hermes Setup | Skill + native plugin (tools, /pwf, pre_llm_call, post_tool_call, pre_verify gate), CLI and Desktop |
| CodeBuddy | CodeBuddy Setup | Skills + Hooks |
| FactoryAI Droid | Factory Setup | Skills + Hooks |
| OpenCode | OpenCode Setup | Native plugin opencode-planning-with-files (chat.message injection, write reminders, compaction flush, session.idle gate, pwf_* tools, /pwf commands) + skill |
| DeepSeek Harness | DeepSeek Harness Setup | Native plugin dsh-planning-with-files (agent/pre-step injection, write reminders, post-compaction restore, agent/turn-stopping gate, pwf_* tools, /pwf commands) + skill |

## 표준 Agent Skills: 검색 경로

| IDE | 설치 가이드 | 스킬 검색 경로 |
|---|---|---|
| Continue | Continue Setup | .continue/skills/ + .prompt files |
| Pi Agent | Pi Agent Setup | .pi/skills/ (npm package) |
| OpenClaw | OpenClaw Setup | .openclaw/skills/ (docs) |
| Autohand Code | Autohand Code Setup | ~/.autohand/skills/ or .autohand/skills/ |
| Antigravity | Antigravity Setup | .agent/skills/ (docs) |
| Kilocode | Kilocode Setup | .kilocode/skills/ (docs) |
| AdaL CLI (Sylph AI) | AdaL Setup | .adal/skills/ (docs) |

참고: IDE가 Skills 대신 레거시 Rules 시스템을 사용하는 경우 legacy-rules-support 브랜치를 참조하세요.

## 샌드박스 런타임

| 런타임 | 상태 | 가이드 | 비고 |
|---|---|---|---|
| BoxLite | ✅ Documented | BoxLite Setup | 하드웨어 격리 마이크로 VM 내에서 Claude Code + planning-with-files 실행 |

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

## ❓ FAQ
**`/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개 이상(npx skills 설치 프로그램만으로 71개 에이전트를 대상으로 함). v3.7.0부터 저장소는 크로스 툴 `.agents/skills/planning-with-files/` 레이아웃도 트리 내에 제공하므로, Agent Skills 표준 경로를 네이티브로 읽는 도구(Zed, Amp, Warp, Devin, Antigravity, Gemini CLI, Cursor)는 도구별 설정 없이 일반 git clone만으로 현재 스킬을 발견합니다. 설치는 한 명령입니다; 위의 빠른 설치를 참조하세요.

**Claude Code의 플랜 모드와 어떻게 함께 작동하나요?**
이들은 대안이 아니라 상호 보완적인 단계입니다. 플랜 모드는 실행 전에 접근 방식을 설계하고 승인하는 곳입니다. planning-with-files는 작업이 실행되는 동안 라이브 실행 상태(단계 상태, 발견 사항, 오류, 진행 상황)를 디스크에 유지하고 매 턴 재주입합니다. 핸드오프는 한 단계입니다: 플랜 모드 계획을 수락한 후, 에이전트에게 이를 단계로 `task_plan.md`에 작성하라고 하거나(또는 `/plan`을 호출하여 스킬이 파일을 생성하도록) 한 다음 일반 모드에서 실행하세요. 그 시점부터 훅이 단계를 주의 윈도우에 유지하고, 파일은 `/clear`, 컴팩션, 세션 종료에서 살아남습니다.

**작업이 완료된 후 계획 파일은 어떻게 되나요?**
이들은 추적되는 결과물이 아니라 작업 기억입니다. `task_plan.md`, `findings.md`, `progress.md`, `.planning/` 디렉터리는 기본적으로 gitignore되며 자동으로 보관되지 않습니다: 다음 작업이 루트 계획을 덮어쓰고, slug 디렉터리는 그저 활성 상태가 아니게 됩니다. 보존할 가치가 있는 것은 코드, 커밋, 문서로 승격되어야 합니다. 전체 라이프사이클과 완료된 계획을 유지하는 방법은 After Completion: What Happens to the Plan Files를 참조하세요. 이것은 누락된 기능이 아니라 의도된 기본값입니다; 완료 시 트리거되는 보관 단계는 환영할 옵트인 확장입니다.

**훅은 얼마나 빠른가요?**
v3.6.0 최적화 이후 훅 한 번 발동은 289ms의 실제 시간(wall-clock)으로 측정되며, 이전에는 2.0~2.4초였습니다. 주입되는 계획 블록은 구조상 KV 캐시 안정적입니다. 계획은 매 턴 주의 윈도우에 남고, `/clear`는 더 이상 치명적이지 않습니다.

## 📦 릴리스

| 버전 | 하이라이트 |
|---|---|
| v3.26.0 | 옵트인 Claude Code 서브에이전트 도구 훅 격리(`PWF_SKIP_SUBAGENTS=1`) 추가; Codex 설정, Copilot PreToolUse 출력, Gemini 라이프사이클 옵트아웃 수정(PR #345, #346, #347; #348). |
| v3.25.2 | 초기화 프로그램을 통한 계획 생성 및 명시적 형식 검증; Copilot 컨텍스트 스키마와 Cursor 선택/설치 수정; 선택적 skill-lens 재개 평가(PR #338, #340, #341, #342). |
| v3.25.1 | OpenCode가 현재 증명 유효성을 보고; DSH가 PLAN_ID 선택 알림을 보존. 문서화된 한계와 기여자가 보고한 측정치를 포함한 선택적 skill-lens 평가 추가(PR #331, #333, #334). |
| v3.25.0 | Hermes 어댑터 0.3.0이 대화별로 명명된 계획을 바인딩하며, 명시적 선택, 성공적인 init/파일 작업 바인딩, 지속적 세션 기록, 동시 세션 격리를 제공. 기존의 모호성, 허용, 증명 검사는 계속 활성(#328). |
| v3.24.3 | Pi가 컨텍스트와 단계 카운트에 사용된 정확한 계획 스냅샷을 검증; 선택된 증명 읽기 실패는 차단 상태로 유지. 가이드가 진행 상황 편집 후 명시적 재증명을 명확히 함(#326). |
| v3.24.2 | Pi 패리티 모드가 변경되지 않은 pre-too…를 억제 |