spr-ai-native

AI 코딩 에이전트(Claude Code / Codex CLI / Cursor)로 개발할 때 쓰는 개발 규칙 문서와 서브에이전트 프리셋을 현재 프로젝트에 생성하는 CLI입니다.

생성되는 것은 계획서 승인 → 구현 → 검증 → 작업 보고서로 이어지는 개발 워크플로우입니다. 사람이 개입하는 지점은 계획서 승인 1회이고, 산출 문서는 plan.md와 work-report.md 둘뿐입니다. 프로젝트 스택에 종속되지 않는 범용 프리셋이며, 스택·검증 항목·금지 사항은 생성된 프로젝트 지침 문서에 채웁니다.

사용법

설치 없이 실행하는 것을 권장합니다.

npx spr-ai-native@latest claude    # Claude Code용
npx spr-ai-native@latest codex     # Codex CLI용
npx spr-ai-native@latest cursor    # Cursor용

전역 설치도 가능합니다.

npm install -g spr-ai-native
spr-ai-native claude

한 번에 한 대상만 생성합니다. 여러 도구를 함께 쓰면 대상별로 각각 실행하세요.

옵션

| 옵션 | 설명 | |---|---| | --global | 공통 행동 지침을 전역 파일에도 설치합니다 (Cursor는 미지원, 아래 참고) | | --force | 기존 파일을 덮어씁니다. 기본 동작은 건너뛰기입니다 | | --dry-run | 파일을 만들지 않고 생성될 경로만 출력합니다 | | -h, --help | 사용법 | | -v, --version | 버전 |

기존 파일은 덮어쓰지 않습니다. 이미 CLAUDE.md나 AGENTS.md가 있으면 건너뛰고, 건너뛴 파일 목록과 함께 --force 안내를 출력합니다. 먼저 --dry-run으로 확인한 뒤 --force를 쓰는 것을 권장합니다.

실행 환경

| 항목 | 요구사항 | |---|---| | Node.js | 18 이상 (CLI 실행에만 필요. 프로젝트 언어와 무관합니다) | | 의존성 | 없음 (외부 패키지를 쓰지 않습니다) | | OS | macOS / Linux / Windows |

생성물을 실제로 활용하려면 각 도구가 서브에이전트를 지원해야 합니다.

| 도구 | 요구사항 | 확인 방법 | |---|---|---| | Claude Code | .claude/agents/, .claude/commands/ 지원 버전 | claude --version | | Codex CLI | 멀티 에이전트(서브에이전트) + skills 지원 버전 | codex --version, ~/.codex/config.toml의 [agents] 확인 | | Cursor | 2.4 이상 (서브에이전트 도입 버전) | Cursor > About |

서브에이전트를 쓸 수 없으면 /pm의 engineer 진행 단계가 동작하지 않습니다. 계획서 작성과 점검은 서브에이전트 없이도 됩니다.

생성되는 파일

claude

CLAUDE.md                      프로젝트 지침 (템플릿 — 직접 채워야 함)
.claude/agents/engineer.md     서브에이전트
.claude/agents/qa.md
.claude/commands/pm.md         유일한 진입점 (/pm)
~/.claude/CLAUDE.md            --global 지정 시, 공통 행동 지침

codex

AGENTS.md                      프로젝트 지침 (템플릿)
.codex/agents/engineer.toml    서브에이전트 (TOML)
.codex/agents/qa.toml
.codex/skills/pm/SKILL.md      유일한 진입점 ($pm)
~/.codex/AGENTS.md             --global 지정 시, 공통 행동 지침

.codex/config.toml은 수정하지 않습니다. 멀티 에이전트가 비활성화되어 있으면 [agents] enabled = true를 직접 확인하세요.

cursor

.cursor/rules/00-base.mdc      공통 행동 지침 (alwaysApply: true)
.cursor/rules/10-project.mdc   프로젝트 지침 (템플릿)
.cursor/agents/engineer.md     서브에이전트
.cursor/agents/qa.md           (readonly: true — 코드·문서 수정 불가)
.cursor/commands/pm.md         유일한 진입점 (/pm)

Cursor는 전역 규칙을 파일로 두지 않고 Settings > Rules > User Rules에 저장합니다. 따라서 cursor 대상에서 --global은 무시되며, 전역으로 쓰려면 .cursor/rules/00-base.mdc의 frontmatter 아래 본문을 User Rules에 직접 붙여넣으세요.

생성 직후 해야 할 일

프로젝트 지침 문서(CLAUDE.md / AGENTS.md / .cursor/rules/10-project.mdc)의 <...> 플레이스홀더를 채우세요.

"3. 검증 항목"의 명령 칸은 비워둬도 됩니다.

| 항목 | 실행 | 명령 |
|---|---|---|
| 린트 | 필수 | |
| 타입 체크 | 필수 | |
| 단위 테스트 | 필수 | |
| 통합 테스트 | 선택 | |
| 포맷 검사 | 안 함 | |

사람이 정하는 것은 실행(필수 / 선택 / 안 함) 뿐입니다. "이 프로젝트가 무엇을 검증해야 하는가"는 사람의 판단이고, "그 명령이 무엇인가"는 프로젝트 설정에 이미 적혀 있는 사실이기 때문입니다.

명령 칸이 비어 있으면 engineer가 매니페스트·CI 설정·도구 설정에서 근거를 찾아 실행하고, 찾은 명령을 그 표에 적어 넣습니다. 다음 회차부터는 다시 찾지 않습니다. qa는 표를 고치지 않고 찾은 명령을 보고에 남깁니다.

근거를 못 찾으면 실행하지 않고 N/A로 보고합니다. "아마 이 명령일 것"은 발견이 아니라 추측이며, 검증이 조용히 생략되는 것보다 N/A로 드러나는 편이 안전하기 때문입니다. 감시(watch) 모드로 도는 명령과 코드를 자동 수정하는 옵션이 붙은 명령도 같은 이유로 실행하지 않습니다.

워크플로우

[사용자] 요구사항 대화
   │
[사용자] /pm TECG-582 plan 작성
   │
[PM]     works/TECG-582/plan.md 작성
   ⏸ 멈춤 ─────────────────────────────────── 게이트 (계획서 승인, 유일)
   │
[사용자] (선택) /pm TECG-582 plan 확인   ← 편집분 점검
[사용자] /pm TECG-582 engineer 진행      ← 이 지시가 곧 승인
   │
[PM]     engineer(구현 + 테스트) → qa(계획 대비 검증) ─┐
         │                                             │ 실패하면 재개발 1회
         └── qa PASS ──────────────────────────────────┘
         works/<task_id>/work-report.md 작성 + 채팅 보고
   │
[사용자] 작업 보고서 검토 → 코드 리뷰 → 직접 커밋

통제 지점은 두 곳입니다

이 프리셋의 목적은 산출물을 남기는 것이 아니라, 한정된 사람의 주의력을 통제가 가장 많이 사는 곳에 배치하는 것입니다.

| 지점 | 문서 | 사람이 하는 일 | |---|---|---| | 위임 전 | plan.md | 범위를 자르고, AI가 대신 내린 판단을 뒤집는다 | | 위임 후 | work-report.md | 계획 대비 결과와 증거를 확인하고, 검증되지 않은 것을 본다 |

그 사이는 통제할 수 없으므로 규칙으로 막습니다 — 계획 범위 밖은 건드리지 않는다.

계획서 게이트 — 하위 명령 세 가지

/pm <task_id> plan 작성은 곧바로 위임하지 않고 works/<task_id>/plan.md만 씁니다. 대화를 나눈 메인 세션이 직접 쓰므로 논의 내용을 서브에이전트에게 압축해 넘기며 새는 구간이 없습니다.

계획서에 쓰는 것: 목표·완료 조건 / 범위(포함 · 제외) / 결정 사항 / 작업 단위 / 테스트 시나리오. 쓰지 않는 것: 함수 시그니처, 클래스 설계, 알고리즘, 코드 조각. 판별 기준은 하나입니다 — 계획서에 코드 블록이 등장하면 선을 넘은 것입니다.

진입점은 /pm 하나이고 하위 명령으로 단계를 나눕니다. "승인" 같은 자연어 회신을 게이트로 쓰지 않습니다 — "좋아 보이네요" 같은 말이 승인으로 해석되면 검토하지 않은 계획이 그대로 넘어가기 때문입니다.

| 입력 | 하는 일 | |---|---| | /pm <task_id> plan 작성 | 계획서를 쓰고 멈춤 | | /pm <task_id> plan 확인 | 계획서를 점검해 보고하고 멈춤 (선택) | | /pm <task_id> engineer 진행 | engineer → qa → 작업 보고서 |

plan 확인은 사용자가 plan.md를 직접 편집한 뒤 그 편집분을 검증하는 자리입니다. 결정 칸이 비었는지, 완료 판정 기준이 없는 작업 단위가 있는지, 테스트가 매핑되지 않은 완료 조건이 있는지 같은 기계적으로 판단 가능한 6가지만 봅니다. 계획 내용 자체를 비판하지는 않습니다 — 설계 판단은 사용자의 몫입니다.

결정 사항 표에는 되돌리는 비용 칸이 있습니다. 항목이 여럿이어도 사용자는 높음부터 보면 되므로 이 칸이 검토 시간을 배분합니다. 스키마나 공개 인터페이스처럼 나중에 바꾸기 비싼 것은 본문이 아니라 여기로 올라와 승인을 받습니다.

작업 단위가 7개를 넘거나 영향 파일이 15개를 넘으면 PM이 계획서를 내놓기 전에 작업을 쪼개자고 먼저 제안합니다. 게이트가 1회뿐이라 한 번에 위임하는 양이 크면 통제할 수 없기 때문입니다.

테스트 기준은 계획서입니다

커버리지 수치나 함수 개수를 기준으로 삼지 않습니다. 숫자를 목표로 주면 통과하기 쉬운 테스트가 생기기 때문입니다 — 구현을 그대로 옮긴 assertion은 커버리지만 올리고 검증력을 남기지 않습니다. 그래서 사용자가 승인한 완료 판정 기준에만 테스트를 매답니다.

| 구분 | 실행 | 기준 | |---|---|---| | 완료 조건 테스트 | 필수 | 계획서 각 작업 단위의 완료 판정 기준마다 최소 1개 | | 실패 경로 테스트 | 필수 | 계획서에 적힌 경계 · 오류 시나리오 | | 단위 테스트 | 선택 | 로직이 복잡한 순수 함수에 한해 engineer 재량 |

qa는 테스트가 통과했는지만이 아니라 완료 판정 기준마다 대응 테스트가 실재하는지를 확인합니다. 없으면 통과가 아니라 미검증입니다.

작업 보고서

work-report.md는 PM이 쓰지만 PM은 코드를 읽지 않습니다. 그래서 증거(실행한 명령, 출력, 파일:라인)는 engineer · qa 응답에서 원문 그대로 옮기고, 응답에 없는 것은 보고서에 적지 않습니다.

계획서의 작업 단위와 보고서의 결과 표가 T 기준으로 1:1이라 두 문서를 나란히 놓고 대조할 수 있습니다.

검증하지 못한 것 섹션이 비어 있고 근거도 없는 보고서는 검증이 아니라 통과 선언입니다. qa는 계획에 없는데 바뀐 파일도 git diff로 대조해 계획 이탈로 보고합니다.

세션이 끊겨도 이어집니다

상태가 대화가 아니라 파일에 있으므로, 새 세션에서 /pm <task_id> plan 확인을 호출하면 현재 상태를 그대로 보고합니다.

| works/<task_id>/에 있는 파일 | 재개 지점 | |---|---| | 없음 | 계획서 작성 | | plan.md (승인 회신 없음) | 사용자 검토 대기 | | plan.md (승인 회신 있음) | engineer부터 | | work-report.md | 완료된 작업 |

산출물

works/<task_id>/
  plan.md          pm   계획서 (사용자 승인 대상)
  work-report.md   pm   작업 보고서 (판정 · 증거 · 미검증 항목)

engineer와 qa는 파일을 만들지 않습니다. 보고는 응답으로만 하고 PM이 보고서로 옮깁니다. 저장소 문서(README 포함)는 어느 역할도 건드리지 않으며, 예외는 프로젝트 지침의 "3. 검증 항목" 명령 칸 기입 하나뿐입니다.

.gitignore는 건드리지 않으므로 works/를 커밋할지는 직접 결정하세요.

역할별 권한

| 역할 | 코드 수정 | 산출물 | 비고 | |---|---|---|---| | pm | ✗ | plan.md, work-report.md | 메인 세션의 역할 | | engineer | ✓ | 없음 (응답으로 보고) | git 커밋 / 푸시 금지 | | qa | ✗ | 없음 (응답으로 보고) | 쓰기 도구 없음. Cursor에서는 readonly: true |

• PM은 서브에이전트가 아니라 메인 세션의 역할입니다. /pm으로 진입하면 그 세션이 PM이 되어 둘에게 위임합니다. 중첩 위임에 의존하지 않으므로 세 도구에서 동일하게 동작합니다. 다만 계획서를 본인이 썼기 때문에 그대로 구현하고 싶어지는데, 도구 권한으로 이를 막을 수 없어 프롬프트 규율에 의존합니다. 그 선을 지키는 것이 이 워크플로우의 존재 이유입니다.
• task_id는 브랜치명의 마지막 / 뒤 토큰에서 자동 발급하고, 무엇으로 정했는지 밝히고 시작합니다. main / develop처럼 부적합하거나 git 저장소가 아니면 사용자에게 묻습니다.
• 재개발은 1회까지입니다. 같은 자리에서 두 번 실패했다면 계획이 틀렸다는 신호이고 계획 판단은 사용자의 몫이므로, 임의로 통과시키지 않고 판정: 미완으로 올립니다.

어느 진입점을 쓸까

| 작업 | 쓸지 여부 | 이유 | |---|---|---| | 범위 · 설계에 갈림길이 있다 | /pm | 결정 사항을 사용자 승인으로 확정하는 것이 이 워크플로우의 값어치입니다 | | 계획은 이미 섰고 구현만 남았다 | /pm <id> plan 작성 후 바로 engineer 진행 | 계획서가 검증 기준이 되므로 건너뛰지 않는 편이 낫습니다 | | 오타 수정, 한 줄 변경 | 아무것도 쓰지 않음 | 워크플로우 비용이 작업보다 큽니다 |

진입점은 /pm 하나뿐입니다. 단계별 커맨드를 따로 두지 않은 이유는, 같은 일을 하는 입구가 둘이면 어느 쪽이 게이트를 갖고 있는지 헷갈리기 때문입니다.

모델 변경

기본값은 부모 세션 모델 상속입니다. 특정 단계만 다른 모델로 돌리고 싶으면 생성된 파일을 직접 수정하세요.

| 도구 | 파일 | 수정 방법 | |---|---|---| | Claude Code | .claude/agents/<role>.md | model: inherit → opus / sonnet / haiku | | Cursor | .cursor/agents/<role>.md | model: inherit → 모델 ID | | Codex CLI | .codex/agents/<role>.toml | model = "..." 줄 추가 (필요 시 model_reasoning_effort 함께) |

각 파일에 안내 주석이 들어 있습니다. 예를 들어 qa는 저렴한 모델로, engineer는 추론이 강한 모델로 두는 구성이 일반적입니다.

커스터마이징

생성된 파일은 그대로 프로젝트에 커밋해 팀과 공유하는 것을 전제로 합니다. 역할 정의를 프로젝트에 맞게 수정해도 되고, 이 저장소의 preset/common/을 포크해 사내 표준 프리셋으로 만들어도 됩니다.

preset/common/
  base-rules.md          공통 행동 지침
  project-doc.md         프로젝트 지침 템플릿
  roles/{engineer,qa}.md         서브에이전트 정의 (도구 중립)
  commands/{pm,engineer,qa}.md   진입점 정의 (도구 중립)

역할 본문은 한 번만 작성하고, 도구별 메타데이터(tools, model, readonly, TOML 변환)는 src/targets/*.js가 처리합니다. {{PROJECT_DOC}} 같은 플레이스홀더는 대상별로 치환됩니다.

개발

node --test        # 테스트
node bin/cli.js claude --dry-run

라이선스

MIT