# cltree - 개발 계획서
## 📋 개요
| 프로젝트명 | cltree |
| 목표 | Claude Code CLI 옆에 파일 트리 UI를 보여주는 TUI 앱 |
| 언어 | Rust |
| 프레임워크 | ratatui + crossterm |
| 라이선스 | MIT |
---
## 🎯 Phase 1: 프로젝트 초기화 (Day 1)
### 1.1 프로젝트 생성
```bash
cargo new cltree
cd cltree
```
### 1.2 Cargo.toml 의존성 추가
```toml
[dependencies]
ratatui = "0.29"
crossterm = "0.28"
tokio = { version = "1.42", features = ["full"] }
portable-pty = "0.8"
notify = "7.0"
ignore = "0.4"
walkdir = "2.5"
anyhow = "1.0"
thiserror = "2.0"
dirs = "5.0"
clap = { version = "4.5", features = ["derive"] }
unicode-width = "0.2"
```
### 1.3 디렉토리 구조 생성
```bash
mkdir -p src/ui src/tree
touch src/app.rs src/event.rs src/terminal.rs
touch src/ui/mod.rs src/ui/file_tree_widget.rs src/ui/terminal_widget.rs src/ui/help_popup.rs
touch src/tree/mod.rs src/tree/file_node.rs
```
### 1.4 완료 기준
- [ ] `cargo build` 성공
- [ ] 기본 main.rs에서 "Hello TUI" 출력
---
## 🎯 Phase 2: 기본 TUI 프레임워크 (Day 1-2)
### 2.1 main.rs - 터미널 초기화
```
태스크:
- [ ] crossterm으로 raw mode 진입
- [ ] alternate screen 활성화
- [ ] ratatui Terminal 생성
- [ ] 종료 시 터미널 복원
```
### 2.2 event.rs - 이벤트 핸들러
```
태스크:
- [ ] Event enum 정의 (Tick, Key, Mouse, Resize)
- [ ] tokio mpsc 채널로 이벤트 전송
- [ ] 250ms tick rate 구현
- [ ] crossterm 이벤트 폴링
```
### 2.3 app.rs - 앱 상태
```
태스크:
- [ ] App struct 정의
- [ ] FocusedPane enum (Tree, Terminal)
- [ ] InputMode enum (Normal, Search)
- [ ] handle_key() 구현
- [ ] handle_mouse() 구현
```
### 2.4 완료 기준
- [ ] 빈 화면에 두 개의 패널 (왼쪽/오른쪽) 표시
- [ ] Tab으로 포커스 전환
- [ ] Ctrl+Q로 종료
---
## 🎯 Phase 3: 파일 트리 구현 (Day 2-3)
### 3.1 tree/file_node.rs - 파일 노드
```
태스크:
- [ ] FileNode struct (path, name, depth, is_dir)
- [ ] icon() 메서드 - 파일 확장자별 이모지
- [ ] tree_prefix() - 트리 선 그리기 (├── └──)
```
### 3.2 tree/mod.rs - 파일 트리 로직
```
태스크:
- [ ] FileTree struct
- [ ] new() - ignore crate로 디렉토리 스캔
- [ ] rebuild_visible_nodes() - 확장된 노드만 표시
- [ ] 네비게이션: select_next/prev, page_up/down
- [ ] toggle_expand() - 디렉토리 확장/축소
- [ ] toggle_hidden() - 숨김 파일 토글
- [ ] search() - 파일명 검색
- [ ] refresh() - 트리 새로고침
```
### 3.3 ui/file_tree_widget.rs - 트리 렌더링
```
태스크:
- [ ] StatefulWidget 구현
- [ ] 선택된 항목 하이라이트
- [ ] 디렉토리/파일 색상 구분
- [ ] 스크롤바 표시
- [ ] 너무 긴 파일명 truncate (...)
```
### 3.4 완료 기준
- [ ] 현재 디렉토리의 파일 트리 표시
- [ ] j/k로 네비게이션
- [ ] Enter/Space로 확장/축소
- [ ] /로 검색
---
## 🎯 Phase 4: PTY 터미널 통합 (Day 3-4)
### 4.1 terminal.rs - PTY 관리
```
태스크:
- [ ] portable-pty로 PTY 생성
- [ ] claude 프로세스 spawn
- [ ] 백그라운드 스레드에서 출력 읽기
- [ ] Arc<Mutex<Vec<u8>>>로 출력 버퍼 공유
- [ ] handle_key() - 키 입력을 PTY로 전송
- [ ] send_interrupt() - Ctrl+C 전송
- [ ] insert_text() - 텍스트 삽입 (@path 등)
- [ ] change_directory() - cd 명령 전송
- [ ] resize() - PTY 크기 조정
```
### 4.2 ui/terminal_widget.rs - 터미널 렌더링
```
태스크:
- [ ] ANSI SGR 파서 구현
- [ ] 기본 색상 (30-37, 40-47)
- [ ] 밝은 색상 (90-97, 100-107)
- [ ] 256 색상 (38;5;N, 48;5;N)
- [ ] RGB (38;2;R;G;B, 48;2;R;G;B)
- [ ] Bold, Italic, Underline
- [ ] 제어 문자 처리 (\r, \t, \n)
- [ ] 스크롤 지원
```
### 4.3 완료 기준
- [ ] Claude Code가 왼쪽 패널에서 실행
- [ ] 키 입력이 Claude Code로 전달
- [ ] 색상 출력 정상 표시
- [ ] Ctrl+C로 인터럽트 전송
---
## 🎯 Phase 5: 패널 통합 및 상호작용 (Day 4-5)
### 5.1 ui/mod.rs - 레이아웃
```
태스크:
- [ ] 수평 분할 (터미널 70% | 트리 30%)
- [ ] 포커스에 따른 테두리 색상 변경
- [ ] 상태바 표시 (검색 모드, 도움말 힌트)
- [ ] help_popup 렌더링
```
### 5.2 app.rs - 상호작용
```
태스크:
- [ ] 파일 선택 시 @path 삽입
- [ ] 디렉토리 선택 시 cd 실행
- [ ] 트리 새로고침 후 터미널 포커스 유지
```
### 5.3 완료 기준
- [ ] Tab으로 패널 전환 부드럽게
- [ ] 파일 Enter → 터미널에 @path 입력
- [ ] 디렉토리 Enter → cd 실행
- [ ] ?로 도움말 표시
---
## 🎯 Phase 6: CLI 및 설정 (Day 5)
### 6.1 clap CLI 파싱
```
태스크:
- [ ] --path: 시작 디렉토리
- [ ] --tree-width: 트리 너비 (10-50%)
- [ ] --show-hidden: 숨김 파일 표시
- [ ] --depth: 최대 트리 깊이
```
### 6.2 완료 기준
- [ ] `cltree --help` 출력
- [ ] 다양한 옵션 조합 테스트
---
## 🎯 Phase 7: 테스트 및 문서화 (Day 6)
### 7.1 테스트
```
태스크:
- [ ] tree/mod.rs 단위 테스트
- [ ] 트리 빌드
- [ ] 네비게이션
- [ ] 검색
- [ ] ANSI 파서 테스트
- [ ] 통합 테스트 (가능하면)
```
### 7.2 문서화
```
태스크:
- [ ] README.md 완성
- [ ] CLAUDE.md 업데이트
- [ ] 코드 주석 추가
- [ ] CHANGELOG.md 작성
```
### 7.3 완료 기준
- [ ] `cargo test` 통과
- [ ] `cargo clippy` 경고 없음
- [ ] `cargo fmt` 적용
---
## 🎯 Phase 8: 릴리스 준비 (Day 7)
### 8.1 최적화
```
태스크:
- [ ] release 프로파일 설정 (LTO, strip)
- [ ] 불필요한 의존성 제거
- [ ] 메모리 사용량 점검
```
### 8.2 배포
```
태스크:
- [ ] GitHub 저장소 생성
- [ ] GitHub Actions CI 설정
- [ ] crates.io 준비 (선택)
- [ ] Homebrew formula (선택)
```
---
## 📊 일정 요약
| Phase | 내용 | 예상 기간 |
|-------|------|----------|
| 1 | 프로젝트 초기화 | 0.5일 |
| 2 | 기본 TUI 프레임워크 | 1일 |
| 3 | 파일 트리 구현 | 1.5일 |
| 4 | PTY 터미널 통합 | 1.5일 |
| 5 | 패널 통합 | 1일 |
| 6 | CLI 및 설정 | 0.5일 |
| 7 | 테스트/문서화 | 1일 |
| 8 | 릴리스 | 0.5일 |
| **총계** | | **약 7일** |
---
## 🚀 Claude Code 작업 가이드
### 시작하기
```bash
# 프로젝트 디렉토리로 이동
cd cltree
# Claude Code 실행
claude
# 첫 번째 명령
> @CLAUDE.md @DEVELOPMENT_PLAN.md 프로젝트 컨텍스트를 파악하고, Phase 1부터 시작하자
```
### 권장 작업 흐름
1. 한 Phase씩 순서대로 진행
2. 각 Phase 완료 후 `cargo build && cargo test` 실행
3. 완료 기준 체크리스트 확인
4. 다음 Phase로 이동
### 유용한 명령어
```bash
# 현재 파일 참조
> @src/app.rs 이 파일 리팩토링해줘
# 컴파일 에러 수정
> !cargo build 2>&1 | head -50
> 이 에러 수정해줘
# 테스트 실행
> !cargo test
# 특정 기능 구현
> Phase 3.2의 search() 함수 구현해줘
```
---
## ⚠️ 주의사항
1. **PTY는 플랫폼 의존적**: macOS/Linux에서 먼저 테스트, Windows는 나중에
2. **ANSI 파싱 복잡**: 모든 이스케이프 시퀀스를 지원할 필요 없음, 주요 색상만
3. **터미널 크기**: 리사이즈 이벤트 처리 중요
4. **메모리**: PTY 출력 버퍼 크기 제한 필요 (무한 증가 방지)