https://github.com/yesonsys03-web/vibelign

AI coding safety CLI for vibe coding workflows. Checkpoints, undo, anchors, MCP, and secret protection for Claude Code, Cursor, Codex, and OpenCode.
https://github.com/yesonsys03-web/vibelign

ai-coding ai-safety claude-code cli code-safety codex cursor developer-tools mcp python vibe-coding vibelign

Last synced: 2 days ago
JSON representation

AI coding safety CLI for vibe coding workflows. Checkpoints, undo, anchors, MCP, and secret protection for Claude Code, Cursor, Codex, and OpenCode.

• Host: GitHub
• URL: https://github.com/yesonsys03-web/vibelign
• Owner: yesonsys03-web
• License: mit
• Created: 2026-03-12T06:54:21.000Z (3 months ago)
• Default Branch: main
• Last Pushed: 2026-05-29T01:10:56.000Z (13 days ago)
• Last Synced: 2026-05-29T02:21:30.355Z (13 days ago)
• Topics: ai-coding, ai-safety, claude-code, cli, code-safety, codex, cursor, developer-tools, mcp, python, vibe-coding, vibelign
• Language: Python
• Homepage: https://yesonsys03-web.github.io/VibeLign/
• Size: 111 MB
• Stars: 19
• Watchers: 0
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.ko.md
  • Changelog: CHANGELOG.md
  • License: LICENSE
  • Agents: AGENTS.md

Awesome Lists containing this project

README

          


  





  🇰🇷 한국어  |  🇺🇸 English





  

  





  

  

  

  

  



---

# 🎮 VibeLign — AI 코딩의 안전장치

VibeLign(`vibelign`)은 바이브 코딩 작업을 더 안전하게 해주는 AI 코딩 안전 **CLI + 데스크톱 GUI** 예요.

프로젝트 구조 보호, 체크포인트 저장, 되돌리기, 앵커 관리, 커밋 전 비밀정보 차단을 도와줘요.

> **🆕 v2.2**: GUI ↔ Rust core 다이렉트 브리지(in-process, Python subprocess 없이 ~80ms → <5ms), 통합 에러 로그 뷰 + GitHub 이슈 자동 보고, 자동 백업 실패 가시화. [CHANGELOG](https://github.com/yesonsys03-web/VibeLign/blob/main/CHANGELOG.md) 참고. v1 → v2 사용자: [마이그레이션 가이드](https://github.com/yesonsys03-web/VibeLign/blob/main/MIGRATION_v1_to_v2.md).

문서: `https://yesonsys03-web.github.io/VibeLign/`  

저장소: `https://github.com/yesonsys03-web/VibeLign`  

이슈: `https://github.com/yesonsys03-web/VibeLign/issues`  

릴리즈: `https://github.com/yesonsys03-web/VibeLign/releases`

> ### 이런 적 있나요?

>

> - AI한테 간단한 기능을 추가해달라고 했더니 **파일 전체를 다시 썼어요**

> - 모든 코드가 `main.py` 한 파일에 들어있어요 — **1000줄 넘음, 관리 불가능**

> - AI가 다른 파일을 건드려서 이제 아무것도 안 돼요

> - 되돌리려고 하는데 방법을 몰라요

>

> **이거를 위해 만들었어요!**

**데스크톱 앱 (macOS / Windows)** — [📥 최신 릴리즈 다운로드](https://github.com/yesonsys03-web/VibeLign/releases/latest)

**Mac / Linux (CLI)**

```bash

pip install vibelign

vib start

```

**Windows** (PowerShell, CLI)

```powershell

# 1단계: uv 설치 — 최초 1회, PATH 자동 설정, 경고 없음

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# PowerShell 껐다 켜고:

uv tool install vibelign

vib start

```

![퀵 스타트](https://raw.githubusercontent.com/yesonsys03-web/VibeLign/main/assets/quickstart_kr.jpeg)

---

## 🤔 VibeLign이 뭔가요?

AI 코딩 도구(Claude Code, Cursor 등)는 코드를 빨리 작성해요. 하지만 **문제**가 있어요:

| 문제 | VibeLign이 해결해줌 |

|------|---------------------|

| 모든 코드가 `main.py`에 들어감 | AI가 **알아서 정리**하게 함 |

| AI가 요청한 것과 다른 걸 함 | **정확한 수정 요청**을 만들어줌 |

| 코드가 망가졌는데 되돌릴 수 없음 | **세이브 & 되돌리기** 기능 제공 |

**어떤 AI 도구와도 함께 쓸 수 있어요**: Claude Code · Cursor · Codex · OpenCode

---

## 📝 딱 3가지만 기억하세요

```

AI가 코딩하기 전  →  vib checkpoint "작업 전"     # 세이브

AI가 망쳤어       →  vib undo                      # 되돌리기

괜찮아졌어        →  vib checkpoint "완료"          # 다시 세이브

```

> Git 몰라도 돼요. 그냥 `vib`만 치면 돼요.

---

## 🚀 3단계로 시작하기

**Mac / Linux**

```bash

# 1. 설치

pip install vibelign

# 2. 프로젝트 폴더로 이동

cd my-project

# 3. 시작!

vib start

```

**Windows** (PowerShell)

```powershell

# 1. uv 설치 — 최초 1회 (PATH 자동 설정, 경고 없음)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# PowerShell 껐다 다시 켜고:

# 2. vibelign 설치

uv tool install vibelign

# 3. 프로젝트 폴더로 이동 후 시작!

cd my-project

vib start

```

---

## 📚 모든 명령어

### 기본 (꼭 알아두기)

| 명령어 | 하는 일 |

|--------|---------|

| `vib start` | 처음 한 번만! 프로젝트 세팅 |

| `vib checkpoint "메시지"` | 지금 상태 저장 (게임 세이브처럼) |

| `vib checkpoint` | 저장할 때 메시지 입력하라고 뜸 |

| `vib undo` | 마지막 세이브 지점으로 돌아감 |

| `vib history` | 세이브 목록 보기 |

| `vib backup-db-viewer --json` | Rust 백업 DB를 읽기 전용으로 확인 |

| `vib backup-db-maintenance --json` | 백업 DB 파일 정리 계획을 dry-run으로 확인 |

| `vib backup-db-maintenance --apply --json` | DB 파일 백업 후 WAL 정리와 조건부 DB 압축 실행 |

### AI한테 코딩 요청할 때

| 명령어 | 하는 일 |

|--------|---------|

| `vib patch "버튼 추가해줘"` | AI에게 어떻게 수정할지 알려줌 (한국어 OK!) |

| `vib anchor` | AI가 수정해도 되는 곳을 표시해줌 |

| `vib scan` | 파일 정리 + 최신 상태 확인 |

### VibeLign patch 규칙

- 복합 요청은 `intent / source / destination / behavior_constraint`로 먼저 분해한다.

- `삭제`와 `이동`이 같이 나오면, 사용자가 분명히 삭제를 원하지 않는 한 이동 + 보존으로 본다.

- `source`와 `destination`은 같은 규칙으로 처리하지 말고 역할별로 따로 해석한다.

- patch contract나 codespeak 구조가 바뀌면 테스트와 문서도 같이 갱신한다.

- 용어는 공통 문서와 glossary 기준으로 맞춘다.

### 확인하고 검증할 때

| 명령어 | 하는 일 |

|--------|---------|

| `vib doctor` | 프로젝트 건강 상태 확인 |

| `vib explain` | 뭐가 바뀌었는지 쉬운 말로 설명 |

| `vib guard` | 코드가 망가지지 않았는지 확인 |

| `vib ask 파일명.py` | 파일이 뭘 하는지 설명해달라고 함 |

### 파일 보호

| 명령어 | 하는 일 |

|--------|---------|

| `vib protect 파일명.py` | 중요한 파일 잠금 (AI가 못 건드림) |

| `vib protect --list` | 잠근 파일 목록 보기 |

| `vib protect --remove 파일명.py` | 잠금 해제 |

| `vib secrets --staged` | 지금 커밋할 내용에서 API 키, 토큰, `.env` 파일 차단 |

### 설정 & 내보내기

| 명령어 | 하는 일 |

|--------|---------|

| `vib config` | API 키 설정 |

| `vib export claude` | Claude Code용 설정 파일 만들기 |

| `vib export cursor` | Cursor용 설정 파일 만들기 |

| `vib export opencode` | OpenCode용 설정 파일 만들기 |

### 기타 유용한 것들

| 명령어 | 하는 일 |

|--------|---------|

| `vib watch` | 파일 변경 실시간 감시 |

| `vib bench` | 앵커가 얼마나 효과적인지 테스트 |

| `vib manual` | 상세 사용 설명서 보기 |

| `vib rules` | AI 개발 규칙 전체 보기 |

| `vib transfer` | AI 도구 전환용 `PROJECT_CONTEXT.md` 생성 |

| `vib transfer --handoff` | Session Handoff 블록 추가 — 새 AI가 바로 이어서 작업 가능 |

| `vib transfer --handoff --session-summary "작업 요약" --first-next-action "다음 할 일"` | handoff 요약과 다음 작업을 직접 지정 |

| `vib transfer --handoff --dry-run` | 파일 저장 없이 handoff 내용 미리 보기 |

| `vib completion` | 탭 누르면 자동완성되게 설정 |

| `vib install` | 설치 방법을 단계별로 알려줌 |

---

## 💡 추천하는 흐름

```bash

# 처음 시작할 때

vib start

# AI가 코딩하기 전

vib checkpoint "로그인 기능 추가 전"

vib doctor --strict

vib patch "로그인 버튼 만들어줘"

# AI가 코딩한 후

vib explain --write-report

vib guard --strict --write-report

# 다 됐으면

vib checkpoint "로그인 기능 완성!"

# 실수했으면

vib undo

# 토큰 한도 도달 또는 AI 툴 전환 전에

vib transfer --handoff    # Session Handoff 블록 생성

vib transfer --handoff --no-prompt --print  # 자동 생성 + 콘솔 출력

vib transfer --handoff --session-summary "현재 세션 작업" --first-next-action "테스트 재실행"

vib transfer --handoff --dry-run  # 저장 전 미리 보기

# 새 AI에게: "PROJECT_CONTEXT.md 상단의 Session Handoff 블록 먼저 읽어줘"

```

`transfer` 호환성: `--handoff`는 `--compact` 또는 `--full`과 함께 쓸 수 없습니다.

이제 `vib start`를 실행하면 Git 저장소에서는 비밀정보 커밋 보호도 자동으로 켜져요.

커밋 전에 지금 올리려는 내용에서 API 키, 토큰, 개인키, `.env` 같은 비밀정보 파일을 검사해서 실수 업로드를 막아줘요.

```bash

# 필요하면 수동 검사도 가능

vib secrets --staged

```

---

## 🔧 설치 방법

### 방법 1: uv (추천, 빠름)

```bash

uv tool install vibelign

```

> **설치 후 "is not on your PATH" 경고가 뜨면:**

> ```bash

> uv tool update-shell

> ```

> 그 다음 터미널 껐다 다시 켜면 `vib` 바로 사용 가능해요.

> **bash 쉘**을 쓴다면 bash 안에서 `uv tool update-shell`을 실행하거나:

> ```bash

> echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

> ```

### 방법 2: pip

```bash

pip install vibelign

```

설치하면 `vib`랑 `vibelign` 둘 다 쓸 수 있어요.

### 방법 3: 데스크톱 앱 (GUI)

최신 `.dmg` (macOS, Apple Silicon) 또는 `.exe` / `.msi` (Windows) 를

[Releases 페이지](https://github.com/yesonsys03-web/VibeLign/releases/latest) 에서 받으세요.

GUI 에는 `vib` 런타임이 함께 번들링 되어 있어서 별도의 CLI 설치가 필요 없어요.

> macOS 첫 실행 시 "앱이 손상되었습니다" 오류가 뜨면 터미널에서 `xattr -rc vibelign-gui.app` 실행

> (Apple 공증(notarization) 없이 배포된 ad-hoc 서명이라 정상적인 Gatekeeper 경고예요).

### Windows — pip으로 설치 후 `vib`가 안 될 때

pip으로 설치하면 `vib.exe`가 Python `Scripts` 폴더에 들어가는데, 이 폴더가 PATH에 없으면 `vib` 명령어를 인식 못해요.

설치할 때 뜨는 경고 메시지에 추가해야 할 경로가 정확히 나와 있어요:

```

WARNING: The scripts vib.exe ... are installed in 'C:\Users\...\Scripts' which is not on PATH.

```

**수동으로 PATH 설정하는 방법:**

1. `Win + R` → `sysdm.cpl` 입력 → 엔터

2. **고급** 탭 → **환경 변수**

3. **시스템 변수**의 `Path` → **편집**

4. **새로 만들기** 클릭 후 경고 메시지에 나온 `Scripts` 경로 붙여넣기

   - 예: `C:\Users\사용자이름\AppData\Local\Programs\Python\Python312\Scripts\`

5. 확인 → PowerShell 완전히 껐다 다시 켜기

> **팁:** `uv tool install vibelign`을 쓰면 이 과정이 필요 없어요 — PATH 자동 설정.

---

## 📖 더 자세히 알고 싶으면

```bash

vib manual          # 상세 사용 설명서

vib manual rules    # AI 개발 규칙만 보기

vib rules           # rules랑 같음

```

---

## 🎯 우리 약속

> *"AI 코딩은 빠르다. 하지만 안전장치 없으면 만든 걸 다 날릴 수 있다."*

VibeLign이 보장하는 것:

- ✅ 1초 만에 세이브 (`vib checkpoint "설명"`)

- ✅ 1초 만에 되돌리기 (`vib undo`)

- ✅ Git 몰라도 됨

- ✅ 초보자도 쉽게 쓸 수 있음

---

⭐ **VibeLign이 코드 저장해줬으면 Star 하나 부탁해요 — 감사합니다!**

---

## 📋 업데이트 내역 (Release Notes)

**v2.2.20** — Code Explorer 사이드바에 docs 트리 + 카테고리별 컬러 구분:

- 📚 **사이드바에 `docs/` 폴더 + `.md` 미리보기** — 엔진 `project_scan`(코드 분석 파이프라인과 공유)과 별도로 Tauri 전용 `list_code_files` 스캐너를 신설. `docs/superpowers/specs/*.md`, wiki, release notes 등의 Markdown 문서가 트리에 노출되고 뷰어에서 Markdown 언어 태그로 열림. anchor_tools/patch_suggester/doctor_v2/risk_analyzer 등 코드 도메인 분석은 그대로 유지.

- 🎨 **4색 탭 카테고리 컬러링** — code(녹) / docs(주황) / tests(보라) / other(회색). 파일은 확장자·경로(`.test.*`, `__tests__/`, `spec/`, `tests/`)로, 디렉터리는 하위 파일 다수결로 자동 판정. 각 행에 4px 왼쪽 액센트 바 + 카테고리 배경 틴트 + 카테고리 도트 — 한눈에 구분.

- 🧩 **`vib/*.ts` ANCHOR 마커 일괄 보강** — GUI 도메인 모듈 16개 + DocsViewer 테스트 2건에 `// === ANCHOR: NAME_START === / _END ===` 추가. `vib guard --strict` 의 앵커 경계 검증이 GUI 전 영역에 적용됨.

**v2.2.19** — GUI 코드 탐색기 (read-only 소스 뷰어):

- 🌲 **새 `CODE EXPLORER` 탭** — 프로젝트 소스 트리를 폴더 단위로 탐색(1단계 기본 펼침, 검색 시 자동 펼침)하고 선택 파일을 라인 번호·언어·줄수·바이트와 함께 read-only 로 미리보기. 검색은 경로·카테고리·import 매칭. DocsViewer 와 분리된 도메인으로 page/layout/tree/viewer/toolbar/line 컴포넌트를 나눠 `App.tsx` 는 탭 연결만 담당.

- 🔒 **Rust `read_code_file` command + `code_access.rs` 가드** — 루트 밖 탈출(`..`, 절대경로, Windows UNC/드라이브, symlink) 거부, hidden/generated 디렉터리(`.git`, `node_modules`, `target`…) 제외, Windows 예약 디바이스명(`NUL`, `CON`, `COM1`…) 차단, 확장자 allowlist, 바이너리/비-UTF-8 거부, 크기 캡(코드 1MB / 데이터 5MB). BOM strip + CRLF 정규화 + SHA-256 해시.

- 🧩 **Diff 확장 seam (`CodeDiffViewer`)** — red/green diff 컴포넌트 미리 분리, 실제 diff 소스가 붙기 전 v1 에서는 비활성(미마운트).

**v2.2.18** — 기획 문서 코드 동기화 + GUI tsconfig 테스트 제외:

- 📝 **superpowers plan/spec 문서 5개에 "현재 구현 대조 메모 (2026-05-14)" 추가** — `mcp-host-llm-pivot-plan`, `규칙수정안-3`, `원클릭설치-기획안_초안`, `지식저장고-기획안`, `mcp-host-llm-pivot-eval-runbook` 의 헤더에 "지금 코드와 실제 격차" 를 명시. MCP primitive 2개 mainlined 사실, `vib knowledge` 미구현 사실, `claude doctor` v1 성공 기준 제외 사실 등이 문서 상단에서 바로 보임. 미래 비전과 v1 현실을 분리해 읽도록.

- 🧹 **`vibelign-gui/tsconfig.json` 에서 테스트 파일 제외** — `src/**/__tests__/**`, `*.test.{ts,tsx}`, `src/test/**` 가 `tsc && vite build` 에 끌려 들어가 가짜 type error 를 뿜던 노이즈 정리. `exclude` 항목 추가로 production 빌드만 깨끗해지고 vitest 실행에는 영향 없음.

**v2.2.17** — PyPI publish 큐 적체 해소 (macos-13 → macos-latest):

- ⚡ **macOS wheel runner 를 Apple Silicon 으로 교체** — `macos-13` (Intel x86_64) runner pool 이 GitHub Actions 에서 만성 큐 적체. v2.2.12 부터 PyPI publish 가 시간 단위로 묶였음. `macos-latest` (Apple Silicon arm64) 는 초 단위로 잡힘. 트레이드오프: Intel Mac 사용자는 PyPI binary wheel 대신 sdist 로 설치 (Rust 툴체인 필요).

**v2.2.16** — Phase 9 CI 그린업 (MCP checkpoint handler 테스트):

- 🟢 **`test_handle_checkpoint_create_*` 2건 실패 fix** — Rust 엔진 migration 잔재. `handle_checkpoint_create` 가 `file_count == 0` 도 `summary is None` 과 동일하게 "blocked" 로 audit. list-checkpoints 테스트가 `router.list_checkpoints` 사용해서 Rust 엔진 SQLite 결과를 보도록. v2.2.11 부터 빨갛던 Phase 9 cross-platform CI green.

**v2.2.15** — post-commit hook v5: v3 분기 순서 복원:

- 🔁 **자동 백업 fallback 순서 v3 으로 되돌림** — v4 의 "절대경로 먼저" 구조가 OpenCode + GPT-5.5 같은 일부 LLM commit tool 에서 자동 백업을 전부 누락시킴 (사용자 신고로 재현). v5 는 v3 와 동일하게 PATH 분기를 앞에 두고, 절대경로 분기는 마지막 fallback 으로 강등 — PATH 가 빈약한 GUI commit tool 케이스만 커버. marker v5 로 bump, v1-v4 hook 다음 `vib start` 에서 자동 교체.

**v2.2.14** — `RUST_ENGINE_INTEGRITY_FAILED` runtime self-heal:

- 🛟 **번들 엔진 integrity 가 macOS 에서 자동 회복** — v2.2.13 은 CI codesign step 만 보강해서, 사용자가 로컬에서 `npm run tauri build` (Intel/ARM Mac) 로 직접 빌드한 GUI 에선 integrity check 가 그대로 폭발. 런타임에서 `codesign --verify --strict` 가 통과하는 binary 면 `.sha256` manifest 를 자동 갱신해 회복한다. Windows/Linux 는 codesign 신뢰 신호가 없어 tamper 검사 그대로 유지.

**v2.2.13** — 자동 백업 정합성 hotfix (GUI + GUI commit tool):

- 🩹 **macOS GUI 의 `RUST_ENGINE_INTEGRITY_FAILED` 해소** — `codesign --deep` 가 bundled `vibelign-engine` binary 에 서명 blob 을 추가한 후 `.sha256` manifest 가 재생성되지 않아 모든 Rust 엔진 호출 (history, BACKUPS) 이 integrity check 로 폭발하던 회귀. CI 에서 codesign 직후 manifest 를 재생성하도록 step 보강.

- 🔌 **post-commit 자동 백업이 `vib` PATH 에 의존하지 않음** — Sourcetree / VS Code / Tower 의 commit 은 launchd PATH 만 상속해 `~/.local/bin` 이 빠지는 경우가 흔함. 모든 `command -v vib` fallback 이 false → 자동 백업 누락이던 회귀. install 시점에 `vib` / `vibelign` / `python -m vibelign.cli.vib_cli` 절대 경로를 캡처해 PATH 분기보다 먼저 시도. marker v4 로 bump, v1-v3 hook 다음 `vib start` 에서 자동 교체.

- 🐧 **CI 에서 Linux 빌드 제외** — wheel publish + Python smoke build 가 Ubuntu 에서 빠짐. 타겟은 macOS + Windows.

**v2.2.12** — pre-commit hook 유연화 (guard advisory + skip env):

- 🟢 **`vib guard --strict` 가 commit 을 막지 않음** — guard 실패는 stderr 에 한 줄 알림만 출력하고 commit 통과. `vib secrets --staged` 는 그대로 차단 (시크릿 누출은 비가역, 구조 drift 는 가역이라 비대칭). guard 가 잡던 drift 는 `vib doctor` / 다음 작업에서 계속 잡힘.

- 🚪 **`VIBELIGN_SKIP_HOOK=1 git commit ...`** — 1회용 우회 (`--no-verify` 의도-명확 버전, vib 자체가 실행되지 않음).

- 🔒 **`VIBELIGN_STRICT_GUARD=1`** — strict 팀용 opt-in. 옛 차단 동작 복귀.

- ♻️ **기존 hook 자동 재설치** — `secrets-pre-commit v1` / `pre-commit-enforcement v1`/`v2` 어느 marker 든 다음 `vib start` 에서 v3 로 자동 교체. 수동 정리 불필요.

**v2.2.11** — GUI Patch 카드 노출 제거 (정확도 기반 deprecation):

- 🚫 **Patch 카드 기본 노출에서 제거** — v2.2.10 측정에서 `vib patch` 자연 분포 정확도가 사용자 실 요청 7건 중 0건이었음 (키워드 함정: `--json` → 무관한 Python docs 명령 파일, `--preview` → 무관한 backup-restore 파일). 사용자가 출력을 무비판적으로 따를 경우 무관 파일이 잘못 수정될 위험이 가장 큰 surface 였음. 신규/기존 사용자 모두 Home 카드 목록에서 더 이상 보이지 않음. CLI `vib patch` 는 그대로 유지. 자연어 패치는 Claude Code / Cursor 에서 직접 (vibelign-mcp 는 `vib start` 시 자동 등록).

**v2.2.10** — MCP host-LLM pivot PoC + BACKUPS 페이지네이션 + Explain 카드 옵션 정리:

- 🧠 **신규 MCP 도구** — `anchor_read_content` (앵커 경계 안 텍스트 read, path traversal 방지, `_START`/`_END` 접미사 자동 정규화) + `project_map_get` (프로젝트 카테고리/파일/앵커 인덱스 일괄 반환). host LLM(Claude Code/Cursor)이 사용자 자연어 요청 → 정확한 `file:anchor` 매핑을 직접 수행. 사용자 실 요청 6건에서 baseline `vib patch` 0/6 vs host LLM 6/6 측정.

- 📋 **BACKUPS 파일 기록 + DB Viewer rows 페이지네이션** — 페이지당 10개, "← 이전 / X / Y 페이지 · M–N / TOTAL / 다음 →" 푸터. 리스트가 누적되어도 예전 항목 다시 볼 수 있음. 검색어 변경 시 1페이지 리셋, 선택 항목이 다른 페이지에 있으면 자동 점프.

- 🧹 **Explain 카드 `--write-report` / `--json` 옵션 제거** — GUI 카드 flags 에서만 제거 (CLI 의 동일 플래그는 그대로 지원, 다른 명령은 영향 없음).

- 📚 도그푸딩 증거: `vib patch "gui 익스플레인 카드에서 --write-report --json 옵션은 제거해줘"` → `vib_docs_build_cmd.py` 라는 완전 엉뚱한 파일을 짚음 (JSON 키워드 함정). 신규 MCP 도구로 작업하는 host LLM 은 정답 `commandData.ts` 즉시 짚음. PR #5 description 부록 참조.

**v2.2.9** — v2.2.8 scroll-to-top 버튼이 안 보이던 패치:

- 🔧 **scroll-to-top 이 실제 scroll container 인식** — v2.2.8 의 listener 가 `window.scrollY` 만 보아 mac/Windows 양쪽에서 버튼이 안 보이던 issue. brutalism 레이아웃이 `.page-content` (inner flex child) 에서 scroll 하므로, v2.2.9 가 document 의 capture-phase scroll listener + `.page-content.scrollTop` 직접 읽음. 클릭도 inner container 의 scrollTo 호출.

**v2.2.8** — GUI UX 수정 두 건 + scroll-to-top 버튼:

- 🔧 **복구 후보 추천 — 후보별 AI 설명 표시** — LLM 의 candidate-specific `reason` 필드가 rule-based 근거 아래 별도로 표시되도록 변경. 3 후보가 동일한 "근거" 문구를 보이던 issue 해결. rule-based 5 항목 문구도 친화화 (예: "커밋 직후 저장" → "코드 저장 직후 만든 백업").

- 🔧 **CANVAS / RAW HTML 화면 — iframe 세로가 content/앱 UI 와 맞춰짐** — `CanvasViewPane` 와 `RawHtmlCanvasPane` 둘 다 휴리스틱 추정 fixed-height 에서 `onLoad` content 측정 + `minHeight: calc(100vh - 200px)` 로 변경 (sandbox 는 scripts/forms 여전히 disabled, `allow-same-origin` 만 추가). 짧은 문서는 앱 viewport 만큼 차지, 긴 문서는 왼쪽 사이드처럼 page natural scroll. iframe 안 별도 스크롤바 없음.

- ⬆️ **scroll-to-top floating 버튼** — 페이지 스크롤이 300px 넘으면 우하단에 ↑ 버튼 표시, 클릭 시 부드럽게 최상단으로 이동. 모든 페이지 공통.

**v2.2.7** — 복구 후보 추천 지연 ~46% 단축:

- 🚀 **Recovery 패널 가속** — "복구 후보 추천 보기" (Gemini AI 추천) 첫 호출 wall 이 ~25s → ~13.6s 로 단축. LLM prompt 의 commit_message 본문이 prompt 28KB 의 49% 를 차지하던 것을 subject 첫 줄 (200자 cap) 만 보내도록 변경. 추천 quality 는 보존 (LLM 결정은 source/created_at/evidence_score/commit_boundary 같은 metadata 에 의존, verbose commit body 는 unused).

- 📦 **`score_path.rs` dormant library** — `meaningful_overlap` Rust port + 5 parity tests + ipc variant 가 dormant library 로 추가. score_path 전체 트랙은 skip-rate 측정 결과 leaf-port batch ROI ~0 으로 §9 retraction 됐지만 artifact 는 보존 (미래 사용 + Python alias drift 자동 감지).

- ✅ 측정-주도 lessons (stub-patch wall diff > cProfile cumtime, skip-rate trap, apples-to-apples harness) 이 본 릴리즈의 prerequisite — `docs/superpowers/plans/2026-05-13-*-plan.md` §9 참조.

**v2.2.6** — GUI 메모리 요약 가속 + tokenizer Rust 토대:

- 🚀 **Phase 3 PoC consumer #13** — `SessionMemoryCard` 마운트가 Python sidecar 호출 대신 in-process Rust (`callEngineDirect({command:"memory_summary_read"})`) 로 전환되어 마운트 시 ~80 ms 지연이 사라졌습니다. audit 로그 parity 는 완전히 보존됩니다.

- 📦 **tokenizer Rust leaf port** — `vibelign-core/src/tokenizer.rs` 가 `patch_suggester.py` 의 6 한국어 토큰 leaf 함수를 dormant library 로 포팅했습니다. `tests/fixtures/tokenizer_goldens/` (102 case × 6 함수 = 612 byte-equal parity record) 로 검증합니다.

- ⚡ **`_normalize_korean_token` pre-sort** — 매 호출 `sorted()` 를 module-level 상수로 옮겼습니다. direct 1M iter 27% 가속, recover preview wall 은 noise (caller-side set 처리가 wall dominate).

- ✅ **크로스플랫폼 pre-flight** — Windows GNU cross-compile 이 vibelign-core 와 vibelign-gui/src-tauri 양쪽에서 통과합니다.

**v2.2.5** — 데스크톱 릴리즈 lockfile 수정:

- 📦 **npm lockfile 복구** — GUI package lock 을 정상 재생성해 `npm ci` 가 존재하지 않는 `json5-2.2.4.tgz` 대신 실제 `json5@2.2.3` dependency 를 설치하도록 했습니다.

- ✅ **릴리즈 빌드 재시도** — 실패한 v2.2.4 데스크톱 GUI 릴리즈 시도를 v2.2.5 가 대체합니다.

**v2.2.4** — 데스크톱 릴리즈 호환성 수정:

- 🛠️ **Backup bridge 호환성** — domain-module bridge 리팩토링 이후에도 기존 GUI 화면이 build 되도록 legacy `backupCreate` export 를 복구했습니다.

- ✅ **릴리즈 빌드 재시도** — 실패한 v2.2.3 데스크톱 GUI 릴리즈 시도를 v2.2.4 가 대체하며, 동일한 bridge 모듈화 작업을 포함합니다.

**v2.2.3** — GUI bridge 모듈화 + 개발 로그 정리:

- 🧩 **GUI vib bridge 모듈화** — 거대한 `src/lib/vib.ts` command bridge 를 domain module 로 나누면서 기존 `src/lib/vib` import 경로는 유지했습니다.

- 🛡️ **계약 보존 리팩토링** — Tauri command string, payload shape, Windows onboarding/env 동작, backup cache singleton 동작을 유지했습니다.

- 🧹 **Tauri dev 로그 정리** — `npm run tauri dev` 때 보이던 Rust warning 2개를 제거했습니다.

**v2.2.2** — DocsViewer HTML Canvas + Windows 안정화:

- 🧭 **Document Control Map Canvas** — 원문 순서 Outline, Flow, Decisions, Actions, Risks, Glossary 를 시각적으로 재구성하고 bullet 중심 섹션 preview 누락을 `body_preview` 로 보강.

- 🧾 **Raw HTML artifact mode** — 선택 문서를 sandboxed iframe 의 읽기 쉬운 article-style HTML 로 렌더링.

- 🪟 **Split 탭 UX** — 창 폭과 상관없이 Split 탭을 항상 표시하고, 좁은 창에서는 내부 레이아웃만 1열로 반응.

- ✨ **선택 탭 하이라이트** — Source/Easy/Canvas/Raw HTML/Split 중 현재 탭을 검은 배경 + 오렌지 그림자로 강조.

- 🛠️ **Windows 경로 수정** — `C:\Repo` vs `c:\repo\...` 같은 대소문자 차이에도 추가 문서 소스 폴더 선택이 정상 동작.

**v2.2.0** — GUI 다이렉트 브리지 + 통합 에러 로그 + 자동 백업 가시성:

- 🌉 **Tauri ↔ vibelign-core 다이렉트 브리지** — GUI 가 Python `vib` 서브프로세스 없이 in-process Rust 엔진을 직접 호출. 6개 GUI consumer 의 trivial 명령 wall time 이 ~80ms → <5ms 로 단축.

- 🐛 **GUI 통합 에러 로그 뷰** — CLI/GUI 에러를 한 탭에 통합, GitHub 이슈로 단일/다중 보고, 수정 완료된 에러를 즉시 정리하는 버튼.

- 🛟 **자동 백업 실패 가시화** — post-commit hook 이 더 이상 silent skip 하지 않음. 통합 에러 로그에 자동 기록 + git terminal 에 stderr 노출.

- 🔐 **Rust secret_scan parity** — `VIBELIGN_SECRET_SCAN_RUST=1` 옵트인 시 Rust 구현 사용 (10개 골든 fixture 로 Python 과 1:1 parity 보장).

- 🛠️ 다수의 silent regression fix — `vib memory show` race, `vib doctor | head` BrokenPipeError, integrity manifest 자동 재생성, GUI listener cleanup, 홈 카드 그리드 1fr 1fr 불균형 수정.

**Rust/SQLite 체크포인트 엔진** (v2.1 시리즈):

- `vib checkpoint`, `vib history`, `vib undo`가 Rust/SQLite 체크포인트 엔진을 기본으로 사용합니다. 번들 엔진을 실행할 수 없으면 Python fallback이 사용자에게 표시됩니다.

- 기존 JSON 체크포인트(`.vibelign/checkpoints/`)는 디스크에 보존하지만 새 SQLite 기반 이력에 자동 import/병합하지 않습니다. 오래된 스냅샷이 필요하면 업그레이드 전에 `.vibelign/checkpoints/`를 백업해두세요.

**v2.0.0** — 데스크톱 GUI + MCP/Patch 모듈화 + AI 옵트인:

- 🖥️ **VibeLign GUI (macOS / Windows)** — Tauri 기반 데스크톱 앱

  - Doctor 페이지: 원클릭 진단 + 자동 적용

  - 앵커카드: 앵커 삽입 + intent/aliases 재생성 (코드 기반 / AI 기반, `--force` 로 기존 AI 결과 덮어쓰기)

  - DocsViewer: 문서별 AI 요약

  - Settings: API 키 관리, AI 옵트인 전역 토글

- 🔌 **MCP 서버 재구성** — `vibelign/mcp/` 아래 dispatch/handlers/tool_specs 분리

- 🧩 **Patch 모듈 분리** — `vibelign/patch/` (builder · handoff · preview · targeting · …)

- 🤖 **AI 옵트인** — consent UI 제거, Settings 전역 토글 하나로 통합. Anthropic / OpenAI / Gemini 자동 선택

- ⚡ **onedir 런타임** — PyInstaller `onefile → onedir` 전환으로 GUI 콜드스타트(1~3초) 제거

- 🏷️ **앵커 `_source` 필드** — `anchor_meta.json` 에 `code / ai / manual / ai_failed` 구분 도입해 AI/수동 결과를 코드 기반 재생성으로부터 보호 (`--force` 로 덮어쓰기 가능)

- ⚠️ **Breaking**: `vibelign.vib_cli` → `vibelign.cli.vib_cli`; `vibelign.mcp_server` → `vibelign.mcp.mcp_server`

- 자세한 내용은 [CHANGELOG.md](https://github.com/yesonsys03-web/VibeLign/blob/main/CHANGELOG.md) · [MIGRATION_v1_to_v2.md](https://github.com/yesonsys03-web/VibeLign/blob/main/MIGRATION_v1_to_v2.md)

**v1.6.0** — MCP 서버 + AI 개발 규칙 시스템:

- `vib mcp` — MCP(Model Context Protocol) 서버 실행 (Claude Desktop 연동)

- `vib start` — Claude Code와 Cursor에 VibeLign MCP 자동 등록 (기존 Cursor MCP 서버는 유지)

- `vib rules` — AI 개발 규칙 전체를 CLI에서 바로 확인

- `vib manual rules` — 개발 규칙 상세 매뉴얼

- Anchor intent system — 앵커에 의도(intent) 정보 저장

- 한국어 토크나이저 — patch 요청을 한국어로도 정확하게 해석

- AI_DEV_SYSTEM — 유지보수성/함수 디자인 규칙 추가 (Section 6-1, 14)

- `vib scan` 버그 수정 — set_intent 속성 누락 해결

**v1.5.32** — 체크포인트/되돌리기 UX 개편 + AI 설정 파일 보호:

- `vib checkpoint` — 메시지 입력 프롬프트 지원

- `vib undo` — 번호 선택 + 취소 옵션 `[0]`

- `vib history` — 초 단위 타임스탬프 표시

- `vib start` — 초보자 온보딩 + 첫 체크포인트 자동 저장

- `vib export` — AGENTS.md, CLAUDE.md, OPENCODE.md, .cursorrules 보호

**v1.5.0** — 멀티 AI 툴 설정 내보내기:

- `vib export claude` — Claude Code용 CLAUDE.md 생성

- `vib export cursor` — Cursor용 .cursorrules 생성

- `vib export opencode` — OpenCode용 OPENCODE.md 생성

- `vib export antigravity` — Codex/에이전트용 AGENTS.md 생성

- 내보낸 파일에 VibeLign 마커 추가 (덮어쓰기 방지)

**v1.1.0** — 코알못을 위한 핵심 기능 추가:

- `vib init` — VibeLign 초기화/리셋

- `vib start` — 처음 사용자 가이드

- `vib checkpoint` / `vib undo` — Git 없이 세이브 & 되돌리기

- `vib protect` — 중요 파일 잠금

- `vib ask` — 파일 설명 AI 프롬프트 생성

- `vib history` — 체크포인트 이력 보기

---

# 라이선스

MIT