OthmanAdi/planning-with-files

Persistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Claude Code, Codex, Cursor, Kiro, OpenCode and 60+ agents via the Agent Skills standard.

해결하는 문제

AI 코딩 에이전트는 컨텍스트 윈도우가 리셋될 때(예: /clear 명령 또는 충돌 시) 중요한 작업 계획과 조사 결과가 손실되는 휘발성 메모리 문제로 인해 어려움을 겪는 경우가 많습니다. 이는 목표 이탈, 반복되는 실수, 세션 리셋 후 사용자가 목표를 수동으로 다시 설명해야 하는 상황을 초래합니다.

작동 방식

이 프로젝트는 파일 시스템을 에이전트의 작업 메모리를 위한 영구 디스크로 취급하는 "3개 파일 패턴"을 구현합니다. 모든 복잡한 작업에 대해 에이전트는 세 가지 특정 Markdown 파일을 생성하고 유지합니다:

task_plan.md: 진행 상황을 위한 단계 및 체크박스를 추적합니다.
findings.md: 조사 노트 및 결정 사항을 저장합니다.
progress.md: 세션 로그 및 테스트 결과입니다.

이 파일들이 사용되도록 보장하기 위해, 프로젝트는 다양한 AI 에이전트(Claude Code, Cursor, GitHub Copilot 등)를 위한 라이프사이클 훅을 제공합니다. 이 훅은 매 턴이 시작될 때 계획을 에이전트의 컨텍스트에 다시 주입하고, 에이전트에게 업데이트를 작성하도록 상기시키며, 에이전트가 중지하기 전에 완료 여부를 확인합니다.

대상 사용자

LLM의 컨텍스트 윈도우 제한을 초과하는 장기적이고 다단계인 작업을 수행하는 AI 코딩 에이전트(Claude Code, Cursor, Pi 등) 사용자.

주요 특징

지속 가능한 메모리: 컨텍스트 삭제, 충돌 및 세션 리셋 후에도 유지됩니다.
광범위한 호환성: Agent Skills 표준을 통해 18개 이상의 플랫폼에서 60개 이상의 에이전트를 지원합니다.
라이프사이클 자동화: 훅을 사용하여 계획 주입 및 업데이트를 선택 사항이 아닌 기계적인 프로세스로 만듭니다.
세션 복구: 이전 세션 데이터를 자동으로 감지하여 에이전트가 현재 단계부터 작업을 재개할 수 있도록 돕습니다.
검증(Attestation): 계획 본문의 변조를 방지하기 위한 SHA-256 잠금 메커니즘이 포함되어 있습니다.