ptw가 뭔데?

Hermes Agent를 쓰면서 “planning with files”라는 기능이 있다는 걸 알게 됐습니다. 줄여서 ptw라고 부릅니다.

간단히 말하면, 에이전트가 복잡한 작업을 할 때 마ardown 파일로 계획을 외부에 기록해서 컨텍스트 윈도우가 압축되어도 진행 상황을 잃지 않게 하는 메커니즘입니다.

실제로 RTK 설치하면서 이걸 써봤는데, 트리거가 자동이 아니라 수동이라는 걸 알게 됐습니다. 그래서 정리해두려고 합니다.

왜 필요한가

LLM 에이전트는 컨텍스트 윈도우가 유한합니다. 긴 세션이 되면 이전 내용이 압축(compaction)되고, 그 과정에서 “지금 어디까지 했지?”가 흐려집니다.

ptw는 이 문제를 파일 시스템으로 해결합니다:

이 파일들은 ~/.planning/<slug>/ 에 저장되고, 매 턴마다 에이전트 프롬프트에 주입됩니다.

트리거: 자동이 아닙니다

여기서 핵심입니다. ptw는 자동으로 활성화되지 않습니다.

제가 소스코드를 파본 결과:

1. 파일 생성 — /pwf 슬래시 명령 또는 planning_with_files_init 툴을 내가 명시적으로 호출해야 함
2. 컨텍스트 주입 — pre_llm_call 훅이 매 턴마다 실행. 프로젝트 디렉토리에 task_plan.md이 있으면 프롬프트에 삽입
3. progress 리마인드 — post_tool_call 훅이 파일 쓰기 후 “progress.md 업데이트해”라고 리마인드

즉, 트리거 체인은 이렇습니다:

내가 /pwf 또는 init 호출
  → 파일 3개 생성 (빈 템플릿)
  → 다음 턴부터 pre_llm_call 훅이 파일 내용 주입
  → 내가 파일에 내용 채움
  → 매 턴 자동 주입 (파일 존재하는 한)

복잡도 감지 로직이 없습니다. “이 작업은 5단계 이상이라 계획 파일 만들자” 같은 자동 판단은 안 됩니다.

legacy mode vs slug mode

/pwf를 치면 두 가지 모드로 생성됩니다:

• root (legacy mode): 현재 작업 디렉토리 바로 아래에 task_plan.md 생성
• slug mode: ~/.planning/<slug>/ 아래에 생성 (세션 격리)

slug는 URL, 작업명 등에서 자동 생성됩니다. 예를 들어 RTK 설치할 때:

~/.planning/2026-10-02-url-https-github-com-rtk-ai-rtk/
├── task_plan.md
├── findings.md
└── progress.md

여러 개가 있으면 PLAN_ID=<slug> 환경변수로 선택합니다.

실제로 써본 느낌

RTK 설치 작업은 사실 3단계(다운로드 → 실행 → PATH 확인)라 ptw 없이도 충분했습니다. 그래서 저는 안 썼고, 빈 파일만 남았습니다.

ptw가 빛을 보는 건 이런 경우입니다:

• 10단계 이상의 멀티스텝 리서치
• 컨텍스트 압축이 여러 번 일어나는 긴 세션
• 여러 에이전트(서브에이전트)가 협업하는 작업
• “어제까지 뭘 했지?”를 다음 세션에서 이어야 하는 경우

정리

결국 상황에 맞게 고르면 됩니다. 정답은 없습니다.