monol - Claude Code Plugin

Documentation

# monol-x - 진화하는 AI 개발 플랫폼

> **성과 기반 자연선택으로 스스로 진화하는 AI 에이전트 시스템**

Claude Code와 함께 멀티 세션, 멀티 worktree 환경에서 효율적으로 작업하며,
**18개의 Cell(모듈)**이 성과에 따라 자동으로 진화합니다.

**📊 [웹 대시보드](#웹-대시보드)** - 브라우저에서 Cell 관리 및 진화 시뮬레이션
**📚 [장기 작업 가이드](docs/guides/LONG-RUNNING-GUIDE.md)** - 2시간+ 자율 작업 방법
**🧬 [진화 시스템](docs/EVOLUTION-JOURNEY.md)** - Cell 진화 메커니즘

## 핵심 개념

```
┌───────────────────────────────────────────────────────────────────────┐
│                           monol-x v1.0                                │
├───────────────────────────────────────────────────────────────────────┤
│  Worktree   │  Session    │  Context   │  Evolution  │  Dashboard    │
│  ─────────  │  ─────────  │  ─────────  │  ─────────  │  ─────────    │
│  브랜치별    │  작업 단위   │  상태 저장  │  Cell 진화   │  웹 시각화    │
│  작업 공간   │  시작/종료   │  복원 가능  │  자연선택    │  실시간 관리  │
└───────────────────────────────────────────────────────────────────────┘
```

### 기본 기능
- **Worktree**: git worktree 기반 병렬 작업 공간
- **Session**: 작업 시작~종료 단위, Claude 세션과 연동
- **Context**: 작업 상태 스냅샷, 나중에 복원 가능
- **Log**: 빠른 메모, 일일/주간 리포트
- **Condition**: 조건 만족까지 장기 작업 지속 (Stop hook)

### Cell 진화 시스템 (v0.7+)
- **Cell**: 독립적인 AI 에이전트 모듈 (18개)
- **Genome**: 능력 가중치 (coding, testing, core 등)
- **Phenotype**: 관찰 가능한 성과 (점수, 트렌드)
- **Evolution**: 성과 기반 자연선택, 변이 생성

---

## 웹 대시보드

브라우저에서 모든 Cell을 시각적으로 관리합니다.

```bash
# 대시보드 시작
monol dashboard start --open

# 상태 확인
monol dashboard status

# 종료
monol dashboard stop
```

### 대시보드 기능

| 탭 | 기능 |
|-----|------|
| **Overview** | 전체 Cell 현황, Diversity Score, Score Trends |
| **Cells** | Cell 목록, 필터링, 상세 조회/편집 |
| **Evolution** | 진화 시뮬레이션, Mutation 생성 |
| **Lineage** | 계보 트리, 부모-자식 관계 |
| **Lessons** | 레슨 포인트 분석 |

### Cell 목록 (18개)

| Cell | Role | Score |
|------|------|-------|
| dev-senior | developer | 92.0 |
| debugger-expert | developer | 88.0 |
| architect-system | planner | 85.0 |
| evaluator-core | evaluator | 85.0 |
| ... | ... | ... |

전체 목록: `monol evolution dashboard`

---

## 설치

이미 설정됨:
- CLI: `~/.zshrc`에 PATH 추가됨
- Plugin: `~/.claude/plugins/monol` 심볼릭 링크

```bash
# 확인
which monol
ls -la ~/.claude/plugins/monol
```

---

## CLI 사용법

### 초기화

```bash
cd /your/project
monol init
```

`.monol/` 디렉토리가 생성됩니다.

### 대시보드

```bash
monol status    # 또는 mn st
```

모든 worktree, 현재 세션, 최근 활동을 한눈에.

### Worktree 관리

```bash
# 목록 보기
monol wt list

# 새 worktree 생성
monol wt add feature-auth           # feature-auth 브랜치로 생성
monol wt add bugfix fix/bug-123     # fix/bug-123 브랜치로 생성

# worktree 제거
monol wt remove feature-auth

# 특정 worktree 상태
monol wt status feature-auth
```

Worktree 생성 후:
```bash
cd ../project-feature-auth    # 새 worktree로 이동
claude                        # Claude 세션 시작
```

### 세션 관리

```bash
# 세션 시작
monol hello "API 개발"        # focus 설정과 함께

# 세션 종료
monol bye "엔드포인트 3개 완성"

# 세션 상태 확인
monol session status

# Claude 세션 목록
monol session list

# 세션 검색
monol session search "API"

# 전체 worktree 세션 오버뷰
monol session overview
```

### 로그 기록

```bash
# 빠른 기록
monol log "인증 모듈 완료"

# 오늘 로그 보기
monol log today

# 최근 로그 목록
monol log list        # 최근 7일
monol log list 14     # 최근 14일

# 로그 검색
monol log search "인증"

# 일일 요약
monol log summary             # 오늘
monol log summary 2024-01-10  # 특정 날짜

# 주간 리포트
monol log weekly      # 이번 주
monol log weekly 1    # 지난 주
```

### 컨텍스트 관리

```bash
# 현재 상태 저장
monol ctx save checkpoint-1
monol ctx save "리팩토링 전" --description "대규모 변경 전 백업"

# 저장된 컨텍스트 목록
monol ctx list

# 컨텍스트 로드/확인
monol ctx load checkpoint-1

# 차이점 확인
monol ctx diff checkpoint-1

# monol.md 편집
monol ctx edit
```

### 조건 기반 장기 작업

```bash
# TODO 완료까지 작업 (가장 권장)
monol condition todo

# 테스트 통과까지
monol condition test "npm test"

# 빌드 성공까지
monol condition build "npm run build"

# 커스텀 스크립트
monol condition script ./check-ready.sh

# 복합 조건
monol condition multi --todo TODO.md --test "npm test"

# 상태 확인
monol condition status

# 강제 종료
monol condition stop
```

**자세한 사용법**: [장기 작업 가이드](docs/LONG-RUNNING-GUIDE.md)

---

## Claude 플러그인 사용법

Claude Code 안에서 슬래시 커맨드로 사용:

### 세션

```
/mn-hello API 개발      # 세션 시작 + 상황 분석 + 제안
/mn-bye 작업 완료       # 세션 종료 + 요약

# 한국어 별칭
/안녕 API 개발
/바이 작업 완료
```

### 대시보드

```
/mn-status              # 전체 현황
/모놀                   # 한국어 별칭
```

### Worktree

```
/mn-wt                  # worktree 목록
/mn-wt add feature-x    # 새 worktree
/mn-wt remove old-wt    # worktree 제거
```

### 로그

```
/mn-log API 완료        # 빠른 기록
/mn-log today           # 오늘 로그
/mn-log weekly          # 주간 리포트

/기록 메모 내용         # 한국어 별칭
```

### 컨텍스트

```
/mn-ctx save backup     # 상태 저장
/mn-ctx load backup     # 상태 복원
/mn-ctx list            # 목록
```

### 검색

```
/mn-search 키워드       # 로그, 세션, 컨텍스트 통합 검색
```

---

## 워크플로우 예시

### 1. 하루 시작

```bash
cd ~/Work/my-project
monol status              # 현황 파악
```

Claude에서:
```
/mn-hello 오늘 할 일
```

→ 이전 세션 요약, 미완료 작업, pull 필요 여부 등 자동 분석

### 2. 새 기능 작업

```bash
monol wt add feature-auth
cd ../my-project-feature-auth
claude
```

Claude에서:
```
/안녕 인증 모듈 개발
```

### 3. 작업 중 기록

```
/기록 JWT 토큰 발급 로직 완료
/기록 리프레시 토큰 구현 중
```

### 4. 컨텍스트 저장 (중요 지점)

```
/mn-ctx save before-refactor
```

### 5. 작업 종료

```
/바이 인증 모듈 1차 완성
```

### 6. 다른 worktree로 전환

```bash
cd ~/Work/my-project      # 메인으로
monol session overview    # 모든 worktree 세션 확인
```

### 7. 주간 리뷰

```bash
monol log weekly
```

---

## 디렉토리 구조

### 프로젝트 내 (.monol/)

```
project/
├── .monol/
│   ├── config.yaml       # 프로젝트 설정
│   ├── state.json        # 현재 상태
│   ├── sessions/         # 세션 기록
│   ├── contexts/         # 저장된 컨텍스트
│   ├── logs/             # 일별 로그 (YYYY-MM-DD.md)
│   └── worktrees/        # worktree 메타 정보
└── monol.md              # 프로젝트 컨텍스트 문서
```

### 글로벌 (~/.monol/)

```
~/.monol/
├── config.yaml           # 글로벌 설정
├── projects/             # 프로젝트 레지스트리
└── templates/            # 템플릿
```

---

## 팁

### Worktree 네이밍 규칙

```
project/              # 메인 (main/master)
project-feature-x/    # 기능 개발
project-bugfix-123/   # 버그 수정
project-experiment/   # 실험
```

### 세션 관리

- **하나의 worktree = 하나의 Claude 세션** 권장
- 세션은 자동으로 Claude 세션과 연동됨
- `/mn-hello`로 시작하면 이전 컨텍스트 자동 로드

### 로그 활용

- 짧게, 자주 기록
- 나중에 검색으로 찾기 쉽게
- 커밋 메시지 작성할 때 참고

### 컨텍스트 저장 타이밍

- 큰 변경 전
- 실험 시작 전
- 하루 끝날 때
- 브랜치 전환 전

---

## 커맨드 요약

| CLI | Claude | 설명 |
|-----|--------|------|
| `monol init` | - | 프로젝트 초기화 |
| `monol status` | `/mn-status`, `/모놀` | 대시보드 |
| `monol hello` | `/mn-hello`, `/안녕` | 세션 시작 |
| `monol bye` | `/mn-bye`, `/바이` | 세션 종료 |
| `monol wt *` | `/mn-wt` | Worktree 관리 |
| `monol log` | `/mn-log`, `/기록` | 로그 기록 |
| `monol ctx *` | `/mn-ctx` | 컨텍스트 관리 |
| `monol session *` | - | 세션 관리 |
| `monol condition *` | `/mn-condition`, `/조건` | 장기 작업 조건 |
| - | `/mn-search` | 통합 검색 |

---

## 조건 타입 상세

### 기본 조건

| 타입 | 사용 시점 | 완료 조건 |
|------|----------|-----------|
| `todo` | 명확한 작업 목록이 있을 때 | 모든 `[ ]` → `[x]` |
| `test` | 테스트 통과가 목표일 때 | 테스트 명령어 성공 (exit 0) |
| `build` | 빌드 성공이 목표일 때 | 빌드 명령어 성공 (exit 0) |
| `script` | 커스텀 검증이 필요할 때 | 스크립트 exit 0 |

### 파일/패턴 조건

| 타입 | 사용 시점 | 완료 조건 |
|------|----------|-----------|
| `file` | 특정 파일 생성이 목표일 때 | 지정 파일 존재 |
| `no_file` | 특정 파일 삭제가 목표일 때 | 지정 파일 없음 |
| `no_pattern` | 코드에서 패턴 제거가 목표일 때 | 코드에서 패턴 사라짐 |

### 복합 조건 (multi)

여러 조건을 동시에 만족해야 할 때:

```bash
# TODO 완료 + 테스트 통과 + 빌드 성공
monol condition multi \
  --todo TODO.md \
  --test "npm test" \
  --build "npm run build"

# TODO 완료 + 코드에서 TODO 주석 제거
monol condition multi \
  --todo TODO.md \
  --no-pattern "// TODO:" "**/*.ts"
```

---

## 쉘 통합

### 프롬프트에 세션 상태 표시

현재 활성 세션을 쉘 프롬프트에 표시합니다:

```bash
# 프롬프트 확인
monol prompt          # [🎪 focus]
monol prompt full     # [🎪 branch:focus]

# zshrc/bashrc에 추가
monol prompt install

# 제거
monol prompt uninstall
```

설치 후 프롬프트 예시:
```
[🎪 API 개발] ~/Work/project $
```

### 자동완성 설정

```bash
# zsh 사용자
echo 'source <(monol completion zsh)' >> ~/.zshrc

# bash 사용자
echo 'source <(monol completion bash)' >> ~/.bashrc

# 적용
source ~/.zshrc  # 또는 ~/.bashrc
```

자동완성 기능:
- 커맨드/서브커맨드 완성 (Tab)
- worktree 이름 동적 완성
- context 이름 동적 완성
- git 브랜치 동적 완성

---

## 문제 해결

### monol 명령어가 없다고 나올 때

```bash
source ~/.zshrc
# 또는 새 터미널 열기
```

### Claude에서 /mn-* 커맨드가 안 될 때

```bash
# 플러그인 링크 확인
ls -la ~/.claude/plugins/monol

# Claude 재시작
```

### jq 관련 에러

```bash
brew install jq
```

---

## 버전

- **v1.0.0** (현재) - 안정화 및 문서 완성
  - Dashboard: 글로벌 에러 핸들러 추가
  - Docs: API 문서화, README 정리
  - Quality: 통합 테스트, 정합성 검증

- **v0.9.0** - 도메인 에이전트 확장
  - Cells: debugger-core, documenter-core 추가
  - Docs: 웹 대시보드 시나리오 문서

- **v0.8.0** - 웹 대시보드 + Cell 메타포
  - Dashboard: FastAPI 서버 + Vanilla JS 프론트엔드
  - Dashboard: Cell CRUD, Mutation 생성, Evolution 시뮬레이션
  - Terminology: Cell 생물학적 용어 체계
    - Module → Cell
    - Foundation Weights → Genome
    - Score/Traits → Phenotype

- **v0.7.0** - 진화 시스템 강화
  - Evolution: 자동 진화 트리거
  - Cells: developer 롤 모듈 확장 (11개)
  - Feedback: 피드백 기반 자동 변이

- **v0.6.0** - 고급 자동화
  - Automation: 컨텍스트 자동 복원, 스마트 요약
  - CI/CD: GitHub Actions, GitLab CI 연동

- **v0.5.0** - 분석 및 인사이트
  - Analytics: 생산성 대시보드, AI 패턴 분석
  - Reports: 주간/월간 리포트 자동 생성

- **v0.4.0** - 팀 협업
  - Team: 세션 공유, 멘션/알림, 활동 피드

- **v0.3.0** - 진화적 에이전트 시스템
  - Foundation: 계층 구조 (core, git, logging, state, testing)
  - Module: 시스템, 세션 평가

- **v0.2.0** - 조건 기반 장기 작업
  - Condition: TODO/Test/Build/Script 조건
  - Stop hook: 조건 만족까지 작업 지속

- **v0.1.0** - 초기 버전
  - Core: config, worktree, session, context, log
  - CLI: monol/mn
  - Plugin: Claude Code 통합