| name | gap-find |
| description | 여러 독립 역할(보안/정합성/기능갭/운영 등)로 프로젝트를 병렬 심사해 취약점·결함·기능갭을 발굴하고, 승인 시 파일-클러스터 배타분리로 병렬 반영까지 닫는 스킬. "취약점 찾아줘", "개선할 기능 찾아줘", "레드팀 해줘", "gap find", "다역할로 감사해줘" 같은 요청에 발동. 코드가 없는 설계 문서 단계에서도 동작한다. |
| user_invocable | true |
| tags | ["security","audit","vulnerability","feature-gap","multi-agent","review"] |
| trigger | 취약점/개선기능 발굴 요청 / 여러 역할로 프로젝트 감사 / 코딩 착수 전 마지막 게이트 |
| version | 1 |
Gap Find
한 명의 심사역이 아니라 서로 다른 렌즈를 가진 N개 역할로 프로젝트를 병렬 심사해 취약점·정합성 결함·기능 갭을 발굴하고, 승인 시 반영까지 닫는다.
doc-health-audit(문서 자체의 위생)과 구분된다 — 이건 프로젝트의 실질적 결함/공백(보안·로직 정합성·로드맵 누락·운영 리스크)을 본다. 코드가 아직 없는 설계 단계에서도 동작한다 — 오히려 그때 발견 비용이 가장 싸다.
Use When
- "취약점 찾아줘", "개선할 기능 찾아줘", "레드팀 해줘" 류 요청 (1차 트리거)
- 큰 설계/구현 단계 완료 직후, 코딩 착수 전 마지막 게이트
- 한 명의 시각으로는 놓치는 게 많다고 의심될 때 (보안만 보면 기능갭을, 기능만 보면 운영 리스크를 놓친다)
- 발견한 결함을 그 자리에서 반영까지 원할 때
표준 역할 세트 (프로젝트에 맞게 조정)
| 역할 | 렌즈 | 반드시 다룸 | 피함 |
|---|
| 보안 레드팀 | 인가/인증/데이터 노출 공격 | RLS·인가 경계, 입력검증, 시크릿 관리 | 근거 없는 트집 |
| 정합성 감사 | 상태 전이·동시성·문서 간 모순 | 전이 완전성, 레이스 컨디션, 계약-머신 정합 | 문체 트집 |
| 기능 갭 헌터 | 로드맵/경쟁 대비 누락 시나리오 | 사용자 여정 커버리지, 기존 갭과 중복 확인 | ROI 없는 기능 남발 |
| 운영 회복탄력성 | 장애 대응·관찰가능성·확장성 | 장애 복구 경로, 모니터링 공백, 병목 | 현재 규모에 안 맞는 오버엔지니어링 |
역할 수·조합은 도메인에 맞게 바꾼다. 각 역할은 서로 겹치지 않는 파일/주제 스코프를 받아야 독립적인 결과가 나온다.
Steps
- Scope & Cluster(직접) — 역할별 담당 파일/문서를 배타적으로 분리. 코드가 없으면 설계문서(계약서/스펙/보안정책) 대상.
- Find(저가 모델, N역할 병렬) — lens/must_emphasize/avoid를 명확히 박은 프롬프트로 동시 실행. 발견마다
파일:라인 근거 + 구체 시나리오 + 제안 강제.
- Verify high-severity(직접) — P0/치명 발견은 원본을 직접 열어 대조. 서브에이전트의 "코드 버그" 판정이 실은 "범위 밖 설계 공백"일 수 있음 — 필요하면 원인 재해석. 여기는 절대 스킵 금지.
- Report + Approve — 심각도(P0/P1/P2) 순 표 1개로 끝. 산문과 중복 금지. 반영 범위(전부/일부/보류) 확인.
- Fix(고가 모델, 파일-클러스터 배타분리 병렬) — 승인 범위를 파일 겹침 없는 클러스터로 나눠 동시 반영. 허브 파일(INDEX·FEATURE-CONTRACT-MAP·GAP-MATRIX 등)은 단 하나의 클러스터만 소유, 나머지는 "무엇을 추가해야 하는지"만 보고.
- Verify(직접) — 기존 검증 도구(
npm run docs:check 등) 재실행. 신규 산출물이 기존 관례(candidate: 표기 등)와 맞는지 원본 대조. 허브 파일 등록 누락(예: docs/INDEX.md)은 직접 마무리.
클러스터링 규칙 (Fix 단계 무충돌 핵심)
- 클러스터는 파일 단위로 배타적이어야 한다 — 같은 파일을 두 클러스터가 동시에 쓰면 유실/충돌.
- 여러 발견이 같은 허브 파일(
GAP-MATRIX.md, FEATURE-SPEC.md, FEATURE-CONTRACT-MAP.md, STORE-DEPENDENCY-MATRIX.md, docs/INDEX.md)을 요구하면 한 클러스터에 몰아준다.
- 신규 계약서 추가로
npm run docs:check가 깨질 수 있는 클러스터는 그 클러스터 자신에게 최종 self-check를 맡긴다(다른 클러스터 병렬 편집 중이면 스킵하고 메인이 마지막에 한 번 더 돈다).
모델 등급
- Find 단계는 병렬화·비용 절감 목적이므로 저가 모델(Haiku)로 충분하다.
- Fix 단계 모델 등급은 전역 에이전트 모델 규칙을 따른다: 메인 모델이 상위급이면 직접/병렬화 목적으로만 서브에이전트, 하위급이면 사용자 요청 시 상위 모델(Opus)로 격상.
Verify
Failure / Fallback
- 허브 파일 경합이 많아 스코프 분리가 애매하면 클러스터 수를 줄이고 순차 실행으로 전환한다.
- Find 단계에서 셸 도구 환경 문제(예:
ls가 빈 결과 반환)로 오탐하면, 재실행 전 find로 직접 사실을 확인해 에이전트에게 주입한다.
- 발견이 실은 의도된 설계 범위 제한이면 "버그"로 반영하지 말고 "제한을 명시적으로 문서화 + GAP-MATRIX 추적 항목 등록"으로 전환한다.
참조 문서
docs/status/AGENT-OPS.md § 주간 보안 체크리스트 — 이 스킬의 보안 레드팀 역할과 연계docs/GAP-MATRIX.md — 기능 갭 헌터 역할이 참조/등록하는 로드맵
