[스킬 사용법] Planning with Files — /clear를 해도 계획을 잃지 않게 파일 3개로 붙잡아 두기
· 바이브코드 운영팀
긴 작업을 시키다 보면 대화가 길어져 앞의 지시가 밀려나거나, /clear 한 번에 어디까지 했는지 사라질 때가 있어요. Planning with Files는 계획·조사 결과·진행 기록을 프로젝트 폴더의 마크다운 파일 3개에 적어 두고, 훅(hook, 정해진 시점에 자동으로 도는 스크립트)으로 매 턴 다시 읽혀 주는 스킬이에요.
출처: 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
설치 방식별로 무엇이 들어오는지는 저장소의 설치 안내에 표로 정리돼 있어요.
설치가 됐는지 확인하는 방법이에요.
- 플러그인으로 설치했다면 터미널에서
claude plugin list를 실행해요. - 스킬만 설치했다면 새 세션에서
/planning-with-files를 불러 보세요. - 프로젝트 루트에서
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-attest | SHA-256 해시로 계획을 잠가요 |
/plan-goal | 모든 단계가 끝날 때까지 가는 종료 조건을 잡아요 |
/plan-loop | 10분 간격으로 계획을 다시 주입하는 반복을 켜요 |
쓰기 전과 후는 이렇게 달라져요.
| 쓰기 전 | 쓴 뒤 | |
|---|---|---|
/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 · 영어 — 마크다운 파일을 작업 기억으로 쓰는 개념을 짧게 소개해요.
더 보기
- 저장소: OthmanAdi/planning-with-files
- 설치 안내: docs/installation.md
- 바이브코드 상세 페이지: Planning with Files
확인한 날짜 · 버전: 2026-11-20 · 최신 릴리스 v3.28.1(2026-11-07)
글이 도움이 되었다면 좋아요를 눌러 주세요.