Planning with Files: /clear에도 살아남는 에이전트의 계획
/clear 뒤 다시 감을 잡는 데 13.3턴 걸리던 에이전트가, 디스크의 계획 파일로 5.0턴 만에 이어 갔어요
- 누가
- OthmanAdi가 MIT 라이선스로 공개한 계획 스킬이에요. 몇 시간씩 걸리는 일을 코딩 에이전트에게 맡기는 사람을 위한 거예요.
- 언제
- 2026년 1월에 공개돼 1월 6일 Trendshift 전체 1위에 올랐고, 최근 릴리스는 11월 7일 v3.28.1이에요.
- 어디서
- Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode 등 60개 넘는 에이전트에서 써요. 파일은 내 프로젝트 폴더에 남아요.
이게 불편했어요
긴 작업을 맡기면 처음엔 잘 가다가, 도구를 50번쯤 쓰고 나면 원래 목표가 흐려져요. /clear를 하거나 컨텍스트가 압축되면 어디까지 했는지 다시 설명하느라 한참이 걸리고요. 덜 끝낸 채 「다 됐어요」 하고 멈출 때도 있어요.
그래서 이렇게 풀어요
계획을 대화가 아니라 프로젝트 폴더의 마크다운 파일 세 개에 둬요. task_plan.md에는 단계와 상태를, findings.md에는 알게 된 것을, progress.md에는 한 일과 테스트 결과를 적어요. 훅이 매 턴 이 계획을 다시 넣어 주고, /clear나 압축 뒤 새 세션은 파일에서 현재 단계를 읽어 바로 이어 가요. gated 모드를 켜면 진행 중인 단계가 남아 있는 동안은 멈추지 못해요.

안에서는 이렇게 돌아가요
- 1
나 → planning-with-files
/plan 또는 「이 작업 계획해 줘」init-session이 템플릿으로 계획 파일 세 개를 프로젝트 폴더에 만들어요.skills/planning-with-files/scripts/init-session.sh - 2
planning-with-files → task_plan.md 외 2개
목표 · 다음 단계 · Phase 1~5단계마다 체크박스와 pending, in_progress, complete 중 하나의 Status를 둬요.skills/planning-with-files/templates/task_plan.md - 3
Claude Code → task_plan.md 외 2개
체크 표시, findings 추가, progress 기록알게 된 건 findings.md에, 한 일과 테스트 결과는 progress.md에 바로 적어요.skills/planning-with-files/SKILL.md - 4
claude-hook.sh → Claude Code
UserPromptSubmit: 매 턴 계획 다시 넣기턴마다 선택된 계획의 내용을 컨텍스트 앞에 넣어 목표가 흐려지지 않게 해요.hooks/hooks.json - 5
claude-hook.sh → Claude Code
Stop: 끝나지 않은 단계가 있으면 붙잡기gated 모드에서만, in_progress 단계가 남으면 멈춤을 막되 횟수 제한과 정체 감지가 있어요.skills/planning-with-files/scripts/gate-stop.sh - 6
claude-hook.sh → 현재 단계에서 이어 하기
/clear·압축 뒤 SessionStart: inject-plan.sh새 세션이 열리면 디스크의 계획에서 현재 단계를 읽어 와 그 자리에서 다시 시작해요.skills/planning-with-files/scripts/inject-plan.sh
넣으면 이렇게 나와요
나한테 맞을까요
이럴 때 좋아요
- 몇 시간씩 걸리는 리팩터링이나 마이그레이션을 에이전트에게 맡길 때
- /clear나 자동 압축 때문에 자주 처음부터 다시 설명하게 될 때
- 한 계획을 Claude Code에서 Codex 같은 다른 에이전트로 넘겨 이어 갈 때
- 여러 에이전트가 한 저장소에서 각자 다른 작업을 할 때
이건 안 돼요
- 13.3턴 → 5.0턴은 프로젝트의 내부 벤치마크 v1이에요. 지금의 파일 전용 복구는 같은 방식으로 다시 재지 않았다고 README가 밝혀요.
- npx skills로 깔면 훅이 조용히 빠질 수 있어요. 훅이 중요하면 Claude Code 플러그인으로 깔고 /plan-doctor로 확인하라고 README가 권해요.
- 계획 파일은 기본으로 gitignore되고 자동 보관되지 않아요. 남길 건 코드, 커밋, 문서로 옮겨야 해요.
- 병렬 쓰기 경고는 쓰고 난 뒤의 알림일 뿐, 잠금이나 병합은 하지 않아요.
발행 전에 Devalley 편집자가 검토했어요. 칼럼은 어떻게 만드나요