OthmanAdi의 `planning-with-files`는 AI 코딩 에이전트가 긴 작업을 할 때 반복해서 부딪히는 문제를 정면으로 다룬다. 모델 컨텍스트는 커져도 여전히 날아갈 수 있고, 사용자는 `/clear`를 누르며, 세션은 중간에 죽는다. 이 저장소의 해법은 계획을 더 길게 말하게 하는 것이 아니라, 계획 자체를 디스크 위의 파일로 남기는 것이다.
핵심 파일은 `task_plan.md`, `findings.md`, `progress.md`다. 에이전트가 해야 할 일, 작업 중 발견한 사실, 현재 진행률을 markdown으로 유지한다. 덕분에 다음 실행이나 다른 에이전트가 같은 작업 디렉터리에서 상태를 다시 읽을 수 있다. README가 Manus-style이라고 부르는 이유도 여기에 있다. 작업 기억을 모델 내부의 휘발성 대화가 아니라, 공유 가능한 작업 산출물로 바꾸는 접근이다.
v3 계열에서 눈에 띄는 기능은 completion gate다. 에이전트가 “완료했다”고 말하는 것과 실제 계획이 끝난 것은 다를 수 있다. 이 프로젝트는 `check-complete.sh`와 PowerShell 대응 스크립트, stop gate를 통해 계획 파일 기준의 완료 상태를 확인한다. 장기 리팩터링이나 여러 phase가 있는 구현 작업에서는 이런 결정적 종료 조건이 꽤 중요하다.
흥미로운 점은 이 repo가 파일 기반 상태의 위험도 함께 드러낸다는 것이다. v3.4.0 릴리스에서는 같은 cwd를 공유하는 one-shot `codex exec` 실행이 미완성 plan을 잘못 읽는 문제를 다뤘다. CI 리뷰 봇이나 read-only 연구 에이전트가 원래 목적과 다르게 plan context에 묶이고, 출력이 `progress.md`로 새거나, `task_plan.md`에 잘못된 완료 기록이 붙는 상황이 있었다. 그래서 `PLANNING_DISABLED=1`이라는 per-invocation opt-out이 추가됐다.
이 디테일은 중요하다. 에이전트의 상태를 파일로 공유하면 복구와 협업은 쉬워지지만, 실행 경계가 흐려질 수 있다. 그래서 v3.3.0의 Pi extension 변경처럼 plan이 존재한다고 바로 hook을 활성화하지 않고 `/plan-execute` 승인 뒤 움직이게 하는 장치도 필요해진다.
`planning-with-files`는 Claude Code, Codex CLI, Cursor, Kiro, OpenCode와 SKILL.md 표준을 통한 60개 이상 에이전트 지원을 내세운다. 특정 도구용 플러그인이라기보다, 에이전트 작업 상태를 파일 시스템에 고정하는 작은 운영 규약에 가깝다. AI 에이전트가 더 오래, 더 안정적으로 일하려면 큰 컨텍스트뿐 아니라 남는 기억과 검증 가능한 완료 조건이 필요하다는 점을 잘 보여주는 프로젝트다.