AI 코딩 에이전트의 맥락 손실 문제를 해결하는 파일 기반 계획 시스템
긴 코딩 작업을 하다 보면 에이전트가 중간에 맥락을 잊고 처음부터 다시 시작하는 일이 생깁니다. 이 도구는 에이전트가 작성한 계획과 진행 상황을 프로젝트 폴더 안에 마크다운 파일로 저장해 두어, 세션이 종료되거나 메모리가 초기화되어도 마지막 작업 지점부터 이어서 진행할 수 있게 합니다. 에이전트가 스스로 계획을 관리하고, 실패했을 때 복구하며, 완료 여부를 검증하는 일련의 과정을 자동화하는 구조입니다.
디스크에 저장되는 3가지 파일
이 시스템은 에이전트의 작업 상태를 세 개의 마크다운 파일로 관리합니다. task_plan.md에는 단계별 체크리스트가 들어 있어 작업의 현재 위치를 파악하는 기준이 되고, findings.md에는 조사 중 발견한 내용과 결정 사항이 기록됩니다. progress.md에는 세션 로그와 테스트 결과가 쌓입니다. 이 파일들은 프로젝트 루트 디렉터리에 생성되며, 병렬로 여러 작업을 수행할 때는 .planning/ 폴더 안에 날짜와 슬러그를 붙인 별도 디렉터리를 만들어 격리합니다. 모든 파일은 기본적으로 .gitignore에 포함되어 있어 버전 관리 시스템에 커밋되지 않습니다.
매 턴마다 주입되는 계획과 복구 메커니즘
에이전트가 매 턴 시작할 때 라이프사이클 훅이 발동하여 디스크에 저장된 계획의 핵심 부분을 컨텍스트 윈도우에 다시 주입합니다. 이를 통해 컨텍스트가 가득 차면서 초기 지시사항이 밀려나는 현상, 즉 컨텍스트 로트를 방지합니다. /clear 명령으로 세션을 초기화하거나 크래시가 발생해도, 에이전트는 디스크의 파일만 읽으면 바로 현재 단계로 복귀할 수 있습니다. 이 과정은 에이전트의 이전 대화 기록을 분석하지 않고 프로젝트 파일만 참조하므로 프라이버시와 성능 면에서 유리합니다. 또한 계획이 완료되었는지 확인하는 게이트가 있어, 에이전트가 작업을 미완성 상태로 종료하는 것을 막습니다.
60개 이상의 에이전트 지원 및 설치
이 스킬은 Agent Skills 표준을 기반으로 하여 Claude Code, Codex CLI, Cursor, GitHub Copilot, OpenCode 등 60개 이상의 코딩 에이전트에서 사용할 수 있습니다. 설치 방법은 npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g 명령어를 실행하는 것 하나입니다. Claude Code와 같은 일부 호스트에서는 네이티브 플러그인 형태로 제공되어 더 깊은 통합을 지원합니다. 아랍어, 독일어, 스페인어, 중국어(간체/번체) 등 5개 언어의 번역 버전도 제공되며, 각 언어별 스크립트와 템플릿이 완전히 현지화되어 있습니다. Qoder CLI를 사용하는 경우 Bash와 Python 3.10 이상이 필요합니다.
실제 측정된 성능 개선
프로젝트 측정에 따르면, 디스크 기반 계획 덕분에 에이전트가 /clear 후 다시 방향을 잡는 데 걸리는 턴 수가 13.3턴에서 5.0턴으로 줄었습니다. 또한 블라인드 A/B 테스트 3회 중 3회 모두 이 방식을 적용한 에이전트가 더 나은 결과를 보였습니다. 훅 발동 시간은 v3.6.0 최적화 이후 289ms로 단축되어, 이전의 2.0~2.4초에 비해 훨씬 빠르게 동작합니다. 이는 에이전트가 매 턴마다 계획 컨텍스트를 안정적으로 유지하면서도 지연 시간을 최소화할 수 있음을 의미합니다.
장기 실행 작업에 적합한 이유
이 도구는 특히 수십 분에서 수 시간 이상 걸리는 자율 코딩 작업에 적합합니다. 에이전트가 중간에 맥락을 잃지 않고 일관된 목표를 유지하며, 오류 발생 시에도 복구 가능한 상태로 돌아갈 수 있기 때문입니다. 반면, 단순한 질문 응답이나 짧은 코드 수정 작업에는 과한 구조일 수 있습니다. 완료된 계획 파일은 자동으로 아카이브되지 않으므로, 중요한 내용은 코드나 문서로 승격시켜 별도로 관리하는 습관이 필요합니다.
