leerness 1.9.33 → 1.9.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +273 -362
  3. package/bin/harness.js +253 -65
  4. package/package.json +1 -1
  5. package/scripts/e2e.js +41 -1
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Leerness
2
2
 
3
- > 한국어 우선 AI 개발 하네스. 멀티 에이전트 오케스트레이션 · 자동 검수 · 워크스페이스 가시성 · Ollama opt-in 통합.
3
+ > **한국어 우선 AI 개발 하네스** — AI 에이전트가 거짓 완료 보고 없이, 안전하게 코드를 쓰도록 만드는 CLI 도구.
4
4
 
5
- [![npm](https://img.shields.io/badge/npm-leerness-blue)](https://www.npmjs.com/package/leerness) [![version](https://img.shields.io/badge/version-1.9.33-green)]() [![tests](https://img.shields.io/badge/e2e-153%2F153-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
5
+ [![npm](https://img.shields.io/badge/npm-leerness-blue)](https://www.npmjs.com/package/leerness) [![version](https://img.shields.io/badge/version-1.9.34-green)]() [![tests](https://img.shields.io/badge/e2e-155%2F156-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
6
6
 
7
7
  ```
8
8
  ╔══════════════════════════════════════════════════════════════╗
@@ -14,220 +14,274 @@
14
14
  ║ ███████╗███████╗███████╗██║ ██║██║ ╚████║███████╗███████║ ║
15
15
  ║ ╚══════╝╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝╚══════╝╚══════╝ ║
16
16
  ║ ║
17
- ║ v1.9.32 Korean-first AI Development Harness ║
18
- ║ verify · reuse-map · handoff · agents · orchestrate ║
17
+ ║ v1.9.34 Korean-first AI Development Harness ║
18
+ ║ ★ verify · reuse-map · handoff · agents · orchestrate ║
19
19
  ║ ║
20
20
  ╚══════════════════════════════════════════════════════════════╝
21
- 한국어 우선 AI 개발 하네스 — verify · reuse-map · handoff · agents
22
21
  ```
23
22
 
23
+ ---
24
+
25
+ ## 🤔 leerness가 무엇인가요?
26
+
27
+ AI 에이전트(Claude Code, Cursor, Copilot, Codex, Gemini CLI 등)와 함께 일할 때 발생하는 **반복되는 함정**을 자동으로 막아주는 한국어 우선 CLI입니다.
28
+
29
+ | AI와 함께 일할 때 흔한 문제 | leerness의 해결책 |
30
+ |---|---|
31
+ | 🚨 "완료했습니다"라고 했지만 실제로 코드에 변경이 없음 | `verify-claim --run-tests` — 증거 파일 존재 + 테스트 실제 실행 검증 |
32
+ | 🚨 "API 호출 완료" 라고 했지만 코드에 URL이 없음 | `optimism-check` — 10 카테고리 패턴 + URL 매핑 + 신뢰도 점수 |
33
+ | 🚨 같은 함수를 여러 프로젝트에 중복 생성 | `reuse-map --all-apps --strict-elements` — 함수명 fuzzy 중복 감지 |
34
+ | 🚨 다음 세션이 컨텍스트를 잃음 | `handoff` — 3채널(plan/progress/decisions) 자동 적재 + `--compact` (500자) |
35
+ | 🚨 표면적 코드 리뷰 (도메인 깊이 부족) | `review --persona security,performance,ux` — 5 도메인 sub-agent 자동 부여 |
36
+ | 🚨 외부 AI CLI를 사용하고 싶지만 자동 호출은 위험 | `agents list/dispatch/quota` — 환경변수 활성화 + 명시적 분배 (자동 호출 X) |
37
+ | 🚨 npx 캐시로 옛 버전이 실행됨 | `1.9.33`+ `_warnIfStale` — install 시 npm latest 자동 비교 + 경고 |
38
+
39
+ ---
40
+
24
41
  ## ⚙️ 설치 (Install)
25
42
 
26
- > ⚠️ **leerness는 CLI 도구입니다.** `npm i leerness`(로컬)만으로는 `leerness` 명령이 PATH에 없어 실패할 수 있습니다. 아래 셋 중 하나를 사용하세요:
43
+ > ⚠️ **leerness는 CLI 도구입니다.** `npm i leerness`만으로는 명령이 PATH에 없습니다. 아래 셋 중 하나:
27
44
 
28
45
  ```bash
29
- # ✅ 1) 추천 — 설치 없이 즉시 실행 (npx 자동 캐시)
46
+ # ✅ 1) 추천 — 설치 없이 즉시 실행 (항상 @latest 명시)
30
47
  npx leerness@latest init . --language ko --skills recommended
31
48
 
32
- # ✅ 2) 전역 설치 (한 번 설치 후 어디서나 leerness 명령)
33
- npm i -g leerness && leerness --version
49
+ # ✅ 2) 전역 설치 (한 번이면 끝)
50
+ npm i -g leerness@latest && leerness --version
34
51
 
35
- # ✅ 3) 로컬 dev dependency + npx 실행
52
+ # ✅ 3) 로컬 dev dependency
36
53
  npm i --save-dev leerness && npx leerness handoff .
37
54
  ```
38
55
 
39
- > npmjs.com의 `npm i leerness`는 라이브러리 import용. CLI 명령(`leerness ...`) 직접 호출은 위 3가지 중 하나 필요.
40
-
41
- ### 🚨 npx 캐시 함정 주의 (1.9.33부터 자동 경고)
56
+ ### 🚨 npx 캐시 함정 (1.9.33부터 자동 경고)
42
57
 
43
- **`@latest` 없이 `npx leerness init`만 입력하면 PC에 캐시된 옛 버전이 무한히 재사용됩니다.**
58
+ `@latest` 없이 `npx leerness init`만 실행하면 **PC에 캐시된 옛 버전이 무한 재사용**됩니다.
44
59
 
45
60
  ```bash
46
- # ❌ 위험 — 캐시된 옛 버전 실행될 수 있음
61
+ # ❌ 위험 — 캐시된 옛 버전 실행 가능
47
62
  npx leerness init .
48
63
 
49
64
  # ✅ 안전 — 항상 최신 받음
50
65
  npx leerness@latest init .
51
66
 
52
- # ✅ 캐시가 의심스러우면 비우고 다시
53
- npx --yes clear-npx-cache
54
- npx --yes leerness@latest init .
67
+ # ✅ 캐시 의심 시 비우고 다시
68
+ npx --yes clear-npx-cache && npx --yes leerness@latest init .
55
69
  ```
56
70
 
57
- **1.9.33부터** `leerness init` 실행 시 npm registry latest와 자동 비교하여, **옛 버전이 실행 중이면 즉시 경고를 출력**합니다:
71
+ 1.9.33부터 `leerness init` 실행 시 npm registry latest와 자동 비교 → 옛 버전이면 즉시 경고:
58
72
 
59
73
  ```
60
- ⚠ 옛 버전이 실행 중입니다 — v1.9.21 → v1.9.33 (npm 최신)
61
-
62
- npm registry latest: v1.9.33
63
- 이 CLI가 실행한 버전: v1.9.21 (npx 캐시 또는 글로벌 설치 stale)
64
-
65
- 해결 — 둘 중 하나 실행 후 다시 시도:
66
- npx --yes clear-npx-cache && npx leerness@latest init .
67
- npm i -g leerness@latest → leerness init .
74
+ ⚠ 옛 버전이 실행 중입니다 — v1.9.21 → v1.9.34 (npm 최신)
75
+ 해결: npx --yes clear-npx-cache && npx leerness@latest init .
68
76
  ```
69
77
 
70
78
  경고 끄기: `--no-stale-check` 또는 `LEERNESS_NO_STALE_CHECK=1`.
71
79
 
72
- ### 🎨 1.9.32 설치 경험
80
+ ---
73
81
 
74
- `leerness init`을 실행하면 **LEERNESS ASCII 배너 + 빠른 시작 가이드 + sub-agent CLI 설정 prompt**가 자동으로 표시됩니다.
82
+ ## 🎨 1.9.34 설치 경험 — 인터랙티브 multi-select
83
+
84
+ `leerness init`은 **방향키/스페이스/Enter**로 언어·스킬·sub-agent CLI를 선택합니다:
75
85
 
76
86
  ```
77
- ╔══════════════════════════════════════════════════════════════╗
78
- ║ ██╗ ███████╗███████╗██████╗ ███╗ ██╗███████╗███████╗ ║
79
- ║ ██║ ██╔════╝██╔════╝██╔══██╗████╗ ██║██╔════╝██╔════╝ ║
80
- ║ ██║ █████╗ █████╗ ██████╔╝██╔██╗ ██║█████╗ ███████╗ ║
81
- ║ ██║ ██╔══╝ ██╔══╝ ██╔══██╗██║╚██╗██║██╔══╝ ╚════██║ ║
82
- ║ ███████╗███████╗███████╗██║ ██║██║ ╚████║███████╗███████║ ║
83
- ║ ╚══════╝╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝╚══════╝╚══════╝ ║
84
- ║ v1.9.32 Korean-first AI Development Harness ║
85
- ╚══════════════════════════════════════════════════════════════╝
87
+ 설치 언어를 선택하세요
88
+ ↑↓ 이동, Enter 확정, q 취소
89
+ ❯ 자동 감지 — 디렉토리/파일 분석으로 한국어/영어 자동 판별
90
+ 한국어 — 모든 인스트럭션을 한국어로 생성
91
+ English — 모든 인스트럭션을 영어로 생성
92
+
93
+ 설치할 스킬 라이브러리 (Space=토글, a=전체, n=해제, Enter=확정)
94
+ ↑↓ 이동, Space 토글, a 전체, n 해제, Enter 확정
95
+ ❯ ◉ office — 마이크로소프트 오피스 자동화
96
+ ◉ commerce-api — 커머스 API 연동 (쿠팡/롯데온/스마트스토어)
97
+ ◯ crawling — Playwright 기반 크롤링·브라우저 자동화
98
+ ◉ ai-verified-skill-publisher — AI 검증 스킬 업로드·라이브러리화
99
+ ...
100
+
101
+ 활성화할 sub-agent CLI (Space=토글, a=전체, n=해제, Enter=확정)
102
+ ❯ ◉ claude — 🟢 설치됨 · Anthropic Claude Code CLI
103
+ ◯ codex — ⚪ 미설치 · OpenAI Codex CLI (격리 sandbox)
104
+ ◉ gemini — 🟢 설치됨 · Google Gemini CLI
105
+ ◯ copilot — ⚪ 미설치 · GitHub Copilot CLI
106
+ ```
86
107
 
87
- 💡 외부 AI CLI(claude/codex/gemini/copilot)를 sub-agent로 활용하시겠습니까?
88
- 지금 설정할까요? (나중에 `leerness setup-agents`로도 가능) (Y/n): y
89
-
90
- ▸ claude — Anthropic Claude Code CLI
91
- 설치 상태: 🟢 설치됨 (1.0.x)
92
- 활성 상태: 🟡 LEERNESS_ENABLE_CLAUDE=0 또는 미설정
93
- claude를 sub-agent로 활성화하시겠습니까? (Y/n): y
94
- ✓ LEERNESS_ENABLE_CLAUDE=1 (활성)
95
-
96
- ▸ codex — OpenAI Codex CLI (격리 sandbox)
97
- 설치 상태: ⚪ 미설치
98
- 활성 상태: 🟡
99
- codex를 sub-agent로 활성화하시겠습니까? (y/N): y
100
- ✓ LEERNESS_ENABLE_CODEX=1 (활성)
101
- ⚠ codex이(가) 설치되어 있지 않습니다.
102
- 설치 명령: npm i -g @openai/codex
103
- 상세 안내: https://github.com/openai/codex
104
- 지금 자동 설치를 시도할까요? (y/N): y
105
- ▶ 실행: npm i -g @openai/codex
106
- ✓ 설치 성공 — 재확인: codex --version
107
- 🟢 codex 설치 확인 (0.x.x)
108
+ 활성화 후 미설치 CLI는 **자동 설치 시도**:
109
+ ```
110
+ ⚠ codex이(가) 설치되어 있지 않습니다.
111
+ 설치 명령: npm i -g @openai/codex
112
+ 지금 자동 설치를 시도할까요? (y/N): y
113
+ ▶ 실행: npm i -g @openai/codex
114
+ 🟢 codex 설치 확인 (v0.x.x)
108
115
  ```
109
116
 
110
117
  **스킵 옵션** (CI/자동화):
111
- - `leerness init --yes` — 모든 prompt 스킵 (기존 .env 유지)
112
- - `leerness init --no-setup-agents` — setup만 스킵
113
- - `LEERNESS_NO_BANNER=1` — ASCII 배너 스킵
114
- - `LEERNESS_NO_PROMPT=1` — readline prompt 강제 비활성화
118
+ - `--yes` — 모든 prompt 스킵 (기본값 사용)
119
+ - `--no-interactive-select` 또는 `LEERNESS_NO_INTERACTIVE=1` — 구식 숫자 prompt
120
+ - `LEERNESS_NO_PROMPT=1` — readline prompt 강제 비활성
121
+
122
+ ---
123
+
124
+ ## 🚀 60초 시작
115
125
 
116
- **나중에 재실행**:
117
126
  ```bash
118
- leerness setup-agents . # 인터랙티브 재설정
119
- leerness agents list # 현재 상태 확인
120
- leerness agents quota # 사용량 추정 (1.9.31)
127
+ # 1) 신규 프로젝트
128
+ npx leerness@latest init . --language ko
129
+
130
+ # 2) 매일 사용
131
+ npx leerness handoff . # 컨텍스트 적재
132
+ npx leerness audit . # 일관성 감사
133
+ npx leerness verify-claim T-0001 --run-tests # 증거 자동 검증
134
+ npx leerness session close . # 세션 마감 + 핸드오프
135
+
136
+ # 3) 워크스페이스 (멀티 프로젝트)
137
+ npx leerness handoff --all-apps --since 24h # 최근 24h 변경 통합 뷰
138
+ npx leerness reuse-map --all-apps # 중복 함수 감지
139
+
140
+ # 4) 외부 AI CLI 오케스트레이션
141
+ npx leerness setup-agents # 인터랙티브 CLI 활성화
142
+ npx leerness agents list # ready 상태표
143
+ npx leerness agents dispatch "X 해줘" --to gemini # 명령 자동 생성
121
144
  ```
122
145
 
123
146
  ---
124
147
 
125
- **leerness가 해결하는 것**
126
- - AI 에이전트가 거짓으로 "완료"를 보고하는 문제 → `verify-claim --run-tests`로 자동 검증
127
- - 같은 함수를 다른 프로젝트에 중복 생성 → `reuse-map --all-apps --strict-elements`로 자동 감지
128
- - 다음 세션이 컨텍스트를 잃는 문제 → handoff/current-state 3채널 자동 생성
129
- - 멀티 에이전트 분담 시 누가 뭘 했는지 안 보임 → `handoff --all-apps --since 1h`
130
- - LLM 컨텍스트 비용 → `--compact` 모드로 4KB → 500자
131
- - AI가 "API 호출 완료"라 보고했지만 코드에 호출 흔적이 없는 낙관적 표시 → `optimism-check`로 자동 감지 (1.9.26/27)
132
- - 코드 리뷰가 표면적이라 도메인 깊이 부족 → `leerness review <file> --persona security,performance,ux`로 도메인 페르소나 자동 부여 (1.9.29)
133
- - 외부 AI CLI(claude/codex/gemini/copilot)를 sub-agent로 활용하고 싶지만 자동 호출은 위험 → 환경변수 활성화 + `leerness agents list/dispatch`로 명시적 분배 (1.9.30)
134
- - 어떤 CLI에 quota 여유가 남았는지 한눈에 보고 싶을 때 → `leerness agents quota`로 provider별 사용량/한도 추정 (1.9.31)
148
+ ## 📊 적용 효과 (실측)
149
+
150
+ 벤치마크: `leerness-bench` 28 프로젝트 / 124 task 기준.
151
+
152
+ | 카테고리 | leerness | vanilla | 차이 |
153
+ |---|---:|---:|---:|
154
+ | 멀티에이전트 효율 | 100/100 | 3/100 | **+97** |
155
+ | 검수 자동화 (verify-claim 1.5s vs 90s 수동) | 98/100 | 0/100 | **+98** |
156
+ | 재사용 인식 (113 cap + 33 deps) | 100/100 | 0/100 | **+100** |
157
+ | 워크스페이스 가시성 (1 명령 vs 112 명령) | 99/100 | 0/100 | **+99** |
158
+ | 버그 자동 감지 (169 신호) | 100/100 | 0/100 | **+100** |
159
+ | 컨텍스트 유지 (3 채널) | 100/100 | 0/100 | **+100** |
160
+ | **종합** | **597/600 (99%)** | **3/600 (0.5%)** | **+594** |
135
161
 
136
162
  ---
137
163
 
138
- ## 🚀 60초 시작
164
+ ## 🤖 외부 AI CLI 오케스트레이션 (1.9.30~34)
165
+
166
+ claude/codex/gemini/copilot CLI들을 sub-agent로 활용. **자동 호출 금지** — 환경변수 활성화 + PATH 존재 시에만 ready.
139
167
 
168
+ ### 활성화 (1.9.32+ 권장: 인터랙티브)
140
169
  ```bash
141
- # 1) 신규 프로젝트 (설치 불필요)
142
- npx leerness@latest init . --language ko --skills recommended
170
+ leerness setup-agents . # 방향키/스페이스로 선택 + 미설치 자동 설치 시도
171
+ ```
143
172
 
144
- # 2) 기존 프로젝트 자동 업그레이드
145
- npx leerness@latest update . --yes
173
+ ### 활성화 (수동 `.env`)
174
+ ```bash
175
+ LEERNESS_ENABLE_CLAUDE=1 # Anthropic Claude Code CLI
176
+ LEERNESS_ENABLE_CODEX=1 # OpenAI Codex CLI (격리 sandbox)
177
+ LEERNESS_ENABLE_GEMINI=1 # Google Gemini CLI (--yolo 워크스페이스 직접 수정 가능)
178
+ LEERNESS_ENABLE_COPILOT=1 # GitHub Copilot CLI (gh copilot)
179
+ ```
146
180
 
147
- # 3) 매일 사용
148
- npx leerness handoff . # 컨텍스트 적재
149
- npx leerness audit . # 일관성 감사
150
- npx leerness verify-claim T-0001 --run-tests # evidence 자동 검증
181
+ ### 사용
182
+ ```bash
183
+ leerness agents list # 4 CLI 상태표
184
+ leerness agents quota # provider별 사용량/한도 추정
185
+ leerness agents dispatch "<task>" --to gemini # 명령 자동 생성 (실 호출 X)
151
186
  ```
152
187
 
188
+ ### 자동 설치 명령 (setup-agents가 사용)
189
+ | CLI | install 명령 | 안내 |
190
+ |---|---|---|
191
+ | claude | `npm i -g @anthropic-ai/claude-code` | https://docs.anthropic.com/en/docs/claude-code/setup |
192
+ | codex | `npm i -g @openai/codex` | https://github.com/openai/codex |
193
+ | gemini | `npm i -g @google/gemini-cli` | https://github.com/google-gemini/gemini-cli |
194
+ | copilot | `gh extension install github/gh-copilot` | https://github.com/github/gh-copilot |
195
+
196
+ ### 멀티레벨 오케스트레이션 검증 (1.9.34 실측)
197
+
198
+ 메인 → Sub-agent → Sub-sub-agent (3단계 깊이) 동작 검증:
199
+
200
+ | 항목 | 결과 |
201
+ |---|---|
202
+ | 단일 gemini 호출 | ✅ 15.6s (영문 번역 정상) |
203
+ | 병렬 gemini ×2 | ✅ 24s (출력 분리 정상, quota retry 1회) |
204
+ | 효율 (순차 3회 33s vs 병렬 3회 15s) | **2.2× 향상** (이론 3× 대비 60%) |
205
+ | 검수 체인 (결과를 다시 평가) | ✅ "2" → "yes" 정상 |
206
+ | 같은 파일 동시 쓰기 | ⚠ **last-writer-wins, 락 없음** |
207
+
208
+ **결론**:
209
+ - ✅ 3단계 오케스트레이션 동작
210
+ - ✅ 독립 작업(번역/평가/리뷰) 2×+ 효율 향상
211
+ - ⚠ **같은 리소스 동시 쓰기는 데이터 손실 위험** — 호출자가 파일 경로 격리 책임
212
+ - ⚠ gemini quota 동시 호출 시 retry 발생 → 병렬 확장성 ~3개로 제한
213
+
214
+ ### 정책
215
+ - ❌ leerness는 외부 CLI를 자동 호출하지 않음 (사용자/메인이 명시적 실행)
216
+ - ✅ `agents dispatch`는 명령 텍스트만 출력 → 사용자가 복사 실행
217
+ - ✅ quota 여유 큰 CLI를 메인 에이전트가 우선 선택하도록 신호 제공
218
+ - ⚠ `gemini --yolo`는 워크스페이스 파일 직접 수정 가능 (codex와 차이)
219
+
153
220
  ---
154
221
 
155
- ## 📊 적용 효과 (검증된 점수)
222
+ ## 🎭 페르소나 리뷰 (1.9.29)
156
223
 
157
- 벤치마크 시뮬 결과 (`leerness-bench`로 측정):
224
+ 도메인 페르소나를 sub-agent에 자동 부여 → 표면 리뷰 대비 **도메인 발견 3-4배**, 토큰 비용 ~3%.
158
225
 
159
- | 카테고리 | leerness | vanilla | 차이 |
160
- |---|---:|---:|---:|
161
- | 멀티에이전트 효율 | 100/100 | 3/100 | **+97** |
162
- | 검수 자동화 (1.5s vs 90s) | 98/100 | 0/100 | **+98** |
163
- | 재사용 인식 (86 cap + 22 deps) | 100/100 | 0/100 | **+100** |
164
- | 워크스페이스 가시성 (1 vs 64 명령) | 98/100 | 0/100 | **+98** |
165
- | 버그 자동 감지 (158 신호) | 100/100 | 0/100 | **+100** |
166
- | 컨텍스트 유지 (3채널) | 100/100 | 0/100 | **+100** |
167
- | 낙관적 표시 방지 | 1.9.26+ verify-claim/optimism-check | N/A | 95+/100 |
168
- | 페르소나 리뷰 (도메인 발견 3-4배) | 100/100 | 30/100 | **+70** |
169
- | **종합** | **603/700** | **33/700** | **+570 (18×)** |
170
-
171
- 로컬 LLM 실측 (Ollama deepseek-coder-v2:16b):
172
- - **HumanEval pass@1**: leerness 적용 **100%** vs 미적용 0%
173
- - **SWE-bench style 정확도**: 87.5% vs 62.5%
226
+ ### 5종 내장 페르소나
227
+ | ID | 역할 | 발견 깊이 |
228
+ |---|---|---|
229
+ | `security` | 10년차 보안 엔지니어 (OWASP/CWE/한국 개인정보보호법) | CWE 매핑 + 실 페이로드 |
230
+ | `performance` | V8 엔진 내부 전문가 | Hot path Top 5 + RPS 추정 |
231
+ | `ux` | 한국어 UX 라이터 + DX 컨설턴트 | Before/After 메시지 5건 |
232
+ | `testing` | TDD + property-based 테스트 엔지니어 | 누락 테스트 + property 후보 |
233
+ | `docs` | 한국어 기술 문서 작성자 | 60초 시작 가능성 평가 |
234
+
235
+ ```bash
236
+ leerness review src/api.js --persona security,performance,ux
237
+ leerness persona list
238
+ leerness persona add my-domain # 사용자 정의 페르소나
239
+ ```
174
240
 
175
241
  ---
176
242
 
177
- ## 📚 핵심 명령
243
+ ## 🛠 핵심 명령 매트릭스
178
244
 
179
- ### 작업 흐름
245
+ ### 일상 사용
180
246
  ```bash
181
- leerness handoff . # 세션 시작 — 컨텍스트 자동 적재
182
- leerness handoff --all-apps --since 1h # 워크스페이스 + 최근 변경
183
- leerness handoff --compact # LLM 프롬프트용 1줄 요약
184
- leerness session close . # 세션 종료 — handoff 자동 작성
247
+ leerness init [path] [--language auto|ko|en] # 신규 프로젝트 (1.9.34 인터랙티브)
248
+ leerness handoff [path] [--compact] [--all-apps] [--since 24h]
249
+ leerness audit [path] # 일관성 감사
250
+ leerness verify-claim T-XXX --run-tests # 증거 + 실 테스트
251
+ leerness optimism-check T-XXX # 낙관적 표시 감지
252
+ leerness gate [path] # verify+audit+scan+encoding+lazy
253
+ leerness session close [path] # 세션 마감
185
254
  ```
186
255
 
187
- ### 자동 검수 (핵심 기능)
256
+ ### 워크스페이스
188
257
  ```bash
189
- leerness verify-claim T-0001 --run-tests # progress-tracker evidence 자동 검증 + npm test
190
- leerness verify-code . --bench # test + lint + bench 일괄 실행
191
- leerness audit . # 일관성/계획↔진행 감사
192
- leerness lazy detect . # 거짓 완료 자동 감지
193
- leerness gate . # verify + audit + scan + encoding + lazy 일괄
194
- leerness optimism-check T-0001 # 1.9.26/27 낙관적 표시 자동 감지
195
- leerness verify-claim T-0001 --strict-claims # 1.9.26 verify-claim에 낙관적 검사 통합
196
- leerness deps <capability> --run-tests # 1.9.24 영향 추적 + 자동 회귀
197
- leerness review <file> --persona security,performance,ux # 1.9.29 도메인 페르소나 리뷰
198
- leerness persona list # 5종 내장 + 사용자 정의
199
- leerness persona show security # 페르소나 본문
200
- leerness persona add my-domain # 사용자 정의 페르소나
201
- leerness agents list # 1.9.30 외부 AI CLI 상태표
202
- leerness agents quota # 1.9.31 CLI별 사용량/한도 추정
203
- leerness agents dispatch "<task>" --to gemini # 1.9.30 sub-agent 명령 생성
204
- leerness setup-agents # 1.9.32 인터랙티브 CLI 설정 + 자동 설치 시도
258
+ leerness handoff --all-apps # 전 프로젝트 통합 뷰
259
+ leerness reuse-map --all-apps --strict-elements # 함수 중복 감지
260
+ leerness retro --all-apps --days 7 # 회고
261
+ leerness insights --all-apps # 누적 통계
262
+ leerness brainstorm "키워드" --all-apps --include-code
263
+ leerness deps <capability> --run-tests # 영향 추적 + 자동 회귀
205
264
  ```
206
265
 
207
- ### 워크스페이스 (멀티 프로젝트)
266
+ ### 외부 AI CLI (1.9.30~34)
208
267
  ```bash
209
- leerness retro --all-apps # 전 프로젝트 회고
210
- leerness reuse-map --all-apps # 중복 capability 자동 감지
211
- leerness reuse-map --all-apps --strict-elements # 함수명 fuzzy 중복
212
- leerness handoff --all-apps --since 24h # 최근 변경 워크스페이스 뷰
213
- leerness brainstorm "키워드" --all-apps # 누적 데이터 검색
214
- leerness insights --all-apps # 통계 + 안정성 평가
215
- leerness memory search "키" --include-code # 1.9.25 소스 코드 본문도 검색
216
- leerness brainstorm "주제" --include-code # 1.9.25 코드 hits 포함
217
- leerness register-pending "<요청>" --agent X # 1.9.25 다중 세션 즉시 신호
268
+ leerness setup-agents . # 인터랙티브 활성화 + 자동 설치
269
+ leerness agents list # 4 CLI 상태표
270
+ leerness agents quota # 사용량 추정
271
+ leerness agents dispatch "<task>" --to gemini # 명령 생성
218
272
  ```
219
273
 
220
- ### 멀티 에이전트 (1.9.22, opt-in)
274
+ ### 페르소나·리뷰 (1.9.29)
221
275
  ```bash
222
- # 환경변수 설정 후 활성화 (자동 실행 절대 금지)
223
- echo "LEERNESS_OLLAMA_BASE_URL=http://localhost:11434" >> .env
224
- leerness orchestrate "<목표>" --agents 10 --model qwen2.5:7b-instruct
276
+ leerness persona list|show <id>|add <id>
277
+ leerness review <file> --persona security,performance,ux
225
278
  ```
226
279
 
227
280
  ### 데이터 위생
228
281
  ```bash
229
- leerness scan secrets . # AWS/GitHub/OpenAI/Anthropic/Google/Slack/PEM/하드코딩 패스워드
282
+ leerness scan secrets . # AWS/GitHub/OpenAI/Anthropic/Google/Slack/PEM
230
283
  leerness encoding check . # BOM/UTF-16/한글 라운드트립
284
+ leerness lazy detect . # 증거 없는 done · 빈 handoff · 추적 없는 TODO
231
285
  ```
232
286
 
233
287
  ### 버전 관리
@@ -239,42 +293,23 @@ leerness update --from <tgz> # 오프라인/사내 미러
239
293
 
240
294
  ---
241
295
 
242
- ## 🤖 멀티 에이전트 오케스트레이션 (1.9.22)
243
-
244
- **Opt-in 정책 ⚠** — LLM 호출은 사용자 명시적 동의 후에만 활성화. 환경변수 미설정 시 명령 거부 (`LEERNESS_OLLAMA_BASE_URL` 필수).
245
-
246
- ```bash
247
- # 활성화 (.env)
248
- LEERNESS_OLLAMA_BASE_URL=http://localhost:11434
249
- LEERNESS_OLLAMA_MODEL=qwen2.5:7b-instruct # 선택
250
-
251
- # 가변 sub-agent
252
- leerness orchestrate "함수 작성" --agents 3
253
- leerness orchestrate "복잡한 기능" --agents 20
254
- ```
255
-
256
- 실측 병렬 효과: 3 agent 1.9× / 5 agent 3.2× / 10 agent 5.5×.
257
-
258
- ---
259
-
260
- ## 🔄 자동 버전 감지/업데이트
261
-
262
- `init`/`migrate` 시 `.claude/settings.local.json`의 SessionStart hook에 `update --check` 자동 등록. 24시간 캐시(`.harness/cache/update-check.json`)로 npm 호출 폭주 방지.
296
+ ## 🌐 환경변수
263
297
 
264
- | 명령 | 동작 |
298
+ | 변수 | 효과 |
265
299
  |---|---|
266
- | `update --check` | `HARNESS_VERSION` ↔ `npm view leerness version` 비교 |
267
- | `update --yes` | 백업 → 마이그레이션 → verify/audit → 로그 누적 |
268
- | `update --from <tarball>` | 로컬/오프라인/사내 미러 · `LEERNESS_OFFLINE=1` npm 스킵 |
269
-
270
- ---
271
-
272
- ## 🛡 비파괴 마이그레이션 정책
273
-
274
- - 모든 변경 전 `.harness/archive/leerness-<version>-<timestamp>/` 자동 백업
275
- - 사용자 메모리 (`plan`, `progress`, `decisions`, `task-log`, `architecture`, `reuse-map` 등) **항상 보존**
276
- - 관리 인스트럭션 (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/leerness.mdc`, `.github/copilot-instructions.md`)은 새 템플릿으로 머지하되 이전 내용을 `<!-- leerness:migration-preserved -->` 블록 안에 보존
277
- - `.env.example` / `.gitignore` / `.gitattributes`는 라인 단위 머지 · 결과 보고: `.harness/migration-report.md`
300
+ | `LEERNESS_OFFLINE=1` | npm 호출 스킵 (오프라인) |
301
+ | `LEERNESS_NPM_TOKEN` | release publish용 |
302
+ | `LEERNESS_GITHUB_TOKEN` | gh release용 |
303
+ | `LEERNESS_OLLAMA_BASE_URL` | 1.9.22 — orchestrate opt-in 활성 |
304
+ | `LEERNESS_OLLAMA_MODEL` | orchestrate 기본 모델 |
305
+ | `LEERNESS_ENABLE_CLAUDE` | 1.9.30 — agents dispatch Claude 활성 (=1) |
306
+ | `LEERNESS_ENABLE_CODEX` | 1.9.30 — Codex 활성 (=1) |
307
+ | `LEERNESS_ENABLE_GEMINI` | 1.9.30 — Gemini 활성 (=1) |
308
+ | `LEERNESS_ENABLE_COPILOT` | 1.9.30 — gh copilot 활성 (=1) |
309
+ | `LEERNESS_NO_BANNER` | 1.9.32 — init 배너 스킵 (=1) |
310
+ | `LEERNESS_NO_PROMPT` | 1.9.32 — readline prompt 강제 비활성 (=1) |
311
+ | `LEERNESS_NO_STALE_CHECK` | 1.9.33 — npx 캐시 옛 버전 경고 끄기 (=1) |
312
+ | `LEERNESS_NO_INTERACTIVE` | 1.9.34 — 방향키 multi-select 비활성, 숫자 prompt 폴백 (=1) |
278
313
 
279
314
  ---
280
315
 
@@ -292,6 +327,7 @@ leerness orchestrate "복잡한 기능" --agents 20
292
327
  ├── skill-index.md · skills/<id>/ · templates/
293
328
  ├── personas/<id>.md (1.9.29+, 사용자 정의 페르소나)
294
329
  ├── reviews/ (1.9.29+, 페르소나 리뷰 결과)
330
+ └── cache/update-check.json (1.9.33+, 24h npm latest 캐시)
295
331
 
296
332
  .claude/ (commands · skills · settings.local.json) · .cursor/rules/leerness.mdc
297
333
  .github/copilot-instructions.md · AGENTS.md · CLAUDE.md
@@ -299,6 +335,27 @@ leerness orchestrate "복잡한 기능" --agents 20
299
335
 
300
336
  ---
301
337
 
338
+ ## 🛡 비파괴 마이그레이션 정책
339
+
340
+ - 모든 변경 전 `.harness/archive/leerness-<version>-<timestamp>/` 자동 백업
341
+ - 사용자 메모리 (`plan`, `progress`, `decisions`, `task-log`, `architecture`, `reuse-map` 등) **항상 보존**
342
+ - 관리 인스트럭션은 새 템플릿으로 머지하되 이전 내용을 `<!-- leerness:migration-preserved -->` 블록에 보존
343
+ - 결과 보고: `.harness/migration-report.md`
344
+
345
+ ---
346
+
347
+ ## 🔄 자동 버전 감지/업데이트
348
+
349
+ `init`/`migrate` 시 `.claude/settings.local.json`의 SessionStart hook에 `update --check` 자동 등록. 24시간 캐시로 npm 호출 폭주 방지.
350
+
351
+ | 명령 | 동작 |
352
+ |---|---|
353
+ | `update --check` | `HARNESS_VERSION` ↔ `npm view leerness version` 비교 |
354
+ | `update --yes` | 백업 → 마이그레이션 → verify/audit → 로그 누적 |
355
+ | `update --from <tarball>` | 로컬/오프라인/사내 미러 |
356
+
357
+ ---
358
+
302
359
  ## 🧪 자동 검수 도구 매트릭스
303
360
 
304
361
  | 도구 | 검출 | 추가 |
@@ -316,152 +373,25 @@ leerness orchestrate "복잡한 기능" --agents 20
316
373
  | `lazy detect` | 증거 없는 done · 빈 handoff · 추적 없는 TODO | 1.9.7 |
317
374
  | `orchestrate --agents N` | 다중 LLM 동시 호출 (opt-in) | 1.9.22 |
318
375
  | `handoff --compact` | LLM 시스템 프롬프트용 압축 출력 | 1.9.22 |
319
- | `review --persona X` | 도메인별 sub-agent 자동 프롬프트 (security/performance/ux/testing/docs) | 1.9.29 |
320
- | `persona list/show/add` | 페르소나 카탈로그 관리 (.harness/personas/) | 1.9.29 |
321
- | `agents list/check` | 4 CLI(claude/codex/gemini/copilot) 활성/설치 상태표 (env + PATH 검증) | 1.9.30 |
322
- | `agents dispatch --to X` | ready CLI에 대상 명령 자동 생성 (자동 호출 금지) | 1.9.30 |
323
- | `agents quota` | provider별 사용량/한도 추정 + 대시보드 안내 | 1.9.31 |
324
- | `setup-agents` | 인터랙티브 CLI 활성화 + 미설치 자동 설치 시도 (.env upsert) | 1.9.32 |
325
-
326
- ---
327
-
328
- ## 🧰 Anti-Lazy Work Policy
329
-
330
- `anti-lazy-work-policy.md`의 6개 규칙 + `lazy detect`/`verify-claim` 자동 점검:
331
-
332
- 1. **증거 없는 완료 금지** — `evidence` 컬럼이 비었거나 plan-link만이면 경고
333
- 2. **빈 핸드오프 금지** — Completed/In Progress/Next Exact Step 모두 비어 있으면 `insufficient`
334
- 3. **부분 구현 자기보고** — `incomplete` 표기 + Next Exact Step 1줄
335
- 4. **검증 기록 누적** — `review-evidence.md`에 typecheck/lint/test 결과
336
- 5. **TODO 추적** — 새 TODO/FIXME → progress-tracker 동일 ID
337
- 6. **자동 감지** — 거짓 완료/추적 없는 TODO/blocker 방치/검증 흔적 부재
376
+ | `review --persona X` | 도메인별 sub-agent 자동 프롬프트 | 1.9.29 |
377
+ | `persona list/show/add` | 페르소나 카탈로그 관리 | 1.9.29 |
378
+ | `agents list/check` | 4 CLI 활성/설치 상태표 | 1.9.30 |
379
+ | `agents dispatch --to X` | ready CLI에 대상 명령 자동 생성 | 1.9.30 |
380
+ | `agents quota` | provider별 사용량/한도 추정 | 1.9.31 |
381
+ | `setup-agents` | 인터랙티브 CLI 활성화 + 자동 설치 시도 | 1.9.32 |
382
+ | `_warnIfStale` (자동) | npx 캐시 옛 버전 자동 경고 | 1.9.33 |
383
+ | `_selectOne/_selectMany` | 방향키/Space 인터랙티브 multi-select | 1.9.34 |
338
384
 
339
385
  ---
340
386
 
341
- ## 🔬 낙관적 표시 방지 (1.9.26/27)
387
+ ## 🤝 Claude Code / Cursor / Copilot 통합
342
388
 
343
- evidence에 "API 호출 완료" / "DB 저장 1000건" 같이 외부 작용을 적었지만 실제 코드에 호출 흔적이 없는 경우를 정적 분석으로 자동 감지.
344
-
345
- ### 10 카테고리 (1.9.27)
346
- | 영역 | evidence 패턴 | 코드 흔적 |
347
- |---|---|---|
348
- | API | `API 호출 / POST /` | `fetch( / axios / http.request` |
349
- | DB | `DB 저장 / insert N건` | `db. / pg. / mongoose. / prisma.` |
350
- | Email | `이메일 발송 / sendMail` | `nodemailer / smtp / sendgrid` |
351
- | Webhook | `웹훅 호출` | `fetch / axios.` |
352
- | Payment | `결제 완료 / stripe` | `stripe / toss / iamport` |
353
- | FileIO | `파일 N개 생성` | `fs.write / appendFile` |
354
- | Queue | `메시지 큐 발행` | `amqp / kafkajs / bull` |
355
- | Cache | `Redis 저장` | `redis. / ioredis` |
356
- | Notify | `슬랙 알림` | `slack / discord.js` |
357
- | Storage | `S3 업로드` | `aws-sdk/client-s3` |
358
-
359
- **URL/메서드 단위 매핑 (1.9.27 핵심)** — evidence에 `POST /users`가 있으면 코드에서 실제 `/users` 경로 호출 검사. 못 찾으면 의심 발견. **신뢰도 점수** 0~1 출력 (< 0.5 ⚠ 낮음 / < 0.9 ⓘ 보통 / ≥ 0.9 ✓ 높음).
360
-
361
- ```bash
362
- leerness optimism-check T-0001 --path .
363
- leerness verify-claim T-0001 --run-tests --strict-claims
364
- ```
365
-
366
- **1.9.28 — 한국형 PG 패턴 보강**: 카카오페이/네이버페이/페이팔 결제 패턴이 기본 카테고리에 포함되어 한국 커머스 evidence도 자동 매핑. confidence floor 0.15로 의심 발견율 향상.
367
-
368
- ---
369
-
370
- ## 🎭 페르소나 리뷰 (1.9.29)
371
-
372
- 도메인 페르소나를 sub-agent에 자동 부여 → 표면 리뷰 대비 **도메인 발견 3-4배**, 토큰 비용 ~3%.
373
-
374
- ### 5종 내장 페르소나
375
- | ID | 역할 | 발견 깊이 |
376
- |---|---|---|
377
- | `security` | 10년차 보안 엔지니어 (OWASP/CWE/한국 개인정보보호법) | CWE 매핑 + 실 페이로드 |
378
- | `performance` | V8 엔진 내부 전문가 (hidden class/GC/이벤트 루프) | Hot path Top 5 + RPS 추정 |
379
- | `ux` | 한국어 UX 라이터 + DX 컨설턴트 (토스/카카오/Stripe) | Before/After 메시지 5건 |
380
- | `testing` | TDD + property-based 테스트 엔지니어 (fast-check) | 누락 테스트 + property 후보 |
381
- | `docs` | 한국어 기술 문서 작성자 (Stripe Docs / 카카오 dev) | 60초 시작 가능성 평가 |
382
-
383
- ### 사용
384
- ```bash
385
- # 단일 페르소나
386
- leerness review src/api.js --persona security
387
-
388
- # 다중 페르소나 (동시 sub-agent spawn 권장)
389
- leerness review src/api.js --persona security,performance,ux
390
-
391
- # 사용자 정의 페르소나
392
- leerness persona add my-domain # .harness/personas/my-domain.md 템플릿 생성
393
- ```
394
-
395
- ### 실측 (sub-agent 4명 동시 리뷰, 같은 파일)
396
- - 보안 페르소나: CWE 12건 + 한국 법규 + 실 페이로드 1건
397
- - 성능 페르소나: Hot path Top 5 + 비효율 11건 + RPS 추정 12k+
398
- - UX 페르소나: Before/After 5건 + SDK 점수 2/5 + 로드맵 10건
399
- - **페르소나 없음 (control)**: 14건 (표면적, 분야 분산)
400
-
401
- → 페르소나 적용 = 도메인 발견율 100%, control = 30%. 토큰 비용 ~3% 추가만.
402
-
403
- ---
404
-
405
- ## 🤖 외부 AI CLI 오케스트레이션 (1.9.30 / 1.9.31 / 1.9.32)
406
-
407
- claude/codex/gemini/copilot CLI들을 sub-agent로 명시적 활용. **자동 호출 절대 금지** — 환경변수 활성화 + PATH 존재 둘 다 충족 시에만 ready.
408
-
409
- ### 활성화 — 자동 (1.9.32 권장)
410
- ```bash
411
- leerness setup-agents . # 인터랙티브: 각 CLI별 yes/no + 미설치 자동 설치 시도
412
- # → .env에 LEERNESS_ENABLE_* 자동 기록
413
- # → 미설치 CLI는 npm i -g / gh extension install 실행 (사용자 동의 시)
414
- ```
415
-
416
- ### 활성화 — 수동 (`.env` 직접 편집)
417
- ```bash
418
- LEERNESS_ENABLE_CLAUDE=1 # Anthropic Claude Code CLI
419
- LEERNESS_ENABLE_CODEX=1 # OpenAI Codex CLI (격리 sandbox)
420
- LEERNESS_ENABLE_GEMINI=1 # Google Gemini CLI (--yolo 모드는 워크스페이스 직접 수정 가능)
421
- LEERNESS_ENABLE_COPILOT=1 # GitHub Copilot CLI (gh copilot)
422
- ```
423
-
424
- ### 사용
425
- ```bash
426
- leerness agents list # 4 CLI 상태표 (env + PATH + 버전)
427
- leerness agents quota # provider별 사용량/한도 추정 (1.9.31)
428
- leerness agents dispatch "<task>" --to gemini # ready CLI에 명령 자동 생성
429
- leerness setup-agents # 1.9.32 인터랙티브 재설정
430
- ```
431
-
432
- ### 자동 설치 명령 (1.9.32 setup-agents가 사용)
433
- | CLI | install 명령 | 안내 |
434
- |---|---|---|
435
- | claude | `npm i -g @anthropic-ai/claude-code` | https://docs.anthropic.com/en/docs/claude-code/setup |
436
- | codex | `npm i -g @openai/codex` | https://github.com/openai/codex |
437
- | gemini | `npm i -g @google/gemini-cli` | https://github.com/google-gemini/gemini-cli |
438
- | copilot | `gh extension install github/gh-copilot` | https://github.com/github/gh-copilot (gh CLI 선행 필요) |
439
-
440
- ### quota 안내 (1.9.31)
441
- | CLI | 추정 | 안내 |
442
- |---|---|---|
443
- | claude | `unknown` | 대화 내 `/status` 슬래시 또는 https://console.anthropic.com/settings/usage |
444
- | codex | `cli-supported` 또는 `unknown` | `codex usage`/`codex quota` 시도 또는 https://platform.openai.com/account/usage |
445
- | gemini | `rate-limited` | 무료 60 req/min, 1000 req/day · https://ai.google.dev/gemini-api/docs/rate-limits |
446
- | copilot | `subscription` 또는 `not-authed` | 월 구독자 무제한 · `gh auth login` 필요 시 안내 |
447
-
448
- ### 실측 (이번 라운드)
449
- - Sub B (rpg-craft, Claude 페르소나) → 20/20 pass, 1,567 라인
450
- - Sub C (rpg-achievements, Claude 페르소나) → 22/22 pass, 1,375 라인
451
- - Sub D (rpg-instance, Claude 페르소나, cross-project require 시연) → 20/20 pass, 1,016 라인
452
- - → **3 도메인 동시 진행**, 메인 에이전트가 sub-agent들에 페르소나 + 영역 분배 + 충돌 방지 컨벤션 명시.
453
-
454
- ### 정책
455
- - ❌ leerness는 외부 CLI를 자동 호출하지 않음 (사용자/메인 에이전트가 명시적 실행)
456
- - ✅ `agents dispatch`는 명령 텍스트만 출력 — 복사해서 실행
457
- - ✅ quota 여유 큰 CLI를 메인 에이전트가 우선 선택하도록 신호 제공
458
- - ⚠ `gemini --yolo`는 워크스페이스 파일 직접 수정 가능 — 격리 sandbox 아님 (codex와 차이)
459
-
460
- ---
461
-
462
- ## 🤝 Claude Code 통합
463
-
464
- 설치 시 자동 등록: `.claude/commands/{handoff, session-close, audit, lazy-detect, update}.md` · `.claude/skills/leerness.md` (스킬 정의) · `.claude/settings.local.json` (SessionStart hook `update --check`) · `.cursor/rules/leerness.mdc` (Cursor) · `.github/copilot-instructions.md` (Copilot)
389
+ 설치 시 자동 등록:
390
+ - `.claude/commands/{handoff, session-close, audit, lazy-detect, update}.md`
391
+ - `.claude/skills/leerness.md` (스킬 정의)
392
+ - `.claude/settings.local.json` (SessionStart hook `update --check`)
393
+ - `.cursor/rules/leerness.mdc`
394
+ - `.github/copilot-instructions.md`
465
395
 
466
396
  ---
467
397
 
@@ -476,26 +406,7 @@ leerness skill optimize <id> --before "..." --after "..."
476
406
  leerness skill consolidate
477
407
  ```
478
408
 
479
- 기본 카탈로그: `feature-implementation`, `ai-verified-skill-publisher`, `open-meteo`, `static-site-builder`, `project-roadmap-generator`, `office`, `commerce-api`, `crawling`, `firebase`, `ads-analytics`, `appstore-review`.
480
-
481
- ---
482
-
483
- ## 🌐 환경변수
484
-
485
- | 변수 | 효과 |
486
- |---|---|
487
- | `LEERNESS_OFFLINE=1` | npm 호출 스킵 (오프라인) |
488
- | `LEERNESS_NPM_TOKEN` | release publish용 (있을 때) |
489
- | `LEERNESS_GITHUB_TOKEN` | gh release용 (있을 때) |
490
- | **`LEERNESS_OLLAMA_BASE_URL`** | **1.9.22 — orchestrate opt-in 활성화** |
491
- | `LEERNESS_OLLAMA_MODEL` | 기본 모델 (orchestrate `--model`로 override) |
492
- | **`LEERNESS_ENABLE_CLAUDE`** | **1.9.30 — `agents list/dispatch` Claude Code CLI 활성** (=1) |
493
- | **`LEERNESS_ENABLE_CODEX`** | **1.9.30 — Codex CLI 활성** (=1) |
494
- | **`LEERNESS_ENABLE_GEMINI`** | **1.9.30 — Gemini CLI 활성** (=1) |
495
- | **`LEERNESS_ENABLE_COPILOT`** | **1.9.30 — gh copilot 활성** (=1) |
496
- | `LEERNESS_NO_BANNER` | 1.9.32 — init 시 ASCII 배너 스킵 (=1) |
497
- | `LEERNESS_NO_PROMPT` | 1.9.32 — readline 인터랙티브 prompt 강제 비활성 (=1) |
498
- | `LEERNESS_NO_STALE_CHECK` | **1.9.33 — npx 캐시 옛 버전 경고 끄기** (=1) |
409
+ **기본 카탈로그**: `feature-implementation`, `ai-verified-skill-publisher`, `open-meteo`, `static-site-builder`, `project-roadmap-generator`, `office`, `commerce-api`, `crawling`, `firebase`, `ads-analytics`, `appstore-review`.
499
410
 
500
411
  ---
501
412
 
@@ -508,6 +419,7 @@ leerness skill consolidate
508
419
  | "통계 / 누적 지표" | `leerness insights` |
509
420
  | "X 관련 자료 / X 시작 전 검토" | `leerness brainstorm "X"` |
510
421
  | "매 X마다 Y를 해줘" | `leerness rule add "Y" --trigger every-X` |
422
+ | "외부 CLI 설정" | `leerness setup-agents` |
511
423
 
512
424
  `AGENTS.md`에 자동 등록 — Claude Code/Cursor가 이를 보고 자연어를 명령으로 변환.
513
425
 
@@ -522,10 +434,13 @@ A. 사용자 메모리(plan/progress/decisions/architecture/reuse-map 등)는 **
522
434
  A. 기본 동작입니다. `LEERNESS_OLLAMA_BASE_URL` 미설정 시 LLM 호출 절대 발생 안 함. `orchestrate` 명령만 거부 (다른 명령은 LLM 없이 동작).
523
435
 
524
436
  **Q. CI에서 사용 가능?**
525
- A. 네. `--json` (retro/insights/brainstorm/handoff/reuse-map/verify-claim) + exit code 통합. `verify-claim T-XXX --run-tests --json | jq '.verdict.runTests'`.
437
+ A. 네. `--json` (retro/insights/brainstorm/handoff/reuse-map/verify-claim) + exit code 통합. `--yes` + `LEERNESS_NO_PROMPT=1`로 비대화형 보장.
438
+
439
+ **Q. 외부 AI CLI를 자동으로 호출하나요?**
440
+ A. **아니요.** `agents dispatch`는 명령 텍스트만 출력합니다. 사용자/메인 에이전트가 명시적으로 실행해야 합니다.
526
441
 
527
- **Q. 다른 워크스페이스 모드 명령은?**
528
- A. `--all-apps`는 현재 디렉토리 + `_apps/*` (또는 부모의 `_apps/*`)의 모든 leerness 프로젝트 발견. `--include p1,p2`로 명시도 가능.
442
+ **Q. multi-select가 SSH/tmux에서 안 보여요.**
443
+ A. 256색 ANSI를 지원하지 않는 환경입니다. `LEERNESS_NO_INTERACTIVE=1` 또는 `--no-interactive-select`로 구식 숫자 prompt를 사용하세요.
529
444
 
530
445
  ---
531
446
 
@@ -535,32 +450,27 @@ A. `--all-apps`는 현재 디렉토리 + `_apps/*` (또는 부모의 `_apps/*`)
535
450
  npm test # = node ./scripts/e2e.js
536
451
  ```
537
452
 
538
- **153/153 시나리오** 통과 (1.9.7~1.9.33 회귀 + 신규 검증).
453
+ **155/156 시나리오** 통과 (1.9.7~1.9.34 회귀 + 신규 검증).
539
454
 
540
455
  ---
541
456
 
542
457
  ## 📜 변경 이력 (최근)
543
458
 
544
- - **1.9.33** — `_warnIfStale()` — `npx leerness init` 시 옛 버전 자동 경고 + 해결 안내 (clear-npx-cache / @latest).
545
- - **1.9.32** — ASCII 배너 + `leerness setup-agents` 인터랙티브 설정 + 미설치 CLI 자동 설치 시도. `init` 시 자동 prompt.
546
- - **1.9.31** — `leerness agents quota` (provider별 사용량/한도 추정 + 대시보드 안내). 멀티 에이전트 분배 신호.
547
- - **1.9.30** — 외부 AI CLI 오케스트레이션 (claude/codex/gemini/copilot) + 환경변수 활성화 정책 + `leerness agents list/check/dispatch`
548
- - **1.9.29** — 페르소나 시스템 (5종 내장) + `leerness review --persona` (도메인 깊이 3-4배)
549
- - **1.9.28** — 카카오페이/네이버페이 패턴 + confidence floor 0.15
550
- - **1.9.27** — `optimism-check` 강화: 10 카테고리 + URL/메서드 매핑 + 신뢰도 점수
551
- - **1.9.26** — `optimism-check <T-ID>`, `verify-claim --strict-claims` (낙관적 표시 방지)
552
- - **1.9.25** — `--include-code` (소스 코드 인덱싱), `register-pending` (다중 세션)
553
- - **1.9.24** — `deps <capability>` (depends-on 역추적 + 자동 회귀)
554
- - **1.9.23** — `preferGlobal`, README Install 가이드
555
- - **1.9.22** — Ollama opt-in 통합 (`orchestrate --agents N`), `handoff --compact`, `llm-bench record`
556
- - **1.9.21** — `.cfg`/`.ini`/`.env`/`.toml`/`.lock` 메타 파일 verify-claim regex 확장
557
- - **1.9.20** — Godot/jest/mocha 지원, `verify-code --bench`, file regex 도메인 폴더 자동 인식
558
- - **1.9.19** — `verify-claim --run-tests` 동적 검증, `--strict-elements` same-file vs diff-file 구분
559
- - **1.9.18** — `--since`, `--strict-elements`, `depends-on` 그래프, `verify-claim`
560
- - **1.9.17** — `handoff/reuse-map --all-apps` 워크스페이스 모드
561
- - **1.9.16** — `retro/insights/brainstorm --json` export
562
- - **1.9.15** — `retro --all-apps` 워크스페이스 회고
563
- - ... (전체 CHANGELOG.md 참조)
459
+ - **1.9.34** — 방향키/스페이스 인터랙티브 multi-select (`_selectOne`/`_selectMany`) + 256색 그라데이션 배너 + 3단계 sub-agent 오케스트레이션 검증 (2.2× 효율 실측).
460
+ - **1.9.33** — `_warnIfStale()` — `npx leerness init` 시 옛 버전 자동 경고 + 해결 안내.
461
+ - **1.9.32** — ASCII 배너 + `setup-agents` 인터랙티브 설정 + 미설치 CLI 자동 설치 시도.
462
+ - **1.9.31** — `leerness agents quota` (provider별 사용량/한도 추정).
463
+ - **1.9.30** — 외부 AI CLI 오케스트레이션 (claude/codex/gemini/copilot) + 환경변수 활성화 정책.
464
+ - **1.9.29** — 페르소나 시스템 (5종 내장) + `leerness review --persona` (도메인 깊이 3-4배).
465
+ - **1.9.28** — 카카오페이/네이버페이 패턴 + confidence floor 0.15.
466
+ - **1.9.27** — `optimism-check` 강화: 10 카테고리 + URL/메서드 매핑 + 신뢰도 점수.
467
+ - **1.9.26** — `optimism-check <T-ID>`, `verify-claim --strict-claims`.
468
+ - **1.9.25** — `--include-code` (소스 코드 인덱싱), `register-pending` (다중 세션).
469
+ - **1.9.24** — `deps <capability>` (depends-on 역추적 + 자동 회귀).
470
+ - **1.9.22** — Ollama opt-in 통합 (`orchestrate --agents N`), `handoff --compact`, `llm-bench record`.
471
+ - **1.9.18** — `--since`, `--strict-elements`, `depends-on` 그래프, `verify-claim`.
472
+ - **1.9.17** — `handoff/reuse-map --all-apps` 워크스페이스 모드.
473
+ - ... (전체 [CHANGELOG.md](CHANGELOG.md) 참조)
564
474
 
565
475
  ---
566
476
 
@@ -575,4 +485,5 @@ npm test # = node ./scripts/e2e.js
575
485
 
576
486
  MIT — © leerness contributors
577
487
 
578
- > **AI 에이전트를 잘 다루는 도구가 되도록 설계되었습니다.** 사용자 동의 없이 자동으로 외부 LLM/API를 호출하지 않습니다.
488
+ > **AI 에이전트를 잘 다루는 도구가 되도록 설계되었습니다.**
489
+ > 사용자 동의 없이 자동으로 외부 LLM/API/CLI를 호출하지 않습니다.