OMC - Keyword Detector

이 문서는 2편 Hook System의 하위 개념으로, 18개 Hook 스크립트 중 keyword-detector.mjs를 다룬다.

---

• keyword-detector.mjs는 UserPromptSubmit Hook에서 사용자 입력을 받아 매직 키워드를 감지하고, 해당 Skill 호출 지시를 Claude context에 주입하는 스크립트
• 5단계 파이프라인: Guard → Extract → Sanitize → Match → Output
• 14개 키워드를 감지하며, 복수 키워드 충돌 시 우선순위 기반으로 해결

작성일: 2026-03-14 소스: keyword-detector.mjs

해당 개념이 필요한 이유

• 사용자가 “ultrawork”, “ralph” 같은 매직 키워드를 입력하면 OMC가 이를 감지해서 적절한 Skill을 로드해야 한다
• Claude Code 자체에는 키워드 감지 기능이 없으므로, UserPromptSubmit Hook에 이 스크립트를 등록하여 처리한다
• 이 스크립트는 hooks.json에서 UserPromptSubmit 이벤트의 첫 번째 스크립트로 등록되어 있어, 모든 사용자 입력에 대해 가장 먼저 실행된다

AS-IS

sequenceDiagram
    autonumber
    participant U as User
    participant CC as Claude Code

    U->>CC: "ultrawork refactor the API"
    CC->>CC: "ultrawork"를 일반 텍스트로 처리
    CC-->>U: 키워드 무시, 일반 응답

TO-BE

sequenceDiagram
    autonumber
    participant U as User
    participant CC as Claude Code
    box OMC
    participant KD as keyword-detector.mjs
    end

    U->>CC: "ultrawork refactor the API"
    CC->>KD: stdin: { prompt, cwd, session_id }
    KD->>KD: sanitize → "ultrawork" 매칭
    KD->>KD: activateState(.omc/state/ultrawork-state.json)
    KD-->>CC: { additionalContext: "[MAGIC KEYWORD: ULTRAWORK] Skill 호출 지시" }
    CC->>CC: Skill tool 호출 → ultrawork SKILL.md 로드

전체 파이프라인 (큰 그림)

graph TD
    A["stdin: JSON"] --> B["1. Guard"]
    B -->|"DISABLE_OMC=1 또는<br/>OMC_TEAM_WORKER"| X1["{ continue: true } 즉시 반환"]
    B -->|"통과"| C["2. Extract"]
    C["extractPrompt()"] --> D["3. Sanitize"]
    D["sanitizeForKeywordDetection()"] --> E["4. Match"]
    E --> F{"매칭 결과"}
    F -->|"0개"| X2["{ continue: true } 패스"]
    F -->|"1개 이상"| G["deduplicate → resolveConflicts()"]
    G --> H["5. Output"]
    H --> H1["cancel → clearStateFiles + Skill 호출"]
    H --> H2["ralph/ultrawork 등 → activateState + Skill 호출"]
    H --> H3["ultrathink/tdd 등 → 메시지 직접 주입 (Skill 호출 없음)"]

1. Guard — 실행 조건 검사

스크립트 최상단에서 실행 여부를 판단하는 3가지 가드:

// Guard 1: 환경변수로 완전 비활성화
if (process.env.DISABLE_OMC === '1' || _skipHooks.includes('keyword-detector')) {
  return { continue: true };
}
 
// Guard 2: Team Worker 내부에서는 키워드 감지 금지
// → "team" 키워드가 다시 감지되면 무한 스폰 루프 발생
if (process.env.OMC_TEAM_WORKER) {
  return { continue: true, suppressOutput: true };
}
 
// Guard 3: 빈 입력
if (!input.trim()) {
  return { continue: true, suppressOutput: true };
}

Team Worker Guard는 실제 버그 방지를 위한 것이다. Team 모드에서 생성된 worker가 사용자 프롬프트를 다시 받으면, “team”이라는 키워드를 재감지하여 또 다른 worker를 생성하는 무한 루프에 빠질 수 있다.

2. Extract — 프롬프트 추출

extractPrompt()는 Claude Code가 보내는 다양한 JSON 구조에서 사용자 텍스트를 추출한다:

function extractPrompt(input) {
  const data = JSON.parse(input);
  if (data.prompt) return data.prompt;                     // 일반 형태
  if (data.message?.content) return data.message.content;  // 메시지 형태
  if (Array.isArray(data.parts)) {                         // 멀티파트 형태
    return data.parts.filter(p => p.type === 'text').map(p => p.text).join(' ');
  }
  return '';
}

파싱 실패 시 빈 문자열을 반환한다 (fail closed — 잘못된 입력에서 false positive 방지).

3. Sanitize — 오탐 방지

sanitizeForKeywordDetection()은 키워드가 아닌 곳에서의 오탐을 방지하기 위해 6단계로 텍스트를 정리한다:

순서	제거 대상	이유
1	XML 태그 블록 <tag>...</tag>	프롬프트 내 XML 구조에서 키워드 오탐
2	Self-closing XML <tag />	동일
3	URL https://...	URL 경로에 키워드 포함 가능
4	파일 경로 /foo/bar/baz	경로에 키워드 포함 가능
5	코드 블록 ```...```	코드 안 키워드는 의도한 명령이 아님
6	인라인 코드 `...`	동일

예: 사용자가 "https://example.com/ultrawork/docs를 봐" 라고 입력하면, URL을 먼저 제거하므로 “ultrawork”가 키워드로 오탐되지 않는다.

4. Match — 키워드 매칭

14개 키워드 (우선순위 순)

우선순위	키워드	트리거 패턴	출력 방식
1	cancel	cancelomc, stopomc	state 삭제 + Skill 호출
2	ralph	ralph, don't stop, must complete, until done	state 생성 + Skill 호출
3	autopilot	autopilot, build me an app, i want a, e2e this 등	state 생성 + Skill 호출
4	ultrawork	ultrawork, ulw, uw	state 생성 + Skill 호출
5	ccg	ccg, claude-codex-gemini	Skill 호출
6	ralplan	ralplan	Skill 호출
7	deep-interview	deep interview, ouroboros	Skill 호출
8	ai-slop-cleaner	ai slop, anti slop + action+smell 조합	Skill 호출
9	tdd	tdd, test first, red green	메시지 직접 주입
10	code-review	code review, review code	메시지 직접 주입
11	security-review	security review, review security	메시지 직접 주입
12	ultrathink	ultrathink, think hard, think deeply	메시지 직접 주입
13	deepsearch	deepsearch, search the codebase, find in code	Skill 호출
14	analyze	deep analyze, deepanalyze	메시지 직접 주입

두 가지 출력 방식

키워드는 감지 후 두 가지 방식으로 처리된다:

Skill 호출 방식 (cancel~deepsearch): createSkillInvocation()으로 Claude에게 “이 Skill을 실행하라”는 지시를 주입한다.

[MAGIC KEYWORD: ULTRAWORK]
You MUST invoke the skill using the Skill tool:
Skill: oh-my-claudecode:ultrawork

메시지 직접 주입 방식 (tdd, code-review, security-review, ultrathink, analyze): Skill 호출 없이 XML 태그로 감싼 지시 메시지를 additionalContext에 직접 주입한다.

<tdd-mode>
[TDD MODE ACTIVATED]
Write or update tests first when practical...
</tdd-mode>

ai-slop-cleaner의 특수한 매칭 로직

다른 키워드는 단순 정규식이지만, ai-slop-cleaner는 2가지 조건의 조합으로 매칭한다:

// 방법 1: 명시적 키워드
/\b(ai[\s-]?slop|anti[\s-]?slop|deslop)\b/
 
// 방법 2: action + smell 조합
action: clean, refactor, simplify, dedupe, prune ...
smell:  slop, duplicate, dead code, over-abstraction, tech debt ...
// "duplicated code를 clean up해줘" → action(cleanup) + smell(duplicated) → 매칭

5. Output — 충돌 해결과 최종 출력

resolveConflicts() — 우선순위 해결

복수 키워드가 동시에 매칭되면 resolveConflicts()가 우선순위로 정렬한다:

cancel > ralph > autopilot > ultrawork > ccg > ralplan > ... > analyze

• cancel은 배타적 — 다른 모든 키워드를 무시하고 cancel만 실행
• 나머지는 공존 가능 — 우선순위 순으로 정렬하여 모두 실행

ralph 활성화 시 ultrawork 자동 연동

ralph가 감지되고 ultrawork가 없으면, ultrawork state도 자동으로 생성한다:

if (hasRalph && !hasUltrawork) {
  activateState(directory, prompt, 'ultrawork', sessionId);
}

ralph는 “작업 완료까지 멈추지 마”이고, ultrawork는 “병렬로 실행하라”이므로 함께 사용하는 것이 자연스럽다.

activateState() — 상태 파일 생성

ralph, autopilot, ultrawork 3개 키워드만 상태 파일을 생성한다:

.omc/state/sessions/{sessionId}/ultrawork-state.json

{
  "active": true,
  "started_at": "2026-03-14T...",
  "original_prompt": "ultrawork refactor the API",
  "session_id": "abc123",
  "reinforcement_count": 0
}

이 state 파일은 나중에 persistent-mode.cjs (Stop Hook)가 읽어서 종료를 차단하는 데 사용된다.

createHookOutput() — Claude Code에 전달

최종 결과는 항상 같은 포맷으로 stdout에 출력된다:

{
  "continue": true,
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "[MAGIC KEYWORD: ULTRAWORK]\nYou MUST invoke the skill..."
  }
}

참고 문서

• keyword-detector.mjs 소스
• OMC - Hook System — Hook 시스템 전체 구조