AI 칼럼

코딩@donghyeok99운영진

Planning with Files: /clear에도 살아남는 에이전트의 계획

/clear 뒤 다시 감을 잡는 데 13.3턴 걸리던 에이전트가, 디스크의 계획 파일로 5.0턴 만에 이어 갔어요

대화가 쌓이던 컨텍스트 창이 /clear로 비워져도, task_plan.md에서 진행 중인 Phase 3이 다시 들어와 일이 이어지고 재방향 잡기는 13.3턴에서 5.0턴이 돼요.
대화가 쌓이던 컨텍스트 창이 /clear로 비워져도, task_plan.md에서 진행 중인 Phase 3이 다시 들어와 일이 이어지고 재방향 잡기는 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 모드를 켜면 진행 중인 단계가 남아 있는 동안은 멈추지 못해요.

PWF: Every task. Every step. Three planning files on a brass-inlaid base beneath an engraved arch

안에서는 이렇게 돌아가요

  1. 1

    나 → planning-with-files

    /plan 또는 「이 작업 계획해 줘」init-session이 템플릿으로 계획 파일 세 개를 프로젝트 폴더에 만들어요.skills/planning-with-files/scripts/init-session.sh
  2. 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. 3

    Claude Code → task_plan.md 외 2개

    체크 표시, findings 추가, progress 기록알게 된 건 findings.md에, 한 일과 테스트 결과는 progress.md에 바로 적어요.skills/planning-with-files/SKILL.md
  4. 4

    claude-hook.sh → Claude Code

    UserPromptSubmit: 매 턴 계획 다시 넣기턴마다 선택된 계획의 내용을 컨텍스트 앞에 넣어 목표가 흐려지지 않게 해요.hooks/hooks.json
  5. 5

    claude-hook.sh → Claude Code

    Stop: 끝나지 않은 단계가 있으면 붙잡기gated 모드에서만, in_progress 단계가 남으면 멈춤을 막되 횟수 제한과 정체 감지가 있어요.skills/planning-with-files/scripts/gate-stop.sh
  6. 6

    claude-hook.sh → 현재 단계에서 이어 하기

    /clear·압축 뒤 SessionStart: inject-plan.sh새 세션이 열리면 디스크의 계획에서 현재 단계를 읽어 와 그 자리에서 다시 시작해요.skills/planning-with-files/scripts/inject-plan.sh

넣으면 이렇게 나와요

절반쯤에서 끊긴 세션에 「Continue the work in this directory.」다시 감을 잡는 데 평균 13.3턴 → 5.0턴 (README의 내부 벤치마크)
Claude Code 플랜 모드에서 승인한 계획task_plan.md의 단계로 옮겨 실행 상태를 디스크에 유지
동시에 돌리는 작업 여러 개.planning/YYYY-MM-DD-slug/마다 따로 세 파일, PLAN_ID로 고정
끝낸 계획set-active-plan.sh --archive로 .planning/.archive/에 보관 (v3.28.0)

나한테 맞을까요

이럴 때 좋아요

  • 몇 시간씩 걸리는 리팩터링이나 마이그레이션을 에이전트에게 맡길 때
  • /clear나 자동 압축 때문에 자주 처음부터 다시 설명하게 될 때
  • 한 계획을 Claude Code에서 Codex 같은 다른 에이전트로 넘겨 이어 갈 때
  • 여러 에이전트가 한 저장소에서 각자 다른 작업을 할 때

이건 안 돼요

  • 13.3턴 → 5.0턴은 프로젝트의 내부 벤치마크 v1이에요. 지금의 파일 전용 복구는 같은 방식으로 다시 재지 않았다고 README가 밝혀요.
  • npx skills로 깔면 훅이 조용히 빠질 수 있어요. 훅이 중요하면 Claude Code 플러그인으로 깔고 /plan-doctor로 확인하라고 README가 권해요.
  • 계획 파일은 기본으로 gitignore되고 자동 보관되지 않아요. 남길 건 코드, 커밋, 문서로 옮겨야 해요.
  • 병렬 쓰기 경고는 쓰고 난 뒤의 알림일 뿐, 잠금이나 병합은 하지 않아요.

발행 전에 Devalley 편집자가 검토했어요. 칼럼은 어떻게 만드나요

로그인하면 글을 쓰고 댓글과 좋아요로 참여할 수 있어요.로그인

신고하기

사유

커뮤니티 규칙 보기