Claude Code의 계획 이탈을 방지하는 Plan Enforcer 공개

실용적 조언

중요한 의사결정이 필요한 프로젝트라면 decisions.md를 활성화하여 AI의 판단 근거를 기록하라.
에이전트가 자꾸 단계를 건너뛴다면 Enforced 티어를 적용하여 완료 조건을 엄격하게 제한하라.

섹션별 상세

AI 에이전트의 신뢰성 문제를 해결하기 위해 7단계의 세션 관리 체계를 도입했다. Ask, Plan, Exec, Decide, Verify, Land, Receipt로 구성된 각 단계는 반드시 대응하는 파일을 생성하도록 설계되어 작업의 투명성을 확보한다. 이를 통해 사용자는 복잡한 채팅 로그를 뒤지는 대신 생성된 마크다운 파일을 통해 작업의 진행 상황과 의사결정 내역을 즉시 확인할 수 있다.

파일 기반의 기록 시스템인 Ledger를 통해 계획과 실제 코드 변경 사항을 동기화한다. ledger.md는 각 태스크의 상태와 증거 포인터를 추적하며, decisions.md는 계획에서 벗어난 의사결정을 정형화된 스키마로 기록한다. 이러한 구조는 에이전트가 세션을 재시작하는 콜드 컨텍스트 상황에서도 작업 흐름을 잃지 않게 만드는 핵심 장치로 작동한다.

세 가지 수준의 강제 티어(Advisory, Structural, Enforced)를 제공하여 사용자가 통제 강도를 선택할 수 있다. 가장 높은 단계인 Enforced 티어는 훅을 사용하여 Ledger의 기록이 실제 저장소 상태와 일치하지 않을 경우 에이전트의 완료 선언을 차단한다. 이는 에이전트가 작업을 다 끝냈다고 거짓 보고하는 'Silent Failure'를 기술적으로 방지하는 메커니즘이다.

프레임워크 비교 실험 결과, Plan Enforcer는 계획 변조나 작업 누락 부문에서 무결성 감점 0점을 기록했다. GSD 프레임워크가 3점, Superpowers가 10점의 감점을 받은 것과 대조적이며, 특히 중단과 재개가 반복되는 복잡한 시나리오인 Carryover Ladder 테스트에서 H부터 N 등급까지 전 구간을 통과했다. 작성자는 해당 벤치마크의 재현 가능성을 강조하며 관련 방법론을 저장소에 공개했다.

용어 해설

훅(Hooks): — 특정 이벤트가 발생할 때 자동으로 실행되는 코드 메커니즘이다. 이 아티클에서는 Claude Code의 실행 과정에 개입하여 계획 준수 여부를 확인하는 지점으로 활용된다.
원장(Ledger): — 모든 작업 내역과 상태를 기록하는 데이터 구조이다. AI 에이전트가 수행한 각 태스크의 상태, 증거 포인터, 타임스탬프를 추적하여 계획과 실제 작업 간의 일관성을 보장한다.
콜드 컨텍스트(Cold Context): — 이전 대화나 작업 맥락이 없는 상태에서 세션을 새로 시작하는 상황이다. Plan Enforcer는 파일 기반 기록을 통해 이러한 상황에서도 작업의 연속성을 유지하도록 돕는다.

코드 예제

bash

git clone https://github.com/jccidc/.plan-enforcer.git
cd .plan-enforcer
./install.sh

Plan Enforcer를 설치하고 Claude Code에 연동하는 과정

언급된 도구

Claude Code추천

Anthropic의 CLI 기반 AI 코딩 에이전트

Plan Enforcer추천링크

Claude Code의 계획 준수를 강제하는 훅 및 스킬 세트

언급된 리소스

GitHubPlan Enforcer GitHub Repository

문서Raw Scorecards and Methodology