verification-before-completion

verification-before-completion 스킬 개요

verification-before-completion이 필요한 상황

verification-before-completion 스킬은 작업을 완료했다, 수정이 끝났다, 테스트를 통과했다, 리뷰할 준비가 됐다고 말하기 직전에 사용하는 엄격한 최종 검증 워크플로입니다. 역할은 단순합니다. 근거 없는 성공 선언을 막고, 먼저 최신 검증 증거를 확보하도록 강제하는 것입니다.

이 스킬은 AI 보조 코딩, 에이전트 워크플로, 커밋 준비, PR 인계 상황에서 특히 유용합니다. 실제로 올바른 명령을 돌려보지 않았는데도 “tests should pass”, “the bug is fixed”, “build looks good” 같은 문구가 상태 업데이트에 들어가는 경우를 본 적이 있다면, verification-before-completion은 바로 그 실패 패턴을 겨냥합니다.

누가 이 스킬을 설치하면 좋은가

특히 잘 맞는 사용자는 다음과 같습니다.

• AI 에이전트로 코드를 수정하는 개발자
• 더 깔끔하고 근거 있는 상태 업데이트를 원하는 리뷰어
• 낙관적이지만 검증되지 않은 완료 메시지에 지친 팀
• 확신보다 증거가 더 중요한 Skill Validation 패턴을 쓰는 사용자

주로 코드 생성, 계획 수립, 폭넓은 디버깅 지원이 필요하다면 이 스킬이 그 역할을 대신하진 않습니다. verification-before-completion 스킬은 전체 전달 과정을 책임지는 워크플로가 아니라, 마지막 단계의 안전장치입니다.

이 스킬이 실제로 해결하는 일

핵심은 단순히 “테스트를 돌린다”가 아닙니다. 실제로 해야 하는 일은 다음입니다.

1. 어떤 증거가 있으면 해당 주장을 입증할 수 있는지 식별한다
2. 그 정확한 검증을 지금 실행한다
3. 실제 출력 결과를 읽는다
4. 증거가 뒷받침하는 범위까지만 주장한다

당연해 보이지만, AI 보조 워크플로는 바로 이 지점에서 자주 무너집니다. verification-before-completion은 이 기대치를 완료 전 필수 게이트로 바꿔줍니다.

verification-before-completion이 다른 점

이 스킬의 핵심 차별점은 범위를 의도적으로 좁혔다는 점입니다. verification-before-completion은 저장소 전체를 똑똑하게 이해하려고 하지 않습니다. 대신 높은 가치의 규칙 하나를 강하게 적용합니다.

최신 검증 증거 없이는 완료 주장 금지

이 때문에 마무리 단계에 붙이는 finishing-layer 스킬로 특히 좋습니다. 일반적인 “조심해서 검증해라” 식 프롬프트보다 일관되게 발동시키기 쉬운 이유도 여기에 있습니다. 판단 함수가 반복 가능하기 때문입니다. 식별하고, 실행하고, 읽고, 검증한 뒤에 말합니다.

verification-before-completion이 특히 잘 맞는 경우

다음과 같은 말을 하려는 순간 verification-before-completion 스킬을 쓰는 것이 좋습니다.

• “tests pass”
• “the bug is fixed”
• “the build succeeds”
• “this is ready to merge”
• “the linter is clean”

이런 문장은 각각 다른 증거를 요구합니다. 이 스킬은 흔한 실수를 막아줍니다. 인접한 무언가만 확인해 놓고, 그보다 더 강한 결론으로 과장해 버리는 문제입니다.

verification-before-completion 스킬 사용 방법

verification-before-completion 설치 맥락

obra/superpowers 저장소에서 설치할 수 있습니다.

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

이 스킬은 단일 SKILL.md 파일에 들어 있어 도입 부담이 가볍습니다. 먼저 이해해야 할 헬퍼 스크립트나 추가 리소스 파일도 없습니다.

가장 먼저 읽어야 할 파일

다음 파일부터 확인하세요.

• skills/verification-before-completion/SKILL.md

이 파일에 전체 동작 계약이 모두 들어 있습니다. 이 스킬은 저장소 차원의 보조 구조가 거의 없기 때문에, 먼저 SKILL.md만 읽어도 내 워크플로와 맞는지 빠르게 판단할 수 있습니다.

이 스킬이 사용자에게 요구하는 입력

verification-before-completion 스킬은 아래 세 가지가 주어질 때 가장 잘 작동합니다.

• 지금 하려는 주장
• 그 주장을 실제로 입증할 명령
• 검증을 막고 있는 환경 제약

예시 입력:

• “I want to say the fix works. The proving command is pytest tests/api/test_login.py -q.”
• “I want to say the build passes. The expected verification is npm run build.”
• “I think lint is clean, but I have not run ruff check . yet.”

구체적인 주장과 명령이 없으면, 이 스킬도 결국 일반적인 주의 문구 수준의 답변만 줄 수 있습니다.

막연한 목표를 실제로 쓸 수 있는 프롬프트로 바꾸기

약한 프롬프트:

• “Can I say this is done?”

더 나은 프롬프트:

• “Before I claim this is complete, apply the verification-before-completion skill. The claim is: ‘the login bug is fixed.’ The best proving command is pytest tests/auth/test_login_bug.py -q. If that is not enough, tell me what additional verification is required.”

왜 더 좋은가:

• 주장 내용을 명시합니다
• 입증 경로를 제안합니다
• 검증이 약하면 스킬이 그 한계를 지적할 수 있습니다

실무에서 verification-before-completion을 호출하는 방법

완료 메시지, 커밋 요약, PR 노트를 쓰기 직전에 verification-before-completion을 사용하세요. 실전 워크플로는 보통 다음 순서가 좋습니다.

1. 코드 변경을 끝낸다
2. 정확히 어떤 주장을 할지 정한다
3. 그 주장을 입증할 명령을 식별한다
4. 해당 전체 명령을 새로 실행한다
5. 출력과 종료 상태를 확인한다
6. 증거가 불완전하면 주장을 낮추거나 조건을 붙인다

이 순서가 중요합니다. 사람들은 요약 단계에서 낙관적으로 말하고 싶은 유혹을 가장 크게 느끼는데, verification-before-completion은 바로 그 지점에서 가장 큰 가치를 냅니다.

주장과 증거를 올바르게 매칭하기

verification-before-completion 스킬의 실질적인 장점 중 하나는 증거 불일치를 막는다는 점입니다.

예시:

• 주장: “Tests pass”
  증거: 관련 전체 테스트 명령이 실패 0건으로 종료됨

• 주장: “Linter is clean”
  증거: linter 명령이 에러 0건을 보여줌

• 주장: “Build succeeds”
  증거: build 명령이 성공적으로 종료됨

• 주장: “Bug is fixed”
  증거: 원래 실패 경로를 재현하는 검증 단계가 이제 통과함

linter가 통과했다고 해서 build 성공이 입증되지는 않습니다. 파일을 바꿨다고 해서 버그 수정이 입증되는 것도 아닙니다. 많은 약한 에이전트 출력이 무너지는 지점이 바로 이런 구분입니다.

어떤 것이 최신 검증 증거로 인정되는가

최신(fresh)이라는 말은, 지금 이 작업 상태에 대해 그 명령을 실제로 실행했다는 뜻이지 예전 시도의 기억을 뜻하지 않습니다. 실무적으로는 다음을 의미합니다.

• 예전 터미널 출력에 기대지 않는다
• 파일이 안 바뀌었다고 결과도 같을 것이라 가정하지 않는다
• 주변 신호만 보고 성공을 추론하지 않는다
• 부분 검증으로 더 넓은 주장을 대신하지 않는다

마지막 실행 이후 코드를 수정했다면, 완료 판단 기준에서 그 이전 실행 결과는 이미 오래된 증거입니다.

검증을 실행할 수 없을 때 해야 할 일

환경 때문에 실행이 막히는 경우도 있습니다. 예를 들어 의존성 누락, 자격 증명 부재, 서비스 미가용, 지원되지 않는 OS, 시간 제약 등이 있습니다. 이런 경우에는 더 강한 주장을 해서는 안 됩니다.

대신 증거 기반 표현을 사용하세요.

• “I made the change, but I could not run npm test in this environment.”
• “The fix is implemented, but build verification remains unconfirmed.”
• “I verified formatting only; full integration tests were not run.”

이 경우에도 verification-before-completion 사용은 성공입니다. 이 스킬의 목적은 억지로 확정적인 표현을 만들게 하는 것이 아니라, 상태를 사실대로 보고하게 하는 데 있기 때문입니다.

에이전트용 실전 프롬프트 패턴

재사용하기 좋은 강한 프롬프트 예시:

“Use the verification-before-completion skill before any success claim. For each claim, identify the proving command, run it fresh if possible, read the full output, and only state what the evidence confirms. If verification is blocked, report the limitation instead of implying success.”

이 패턴은 에이전트 지침, PR 보조 도구, 커밋 생성 플로에서 잘 작동합니다.

Skill Validation 용도에서의 최적 워크플로

verification-before-completion for Skill Validation에서는 이 스킬을 메인 작업 도구가 아니라 최종 검증자로 다루는 것이 좋습니다. 좋은 순서는 다음과 같습니다.

1. 구현이나 디버깅에는 다른 스킬을 사용한다
2. verification-before-completion으로 전환한다
3. 외부에 공개할 좁고 명확한 주장만 검증한다
4. 실행한 명령과 결과 증거를 포함해 요약을 작성한다

이렇게 역할을 분리하면 구현과 검증이 뒤섞이지 않아 신뢰도가 올라갑니다.

verification-before-completion 스킬 FAQ

verification-before-completion은 그냥 테스트 돌리라는 알림인가요?

아닙니다. verification-before-completion 스킬은 단순 알림보다 훨씬 엄격합니다. 이 스킬은 주장과 증거의 매핑을 강제합니다. 핵심은 그냥 “뭔가를 실행하라”가 아니라, “지금 하려는 정확한 문장을 입증하는 명령을 실행하라”입니다.

초보자에게도 이 스킬이 유용한가요?

네. 특히 각종 체크가 실제로 무엇을 증명하는지 아직 익히는 중인 초보자에게 유용합니다. 이 스킬은 강한 습관을 가르칩니다. 증거가 말해 주는 범위를 넘어서 일반화하지 말라는 것입니다. 이 습관은 기술적 정확성과 리뷰어 신뢰를 모두 높여줍니다.

언제 verification-before-completion을 쓰지 말아야 하나요?

이 스킬만으로 코딩이나 디버깅을 전부 해결하려고 해서는 안 됩니다. 아키텍처를 설계해 주지도 않고, 근본 원인을 찾아주지도 않으며, 전체 테스트 계획을 대신 작성해 주지도 않습니다. 이 스킬은 마무리 체크포인트이며, 구현 중심 스킬과 함께 쓸 때 가장 효과적입니다.

일반 프롬프트보다 어떤 점이 더 낫나요?

일반 프롬프트도 종종 “답변 전에 검증하라”고 말하지만, 에이전트는 여전히 애매한 성공 표현으로 흘러가곤 합니다. verification-before-completion skill은 근거 없는 단정을 했을 때의 결과가 분명한, 일관된 완료 전 게이트가 필요할 때 더 적합합니다.

특정 스택이나 툴체인이 필요한가요?

아니요. 이 스킬은 언어나 프레임워크가 아니라 증거 논리에 기반하므로 스택에 구애받지 않습니다. 환경에 맞는 입증 명령은 사용자가 제공하면 됩니다. 예를 들어 pytest, npm test, go test, cargo test 또는 다른 검증 명령을 쓸 수 있습니다.

전체 검증 비용이 너무 클 때도 사용할 수 있나요?

네. 다만 그 경우에는 주장도 그만큼 좁아져야 합니다. 특정 테스트만 돌렸다면, 그 특정 테스트가 통과했다고 말해야 합니다. 더 넓은 검증을 실제로 수행하지 않았다면 그것을 “everything passes”로 확대해서는 안 됩니다.

verification-before-completion 스킬을 더 잘 활용하는 방법

검증 요청 전에 주장 문장부터 명시하기

출력 품질을 가장 크게 끌어올리는 방법은, 실제로 쓰고 싶은 문장을 먼저 제시하는 것입니다. 예를 들어:

• 약함: “validate this”
• 강함: “I want to say: ‘the payment bug is fixed and tests pass’”

이렇게 하면 스킬이 복합 주장을 분리하고, 각 부분에 어떤 증거가 필요한지 더 정확히 배정할 수 있습니다.

가장 적절한 입증 명령을 명시적으로 적기

이미 저장소 관례를 알고 있다면, 스킬이 그 규칙을 추측하게 두지 마세요. 더 강한 입력 예시는 다음과 같습니다.

• “The canonical project check is make test.”
• “The bug is proven by pytest tests/payments/test_refund.py -q plus npm run build.”

이렇게 해야 불완전한 체크에 기대어 잘못된 자신감을 갖는 일을 줄일 수 있습니다.

구현 상태와 검증 완료 상태를 분리하기

흔한 실패 패턴은 “코드를 바꿨다”와 “이슈가 해결됐다”를 섞어 말하는 것입니다. verification-before-completion usage를 개선하려면 두 부분으로 나눠 답하도록 요청하세요.

• 무엇을 변경했는가
• 실제로 무엇이 검증되었는가

이렇게 하면 실행이 막힌 상황에서도 요약이 정직해집니다.

좁은 체크 결과로 넓은 주장을 하지 않기

하나의 집중 테스트만 실행했다면, 스킬에게 저장소 전체를 인증해 달라고 요청하지 마세요. 더 좋은 표현은 다음과 같습니다.

• “Can I say the targeted regression test now passes?”
• not “Can I say the system is fully fixed?”

이것은 verification-before-completion이 길러주는 가장 가치 높은 습관 중 하나입니다.

증거가 부분적일 때 낮춘 표현을 요청하기

실제 업무에서 verification-before-completion guide를 더 유용하게 만드는 실전 방법 중 하나는 대체 문구까지 요청하는 것입니다.

• “If the claim is too strong for the evidence, rewrite it to the strongest accurate version.”

이렇게 하면 이 스킬은 단순 차단기가 아니라, 커뮤니케이션 품질을 높여주는 도구가 됩니다.

중요한 변경 후에는 다시 실행하기

성공적인 검증 실행 이후에 코드를 다시 수정했다면, verification-before-completion 스킬을 한 번 더 사용하세요. 최신 증거는 이전 초안이 아니라 현재 상태에 연결됩니다. 특히 에이전트가 빠르게 반복 작업하는 흐름에서는 “마지막으로 조금만 수정”한 내용이 앞선 검증을 무효로 만들 수 있어 더 중요합니다.

최종 요약에 증거를 직접 포함하기

신뢰도를 높이려면 완료 노트 안에 증거를 직접 넣으세요.

• 실행한 명령
• pass/fail 결과
• 남아 있는 제한이나 생략 사항

예시:

• “Verified with pytest tests/auth/test_login_bug.py -q: passed, 1 test, 0 failures.”
• “Did not verify full integration suite in this environment.”

이런 스타일은 리뷰어에게도, 미래의 나 자신에게도 verification-before-completion의 가치를 더 크게 만들어 줍니다.

가장 흔한 실패 패턴을 경계하기

verification-before-completion for Skill Validation에서 가장 흔한 오용은 출력 결과가 아니라 의도, 코드 변경, 기대감만으로 성공을 주장하는 것입니다. 더 나은 결과를 원한다면, 완료 메시지 직전에 항상 마지막으로 이 질문을 던지세요.

“이 문장을 참으로 만들려면 어떤 명령 출력이 있어야 하는가?”

이 질문에 명확히 답할 수 없다면, 그 주장은 아직 준비되지 않았을 가능성이 높습니다.