planning-with-files

planning-with-files 스킬 개요

planning-with-files가 실제로 하는 일

planning-with-files 스킬은 일시적인 채팅 메모리에 기대는 대신, markdown 파일을 기반으로 AI 에이전트가 간단하고 지속적인 계획 시스템을 운영할 수 있게 해줍니다. 핵심 패턴은 3개 파일 워크플로입니다. task_plan.md에는 단계와 상태를, notes.md에는 조사 내용과 발견사항을, 그리고 output.md 같은 최종 결과물 파일에는 산출물을 기록합니다. 여러 단계에 걸친 작업에서 진행 상황을 반복 가능하게 추적하고 싶다면, 바로 이 점이 planning-with-files를 설치할 가장 큰 이유입니다.

planning-with-files를 써야 하는 사람

planning-with-files는 여러 단계 또는 여러 세션에 걸쳐 진행되는 작업에 가장 잘 맞습니다. 예를 들면 리서치, 마이그레이션, 감사, 분석, 콘텐츠 기획, 전반적인 프로젝트 정리 같은 작업입니다. 특히 에이전트가 이미 학습한 내용을 매번 다시 컨텍스트에 붙여 넣지 않고도 기억하게 하고 싶을 때 유용합니다.

가장 잘 맞는 작업 유형

planning-with-files skill은 “답변 하나를 써달라”가 아니라 “진행 중인 계획을 유지하고, 근거를 모으고, 흐름을 잃지 않은 채 결과물을 만들어라”가 진짜 요구일 때 써야 합니다. 이런 점에서 planning-with-files for Project Management는 가벼운 실행 추적에는 잘 맞지만, 무거운 PM 프레임워크를 대체하는 용도로는 적합하지 않습니다.

일반 프롬프트와의 핵심 차이점

일반 프롬프트로도 계획을 요청할 수는 있습니다. 하지만 planning-with-files는 작업 방식 자체를 바꿉니다. 계획, 메모, 결과물을 파일로 외부화해 컨텍스트 리셋이나 긴 도구 사용 세션 이후에도 유지되게 만듭니다. 중요한 것은 개별 프롬프트 문구보다 이 작업 방식의 전환입니다.

맞지 않는 경우

아주 작은 단발성 질문, 순수한 대화형 브레인스토밍, 혹은 PRD 전용 워크플로에는 planning-with-files를 쓰지 않는 편이 낫습니다. 저장소에서도 PRD 작업은 prd-planner를 사용하라고 명시적으로 안내합니다. 워크스페이스 안에 파일이 새로 만들어지는 것을 원하지 않는다면, 이 스킬은 일반 프롬프트보다 더 무겁게 느껴질 수 있습니다.

planning-with-files 스킬 사용 방법

planning-with-files 설치 맥락

이 저장소의 SKILL.md 안에는 전용 설치 명령이 따로 드러나 있지 않아서, 보통은 스킬 컬렉션 저장소에서 다음처럼 추가합니다.

npx skills add https://github.com/zhaono1/agent-playbook --skill planning-with-files

이 스킬은 에이전트가 markdown 파일을 생성하고 수정할 수 있는 환경을 전제로 합니다. 선언된 도구 가정에는 Read, Write, Edit, Bash, Grep, Glob가 포함됩니다.

스킬이 생성하길 기대하는 파일

실무적으로는 다음 기본 패턴을 따릅니다.

• task_plan.md — 목표, 단계, 상태, 다음 단계
• notes.md — 조사 내용, 발견사항, 의사결정, 참고자료
• [deliverable].md — output.md 같은 최종 산출물

기존 저장소에서 planning-with-files usage를 도입한다면, 특별히 로컬 관례에 맞춰야 할 이유가 없는 한 이 파일명을 유지하는 편이 좋습니다. 파일명이 일관되면 에이전트가 혼동할 가능성이 줄어듭니다.

도입 전에 먼저 읽어야 할 파일

다음 순서로 읽는 것이 좋습니다.

1. skills/planning-with-files/SKILL.md
2. skills/planning-with-files/README.md

SKILL.md에는 실제 운영 방식이 담겨 있습니다. README.md는 더 짧아서 빠르게 적합성을 판단할 때 유용합니다. 이 경로에는 추가 규칙, 리소스, 헬퍼 스크립트가 따로 없기 때문에, 숨겨진 자동화를 찾기보다 워크플로 패턴 자체를 이해하는 데 가치가 있습니다.

사용자가 실제로 planning-with-files를 호출하는 방식

실제 사용에서는 보통 다음처럼 요청해 스킬을 트리거합니다.

• “Plan a multi-step migration and track progress in files.”
• “Create a research plan and save notes and deliverables.”
• “Organize this project with persistent task files.”

이 예시들이 잘 작동하는 이유는, 단일 응답이 아니라 여러 단계로 이어지는 작업이라는 점을 전제로 하기 때문입니다.

막연한 목표를 강한 프롬프트로 바꾸기

약한 프롬프트:

• “Help me migrate this app.”

planning-with-files에 더 적합한 프롬프트:

• “Use planning-with-files to create task_plan.md, notes.md, and migration-output.md for a React to Next.js migration. Break the work into phases, track open risks, save findings in notes.md, and keep task_plan.md updated as you go.”

더 좋은 이유:

• 파일 기반 워크플로를 명시합니다
• 구체적인 결과물을 지정합니다
• 메모가 지속적으로 남아야 함을 알려줍니다
• 초기 개요만이 아니라 계획 업데이트까지 요구합니다

결과 품질을 실질적으로 끌어올리는 입력 정보

가능하다면 처음부터 아래 정보를 함께 주는 것이 좋습니다.

• 목표
• 제약사항
• 현재 저장소 또는 소스 자료
• 마감일 또는 우선순위
• 원하는 결과물 파일명
• 무엇을 완료로 볼지에 대한 기준

예시:

• Goal: onboarding flow를 감사하고 개선안을 제안
• Constraints: 코드 변경 없음, 분석만 수행
• Inputs: /docs, /src/onboarding, analytics summary
• Deliverable: onboarding-audit.md
• Done means: 발견사항, 우선순위가 매겨진 이슈, 권장 조치

이런 정보가 없어도 에이전트는 파일을 만들 수는 있지만, 계획이 지나치게 일반적인 수준에 머물 수 있습니다.

추천 워크플로 루프

좋은 planning-with-files guide는 대체로 다음 순서를 따릅니다.

1. 목표와 단계가 담긴 task_plan.md를 생성합니다.
2. 자료를 조사하거나 소스 내용을 점검합니다.
3. 발견사항을 notes.md에 저장합니다.
4. 진행 상황, 막힌 지점, 다음 액션을 반영해 task_plan.md를 업데이트합니다.
5. notes.md를 바탕으로 최종 결과물을 초안 작성합니다.
6. 마무리 전에 남아 있는 공백이나 누락을 표시합니다.

핵심은 처음 파일을 만드는 것 자체가 아니라, 이 루프를 계속 유지하는 행동입니다.

Project Management 용 planning-with-files가 잘 맞는 사례

planning-with-files for Project Management는 엔터프라이즈 PM 도구가 아니라 가벼운 협업·조율용으로 생각하는 것이 맞습니다. 잘 맞는 예시는 다음과 같습니다.

• 마이그레이션 계획 수립
• 리서치 추적
• 구현 체크리스트
• 콘텐츠 제작 워크플로
• 기술 감사
• 의존성 조사

이 스킬은 에이전트가 정보를 찾아내는 동시에 그 내용을 완성도 있는 결과물로 정리해야 할 때 가장 잘 작동합니다.

도입을 막는 흔한 장애물

보통의 장애물은 개념적인 문제가 아니라 실무적인 문제입니다.

• 아주 작은 작업에서 즉각적인 가치를 기대한다
• 에이전트에 명확한 결과물을 지정하지 않는다
• task_plan.md를 계속 업데이트하라고 요청하지 않는다
• 이미 엄격한 프로젝트 파일 구조가 있어서 새 최상위 파일을 원하지 않는다

이 중 하나라도 해당된다면, 설치 전에 이 정확한 패턴이 필요한지 아니면 일회성 계획 프롬프트면 충분한지 먼저 판단하는 것이 좋습니다.

파일 배치에 대한 실용적인 조언

저장소 예시는 루트 레벨의 단순한 파일명을 사용합니다. 독립적인 작업에는 이것으로 충분합니다. 하지만 바쁜 프로젝트에서는 /workstreams/migration/ 같은 작업 폴더 안에 두는 편이 더 깔끔할 수 있습니다. 그렇게 할 경우, 프롬프트에서 경로를 명시적으로 지정해야 에이전트가 파일을 여러 위치로 흩어 놓지 않습니다.

planning-with-files 스킬 FAQ

planning-with-files는 채팅에서 계획만 요청하는 것보다 나은가요?

여러 단계의 작업이라면 대체로 그렇습니다. 장점은 지속성과 추적 가능성입니다. planning-with-files는 변화하는 계획과 발견사항을 파일에 저장하므로, 에이전트가 덜 흔들리면서 이어서 작업하기 쉽습니다. 한 번만 개요가 필요하다면 일반 프롬프트가 더 간단합니다.

planning-with-files 스킬은 초보자도 쓰기 쉬운가요?

네. 패턴이 단순하기 때문입니다. 계획 파일 하나, 메모 파일 하나, 결과물 파일 하나면 됩니다. 초보자가 가장 자주 하는 실수는 파일 관리 오버헤드를 정당화할 수 없을 만큼 작은 작업에 이 스킬을 쓰는 것입니다.

planning-with-files는 특정 프로젝트 유형이 필요한가요?

아니요. 이 패턴은 의도적으로 범용적으로 설계되었습니다. 에이전트가 파일을 읽고 쓸 수만 있다면 엔지니어링, 리서치, 운영, 글쓰기, 분석 작업을 모두 지원할 수 있습니다.

planning-with-files를 쓰면 안 되는 시점은 언제인가요?

다음 경우에는 planning-with-files를 쓰지 않는 것이 좋습니다.

• 한 번의 응답으로 끝나는 작업
• 순수한 대화형 아이데이션
• 파일을 쓸 수 없는 환경의 작업
• prd-planner가 더 적합한 PRD 전용 워크플로

task tracker나 TodoWrite와는 어떻게 다른가요?

이 스킬이 해결하는 문제는 다릅니다. 핵심은 오래 유지되는 작업 기억입니다. task tracker는 할 일을 나열할 수 있지만, planning-with-files는 계획, 근거, 최종 결과물을 서로 연결된 일반 markdown 파일로 유지해 에이전트가 다시 열고 이어서 확장할 수 있게 합니다.

planning-with-files에는 자동화나 스크립트가 포함되어 있나요?

이 저장소 경로에는 포함되어 있지 않습니다. 가치의 중심은 번들 도구가 아니라 워크플로 패턴 그 자체입니다. 이해하기는 쉽지만, 그만큼 출력 품질은 작업을 얼마나 명확하게 정의하느냐에 크게 좌우됩니다.

planning-with-files 스킬 개선 방법

더 선명한 작업 프레임으로 planning-with-files 시작하기

planning-with-files 결과를 가장 빠르게 개선하는 방법은 범위, 제약, 이름 붙은 결과물을 포함한 작업 프레임을 주는 것입니다. “이걸 조사해줘”는 약합니다. “auth failures를 조사하고, 발견사항은 notes.md에 저장하고, 원인과 수정안을 담은 auth-failure-analysis.md를 만들어라”는 훨씬 강합니다.

파일 생성만이 아니라 파일 업데이트를 요청하기

흔한 실패 패턴은 에이전트가 세 파일을 한 번 만든 뒤 대부분의 작업을 다시 채팅에서 해버리는 것입니다. 주요 단계가 끝날 때마다 task_plan.md를 업데이트하고, 실질적인 발견사항은 notes.md에 저장하라고 명시하세요. 그래야 워크플로가 살아 있습니다.

긴 작업에서는 단계를 명시적으로 나누기

작업이 복잡하다면 task_plan.md를 discovery, analysis, execution, validation, handoff 같은 단계로 구성하라고 요청하세요. 이렇게 하면 구분 없는 체크리스트 하나를 만드는 것보다 스킬이 훨씬 잘 작동합니다.

근거 기준을 지정해 notes 품질 높이기

다음 항목을 요구하면 notes.md의 활용도가 크게 높아집니다.

• source path 또는 참고자료
• 가정
• 열린 질문
• 내려진 결정
• 기각한 대안

이렇게 하면 메모가 단순한 임시 스크래치패드가 아니라 재사용 가능한 작업 메모리로 바뀝니다.

결과물 명세로 일반적인 출력 줄이기

최종 파일이 decision memo인지, migration checklist인지, audit report인지, implementation plan인지 명확히 말하세요. planning-with-files skill은 사용자가 정의한 목표 결과물만큼만 구체적일 수 있습니다.

첫 번째 결과가 약할 때 복구하는 방법

첫 시도가 얕았다고 처음부터 다시 시작할 필요는 없습니다. 대신 에이전트에게 다음을 요청하세요.

1. task_plan.md에서 빠진 단계를 검토하기
2. notes.md에 근거와 미해결 질문을 보강하기
3. 업데이트된 메모를 바탕으로 결과물을 다시 쓰기

대개는 처음부터 새로 프롬프트를 쓰는 것보다 이 방식이 더 빨리 품질을 끌어올립니다.

워크스페이스에 맞게 파일 패턴을 의도적으로 조정하기

기본 3파일 패턴은 최소한의 구조라는 점에서 유용합니다. 팀에 이미 맞춰야 할 구조가 있는 경우가 아니라면 그대로 유지하는 편이 좋습니다. 파일명을 바꾸거나 하위 폴더로 옮길 경우에는 정확한 경로를 지정해 planning-with-files usage가 세션 간에도 일관되게 유지되도록 하세요.

planning-with-files를 소스 점검과 함께 쓰기

이 스킬은 에이전트가 실제로 점검할 자료가 있을 때 더 강해집니다. 예를 들면 저장소 폴더, 문서, 로그, 이슈 목록, 요구사항 등이 있습니다. 추상적인 목표만 주면 워크플로 자체는 돌아가더라도, 생성된 파일이 근거 있는 작업물보다 자리만 채운 초안처럼 보일 수 있습니다.

가장 분명한 부적합 신호를 살피기

planning-with-files가 잘못된 도구라는 가장 명확한 신호는 계획 파일이 지원 수단이 아니라 관료적 부담이 되기 시작할 때입니다. 한 번의 집중된 응답으로 충분히 해결 가능한 작업이라면, 굳이 오버헤드를 추가하지 말고 직접 프롬프트를 쓰는 편이 낫습니다.