AI 코딩을 「비교를 통해 개선」할 수 있는 토대로 만들기: PlanGate v8.6.0의 Metrics v1과 Governance

AI 코딩 에이전트 (AI Coding Agent)를 사용하면 구현의 초속은 크게 올라갑니다.

반면, 빨라진 만큼 다음과 같은 문제도 눈에 띕니다.

• 계획이 모호한 상태로 코드 변경을 진행함
• 관련되어 보이는 개선을 AI가 임의로 확장함
• 테스트 관점이 사후에 추가됨
• PR (Pull Request)의 차분이 커져서 리뷰가 무거워짐
• 세션이 바뀌면 판단 근거를 잃어버림

PlanGate는 이 문제에 대해 「AI를 더 똑똑하게 만드는」 것이 아니라, **인간이 승인할 때까지 진행할 수 없는 게이트 (Gate)**를 두는 접근 방식입니다.

승인 없이는, 코드도 없습니다.

v8.5.0에서 Hook enforcement 10/10이 완성되어 「실행 시점에 멈추는」 메커니즘은 모두 갖춰졌습니다. 이어지는 v8.6.0에서는 그 위에 Metrics v1 / Issue governance / Baseline이 올라갔습니다.

한마디로 말하면, **「멈춘 횟수를 집계하여 비교할 수 있는 harness」**로 진화했습니다.

이 기사에서는 v8.6.0에서 추가된 4가지 기둥 (baseline · governance · privacy · Metrics v1)을 실제로 어떻게 사용하는가라는 관점에서 정리합니다.

TL;DR

PlanGate는 AI 코딩 에이전트를 안전하게 사용하기 위한 경량 거버넌스 하네스 (Governance Harness)입니다.

• v8.5.0에서 Hook enforcement 10/10이 갖춰져 「멈추는」 메커니즘은 모두 구비되었습니다.
• v8.6.0에서 Harness Improvement Roadmap Phase 0/1 (baseline → governance → privacy → Metrics v1)이 탑재되어 「관측하는 것 · 비교하는 것」과 합류했습니다.
• 11 events의 JSON Schema, CLI (plangate metrics --collect/--report), CLI tests 24→32 PASS (hook 측은 42 PASS 유지)에 대한 상세 내용은 본문에서 정리합니다.

hook violation이나 C-3/C-4 판단을 주 단위로 회고하고 싶은 팀에 적합합니다. 「AI에게 빠르게 쓰게 하는 것」뿐만 아니라, 「AI가 어디서 멈추고, 얼마나 멈추고 있는가」를 숫자로 다루고 싶은 팀에 맞습니다.

이 기사의 대상 독자

• Claude Code / Codex CLI 등의 AI 코딩 에이전트를 실무에서 사용하고 있는 사람
• AI가 만드는 PR의 차분이 커져서 리뷰에 어려움을 겪고 있는 사람
• Hook으로 멈추는 단계까지는 도입했지만, 「효과가 있는지」를 숫자로 확인하지 못하고 있는 사람
• 스크럼 (Scrum)이나 PBI (Product Backlog Item) 기반의 개발에서, AI 운용 개선을 회고 (Retrospective)를 통해 진행하고 싶은 사람

v8.5.0과 v8.6.0의 역할 분담

PlanGate의 진화는 「멈추는 것」과 「관측하는 것」을 나누어 이해하면 정리하기 쉽습니다.

버전	주역	무엇이 갖춰졌는가
v8.4.0	Hook 기반	default warning / strict block / bypass의 3가지 모드 설계
v8.5.0	Hook enforcement 완성	10/10 hooks 구현, hook tests 12→42 PASS
v8.6.0	관측과 비교	Metrics v1 / Issue governance / Privacy / Baseline

v8.5.0까지는 「위험한 조건을 얼마나 멈출 수 있는가」가 과제였습니다. v8.6.0부터는 「어디서 몇 번 멈췄는지를 기록하여, harness 자체를 개선할 수 있는가」가 테마입니다.

v8.6.0에서 추가된 4가지 기둥

EPIC #193 Harness Improvement Roadmap의 v8.6.0 milestone P0로서, 4개의 PBI가 Metrics v1 이전에 baseline · governance · privacy를 정비하는 의존 관계로 구현되었습니다.

#	PBI	문서 (Document)	역할
1	#194 Baseline alignment	docs/ai/eval-baselines/2026-05-04-baseline.{md,json}	개선 전 상태를 고정
2	#201 Issue/Label/Milestone Governance	docs/ai/issue-governance.md	추측 금지 조항과 Roadmap PBI 템플릿
3	#202 Metrics Privacy	docs/ai/metrics-privacy.md	저장 가능 12 / 금지 9 카테고리
4	#195 Metrics v1	schemas/plangate-event.schema.json 외	11 events와 CLI 집계

순서가 중요합니다. governance (무엇을 Issue로 남길 것인가)와 privacy (무엇을 기록해도 되는가)를 먼저 결정한 후 Metrics v1을 구현함으로써, schema 설계 시 privacy §3/§4가 선행 참조되어 "Forbidden 카테고리는 schema 상에 존재시키지 않는다"는 설계를 강제할 수 있습니다.

Metrics v1: 11 events로 운영을 기록한다

Metrics v1의 스키마 (schemas/plangate-event.schema.json)가 기록하는 events는 다음 11종류입니다.

Event	기록 내용
task_initialized	TASK 디렉토리 생성, PBI 번호, mode
plan_generated	plan.md / todo.md / test-cases.md 구비 여부
c3_decided	C-3 승인 결과 (APPROVED / CONDITIONAL / REJECTED)
exec_started	exec 페이즈 시작
hook_violation	어떤 hook이 어떤 조건에서 발화했는지
v1_completed	V-1 검증 완료, AC PASS/FAIL/WARN 건수
fix_loop_incremented	수정 루프 (fix loop) 횟수
external_review_completed	V-3 외부 리뷰 결과
pr_created	PR 번호와 차이(diff) 요약
c4_decided	C-4 머지(merge) 승인
handoff_completed	handoff 필수 요소 체크

각 event는 conditional required (c3 / c4 / v1 / hook / fix_loop 각각에 필수 필드 있음)로 정의되어 있으며, 형식 위반은 schema 검증에서 걸러집니다.

CLI로 집계하기

스키마와 더불어 scripts/metrics_collector.py / scripts/metrics_reporter.py가 준비되어 있습니다. bin/plangate metrics를 통해 호출합니다.

# TASK 디렉토리에서 6 events를 자동으로 도출하여 NDJSON에 추가
bin/plangate metrics --collect TASK-0061
# events.ndjson으로부터 TASK 단위의 요약을 표시
...

--collect는 dry-run 모드 (--dry-run)도 지원하므로, 처음에는 NDJSON에 쓰지 않고 events 추출 결과만 확인할 수 있습니다.

Privacy는 스키마로 강제한다

events.ndjson은 docs/working/_metrics/events.ndjson에 출력되지만, .gitignore로 제외되어 있어 public repo에 commit되지 않습니다. 이는 docs/ai/metrics-privacy.md §8의 요구사항입니다. metrics-privacy.md는 다음과 같이 12/9 카테고리로 구분하고 있습니다.

저장 가능 12 카테고리: TASK ID, event 종류, timestamp, mode, AC count, hook 명, C-3/C-4 decision, V-1 result, fix loop count, PR 번호, 차분 행수 집계, handoff 필수 요소 체크 결과 -
금지 9 카테고리: file path (전체 경로), stack trace, command output, provider metadata, API key, 사용자명, commit message 전문, 코드 본문, private prompt 내용

설계 단계에서 이러한 구분(line)이 포함되어 있으므로, Metrics v1을 사용하더라도 Forbidden 카테고리를 의도치 않게 저장하기 어려운 구조로 되어 있습니다.

Issue governance: 「추측 금지 조항」이란

docs/ai/issue-governance.md에서 정본화된 Issue 운영 규칙의 핵심은 §4 추측 금지 조항입니다.

Roadmap PBI를 Issue화할 때, Why / What / AC / Non-goals / Labels / Milestone을 추측으로 채워서는 안 된다. 명시되지 않은 요소는 「미확정」 상태로 남겨두고, 확정 후에 업데이트한다.

이는 v8.5.0 → v8.6.0 기간에 발생한 「11개의 PBI가 실수로 v7.x milestone에 연결되었던」 사고에 대한 재발 방지책입니다. AI에게 Issue Form을 작성하게 하면, 그럴듯한 milestone을 그럴싸하게 추측해 버리기 때문에 규칙으로서 금지했습니다.

이를 뒷받침하는 메커니즘은 두 가지입니다.

• .github/ISSUE_TEMPLATE/plangate-roadmap-task.yml — Roadmap PBI용 Issue Form. Why / What / AC / Non-goals / Labels / Milestone을 필수 입력으로 강제
• docs/ai/issue-governance.md의 Label taxonomy — kind / area / priority / status의 4개 축으로 분류, milestone mapping은 별도 문서에서 명시

「AI가 대신 작성할 수 있는 부분」과 「인간이 확정할 때까지 채워서는 안 되는 부분」을 분리하는 것이 요점입니다.

Baseline: 개선 전 상태를 고정하기

docs/ai/eval-baselines/2026-05-04-baseline.{md,json}에는 v8.5.0 직후 시점의 baseline이 기록되어 있습니다.

• 대표 5개 TASK (TASK-0050 / 0054 / 0055 / 0056 / 0057) 선정
• 기존 8개 관점 eval (scope / approval / AC coverage / verification / stop / tool overuse / format / latency-cost)을 전건 적용
• 기계 판독 가능한 JSON snapshot을 병치하여, 후속 개선 사항과의 diff를 구할 수 있는 형태로 구성

이것이 있음으로써, 예를 들어 v8.7.0 후보인 #196 Eval expansion이나 #197 Model Profile v2를 도입했을 때, 「관점별로 몇 점이 개선되었는지」를 baseline JSON과의 diff로 보여줄 수 있습니다.

반대로 말하면, baseline이 없는 상태에서는 harness 개선을 도입하더라도 「왠지 좋아진 것 같다」는 느낌으로 끝나게 됩니다. v8.6.0은 이 「느낌」을 없애기 위해 나아간 릴리스입니다.

Hook enforcement의 역할은 변하지 않음

v8.6.0에서도 v8.5.0에서 완성된 Hook enforcement 10/10은 그대로 토대로 작동합니다. Metrics v1은 이러한 hook 발생을 hook_violation event로서 기록하는 레이어이며, hook을 대체하는 것이 아닙니다.

만약을 위해, 현재 10개 hooks의 역할을 정리해 둡니다.

Hook	목적
EH-1	plan.md 없는 production code 편집을 감지
EH-2	C-3 승인 없는 구현을 차단
EH-3	승인 후의 plan.md 변조를 plan_hash로 감지
EH-4	test-cases.md 없는 V-1 실행을 감지
EH-5	검증 evidence 없는 PR 생성을 감지
EH-6	forbidden_files에 의한 scope 외 편집을 감지
EH-7	C-3 / C-4 승인 없는 머지를 감지
EHS-1	standard 이상에서 V-3 외부 리뷰를 필수화
EHS-2	handoff의 필수 요소를 검사
EHS-3	fix loop의 상한 초과를 감지

테스트 스위트 (test suite) 구성도 동일합니다.

sh tests/run-tests.sh # CLI / eval / schema / metrics
sh tests/hooks/run-tests.sh # hook enforcement

v8.6.0 시점에서는, CLI 측 32 PASS (v8.5.0의 24에서 +8), Hook 측 42 PASS입니다. +8은 모두 Metrics v1용 tests/extras/ta-09-metrics.sh

(schema validation / 각 event 검출 / aggregate report / JSON 출력)에서 온 것입니다.

v8.6.0을 시도하는 순서

PlanGate를 신규 도입하는 경우와 이미 v8.5.0을 운용하고 있는 경우에 따라 순서가 달라집니다.

신규 도입하는 경우

# 1. 1개 태스크(task)로 plan → approve → exec를 시도
/working-context TASK-0001
/ai-dev-workflow TASK-0001 plan
...

여기까지 접해본 뒤에 Hook과 Metrics로 넘어가는 것이 현실적입니다. 처음부터 metrics --collect를 돌려도, 관찰(observe)할 대상(TASK 이력)이 없으면 의미가 없습니다.

v8.5.0에서 업그레이드하는 경우

• Privacy를 읽기: docs/ai/metrics-privacy.md의 저장 가능 12개 / 금지 9개를 자신의 팀의 공개 정책과 대조한다.
• Baseline을 잡기: 기존 TASK 중 대표적인 3~5건을 선정하여 docs/ai/eval-baselines/에 스냅샷(snapshot)을 만든다.
• Metrics를 dry-run으로 돌리기: bin/plangate metrics --collect <TASK> --dry-run으로 event 추출이 예상대로인지 확인한다.
• Issue governance를 적용: 기존의 Roadmap Issue를 plangate-roadmap-task.yml 템플릿에 맞춰 정리한다. milestone은 추측으로 채우지 않는다.
• NDJSON 축적 시작: dry-run을 해제하고, bin/plangate metrics --aggregate로 주 단위로 집계한다.

특히 1번과 2번을 건너뛰면, "Metrics는 수집되고 있지만 무엇과 비교해야 할지 모르겠다"는 상태에 빠지게 됩니다.

다음 EPIC: v8.7.0 / v8.8.0 / v8.9.0

CHANGELOG에 나와 있듯이, v8.6.0 milestone P0 완주에 따라 다음 로드맵이 보입니다.

• v8.7.0 (P1): #196 Eval comparison for harness changes, #197 Model Profile v2, #203 Tool Error Taxonomy, #204 PlanGateBench Fixture Suite
• v8.8.0 (P1/P2): #198 Keep Rate v1 (Code / Plan / Acceptance / Handoff), #199 Dynamic Context Engine v1
• v8.9.0 (P2): #200 Reporting & Retrospective (sprint retrospective 통합)

이 모든 것은 v8.6.0에서 고정한 baseline과 Metrics v1 이벤트 로그 위에서 「비교 가능한」 형태로 평가될 예정입니다.

FAQ

Metrics v1은 대시보드 (Dashboard) 기능인가요?

아니요. v8.6.0 시점의 Metrics v1은 대시보드라기보다 후속 개선을 비교하기 위한 이벤트 로그 (Event log) 기반입니다.

plangate metrics --collect

를 통해 TASK에서 events를 추출하고, --report나 --aggregate로 집계합니다. 시각적인 가시화보다는 「어떤 hook이 몇 번 중단시켰는가」, 「C-3 / C-4의 판단이 어떻게 추이했는가」를 나중에 비교할 수 있는 것을 우선시합니다.

Hook enforcement만 도입해도 충분한가요?

최초 도입 시에는 Hook enforcement만으로도 충분합니다.

하지만 운영을 지속하다 보면 「중단되었는가」뿐만 아니라, 「어디서 몇 번 중단되었는가」, 「그것이 개선되고 있는가」를 보고 싶어집니다. Metrics v1은 그러한 회고를 retrospective (회고)나 주간 리뷰에 반영하기 위한 레이어 (Layer)입니다.

Privacy의 경계는 어디에서 확인할 수 있나요?

docs/ai/metrics-privacy.md가 정본입니다.

저장 가능 12개 카테고리와 금지 9개 카테고리를 먼저 결정하고, 해당 금지 카테고리를 schema (스키마) 상에 포함하지 않는 설계로 되어 있습니다. 자체 팀에서 사용할 경우에도, 먼저 이 privacy policy (개인정보 보호 정책)를 자신들의 공개·저장 규칙에 비추어 확인하는 것을 권장합니다.

신규 도입 시에는 v8.6.0의 어느 부분부터 시작해야 하나요?

우선 1개의 TASK로 plan → approve → exec를 시도해 보는 것이 좋습니다.

Metrics v1은 TASK 이력이 있어야 비로소 의미를 갖습니다. 처음부터 전부 도입하기보다는, PlanGate의 승인 플로우 (Flow)를 한 바퀴 돌린 후, metrics --collect --dry-run으로 events 추출을 확인하는 순서가 현실적입니다.

요약

AI 코딩 에이전트의 과제는 「코드를 쓸 수 있는가」에서 「어떻게 안전하게 진행할 것인가」로, 그리고 「개선되고 있는지 관측할 수 있는가」로 옮겨가고 있습니다.

• v8.5.0까지 「중단하기」 기능이 모두 갖춰짐 (Hook enforcement 10/10)
• v8.6.0에서 「관측하기·비교하기」 기능이 모두 갖춰짐 (Metrics v1 / governance / baseline / privacy)
• 다음 v8.7.0 이후는 이 토대 위에서 harness 자체의 개선을 비교를 통해 판단해 나가는 단계로 진입

PlanGate v8.6.0은 AI 운영을 retrospective (회고)에 반영하기 위한 토대가 마련된 릴리스입니다. Hook으로 중단해 본 경험이 있는 팀일수록 「중단 횟수의 집계」와 「baseline과의 비교」의 효과를 체감할 수 있을 것입니다.

먼저 1개 태스크부터 시도한다면 신규 도입 흐름과 같습니다. Metrics v1까지 사용하고 싶다면 docs/ai/metrics-privacy.md를 먼저 읽은 후 --dry-run으로 한 바퀴 돌려보시기 바랍니다.

관련 기사

• Qiita: AI의 중단 방식을 「숫자로 보는」 경험: PlanGate v8.6.0에서 Metrics v1과 Governance를 도입한 이야기
• note: AI에게 코드를 쓰게 하기 전에, 인간이 승인하는 곳을 만들기