oh-my-toong

# oh-my-toong

한국어 | **[English](README.en.md)**

**나의 Claude Code 설정 라이브러리 - 프로젝트별로 복사해서 커스터마이징하는 스킬, 에이전트, 훅 모음**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Acknowledgments

이 프로젝트는 아직 놀이터 수준이지만, Claude Code 커뮤니티 덕분에 정말 많이 배우고 성장하고 있습니다.

다음 프로젝트들에서 영감을 받고, 공부하고, 참고하며 개발하고 있습니다. 감사합니다.

- [everything-claude-code](https://github.com/affaan-m/everything-claude-code)
- [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode)
- [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)
- [claude-hud](https://github.com/jarrodwatts/claude-hud)
- [superpowers](https://github.com/obra/superpowers)
- [team-attention](https://github.com/team-attention/plugins-for-claude-natives)

---

## oh-my-toong이란?

Claude Code의 Skill 도구는 프로젝트의 `.claude/` 디렉토리 안에 있는 파일만 인식합니다. 이 때문에 모든 프로젝트가 각자 스킬 파일을 가져야 하지만, 같은 이름의 스킬(`testing`, `implementation` 등)이라도 프로젝트의 언어와 컨벤션에 따라 내용이 달라야 합니다. oh-my-toong은 이 딜레마를 해결하는 설정 라이브러리입니다. 스킬, 에이전트, 훅을 이 저장소에서 버전 관리하고, `sync.yaml`로 필요한 것만 선택적으로 대상 프로젝트의 `.claude/`에 동기화합니다. 프로젝트별 오버라이드(`projects/`)를 통해 같은 이름의 스킬이라도 프로젝트 특성에 맞게 분화할 수 있습니다.

## 주요 기능

- **스킬 기반 워크플로우** - Skill 도구를 통해 필요할 때 로드되는 작업별 방법론
- **특화된 에이전트** - 명확한 역할 경계를 가진 위임용 서브에이전트
- **세션 훅** - 지속 모드와 키워드 감지를 위한 라이프사이클 스크립트
- **프로젝트별 스킬 분화** - 상위 검색 로직으로 글로벌 스킬 위에 프로젝트 고유 컨벤션 오버라이드
- **선언적 동기화** - `sync.yaml`로 스킬/에이전트/훅을 대상 프로젝트의 `.claude/`에 동기화

## 철학

### 왜 이 설계인가

**1단계 - 기술적 제약**: Claude Code의 Skill 도구는 프로젝트의 `.claude/` 디렉토리에 있는 파일만 인식합니다. 외부 경로에서 스킬을 불러오는 플러그인 시스템이 없으므로, 모든 프로젝트가 자신의 `.claude/` 안에 스킬 파일을 직접 가져야 합니다.

**2단계 - 같은 이름, 다른 내용**: 각 프로젝트에 동일한 스킬을 복사하면 되지만, 핵심 딜레마가 있습니다. 예를 들어 `testing`은 Kotlin/Spring 프로젝트에서 "Classical TDD, verify() 금지, BDD 구조"를 의미하지만, 다른 프로젝트에서는 완전히 다른 컨벤션을 가질 수 있습니다. `implementation`도 마찬가지입니다. **동일한 이름의 스킬이 프로젝트마다 다른 내용을 담아야 합니다.**

**3단계 - 중앙 관리 + 프로젝트 분화**: oh-my-toong은 이 딜레마를 두 가지 메커니즘으로 해결합니다:
- **글로벌 스킬** (`skills/`): 프로젝트에 관계없이 공통인 스킬(prometheus, sisyphus, diagnose 등)을 한 곳에서 버전 관리
- **프로젝트 오버라이드** (`projects/<name>/skills/`): 프로젝트마다 달라야 하는 스킬(testing, implementation)을 프로젝트별로 분화

동기화 시 **상위 검색(Upward Search)** 로직이 동작합니다: 프로젝트의 sync.yaml에서 `testing`을 참조하면, 먼저 해당 프로젝트의 `projects/<name>/skills/testing/`을 찾고, 없으면 글로벌 `skills/testing/`으로 폴백합니다.

### 에이전틱 개발 (Agentic Development)

oh-my-toong은 **에이전틱 개발**을 지향합니다. 하나의 AI가 모든 것을 처리하는 대신, 명확한 역할을 가진 에이전트들이 협업합니다:

| 역할 | 에이전트 | 책임 |
|------|----------|------|
| 명세 | spec | 코드 작성 전 종합적인 명세 작성 |
| 기획 | prometheus | 요구사항을 실행 가능한 작업 계획으로 변환 |
| 실행 | sisyphus | 전문 에이전트를 통한 구현 조율 |
| 구현 | sisyphus-junior | 코드 작성 (sisyphus가 위임) |
| 품질 보증 | argus | 구현 품질, 계획 준수, 지시 이행 검증 |

**핵심 원칙**: 관심사 분리를 통해 성급한 구현을 방지하고, 필수 검증을 통해 품질을 보장합니다.

## 핵심 스킬 아키텍처

세 가지 기반 스킬이 **설계 -> 기획 -> 실행** 파이프라인을 형성합니다:

```mermaid
flowchart LR
    subgraph 설계
        spec["spec"]
    end
    subgraph 기획
        prometheus["prometheus"]
    end
    subgraph 실행
        sisyphus["sisyphus"]
    end

    spec -->|"~/.omt/{OMT_PROJECT}/specs/{name}/"| prometheus
    prometheus -->|"~/.omt/{OMT_PROJECT}/plans/*.md"| sisyphus
    sisyphus -->|"검증된 코드"| Done((완료))
```

### spec - 소프트웨어 명세 전문가

**목적**: 불명확한 요구사항의 구현을 방지하고, 포괄적이고 테스트 가능한 명세를 작성합니다.

**핵심 제약**: 사용자 확인 없이 단계를 완료할 수 없습니다. 모든 인수 기준은 테스트 가능해야 합니다.

```mermaid
flowchart TB
    Start([사용자 요청]) --> Phase[단계 선택]
    Phase --> Step[단계 실행]
    Step --> Save[~/.omt/{OMT_PROJECT}/specs/에 저장]
    Save --> Review{spec-reviewer<br/>피드백 필요?}
    Review -->|아니오| Next{다음 단계?}
    Review -->|예| Feedback[Multi-AI 피드백 수신]
    Feedback --> Present[사용자에게 제시]
    Present --> Decision{사용자 결정}
    Decision -->|반영| Step
    Decision -->|건너뛰기| Next
    Decision -->|재검토| Feedback
    Next -->|예| Step
    Next -->|아니오| Complete([명세 완료])
```

**핵심 단계**:
1. 요구사항 - 모호한 요구사항 명확화
2. 아키텍처 - 시스템 구조 변경
3. 도메인 - 상태 머신, 비즈니스 규칙
4. 상세 - 성능, 동시성
5. API - 외부 API 노출

### prometheus - 전략적 기획 컨설턴트

**목적**: 기획과 실행을 분리합니다. 코드 작성 전에 작업 계획을 수립합니다.

**핵심 제약**: **절대 코드를 작성하지 않습니다**. 모든 요청을 기획 요청으로 해석합니다.

```mermaid
flowchart TB
    Start([사용자 요청]) --> Interpret['X 계획 수립'으로<br/>해석]
    Interpret --> Interview[인터뷰 모드]
    Interview --> Research[explore/librarian으로<br/>조사]
    Research --> More{추가<br/>질문?}
    More -->|예| Interview
    More -->|아니오| Criteria{사용자가 인수<br/>기준 제공?}
    Criteria -->|예| Metis[metis 상담]
    Criteria -->|아니오| Draft[기준 초안<br/>-> 사용자 확인]
    Draft --> Metis
    Metis --> Write[~/.omt/{OMT_PROJECT}/plans/*.md에<br/>계획 작성]
    Write --> Handoff([/sisyphus로 전달])
```

**금지된 행위**:
- 코드 파일 작성 (.ts, .js, .py 등)
- 소스 코드 편집
- 구현 명령 실행
- "작업을 수행하는" 모든 행위

### sisyphus - 태스크 오케스트레이터

**목적**: 복잡한 작업을 위임을 통해 조율합니다. 단독 실행하지 않습니다.

**핵심 제약**: **조율한다. 위임한다. 단독 작업 안 함.** 모든 코드 변경(한 줄도) = 위임.

```mermaid
flowchart TB
    Start([사용자 요청]) --> Classify{요청 유형?}
    Classify -->|단순| Direct[직접 도구 사용]
    Classify -->|명시적| Execute[직접 실행]
    Classify -->|탐색적| Explore[explore 에이전트 실행]
    Classify -->|개방형| Interview[심층 인터뷰]

    Interview --> Tasks[태스크 목록 생성]
    Explore --> Tasks

    Tasks --> Loop{대기 중인<br/

... (truncated)