본문으로 건너뛰기

[스킬 사용법] Planning with Files — /clear를 해도 계획을 잃지 않게 파일 3개로 붙잡아 두기

· 바이브코드 운영팀

목차

긴 작업을 시키다 보면 대화가 길어져 앞의 지시가 밀려나거나, /clear 한 번에 어디까지 했는지 사라질 때가 있어요. Planning with Files는 계획·조사 결과·진행 기록을 프로젝트 폴더의 마크다운 파일 3개에 적어 두고, 훅(hook, 정해진 시점에 자동으로 도는 스크립트)으로 매 턴 다시 읽혀 주는 스킬이에요.

task_plan.md, findings.md, progress.md 세 파일이 놓인 PWF 배너 출처: OthmanAdi/planning-with-files

이럴 때 쓰세요

  • 리팩터링이나 이관처럼 단계가 5개 넘게 이어지는 작업
  • 세션이 자주 끊겨서 매번 "지난번에 어디까지 했더라"를 설명해야 할 때
  • 조사하면서 알게 된 것을 컨텍스트 밖에 남겨 두고 싶을 때

한 줄짜리 수정이나 짧은 질문에는 파일 3개가 오히려 과해요. 저장소도 간단한 질문이나 빠른 조회에는 쓰지 말라고 안내해요.

파일 3개가 하는 일

your-project/
├── task_plan.md   ← 단계와 체크박스. /clear 뒤에 돌아올 자리
├── findings.md    ← 조사 메모와 결정
└── progress.md    ← 세션 기록과 테스트 결과

컨텍스트 창은 RAM, 파일은 디스크라고 생각하면 쉬워요. 중요한 건 파일에 적어 두고, 에이전트가 필요할 때 다시 읽게 하는 방식이에요.

준비물

  • Claude Code
  • 훅은 Bash와 Python 3 환경에서 돌아가요
  • npx 방식으로 설치한다면 Node.js

설치

훅과 슬래시 명령(/plan-doctor 등)까지 모두 쓰려면 플러그인 방식이 저장소가 추천하는 길이에요. Claude Code 안에서 두 줄을 따로 입력하세요.

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

스킬만 가볍게 넣고 싶다면 이 한 줄도 돼요. 대신 슬래시 명령은 복사되지 않고, 훅은 스킬이 호출된 뒤에 켜져요.

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

설치 방식별로 무엇이 들어오는지는 저장소의 설치 안내에 표로 정리돼 있어요.

설치가 됐는지 확인하는 방법이에요.

  1. 플러그인으로 설치했다면 터미널에서 claude plugin list를 실행해요.
  2. 스킬만 설치했다면 새 세션에서 /planning-with-files를 불러 보세요.
  3. 프로젝트 루트에서 sh scripts/plan-doctor.sh(플러그인이면 /plan-doctor)를 실행하면 계획 인식, 주입, 지연 시간을 한 번에 점검해 줘요.

사용 예

플러그인 방식이면 /plan 뒤에 목표를 적어 시작해요. /pwf도 같은 별칭이에요.

/plan 로그인 API를 JWT 방식으로 바꾸고 테스트까지 통과시키기

프로젝트에 위 3개 파일이 만들어지고, 에이전트가 단계별로 체크박스를 채워 가며 일해요. 스킬로만 설치했다면 이렇게 말로 불러도 돼요.

이 리팩터링을 5단계로 쪼개서 계획부터 세워줘
지난번 세션에서 어디까지 했는지 이어서 진행해줘

쓰는 동안 에이전트는 이런 규칙을 따라요(저장소 SKILL.md 기준).

  • 조회·검색을 2번 할 때마다 알게 된 것을 findings.md에 적어요
  • 에러는 전부 계획 파일에 기록하고, 같은 방법으로 실패한 일을 되풀이하지 않아요
  • 단계가 끝나면 in_progress에서 complete로 바꾸고 progress.md에 남겨요

자주 쓰는 명령이에요.

명령하는 일
/plan활성 계획을 시작하거나 보여 줘요
/plan-status현재 단계와 완료 상태를 보여 줘요
/plan-doctor계획 인식·주입·지연 시간을 점검해요
/plan-attestSHA-256 해시로 계획을 잠가요
/plan-goal모든 단계가 끝날 때까지 가는 종료 조건을 잡아요
/plan-loop10분 간격으로 계획을 다시 주입하는 반복을 켜요

쓰기 전과 후는 이렇게 달라져요.

쓰기 전쓴 뒤
/clear 뒤처음부터 다시 설명디스크의 task_plan.md를 읽고 현재 단계에서 이어 감
긴 대화앞의 목표가 밀려남매 턴 계획이 다시 주입됨
같은 에러다시 시도하기 쉬움progress.md에 실패 기록이 남음

알아둘 점

  • 훅이 빠질 수 있어요. 스킬만 설치하면 훅이 스킬이 호출된 뒤에야 켜져요. 프로젝트 폴더에 설치했는데 신뢰(trust) 확인을 거치지 않은 세션도 훅이 안 걸려요. 훅이 중요하다면 플러그인으로 설치하고 /plan-doctor로 확인하세요.
  • 스킬이 안 떠오를 때가 있어요. 저장소의 2026년 7월 측정에서 스킬이 저절로 켜진 비율은 60~67%였고, CLAUDE.md에 규칙을 한 줄 넣은 쪽은 100%였어요. 아래 한 줄을 CLAUDE.md에 넣어 두면 확실해져요.
When a task needs 3+ steps or 5+ tool calls, invoke the planning-with-files skill first and keep task_plan.md current.
  • 계획 파일은 자동 보관되지 않아요. task_plan.md, findings.md, progress.md, .planning/은 기본으로 gitignore 대상이에요. 남길 가치가 있는 내용은 코드나 문서로 옮기세요.
  • 웹에서 가져온 글은 findings.md에만. task_plan.md는 매 턴 다시 읽혀 지시처럼 작동할 수 있어요. 외부 글 안의 지시문을 계획에 옮겨 적지 마세요.
  • 훅이 스크립트를 실행해요. 매 턴 셸과 Python 스크립트가 돌아가니, 설치 전에 저장소의 hooks/와 scripts/를 한 번 읽어 보세요.
  • 수치는 저장소가 직접 잰 값이에요. /clear 뒤 재정렬이 13.3턴에서 5.0턴으로 줄었다는 내용도 프로젝트 자체 측정이라 참고용으로 보세요.
  • 라이선스는 MIT예요.

관련 영상

Planning with Files: Claude Code skill that brings workflow behind Manus straight into your terminal · Github Awesome · 영어 — 마크다운 파일을 작업 기억으로 쓰는 개념을 짧게 소개해요.

더 보기

확인한 날짜 · 버전: 2026-11-20 · 최신 릴리스 v3.28.1(2026-11-07)

글이 도움이 되었다면 좋아요를 눌러 주세요.