verification-before-completion

개요

verification-before-completion 스킬이란?

verification-before-completion 스킬은 개발자와 에이전트를 위한 엄격한 워크플로우 규칙을 정의합니다. 핵심은 다음과 같습니다. 관련 검증 커맨드를 방금 실행하고 그 출력을 확인하지 않았다면, 작업이 끝났다고 하거나, 테스트가 통과했다고 하거나, 버그가 수정됐다고 말해서는 안 됩니다. 이 스킬의 핵심 원칙은 다음 한 줄로 표현됩니다.

어떤 주장보다 먼저, 항상 근거가 있어야 한다.

실제 업무에서는 "tests are passing", "the build is green", "the bug is fixed"와 같은 문장을 적기 전에 다음을 반드시 수행해야 합니다.

• 해당 주장을 입증할 수 있는 커맨드를 찾고
• 예전 실행 결과나 추측이 아닌, 새로 실행하고
• 출력과 exit status를 읽은 뒤
• 그 근거에 기반해 결과를 말해야 합니다.

이 스킬은 누구를 위한 것인가?

다음에 해당한다면 verification-before-completion 스킬 사용을 고려해 보세요.

• 실패한 테스트, 깨진 빌드, 검증되지 않은 수정 사항이 코드베이스에 자주 섞여 들어가는 환경에서 작업한다
• 실제로 검증을 실행하지 않고도 성공을 주장할 수 있는 에이전트나 자동화 도구를 사용한다
• 개발 워크플로우 안에 규율 잡힌, 반복 가능한 테스트·검증 관행을 도입하고 싶다

특히 다음과 같은 경우에 유용합니다.

• 테스트 자동화: 테스트 스위트가 실제로 실행되고, 그 결과가 올바르게 해석되도록 보장
• 워크플로우 자동화: 완료 단계가 항상 검증 커맨드 실행을 포함하도록 강제
• "done" 상태 이후의 예상치 못한 문제를 줄이고 싶은 코드 리뷰·CI·CD 팀

verification-before-completion은 어떤 문제를 해결하나요?

안전장치가 없다면 다음과 같은 상황은 너무 쉽게 발생합니다.

• 변경이 "작으니까" 테스트도 당연히 통과할 것이라고 가정한다
• 코드를 조금 수정해 놓고, 실패했던 시나리오를 다시 실행해 보지 않은 채 버그가 고쳐졌다고 주장한다
• 변경 후 빌드를 다시 하지 않고, 예전에 성공했던 빌드 결과만 믿고 넘긴다

verification-before-completion 스킬은 저장소에서 Iron Law(철칙) 라고 부르는 규칙을 명확히 정의합니다.

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

이 스킬을 도입하면, 이 철칙을 나 자신과 팀, 혹은 에이전트를 위한 구체적인 워크플로우 규칙으로 바꿀 수 있습니다. 이를 통해 다음을 줄일 수 있습니다.

• Pull Request에서의 잘못된 "green" 상태 주장
• 실제로는 테스트되지 않은 채 숨어 있던 회귀 버그
• 개발자, 리뷰어, 자동화 사이의 오해와 커뮤니케이션 오류

언제 이 스킬이 잘 맞을까요?

다음과 같은 경우 verification-before-completion을 선택하면 좋습니다.

• 이미 테스트, lint, 빌드 커맨드가 존재하고, 항상 실행되도록 확실히 만들고 싶다
• 개발 작업을 도와주는 에이전트나 스크립트를 사용하며, 검증에 대해서는 엄격하게 동작하길 원한다
• 워크플로우 시간을 몇 초 줄이는 것보다, 신뢰할 수 있는 상태 보고가 더 중요하다

반대로, 다음과 같은 경우에는 활용도가 낮을 수 있습니다.

• 프로젝트에 아직 의미 있는 자동화 검증(테스트, lint, 빌드 커맨드 등)이 없다
• 아직 "passing" 또는 "fixed"라는 식의 상태를 선언할 준비가 되지 않은 탐색적 작업을 하고 있다
• 이 저장소를 강제되는 워크플로우가 아니라 개념적인 참고 자료로만 사용하고 있다

이런 상황이라도, 앞으로의 테스트와 검증 체계를 설계할 때 참고용 가이드로 이 스킬을 활용할 수 있습니다.

사용 방법

설치 및 설정

npx를 사용해 verification-before-completion 스킬을 설치하려면 다음 커맨드를 실행하세요.

npx skills add https://github.com/obra/superpowers --skill verification-before-completion

설치 후에는 다음 순서로 진행합니다.

1. obra/superpowers 저장소 안의 skills/verification-before-completion 디렉터리를 엽니다.
2. 전체 규칙과 그 배경 설명을 확인하려면 SKILL.md부터 읽어보세요.
3. 이 규칙을 프로젝트 문서, 에이전트 설정, 개발 가이드라인 등에 통합합니다.

저장소 구조를 그대로 복사할 필요는 없습니다. 대신, 그 구조를 참고해 자신의 환경에서 규칙을 어떻게 설명하고 강제할지 설계하면 됩니다.

핵심 워크플로우: Gate Function

이 스킬은 어떤 완료 주장 전에 반드시 실행해야 하는 Gate Function을 정의합니다. 일상적인 작업에서는 다음과 같이 적용합니다.

어떤 상태를 주장하거나, 만족스럽다고 표현하기 전에:

1. IDENTIFY: 이 주장을 입증해 줄 커맨드는 무엇인가?
2. RUN: 해당 커맨드를 처음부터 끝까지 (새로, 전체) 실행한다
3. READ: 전체 출력을 읽고, exit code와 실패 개수를 확인한다
4. VERIFY: 출력이 이 주장을 실제로 뒷받침하는가?
   - NO인 경우: 근거와 함께 실제 상태를 기술한다
   - YES인 경우: 근거와 함께 주장을 기술한다
5. ONLY THEN: 그때 비로소 주장을 한다

이 중 어느 단계라도 건너뛰면 더 이상 verification-before-completion을 따르고 있다고 볼 수 없습니다.

일반적으로 자주 쓰이는 커맨드 예시는 다음과 같습니다.

• Tests: npm test, pytest, go test ./..., mvn test
• Lint: eslint ., flake8, golangci-lint run
• Build: npm run build, make, cargo build --release
• 특정 버그 검증: 원래 이슈를 재현하는 스크립트, 테스트, 또는 수동 확인 절차

예시: 개발 워크플로우에서 스킬 사용하기

시나리오: 코드를 수정했고 "All tests pass"라고 말하고 싶습니다.

verification-before-completion을 다음과 같이 적용합니다.

1. IDENTIFY: 해당 주장을 입증할 커맨드를 정합니다. 예를 들어 pytest.
2. 변경 후 RUN 단계에서 커맨드를 실행합니다.

   pytest
   

3. 출력 내용을 READ하고 exit code가 0인지 확인합니다.
4. VERIFY 단계:
   • 테스트가 실패했다면, 절대 성공을 주장해서는 안 됩니다. 대신 다음처럼 보고합니다. "Tests are failing: 3 tests failing in test_user_flow.py. See pytest output."
   • 테스트가 모두 통과했다면, 이렇게 말할 수 있습니다. "All tests pass (pytest, exit code 0)."
5. ONLY THEN 단계에서 작업을 완료 처리하고, 커밋을 푸시하거나 Pull Request를 엽니다.

이 패턴은 빌드, linters, 포매터, 버그 수정 등 모든 종류의 상태 주장에 동일하게 적용할 수 있습니다.

에이전트 및 자동화와 통합하기

개발을 도와주는 에이전트나 스크립트를 사용하는 경우 다음과 같이 설정할 수 있습니다.

• 테스트, 빌드, 버그 수정에 대한 어떤 주장도 반드시 구체적인 커맨드 실행 및 결과 요약 이후에만 나오도록 구성합니다.
• 에이전트가 실행한 커맨드와 그 결과를 항상 언급하도록 요구합니다. 예를 들어 다음과 같습니다.
  • "Ran npm test: exit code 0, 0 failing tests."
  • "Ran npm run build: exit code 1, build failed. Not claiming completion."

리뷰나 CI 파이프라인에서, verification-before-completion 기준에 따르면 근거 없이 이루어진 모든 주장은 불완전한 것으로 간주할 수 있습니다.

도구와 환경에 맞게 조정하기

이 저장소는 특정 언어나 프레임워크를 전제하지 않습니다. 스킬을 프로젝트에 맞게 적용하려면 다음과 같이 하면 됩니다.

• 자주 사용하는 각 상태 주장마다 그것을 입증하는 하나의 명확한 커맨드를 매핑합니다.
• 이러한 매핑을 자신의 저장소에 문서화합니다. (예: CONTRIBUTING.md, WORKFLOW.md 등)
• 기여자와 에이전트가 항상 다음을 따르도록 권장하거나 요구합니다.
  • "done"이라고 말하기 전에 해당 커맨드를 실행한다
  • 주장을 할 때 관련 출력 내용을 붙이거나 요약해 남긴다

예시 claim→command 매핑은 다음과 같습니다.

• "Backend tests pass" → pytest backend/tests
• "Frontend builds successfully" → npm run build (in frontend/)
• "Go module is clean" → go test ./... 및 golangci-lint run

FAQ

verification-before-completion의 핵심 규칙은 무엇인가요?

핵심 규칙은 다음과 같은 "Iron Law(철칙)"입니다.

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

관련 검증 커맨드를 방금 실행하고 출력 결과를 확인하지 않았다면, 성공했다고 정직하게 말할 수 없습니다.

"verification evidence"는 무엇을 의미하나요?

verification evidence(검증 근거)는 주장과 직접적으로 연결된 커맨드를 방금 실행해서 얻은 최신 출력을 뜻합니다. 예를 들면 다음과 같습니다.

• 실패 0개, exit code 0을 보여주는 테스트 스위트 실행 결과
• 에러 없이 종료된 linter 실행 결과와 성공 exit status
• 성공적으로 끝난 빌드 커맨드 (exit 0)
• 이제 통과하게 된 버그 재현 스크립트 또는 테스트

이 스킬의 관점에서, 오래된 실행 결과나 추측, "아마 될 거야"와 같은 말은 근거로 인정되지 않습니다.

아무것도 안 바뀌었으면 이전 테스트 결과를 믿어도 되지 않나요?

verification-before-completion에서는 기본적으로 아니요입니다. 이 스킬은 완료를 새로 주장할 때마다 최신 검증을 수행하는 것을 강조합니다. 이전 실행 결과에 의존하고 싶다면, 어떤 조건에서 예외를 인정할지 명확히 정의하고, 그만큼 보증 수준이 약해진다는 점을 인지해야 합니다.

이 스킬은 특정 도구나 언어를 요구하나요?

요구하지 않습니다. verification-before-completion 스킬은 도구에 독립적입니다. 다음이 가능한 모든 스택에서 활용할 수 있습니다.

• 동작을 검증하는 커맨드(테스트, lint, 빌드, 스크립트 등)를 정의하고
• 필요할 때마다 실행하며
• exit code와 출력을 해석할 수 있는 환경

프로젝트에 맞는 커맨드를 채워 넣은 뒤, Gate Function 단계를 따라가면 됩니다.

그냥 가끔 테스트를 돌려보는 것과 무엇이 다른가요?

차이는 규율과 일관성에 있습니다.

• 완료를 주장하기 직전마다 검증 커맨드를 실행합니다.
• 성공을 당연하게 여기지 않고, 항상 출력 결과를 직접 확인합니다.
• 근거 없는 주장은 모두 무효한 것으로 취급합니다.

이렇게 하면 테스트와 빌드 실행이 선택적인 부가 요소가 아니라, 공식적인 게이트 역할을 하게 됩니다.

verification-before-completion은 수동 테스트에도 쓸 수 있나요?

네, 해당 주장에 대응하는 "커맨드" 역할을 하는 명확한 절차를 정의할 수만 있다면 가능합니다. 예를 들어 다음과 같습니다.

• 버그를 재현하는 단계별 수동 테스트 절차를 문서화하고
• 변경 후 그 절차를 다시 수행한 뒤
• 결과를 근거로 기록합니다.

다만, 검증이 스크립트나 테스트 프레임워크를 통해 자동화되어 있을수록 결과를 반복 실행하기 쉽고, 일관성도 높아지기 때문에 이 스킬과 가장 잘 맞습니다.

원래 스킬 정의는 어디에서 볼 수 있나요?

verification-before-completion 스킬에 대한 권위 있는 설명은 obrа/superpowers 저장소의 SKILL.md 파일에 있습니다.

• Repository: https://github.com/obra/superpowers
• Skill file: skills/verification-before-completion/SKILL.md

원칙의 정확한 문구, Iron Law, Gate Function, 피해야 할 대표적인 실패 사례를 확인하려면 해당 파일을 참고하세요.