leerness 1.9.33 → 1.9.35

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 +79 -0
  2. package/README.md +288 -362
  3. package/bin/harness.js +439 -69
  4. package/package.json +1 -1
  5. package/scripts/e2e.js +111 -1
package/README.md CHANGED
@@ -1,8 +1,10 @@
1
1
  # Leerness
2
2
 
3
- > 한국어 우선 AI 개발 하네스. 멀티 에이전트 오케스트레이션 · 자동 검수 · 워크스페이스 가시성 · Ollama opt-in 통합.
3
+ > **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.35-green)]() [![tests](https://img.shields.io/badge/e2e-161%2F161-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
6
+
7
+ > Claude Code · Cursor · Copilot · Codex · Gemini CLI — 어떤 AI 에이전트로 코드를 짜든, leerness는 **"진짜로 했나? 중복 아닌가? 합의된 사양인가?"** 를 자동으로 검수합니다.
6
8
 
7
9
  ```
8
10
  ╔══════════════════════════════════════════════════════════════╗
@@ -14,220 +16,282 @@
14
16
  ║ ███████╗███████╗███████╗██║ ██║██║ ╚████║███████╗███████║ ║
15
17
  ║ ╚══════╝╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝╚══════╝╚══════╝ ║
16
18
  ║ ║
17
- ║ v1.9.32 Korean-first AI Development Harness ║
18
- ║ verify · reuse-map · handoff · agents · orchestrate ║
19
+ ║ v1.9.34 Korean-first AI Development Harness ║
20
+ ║ ★ verify · reuse-map · handoff · agents · orchestrate ║
19
21
  ║ ║
20
22
  ╚══════════════════════════════════════════════════════════════╝
21
- 한국어 우선 AI 개발 하네스 — verify · reuse-map · handoff · agents
22
23
  ```
23
24
 
25
+ ---
26
+
27
+ ## 🤔 leerness가 해결하는 문제
28
+
29
+ AI 에이전트(Claude Code, Cursor, Copilot, Codex, Gemini CLI 등)는 **빠르게 코드를 쓰지만, 다음 함정에 반복해서 빠집니다**:
30
+
31
+ | AI와 함께 일할 때 흔한 함정 | leerness의 해결책 |
32
+ |---|---|
33
+ | 🚨 "완료했습니다"라고 했지만 실제로 코드에 변경이 없음 | `verify-claim --run-tests` — 증거 파일 존재 + 테스트 실제 실행 검증 |
34
+ | 🚨 "API 호출 완료" 라고 했지만 코드에 URL이 없음 | `optimism-check` — 10 카테고리 패턴 + URL 매핑 + 신뢰도 점수 |
35
+ | 🚨 같은 함수를 여러 프로젝트에 중복 생성 | `reuse-map --all-apps --strict-elements` — 함수명 fuzzy 중복 감지 |
36
+ | 🚨 다음 세션이 컨텍스트를 잃음 | `handoff` — plan/progress/decisions 3채널 자동 적재 + `--compact` (500자) |
37
+ | 🚨 표면적 코드 리뷰 (도메인 깊이 부족) | `review --persona security,performance,ux` — 5 도메인 sub-agent 자동 부여 |
38
+ | 🚨 외부 AI CLI를 자동 호출하면 위험 | `agents list/dispatch/quota` — 환경변수 활성화 + 명시적 분배 (자동 호출 X) |
39
+ | 🚨 npx 캐시로 옛 버전이 실행됨 | `_warnIfStale` — install 시 npm latest 자동 비교 + 경고 (1.9.33+) |
40
+ | 🚨 멀티 sub-agent가 같은 파일을 동시에 써서 작업 손실 | 프롬프트 템플릿에 **파일 경로 격리 의무**, `agents dispatch` 안내문이 자동 추가 (1.9.34/35) |
41
+ | 🚨 sub-agent마다 사양 해석이 달라 통합 시 BUG 양산 | **`leerness contract verify <spec.md> <impl.js>`** — 명세 ↔ 구현 함수/필드 자동 검사 (1.9.35) |
42
+ | 🚨 신규 모듈의 capability가 reuse-map에 등록 안 됨 | **`leerness reuse autodetect`** — `module.exports` 스캔 + 자동 등록 (1.9.35) |
43
+ | 🚨 신규 디렉토리에서 sub-agent가 컨텍스트 없이 작업 시작 | `handoff` 호출 시 **.harness 부재 자동 경고** (1.9.35) |
44
+ | 🚨 audit warning이 쌓이지만 수동 fix가 번거로움 | **`audit --fix`** — session-handoff/current-state 자동 갱신 (1.9.35) |
45
+
46
+ ---
47
+
24
48
  ## ⚙️ 설치 (Install)
25
49
 
26
- > ⚠️ **leerness는 CLI 도구입니다.** `npm i leerness`(로컬)만으로는 `leerness` 명령이 PATH에 없어 실패할 수 있습니다. 아래 셋 중 하나를 사용하세요:
50
+ > ⚠️ **leerness는 CLI 도구입니다.** `npm i leerness`만으로는 명령이 PATH에 없습니다. 아래 셋 중 하나:
27
51
 
28
52
  ```bash
29
- # ✅ 1) 추천 — 설치 없이 즉시 실행 (npx 자동 캐시)
53
+ # ✅ 1) 추천 — 설치 없이 즉시 실행 (항상 @latest 명시)
30
54
  npx leerness@latest init . --language ko --skills recommended
31
55
 
32
- # ✅ 2) 전역 설치 (한 번 설치 후 어디서나 leerness 명령)
33
- npm i -g leerness && leerness --version
56
+ # ✅ 2) 전역 설치 (한 번이면 끝)
57
+ npm i -g leerness@latest && leerness --version
34
58
 
35
- # ✅ 3) 로컬 dev dependency + npx 실행
59
+ # ✅ 3) 로컬 dev dependency
36
60
  npm i --save-dev leerness && npx leerness handoff .
37
61
  ```
38
62
 
39
- > npmjs.com의 `npm i leerness`는 라이브러리 import용. CLI 명령(`leerness ...`) 직접 호출은 위 3가지 중 하나 필요.
63
+ ### 🚨 npx 캐시 함정 (1.9.33부터 자동 경고)
40
64
 
41
- ### 🚨 npx 캐시 함정 주의 (1.9.33부터 자동 경고)
42
-
43
- **`@latest` 없이 `npx leerness init`만 입력하면 PC에 캐시된 옛 버전이 무한히 재사용됩니다.**
65
+ `@latest` 없이 `npx leerness init`만 실행하면 **PC에 캐시된 옛 버전이 무한 재사용**됩니다.
44
66
 
45
67
  ```bash
46
- # ❌ 위험 — 캐시된 옛 버전 실행될 수 있음
68
+ # ❌ 위험 — 캐시된 옛 버전 실행 가능
47
69
  npx leerness init .
48
70
 
49
71
  # ✅ 안전 — 항상 최신 받음
50
72
  npx leerness@latest init .
51
73
 
52
- # ✅ 캐시가 의심스러우면 비우고 다시
53
- npx --yes clear-npx-cache
54
- npx --yes leerness@latest init .
74
+ # ✅ 캐시 의심 시 비우고 다시
75
+ npx --yes clear-npx-cache && npx --yes leerness@latest init .
55
76
  ```
56
77
 
57
- **1.9.33부터** `leerness init` 실행 시 npm registry latest와 자동 비교하여, **옛 버전이 실행 중이면 즉시 경고를 출력**합니다:
78
+ 1.9.33부터 `leerness init` 실행 시 npm registry latest와 자동 비교 → 옛 버전이면 즉시 경고:
58
79
 
59
80
  ```
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 .
81
+ ⚠ 옛 버전이 실행 중입니다 — v1.9.21 → v1.9.34 (npm 최신)
82
+ 해결: npx --yes clear-npx-cache && npx leerness@latest init .
68
83
  ```
69
84
 
70
85
  경고 끄기: `--no-stale-check` 또는 `LEERNESS_NO_STALE_CHECK=1`.
71
86
 
72
- ### 🎨 1.9.32 설치 경험
87
+ ---
88
+
89
+ ## 🎨 1.9.34 설치 경험 — 인터랙티브 multi-select
73
90
 
74
- `leerness init`을 실행하면 **LEERNESS ASCII 배너 + 빠른 시작 가이드 + sub-agent CLI 설정 prompt**가 자동으로 표시됩니다.
91
+ `leerness init`은 **방향키/스페이스/Enter**로 언어·스킬·sub-agent CLI를 선택합니다:
75
92
 
76
93
  ```
77
- ╔══════════════════════════════════════════════════════════════╗
78
- ║ ██╗ ███████╗███████╗██████╗ ███╗ ██╗███████╗███████╗ ║
79
- ║ ██║ ██╔════╝██╔════╝██╔══██╗████╗ ██║██╔════╝██╔════╝ ║
80
- ║ ██║ █████╗ █████╗ ██████╔╝██╔██╗ ██║█████╗ ███████╗ ║
81
- ║ ██║ ██╔══╝ ██╔══╝ ██╔══██╗██║╚██╗██║██╔══╝ ╚════██║ ║
82
- ║ ███████╗███████╗███████╗██║ ██║██║ ╚████║███████╗███████║ ║
83
- ║ ╚══════╝╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝╚══════╝╚══════╝ ║
84
- ║ v1.9.32 Korean-first AI Development Harness ║
85
- ╚══════════════════════════════════════════════════════════════╝
94
+ 설치 언어를 선택하세요
95
+ ↑↓ 이동, Enter 확정, q 취소
96
+ ❯ 자동 감지 — 디렉토리/파일 분석으로 한국어/영어 자동 판별
97
+ 한국어 — 모든 인스트럭션을 한국어로 생성
98
+ English — 모든 인스트럭션을 영어로 생성
99
+
100
+ 설치할 스킬 라이브러리 (Space=토글, a=전체, n=해제, Enter=확정)
101
+ ↑↓ 이동, Space 토글, a 전체, n 해제, Enter 확정
102
+ ❯ ◉ office — 마이크로소프트 오피스 자동화
103
+ ◉ commerce-api — 커머스 API 연동 (쿠팡/롯데온/스마트스토어)
104
+ ◯ crawling — Playwright 기반 크롤링·브라우저 자동화
105
+ ◉ ai-verified-skill-publisher — AI 검증 스킬 업로드·라이브러리화
106
+ ...
107
+
108
+ 활성화할 sub-agent CLI (Space=토글, a=전체, n=해제, Enter=확정)
109
+ ❯ ◉ claude — 🟢 설치됨 · Anthropic Claude Code CLI
110
+ ◯ codex — ⚪ 미설치 · OpenAI Codex CLI (격리 sandbox)
111
+ ◉ gemini — 🟢 설치됨 · Google Gemini CLI
112
+ ◯ copilot — ⚪ 미설치 · GitHub Copilot CLI
113
+ ```
86
114
 
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)
115
+ 활성화 후 미설치 CLI는 **자동 설치 시도**:
116
+ ```
117
+ ⚠ codex이(가) 설치되어 있지 않습니다.
118
+ 설치 명령: npm i -g @openai/codex
119
+ 지금 자동 설치를 시도할까요? (y/N): y
120
+ ▶ 실행: npm i -g @openai/codex
121
+ 🟢 codex 설치 확인 (v0.x.x)
108
122
  ```
109
123
 
110
124
  **스킵 옵션** (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 강제 비활성화
125
+ - `--yes` — 모든 prompt 스킵 (기본값 사용)
126
+ - `--no-interactive-select` 또는 `LEERNESS_NO_INTERACTIVE=1` — 구식 숫자 prompt
127
+ - `LEERNESS_NO_PROMPT=1` — readline prompt 강제 비활성
128
+
129
+ ---
130
+
131
+ ## 🚀 60초 시작
115
132
 
116
- **나중에 재실행**:
117
133
  ```bash
118
- leerness setup-agents . # 인터랙티브 재설정
119
- leerness agents list # 현재 상태 확인
120
- leerness agents quota # 사용량 추정 (1.9.31)
134
+ # 1) 신규 프로젝트
135
+ npx leerness@latest init . --language ko
136
+
137
+ # 2) 매일 사용
138
+ npx leerness handoff . # 컨텍스트 적재
139
+ npx leerness audit . # 일관성 감사
140
+ npx leerness verify-claim T-0001 --run-tests # 증거 자동 검증
141
+ npx leerness session close . # 세션 마감 + 핸드오프
142
+
143
+ # 3) 워크스페이스 (멀티 프로젝트)
144
+ npx leerness handoff --all-apps --since 24h # 최근 24h 변경 통합 뷰
145
+ npx leerness reuse-map --all-apps # 중복 함수 감지
146
+
147
+ # 4) 외부 AI CLI 오케스트레이션
148
+ npx leerness setup-agents # 인터랙티브 CLI 활성화
149
+ npx leerness agents list # ready 상태표
150
+ npx leerness agents dispatch "X 해줘" --to gemini # 명령 자동 생성
121
151
  ```
122
152
 
123
153
  ---
124
154
 
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)
155
+ ## 📊 적용 효과 (실측)
156
+
157
+ 벤치마크: `leerness-bench` 28 프로젝트 / 124 task 기준.
158
+
159
+ | 카테고리 | leerness | vanilla | 차이 |
160
+ |---|---:|---:|---:|
161
+ | 멀티에이전트 효율 | 100/100 | 3/100 | **+97** |
162
+ | 검수 자동화 (verify-claim 1.5s vs 90s 수동) | 98/100 | 0/100 | **+98** |
163
+ | 재사용 인식 (113 cap + 33 deps) | 100/100 | 0/100 | **+100** |
164
+ | 워크스페이스 가시성 (1 명령 vs 112 명령) | 99/100 | 0/100 | **+99** |
165
+ | 버그 자동 감지 (169 신호) | 100/100 | 0/100 | **+100** |
166
+ | 컨텍스트 유지 (3 채널) | 100/100 | 0/100 | **+100** |
167
+ | **종합** | **597/600 (99%)** | **3/600 (0.5%)** | **+594** |
135
168
 
136
169
  ---
137
170
 
138
- ## 🚀 60초 시작
171
+ ## 🤖 외부 AI CLI 오케스트레이션 (1.9.30~34)
172
+
173
+ claude/codex/gemini/copilot CLI들을 sub-agent로 활용. **자동 호출 금지** — 환경변수 활성화 + PATH 존재 시에만 ready.
139
174
 
175
+ ### 활성화 (1.9.32+ 권장: 인터랙티브)
140
176
  ```bash
141
- # 1) 신규 프로젝트 (설치 불필요)
142
- npx leerness@latest init . --language ko --skills recommended
177
+ leerness setup-agents . # 방향키/스페이스로 선택 + 미설치 자동 설치 시도
178
+ ```
143
179
 
144
- # 2) 기존 프로젝트 자동 업그레이드
145
- npx leerness@latest update . --yes
180
+ ### 활성화 (수동 `.env`)
181
+ ```bash
182
+ LEERNESS_ENABLE_CLAUDE=1 # Anthropic Claude Code CLI
183
+ LEERNESS_ENABLE_CODEX=1 # OpenAI Codex CLI (격리 sandbox)
184
+ LEERNESS_ENABLE_GEMINI=1 # Google Gemini CLI (--yolo 워크스페이스 직접 수정 가능)
185
+ LEERNESS_ENABLE_COPILOT=1 # GitHub Copilot CLI (gh copilot)
186
+ ```
146
187
 
147
- # 3) 매일 사용
148
- npx leerness handoff . # 컨텍스트 적재
149
- npx leerness audit . # 일관성 감사
150
- npx leerness verify-claim T-0001 --run-tests # evidence 자동 검증
188
+ ### 사용
189
+ ```bash
190
+ leerness agents list # 4 CLI 상태표
191
+ leerness agents quota # provider별 사용량/한도 추정
192
+ leerness agents dispatch "<task>" --to gemini # 명령 자동 생성 (실 호출 X)
151
193
  ```
152
194
 
195
+ ### 자동 설치 명령 (setup-agents가 사용)
196
+ | CLI | install 명령 | 안내 |
197
+ |---|---|---|
198
+ | claude | `npm i -g @anthropic-ai/claude-code` | https://docs.anthropic.com/en/docs/claude-code/setup |
199
+ | codex | `npm i -g @openai/codex` | https://github.com/openai/codex |
200
+ | gemini | `npm i -g @google/gemini-cli` | https://github.com/google-gemini/gemini-cli |
201
+ | copilot | `gh extension install github/gh-copilot` | https://github.com/github/gh-copilot |
202
+
203
+ ### 멀티레벨 오케스트레이션 검증 (1.9.34 실측)
204
+
205
+ 메인 → Sub-agent → Sub-sub-agent (3단계 깊이) 동작 검증:
206
+
207
+ | 항목 | 결과 |
208
+ |---|---|
209
+ | 단일 gemini 호출 | ✅ 15.6s (영문 번역 정상) |
210
+ | 병렬 gemini ×2 | ✅ 24s (출력 분리 정상, quota retry 1회) |
211
+ | 효율 (순차 3회 33s vs 병렬 3회 15s) | **2.2× 향상** (이론 3× 대비 60%) |
212
+ | 검수 체인 (결과를 다시 평가) | ✅ "2" → "yes" 정상 |
213
+ | 같은 파일 동시 쓰기 | ⚠ **last-writer-wins, 락 없음** |
214
+
215
+ **결론**:
216
+ - ✅ 3단계 오케스트레이션 동작
217
+ - ✅ 독립 작업(번역/평가/리뷰) 2×+ 효율 향상
218
+ - ⚠ **같은 리소스 동시 쓰기는 데이터 손실 위험** — 호출자가 파일 경로 격리 책임
219
+ - ⚠ gemini quota 동시 호출 시 retry 발생 → 병렬 확장성 ~3개로 제한
220
+
221
+ ### 정책
222
+ - ❌ leerness는 외부 CLI를 자동 호출하지 않음 (사용자/메인이 명시적 실행)
223
+ - ✅ `agents dispatch`는 명령 텍스트만 출력 → 사용자가 복사 실행
224
+ - ✅ quota 여유 큰 CLI를 메인 에이전트가 우선 선택하도록 신호 제공
225
+ - ⚠ `gemini --yolo`는 워크스페이스 파일 직접 수정 가능 (codex와 차이)
226
+
153
227
  ---
154
228
 
155
- ## 📊 적용 효과 (검증된 점수)
229
+ ## 🎭 페르소나 리뷰 (1.9.29)
156
230
 
157
- 벤치마크 시뮬 결과 (`leerness-bench`로 측정):
231
+ 도메인 페르소나를 sub-agent에 자동 부여 → 표면 리뷰 대비 **도메인 발견 3-4배**, 토큰 비용 ~3%.
158
232
 
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%
233
+ ### 5종 내장 페르소나
234
+ | ID | 역할 | 발견 깊이 |
235
+ |---|---|---|
236
+ | `security` | 10년차 보안 엔지니어 (OWASP/CWE/한국 개인정보보호법) | CWE 매핑 + 실 페이로드 |
237
+ | `performance` | V8 엔진 내부 전문가 | Hot path Top 5 + RPS 추정 |
238
+ | `ux` | 한국어 UX 라이터 + DX 컨설턴트 | Before/After 메시지 5건 |
239
+ | `testing` | TDD + property-based 테스트 엔지니어 | 누락 테스트 + property 후보 |
240
+ | `docs` | 한국어 기술 문서 작성자 | 60초 시작 가능성 평가 |
241
+
242
+ ```bash
243
+ leerness review src/api.js --persona security,performance,ux
244
+ leerness persona list
245
+ leerness persona add my-domain # 사용자 정의 페르소나
246
+ ```
174
247
 
175
248
  ---
176
249
 
177
- ## 📚 핵심 명령
250
+ ## 🛠 핵심 명령 매트릭스
178
251
 
179
- ### 작업 흐름
252
+ ### 일상 사용
180
253
  ```bash
181
- leerness handoff . # 세션 시작 — 컨텍스트 자동 적재
182
- leerness handoff --all-apps --since 1h # 워크스페이스 + 최근 변경
183
- leerness handoff --compact # LLM 프롬프트용 1줄 요약
184
- leerness session close . # 세션 종료 — handoff 자동 작성
254
+ leerness init [path] [--language auto|ko|en] # 신규 프로젝트 (1.9.34 인터랙티브)
255
+ leerness handoff [path] [--compact] [--all-apps] [--since 24h]
256
+ leerness audit [path] # 일관성 감사
257
+ leerness verify-claim T-XXX --run-tests # 증거 + 실 테스트
258
+ leerness optimism-check T-XXX # 낙관적 표시 감지
259
+ leerness gate [path] # verify+audit+scan+encoding+lazy
260
+ leerness session close [path] # 세션 마감
185
261
  ```
186
262
 
187
- ### 자동 검수 (핵심 기능)
263
+ ### 워크스페이스
188
264
  ```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 설정 + 자동 설치 시도
265
+ leerness handoff --all-apps # 전 프로젝트 통합 뷰
266
+ leerness reuse-map --all-apps --strict-elements # 함수 중복 감지
267
+ leerness retro --all-apps --days 7 # 회고
268
+ leerness insights --all-apps # 누적 통계
269
+ leerness brainstorm "키워드" --all-apps --include-code
270
+ leerness deps <capability> --run-tests # 영향 추적 + 자동 회귀
205
271
  ```
206
272
 
207
- ### 워크스페이스 (멀티 프로젝트)
273
+ ### 외부 AI CLI · 멀티 에이전트 (1.9.30~35)
208
274
  ```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 다중 세션 즉시 신호
275
+ leerness setup-agents . # 인터랙티브 활성화 + 자동 설치
276
+ leerness agents list # 4 CLI 상태표
277
+ leerness agents quota # 사용량 추정
278
+ leerness agents dispatch "<task>" --to gemini # 명령 생성 (안전 규칙 포함)
279
+ leerness contract verify <spec.md> <impl.js> # 1.9.35 명세 ↔ 구현 일치 검사
280
+ leerness reuse autodetect [path] [--apply] # 1.9.35 capability 자동 등록
281
+ leerness audit . --fix # 1.9.35 누락 메타 자동 갱신
218
282
  ```
219
283
 
220
- ### 멀티 에이전트 (1.9.22, opt-in)
284
+ ### 페르소나·리뷰 (1.9.29)
221
285
  ```bash
222
- # 환경변수 설정 후 활성화 (자동 실행 절대 금지)
223
- echo "LEERNESS_OLLAMA_BASE_URL=http://localhost:11434" >> .env
224
- leerness orchestrate "<목표>" --agents 10 --model qwen2.5:7b-instruct
286
+ leerness persona list|show <id>|add <id>
287
+ leerness review <file> --persona security,performance,ux
225
288
  ```
226
289
 
227
290
  ### 데이터 위생
228
291
  ```bash
229
- leerness scan secrets . # AWS/GitHub/OpenAI/Anthropic/Google/Slack/PEM/하드코딩 패스워드
292
+ leerness scan secrets . # AWS/GitHub/OpenAI/Anthropic/Google/Slack/PEM
230
293
  leerness encoding check . # BOM/UTF-16/한글 라운드트립
294
+ leerness lazy detect . # 증거 없는 done · 빈 handoff · 추적 없는 TODO
231
295
  ```
232
296
 
233
297
  ### 버전 관리
@@ -239,42 +303,23 @@ leerness update --from <tgz> # 오프라인/사내 미러
239
303
 
240
304
  ---
241
305
 
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 호출 폭주 방지.
306
+ ## 🌐 환경변수
263
307
 
264
- | 명령 | 동작 |
308
+ | 변수 | 효과 |
265
309
  |---|---|
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`
310
+ | `LEERNESS_OFFLINE=1` | npm 호출 스킵 (오프라인) |
311
+ | `LEERNESS_NPM_TOKEN` | release publish용 |
312
+ | `LEERNESS_GITHUB_TOKEN` | gh release용 |
313
+ | `LEERNESS_OLLAMA_BASE_URL` | 1.9.22 — orchestrate opt-in 활성 |
314
+ | `LEERNESS_OLLAMA_MODEL` | orchestrate 기본 모델 |
315
+ | `LEERNESS_ENABLE_CLAUDE` | 1.9.30 — agents dispatch Claude 활성 (=1) |
316
+ | `LEERNESS_ENABLE_CODEX` | 1.9.30 — Codex 활성 (=1) |
317
+ | `LEERNESS_ENABLE_GEMINI` | 1.9.30 — Gemini 활성 (=1) |
318
+ | `LEERNESS_ENABLE_COPILOT` | 1.9.30 — gh copilot 활성 (=1) |
319
+ | `LEERNESS_NO_BANNER` | 1.9.32 — init 배너 스킵 (=1) |
320
+ | `LEERNESS_NO_PROMPT` | 1.9.32 — readline prompt 강제 비활성 (=1) |
321
+ | `LEERNESS_NO_STALE_CHECK` | 1.9.33 — npx 캐시 옛 버전 경고 끄기 (=1) |
322
+ | `LEERNESS_NO_INTERACTIVE` | 1.9.34 — 방향키 multi-select 비활성, 숫자 prompt 폴백 (=1) |
278
323
 
279
324
  ---
280
325
 
@@ -292,6 +337,7 @@ leerness orchestrate "복잡한 기능" --agents 20
292
337
  ├── skill-index.md · skills/<id>/ · templates/
293
338
  ├── personas/<id>.md (1.9.29+, 사용자 정의 페르소나)
294
339
  ├── reviews/ (1.9.29+, 페르소나 리뷰 결과)
340
+ └── cache/update-check.json (1.9.33+, 24h npm latest 캐시)
295
341
 
296
342
  .claude/ (commands · skills · settings.local.json) · .cursor/rules/leerness.mdc
297
343
  .github/copilot-instructions.md · AGENTS.md · CLAUDE.md
@@ -299,6 +345,27 @@ leerness orchestrate "복잡한 기능" --agents 20
299
345
 
300
346
  ---
301
347
 
348
+ ## 🛡 비파괴 마이그레이션 정책
349
+
350
+ - 모든 변경 전 `.harness/archive/leerness-<version>-<timestamp>/` 자동 백업
351
+ - 사용자 메모리 (`plan`, `progress`, `decisions`, `task-log`, `architecture`, `reuse-map` 등) **항상 보존**
352
+ - 관리 인스트럭션은 새 템플릿으로 머지하되 이전 내용을 `<!-- leerness:migration-preserved -->` 블록에 보존
353
+ - 결과 보고: `.harness/migration-report.md`
354
+
355
+ ---
356
+
357
+ ## 🔄 자동 버전 감지/업데이트
358
+
359
+ `init`/`migrate` 시 `.claude/settings.local.json`의 SessionStart hook에 `update --check` 자동 등록. 24시간 캐시로 npm 호출 폭주 방지.
360
+
361
+ | 명령 | 동작 |
362
+ |---|---|
363
+ | `update --check` | `HARNESS_VERSION` ↔ `npm view leerness version` 비교 |
364
+ | `update --yes` | 백업 → 마이그레이션 → verify/audit → 로그 누적 |
365
+ | `update --from <tarball>` | 로컬/오프라인/사내 미러 |
366
+
367
+ ---
368
+
302
369
  ## 🧪 자동 검수 도구 매트릭스
303
370
 
304
371
  | 도구 | 검출 | 추가 |
@@ -316,152 +383,29 @@ leerness orchestrate "복잡한 기능" --agents 20
316
383
  | `lazy detect` | 증거 없는 done · 빈 handoff · 추적 없는 TODO | 1.9.7 |
317
384
  | `orchestrate --agents N` | 다중 LLM 동시 호출 (opt-in) | 1.9.22 |
318
385
  | `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 방치/검증 흔적 부재
338
-
339
- ---
340
-
341
- ## 🔬 낙관적 표시 방지 (1.9.26/27)
342
-
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와 차이)
386
+ | `review --persona X` | 도메인별 sub-agent 자동 프롬프트 | 1.9.29 |
387
+ | `persona list/show/add` | 페르소나 카탈로그 관리 | 1.9.29 |
388
+ | `agents list/check` | 4 CLI 활성/설치 상태표 | 1.9.30 |
389
+ | `agents dispatch --to X` | ready CLI에 대상 명령 자동 생성 | 1.9.30 |
390
+ | `agents quota` | provider별 사용량/한도 추정 | 1.9.31 |
391
+ | `setup-agents` | 인터랙티브 CLI 활성화 + 자동 설치 시도 | 1.9.32 |
392
+ | `contract verify <spec> <impl>` | 명세 ↔ 구현 함수/필드 일치 자동 검사 | 1.9.35 |
393
+ | `reuse autodetect [--apply]` | `module.exports` 스캔 → reuse-map 후보 등록 | 1.9.35 |
394
+ | `audit --fix` | session-handoff/current-state 자동 갱신 | 1.9.35 |
395
+ | `handoff` (init 부재 경고) | 신규 디렉토리에서 즉시 init 안내 | 1.9.35 |
396
+ | `_warnIfStale` (자동) | npx 캐시 옛 버전 자동 경고 | 1.9.33 |
397
+ | `_selectOne/_selectMany` | 방향키/Space 인터랙티브 multi-select | 1.9.34 |
459
398
 
460
399
  ---
461
400
 
462
- ## 🤝 Claude Code 통합
401
+ ## 🤝 Claude Code / Cursor / Copilot 통합
463
402
 
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)
403
+ 설치 시 자동 등록:
404
+ - `.claude/commands/{handoff, session-close, audit, lazy-detect, update}.md`
405
+ - `.claude/skills/leerness.md` (스킬 정의)
406
+ - `.claude/settings.local.json` (SessionStart hook `update --check`)
407
+ - `.cursor/rules/leerness.mdc`
408
+ - `.github/copilot-instructions.md`
465
409
 
466
410
  ---
467
411
 
@@ -476,26 +420,7 @@ leerness skill optimize <id> --before "..." --after "..."
476
420
  leerness skill consolidate
477
421
  ```
478
422
 
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) |
423
+ **기본 카탈로그**: `feature-implementation`, `ai-verified-skill-publisher`, `open-meteo`, `static-site-builder`, `project-roadmap-generator`, `office`, `commerce-api`, `crawling`, `firebase`, `ads-analytics`, `appstore-review`.
499
424
 
500
425
  ---
501
426
 
@@ -508,6 +433,7 @@ leerness skill consolidate
508
433
  | "통계 / 누적 지표" | `leerness insights` |
509
434
  | "X 관련 자료 / X 시작 전 검토" | `leerness brainstorm "X"` |
510
435
  | "매 X마다 Y를 해줘" | `leerness rule add "Y" --trigger every-X` |
436
+ | "외부 CLI 설정" | `leerness setup-agents` |
511
437
 
512
438
  `AGENTS.md`에 자동 등록 — Claude Code/Cursor가 이를 보고 자연어를 명령으로 변환.
513
439
 
@@ -522,10 +448,13 @@ A. 사용자 메모리(plan/progress/decisions/architecture/reuse-map 등)는 **
522
448
  A. 기본 동작입니다. `LEERNESS_OLLAMA_BASE_URL` 미설정 시 LLM 호출 절대 발생 안 함. `orchestrate` 명령만 거부 (다른 명령은 LLM 없이 동작).
523
449
 
524
450
  **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'`.
451
+ A. 네. `--json` (retro/insights/brainstorm/handoff/reuse-map/verify-claim) + exit code 통합. `--yes` + `LEERNESS_NO_PROMPT=1`로 비대화형 보장.
452
+
453
+ **Q. 외부 AI CLI를 자동으로 호출하나요?**
454
+ A. **아니요.** `agents dispatch`는 명령 텍스트만 출력합니다. 사용자/메인 에이전트가 명시적으로 실행해야 합니다.
526
455
 
527
- **Q. 다른 워크스페이스 모드 명령은?**
528
- A. `--all-apps`는 현재 디렉토리 + `_apps/*` (또는 부모의 `_apps/*`)의 모든 leerness 프로젝트 발견. `--include p1,p2`로 명시도 가능.
456
+ **Q. multi-select가 SSH/tmux에서 안 보여요.**
457
+ A. 256색 ANSI를 지원하지 않는 환경입니다. `LEERNESS_NO_INTERACTIVE=1` 또는 `--no-interactive-select`로 구식 숫자 prompt를 사용하세요.
529
458
 
530
459
  ---
531
460
 
@@ -535,32 +464,28 @@ A. `--all-apps`는 현재 디렉토리 + `_apps/*` (또는 부모의 `_apps/*`)
535
464
  npm test # = node ./scripts/e2e.js
536
465
  ```
537
466
 
538
- **153/153 시나리오** 통과 (1.9.7~1.9.33 회귀 + 신규 검증).
467
+ **161/161 시나리오** 통과 (1.9.7~1.9.35 회귀 + 신규 검증).
539
468
 
540
469
  ---
541
470
 
542
471
  ## 📜 변경 이력 (최근)
543
472
 
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 참조)
473
+ - **1.9.35** — 파이프라인 메타-감사에서 도출된 5개 개선 통합: `contract verify` · `reuse autodetect` · `audit --fix` · `handoff` init 부재 경고 · `agents dispatch` 안전 규칙 안내.
474
+ - **1.9.34** — 방향키/스페이스 인터랙티브 multi-select (`_selectOne`/`_selectMany`) + 256색 그라데이션 배너 + 3단계 sub-agent 오케스트레이션 검증 (2.2× 효율 실측).
475
+ - **1.9.33** — `_warnIfStale()` — `npx leerness init` 시 옛 버전 자동 경고 + 해결 안내.
476
+ - **1.9.32** — ASCII 배너 + `setup-agents` 인터랙티브 설정 + 미설치 CLI 자동 설치 시도.
477
+ - **1.9.31** — `leerness agents quota` (provider별 사용량/한도 추정).
478
+ - **1.9.30** — 외부 AI CLI 오케스트레이션 (claude/codex/gemini/copilot) + 환경변수 활성화 정책.
479
+ - **1.9.29** — 페르소나 시스템 (5종 내장) + `leerness review --persona` (도메인 깊이 3-4배).
480
+ - **1.9.28** — 카카오페이/네이버페이 패턴 + confidence floor 0.15.
481
+ - **1.9.27** — `optimism-check` 강화: 10 카테고리 + URL/메서드 매핑 + 신뢰도 점수.
482
+ - **1.9.26** — `optimism-check <T-ID>`, `verify-claim --strict-claims`.
483
+ - **1.9.25** — `--include-code` (소스 코드 인덱싱), `register-pending` (다중 세션).
484
+ - **1.9.24** — `deps <capability>` (depends-on 역추적 + 자동 회귀).
485
+ - **1.9.22** — Ollama opt-in 통합 (`orchestrate --agents N`), `handoff --compact`, `llm-bench record`.
486
+ - **1.9.18** — `--since`, `--strict-elements`, `depends-on` 그래프, `verify-claim`.
487
+ - **1.9.17** — `handoff/reuse-map --all-apps` 워크스페이스 모드.
488
+ - ... (전체 [CHANGELOG.md](CHANGELOG.md) 참조)
564
489
 
565
490
  ---
566
491
 
@@ -575,4 +500,5 @@ npm test # = node ./scripts/e2e.js
575
500
 
576
501
  MIT — © leerness contributors
577
502
 
578
- > **AI 에이전트를 잘 다루는 도구가 되도록 설계되었습니다.** 사용자 동의 없이 자동으로 외부 LLM/API를 호출하지 않습니다.
503
+ > **AI 에이전트를 잘 다루는 도구가 되도록 설계되었습니다.**
504
+ > 사용자 동의 없이 자동으로 외부 LLM/API/CLI를 호출하지 않습니다.