# 파일 기반 계획 (planning-with-files)

> 디스크의 task_plan.md, findings.md, progress.md로 여러 단계의 작업을 관리하고 중단 후에도 이어갈 수 있습니다.

- 카테고리: [작업 분해](https://www.myskills.tools/ko/categories/task-breakdown/)
- 출처: 커뮤니티 · Ahmad Othman Ammar Adi
- 저장소: https://github.com/OthmanAdi/planning-with-files/tree/master/skills/planning-with-files (commit a13b6be · v3.27.0)
- SKILL.md: https://github.com/OthmanAdi/planning-with-files/blob/master/skills/planning-with-files/SKILL.md
- 설치 명령: `npx skills add OthmanAdi/planning-with-files --skill planning-with-files`
- 라이선스: MIT
- 호환 도구: Claude Code, Codex, Cursor, Copilot, OpenCode
- 권한: read-repo ✓, write-files ✓, shell ✓, network ✗
- 상태: 스캔 통과
- 규칙 스캔으로 모든 위험을 찾을 수는 없습니다. 설치 전에 이 스킬의 SKILL.md를 읽고 권한을 확인하세요.
- ⚠ 여러 라이프사이클 훅을 등록합니다. session-catchup.py는 같은 프로젝트의 로컬 세션 기록을 읽을 수 있으며, --replay 발췌는 사용자의 명시적 동의가 필요합니다.

## 핵심 규칙

복잡한 작업은 반드시 task_plan.md를 먼저 만들고, 결정 전에 계획을 다시 읽습니다.

## 실행 단계

1. **상태 복원** — 기존 계획을 찾아 재사용하고, 새 작업은 초기화 스크립트로 계획 파일을 만들며 기존 파일은 덮어쓰지 않습니다.
2. **읽고 나서 결정** — 결정 전에 계획을 다시 읽고, 두 번 행동할 때마다 발견 사항을 findings.md에 씁니다.
3. **행동 후 갱신** — 각 단계가 끝나면 progress.md와 계획의 '다음 단계'를 갱신하고 모든 오류를 기록합니다.
4. **실패 반복 금지** — 3회 오류 규칙에 따라 방법을 바꾸고 같은 실패는 다시 시도하지 않습니다.

## 권한 설명 (SKILL.md 기준)

| 기능 | 필요 여부 | 설명 |
|---|---|---|
| 파일 쓰기 | 필요 | 프로젝트 안에서 계획·발견·진행 파일을 만들고 갱신하며 기존 계획 파일은 덮어쓰지 않습니다. |
| 명령 실행 | 일부 필요 | 포함된 shell/PowerShell 스크립트를 실행하고 프롬프트 제출, 도구 사용, 중지, 압축 시 동작하는 훅을 등록하며, Markdown에 적힌 명령은 실행하지 않습니다. |
| 네트워크 송신 | 필요 없음 | 스킬에는 네트워크 업로드 경로가 없습니다. |

## SKILL.md 프런트매터(YAML)

```yaml
---
name: planning-with-files
description: "Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls."
user-invocable: true
allowed-tools: "Read Write Edit Bash Glob Grep"
hooks:
  UserPromptSubmit:
    - hooks:
        - type: command
          command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=userprompt; exit 0"
  PreToolUse:
    - matcher: "Write|Edit|Bash|Read|Glob|Grep"
      hooks:
        - type: command
          command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=pretool; exit 0"
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=posttool; exit 0"
  Stop:
    - hooks:
        - type: command
          command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=stop; exit 0"
  PreCompact:
    - matcher: "*"
      hooks:
        - type: command
          command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
  version: "3.27.0"
---
```

홈: https://www.myskills.tools/ko/ · URL: https://www.myskills.tools/ko/skills/planning-with-files/