PlanGate는 v3에서 v8.6까지의 1개월 동안, 'AI에게 작업을 시키는 메커니즘'에서 'AI를 멈추고, 관측하며, 재현 가능하게 만드는 통제 하네스 (Control Harness)'로 성장했습니다.

PlanGate는 AI 코딩 에이전트 (AI Coding Agent)를 '승인한 후 동작시키기' 위한 하네스입니다.

v3.0.0 (2026-04-09)에서 AI 주도 개발 워크플로 (AI-driven development workflow)의 기반을 내놓은 후, v8.6.0 (2026-05-04)에서 Metrics v1과 Governance가 갖춰지기까지, 약 1개월 동안 24번의 릴리스를 거듭해 왔습니다.

각 버전은 개별 CHANGELOG를 읽으면 추적할 수 있지만, "왜 그 순서로 기능이 쌓여 올랐는가"는 시계열을 조망하지 않으면 보이지 않습니다.

이 기사는 그 1개월간의 변천을 4가지 설계 축으로 재정리하는 회고입니다. 다음 v8.7 이후를 위한 지도로서 사용할 수 있도록, 각 축의 도달점과 미해결 논점도 함께 작성했습니다.

TL;DR

PlanGate의 진화는 독립된 기능 추가의 연속이 아니라, 4가지 설계 축이 병행하여 성장해 온 결과로 정리할 수 있습니다.

v8.6 시점에서는 모드 선택, GatePolicy, Workflow DSL, CLI, Provider RFC, JSON Schema, eval runner, Metrics v1이 갖춰져, PlanGate는 "실행 전에 계약하고, 실행 중에 멈추며, 실행 후에 관측하는" 구조가 되었습니다.

"멈추기 위한 메커니즘"과 "멈춘 것을 관측하는 메커니즘"이 별도로 성장하여 v8.6에서 합류한 것이 이 1개월의 본질입니다.

이 기사의 대상 독자

• AI 코딩 에이전트의 운영 설계를 자신의 프로젝트에 도입하려고 검토 중인 사람
• PlanGate를 v8 계열부터 사용하기 시작하여, 과거의 설계 판단 경위를 알고 싶은 사람
• "게이트형 워크플로 (Gate-type workflow)", "하네스 엔지니어링 (Harness Engineering)"의 설계 트레이드오프 (Trade-off)에 관심이 있는 사람
• 자신의 팀의 개발 통제를 감각이 아닌 문서와 스키마 (Schema)로 운영하고 싶은 사람

축 1: 멈추기 — 게이트 설계의 진화

PlanGate의 핵심은 "승인 없이, 코드 없이"라는 Iron Law입니다. 이 한 줄을 성립시키기 위한 메커니즘이 4단계로 성장해 왔습니다.

v3.0.0 (2026-04-09) — 게이트형 모델의 도입

• PBI로부터 Plan / ToDo / Test Cases를 생성하는 기본 플로를 정의
• 계획 승인 후 Agent 실행으로 진행
  게이트형 모델을 처음으로 도입 - 이 시점에서는 "승인 → 실행"의 전후 관계를 Markdown 규약으로 정의한 단계였으며, 게이트 판정값의 기계화는 이제 시작 단계였음

v4.0.0 (2026-04-09) — C-3 삼치화와 V-1~V-4의 윤곽

• 게이트 판정을 APPROVE / CONDITIONAL / REJECT의 삼치 (C-3)로 정리 - V-1~V-4 검증 단계 (구현 후 검증)를 도입
• "멈출 것인가 진행할 것인가"의 이지선다에서, "조건부로 진행한다"가 운영상의 전제가 됨

v5.0.0 ~ v7.x — 하네스 엔지니어링으로의 확장

• v5.0.0에서 L-0 린터 (Linter) 자동 수정 루프를 설계하여 검증 단계의 기반을 마련
• v6.0.0에서 Context Engineering과 18개 에이전트 체제, 태스크 규모별 모드 분류의 방향성을 정리
• v7.0.0에서 Workflow / Skill / Agent의 3층 구조로 재구축 (후술할 "축 3")
• v7.4.0에서 Artifact JSON Schema 7종과 c3.json

gate enforcement spec을 투입하여, 게이트가 기계 판독 가능(machine-readable)해졌다

여기까지 '게이트 사양'은 확정되었지만, 실제로 에이전트(Agent)를 중단시키는 강제력은 아직 규약(convention) 수준이었습니다.

v8.4.0 〜 v8.5.0 (2026-05-01) — Hook enforcement를 통한 런타임 중단

예를 들어 C-3 승인이 통과되지 않은 상태에서 bin/plangate exec를 실행하려고 하면, EH-2 hook이 즉시 차단합니다. "구현으로 넘어가기 전에 반드시 승인을 받아야 한다"라는 불변 조건(invariant)이 규약이 아닌 실행 시점(runtime)에 지켜지게 된 것이 이 단계입니다.

• v8.4.0에서 3 mode hook 설계(default warning / strict block / bypass escape)를 도입하고, 3가지 hook(EH-2: C-3 승인 없는 구현 감지 / EHS-2: handoff 필수 요소 체크 / EHS-3: fix loop 상한)을 구현
• v8.5.0에서 나머지 7개 hook을 완료하여, 10/10 hooks 구현 완료
• PreToolUse 계열: plan.md 없는 production code 편집을 block, c3.json의 plan_hash와 현재 plan.md를 대조, forbidden_files glob 패턴으로 scope 외 편집을 block
• CLI 계열: V-1 전의 test-cases.md 부재 시 warn / block, PR 생성 전의 verification evidence 부재 시 block, merge 승인 누락 감지, V-3 review의 mode 연계 필수화

이로써 "게이트가 규약상 존재하지만 구현이 이를 위반하는" 기존의 허점이 Claude Code / Codex의 실행 레이어(execution layer)에서 차단되었습니다.

v8.6.0 (2026-05-04) — 차단 횟수를 관측하는 Metrics v1

• 11개 이벤트의 JSON Schema(task_initialized / plan_generated / c3_decided / exec_started / hook_violation / v1_completed / fix_loop_incremented / external_review_completed / pr_created / c4_decided / handoff_completed)를 정의
• plangate metrics --collect / --report를 통해 TASK 디렉토리에서 자동 도출
• v8.5.0까지의 "차단"과 v8.6.0에서 추가된 "관측"이 결합

이를 통해 예를 들어 "특정 PBI에서 forbidden_files의 hook violation이 많이 발생한다", "C-3가 CONDITIONAL이 되기 쉬운 mode가 있다"와 같은 경향을 주 단위로 회고하고, 다음 스프린트의 allowed_files 설계나 모드 재분류의 판단 근거로 삼을 수 있습니다. 관측 대상이 정량화됨에 따라, 하네스(harness) 개선에 대한 논의가 감상 기반에서 건수 기반으로 변화했습니다.

게이트 설계의 도달점은 "멈춰야 할 곳에서 멈추고, 멈춘 횟수를 나중에 비교할 수 있는 상태"입니다.

축 2: 선택하기 — 리스크별 모드의 정교화

PlanGate의 모드 분류는 태스크의 규모와 리스크에 따라 게이트의 엄격함을 조절하는 메커니즘입니다. 초기 2단계 분류에서 시작하여, 기계 판독 가능한 GatePolicy까지 단계적으로 성장해 왔습니다.

v6.0.0 — 태스크 규모별 모드 분류의 방향성

• Light / Full의 2단계 분류를 기점으로, ultra-light / light / standard / high-risk / critical의 5단계로 나아가는 방향성을 정리
• 이 시점에서는 적용 게이트와의 대응이 문서 표 수준이었으며, docs 측의 "Light / Full" 표기가 완전히 5개 모드 표로 대체되는 것은 v8.2.0입니다.

v7.2.0 (2026-04-26) — GatePolicy와 skill-policy-router

• Intent + Mode → GatePolicy(requiredSkills / requiresEvidence / requiresFailingTestFirst / requiresWorktree)를 기계 판독 가능(machine-readable)하게 구현
• design-gate / review-gate / completion-gate / worktree-policy를 규칙화하여 mode로부터 자동 적용
• full → high-risk로의 이름 변경 완료 (v7.3.0에서 명칭 통일)

v8.0.0 (2026-04-27) — Workflow DSL을 통한 모드 완전 기계화

• workflows/ 하위에 5개 모드 분량의 YAML (ultra-light / light / standard / high-risk / critical) 배치 - 각 페이즈(phase)의 완료 조건·입출력·담당 에이전트(agent)를 기계 판독 가능하게 정의
• tests/run-tests.sh를 통해 CLI 테스트 4건 및 CI 통합 (이후 v8.5에서 42개 테스트까지 확대)

v8.1.0 (2026-04-27) — validate --mode를 통한 게이트 요구사항 동적 결정

• bin/plangate validate --mode <mode>가 workflows/<mode>.yaml을 읽고, gate_enforcement.c3.required_artifacts로부터 artifact 리스트를 동적으로 결정 - v7.4에서 작성한 사양(c3.json)을 v8.0의 DSL과 연결하여, 모드별로 artifact 필수 리스트가 자동으로 전환되는 상태에 도달

도달점은 "모드를 선언하는 것만으로 요구사항·게이트·테스트의 엄격함이 연동되어 전환되는 것"입니다.

축 3: 실행하기 — CLI · Provider · Orchestrator

"누가·무엇을·어떤 순서로 실행할 것인가"에 대한 정리가 3단계로 진행되었습니다.

v7.0.0 (2026-04-20) — Workflow / Skill / Agent의 3계층 분리

• docs/plangate-v7-hybrid.md를 통해 3계층 아키텍처(architecture)를 정본화 - WF-01~WF-05 Workflow 정의
• v7용 Skill / Agent의 책임을 분리
• bin/plangate CLI 등장

v7.5.x (2026-04-27) —

• v7.5.1에서 CLI v0.1.0 투입: init / doctor / status / validate / abort / timeline / resume
• v7.5.2에서 macOS 환경을 위한 python3 수정
• "문서에 적힌 절차"를 "명령어 한 번"으로 대체할 수 있는 기반 마련

v8.0.0 ~ v8.1.0 — Provider RFC에서 외부 에이전트 실행으로

• v8.0.0에서 docs/rfc/provider-gemini-cli.md (외부 리뷰 역할)와 docs/rfc/provider-opencode.md (구현 에이전트 역할)를 책정 - v8.1.0에서 bin/plangate review (Gemini CLI 호출)와 bin/plangate exec (OpenCode 실행, C-3 미통과 시 block)를 구현 - "Claude Code 전용"이었던 구조가 "Provider 교체 가능"하도록 확장

v8.2.0 (2026-04-28) — Parent-Child PBI Orchestrator Mode

• docs/orchestrator-mode.md에서 부모 PBI → 자식 PBI 분해 / 통합 Workflow를 정본화 - docs/schemas/child-pbi.yaml에서 자식 PBI YAML 스키마(schema)를 정의 - 이후 v8.3.0에서 실운용 케이스 제1호로 PBI-116을 4개 페이즈로 완주

실행층의 도달점은 "단일 에이전트의 직렬 실행에서, 다중 에이전트·다중 Provider의 병렬·통합 실행"까지 스코프(scope)가 확장된 상태입니다.

축 4: 증명하기 — 계약 · Schema · Metrics

"규약으로서 작성하기"에서 "스키마(schema)로 검증하기"로의 이행이 3단계로 진행되었습니다.

v7.4.0（2026-04-26）— 7종의 Artifact JSON Schema

• schemas/ 디렉토리에 pbi-input / plan / todo / test-cases / review-self / review-external / handoff의 7가지 스키마(schema) 추가
• docs/working/templates/에 프런트매터(frontmatter) (task_id / artifact_type / schema_version / status) 추가
• c3.json의 게이트 강제 사양(gate enforcement spec)을 처음으로 정의

v8.3.0（2026-04-30）— Outcome-first contract 및 Prompt Assembly

• docs/ai/core-contract.md에서 7가지 철칙(Iron Law)을 outcome-first 형식으로 정본화 (GPT-5.5 이후 모델의 특성에 대응)
• docs/ai/model-profiles.yaml 및 schemas/model-profile.schema.json을 통해 실행 모델별 4가지 프로필(gpt-5_5 / gpt-5_5_pro / gpt-5_mini / legacy_or_unknown) 정의
• docs/ai/prompt-assembly.md에서 4계층 프롬프트 어셈블리(Prompt Assembly) (base_contract / phase_contract / risk_mode_contract / model_adapter) 구현 - Structured Outputs를 통해 review-result / acceptance-result / mode-classification / handoff-summary의 4가지 스키마 추가
• 평가 프레임워크(Eval framework)를 8가지 관점으로 정리하고, 4가지 관점을 릴리스 차단 요소(release blocker)로 지정

v8.4.0（2026-05-01）— Schema validate CI 및 eval runner

• scripts/validate-schemas.py + bin/plangate validate-schemas + .github/workflows/schema-validate.yml을 통해 JSON 아티팩트(artifact)의 스키마 기계 검증 수행
• bin/plangate eval + scripts/eval-runner.py + schemas/eval-result.schema.json을 통해 8가지 관점의 기계 평가 CLI 구현 - 베이스라인(baseline) 비교 및 릴리스 차단 요소(release blocker) 위반 탐지가 CI에 통합됨

v8.6.0（2026-05-04）— Metrics v1 및 프라이버시 contract

• docs/ai/metrics-privacy.md에서 저장 가능한 12개 카테고리 / 금지된 9개 카테고리를 정본화 (스키마 설계 시 §4 금지 사항이 스키마 상에 존재하지 않도록 하는 설계를 강제)
• schemas/plangate-event.schema.json에서 11가지 이벤트를 JSON Schema로 정의 - v8.5.0까지는 "계약을 위반하면 중단한다"였고, v8.6.0에 이르러 "계약에 따른 행동을 기록한다"가 갖춰짐

도달점은 "계약은 Markdown뿐만 아니라 JSON Schema로서 존재하며, CI와 런타임 훅(runtime hook) 양쪽 모두에서 검증된다"는 상태입니다.

버전 연표

이 연표는 사전식 참조를 위한 것입니다. 설계 의도는 앞서 설명한 4가지 축을 통해 설명했습니다.

4가지 축의 변천을 시계열로 조망하면 다음과 같습니다.

4가지 축을 뒷받침한 「보급·운용 경로」

4가지 축과는 별개로, PlanGate를 OSS(Open Source Software)로 공개하여 팀에서 사용할 수 있도록 하기 위한 릴리스들이 포함되어 있습니다.

• v7.1.0（2026-04-23）— README 개편, GitHub Pages 공개, docs/philosophy.md

분리, MIT LICENSE 추가, Codex CLI / Claude Code 공용 기술을 .agents/skills/에 정비. "사용자를 위한 경로"와 "철학 문서"를 여기서 분리했다.

• v7.3.x (2026-04-26~27)— docs/oss-governance.md에서 Required approvals / Scorecard / Actions allowlist를 확정, 영어 버전 README와 examples/의 샘플 정비, setup-team skill 추가, full → high-risk 명칭 완전 통일. OSS와 팀 운영의 기반이 갖춰진 단계.

이것들은 4개 축의 기능 추가와는 별개의 계통이지만, 후속 v8 계열을 "타인이 재현할 수 있는 harness"로 만드는 데 기여하고 있습니다.

v8.7 이후의 3가지 테마

v8.6.0 완료 시점에서 다음에 예정된 Roadmap은 수없이 많지만, 본고의 4개 축과의 연결 측면에서 보면 3가지 테마로 압축할 수 있습니다.

• 비교 주도형 개선 (Comparison-driven improvement)— Eval comparison (#196), Keep Rate v1 (#198), Reporting & Retrospective (#200). v8.4의 eval runner와 v8.6의 baseline / Metrics events를 전제로 한 "숫자로 개선하는" 계열.
• Provider와 Model의 확장— Model Profile v2 (#197), Dynamic Context Engine v1 (#199). v8.3의 4개 profile과 Prompt Assembly 4개 층을 실행 시점에 다시 조립하는 계열.
• 에러 분류와 벤치마크 정비— Tool Error Taxonomy (#203), PlanGateBench Fixture Suite (#204). v8.4의 Schema validate CI를 기점으로, 회복 정책(Recovery policy)과 회귀 탐지(Regression detection)를 기계화하는 계열.

즉, v3부터 v8.6까지의 설계 변천은 여기까지로 "개선 전 baseline과 비교할 수 있는 harness"를 만드는 단계를 마쳤다고 할 수 있습니다. 다음은 "비교를 통해 개선하는" 단계로 진입합니다.

이 변천 과정을 자신의 프로젝트에 도입하려면

PlanGate의 1개월 과정을 제로 베이스에서 자신의 프로젝트로 이식한다면, 다음 순서가 무리가 적을 것입니다.

• 승인 게이트(Approval gate)를 설치한다— 우선 Plan / ToDo / Test Cases를 생성하고, 승인 후에만 Agent가 동작할 수 있다는 운영 규칙을 Markdown으로 작성한다 (v3~v4 상당)
• 모드를 분리한다— 태스크의 규모와 리스크에 따라 게이트의 엄격함을 바꾸는 분류를 도입한다 (v6~v7.2 상당)
• 결과물을 schema화 한다— Markdown 규약을 JSON Schema로 변환하고, CI에서 검증한다 (v7.4~v8.4 상당)
• hook과 metrics는 마지막에 추가한다— 규약과 schema가 안정된 후, 런타임 hook으로 강제하고, events를 집계한다 (v8.5~v8.6 상당)

순서를 거꾸로 하면, 관측 대상(events)이 완전히 정의되지 않은 상태에서 hook을 구성하게 되어 나중에 전부 다시 작성해야 하는 상황이 발생합니다.

요약

PlanGate v3 ~ v8.6을 4개 축으로 다시 읽어보면, 기능 추가 순서에도 내적인 필연성이 보입니다.

• 막기 (게이트 설계): 게이트형 모델 → C-3 삼치(Ternary) + V-1~V-4 → Hook 10/10 → Metrics
• 선택하기 (모드 분류): 2분류 → 5단계 방향성 → GatePolicy → Workflow DSL → validate --mode
• 움직이기 (실행층): 3개 층 분리 → CLI → Provider RFC → Orchestrator
• 증명하기 (계약과 검증): Markdown 규약 → Artifact schema 7종 → CI 통합 → Outcome-first → event schema

"막기", "관측하기", "비교하기"가 각각 독립적으로 성장하여 합류하기까지 1개월이 걸렸습니다. 같은 작업을 자신의 프로젝트에서 제로 베이스로 설계한다면, 이 순서를 참고하여 분해할 수 있을 것입니다.

가져가야 할 설계 원칙

PlanGate의 변천 과정에서 얻을 수 있는 교훈은, AI 코딩의 통제는 처음부터 거대한 기반으로서 만들 필요가 없다는 것입니다.

• 우선
  **Markdown 계약 (Markdown Contract)**으로 제한하기 (v3v4 상당) - 다음으로
  **모드 (Mode)**로 분리하기 (v6v7.2 상당) -
  CLI로 실행 경로를 고정하기 (v7.5v8.1 상당) -
  Schema로 기계적 검증하기 (v7.4v8.4 상당) - 마지막으로
  Metrics로 관측하기 (v8.5~v8.6 상당)

이러한 순서라면 개인 개발에서도 팀 개발에서도 단계적으로 도입할 수 있습니다. 반대로 순서를 뒤집어 "먼저 Metrics나 Hook부터 만들자"라고 하면, 관측 대상이나 강제 대상이 정해지지 않은 채 구현에 착수하게 되어 나중에 전부 다시 작성해야 하는 상황이 발생합니다.

통제 하네스 (Control Harness)의 설계는 기능의 총량이 아니라, 도입하는 순서가 품질을 결정합니다.

참고 링크

Discussion