블라인드 스팟 감사(Blindspot Audit)
목적
사용자가 그린 프로젝트 지도와 프로젝트의 실제 영역 사이의 간극을 찾아냅니다. 알려지지 않은 미지를 사용자가 검사하고, 답변하고, 테스트하거나 의도적으로 미룰 수 있는 구체적인 알려진 미지로 전환합니다.
프로젝트의 맥락은 스스로 선택됩니다. 소유자는 자신이 이미 알고 있는 내용만 적을 수 있기 때문에, 모든 README, TODO, 계획은 그들의 머릿속에 있는 지도를 인코딩합니다. 그리고 그 파일들을 기반으로 작업하는 AI는 동일한 블라인드 스팟을 물려받습니다. 이 감사는 의도적으로 프로젝트 외부의 참조 프레임을 가져와서 그 간극을 측정합니다.
이 스킬은 일반적인 품질 체크리스트가 아닙니다. 리포지토리나 제공된 아티팩트의 증거를 바탕으로, 이 특정 프로젝트에 대해, 이 특정 단계에서, 비정상적으로 중요한 것이 무엇인지 식별해야 합니다. 감사는 소유자가 적어도 한 번 "그건 생각도 못 했어"라고 말할 때 성공합니다. 그리고 그 후에 무엇을 안전하게 무시할 수 있는지도 알게 되어 더 차분해져야 합니다.
핵심 모델
네 가지 미지 프레임워크로 결과를 분류합니다.
- 알려진 알려짐(Known knowns): 프롬프트, 문서, 코드, 계획에 이미 명시된 것.
- 알려진 미지(Known unknowns): 문서, TODO, 계획, 주석, 사용자 표현에 이미 보이는 미해결 질문.
- 알려지지 않은 알려짐(Unknown knowns): 사용자에게 보여주면 인식하지만, 아직 말이나 글로 표현하지 않은 것.
- 알려지지 않은 미지(Unknown unknowns): 프로젝트 형태가 암시하는 누락된 개념, 숨겨진 제약 조건, 묻지 않은 질문.
이 프레임워크가 중요한 이유는 처방이 다르기 때문입니다. 알려지지 않은 알려짐은 강의가 아닌 체크리스트 한 줄이 필요합니다. 알려지지 않은 미지는 간단한 설명과 가장 저렴한 첫 번째 단계가 필요합니다. 좋은 결과물은 확실성을 주장하지 않습니다. 후보를 노출하고 가장 저렴한 다음 확인 방법을 제시합니다.
기본 규칙
이 규칙들은 이 스킬의 실패 모드가 "간극을 놓치는 것"이 아니라 "무시당하는 일반적인 체크리스트 잔소리가 되는 것"이기 때문에 존재합니다.
- 프로젝트 자체의 추적 문서는 필터이지, 발견의 원천이 아닙니다. README / TODO / 로드맵 / 체크리스트 / 이슈 목록에 이미 있는 것은 **알려진 미지(KNOWN unknown)**입니다. 절대 새로운 발견으로 보고하지 마세요. (현장 데이터: 이 필터는 일반적으로 후보 목록을 절반 이상 줄이며, 소유자가 보고서를 신뢰하는 주요 이유입니다.)
- 최상위 발견은 3-7개로 제한하고, 영향력 x 소유자가 진짜로 모를 가능성으로 순위를 매깁니다. 초과분은 짧은 "낮은 신호 감시 목록"이나 원장으로 보내며, 절대 메인 목록에 넣지 않습니다.
- 부재 자체만으로는 발견이 아닙니다. "당신에게 X가 없습니다"라는 것은 이 프로젝트에 대한 구체적인 결과와 그것을 해결하기 위한 가장 저렴한 첫 번째 단계를 명시할 수 있을 때만 유효합니다.
- 항상 두 가지 신뢰 섹션을 포함하세요. "확인 및 잘 커버됨"과 "지금은 건너뛰기 가능" (각 건너뛰기 항목에는 명시적인 재확인 트리거 포함). 이것들은 불안과 재스캔을 방지하며, 소유자가 보고서를 신뢰할 수 있다고 배우는 방법입니다.
- 규제 영역은 신중하게 다루세요. 법률, 세금 또는 규제 관련 발견의 경우, 발견한 내용과 출처를 밝히고, 전문가가 확인해야 한다고 명확히 말하세요. 당신은 정찰병이지, 변호사나 회계사가 아닙니다.
모드
quick: 문서와 프로젝트 인벤토리를 읽고, 최상위 블라인드 스팟을 반환합니다.deep: 발견 순위를 매기기 전에 대표적인 코드 경로, 테스트, 설정, 문서를 검사합니다.interview: 답변이 아키텍처, 워크플로우, 범위 또는 위험을 변경할 때 한 번에 한 가지 질문을 합니다.post-implementation: 완료된 변경 사항, 노트, diff, 테스트를 비교하여 남아 있는 미지를 찾습니다.planning: 구현 전에 데이터 모델, 인터페이스, UX 흐름, 운영 또는 검증을 변경할 가능성이 높은 결정을 표면화합니다.
사용자의 표현에서 모드를 유추하세요. 사용자가 지금 실행을 요청하면, 감사 경계를 유추하는 것이 불가능하지 않은 한 모드 질문을 하지 마세요.
빠른 시작
- 프로젝트 루트와 감사 경계를 식별합니다.
- 파일시스템 프로젝트를 사용할 수 있을 때 인벤토리 헬퍼를 실행합니다. 스크립트는 이 스킬의 폴더 안에 있습니다. 이 SKILL.md를 기준으로 경로를 확인하세요.
python <이-스킬-폴더>/scripts/project_inventory.py <프로젝트-루트> --format md
런타임 출력물, 생성된 보고서, 로그, 캐시된 아티팩트가 감사 질문의 일부인 경우에만 --include-generated를 사용하세요.
- 관련 참조 문서만 읽으세요.
references/archetypes.md: 프로젝트 유형과 예상 블라인드 스팟을 선택합니다.references/lenses.md: 감사 렌즈를 도출하고 적용합니다.references/host-surfaces.md: Claude Code, Codex, OpenCode, CLI, 또는 채팅 전용 표면에 맞게 질문과 출력을 조정합니다.references/ledger-lifecycle.md: 지속 가능한 블라인드 스팟 원장을 발견, 생성, 전달 또는 업데이트합니다.references/report-template.md: 결과 형식을 지정합니다.
- 블라인드 스팟 원장을 발견하거나 초기화합니다.
- 이전 원장이 있으면 검색 전에 읽으세요 (Diff 실행 규칙 적용 - 원장 및 Diff 실행 섹션 참조).
- 원장이 없고 호스트가 파일을 쓸 수 있으면, 사용자가 읽기 전용/채팅 전용 출력을 요청하지 않는 한 최적의 프로젝트 로컬 문서 위치에
BLINDSPOT_LEDGER.md를 생성합니다. - 원장이 없고 호스트가 파일을 쓸 수 없으면, 보고서에 제안된 경로와 첫 번째 원장 항목을 포함합니다.
- 인벤토리에서 가장 강력한 증거 파일을 검사합니다. README/AGENTS, 계획, 패키지 설정, 앱 진입점, 테스트 설정, CI, 환경 예제, 스키마, 프롬프트, 에이전트/스킬 파일, 런타임 문서.
- 호스트에 웹 액세스가 있으면 새 시각 외부 스캔을 실행합니다 (워크플로우 5단계 참조).
- 결과 순위를 매기고, 가능하면 소유자와 인터뷰하고, 보고서를 작성하고, 원장을 업데이트합니다.
호스트 표면 정책
감사 핵심은 Claude Code, Codex, OpenCode, CLI, 일반 채팅에서 동일하게 작동해야 합니다. 상호작용 스타일만 변경됩니다. 자세한 내용은 references/host-surfaces.md를 참조하세요.
- 선택 가능 호스트 (Claude Code
AskUserQuestion, OpenCodequestion): 결정이 아키텍처, 워크플로우, 범위 또는 위험을 변경할 때, 그리고 소유자 인식 인터뷰를 위해, 짧은 2-3 옵션 질문을 하나 하고 선택된 옵션을 보고서나 원장에 기록합니다. - Codex 또는 채팅 전용 호스트: 중요하지 않은 질문에 막히지 않습니다. 가장 안전한 되돌릴 수 있는 가정으로 계속 진행하고, 가정으로 표시하며, 사용자가 나중에 선택해야 할 옵션이 포함된 '결정 패킷(Decision packet)'을 포함합니다.
- 웹 액세스가 없는 호스트: 새 시각 외부 스캔을 건너뛰고, 보고서에 명시적으로 언급하며, 시간에 민감한 영역(규제, 플랫폼 정책, 가격)을 훈련 지식에서 주장하지 않고 확인되지 않음으로 표시합니다.
- 파일 쓰기 가능 호스트: 프로젝트 감사의 경우, 사용자가 읽기 전용/채팅 전용 출력을 요청하지 않는 한 기본적으로 원장을 생성하거나 업데이트합니다. 보고서에 경로와 라우팅 편집을 언급합니다.
- 읽기 전용 또는 공개 공유 호스트: 사용자가 실행할 수 있는 명령/확인과 함께 이식 가능한 보고서를 반환합니다.
계속 진행하는 것이 위험하거나, 파괴적이거나, 비용이 많이 들거나, 오해의 소지가 있는 결과를 초래할 가능성이 있는 경우에만 즉시 질문하세요.
원장 및 Diff 실행
첫 번째 실행:
references/ledger-lifecycle.md를 사용하여BLINDSPOT_LEDGER.md의 최적의 지속 가능한 위치를 선택합니다.- 파일 쓰기가 적절할 때
templates/BLINDSPOT_LEDGER.md에서 원장을 생성합니다. - 해당 라우팅 파일이 이미 존재하는 경우, 운영 README, 문서 색인, 또는 인계 포인터와 같은 가장 가까운 라우팅 표면에 원장을 추가합니다.
- 감사 범위, 모드, 증거 범위, 첫 번째 발견 사항을 기록합니다.
프로젝트에 이미 블라인드 스팟 원장이 있는 경우:
- 원장을 입력으로 취급하되, 진실로 취급하지 마세요. 영향이 크거나 오래된 발견 사항을 현재 코드/문서와 다시 확인하세요.
- 출력을
new,changed,confirmed,downgraded,resolved,needs-decision으로 분류합니다. - 변경되지 않은 보류 항목이 현재 목표를 방해하지 않는 한 반복하지 마세요. 이것이 반복 실행을 잔소리처럼 느껴지지 않고 진전처럼 느끼게 하는 방법입니다.
- 원장이 새롭지만 색인, 인계, 또는 운영 README에서 라우팅되지 않은 경우, 이를 발견 가능성 블라인드 스팟으로 플래그 지정합니다.
- 업데이트 시 원장의 로컬 상태 언어와 ID를 유지합니다.
좋은 원장은 미래 감사 비용을 낮춥니다. 나쁜 원장은 또 다른 숨겨진 문서가 되므로, 항상 발견 가능성을 확인하세요.
검색 위생
제한된 검색을 사용하세요. 블라인드 스팟 감사는 종종 광범위한 리포지토리를 다루며, 노이즈가 많은 생성 파일은 잘못된 확신을 주거나 컨텍스트를 낭비할 수 있습니다.
rg 및 유사한 도구의 기본 제외 항목 (감사가 해당 영역을 명시적으로 대상으로 하지 않는 한):
!.git/**
!node_modules/**
!.venv/**
!dist/**
!build/**
!runtime/**
!external_repos/**
!vendor/**
!docs/archive/**
!docs/research/**
!docs/sources/**
!data/external/raw/**
리포지토리 전체 스캔보다는 대상 경로와 --glob 제외를 선호하세요. 광범위한 스캔이 거대한 생성 파일을 반환하면 중단하고 결과를 사용하기 전에 더 좁은 경계로 다시 실행하세요.
워크플로우
1. 지도 정의
사용자의 명백한 목표, 프로젝트 유형, 성숙도, 감사 경계를 2-4줄로 명시합니다. 가정을 명시적으로 표시합니다. 소유자 프로필을 포함합니다.
- 개인인가 팀인가? 소유자가 명백히 전문가인 영역은 무엇이며, 더 유용하게는 전문가가 아닌 영역은 무엇인가? 블라인드 스팟은 소유자의 비전문 영역에 집중되므로, 해당 렌즈에 가중치를 두세요.
- 취미인가 상업적인가? 비공개인가 공개인가? 상업적 또는 공개적 의도는 비공개 취미 프로젝트에게는 순수한 노이즈가 될 법률, 세금, 시장 렌즈를 활성화합니다. 의도를 파일에서 읽을 수 없으면 스캔 전에 물어보세요 (짧은 질문 하나). 의도를 잘못 추측하면 감사 전체가 낭비됩니다.
2. 증거 수집
인벤토리 헬퍼와 대상 읽기를 사용합니다. 프로젝트의 자기 인식 표면(README, TODO, 로드맵, 체크리스트, 설계 문서, 개요/요약)을 먼저 읽으세요. 이것들은 최고의 프로필 소스이자 노이즈 필터입니다 (기본 규칙 1). 광범위한 추측보다 증거를 선호합니다. 증거를 다음과 같이 태그하세요.
- observed: 파일이나 출력물에 직접 존재함.
- absent: 검사된 범위에서 예상되는 아티팩트를 찾을 수 없음.
- inferred: 구조, 명명 규칙, 관례에서 추론됨.
- question: 사용자 또는 도메인 소유자의 확인 필요.
3. 영역 분류
references/archetypes.md에서 하나 이상의 아키타입을 선택합니다. 프로젝트가 하이브리드인 경우 하나의 범주에 강제로 맞추지 마세요.
4. 렌즈 실행
프로젝트 단계에 맞는 렌즈만 적용하세요. 프로토타입에 엔터프라이즈 규정 준수가 필요하지는 않지만, 데이터 손실 경계, 비밀 처리, 복구 가능성은 여전히 필요할 수 있습니다.
5. 새 시각 외부 스캔
호스트에 웹 액세스가 있으면 두 가지 질문에 대해 시간 제한을 두고 조사합니다.
- 이 카테고리의 건강한 프로젝트들이 현재 표준 장비로 간주하는 것은 무엇인가?
- 지난 6-12개월 동안 이 프로젝트의 문서가 절대 포함할 수 없는 것(규제, 플랫폼 정책, 시장 또는 장르 관례, 도구) 중 무엇이 변경되었는가?
질문 2는 불균형적으로 가치가 높습니다. 시간 의존적 변화는 리포지토리와 소유자의 기억 모두에 구조적으로 보이지 않습니다. (현장 데이터: 초기 실행에서 가장 영향력이 컸던 발견들 - 다음 달 시행되는 AI 콘텐츠 라벨링 법률, 문서화된 계획을 무효화한 결제 공급자 인수 - 모두 이 단계에서 나왔습니다.) 여기서 찾은 내용에는 출처를 인용하세요. 웹 액세스 없이 건너뛰고 공개합니다 (호스트 표면 정책 참조).
6. 블라인드 스팟을 확인 사항으로 전환
모든 발견에 대해 다음을 포함합니다.
- 무엇이 누락되었을 수 있는가.
- 이 프로젝트에 왜 중요한가.
- 증거.
- 가장 저렴한 다음 확인.
- 예상 소유자 또는 결정 표면.
- 우선 순위: now, next, later, watch.
- 신뢰도: high, medium, low.
프로젝트 자체 추적 문서에 나타나는 후보는 삭제하고 (기본 규칙 1), 상위 3-7개를 유지하며, 나머지는 감시 목록이나 원장으로 옮깁니다.
7. 소유자 인터뷰
발견 사항을 제시한 후, 소유자가 이미 알고 있었던 것을 묻습니다 (선택 가능 호스트에서 하나의 다중 선택 질문이 잘 작동합니다). 각 발견을 분류합니다.
| 인식 | 의미 | 처방 |
|---|---|---|
unknown_unknown | 소유자가 몰랐음 | 여기서 왜 중요한지 설명 + 가장 저렴한 첫 번째 단계 |
unknown_known | 소유자는 알았지만, 어디에도 기록되지 않음 | 해결책은 구현이 아닌 문서화입니다. 에이전트와 향후 세션이 볼 수 있도록 추적 문서에 넣으세요 |
deliberate_skip | 소유자가 고려하고 선택하지 않음 | 이유와 재확인 트리거와 함께 건너뛰기 목록으로 이동 |
(현장 데이터: 초기 실행에서 상위 발견의 약 절반이 unknown_known으로 판명되었습니다. 즉, 리포지토리에는 실제 간극이 있지만 소유자의 머릿속에는 없었습니다. 이 구분은 후속 조치를 완전히 바꿉니다.)
질문할 수 없는 호스트에서는 모든 인식 값을 unconfirmed로 표시하고, 인터뷰 질문을 보고서에 포함시키며, 미해결 결정은 Decision packet에 넣습니다.
8. 출력을 유용하게 유지
가장 신호가 강한 블라인드 스팟으로 시작합니다. 항상 두 가지 신뢰 섹션을 포함합니다 (기본 규칙 4). 보고서와 원장 본문은 소유자가 대화에서 사용하는 언어로 작성하세요. ID, 상태, 인식 값은 세션과 언어 간 diff를 유지할 수 있도록 영어로 유지합니다. references/report-template.md에 따라 형식을 지정합니다.
가드레일
- 프로젝트 증거가 관련성을 만들지 않는 한 일반적인 모범 사례를 발견으로 제시하지 마세요.
- 원장이나 프로젝트 자체 추적 문서에 이미 있는 항목을 다시 보고하지 마세요.
- 개인 실험이나 초기 프로토타입에 대해 과도한 프로세스를 요구하지 마세요.
- 사용자가 명시적으로 수정을 요청하지 않는 한 코드를 변경하지 마세요.
- 파일이 없다는 이유만으로 무언가가 고장 났다고 주장하지 마세요. 부재가 암시하는 것과 확인 방법을 말하세요.
- 부재하는 CI, 테스트, 릴리스 문서, 배포 파일은 프로젝트가 반복 가능한 전달, 공유 인계, 프로덕션 수준의 안정성을 주장할 때만 블라인드 스팟으로 취급하세요. 개인 노트와 초기 프로토타입에는 필요하지 않을 수 있습니다.
- 가능한 모든 위험으로 사용자를 압도하지 마세요. 프로젝트 적합성, 피해 반경, 되돌릴 수 있는 정도, 가능성으로 순위를 매기세요.
- 사용자가 해당 도메인에 비전문가인 경우, 익숙하지 않은 블라인드 스팟에 대한 짧은 교육 노트를 포함하세요.
- 발견 사항이 현재 외부 플랫폼 동작에 의존하는 경우, 사실로 취급하기 전에 공식 문서나 최신 연구로 확인하세요. 웹 액세스 없이 추정되는 사실로 제시하지 말고, 확인되지 않음으로 표시하세요.
참조
참조 문서는 이 스킬의 references/ 디렉토리에 있습니다.
| 파일 | 목적 |
|---|---|
archetypes.md | 프로젝트 유형별 예상 블라인드 스팟 |
lenses.md | 블라인드 스팟 발견을 위한 감사 렌즈 |
host-surfaces.md | 호스트별 상호작용 및 출력 적응 |
ledger-lifecycle.md | 원장 생성, 업데이트, 발견 |
report-template.md | 감사 보고서 형식 템플릿 |
템플릿
| 파일 | 목적 |
|---|---|
templates/BLINDSPOT_LEDGER.md | 새로운 블라인드 스팟 원장을 위한 템플릿 |
스크립트
| 파일 | 목적 |
|---|---|
scripts/project_inventory.py | 프로젝트 파일 구조 및 증거 수집 |