Community라이팅 & 에디팅github.com

MJL-ren/blindspot-audit - 블라인드 스팟 감사

프로젝트의 블라인드 스팟, 알려지지 않은 미지의 영역, 숨겨진 위험, 누락된 결정을 찾아내는 이식 가능한 AI 에이전트 스킬입니다. Claude Code, Codex, OpenCode에서 반복 감사를 지원하는 지속 가능한 원장(ledger)을 포함합니다.

blindspot-audit - 블라인드 스팟 감사란 무엇인가요?

Blindspot Audit은 소프트웨어 프로젝트의 '알려지지 않은 미지(unknown unknowns)'를 식별하여 구체적인 '알려진 미지(known unknowns)'로 전환하는 AI 에이전트 스킬입니다. 기존의 README나 TODO 파일은 프로젝트 소유자가 이미 알고 있는 내용만 담고 있기 때문에, AI도 동일한 블라인드 스팟을 상속받습니다. 이 스킬은 프로젝트 외부의 참조 프레임을 의도적으로 가져와서 그 간극을 측정합니다. Claude Code, Codex, OpenCode, CLI, 일반 채팅 등 다양한 호스트에서 동작하며, 각 플랫폼의 상호작용 방식에 맞춰 감사 결과를 제공합니다. 핵심 모델은 '네 가지 미지(known knowns, known unknowns, unknown knowns, unknown unknowns)' 프레임워크로, 발견된 항목을 분류하고 우선순위를 매깁니다. 또한 감사 결과는 프로젝트 수명 기간 동안 추적 가능하도록 지속 가능한 '블라인드 스팟 원장(ledger)'에 기록됩니다. 이 스킬의 가장 큰 가치는 프로젝트 소유자가 '그건 생각도 못 했어'라고 느끼게 하고, 동시에 무엇을 무시해도 안전한지 알게 해서 불안을 덜어주는 데 있습니다.

지원 대상✓Claude Code✓Codex CLI~Cursor✓OpenCode
npx skills add MJL-ren/blindspot-audit

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

블라인드 스팟 감사(Blindspot Audit)

목적

사용자가 그린 프로젝트 지도와 프로젝트의 실제 영역 사이의 간극을 찾아냅니다. 알려지지 않은 미지를 사용자가 검사하고, 답변하고, 테스트하거나 의도적으로 미룰 수 있는 구체적인 알려진 미지로 전환합니다.

프로젝트의 맥락은 스스로 선택됩니다. 소유자는 자신이 이미 알고 있는 내용만 적을 수 있기 때문에, 모든 README, TODO, 계획은 그들의 머릿속에 있는 지도를 인코딩합니다. 그리고 그 파일들을 기반으로 작업하는 AI는 동일한 블라인드 스팟을 물려받습니다. 이 감사는 의도적으로 프로젝트 외부의 참조 프레임을 가져와서 그 간극을 측정합니다.

이 스킬은 일반적인 품질 체크리스트가 아닙니다. 리포지토리나 제공된 아티팩트의 증거를 바탕으로, 이 특정 프로젝트에 대해, 이 특정 단계에서, 비정상적으로 중요한 것이 무엇인지 식별해야 합니다. 감사는 소유자가 적어도 한 번 "그건 생각도 못 했어"라고 말할 때 성공합니다. 그리고 그 후에 무엇을 안전하게 무시할 수 있는지도 알게 되어 더 차분해져야 합니다.

핵심 모델

네 가지 미지 프레임워크로 결과를 분류합니다.

  • 알려진 알려짐(Known knowns): 프롬프트, 문서, 코드, 계획에 이미 명시된 것.
  • 알려진 미지(Known unknowns): 문서, TODO, 계획, 주석, 사용자 표현에 이미 보이는 미해결 질문.
  • 알려지지 않은 알려짐(Unknown knowns): 사용자에게 보여주면 인식하지만, 아직 말이나 글로 표현하지 않은 것.
  • 알려지지 않은 미지(Unknown unknowns): 프로젝트 형태가 암시하는 누락된 개념, 숨겨진 제약 조건, 묻지 않은 질문.

이 프레임워크가 중요한 이유는 처방이 다르기 때문입니다. 알려지지 않은 알려짐은 강의가 아닌 체크리스트 한 줄이 필요합니다. 알려지지 않은 미지는 간단한 설명과 가장 저렴한 첫 번째 단계가 필요합니다. 좋은 결과물은 확실성을 주장하지 않습니다. 후보를 노출하고 가장 저렴한 다음 확인 방법을 제시합니다.

기본 규칙

이 규칙들은 이 스킬의 실패 모드가 "간극을 놓치는 것"이 아니라 "무시당하는 일반적인 체크리스트 잔소리가 되는 것"이기 때문에 존재합니다.

  1. 프로젝트 자체의 추적 문서는 필터이지, 발견의 원천이 아닙니다. README / TODO / 로드맵 / 체크리스트 / 이슈 목록에 이미 있는 것은 **알려진 미지(KNOWN unknown)**입니다. 절대 새로운 발견으로 보고하지 마세요. (현장 데이터: 이 필터는 일반적으로 후보 목록을 절반 이상 줄이며, 소유자가 보고서를 신뢰하는 주요 이유입니다.)
  2. 최상위 발견은 3-7개로 제한하고, 영향력 x 소유자가 진짜로 모를 가능성으로 순위를 매깁니다. 초과분은 짧은 "낮은 신호 감시 목록"이나 원장으로 보내며, 절대 메인 목록에 넣지 않습니다.
  3. 부재 자체만으로는 발견이 아닙니다. "당신에게 X가 없습니다"라는 것은 이 프로젝트에 대한 구체적인 결과와 그것을 해결하기 위한 가장 저렴한 첫 번째 단계를 명시할 수 있을 때만 유효합니다.
  4. 항상 두 가지 신뢰 섹션을 포함하세요. "확인 및 잘 커버됨"과 "지금은 건너뛰기 가능" (각 건너뛰기 항목에는 명시적인 재확인 트리거 포함). 이것들은 불안과 재스캔을 방지하며, 소유자가 보고서를 신뢰할 수 있다고 배우는 방법입니다.
  5. 규제 영역은 신중하게 다루세요. 법률, 세금 또는 규제 관련 발견의 경우, 발견한 내용과 출처를 밝히고, 전문가가 확인해야 한다고 명확히 말하세요. 당신은 정찰병이지, 변호사나 회계사가 아닙니다.

모드

  • quick: 문서와 프로젝트 인벤토리를 읽고, 최상위 블라인드 스팟을 반환합니다.
  • deep: 발견 순위를 매기기 전에 대표적인 코드 경로, 테스트, 설정, 문서를 검사합니다.
  • interview: 답변이 아키텍처, 워크플로우, 범위 또는 위험을 변경할 때 한 번에 한 가지 질문을 합니다.
  • post-implementation: 완료된 변경 사항, 노트, diff, 테스트를 비교하여 남아 있는 미지를 찾습니다.
  • planning: 구현 전에 데이터 모델, 인터페이스, UX 흐름, 운영 또는 검증을 변경할 가능성이 높은 결정을 표면화합니다.

사용자의 표현에서 모드를 유추하세요. 사용자가 지금 실행을 요청하면, 감사 경계를 유추하는 것이 불가능하지 않은 한 모드 질문을 하지 마세요.

빠른 시작

  1. 프로젝트 루트와 감사 경계를 식별합니다.
  2. 파일시스템 프로젝트를 사용할 수 있을 때 인벤토리 헬퍼를 실행합니다. 스크립트는 이 스킬의 폴더 안에 있습니다. 이 SKILL.md를 기준으로 경로를 확인하세요.
python <이-스킬-폴더>/scripts/project_inventory.py <프로젝트-루트> --format md

런타임 출력물, 생성된 보고서, 로그, 캐시된 아티팩트가 감사 질문의 일부인 경우에만 --include-generated를 사용하세요.

  1. 관련 참조 문서만 읽으세요.
    • references/archetypes.md: 프로젝트 유형과 예상 블라인드 스팟을 선택합니다.
    • references/lenses.md: 감사 렌즈를 도출하고 적용합니다.
    • references/host-surfaces.md: Claude Code, Codex, OpenCode, CLI, 또는 채팅 전용 표면에 맞게 질문과 출력을 조정합니다.
    • references/ledger-lifecycle.md: 지속 가능한 블라인드 스팟 원장을 발견, 생성, 전달 또는 업데이트합니다.
    • references/report-template.md: 결과 형식을 지정합니다.
  2. 블라인드 스팟 원장을 발견하거나 초기화합니다.
    • 이전 원장이 있으면 검색 전에 읽으세요 (Diff 실행 규칙 적용 - 원장 및 Diff 실행 섹션 참조).
    • 원장이 없고 호스트가 파일을 쓸 수 있으면, 사용자가 읽기 전용/채팅 전용 출력을 요청하지 않는 한 최적의 프로젝트 로컬 문서 위치에 BLINDSPOT_LEDGER.md를 생성합니다.
    • 원장이 없고 호스트가 파일을 쓸 수 없으면, 보고서에 제안된 경로와 첫 번째 원장 항목을 포함합니다.
  3. 인벤토리에서 가장 강력한 증거 파일을 검사합니다. README/AGENTS, 계획, 패키지 설정, 앱 진입점, 테스트 설정, CI, 환경 예제, 스키마, 프롬프트, 에이전트/스킬 파일, 런타임 문서.
  4. 호스트에 웹 액세스가 있으면 새 시각 외부 스캔을 실행합니다 (워크플로우 5단계 참조).
  5. 결과 순위를 매기고, 가능하면 소유자와 인터뷰하고, 보고서를 작성하고, 원장을 업데이트합니다.

호스트 표면 정책

감사 핵심은 Claude Code, Codex, OpenCode, CLI, 일반 채팅에서 동일하게 작동해야 합니다. 상호작용 스타일만 변경됩니다. 자세한 내용은 references/host-surfaces.md를 참조하세요.

  • 선택 가능 호스트 (Claude Code AskUserQuestion, OpenCode question): 결정이 아키텍처, 워크플로우, 범위 또는 위험을 변경할 때, 그리고 소유자 인식 인터뷰를 위해, 짧은 2-3 옵션 질문을 하나 하고 선택된 옵션을 보고서나 원장에 기록합니다.
  • Codex 또는 채팅 전용 호스트: 중요하지 않은 질문에 막히지 않습니다. 가장 안전한 되돌릴 수 있는 가정으로 계속 진행하고, 가정으로 표시하며, 사용자가 나중에 선택해야 할 옵션이 포함된 '결정 패킷(Decision packet)'을 포함합니다.
  • 웹 액세스가 없는 호스트: 새 시각 외부 스캔을 건너뛰고, 보고서에 명시적으로 언급하며, 시간에 민감한 영역(규제, 플랫폼 정책, 가격)을 훈련 지식에서 주장하지 않고 확인되지 않음으로 표시합니다.
  • 파일 쓰기 가능 호스트: 프로젝트 감사의 경우, 사용자가 읽기 전용/채팅 전용 출력을 요청하지 않는 한 기본적으로 원장을 생성하거나 업데이트합니다. 보고서에 경로와 라우팅 편집을 언급합니다.
  • 읽기 전용 또는 공개 공유 호스트: 사용자가 실행할 수 있는 명령/확인과 함께 이식 가능한 보고서를 반환합니다.

계속 진행하는 것이 위험하거나, 파괴적이거나, 비용이 많이 들거나, 오해의 소지가 있는 결과를 초래할 가능성이 있는 경우에만 즉시 질문하세요.

원장 및 Diff 실행

첫 번째 실행:

  1. references/ledger-lifecycle.md를 사용하여 BLINDSPOT_LEDGER.md의 최적의 지속 가능한 위치를 선택합니다.
  2. 파일 쓰기가 적절할 때 templates/BLINDSPOT_LEDGER.md에서 원장을 생성합니다.
  3. 해당 라우팅 파일이 이미 존재하는 경우, 운영 README, 문서 색인, 또는 인계 포인터와 같은 가장 가까운 라우팅 표면에 원장을 추가합니다.
  4. 감사 범위, 모드, 증거 범위, 첫 번째 발견 사항을 기록합니다.

프로젝트에 이미 블라인드 스팟 원장이 있는 경우:

  1. 원장을 입력으로 취급하되, 진실로 취급하지 마세요. 영향이 크거나 오래된 발견 사항을 현재 코드/문서와 다시 확인하세요.
  2. 출력을 new, changed, confirmed, downgraded, resolved, needs-decision으로 분류합니다.
  3. 변경되지 않은 보류 항목이 현재 목표를 방해하지 않는 한 반복하지 마세요. 이것이 반복 실행을 잔소리처럼 느껴지지 않고 진전처럼 느끼게 하는 방법입니다.
  4. 원장이 새롭지만 색인, 인계, 또는 운영 README에서 라우팅되지 않은 경우, 이를 발견 가능성 블라인드 스팟으로 플래그 지정합니다.
  5. 업데이트 시 원장의 로컬 상태 언어와 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. 새 시각 외부 스캔

호스트에 웹 액세스가 있으면 두 가지 질문에 대해 시간 제한을 두고 조사합니다.

  1. 이 카테고리의 건강한 프로젝트들이 현재 표준 장비로 간주하는 것은 무엇인가?
  2. 지난 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프로젝트 파일 구조 및 증거 수집

관련 스킬