Planning-with-Files는 Claude Code에 더 강력한 계획 시스템을 보완하는 인기 있는 Claude Code 플러그인입니다. 이 글에서는 두 가지 수준에서 이 방식과 AGE (Attractor-Guided Engineering) 시스템의 Plan 개념을 비교합니다.

명세 계층 (Specification Layer - Plan System)

• AGE Plan — docs/plans/00-plan-authoring-and-execution-guide.md에 정의된 24가지 최소 규칙(Minimum Rules)에 의해 정의되는 Attractor-Guided Engineering의 계획 거버넌스 시스템입니다. 특정 툴체인(toolchain)에 의존하지 않는 순수 텍스트 명세입니다.
• Planning-with-Files (PwF) — OthmanAdi/planning-with-files는 Manus의 문맥 엔지니어링(context engineering) 철학에서 유래한 범용 AI 에이전트 기술 플러그인입니다. 3개 파일 구조 + 상태 모델(state model) + 훅(hooks)으로 구성됩니다.

자동화 계층 (Automation Layer - Execution Engine)

• AGE Goal Driver — nop-entropy/ai-dev/tools/opencode-goal-driver/에 위치한 독립적인 프로세스 상태 머신(process state machine)으로, AGE Plan의 텍스트 규칙을 실행 가능한 코드로 엔지니어링합니다. AGE Goal Driver는 AGE Plan을 위한 선택적인 실행 메커니즘입니다.

AGE Plan은 완성이 진정한지(genuine)를 관리하고, PwF는 문맥(context)이 여전히 존재하는지를 관리합니다. 하나는 계획의 잘못된 완성을 방지하고, 다른 하나는 에이전트가 목표를 잃어버리는 것을 방지합니다. 이러한 차이가 이후의 모든 메커니즘 차이를 결정합니다.

1. 설계 지향점 (Design Orientation)

명세 계층 (Specification Layer): AGE Plan vs PwF

자동화 계층 (Automation Layer): AGE Goal Driver vs PwF hooks/loop

2. AGE Plan의 고유 기능 (사양 계층 (Specification Layer))

AGE Plan의 24가지 최소 규칙 (Minimum Rules)은 모두 실행 이력에서 발견된 7가지 범주의 오류에서 기인합니다. 각 규칙은 에이전트가 어느 시점에서 무언가를 "완료됨"이라고 자기기만적으로 표시했기 때문에 추가된 패치 (Patch)입니다. 이 섹션은 AGE Plan 사양 계층에서의 요구 사항만을 설명합니다. 이 규칙들은 AGE Goal Driver에 의존하지 않으며, 수동으로 준수할 때도 동일하게 효과적입니다. AGE Goal Driver의 자동화 구현은 섹션 4에서 다룹니다.

2.1 Closure Gates — 단계 종료 기준과 독립적인 최종 검사 계층

Closure Gates는 계획 수준의 최종 검사 체크리스트로, 각 단계 (Phase) 내의 종료 기준 (Exit Criteria)과는 별개의 검증 계층을 형성합니다. 이 항목들은 작업 목록이 아니라, 자기기만 방지를 위한 판단 기준입니다:

• "범위 내의 활성 결함 (Live defect)이 암묵적으로 보류 (Deferred) 또는 후속 조치 (Follow-up)로 강등되지 않았음"
• "독립적인 서브 에이전트 (Sub-agent) 종료 감사 (Closure audit)가 완료되었고 증거가 기록되었음"
• "범위 내의 확인된 모든 계약 드리프트 (Contract drifts)가 수렴되었음"
• pnpm typecheck && pnpm build && pnpm lint && pnpm test

PwF의 check-complete.sh는 구문 검사(syntactic checks)를 수행합니다. 즉, **Status:** complete (및 fallback 형식인 [complete])의 발생 횟수가 ### Phase의 발생 횟수와 일치하는지 확인합니다. PwF는 의도적으로 의미론적 감사(semantic audits)를 수행하지 않기로 선택했습니다. PwF의 목표는 17개 이상의 플랫폼에 걸친 교차 플랫폼 범용성(cross-platform universality)이며, 의미론적 감사는 프로젝트별로 특화된 완료 기준을 이해해야 하므로 템플릿화하기 어렵기 때문입니다. 그러나 그 대가로,

optional, if time permits, consider, maybe, nice to have와 같은 표현을 사용하여 상태 판정 (status adjudication)을 대체하는 것은 금지됩니다.

## Deferred But Adjudicated (판정되었으나 연기됨) 섹션의 각 연기 항목은 반드시 세 가지 필드를 포함해야 합니다: Classification (watch-only residual | optimization candidate | out-of-scope improvement 중 하나만 허용), Why Not Blocking Closure (명시적 이유), Successor Required (예/아니오). 이유가 없는 연기 항목은 미완료(incomplete)로 간주됩니다.

PwF의 상태는 오직 pending → in_progress → complete로만 구성되며, "판정되었으나 연기됨"을 위한 중간 상태는 존재하지 않습니다.

2.4 비저하 항목 (Non-Degradable Items) + 테스트 전략 (Test Strategy) + 실패 경로 (Failure Paths)

이 세 가지 규칙은 결합하여 AGE Plan의 "비저하 (non-degradable)" 경계를 형성합니다.

비저하 항목 (Non-Degradable Items). 다음 다섯 가지 범주의 항목은 연기(deferred) 또는 비차단(non-blocking) 항목으로 분류될 수 없습니다: 린트 규칙 (lint rules), 라이브 결함 (live defects), 공개 계약 드리프트 (public-contract drift), 소유자 문서 드리프트 (owner-doc drift), 필수 집중 검증 (necessary focused verification). 각 실행 항목은 Fix | Decision | Proof | Follow-up 중 하나로 태깅되어야 합니다. 확인된 라이브 결함은 오직 Fix로만 분류될 수 있으며, Follow-up으로 강등될 수 없습니다.

테스트 전략 계층화 (Test Strategy Tiering). 모든 계획은 위험도에 부합하는 테스트 투자 전략을 선언해야 합니다: 인증(Auth) 및 외부 API 계약은 반드시 자동화되어야 합니다 (Fix 항목 이전에 Proof 항목 선행); 일반적인 기능은 테스트를 권장합니다; 행동 변화가 없는 순수 문서는 정당한 사유를 바탕으로 해당 없음(not applicable)을 선언할 수 있습니다.

실패 경로 (Failure Paths). 템플릿은 ## Failure Paths 테이블을 제공하며, 이는 오류 처리, API 계약, 인증 또는 외부 통합을 포함하는 계획에 권장됩니다. 각 행에는 트리거 조건, 예상 동작 (상태 코드 포함), 재시도 가능성 (retryability), 그리고 사용자에게 보이는 성능이 포함됩니다. 이는 계획 작성자가 해피 패스 (happy paths)와 함께 언해피 패스 (unhappy paths)를 고려하도록 강제합니다.

PwF의 오류 처리는 3-Strike 오류 프로토콜 (retry escalation)과 발생한 오류 (Errors Encountered) 테이블 (사후 기록)로 제한되며, 예외 경로 (exception paths)에 대한 사전 명세는 제공하지 않습니다.

2.5 현재 기준선 (Current Baseline) + 단계에 내장된 문서 판정 (Documentation Adjudication Embedded in Phases)

계획(plan)을 작성하기 전에, 먼저 라이브 저장소(live repo)의 현재 상태를 확인하여 "확립된 사실(established facts)", "완료되었으나 기존 문서가 동기화되지 않은 사실(facts that have been completed but old documentation hasn't synchronized)", 그리고 "실제 남아있는 격차(the real remaining gaps)"를 항목별로 나열해야 합니다. 목표(Goal)는 베이스라인(Baseline)이 아닙니다. 목표는 당신이 가고자 하는 곳이며, 베이스라인은 당신이 현재 있는 곳입니다.

각 단계(Phase)의 종료 기준(Exit Criteria)에는 다음이 포함됩니다: "만약 이 단계가 라이브 베이스라인을 변경한다면, 관련 docs/architecture/가 업데이트되어야 합니다. 그렇지 않다면, No owner-doc update required라고 명시적으로 기재하십시오." 문서 동기화(Documentation synchronization)는 단계(Phase) 내에서 수행해야 하는 작업이지, 마무리 작업(wrap-up work)이 아닙니다.

AGE 목표 드라이버 자동화 (AGE Goal Driver Automation): detectStartPhase는 시작 시 어디서부터 계속할지를 자동으로 결정합니다. check-plan-status.mjs를 실행하여 미완료된 계획이 있는지 확인하고, 감사(audit) 디렉토리가 존재하는지 확인합니다. 미완료된 계획이 있다면 실행(execution) 단계로 점프하고, 감사 디렉토리가 존재하면 계획(planning) 단계로 점프하며, 둘 다 아니라면 감사(auditing)부터 시작합니다. 순수 스크립트 로직이며, LLM 호출은 없습니다.

2.6 과거 계획 보호 + 과도한 분할 방지 (Historical Plan Protection + Anti-Excessive Splitting)

• 규칙 20 (과거 보호, Historical Protection): 이미 completed로 표시된 과거 계획은 기본적으로 역사적 기록으로 취급되며, 사양(specification)의 진화, 템플릿 변경 또는 코드 진화로 인해 능동적으로 재작성되지 않습니다.
• 규칙 21-24 (과도한 분할 방지, Anti-Excessive Splitting): 단순히 발견 사항(findings)이 많거나 파일 크기가 30 KB에 근접한다고 해서 계획을 분할하지 마십시오. 동일한 컴포넌트, 동일한 모듈 또는 동일한 소유자 문서(owner-doc)에 속하는 여러 발견 사항은 가급적 하나의 소유자 계획(owner plan)으로 병합해야 합니다. 분할은 종결 의미론(closure semantics)이 갈라질 때만 트리거됩니다.

3. PwF의 고유 기능 (사양 + 자동화 레이어) (Unique Features of PwF (Specification + Automation Layer))

PwF의 핵심 관심사는 단 하나입니다: 에이전트가 긴 작업(long tasks)을 수행하는 동안 문맥(context)을 잃어버리는 것을 방지하는 것입니다.

3.1 세 파일 분리 + 보안 격리 (Three-File Separation + Security Isolation)

task_plan.md (로드맵) + findings.md (지식 베이스) + progress.md (세션 로그). 이 세 파일은 명확한 책임과 업데이트 빈도를 가집니다:

findings.md의 존재는 단순한 노트 그 이상입니다. 그 설계에는 보안 고려 사항이 포함되어 있습니다. task_plan.md는 모든 도구 호출(tool call) 시 훅(hook)에 의해 에이전트의 컨텍스트(context)로 자동 주입됩니다. 만약 외부 웹 검색 결과가 task_plan.md에 기록된다면, 그 안에 포함된 적대적 지시문(adversarial instructions)이 모든 도구 호출 시 증폭될 것입니다. SKILL.md 보안 경계(Security Boundary)는 외부 콘텐츠를 findings.md에는 작성할 수 있지만, task_plan.md에는 작성할 수 없음을 명시적으로 규정합니다.

AGE Plan은 계획 시스템 내에서 연구 결과와 외부 콘텐츠를 관리하지 않습니다. 실행 중에 생성된 이러한 자료들은 실제 상황에 따라 에이전트에 의해 적절한 위치에 저장되며, 계획 파일 내에는 포함되지 않습니다.

3.2 훅 자동 주입 시스템 (Hook Auto-Injection System)

IDE 생명주기(lifecycle) 동안 다섯 가지 유형의 훅이 자동으로 실행되어, 에이전트가 의식적으로 규칙을 따를 필요를 없애줍니다:

AGE Plan의 규칙 계층은 자동 주입 메커니즘이 없으며 에이전트가 AGENTS.md를 따르는 것에 의존합니다. AGE Goal Driver 또한 계획 콘텐츠를 주입하지 않고, 프로그래밍 방식의 출력 파싱(output parsing)을 위해 XML 태그 프로토콜을 사용합니다. PwF는 세 번째 경로를 나타냅니다. 즉, 에이전트가 인지하지 못하는 사이에 훅을 사용하여 계획을 컨텍스트에 자동으로 채워 넣는 방식입니다.

3.3 이중 계층 보안 방어 (Two-Layer Security Defense)

첫 번째 계층(기본 활성화): 구분자 프레이밍(delimiter framing). 훅으로 주입된 계획 콘텐츠는 ===BEGIN PLAN DATA=== / ===END PLAN DATA===로 감싸져 구조화된 데이터로 표시되며, 에이전트에게 그 내부의 명령형 텍스트(imperative text)를 실행하지 않도록 지시합니다.

두 번째 계층 (선택 사항): SHA-256 증명 (attestation). /plan-attest는 task_plan.md의 해시(hash)를 계산하고 저장합니다. 모든 훅(hook)은 주입(injection) 전에 해시를 비교하며, 만약 일치하지 않으면 주입을 거부하고 [PLAN TAMPERED]를 출력합니다. PreCompact 훅 또한 Plan-SHA256을 출력하여, 압축(compaction) 이후에도 에이전트가 계획이 변조되지 않았음을 여전히 검증할 수 있도록 보장합니다.

AGE Plan은 에이전트와 파일 시스템을 신뢰하기 때문에 이와 동등한 보안 메커니즘이 없습니다.

3.4 세션 캐치업 (Session Catchup) — 자동 세션 복구

session-catchup.py는 /clear 또는 문맥(context) 재설정 이후, IDE의 세션 저장소(session store)로부터 마지막 계획 파일 업데이트 이후에 발생한 대화를 자동으로 추출하여 캐치업 보고서(catchup report)를 생성합니다.

AGE Plan은 docs/logs/를 통해 수동으로 문맥을 재구성하며, 자동 세션 복구 메커니즘이 없습니다. AGE Goal Driver의 detectStartPhase는 저장소(repo) 상태를 확인하여 어디서부터 계속할지를 결정합니다. 이는 대화 기록을 복구하는 것이 아니라, 실행 위치(execution position)만을 복구합니다.

3.5 병렬 작업 격리 (Parallel Task Isolation)