장기 실행 코딩 에이전트를 위한 지속적 파일 기반 계획 하네스
README 링크에서 발견 · 2 days ago
Agent는 /clear 후에도 살아남기 위해 task_plan.md, findings.md, progress.md를 디스크에 유지합니다.
What they did
Agent Skills CLI를 통해 planning-with-files 스킬을 전역으로 설치하고, 해당 스킬의 라이프사이클 훅이 리포지토리 내에서 세 개의 파일로 구성된 플래닝 루프를 이끌도록 했다. 모델이 잊어버릴 수 있는 프롬프트에 의존하는 대신, 훅이 매 턴마다 실행되어 현재 계획 컨텍스트를 주입한다. 그 결과 에이전트는 task_plan.md를 읽고, 발견 사항을 findings.md에 추가하며, 단계 상태를 progress.md에 기록한다. 컨텍스트 윈도우가 가득 차거나 작업 도중 /clear를 실행했을 때, 에이전트는 디스크에 있는 파일을 다시 읽고 처음부터 시작하는 대신 중단된 지점에서 이어서 작업했다. 또한 Anthropic Skills와 함께 사용하여 플래닝 규율과 도메인별 스킬 지침이 함께 로드되도록 했고, 이를 통해 수 시간에 걸친 리팩터링 동안 계획이 권위 있는 기준으로 유지되었다.
How it went
계획은 /clear, compaction, 세션 크래시를 견뎌냈고, 에이전트는 단계 목록을 다시 도출하지 않고 그대로 이어받았다. 이 repo는 96.7%의 assertion 통과율과 3/3 blind A/B 승리를 내세우며, 긴 작업에서 워크플로가 눈에 띄게 더 안정적으로 느껴졌다. 완성도도 높다: Claude Code, Codex CLI 등을 위한 네이티브 플러그인과 60개 이상의 에이전트에 걸친 설치를 지원한다.
Worth knowing
자동 복구는 프로젝트 파일만 읽습니다. 로컬 에이전트 세션 기록을 집계하거나 재생하려면 명시적인 catchup 모드가 필요합니다. 훅은 호스트별로 설치해야 하며, 오래된 plan 파일은 정리하지 않으면 에이전트를 오도할 수 있습니다. 벤치마크 수치는 독립적인 감사가 아니라 프로젝트 자체의 evals에서 나온 것입니다.
Wiring
Agent Skills CLI로 스킬을 전역 설치하거나, 호스트(Claude Code, Codex CLI, OpenCode 등)에 맞는 네이티브 플러그인을 사용하세요. 라이프사이클 훅을 활성화하여 매 턴마다 실행되고 플랜 컨텍스트를 주입하도록 하세요. 이 스킬은 프로젝트 루트에 task_plan.md, findings.md, progress.md를 유지하며, 에이전트는 세션 시작 시와 /clear 또는 컴팩션 이후에 이들을 읽고, 단계가 완료될 때마다 업데이트를 기록합니다. 선택적으로 Anthropic Skills를 함께 로드하여 도메인 지침과 플래닝 규율이 공존하도록 하세요. 세 파일을 버전 관리에 포함하거나 의도적으로 gitignore하고, 완료된 플랜을 정리하여 오래된 컨텍스트를 방지하세요.
Try it yourself
# planning-with-files 스킬 설치 및 멀티스텝 작업 계획 ## 1단계: 스킬 설치 ```bash npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g ``` 설치 후 이 저장소에서 스킬이 활성화됩니다. 이제 코드를 건드리기 전에 세 개의 파일을 먼저 생성합니다. --- ## 2단계: 작업 파일 생성 (코드 변경 전) ### `task_plan.md` ```markdown # Task Plan: 테스트 스위트 감사, flaky 테스트 수정, CI 업데이트 ## 목표 테스트 스위트를 감사하고, flaky 테스트를 안정화하며, CI 파이프라인을 개선한다. ## 단계 ### 1. 테스트 스위트 감사 - [ ] 테스트 러너/프레임워크 확인 (Jest, Vitest, pytest 등) - [ ] 전체 테스트 목록 및 커버리지 현황 파악 - [ ] CI에서 실행되는 테스트 범위 확인 - **수용 기준**: 모든 테스트 파일 목록화, 커버리지 리포트 생성, CI 설정 문서화 ### 2. Flaky 테스트 식별 - [ ] 반복 실행(예: 10회)으로 불안정 테스트 탐지 - [ ] 타이밍/순서/네트워크 의존성 분석 - [ ] 각 flaky 테스트의 근본 원인 기록 - **수용 기준**: flaky 테스트 목록과 원인 분석이 findings.md에 기록됨 ### 3. Flaky 테스트 수정 - [ ] 타이밍 의존성 제거 (fake timers, 명시적 대기) - [ ] 테스트 격리 (공유 상태 제거) - [ ] 비결정적 의존성 모킹 - **수용 기준**: 수정된 테스트가 10회 연속 실행에서 100% 통과 ### 4. CI 업데이트 - [ ] flaky 재시도/격리 전략 추가 - [ ] 테스트 병렬화 및 캐싱 개선 - [ ] 커버리지 리포팅 통합 - **수용 기준**: CI 파이프라인 통과, 실행 시간 개선, 커버리지 리포트 게시 ## 완료 정의 - 모든 flaky 테스트 안정화 - CI 그린 상태 유지 - 세 파일(task_plan, findings, progress) 최신 상태 ``` ### `findings.md` ```markdown # Findings ## 감사 결과 (아직 없음 — 1단계 진행 후 기록) ## Flaky 테스트 원인 (아직 없음 — 2단계 진행 후 기록) ## CI 관찰 사항 (아직 없음 — 4단계 진행 후 기록) ``` ### `progress.md` ```markdown # Progress ## 상태: 시작 전 | 단계 | 상태 | 비고 | |------|------|------| | 1. 테스트 스위트 감사 | ⬜ 대기 | | | 2. Flaky 테스트 식별 | ⬜ 대기 | | | 3. Flaky 테스트 수정 | ⬜ 대기 | | | 4. CI 업데이트 | ⬜ 대기 | | ## 로그 - (없음) ``` --- ## 3단계: 실행 및 파일 갱신 규칙 각 단계를 마칠 때마다 **세 파일을 모두 갱신**합니다: - `task_plan.md`: 해당 단계 체크박스 완료 처리 - `findings.md`: 새로 발견한 사실 추가 - `progress.md`: 상태 표 업데이트 + 로그 한 줄 추가 예시 (1단계 완료 후): ```markdown # progress.md (발췌) | 1. 테스트 스위트 감사 | ✅ 완료 | Vitest, 42개 파일, 커버리지 68% | ## 로그 - 1단계 완료: Vitest 확인, 42개 테스트 파일, 커버리지 68% ``` --- ## 4단계: 컨텍스트 리셋 시뮬레이션 ``` /clear ``` 리셋 후 재개 절차: 1. `task_plan.md` 읽기 → 남은 단계와 수용 기준 확인 2. `progress.md` 읽기 → 마지막 완료 단계와 다음 단계 확인 3. `findings.md` 읽기 → 지금까지의 발견 사항 복원 4. **저장소 전체를 다시 읽지 않고** 다음 미완료 단계부터 재개 이 세 파일만으로 다음을 복원할 수 있어야 합니다: - 무엇을 하고 있는가 (task_plan) - 어디까지 했는가 (progress) - 무엇을 알아냈는가 (findings) --- ## 확인 필요 사항 실제 실행을 위해 다음 정보가 필요합니다: 1. **테스트 프레임워크** — 저장소의 `package.json` / `pyproject.toml` 등을 확인해야 합니다 2. **CI 시스템** — GitHub Actions, GitLab CI 등 3. **flaky 테스트 재현 조건** — 반복 실행 횟수, 환경 변수 이 정보를 알려주시면 1단계 감사부터 실제로 진행하겠습니다. 또는 저장소 구조를 공유해 주시면 제가 직접 확인하겠습니다.