governance

거버넌스: Plan → Review → Execute → Re-verify

핵심 원칙: 모든 실행은 실행계획이 수립되고, 검증/수락된 후에만 실행된다. 실행 후에는 반드시 재검증을 통해 품질을 보증한다.

먼저 실행 후 계획을 변경하는 것은 비효율적이며 시간과 에너지의 낭비를 초래한다. 이 프로세스는 모든 Phase에 예외 없이 적용되는 필수 거버넌스 규칙이다.

4단계 프로세스

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌────────────┐
│  1. PLAN │────▶│ 2. REVIEW│────▶│3. EXECUTE│────▶│4. RE-VERIFY│
│  계획 수립 │     │  검증/수락 │     │   실행    │     │   재검증    │
└──────────┘     └──────────┘     └──────────┘     └────────────┘
                       │                                  │
                  ┌────┴────┐                       ┌─────┴─────┐
                  │ 거부/수정 │──▶ 1. PLAN으로 복귀    │ 미달 시     │──▶ 보완 실행 또는
                  └─────────┘                       └───────────┘    1. PLAN으로 복귀

---

Stage 1: PLAN (계획 수립)

어떤 Phase를 시작하든, 먼저 실행계획 문서를 작성한다.

실행계획서는 .claude/local/plans/<branch>/<NN-phase>/execution-plan.md에 저장되며, 이 디렉토리는 세션을 가로질러 유지되어 세션이 종료된 후에도 기록(문서)으로 디스크에 남는다. 자세한 경로 규약은 본 문서 하단 "실행계획서 저장 위치" 섹션 참조.

PLAN 사전 준비 (모든 Phase 공통, 매 PLAN 진입 시 수행)

플러그인이 설치된 사용자 프로젝트에서는 SessionStart 훅(hooks/bootstrap-local.sh)이 세션 시작 시 자동으로 다음을 보장한다:

• 프로젝트 루트에 .claude/local/plans/ 디렉토리 생성
• 프로젝트 .gitignore에 .claude/ 한 줄 추가 (없으면 새로 만들고, 기존 내용은 보존)
• 레거시 .claude/local/ 라인이 있으면 자동으로 .claude/로 교체 (v0.3.x → v0.4.0 업그레이드 보조)
• 이미 적용된 프로젝트에서는 아무 동작도 하지 않는다 (idempotent)
• 사용자의 cwd가 git 저장소가 아니면 동작하지 않는다 (보수적 가드)

훅이 실행되지 못한 환경(예: 훅을 비활성화한 사용자, 플러그인 외부 호출)을 대비하여, 모든 Phase의 PLAN 단계는 실행계획서 파일을 쓰기 전에 동일한 보장을 자체적으로 수행한다:

1. 프로젝트 루트의 .gitignore에 .claude/ 줄이 있는지 확인한다.
   • 없으면 한 줄 추가한다 (.gitignore가 없으면 새로 만든다).
   • 동일 의미의 패턴(.claude, .claude/* 등)이 이미 있으면 중복 추가하지 않는다.
   • 레거시 .claude/local/만 있는 경우 .claude/로 교체한다 (훅과 동일).
2. "브랜치 이름 결정 절차"(아래 "실행계획서 저장 위치" 섹션 참조)에 따라 <branch>를 산출한다.
3. .claude/local/plans/<branch>/<NN-phase>/ 디렉토리를 생성한다 (없을 경우).
4. 위 디렉토리에 execution-plan.md를 작성한다.

이 절차는 사용자가 Phase 0(00-setup)을 건너뛰고 다른 Phase부터 시작했을 때, 또는 SessionStart 훅이 실행되지 않은 환경에서도 작업 영역과 gitignore 보호가 정합 상태로 유지됨을 보장한다.

실행계획서 구조

references/execution-plan-template.md의 템플릿을 기반으로 작성:

# [Phase N] 실행계획서

## 1. 목표 (Objective)
> 이 Phase에서 달성하려는 것

## 2. 전제 조건 (Prerequisites)
> 이전 Phase의 어떤 산출물에 의존하는가
> 해당 산출물이 존재하고 최신인가

## 3. 범위 (Scope)
> 이번 실행에서 다루는 것 / 다루지 않는 것
- In-Scope:
- Out-of-Scope:

## 4. 실행 단계 (Steps)
> 구체적 실행 순서와 각 단계의 예상 산출물
| 순서 | 작업 | 산출물 | 예상 소요 |
|------|------|--------|----------|
| 1 | | | |
| 2 | | | |

## 5. 의존성 및 리스크 (Dependencies & Risks)
> 외부 의존성, 잠재 리스크, 대응 방안
| 리스크 | 확률 | 영향 | 대응 |
|--------|------|------|------|

## 6. 성공 기준 (Success Criteria)
> 이 Phase가 "완료"되었다고 판단하는 기준
- [ ] 기준 1
- [ ] 기준 2

## 7. 검증 방법 (Verification)
> 산출물의 품질을 어떻게 검증할 것인가

## 8. 재검증 기준 (Re-verification Criteria)
> 실행 완료 후 재검증 시 확인할 항목
- [ ] 성공 기준 달성 여부
- [ ] 산출물 완결성 및 정합성
- [ ] 이전 Phase 산출물과의 추적성
- [ ] 개선점 및 교훈 (Lessons Learned)

계획 수립 원칙

• 구체적으로 — "API를 설계한다"가 아닌 "유저 스토리 US-001~005에 대응하는 REST 엔드포인트를 설계한다"
• 측정 가능한 성공 기준 — "잘 만든다"가 아닌 "PRD의 모든 Must Have 기능에 대한 유저 스토리가 작성된다"
• 범위를 명시적으로 한정 — Out-of-Scope를 반드시 기재하여 스코프 크립 방지
• 이전 산출물 확인 — 전제 조건의 산출물이 실제로 존재하고 유효한지 확인

---

Stage 2: REVIEW (검증/수락)

실행계획서가 작성되면, 반드시 사용자에게 검증을 요청한다.

검증 절차

1. 실행계획서를 사용자에게 제시한다
2. 아래 체크리스트로 사용자와 함께 검증한다:

계획 검증 체크리스트:

• 목표가 명확하고 이번 Phase에 적합한가?
• 전제 조건이 충족되었는가? (이전 산출물 존재 확인)
• 범위가 적절한가? (너무 넓지도, 좁지도 않은가)
• 실행 단계가 논리적 순서인가?
• 성공 기준이 측정 가능한가?
• 빠진 리스크는 없는가?
• 재검증 기준이 명확한가?

3. 사용자로부터 명시적 수락을 받는다:
   • 승인 (Approved) → Stage 3 실행으로 진행
   • 수정 요청 (Revise) → 피드백 반영하여 계획 수정 후 재검증
   • 거부 (Rejected) → 근본적 재설계 필요, Stage 1로 복귀

검증 시 주의사항

• 수락 없이 실행에 들어가지 않는다 — 이것은 절대 규칙
• 사용자가 "알아서 해줘"라고 해도, 최소한 핵심 사항에 대해 확인을 받는다
• 계획 변경이 발생하면 변경 사항을 명시하고 재수락을 받는다

---

Stage 3: EXECUTE (실행)

수락된 계획에 따라 실행한다.

실행 원칙

• 계획대로 실행 — 수락된 계획의 범위와 순서를 준수한다
• 계획 변경 시 중단 — 실행 중 계획 변경이 불가피하면 실행을 중단하고 계획을 수정한다
• 진행 상황 보고 — 각 단계 완료 시 진행 상태를 보고한다
• 산출물 저장 — 계획서에 명시된 산출물을 약속된 경로에 생성한다

실행 중 계획 변경이 필요한 경우

실행 중 예상치 못한 상황 발생
  → 실행 일시 중단
  → 변경 사유와 영향 범위 정리
  → 계획 수정안 작성
  → 사용자 수락 (Stage 2 미니 루프)
  → 수정된 계획으로 실행 재개

---

Stage 4: RE-VERIFY (재검증)

실행이 완료되면, 산출물과 결과를 계획 대비 재검증한다.

재검증 목적

실행 결과가 당초 계획의 성공 기준을 충족하는지 객관적으로 검증하고, 품질 문제나 누락 사항을 조기에 발견하여 다음 Phase로의 전이 품질을 보장한다.

재검증 절차

1. 성공 기준 대조 — 실행계획서의 성공 기준 체크리스트를 하나씩 확인한다
2. 산출물 완결성 점검 — 계획된 모든 산출물이 생성되었는지 확인한다
3. 정합성 검증 — 산출물 간, 그리고 이전 Phase 산출물과의 일관성을 확인한다
4. 품질 평가 — quality-reviewer 에이전트를 활용하여 산출물 품질을 평가한다
5. 교훈 기록 — 실행 과정에서의 개선점, 발견한 리스크, 교훈을 기록한다

재검증 체크리스트

• 모든 성공 기준이 달성되었는가?
• 계획된 모든 산출물이 존재하는가?
• 산출물의 내용이 이전 Phase 산출물과 모순되지 않는가?
• 산출물의 품질이 기준에 부합하는가? (Major 이슈 0건)
• 다음 Phase의 전제 조건을 충족하는가?
• 개선점 및 교훈이 기록되었는가?

재검증 판정

• 통과 (Pass) → .claude/lifecycle.md에 이력 기록 후 다음 Phase 진행 가능
• 조건부 통과 (Conditional Pass) → 경미한 보완 후 통과 처리 (보완 사항 명시)
• 미달 (Fail) → 보완 실행 (Stage 3 부분 재실행) 또는 근본적 문제 시 Stage 1로 복귀

재검증 완료 후

1. 실행계획서의 성공 기준 체크리스트를 채운다
2. 산출물 목록과 저장 경로를 보고한다
3. 교훈 및 개선 사항을 .claude/lifecycle.md에 기록한다
4. 다음 Phase 진행 가능 여부를 명시한다

---

Phase별 적용 예시

Phase 2 (기획) 진입 시:

1. [PLAN] "Phase 2 실행계획서를 작성합니다."
   → .claude/local/plans/<branch>/02-planning/execution-plan.md 생성
   → "아이디어 브리프 기반으로 PRD, 유저 스토리, 스코프 문서를 작성합니다.
      In-Scope: Must/Should Have 기능 도출, MVP 범위 확정
      Out-of-Scope: 기술 스택 결정 (Phase 3에서)
      성공 기준: 모든 기능에 ID 부여, AC 포함 유저 스토리, MVP 범위 확정"

2. [REVIEW] "실행계획을 확인해주세요."
   → 사용자: "승인" 또는 "이 부분 수정해줘"

3. [EXECUTE] 승인 후 실행
   → PRD, 유저 스토리, 스코프 문서 순서대로 작성

4. [RE-VERIFY] 실행 완료 후 재검증
   → 성공 기준 대조: 모든 기능 ID 부여됨 ✅, AC 포함 ✅, MVP 확정 ✅
   → 산출물 정합성: 아이디어 브리프와 PRD 간 일관성 확인 ✅
   → 교훈 기록: "비기능 요구사항 누락 가능성 → NFR 체크리스트 활용 필수"
   → 판정: Pass → Phase 3 진행 가능

---

실행계획서 저장 위치

실행계획서는 브랜치별로 분리된 작업 영역 .claude/local/plans/<branch>/<NN-phase>/execution-plan.md에 저장된다. 이 영역은 단계별 산출물(.claude/<NN-phase>/)과 분리된 "초안/작업 메모" 공간으로, 세션이 종료되어도 디스크에 남아 다음 세션에서 이어서 사용할 수 있다. .claude/ 폴더 전체가 gitignore되므로 실행계획서·산출물 모두 기본적으로 git 추적에서 제외된다.

<project-root>/
├── .gitignore                       ← `.claude/` 한 줄 등록 (Phase 0 setup이 자동 처리)
└── .claude/                         ← 폴더 전체 ignore (기본값)
    ├── CLAUDE.md                    ← 에이전트 컨텍스트
    ├── lifecycle.md                 ← ALM 추적 이력
    ├── tech-debt-registry.md
    ├── kpi-definitions.md
    ├── 00-setup/, 01-ideation/, ..., 08-maintenance/   ← 단계별 산출물
    └── local/                       ← 작업영역 (실행계획서)
        └── plans/
            ├── main/
            │   └── 02-planning/execution-plan.md
            └── claude-save-execution-plans-AaqnA/
                ├── 01-ideation/execution-plan.md
                ├── 02-planning/execution-plan.md
                └── 05-implementation/execution-plan.md

브랜치 이름 결정 절차

PLAN 단계 진입 시 다음 절차로 <branch> 부분을 결정한다:

1. git branch --show-current로 현재 브랜치 이름을 얻는다. (커밋이 없는 unborn 브랜치에서도 동작한다.) 사용 불가 환경이면 git rev-parse --abbrev-ref HEAD로 대체한다.
2. 결과가 빈 문자열이거나 HEAD(detached)이거나 git 저장소가 아니면 _no-branch로 폴백한다.
3. 슬래시(/)를 하이픈(-)으로 치환한다 (tr '/' '-'). 예: claude/save-execution-plans-AaqnA → claude-save-execution-plans-AaqnA.
4. 결과를 <branch>에 사용한다.

gitignore 처리

.claude/ 폴더 전체를 프로젝트 .gitignore에 등록한다. 이로써 플러그인이 만드는 모든 산출물(단계 폴더, 실행계획서, ALM 추적 파일, 에이전트 컨텍스트)이 일괄적으로 git 추적에서 제외된다.

• 신규 프로젝트: Phase 0 (00-setup) 스킬과 SessionStart 훅이 초기 설정 시 .gitignore에 자동 추가한다.
• 기존 프로젝트(v0.3.x 이전): SessionStart 훅이 레거시 .claude/local/ 라인을 자동으로 .claude/로 교체한다. 수동 작업 불필요.

왜 .claude/ 전체를 ignore 하는가

플러그인이 만드는 모든 파일은 기본적으로 사용자의 비공개 작업물로 본다. 추적 여부는 전적으로 사용자의 결정이다. 팀과 공유하고 싶은 산출물이 생기면, 사용자가 해당 파일을 .claude/ 밖(예: docs/)으로 직접 이동시키면 된다 — 이동된 파일은 자연스럽게 git 추적 대상이 된다. 이 방식은 (a) 프로젝트 저장소를 깨끗하게 유지하고, (b) Codex·Gemini 같은 다른 AI 도구가 추가되어도 각자 자기 폴더에 가둘 수 있으므로 도구 비종속성이 확보된다.

같은 브랜치 내 재수립 / 수동 승격

• 같은 브랜치+Phase에서 계획을 다시 수립할 때는 단일 파일을 덮어쓴다. .claude/local/은 git 추적 대상이 아니므로 이력 보존은 사용자 책임이다.
• 합의가 끝난 계획을 영구 산출물로 보존하려면 (a) 실행계획서를 .claude/<NN-phase>/로 이동/복사하고, (b) 그 산출물을 팀과 공유하여 git 추적이 필요하면 사용자가 직접 .claude/ 밖(예: docs/<NN-phase>/)으로 이동시킨다. 추적 여부는 전적으로 사용자 결정이며, 자동 승격은 수행하지 않는다.

참고 자료

• references/execution-plan-template.md — 실행계획서 전체 템플릿