ONEDEV

planning-with-files

othmanadi파일 736개

★ 26,928주당 +174조회 6

무엇인가

planning-with-files는 장기 실행 에이전트 작업의 계획 상태를 컨텍스트 윈도우가 아니라 파일시스템에 두도록 규율하는 스킬이다. 목표 정의, 단계 진행, 조사 결과, 테스트 결과, 완료 판정이라는 작업 상태 관리 영역을 담당하며, 컨텍스트 리셋·압축·크래시 이후에도 동일한 단계에서 재개할 수 있는 상태를 남기는 것을 목적으로 한다.

어떻게 동작하나

동작은 세 파일과 훅으로 구성된다. 프로젝트 루트에 task_plan.md(단계와 체크박스), findings.md(조사 노트와 결정), progress.md(세션 로그와 테스트 결과)를 만들고, UserPromptSubmit 훅이 매 턴 task_plan.md에서 읽은 내용을 ===BEGIN PLAN DATA=== 블록 형태로 컨텍스트에 주입한다. 계획은 해시로 검증되며, 결정적 완료 게이트가 계획이 완료를 보고할 때까지 에이전트의 정지를 붙잡는다. 병렬 작업은 .planning/YYYY-MM-DD-slug/ 디렉터리에 같은 세 파일을 두고 .active_plan으로 선택한다. 순수 마크다운이며 기본적으로 gitignore되고, 그 외 런타임 상태는 두지 않는다.

무엇과 다른가

프롬프트에 계획을 적어 두거나 컨텍스트 안에 사는 할 일 목록과 구조적으로 다르다. 전자는 에이전트가 따를 수도 있는 지시지만, 이 스킬은 매 턴 발동하는 훅과 디스크 위의 계획 파일, 그리고 정지를 제어하는 완료 게이트로 강제된다. 장기 실행 기능은 계획별 opt-in이며 모드 마커를 설정하지 않으면 이전 동작과 바이트 단위로 동일하다.

어떻게 쓰나

설치는 경로가 나뉜다. 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 한 줄로 Agent Skills 표준을 통해 설치한다. 버전을 고정하거나 저장소에 벤더링하려면 npm install planning-with-files를 쓰고, Pi Coding Agent는 pi install npm:planning-with-files, Hermes Agent는 hermes skills install 및 hermes plugins install/enable 경로를 쓴다.

전제와 한계

전제와 한계가 있다. Agent Skills 표준을 통해 60개 이상 에이전트에서 동작하고 Claude Code·Codex CLI·Pi·Hermes Agent에는 네이티브 플러그인이 있다. npm 패키지는 SKILL.md·scripts/·templates/만 담고 훅을 스스로 등록하지 않는다. 자동 복구는 프로젝트 파일만 읽으며, 같은 프로젝트의 로컬 에이전트 세션 기록을 집계하거나 제한적으로 재생하려면 명시적 catchup 모드가 필요하다. README에 인용된 5.0턴 대 13.3턴 수치는 이전 기본 동작으로 측정된 내부 벤치마크이며 현재 기본값에 대한 새 측정값이 아니다.

관련 논문 2

유사 스킬