Communitygithub.com

tangjuyo/reels-blocker

현재 코드베이스가 기능 명세, 계획 및 작업과 일치하는지 평가하고, 미완료된 작업을 tasks.md에 새로운 작업으로 추가하여 구현을 완료할 수 있도록 합니다.

reels-blocker란 무엇인가요?

이 스킬은 개발자가 기능 명세(spec.md), 계획(plan.md), 작업 목록(tasks.md)에 정의된 요구사항과 현재 코드베이스의 실제 구현 상태 간의 차이를 분석합니다. 각 요구사항, 승인 기준, 계획 결정, 헌법(constituion) 원칙을 검토하여 누락되거나, 부분적으로만 충족되거나, 의도와 상충되거나, 요청되지 않은 작업을 찾아냅니다. 발견된 격차는 심각도(CRITICAL, HIGH, MEDIUM, LOW)에 따라 분류되어 tasks.md 파일 끝에 새로운 'Convergence' 단계로 추가되며, 이후 /speckit-implement 명령이 이를 완료할 수 있도록 합니다. 코드를 직접 수정하지 않고 작업 항목만 추가하는 '추가 전용' 모드로 동작하며, Claude Code 및 기타 AI 에이전트 플랫폼에서 사용할 수 있습니다.

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

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

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

문서

사용자 입력

$ARGUMENTS

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

실행 전 검사

확장 후크 확인 (수렴 전):

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

  • 파일이 존재하면 읽고 hooks.before_converge 키 아래의 항목을 찾습니다.

  • 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와 다를 수 있습니다. 예를 들어 스킬 모드 에이전트는 /skill:speckit-... 또는 $speckit-...로 실행함). 블록만 출력하는 것은 후크를 실행하는 것이 아닙니다.

  • 등록된 후크가 없거나 .specify/extensions.yml이 존재하지 않으면 조용히 건너뜁니다.

목표

기능의 명세, 계획 및 작업이 요구하는 사항과 코드베이스가 현재 구현하고 있는 사항 간의 차이를 좁힙니다. spec.md, plan.md 및 tasks.md를 유일한 의도 소스로 읽고(헌법을 제약 조건으로 사용), 코드의 현재 상태를 평가하여 충족되지 않았거나, 불완전하거나, 부분적으로만 충족된 요구사항, 승인 기준, 계획 결정 및 기존 작업을 확인하고, 남은 각 작업을 새롭고 추적 가능한 작업으로 tasks.md 하단에 추가하여 /speckit-implement가 완료할 수 있도록 합니다. 이 명령은 /speckit-implement가 현재 tasks.md에서 실행된 후, 그리고 /speckit-tasks가 완전한 tasks.md를 생성한 후에만 실행되어야 합니다.

이는 diff 도구가 아니며 변경 사항을 추적하지 않습니다. 기능의 산출물을 기준으로 코드의 현재 상태를 평가합니다. — git도, 브랜치 비교도, 히스토리도 없습니다.

작동 제약 조건

추가 전용, 절대 다시 쓰지 않음: 명령의 유일한 쓰기 작업은 tasks.md에 새로운 ## Phase N: Convergence 섹션을 추가하는 것입니다. 다음을 수행해서는 안 됩니다:

  • 어떤 방식으로든 spec.md 또는 plan.md를 수정합니다.
  • 기존 작업(이전 Convergence 단계의 작업 포함)을 다시 쓰거나, 번호를 다시 매기거나, 순서를 바꾸거나, 삭제합니다.
  • 애플리케이션 코드를 수정, 생성 또는 삭제합니다. — 추가된 작업을 완료하는 것은 /speckit-implement의 몫입니다.

코드베이스가 이미 모든 것을 충족하는 경우, 명령은 tasks.md를 바이트 단위로 변경하지 않고 그대로 두고(빈 Convergence 헤더 없음) 깨끗한 결과를 보고해야 합니다.

헌법 권한: 프로젝트 헌법(.specify/memory/constitution.md)은 논쟁의 여지가 없습니다. 반드시(MUST) 원칙을 위반하는 코드는 가장 높은 심각도의 발견 사항이며 해당 수정 작업을 생성합니다. 헌법이 채워지지 않은 템플릿인 경우, 실패하지 않고 정상적으로 헌법 검사를 건너뜁니다.

실행 단계

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
  • CONSTITUTION = .specify/memory/constitution.md (있는 경우) spec.md, plan.md 또는 tasks.md가 누락된 경우, 누락된 문서를 생성하기 위해 실행해야 하는 사전 조건 명령(/speckit-specify, /speckit-plan, /speckit-tasks)을 명확하고 실행 가능한 메시지와 함께 중단합니다. 부분 출력을 생성하지 마십시오. 인수에 "I'm Groot"와 같은 작은따옴표가 있는 경우 이스케이프 구문(예: 'I'''m Groot')을 사용하거나 가능하면 큰따옴표("I'm Groot")를 사용하십시오.

2. 산출물 로드 (점진적 공개)

각 산출물에서 필요한 최소한의 컨텍스트만 로드합니다:

spec.md에서:

  • 기능 요구사항 (FR-###)
  • 성공 기준 (SC-###) — 빌드 가능한 작업이 필요한 항목만 포함하고, 출시 후 결과 지표 및 비즈니스 KPI는 제외합니다.
  • 사용자 스토리 및 해당 승인 시나리오
  • 엣지 케이스 (있는 경우)

plan.md에서:

  • 아키텍처/스택 선택 및 기술 결정
  • 데이터 모델 참조
  • 단계 및 명명된 접점 (계획에 따라 생성되거나 편집될 파일/컴포넌트)
  • 기술 제약 조건

tasks.md에서:

  • 작업 ID (다음 ID 및 다음 단계 번호를 계산하기 위해)
  • 설명, 단계 그룹화 및 참조된 파일 경로

헌법(채워지지 않은 템플릿이 아닌 경우)에서:

  • 원칙 이름 및 MUST/SHOULD 규범적 진술

3. 의도 인벤토리 구축

내부 모델 생성(원시 산출물을 에코하지 않음):

  • 요구사항 인벤토리: FR-### / SC-### / 사용자 스토리 승인 시나리오(예: US1/AC2)당 하나의 안정적인 키와 빌드 가능한 의무를 부과하는 계획 결정 및 헌법 원칙을 포함합니다.
  • 코드 범위 맵: plan.md 및 tasks.md에 명명된 파일 경로와 각 요구사항이 설명하는 개념에 대한 키워드 검색을 통해 평가 대상이 되는 소스 파일 및 컴포넌트 집합을 파생시킵니다. 평가 범위를 이들로 제한합니다. — 산출물이 정의한 범위를 넘어 추론하지 마십시오.

4. 코드베이스 평가 및 발견 사항 분류

체크박스 상태나 Convergence 단계와 관계없이 모든 기존 작업을 의도 인벤토리에 포함합니다. 완료 주장은 증거가 아닙니다. 현재 동작을 명세, 계획, 작업 및 헌법과 비교하여 확인합니다. 수정 작업 체인의 경우 결과 동작을 평가하고 대체된 구현 세부 사항은 평가하지 않습니다. 명시된 의도를 충족하지 못하거나, 이에 위배되거나, 이를 초과하거나, 그 범위를 벗어나는 구현을 모두 확인합니다.

의도 인벤토리의 각 항목에 대해 범위 내의 현재 코드를 검사하고 차이가 있는 경우에만 발견 사항을 생성합니다. 모든 발견 사항을 차이 유형별로 분류합니다:

  • missing: 필요한 작업이 코드에 완전히 없습니다.
  • partial: 작업이 존재하지만 아직 요구사항/승인 기준/계획 결정을 완전히 충족하지 않습니다.
  • contradicts: 코드가 명시된 의도 또는 헌법 MUST 원칙과 충돌하는 작업을 수행합니다.
  • unrequested: 코드에 명세, 계획 또는 작업에서 요구하지 않은 작업이 포함되어 있습니다(인식을 위해 표시됨 — 수렴은 코드를 삭제하지 않고 검토/정당화 또는 제거 작업만 추가합니다).

각 발견 사항은 다음을 기록합니다: 안정적인 ID, 참조하는 source-ref, gap-type, 심각도 및 증거(관찰된 파일/영역)가 포함된 짧은 사람이 읽을 수 있는 설명.

엣지 케이스:

  • 코드가 거의 없거나 전혀 없는 경우: 명시된 전체 범위를 실패로 처리하지 않고 missing 남은 작업으로 처리합니다.
  • 남은 작업이 없는 경우: 발견 사항을 0개 생성하고 7단계의 수렴 분기를 따릅니다.

5. 심각도 할당

  • CRITICAL: 헌법 MUST 원칙을 위반하거나 P1 사용자 스토리의 기본 기능을 차단하는 missing/contradicts 차이입니다.
  • HIGH: 핵심 기능 요구사항 또는 승인 기준에 대한 missing 또는 partial 차이입니다.
  • MEDIUM: 보조 요구사항에 대한 partial 차이 또는 정당화가 불명확한 unrequested 추가입니다.
  • LOW: 사소한 부분적 차이, 개선 또는 위험이 낮은 unrequested 추가입니다.

6. 세션 내 발견 사항 요약 제시

아무 것도 추가하기 전에 압축된 심각도 등급 요약을 출력합니다(아직 파일 쓰기 없음):

수렴 발견 사항

ID차이 유형심각도출처증거남은 작업
F1missingHIGHFR-008예: path/to/module.py에서 tasks.md 작성 시 추가 전용 가드가 감지되지 않음추가 전용 강제 적용 추가

요약 지표:

  • 확인된 요구사항 / 승인 기준
  • 확인된 계획 결정
  • 확인된 헌법 원칙 (또는 "건너뜀 — 템플릿")
  • 차이 유형별 발견 사항 (missing / partial / contradicts / unrequested)
  • 심각도별 발견 사항

7. 수렴 작업 추가 (또는 수렴됨 보고)

하나 이상의 실행 가능한 발견 사항이 있는 경우 (tasks_appended 결과):

추가 전용 계약에 따라 tasks.md의 끝에 추가합니다:

  1. 모든 기존 작업 ID를 스캔합니다. 최대값을 M으로 둡니다. 다음 단계 번호 N을 결정합니다(가장 높은 기존 단계 + 1).

  2. 단일 새 섹션 헤더 ## Phase N: Convergence를 작성합니다.

  3. 실행 가능한 발견 사항당 하나의 체크리스트 항목을 CRITICAL/HIGH 순서로 발행하고, 0으로 채워진 ID T{M+1:03d}, T{M+2:03d}, …를 할당합니다:

    - [ ] T042 <명령형 설명> (<source-ref> 기준) (<gap-type>)
    

    <source-ref>는 작업의 출처를 추적합니다. 예: FR-003, SC-002, US1/AC2, plan: storage decision, Constitution II.

    <gap-type>은 missing, partial, contradicts, unrequested 중 하나입니다.

    헌법 위반 작업은 먼저 발행되어야 하며 CRITICAL로 설명되어야 합니다.

  4. 기존 ID를 재사용하거나 번호를 다시 매기지 마십시오. 이전 Convergence 단계가 존재하는 경우, 그 아래에 새롭고 별도로 번호가 매겨진 단계를 추가하십시오. — 이전 단계는 건드리지 마십시오.

실행 가능한 발견 사항이 없는 경우 (converged 결과):

  • tasks.md를 전혀 수정하지 마십시오. — 빈 단계 헤더도 없습니다.
  • 보고: "✅ 수렴됨 — 구현이 명세, 계획 및 작업을 충족합니다."
  • 확인된 항목의 요약 개수를 포함합니다.

8. 다음 작업 제공 (핸드오프)

  • tasks_appended의 경우: 몇 개의 작업이 어떤 단계 아래에 추가되었는지 명시하고 /speckit-implement를 실행하여 완료할 것을 권장합니다. 후속 수렴 실행 시 남은 항목이 더 적거나 없을 것임을 언급합니다.
  • converged의 경우: 검토 진행 / PR 열기를 권장합니다. 이 기능의 명시된 범위에 대해서는 더 이상의 구현 패스가 필요하지 않습니다.

9. 확장 후크 확인

결과를 생성한 후 프로젝트 루트에 .specify/extensions.yml이 있는지 확인합니다.

  • 파일이 존재하면 읽고 hooks.after_converge 키 아래의 항목을 찾습니다.

  • YAML을 구문 분석할 수 없거나 유효하지 않은 경우, 조용히 건너뛰지 말고 .specify/extensions.yml을 읽을 수 없다고 사용자에게 알리고(파서 오류 포함) 해당 파일에 등록된 모든 필수(optional: false) 후크를 포함하여 어떤 후크도 확인되지 않았음을 알린 후 정상적으로 계속 진행합니다.

  • enabled가 명시적으로 false인 후크는 필터링하여 제외합니다. enabled 필드가 없는 후크는 기본적으로 활성화된 것으로 간주합니다.

  • 나머지 각 후크에 대해 후크 condition 표현식을 해석하거나 평가하려고 시도하지 마십시오:

    • 후크에 condition 필드가 없거나 null/비어 있는 경우 후크를 실행 가능한 것으로 처리합니다.
    • 후크가 비어 있지 않은 condition을 정의하는 경우 후크를 건너뛰고 조건 평가는 HookExecutor 구현에 맡깁니다.
  • 후크를 나열하기 전에 수렴 결과(converged 또는 tasks_appended)를 세션 내에서 보고하여 사용자가 선택적 후속 명령을 실행할지 여부를 결정할 수 있도록 합니다.

  • 후크 명령 이름에서 마침표(.)를 하이픈(-)으로 바꾸어 명령 호출을 구성합니다. 예를 들어 speckit.git.commit → /speckit-git-commit이 됩니다.

  • 각 실행 가능한 후크에 대해 optional 플래그에 따라 다음을 출력합니다:

    • 선택적 후크 (optional: true):

      ## 확장 후크
      
      **선택적 후크**: {extension}
      명령어: `/{command}`
      설명: {description}
      
      프롬프트: {prompt}
      실행하려면: `/{command}`
      
    • 필수 후크 (optional: false):

      ## 확장 후크
      
      **자동 후크**: {extension}
      실행 중: `/{command}`
      EXECUTE_COMMAND: {command}
      

      위 블록을 출력한 후 반드시 실제로 후크를 호출하고 계속 진행하기 전에 완료될 때까지 기다려야 합니다. 이 에이전트/세션에서 직접 명령을 실행하는 것과 동일한 방식으로 실행하십시오(호출 방식은 위에 표시된 리터럴 {command} ID와 다를 수 있습니다. 예를 들어 스킬 모드 에이전트는 /skill:speckit-... 또는 $speckit-...로 실행함). 블록만 출력하는 것은 후크를 실행하는 것이 아닙니다.

  • 등록된 후크가 없거나 .specify/extensions.yml이 존재하지 않으면 조용히 건너뜁니다.

Individual skills in this repo

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

관련 스킬