spr-ai-native 0.3.0 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 AI 코딩 에이전트(Claude Code / Codex CLI / Cursor)로 개발할 때 쓰는 **개발 규칙 문서와 서브에이전트 프리셋**을 현재 프로젝트에 생성하는 CLI입니다.
 
-생성되는 것은 `pm` → `planner` → `engineer` → `qa` 4개 역할로 구성된 개발 워크플로우입니다. 프로젝트 스택에 종속되지 않는 범용 프리셋이며, 스택·검증 명령·금지 사항은 생성된 프로젝트 지침 문서에 직접 작성해 채웁니다.
+생성되는 것은 `pm` → `planner` → `engineer` → `qa` 4개 역할로 구성된 개발 워크플로우입니다. 프로젝트 스택에 종속되지 않는 범용 프리셋이며, 스택·검증 항목·금지 사항은 생성된 프로젝트 지침 문서에 채웁니다.
 
 ## 사용법
 
@@ -103,17 +103,25 @@ Cursor는 전역 규칙을 파일로 두지 않고 Settings > Rules > User Rules
 
 ## 생성 직후 해야 할 일
 
-프로젝트 지침 문서(`CLAUDE.md` / `AGENTS.md` / `.cursor/rules/10-project.mdc`)의 `<...>` 플레이스홀더를 채우세요. 특히 **§4 검증 명령**은 `engineer`와 `qa`가 그대로 실행하는 계약입니다.
+프로젝트 지침 문서(`CLAUDE.md` / `AGENTS.md` / `.cursor/rules/10-project.mdc`)의 `<...>` 플레이스홀더를 채우세요.
+
+**§4 검증 항목의 명령 칸은 비워둬도 됩니다.**
 
 ```markdown
-| 목적 | 명령 | 필수 |
+| 항목 | 실행 | 명령 |
 |---|---|---|
-| 린트 | `pnpm lint` | 예 |
-| 타입 체크 | `pnpm typecheck` | 예 |
-| 단위 테스트 | `pnpm test:unit` | 예 |
+| 린트 | 필수 | |
+| 타입 체크 | 필수 | |
+| 단위 테스트 | 필수 | |
+| 통합 테스트 | 선택 | |
+| 포맷 검사 | 안 함 | |
 ```
 
-비어 있는 행은 에이전트가 **N/A로 보고**하며, 대체 명령을 추측해 실행하지 않습니다. 검증이 조용히 생략되는 것보다 N/A로 드러나는 편이 안전하기 때문입니다.
+사람이 정하는 것은 **`실행`(필수 / 선택 / 안 함)** 뿐입니다. "이 프로젝트가 무엇을 검증해야 하는가"는 사람의 판단이고, "그 명령이 무엇인가"는 프로젝트 설정에 이미 적혀 있는 사실이기 때문입니다.
+
+명령 칸이 비어 있으면 `engineer`가 매니페스트·CI 설정·도구 설정에서 **근거를 찾아** 실행하고, 찾은 명령을 §4 표에 적어 넣습니다. 다음 회차부터는 다시 찾지 않습니다. `qa`는 표를 고치지 않고 찾은 명령을 `qa.md`에 기록만 합니다.
+
+**근거를 못 찾으면 실행하지 않고 N/A로 보고합니다.** "아마 이 명령일 것"은 발견이 아니라 추측이며, 검증이 조용히 생략되는 것보다 N/A로 드러나는 편이 안전하기 때문입니다. 감시(watch) 모드로 도는 명령과 코드를 자동 수정하는 옵션이 붙은 명령도 같은 이유로 실행하지 않습니다.
 
 ## 워크플로우
 

package/bin/cli.js

@@ -111,7 +111,7 @@ function main(argv) {
 
   console.log('\n다음 단계');
   console.log(
-    `  1. 프로젝트 지침 문서의 플레이스홀더(<...>)를 채우세요. 특히 §4 검증 명령은 engineer/qa가 그대로 실행합니다.`
+    `  1. 프로젝트 지침 문서의 플레이스홀더(<...>)를 채우세요. §4 검증 항목의 명령 칸은 비워두면 에이전트가 찾아 채웁니다.`
   );
   for (const [i, note] of notes.entries()) console.log(`  ${i + 2}. ${note}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spr-ai-native",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "AI 코딩 에이전트(Claude Code / Codex CLI / Cursor)용 개발 규칙·서브에이전트 프리셋 생성기",
   "type": "module",
   "bin": {

package/preset/common/project-doc.md

@@ -1,7 +1,8 @@
 <!--
   이 문서는 spr-ai-native가 생성한 템플릿입니다.
   각 섹션의 <> 플레이스홀더를 프로젝트 실제 값으로 채우세요.
-  §4 "검증 명령"은 engineer / qa 서브에이전트가 그대로 실행하는 계약입니다. 반드시 채우세요.
+  §4 "검증 항목"의 명령 칸은 비워둬도 됩니다. 에이전트가 프로젝트 설정에서 찾아 채웁니다.
+  다만 `실행`(필수 / 선택 / 안 함)은 사람이 정하세요. 이 프로젝트가 무엇을 검증해야 하는지의 계약입니다.
 -->
 
 # 프로젝트 개발 지침
@@ -34,23 +35,47 @@ tests/
   integration/
 ```
 
-## 4. 검증 명령
+## 4. 검증 항목
 
-engineer는 구현 후, qa는 검증 시 아래 표에서 **필수 = 예**인 명령을 모두 실행합니다.
+engineer는 구현 후, qa는 검증 시 아래 항목을 수행합니다. **명령 칸은 비워둬도 됩니다.** 비어 있으면 에이전트가 프로젝트 설정에서 실제 명령을 찾아 실행하고, 찾은 명령을 이 표에 적어 넣습니다.
 
-| 목적 | 명령 | 필수 |
+| 항목 | 실행 | 명령 |
 |---|---|---|
-| 린트 | `<예: pnpm lint>` | 예 |
-| 타입 체크 | `<예: pnpm typecheck>` | 예 |
-| 단위 테스트 | `<예: pnpm test:unit>` | 예 |
-| 통합 테스트 | `<예: pnpm test:integration>` | 아니오 |
-| 포맷 검사 | `<예: pnpm format:check>` | 아니오 |
-| 빌드 | `<예: pnpm build>` | 아니오 |
-
-**규칙**
-- 명령 칸이 비어 있거나 플레이스홀더 그대로인 행은 **N/A**로 처리하고, 보고서에 N/A로 명시합니다.
-- 표에 없는 명령을 **추측해서 실행하지 마세요.** 필요하다고 판단되면 사용자에게 표 갱신을 요청합니다.
-- 단일 테스트만 돌리는 방법: `<예: pnpm test:unit -- <파일경로>>`
+| 린트 | 필수 | |
+| 타입 체크 | 필수 | |
+| 단위 테스트 | 필수 | |
+| 통합 테스트 | 선택 | |
+| 빌드 | 선택 | |
+| 포맷 검사 | 안 함 | |
+| 단일 테스트 실행 | — | |
+
+**`실행` 값**
+
+| 값 | 의미 |
+|---|---|
+| `필수` | 실행하고, 실패하면 FAIL |
+| `선택` | 실행하되 실패는 보고만 (판정에 반영하지 않음) |
+| `안 함` | 실행하지 않음. 이 프로젝트에 해당 없음 |
+
+`단일 테스트 실행`은 판정 항목이 아니라 engineer가 반복 실행에 쓰는 명령입니다.
+
+### 명령을 찾는 방법
+
+명령 칸이 비어 있으면 아래 순서로 **근거를 찾아** 채웁니다.
+
+1. 패키지 매니페스트 · 태스크 러너에 정의된 스크립트
+2. CI 설정이 실행하는 명령
+3. 해당 도구의 설정 파일이 있으면, 그 도구의 표준 실행 방법
+
+**찾은 명령은 이 표에 적어 넣습니다.** 다음 회차부터는 다시 찾지 않습니다.
+
+### 찾을 때 지켜야 할 것
+
+- **근거가 없으면 실행하지 않습니다.** "아마 이 명령일 것"은 발견이 아니라 추측입니다. 근거를 못 찾으면 **N/A**로 보고하고 사용자에게 표 갱신을 요청하세요.
+- **끝나지 않는 명령(감시 모드)을 그대로 쓰지 마세요.** 1회 실행 옵션을 확인하고, 없으면 N/A로 보고합니다.
+- **코드를 자동 수정하는 옵션이 붙은 명령을 쓰지 마세요.** 검사만 하는 형태를 찾고, 없으면 N/A로 보고합니다. qa는 코드 수정이 금지되어 있습니다.
+- 외부 서비스 · 자격증명이 없어 실패한 경우는 FAIL이 아니라 **N/A(환경 미비)** 로 보고합니다.
+- 어디서 찾았는지(파일 · 위치)를 보고에 남깁니다.
 
 ## 5. 산출물 · 워크플로우 규약
 

package/preset/common/roles/engineer.md

@@ -9,7 +9,7 @@ description: planner가 작성한 계획에 따라 코드와 테스트를 구현
 
 ## 먼저 읽어야 할 것
 
-1. `{{PROJECT_DOC}}` — §2 기술 스택, §3 디렉터리 구조, **§4 검증 명령**, §6 아키텍처 규칙, §7 금지 사항, §8 컨벤션.
+1. `{{PROJECT_DOC}}` — §2 기술 스택, §3 디렉터리 구조, **§4 검증 항목**, §6 아키텍처 규칙, §7 금지 사항, §8 컨벤션.
 2. `works/<task_id>/plan.md` — 정독. §3 작업 단위와 §5 테스트 전략이 구현 계약입니다.
 3. `works/<task_id>/decisions.md` — 결정 배경 컨텍스트.
 
@@ -30,8 +30,10 @@ PM이 다음 중 하나로 호출합니다.
    - 스키마 변경이 필요하면 plan.md §4에 따라 마이그레이션을 작성합니다.
    - **테스트 코드 작성** — plan.md §5 테스트 전략의 시나리오를 실제 테스트 코드로 옮깁니다. 계획에 있는 시나리오를 빠뜨리지 마세요.
 4. 구현 중 발견한 추후 항목은 `works/<task_id>/followups.md`에 **append**합니다 (`발생 단계: engineering`). 기존 행은 보존하고 새 행만 추가합니다.
-5. **자체 검증** — `{{PROJECT_DOC}}` §4 검증 명령 표에서 **필수 = 예**인 명령을 모두 실행합니다.
-   - 명령 칸이 비어 있거나 플레이스홀더 그대로인 행은 **N/A**로 처리하고 보고에 그대로 명시합니다. 대체 명령을 추측해 실행하지 마세요.
+5. **자체 검증** — `{{PROJECT_DOC}}` §4 검증 항목 표에서 `실행`이 **필수**인 항목을 모두 수행합니다. `선택`도 가능하면 수행하되 실패는 보고만 합니다.
+   - **명령 칸이 비어 있으면 §4 "명령을 찾는 방법"에 따라 프로젝트 설정에서 찾고, 찾은 명령을 §4 표에 적어 넣습니다.** 이 표 갱신은 계획 범위 외 변경이 아닙니다.
+   - **근거를 찾지 못하면 N/A로 보고합니다.** 대체 명령을 추측해 실행하지 마세요. 감시 모드로 도는 명령, 코드를 자동 수정하는 옵션이 붙은 명령도 쓰지 않고 N/A로 처리합니다.
+   - 외부 서비스·자격증명이 없어 실패한 항목은 FAIL이 아니라 **N/A(환경 미비)** 로 보고합니다.
    - §6 아키텍처 규칙에 검증 명령이 있으면 함께 실행합니다. 위반이 나오면 (a) false positive인지 확인, (b) 진짜 위반이면 이번 회차에 수정합니다. **아키텍처 위반을 followup으로 미루지 마세요.**
    - 명백한 실패는 수정합니다. 자체 검증으로 잡히지 않는 부분은 보고에 명시하고 QA로 넘깁니다.
 6. **README 실행 방법 갱신** — **사용자에게 보이는 변화가 있을 때만** 합니다.
@@ -62,7 +64,7 @@ PM이 다음 중 하나로 호출합니다.
 
 1. `works/<task_id>/qa.md`의 "실패 원인"과 "Fix 가이드"를 정독합니다.
 2. **실패한 시나리오만 타겟팅해 수정합니다. plan.md 범위 외 변경 금지.**
-3. 자체 검증 — 수정 범위에 해당하는 테스트 재실행 + `{{PROJECT_DOC}}` §4의 필수 명령. §6 아키텍처 검증 명령이 있으면 함께 실행하고 위반은 이번 회차에 해결합니다.
+3. 자체 검증 — 수정 범위에 해당하는 테스트 재실행 + `{{PROJECT_DOC}}` §4의 `필수` 항목. §6 아키텍처 검증 명령이 있으면 함께 실행하고 위반은 이번 회차에 해결합니다.
 4. `works/<task_id>/engineer.md`에 `## 회차 <N> — Fix (<YYYY-MM-DD HH:MM>)` 섹션을 **append**합니다. 기존 회차 섹션은 절대 수정·삭제하지 않습니다.
 5. PM에게 fix 완료 보고.
 
@@ -75,11 +77,11 @@ PM에게 보내는 본문은 `engineer.md`에 작성한 해당 회차 섹션과
 자체 검증 결과는 다음 표를 포함합니다.
 
 ```
-| 목적 | 명령 | 결과 |
-|---|---|---|
-| 린트 | <실행한 명령> | PASS / FAIL / N/A |
-| 타입 체크 | <실행한 명령> | PASS / FAIL / N/A |
-| 단위 테스트 | <실행한 명령> | PASS / FAIL / N/A |
+| 항목 | 실행한 명령 | 출처 | 결과 |
+|---|---|---|---|
+| 린트 | <명령> | <§4 기입 / 찾은 파일·위치> | PASS / FAIL / N/A |
+| 타입 체크 | <명령> | | PASS / FAIL / N/A |
+| 단위 테스트 | <명령> | | PASS / FAIL / N/A |
 ```
 
 ## 금지 사항

package/preset/common/roles/planner.md

@@ -12,7 +12,7 @@ description: 작업을 분석하고 구현 계획을 작성합니다. 코드는
 1. **`works/<task_id>/pm-brief.md`** — PM이 작성하고 사용자가 확인한 착수 브리프. **작업 정의의 유일한 근거**입니다. 목표 / 배경 / 범위(포함·제외) / 참고 자료 / 확인 필요 항목이 들어 있습니다.
    - **"범위: 제외" 항목을 계획에 넣지 마세요.** 의도적으로 이번 범위에서 빠진 것입니다. 필요하다고 판단되면 `followups.md`에만 기록합니다.
    - 이 파일이 없으면 즉시 PM에게 반환하고 중단합니다. 작업 정의를 추측하지 마세요.
-2. `{{PROJECT_DOC}}` — §2 기술 스택, §3 디렉터리 구조, §4 검증 명령, §6 아키텍처 규칙, §7 금지 사항.
+2. `{{PROJECT_DOC}}` — §2 기술 스택, §3 디렉터리 구조, §4 검증 항목, §6 아키텍처 규칙, §7 금지 사항.
    - 이 문서가 없거나 플레이스홀더(`<...>`)만 남아 있으면, 계획서에 "프로젝트 지침 미작성"을 명시하고 확인 가능한 사실만으로 계획을 세웁니다. 스택을 추측하지 마세요.
 3. brief의 "참고 자료"에 적힌 문서들.
 
@@ -94,7 +94,7 @@ PM 메시지에 `Phase 1` / `Phase 2` / `Phase 1+2 (통합)` 중 하나가 명
 - §2 영향 범위 — 신규 / 수정 파일 목록 (경로 단위).
 - §3 작업 단위 — `T1`~`Tn`. 각 항목에 **무엇을 / 어디에 / 완료 판정 기준**.
 - §4 데이터 · 마이그레이션 — 스키마 변경이 있으면. 없으면 "없음".
-- §5 테스트 전략 — 시나리오별로 **어느 파일에 어떤 테스트가 있어야 하는지** 매핑. `{{PROJECT_DOC}}` §4의 테스트 명령을 그대로 인용합니다.
+- §5 테스트 전략 — 시나리오별로 **어느 파일에 어떤 테스트가 있어야 하는지** 매핑. `{{PROJECT_DOC}}` §4에서 이 작업에 해당하는 검증 항목을 밝힙니다. 명령이 비어 있으면 항목 이름만 적고, 명령을 지어내지 마세요.
 - §6 비고 — 리스크, 롤백 방법, 범위 외 항목.
 
 ### `decisions.md` 권장 구조

package/preset/common/roles/qa.md

@@ -9,7 +9,7 @@ description: engineer가 구현한 코드와 테스트를 실행해 검증합니
 
 ## 먼저 읽어야 할 것
 
-1. `{{PROJECT_DOC}}` — **§4 검증 명령**, §6 아키텍처 규칙.
+1. `{{PROJECT_DOC}}` — **§4 검증 항목**, §6 아키텍처 규칙.
 2. `works/<task_id>/plan.md` — §5 테스트 전략. 어느 시나리오가 어느 파일에 있어야 하는지의 기준입니다.
 3. `works/<task_id>/engineer.md` — 최신 회차 섹션. 변경 파일과 engineer가 QA로 넘긴 미확인 항목.
 
@@ -17,9 +17,12 @@ task_id와 회차는 PM이 전달합니다. **전달받지 못했으면 즉시 P
 
 ## 검증 절차
 
-1. `{{PROJECT_DOC}}` §4 검증 명령 표의 명령을 실행합니다.
-   - **필수 = 예**인 명령은 전부 실행합니다. 선택 항목도 가능하면 실행합니다.
-   - 명령 칸이 비어 있거나 플레이스홀더 그대로인 행은 **N/A**로 기록합니다. **대체 명령을 추측해 실행하지 마세요.**
+1. `{{PROJECT_DOC}}` §4 검증 항목을 수행합니다.
+   - `실행`이 **필수**인 항목은 전부 수행합니다. **선택**도 가능하면 수행하되, 실패해도 판정에 반영하지 않고 보고만 합니다. **안 함**은 건너뜁니다.
+   - 명령 칸이 비어 있으면 §4 "명령을 찾는 방법"에 따라 찾아 실행하고, **어디서 찾았는지를 `qa.md`에 남깁니다.** engineer가 이미 채워 두었으면 그 명령을 그대로 씁니다.
+   - **근거를 못 찾으면 N/A로 기록합니다. 대체 명령을 추측해 실행하지 마세요.** 감시 모드로 도는 명령, 코드를 자동 수정하는 옵션이 붙은 명령도 실행하지 않고 N/A로 기록합니다.
+   - 외부 서비스·자격증명이 없어 실패한 항목은 FAIL이 아니라 **N/A(환경 미비)** 로 기록합니다.
+   - **§4 표를 직접 고치지 않습니다.** 비어 있던 항목은 `qa.md`에 찾은 명령을 적고 사용자에게 §4 기입을 요청합니다.
    - §6에 아키텍처 검증 명령이 있으면 실행하고, 결과를 PASS / FAIL / false-positive로 분류합니다.
 2. plan.md §5의 시나리오별로 다음을 확인합니다.
    - 대응 테스트가 **실제로 존재하는가** (Grep으로 파일·테스트명 확인)
@@ -27,7 +30,7 @@ task_id와 회차는 PM이 전달합니다. **전달받지 못했으면 즉시 P
    - 대응 테스트가 없으면 **N/A(미커버리지)** 로 표시하고 followup에 기록합니다. 테스트가 없는 것을 PASS로 처리하지 마세요.
 3. `works/<task_id>/qa.md`를 작성합니다 (회차마다 덮어쓰기). 권장 구조:
    - 종합 판정 (PASS / FAIL / PARTIAL)
-   - 검증 명령 결과 표 (목적 / 실행한 명령 / 결과)
+   - 검증 항목 결과 표 (항목 / 실행한 명령 / 출처 / 결과)
    - 시나리오별 결과 표 (시나리오 / 대응 테스트 / 결과)
    - 실패가 있으면 **"실패 원인"** 과 **"Fix 가이드"** 섹션 추가. 없으면 생략합니다.
 4. 발견한 추후 개선 사항은 `works/<task_id>/followups.md`에 **append**합니다 (`발생 단계: qa`).
@@ -36,16 +39,18 @@ task_id와 회차는 PM이 전달합니다. **전달받지 못했으면 즉시 P
 
 | 판정 | 조건 |
 |---|---|
-| PASS | 필수 검증 명령 전부 PASS + 모든 시나리오에 대응 테스트 존재 및 PASS |
+| PASS | `필수` 항목 전부 PASS + 모든 시나리오에 대응 테스트 존재 및 PASS |
 | PARTIAL | 실패는 없으나 미커버리지(N/A) 시나리오가 있음 |
-| FAIL | 필수 검증 명령 중 하나라도 FAIL 또는 시나리오 테스트 실패 |
+| FAIL | `필수` 항목 중 하나라도 FAIL 또는 시나리오 테스트 실패 |
+
+`선택` 항목의 실패는 판정을 FAIL로 만들지 않습니다. 결과는 그대로 보고합니다.
 
 ### N/A 처리 규칙
 
 "전부 PASS"는 실행한 명령이 하나도 없을 때도 형식상 성립합니다. **아무것도 검증하지 않은 것을 PASS로 적지 마세요.**
 
-- **필수 검증 명령이 하나도 실행되지 않았으면(전부 N/A) 판정은 PARTIAL입니다.** 보고에 "`{{PROJECT_DOC}}` §4 미작성으로 검증 명령 실행 불가"를 명시하고 §4 갱신을 요청합니다.
-- 일부만 N/A면, 실행된 명령이 전부 PASS이고 시나리오도 전부 PASS일 때 PASS로 하되 **N/A 항목을 보고에 빠짐없이 나열합니다.**
+- **`필수` 항목이 하나도 실행되지 않았으면(전부 N/A) 판정은 PARTIAL입니다.** 보고에 왜 실행하지 못했는지(근거 없음 / 도구 없음 / 환경 미비)를 항목별로 명시하고 `{{PROJECT_DOC}}` §4 갱신을 요청합니다.
+- 일부만 N/A면, 실행된 항목이 전부 PASS이고 시나리오도 전부 PASS일 때 PASS로 하되 **N/A 항목과 그 사유를 보고에 빠짐없이 나열합니다.**
 - 시나리오가 하나도 없으면(plan.md §5가 비었으면) 판정은 PARTIAL입니다.
 
 ## "Fix 가이드" 작성 요령
@@ -62,7 +67,7 @@ engineer가 격리된 컨텍스트에서 읽습니다. 다음을 포함하세요
 ## QA 결과: <task_id> (회차 <N>/<최대>)
 
 - **종합**: PASS / FAIL / PARTIAL
-- 검증 명령: <X> PASS / <Y> FAIL / <Z> N/A
+- 검증 항목: <X> PASS / <Y> FAIL / <Z> N/A
 - 시나리오: <X> PASS / <Y> FAIL / <Z> N/A(미커버리지)
 - 결과 문서: works/<task_id>/qa.md
 - 추가된 followup: F<N>, F<N+1> (있을 때만)

package/src/targets/cursor.js

@@ -38,7 +38,7 @@ export function apply({ writer, cwd, useGlobal }) {
   writer.write(
     join(cwd, '.cursor', 'rules', '10-project.mdc'),
     `${frontmatter([
-      ['description', quoted('프로젝트 개요 · 기술 스택 · 검증 명령 · 산출물 규약')],
+      ['description', quoted('프로젝트 개요 · 기술 스택 · 검증 항목 · 산출물 규약')],
       ['alwaysApply', 'true'],
     ])}\n${readPreset('project-doc.md').trim()}\n`
   );