Communitygithub.com

tangjuyo/reels-blocker

태스크 생성 후 spec.md, plan.md, tasks.md 간의 비파괴적 교차 아티팩트 일관성 및 품질 분석을 수행합니다.

reels-blocker란 무엇인가요?

이 스킬은 `spec.md`, `plan.md`, `tasks.md` 세 가지 핵심 아티팩트 간의 일관성과 품질을 비파괴적으로 분석하는 AI 에이전트 명령입니다. 주로 Claude Code, Cursor, Codex와 같은 AI 코딩 에이전트에서 사용되며, 구현 전에 요구사항 중복, 모호성, 미지정 항목, 헌법(constitution) 위반, 적용 범위(gap) 문제를 체계적으로 식별합니다. 분석은 읽기 전용(read-only)으로 진행되며, 결과는 구조화된 Markdown 보고서 형태로 출력되고 사용자 승인 후에만 수정 제안이 제공됩니다. `.specify/extensions.yml` 파일을 통해 확장 훅을 지원하며, 분석 전후로 선택적 또는 필수 훅을 실행할 수 있어 유연한 워크플로우 통합이 가능합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tangjuyo/reels-blocker/tree/HEAD/.claude/skills/speckit-analyze

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

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

문서

사용자 입력

$ARGUMENTS

진행하기 전에 사용자 입력을 반드시 고려해야 합니다(비어 있지 않은 경우).

사전 실행 검사

확장 훅 확인 (분석 전):

  • 프로젝트 루트에 .specify/extensions.yml이 있는지 확인합니다.
  • 존재하는 경우, hooks.before_analyze 키 아래의 항목을 읽습니다.
  • YAML을 구문 분석할 수 없거나 유효하지 않은 경우, 조용히 넘어가지 않고 .specify/extensions.yml을 읽을 수 없다고 사용자에게 알리고(구문 분석 오류 포함), 등록된 필수(optional: false) 훅을 포함한 어떤 훅도 확인되지 않았음을 알린 후 정상적으로 계속 진행합니다.
  • enabled가 명시적으로 false인 훅은 필터링합니다. enabled 필드가 없는 훅은 기본적으로 활성화된 것으로 간주합니다.
  • 나머지 각 훅에 대해, 훅 condition 표현식을 해석하거나 평가하려고 시도하지 마십시오:
    • 훅에 condition 필드가 없거나 null/비어 있으면, 훅을 실행 가능한 것으로 처리합니다.
    • 훅이 비어 있지 않은 condition을 정의하는 경우, 해당 훅은 건너뛰고 조건 평가는 HookExecutor 구현에 맡깁니다.
  • 훅 명령 이름에서 점(.)을 하이픈(-)으로 바꾸어 명령 호출을 구성합니다. 예를 들어, speckit.git.commit → /speckit-git-commit이 됩니다.
  • 각 실행 가능한 훅에 대해, optional 플래그에 따라 다음을 출력합니다:
    • 선택적 훅 (optional: true):
      ## 확장 훅
      
      **선택적 사전 훅**: {extension}
      명령어: `/{command}`
      설명: {description}
      
      프롬프트: {prompt}
      실행하려면: `/{command}`
      
    • 필수 훅 (optional: false):
      ## 확장 훅
      
      **자동 사전 훅**: {extension}
      실행 중: `/{command}`
      EXECUTE_COMMAND: {command}
      
      훅 명령의 결과를 기다린 후 목표를 진행하세요.
      
      위 블록을 출력한 후에는 실제로 훅을 호출하고 완료될 때까지 기다려야 합니다. 이 에이전트/세션에서 직접 명령을 실행하는 것과 같은 방식으로 실행하십시오(호출 방식은 위에 표시된 리터럴 {command} ID와 다를 수 있습니다. 예를 들어, skills 모드 에이전트는 /skill:speckit-... 또는 $speckit-...로 실행합니다). 블록만 출력하는 것으로는 훅이 실행되지 않습니다.
  • 등록된 훅이 없거나 .specify/extensions.yml이 존재하지 않으면, 조용히 건너뜁니다.

목표

구현 전에 세 가지 핵심 아티팩트(spec.md, plan.md, tasks.md)에서 불일치, 중복, 모호성, 미지정 항목을 식별합니다. 이 명령은 /speckit-tasks가 완전한 tasks.md를 성공적으로 생성한 후에만 실행되어야 합니다.

운영 제약 조건

엄격히 읽기 전용: 파일을 수정하지 마십시오. 구조화된 분석 보고서를 출력합니다. 선택적 수정 계획을 제공합니다(사용자가 명시적으로 승인한 후에만 후속 편집 명령이 수동으로 호출될 수 있습니다).

헌법 권한: 프로젝트 헌법(.specify/memory/constitution.md)은 이 분석 범위 내에서 불가침입니다. 헌법 충돌은 자동으로 중요(CRITICAL)하며, spec, plan 또는 tasks의 조정이 필요합니다—원칙의 약화, 재해석 또는 묵시적 무시가 아닙니다. 원칙 자체를 변경해야 하는 경우, /speckit-analyze 외부에서 별도의 명시적 헌법 업데이트로 이루어져야 합니다.

실행 단계

1. 분석 컨텍스트 초기화

.specify/scripts/bash/check-prerequisites.sh --json --require-spec --require-tasks --include-tasks를 저장소 루트에서 한 번 실행하고 JSON을 파싱하여 FEATURE_DIR과 AVAILABLE_DOCS를 가져옵니다. 절대 경로를 도출합니다:

  • SPEC = FEATURE_DIR/spec.md
  • PLAN = FEATURE_DIR/plan.md
  • TASKS = FEATURE_DIR/tasks.md

필요한 파일이 없으면 오류 메시지와 함께 중단합니다(사용자에게 누락된 사전 조건 명령을 실행하도록 안내). "I'm Groot"와 같이 인수에 작은따옴표가 있는 경우 이스케이프 구문을 사용하세요: 예: 'I'''m Groot' (또는 가능하면 큰따옴표 사용: "I'm Groot").

2. 아티팩트 로드 (점진적 공개)

각 아티팩트에서 필요한 최소한의 컨텍스트만 로드합니다:

spec.md에서:

  • 개요/컨텍스트
  • 기능 요구사항
  • 성공 기준 (측정 가능한 결과 — 예: 성능, 보안, 가용성, 사용자 성공, 비즈니스 영향)
  • 사용자 스토리
  • 엣지 케이스 (있는 경우)

plan.md에서:

  • 아키텍처/스택 선택
  • 데이터 모델 참조
  • 단계
  • 기술적 제약 조건

tasks.md에서:

  • 작업 ID
  • 설명
  • 단계 그룹화
  • 병렬 마커 [P]
  • 참조된 파일 경로

헌법에서:

  • .specify/memory/constitution.md에서 원칙 검증을 위해 로드

3. 의미 모델 구축

내부 표현을 생성합니다(출력에 원시 아티팩트를 포함하지 마십시오):

  • 요구사항 인벤토리: 각 기능 요구사항(FR-###) 및 성공 기준(SC-###)에 대해 안정적인 키를 기록합니다. 있는 경우 명시적 FR-/SC- 식별자를 기본 키로 사용하고, 가독성을 위해 명령형 구문 슬러그도 선택적으로 도출합니다(예: "사용자가 파일을 업로드할 수 있음" → user-can-upload-file). 빌드 가능한 작업이 필요한 성공 기준 항목(예: 부하 테스트 인프라, 보안 감사 도구)만 포함하고, 출시 후 결과 메트릭 및 비즈니스 KPI(예: "지원 티켓 50% 감소")는 제외합니다.
  • 사용자 스토리/행동 인벤토리: 승인 기준이 있는 개별 사용자 행동
  • 작업 적용 범위 매핑: 각 작업을 하나 이상의 요구사항 또는 스토리에 매핑합니다(키워드 / ID와 같은 명시적 참조 패턴 또는 핵심 구문을 통한 추론).
  • 헌법 규칙 집합: 원칙 이름과 MUST/SHOULD 규범적 진술문을 추출합니다.

4. 탐지 패스 (토큰 효율적 분석)

고신호 발견에 집중합니다. 총 50개로 제한하며, 나머지는 오버플로 요약에 통합합니다.

A. 중복 탐지

  • 유사 중복 요구사항 식별
  • 통합을 위해 품질이 낮은 표현에 표시

B. 모호성 탐지

  • 측정 가능한 기준이 없는 모호한 형용사(빠른, 확장 가능한, 안전한, 직관적인, 견고한 등) 표시
  • 해결되지 않은 플레이스홀더(TODO, TKTK, ???, <placeholder> 등) 표시

C. 미지정

  • 동사는 있지만 목적어나 측정 가능한 결과가 없는 요구사항
  • 승인 기준 정렬이 누락된 사용자 스토리
  • spec/plan에 정의되지 않은 파일이나 컴포넌트를 참조하는 작업

D. 헌법 정렬

  • MUST 원칙과 충돌하는 모든 요구사항 또는 계획 요소
  • 헌법에서 요구하는 필수 섹션 또는 품질 게이트 누락

E. 적용 범위 격차

  • 연결된 작업이 없는 요구사항
  • 매핑된 요구사항/스토리가 없는 작업
  • 작업에 반영되지 않은 빌드 가능한 작업이 필요한 성공 기준(성능, 보안, 가용성)

F. 불일치

  • 용어 변화 (동일한 개념이 파일마다 다르게 명명됨)
  • plan에서 참조되지만 spec에는 없는 데이터 엔터티(또는 그 반대)
  • 작업 순서 모순 (예: 종속성 없이 기초 설정 작업 전에 통합 작업)
  • 충돌하는 요구사항 (예: 하나는 Next.js를 요구하고 다른 하나는 Vue를 지정)

5. 심각도 할당

다음 휴리스틱을 사용하여 발견에 우선순위를 지정합니다:

  • CRITICAL: 헌법 MUST 위반, 핵심 spec 아티팩트 누락, 또는 기본 기능을 차단하는 적용 범위가 0인 요구사항
  • HIGH: 중복 또는 충돌하는 요구사항, 모호한 보안/성능 속성, 테스트 불가능한 승인 기준
  • MEDIUM: 용어 변화, 누락된 비기능적 작업 적용 범위, 미지정된 엣지 케이스
  • LOW: 스타일/문구 개선, 실행 순서에 영향을 주지 않는 사소한 중복

6. 간결한 분석 보고서 생성

다음 구조의 Markdown 보고서를 출력합니다(파일 쓰기 없음):

사양 분석 보고서

ID카테고리심각도위치요약권장 사항
A1중복HIGHspec.md:L120-134두 개의 유사한 요구사항 ...병합; 더 명확한 버전 유지

(발견당 한 행씩 추가; 카테고리 이니셜을 접두사로 하는 안정적인 ID 생성)

적용 범위 요약 표:

요구사항 키작업 있음?작업 ID비고

헌법 정렬 문제: (있는 경우)

매핑되지 않은 작업: (있는 경우)

메트릭:

  • 총 요구사항 수
  • 총 작업 수
  • 적용 범위 % (>=1개 작업이 있는 요구사항)
  • 모호성 개수
  • 중복 개수
  • 중요 이슈 개수

7. 다음 작업 제공

보고서 마지막에 간결한 다음 작업 블록을 출력합니다:

  • CRITICAL 이슈가 있는 경우: /speckit-implement 전에 해결 권장
  • LOW/MEDIUM만 있는 경우: 사용자는 계속 진행할 수 있지만 개선 제안 제공
  • 명시적 명령 제안 제공: 예: "정제를 위해 /speckit-specify 실행", "아키텍처 조정을 위해 /speckit-plan 실행", "수동으로 tasks.md를 편집하여 'performance-metrics'에 대한 적용 범위 추가"

8. 수정 제안

사용자에게 질문: "상위 N개 이슈에 대한 구체적인 수정 편집을 제안해 드릴까요?" (자동으로 적용하지 마십시오.)

9. 확장 훅 확인

보고 후, 프로젝트 루트에 .specify/extensions.yml이 있는지 확인합니다.

  • 존재하는 경우, hooks.after_analyze 키 아래의 항목을 읽습니다.
  • YAML을 구문 분석할 수 없거나 유효하지 않은 경우, 조용히 넘어가지 않고 .specify/extensions.yml을 읽을 수 없다고 사용자에게 알리고(구문 분석 오류 포함), 등록된 필수(optional: false) 훅을 포함한 어떤 훅도 확인되지 않았음을 알린 후 정상적으로 계속 진행합니다.
  • enabled가 명시적으로 false인 훅은 필터링합니다. enabled 필드가 없는 훅은 기본적으로 활성화된 것으로 간주합니다.
  • 나머지 각 훅에 대해, 훅 condition 표현식을 해석하거나 평가하려고 시도하지 마십시오:
    • 훅에 condition 필드가 없거나 null/비어 있으면, 훅을 실행 가능한 것으로 처리합니다.
    • 훅이 비어 있지 않은 condition을 정의하는 경우, 해당 훅은 건너뛰고 조건 평가는 HookExecutor 구현에 맡깁니다.
  • 훅 명령 이름에서 점(.)을 하이픈(-)으로 바꾸어 명령 호출을 구성합니다. 예를 들어, speckit.git.commit → /speckit-git-commit이 됩니다.
  • 각 실행 가능한 훅에 대해, optional 플래그에 따라 다음을 출력합니다:
    • 선택적 훅 (optional: true):
      ## 확장 훅
      
      **선택적 훅**: {extension}
      명령어: `/{command}`
      설명: {description}
      
      프롬프트: {prompt}
      실행하려면: `/{command}`
      
    • 필수 훅 (optional: false):
      ## 확장 훅
      
      **자동 훅**: {extension}
      실행 중: `/{command}`
      EXECUTE_COMMAND: {command}
      
      위 블록을 출력한 후에는 실제로 훅을 호출하고 완료될 때까지 기다려야 합니다. 이 에이전트/세션에서 직접 명령을 실행하는 것과 같은 방식으로 실행하십시오(호출 방식은 위에 표시된 리터럴 {command} ID와 다를 수 있습니다. 예를 들어, skills 모드 에이전트는 /skill:speckit-... 또는 $speckit-...로 실행합니다). 블록만 출력하는 것으로는 훅이 실행되지 않습니다.
  • 등록된 훅이 없거나 .specify/extensions.yml이 존재하지 않으면, 조용히 건너뜁니다.

운영 원칙

컨텍스트 효율성

  • 최소 고신호 토큰: 철저한 문서화가 아닌 실행 가능한 발견에 집중
  • 점진적 공개: 아티팩트를 증분적으로 로드; 모든 내용을 분석에 덤프하지 않음
  • 토큰 효율적 출력: 발견 테이블을 50행으로 제한; 오버플로 요약
  • 결정론적 결과: 변경 없이 재실행 시 일관된 ID와 개수 생성

분석 지침

  • 절대 파일을 수정하지 마십시오 (읽기 전용 분석)
  • 절대 누락된 섹션을 환각하지 마십시오 (없는 경우 정확하게 보고)
  • 헌법 위반에 우선순위를 두십시오 (항상 CRITICAL)
  • 포괄적인 규칙보다 예제를 사용하십시오 (일반 패턴이 아닌 특정 인스턴스 인용)
  • 이슈가 없으면 우아하게 보고하십시오 (적용 범위 통계와 함께 성공 보고서 출력)

컨텍스트

$ARGUMENTS

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

관련 스킬