실행 시점 (결정 규칙)
반사적으로 실행하지 말고, 상황에 따라 판단하세요. 상황별 실행 수준:
| 상황 | 실행할 항목 |
|---|---|
| 문서, 노트, 주석, 계획 또는 명세만 있는 경우 | 아무것도 하지 않음. 필요하지 않았다고 알리세요. |
| 작업 중간: 편집 사이, 수정 라운드, "타입이 깨졌나?" 확인 | 빠른 모드: node .claude/skills/verify-saas/driver.mjs --quick (또는 하나의 타입만 변경된 경우 해당 타입 명령어만) |
| 각 작업 또는 논리적 배치 끝, 커밋 전 | 전체 모드, 한 번 |
git push, 배포, 메인 브랜치 병합 전 | 전체 모드, 필수. 마지막 전체 실행이 올릴 커밋을 정확히 포함한다면 반복하지 마세요. |
새 마이그레이션, package.json 변경, 빌드 설정, 접근/인증 규칙 변경 | 전체 모드 해당 변경 끝에 (구조적 변경 위험) |
git pull 또는 다른 사람의 작업 병합 후 | 전체 모드 (기준선 재설정) |
절대:
- 변경 없이 두 번 연속 실행하지 않음;
- 첫 번째 실행 결과를 읽기 전에 두 번째 실행을 시작하지 않음;
- 동일 폴더에서 다른 빌드나 테스트와 병렬로 실행하지 않음;
- 라이브 조정 중에 전체 모드를 실행하지 않음 (커밋 요청을 기다리세요).
항상:
- 테스트가 테스트용 데이터베이스/환경을 가리키는지 확인하고, 프로덕션은 절대 안 됨 (README 경고 참조);
- 실행 전에 자신의 diff를 다시 읽을 것: 불필요한 import나 잘못된 속성명은 읽어서 잡을 수 있으며, 실행 시간을 낭비하지 않음;
- 종료 코드뿐 아니라 전체 보고서를 읽을 것.
실행 방법
프로젝트 루트에서:
node .claude/skills/verify-saas/driver.mjs # 전체 모드
node .claude/skills/verify-saas/driver.mjs --quick # 빠른 모드, 기준선을 건드리지 않음
node .claude/skills/verify-saas/driver.mjs --baseline # 현재 상태를 "좋은 상태"로 다시 캡처
프로젝트별 모든 설정(명령어, 폴더, 경고 단어, 켜거나 끈 단계)은 프로젝트 루트의 verify-saas.config.json에 있습니다. 이 파일이 없으면 Next.js + TypeScript + npm에 대한 기본값이 적용됩니다.
종료 코드: 0 = 악화된 것 없음; 1 = 무언가 악화되었거나 이미 깨진 상태(타입, 빌드 또는 테스트).
첫 사용: 프로젝트에 적용 (이것을 읽고 있는 에이전트용)
사용자가 방금 스킬을 설치하고 SaaS 프로젝트에 적용해 달라고 요청했다면, 다음 순서로 진행하세요:
- 프로젝트를 읽고 (
package.json또는 동등 파일, 마이그레이션 폴더, 테스트 실행 방법)verify-saas.config.json을 조정하세요: 타입, 린트, 빌드, 테스트 명령어,structure.migrationsDir,alertKeywords를 설정하세요. 프로젝트에 없는 것은 ("enabled": false)로 끄세요. - 비즈니스에서 깨지면 안 되는 것이 무엇인지 질문하세요 (중복되지 않은 일정, 음수로 떨어지지 않는 재고, 일치하는 잔액, 회사 A가 회사 B를 보지 못함, 결제가 두 번 수신되었지만 한 번만 적립...). 규칙을 임의로 만들지 말고 사용자와 확인한 후
docs/examples-by-niche.md를 모델로 테스트를 작성하세요. - 테스트 환경을 확인하세요. 절대 프로덕션에서 테스트를 실행하지 마세요. 테스트용 데이터베이스나 환경이 없으면 중단하고 사용자에게 알리세요.
- 그런 다음에만
node .claude/skills/verify-saas/driver.mjs --baseline을 실행하고 보고서를 보여주며, 이미 깨져 있던 것(부채)과 통과한 항목을 지적하세요. - 조정된 내용과 작성한 테스트를 사용자가 검토해야 한다고 알리세요.
보고서 읽는 법
순서대로:
- 타입: 통과/실패 및 기준선 대비 오류 수.
- 린트: 단순 개수가 아니라 지문(file:line:column:rule)으로 비교합니다. "이전 5개 오류, 이후 5개"는 서로 다른 5개의 오류를 숨길 수 있습니다. 기존 부채는 절대 당신 탓이 아닙니다. 새로운 오류만 중요합니다.
- 빌드: 통과/실패 및 라우트 목록(설정된 경우).
- 테스트: 기준선 대비 통과/실패.
- 구조: 새로 추가된 의존성, 제거된 의존성, 버전이 변경된 의존성; 새 마이그레이션은 경고 단어(보안/권한)를 포함하면 경고와 함께 표시됩니다.
기호: ✗ 회귀(수정 필요), ✓ 개선됨, = 변경 없음, ℹ 정보, ⚠ 의도적인지 확인.
출력 후 전체 모드는 기준선을 현재 상태로 덮어씁니다. 따라서 회귀를 먼저 수정한 후 다시 실행하세요. 그렇지 않으면 두 번째 실행이 오류를 "기존 부채"로 처리합니다.
모범 사례
- 기준선(
verify-saas.baseline.json)은 프로젝트에 커밋되어야 합니다. 그래야 세션과 머신 간에 "마지막 이후" 비교가 작동합니다. - 프로젝트 처음 사용 시: 좋은 상태라고 알고 있는 상태에서
--baseline으로 실행하세요. - 마이그레이션은 파일 이름만으로 비교됩니다. 스킬은 SQL을 적용하거나 검증하지 않습니다. 새로운 마이그레이션이 나타났고 보안과 관련된 경우 알림만 제공합니다.
- 스킬은 의존성을 설치하지 않습니다 (
npm install은 검증이 단독으로 수행하기에는 너무 큰 작업입니다). - 보고서에 "새로운" 문제가 표시되었는데 본인이 발생시키지 않은 경우, 실행 사이에 누군가 리포지토리를 변경했는지 확인하세요 (
git log -3 --oneline). - 진정한 보호는 사용자가 작성한 테스트에서 옵니다 (
docs/examples-by-niche.md참조). 스킬은 테스트가 실행되고 변경 사항이 알림되도록 보장할 뿐입니다.