OMC - State Lifecycle

시리즈: oh-my-claudecode 내부 구조부터 플러그인 개발까지

이 시리즈는 Claude Code 플러그인 시스템의 내부 동작을 단계별로 해부하고, 최종적으로 나만의 플러그인을 직접 개발하는 것까지 도달하는 과정이다.

편	내용	핵심
1편	Plugin Anatomy	plugin.json 하나로 시작하는 플러그인 뼈대
2편	Hook System	이벤트 → stdin JSON → 스크립트 → stdout JSON
3편	Skill System	SKILL.md로 워크플로우를 정의하는 방법
4편	Agent System	Task tool로 위임되는 실제 작업 수행자
5편	MCP Tools Bridge	LSP, AST 등 커스텀 도구 서버
6편 (본문)	State & Lifecycle	.omc/ 상태 관리와 모드 지속
7편	Parallel Orchestration	Ultrawork, Team, Autopilot, Ralph 패턴

---

• OMC의 State & Lifecycle은 모드 상태, 세션 메모리, 프로젝트 지식을 .omc/ 디렉토리에서 관리하는 상태 영속화 시스템
• keyword-detector가 모드를 활성화하면 .omc/state/에 상태 파일을 기록하고, Stop hook(persistent-mode)이 상태를 읽어 작업 완료까지 종료를 차단하는 구조
• 컨텍스트 압축(Compact) 시 핵심 정보가 유실되는 문제를 Notepad(3섹션 메모리)와 Project Memory(프로젝트 지식 JSON)로 해결하는 압축 내성 아키텍처

해당 개념이 필요한 이유

• 5편(MCP Tools Bridge)에서 state_read, state_write 등 MCP 도구로 상태를 읽고 쓸 수 있게 되었음
• 하지만 **“언제 상태를 기록하고, 언제 읽고, 모드 전환은 어떻게 되며, 컨텍스트 압축 시 정보를 어떻게 보존하는지”**가 필요
• 이 파트는 OMC의 상태 관리 전략 — 모드 레지스트리, 종료 차단, 압축 대응 메모리의 전체 생명주기를 다룸

AS-IS

sequenceDiagram
    autonumber
    participant U as 사용자
    participant CC as Claude Code

    U->>CC: "ralph로 리팩터링 해줘"
    CC->>CC: 작업 시작
    CC->>CC: 1단계 완료
    CC-->>U: 응답 종료 (자동)
    Note over U: "아직 안 끝났는데..."
    U->>CC: "계속해줘"
    CC->>CC: 이전 컨텍스트 유실
    Note over CC: 뭘 하고 있었는지<br/>기억 못 함

TO-BE

sequenceDiagram
    autonumber
    participant KD as keyword-detector
    participant ST as .omc/state/
    participant PM as persistent-mode<br/>(Stop hook)
    participant CC as Claude Code

    KD->>ST: ralph-state.json 생성<br/>{ active: true, started_at }
    CC->>CC: 작업 진행
    CC->>PM: Stop 이벤트 (응답 종료 시도)
    PM->>ST: readModeState("ralph")
    ST-->>PM: { active: true }
    PM-->>CC: { continue: false } → 종료 차단
    CC->>CC: 작업 계속 진행
    CC->>ST: state_write({ active: false })
    CC->>PM: Stop 이벤트
    PM-->>CC: { continue: true } → 종료 허용

.omc/ 디렉토리 구조

.omc/
├── state/                          ← 모드 상태 파일
│   ├── ultrawork-state.json
│   ├── ralph-state.json
│   ├── team-state.json
│   ├── autopilot-state.json
│   ├── ultraqa-state.json
│   ├── skill-active-state.json
│   ├── last-tool-error.json        ← 일시적 (60초 TTL)
│   ├── subagent-tracking.json      ← 일시적
│   ├── mission-state.json
│   ├── checkpoints/                ← PreCompact 체크포인트
│   ├── shared-memory/              ← 에이전트 간 공유 저장소
│   │   └── {namespace}/{key}.json
│   └── sessions/                   ← 세션별 격리
│       └── {sessionId}/
│           ├── {mode}-state.json
│           ├── cancel-signal.json
│           └── {mode}-stop-breaker.json
├── sessions/                       ← 세션 종료 시 요약 기록
│   └── {sessionId}.json
├── notepad.md                      ← 압축 내성 메모리 (3섹션)
├── project-memory.json             ← 프로젝트 지식
├── notepads/                       ← 플랜별 위즈덤 노트패드
│   └── {planName}/
│       ├── learnings.md
│       ├── decisions.md
│       ├── issues.md
│       └── problems.md
├── plans/                          ← 계획 문서
├── research/                       ← 조사 결과
├── drafts/                         ← 드래프트 파일
├── logs/                           ← 로그
├── autopilot/                      ← Autopilot 스펙/플랜
└── skills/                         ← 스킬 저장소

ensureAllOmcDirs()가 state, plans, research, logs, notepads, drafts를 자동 생성한다. setup-init.mjs는 추가로 state/checkpoints도 보장.

Mode Registry — 모드 상태 머신

5가지 실행 모드 (ExecutionMode)

src/hooks/mode-registry/types.ts에 정의된 공식 실행 모드:

type ExecutionMode = 'autopilot' | 'team' | 'ralph' | 'ultrawork' | 'ultraqa';

stateDiagram-v2
    [*] --> inactive: 기본 상태
    inactive --> active: 키워드 감지 or Skill 활성화
    active --> active: 작업 진행 중 (Stop hook이 종료 차단)
    active --> inactive: 작업 완료 or /cancel
    active --> stale: 24시간 이상 비활성

    state active {
        [*] --> running
        running --> verifying: 검증 단계 (ralph)
        verifying --> running: 검증 실패 → 재작업
        verifying --> done: 검증 통과
    }

모드	상태 파일	배타적?	설명
autopilot	autopilot-state.json	Yes (유일)	전체 자동화
team	team-state.json	No	N worker 병렬
ralph	ralph-state.json	No	검증 루프
ultrawork	ultrawork-state.json	No	병렬 실행
ultraqa	ultraqa-state.json	No	QA 사이클

• 배타적 모드: EXCLUSIVE_MODES 배열에 autopilot만 포함. canStartMode()가 isModeActiveInAnySession()으로 전 세션을 검사하여 동시 실행 차단
• 합성 가능 모드: team, ralph, ultrawork, ultraqa는 동시 활성화 가능

실행 모드가 아닌 상태 도구 모드

state-tools.ts의 STATE_TOOL_MODES에는 실행 모드 5개 외에 추가 모드가 있다:

모드	성격	비고
ralplan	실행 전 계획 모드	Stop hook에서 별도 checkRalplan()으로 처리 (최대 30회 강화, 45분 TTL)
omc-teams	team 모드의 스킬 상태	skill-state에서 protection 'none'으로 등록
deep-interview	인터뷰 모드	skill-state에서 protection 'heavy' (10회 강화, 30분 TTL)

이들은 ExecutionMode 타입에 포함되지 않으며, Mode Registry가 아닌 각자의 메커니즘으로 상태를 관리한다.

모드 활성화 경로

graph TD
    UP["UserPromptSubmit"] --> KD["keyword-detector.mjs"]
    KD -->|"ralph, autopilot,<br/>ultrawork, ultraqa"| ACT["모드 활성화"]
    KD -->|"ralplan gate 적용"| RG{"유효한 프롬프트?<br/>(15단어 이상,<br/>파일경로·함수명 등)"}
    RG -->|"No"| RP["ralplan으로 대체"]
    RG -->|"Yes"| ACT

    SK["Skill 직접 호출"] -->|"/team, /ralph 등"| ACT

    Note1["team 키워드 감지는<br/>명시적으로 비활성화됨<br/>(never-match regex)"]
    style Note1 fill:#ffd,stroke:#aa0

keyword-detector가 실행 키워드를 감지하되, applyRalplanGate()로 프롬프트 품질을 검증한다. 15단어 미만이고 구체적 신호(파일 경로, 함수명 등)가 없으면 실행 모드 대신 ralplan(계획 모드)으로 대체된다.

team 모드의 키워드 감지는 (?!x)x(절대 매칭 불가 정규식)로 설정되어 스킬 직접 호출(/team)으로만 활성화 가능하다.

Stale State 방지

clearStaleSessionDirs()가 세션 디렉토리를 정리한다:

function clearStaleSessionDirs(
  cwd: string,
  maxAgeMs: number = 24 * 60 * 60 * 1000  // 기본 24시간
): string[]

디렉토리 내 가장 최신 파일의 mtimeMs를 기준으로, 24시간 이상 경과한 세션 디렉토리를 제거한다. 빈 디렉토리는 즉시 정리.

Persistent Mode — Stop Hook의 종료 차단

아키텍처

hooks.json의 Stop 이벤트에 등록된 3개 훅:

1. context-guard-stop.mjs (5초) — 컨텍스트 가드
2. persistent-mode.cjs (10초) — 메인 종료 차단기
3. code-simplifier.mjs (5초) — 코드 단순화

우선순위별 체크 순서

checkPersistentModes()가 다음 순서로 검사한다:

graph TD
    START["Stop 이벤트 수신"] --> CRIT{"Critical Context?<br/>(95%+ 또는 429/401/403<br/>또는 /cancel)"}
    CRIT -->|"Yes"| ALLOW["종료 허용<br/>{ continue: true }"]
    CRIT -->|"No"| CANCEL{"cancel-signal.json<br/>존재 + 유효?"}
    CANCEL -->|"Yes"| ALLOW
    CANCEL -->|"No"| P1["P1: Ralph 체크"]
    P1 -->|"활성"| BLOCK["종료 차단<br/>{ continue: false,<br/>message: '...' }"]
    P1 -->|"비활성"| P15["P1.5: Autopilot 체크"]
    P15 -->|"활성"| BLOCK
    P15 -->|"비활성"| P17["P1.7: Team Pipeline<br/>(max 20회, TTL 5분)"]
    P17 -->|"활성"| BLOCK
    P17 -->|"비활성"| P18["P1.8: Ralplan<br/>(max 30회, TTL 45분)"]
    P18 -->|"활성"| BLOCK
    P18 -->|"비활성"| P2["P2: Ultrawork 체크"]
    P2 -->|"활성"| BLOCK
    P2 -->|"비활성"| P3["P3: Skill Active State"]
    P3 -->|"활성"| BLOCK
    P3 -->|"비활성"| ALLOW

응답 포맷

function createHookOutput(result: PersistentModeResult): {
  continue: boolean;
  message?: string;
} {
  return {
    continue: !result.shouldBlock,
    message: result.message || undefined
  };
}

상황	응답
종료 차단	{ "continue": false, "message": "<계속 작업 프롬프트>" }
종료 허용	{ "continue": true }

Circuit Breaker (Stop-Breaker)

각 모드는 무한 차단을 방지하기 위한 회로 차단기를 가진다:

모드	최대 강화 횟수	TTL
Team Pipeline	20회	5분
Ralplan	30회	45분
Deep-interview	10회	30분

Ralph의 특수 동작

Ralph 모드에서 state.iteration >= state.max_iterations에 도달하면 종료하지 않고 한도를 10 추가 확장한다:

state.max_iterations += 10;
writeRalphState(workingDir, state, sessionId);

Ralph의 유일한 종료 방법은 명시적 /oh-my-claudecode:cancel 명령이다.

Notepad — 컨텍스트 압축 대응 메모리

Claude Code는 컨텍스트 윈도우가 가득 차면 Compact(압축)을 수행한다. 이전 대화가 요약되면서 세부 정보가 유실된다.

3섹션 구조

.omc/notepad.md의 고정 구조:

# Notepad
<!-- Auto-managed by OMC. Manual edits preserved in MANUAL section. -->
 
## Priority Context
<!-- ALWAYS loaded. Keep under 500 chars. Critical discoveries only. -->
 
## Working Memory
<!-- Session notes. Auto-pruned after 7 days. -->
 
## MANUAL
<!-- User content. Never auto-pruned. -->

섹션	쓰기 방식	최대 크기	생명주기
Priority Context	REPLACE (교체)	500자 권장 (hard limit 2000)	영구 유지, SessionStart 시 항상 주입
Working Memory	APPEND (추가)	4000자/항목	7일 후 자동 정리
Manual	APPEND (추가)	4000자/항목	자동 정리 없음

전체 파일 크기 제한: 8KB (maxTotalSize: 8192)

Working Memory 항목은 ### YYYY-MM-DD HH:MM 헤더로 타임스탬프가 부여된다.

압축 대응 흐름

sequenceDiagram
    autonumber
    participant CC as Claude Code
    participant PC as pre-compact.mjs
    participant NP as .omc/notepad.md
    participant WD as .omc/notepads/{plan}/
    participant PM as project-memory-precompact.mjs
    participant CC2 as Claude Code (압축 후)

    CC->>CC: 컨텍스트 임계치 도달
    CC->>PC: PreCompact 이벤트
    PC->>PC: 체크포인트 JSON 생성<br/>(.omc/state/checkpoints/)
    PC->>WD: 위즈덤 노트 내보내기<br/>(learnings, decisions, issues)
    PC-->>CC: systemMessage: 활성 모드 + TODO 요약

    CC->>PM: PreCompact 이벤트
    PM-->>CC: systemMessage: project-memory.json 재주입

    CC->>CC: Compact 실행 (이전 대화 요약)

    CC2->>NP: notepad_read("priority")
    NP-->>CC2: Priority Context 복원
    Note over CC2: 압축 전 핵심 정보 복원 성공

Priority Context는 SessionStart 시 자동 주입되어 세션이 시작될 때마다 핵심 정보가 컨텍스트에 로드된다. PreCompact hook은 체크포인트를 생성하고 플랜별 위즈덤 노트(notepads/ 하위)를 내보내는 역할이다.

Project Memory — 프로젝트 지식

데이터 구조

.omc/project-memory.json의 실제 스키마 (src/hooks/project-memory/types.ts):

{
  "version": "1.0.0",
  "lastScanned": 1710849600000,
  "projectRoot": "/path/to/project",
  "techStack": {
    "languages": ["typescript"],
    "frameworks": ["express"],
    "buildTools": ["esbuild"]
  },
  "build": {
    "buildCommand": "npm run build",
    "testCommand": "npm test",
    "lintCommand": "npm run lint",
    "devCommand": "npm run dev",
    "scripts": {}
  },
  "conventions": {
    "namingStyle": "camelCase",
    "importStyle": "esm",
    "testPattern": "*.test.ts",
    "fileOrganization": "feature-based"
  },
  "structure": {},
  "customNotes": [],
  "directoryMap": {},
  "hotPaths": [],
  "userDirectives": []
}

필드명 주의: build (buildInfo), conventions (codeConventions)

학습 경로 3가지

graph TD
    SS["SessionStart<br/>session-start.mjs"] -->|"detectProjectEnvironment()"| PM[".omc/project-memory.json"]
    PT["PostToolUse<br/>project-memory-posttool.mjs"] -->|"learnFromToolOutput()"| PM
    PC["PreCompact<br/>project-memory-precompact.mjs"] -->|"formatContextSummary()"| SYS["systemMessage로 재주입"]

    subgraph "PostToolUse 학습 대상"
        R["Read/Edit/Write → 파일 핫패스"]
        G["Glob/Grep → 디렉토리 핫패스"]
        B["Bash → 빌드/테스트 명령, 환경 힌트"]
        U["User 메시지 → 지시사항 감지"]
    end

    PT --> R
    PT --> G
    PT --> B
    PT --> U

• SessionStart: shouldRescan()이 true(24시간 경과 또는 파일 미존재)이면 detectProjectEnvironment()로 프로젝트 자동 감지
• PostToolUse: learnFromToolOutput()이 도구 출력에서 핫패스, 빌드 명령, 환경 힌트를 추출. customNotes는 최대 20개 (초과 시 가장 오래된 항목 제거)
• PreCompact: formatContextSummary(memory)를 systemMessage로 반환하여 압축 후에도 프로젝트 지식이 유지됨. userDirectives에는 “압축 후에도 반드시 따라야 함” 지시 포함

Session Lifecycle 전체 흐름

graph TD
    A["SessionStart"] -->|"session-start.mjs (5s)<br/>project-memory-session.mjs (5s)<br/>setup-init.mjs (30s, matcher: init)<br/>setup-maintenance.mjs (60s, matcher: maintenance)"| B["초기 설정 완료"]
    B --> C["사용자 입력"]
    C -->|"UserPromptSubmit"| D["keyword-detector.mjs (5s)<br/>skill-injector.mjs (3s)"]
    D --> E["작업 진행"]

    E -->|"PreToolUse"| F["pre-tool-enforcer.mjs (3s)"]
    F --> G["도구 실행"]
    G -->|"PostToolUse"| H["post-tool-verifier.mjs (3s)<br/>project-memory-posttool.mjs (3s)"]
    H --> E

    G -->|"PostToolUseFailure"| HF["post-tool-use-failure.mjs (3s)"]
    HF --> E

    E -->|"SubagentStart"| SA["subagent-tracker.mjs start (3s)"]
    SA -->|"SubagentStop"| SB["subagent-tracker.mjs stop (5s)<br/>verify-deliverables.mjs (5s)"]

    E -->|"PreCompact"| I["pre-compact.mjs (10s)<br/>project-memory-precompact.mjs (5s)"]
    I -->|"Compact 실행"| E

    E -->|"Stop"| J{"persistent-mode.cjs<br/>(10s)"}
    J -->|"continue: false"| K["종료 차단 → 계속"]
    K --> E
    J -->|"continue: true"| L["종료 허용"]

    L -->|"SessionEnd"| M["session-end.mjs (10s)<br/>메트릭 기록 + 상태 정리"]

나만의 플러그인을 만든다면

최소 상태 관리로 “완료까지 멈추지 않는” 모드를 구현하는 패턴:

// 상태 기록 (keyword-detector에서)
const state = {
  active: true,
  started_at: new Date().toISOString(),
  original_prompt: prompt
};
writeFileSync('.omc/state/my-mode-state.json', JSON.stringify(state));

// 상태 읽기 (Stop hook에서)
const state = JSON.parse(readFileSync('.omc/state/my-mode-state.json'));
if (state.active) {
  // 종료 차단: continue: false가 핵심
  console.log(JSON.stringify({ continue: false, message: "작업 계속 진행" }));
} else {
  console.log(JSON.stringify({ continue: true }));
}

참고 문서

• 소스: ~/Documents/study/oh-my-claudecode/src/hooks/mode-registry/
• 소스: ~/Documents/study/oh-my-claudecode/src/hooks/persistent-mode/
• 소스: ~/Documents/study/oh-my-claudecode/src/hooks/notepad/
• 소스: ~/Documents/study/oh-my-claudecode/src/hooks/project-memory/
• 소스: ~/Documents/study/oh-my-claudecode/src/hooks/pre-compact/