작동 증명 (Proof It Works)
이 스킬은 작업이 '완료됨'이라고 불릴 수 있는지 여부를 결정합니다. 이는 조언이 아니라 엄격한 게이트입니다.
1. 핵심 법칙: 완료 = 입증됨
- 주장은 증거가 아닙니다. 다른 에이전트가 검사할 수 있는 재현 가능한 결과물만이 증거로 인정됩니다.
- 섹션 6의 필수 게이트 항목이 하나라도 누락된 경우, '완료됨', '수정됨', '통과', '배송됨'이라고 말할 수 없습니다.
- '작동할 것이다', '올바른 것 같다', '이론적으로 괜찮다', '컴파일된다'는 완료 상태가 아닙니다.
- 증명이 불가능한 경우, 통과(PASS)가 아닌 UNAVAILABLE/BLOCKED(섹션 7)로 선언하십시오. 서면 사용자 면제는 FAIL을 FAIL-WAIVED(섹션 7)로 마감할 수 있습니다. 기계적으로 테스트할 수 없는 차원은 PENDING USER 상태로 유지될 수 있으며 사용자 승인 시 PASS-BY-USER(섹션 7)로 마감됩니다. 이 세 가지(FAIL-WAIVED, PENDING USER, PASS-BY-USER)는 기계 증거가 아닌 유일한 종료 조건입니다. 이 중 어느 것도 PASS가 아닙니다.
- 증거는 작업 트리와 보고서(섹션 3,
Change ref)에 명명된 변경 커밋에서 가져와야 합니다. 오래된 결과물은 유효하지 않습니다. - 이 스킬은 런타임 표면 또는 설계 결과물이 있는 작업만 게이트합니다. 해당 작업의 경우, 최소 증거 집합(하나의 긍정 + 하나의 역 사례)은 더 가벼운 검사를 대체하며 추가하지 않습니다. 런타임 표면이 없는 작업은 범위를 벗어나며 이 스킬은 완전히 적용되지 않습니다. 사용자가 이미 최소한으로 승인한 전달을 재정의하지 않습니다.
2. 증거 수준
세 가지 수준이 엄격한 순서로 있습니다: 주장 (Claim) (언어적 또는 추론, 증거 없음) < 결과물 (Artifact) (이 작업의 표면에서 나온 실제 원시 결과물 파일) < 결과물 + 역 사례 (Artifact + reverse case). 게이트는 마지막 두 가지만 허용합니다. 항목에 필요한 수준은 전역 규칙이 아니라 선택한 프로필의 게이트 항목에 의해 설정됩니다. 주장 (Claim)은 결코 PASS를 지원하지 않으며, 어떤 항목도 실제보다 높은 수준으로 레이블될 수 없습니다.
3. 바인딩 / 任务绑定
report.md상단에 사용자 요청에서 승인 대상을 정의하는 문장을 그대로 인용하십시오. 'X를 Y로 변경하고 증명하십시오'와 같은 지시도 포함됩니다. 작업이 완료되었음을 명시할 필요는 없습니다.Acceptance target (user verbatim)레이블을 붙이십시오. 요청이 승인 대상을 전혀 정의하지 않은 경우(무엇이 '완료'처럼 보여야 하는지 전혀 명시하지 않은 경우), 한 줄로 명시하고 사용자에게 이를 요청한 후 중단하십시오. 게이트할 내용이 없습니다. 섹션 2의 증거 수준주장 (Claim)은 별도의 개념이며 이름을 유지합니다.Change ref(보고서 헤더) = 테스트 중인 변경 사항을 포함하는 커밋입니다. 이 보고서를 추가하는 커밋이 아니며 반드시 HEAD일 필요도 없습니다. git이 없는 경우 해시 대신변경된 파일의 sha256 + 파일 목록을 사용하십시오. 보고서가 커밋된 후 HEAD가 앞으로 이동하는 것은 정상이며, 검증자는 HEAD가 아닌Change ref로 판단합니다.Working tree(보고서 헤더)는 두 값 열거형이 아닌 자유 텍스트입니다. 예:tracked clean; .proof/ untracked.- 이 변경 사항이 건드린 파일/함수/라우트/컴포넌트를 현재 diff에서 가져와 선언하십시오.
- 선택된 모든 프로필에는 이 diff에 도달하는(건드린 경로를 실행하거나 검사하는) 증거 항목이 하나 이상 있어야 합니다. 모든 결과물이 존재하더라도 diff에서 아무것도 건드리지 않는 증거는 FAIL입니다.
- DESIGN 기준선은 외부 소스(섹션 6, proof-profiles.md)가 있어야 합니다. 추적할 수 없는 기준선은
주장 (Claim)이며 게이트 항목에서 실패합니다.
4. 증명 프로필 선택
한 줄 테스트가 사용자의 승인 대상 문장에 가장 잘 맞는 프로필을 선택하십시오. 하나의 작업이 DESIGN과 FEATURE을 동시에 가질 수 있으며, 이 경우 두 가지를 모두 충족해야 합니다. 일치하는 프로필이 없으면 한 줄로 명시하고 중단하십시오. 런타임 표면이 없는 변경 사항에 프로필을 강제로 적용하지 마십시오.
| 프로필 | 한 줄 테스트 | 세부 사항 |
|---|---|---|
| DESIGN | 명세서, 레이아웃, 상호작용, 아키텍처 또는 계약서를 생성했으며, 이것이 제안된 것이 아니라 실제로 구현되었음을 보여야 합니다. | references/proof-profiles.md |
| FEATURE | 런타임 동작을 변경했으며, 이것이 작동하고 잘못된 입력이 거부됨을 보여야 합니다. | references/proof-profiles.md |
| DATAFLOW | 값이 여러 단계(입력, 변환, 영속성, 종료)를 거치며 각 홉이 표시되어야 합니다. | references/proof-profiles.md |
- "내 설계가 구현되었나요?" -> DESIGN. "이것이 작동하나요?" -> FEATURE. "데이터가 어디로 갔나요/영구 저장되었나요?" -> DATAFLOW.
5. 실행 흐름
순서대로 실행하십시오. 건너뛰거나 순서를 바꾸지 마십시오.
- 저장소에
.proof/<task-name>/를 생성하십시오(짧은 케밥 케이스 이름). 결과물이 여기에 파일이 될 때까지 증거가 아닙니다. - 증거를 수집하기 전에
report.md에 3-7개의 승인 어설션을 작성하십시오. 8개의 열을 사용하십시오:id | assertion | expected | pass criterion (checkable) | changed path (file:function/route) | level required | evidence file | depends on. "올바른 것 같다", "괜찮아 보인다", "예상대로 작동한다"를 금지합니다. 확인 가능한 조건을 사용하십시오. 예: "HTTP 200 with body.field X = Y", "rect width = 120px", "유효하지 않은 토큰은 401을 반환한다".expected는 증거 수집 전에 채워진 예측 결과입니다(예:401 + BAD_CREDENTIALS,rect width 240px). FEATURE/DATAFLOW는 모든 행에 이것을 채워야 합니다. DESIGN은n/a를 쓸 수 있습니다. 보고서 헤더에 등록 시간을Expected registered (UTC): <time>으로 기록하십시오. 사전 등록은 자체 선언이며 해시나 디스크 의식은 없습니다.expected와pass criterion은 하나의 조건에 대한 두 가지 표현(예측 대 결정 가능한 검사)입니다. 이들은 충돌해서는 안 됩니다. 충돌하는 행은 수집 전에 수정되어야 합니다. 상태는 오로지pass criterion과observed에 대해서만 결정됩니다.observed가 기준을 충족하지만expected와 다른 경우,expected와 일치하도록 구현을 수정하거나 어설션을 FAIL로 표시하십시오.expected를 관찰된 값으로 다시 쓰지 마십시오(섹션 8).changed path를 어설션이 실행하는 파일/함수/라우트로 채우십시오. 코드 경로를 실행하지 않는 DESIGN 행에만n/a를 쓰십시오. 하나 이상의 어설션은 이 diff에서 변경된 코드 경로를 실행하고 이름을 지정해야 합니다. 건드리지 않은 경로에 대한 어설션은 바인딩되지 않습니다. FEATURE/DATAFLOW는 적어도 하나의n/a가 아닌changed path셀이 있어야 합니다. DESIGN은n/a를 사용할 수 있습니다.depends on= 쉼표로 구분된 선행 조건 id입니다(없으면 비워 둠). 위상 순서로 수집됩니다. 선행 조건은 해당 상태가PASS또는PASS-BY-USER인 경우에만 충족된 것으로 간주됩니다. 다른 상태인 경우 다운스트림 행은NOT RUN(섹션 7)이며NOT RUN은 게이트를 FAIL로 만듭니다.depends on그래프는 비순환적이어야 합니다. 순환은 FAIL입니다.USER-JUDGMENT행은 리프입니다. 어떤 행도depends on에USER-JUDGMENTid를 나열할 수 없습니다.
- 이 머신에서 실제로 사용 가능한 명령어로 실제 표면을 구동하십시오(예:
npm run dev로 시작,curl -i -X POST http://localhost:3000/login -d '{"user":"a","pass":"wrong"}'API용, 실제 브라우저 + DevTools UI용,tail -f로그용). 원시 stdout/stderr/응답/스크린샷을 번호가 매겨진 파일로 저장하십시오(섹션 11).원시( raw)= 캡처된 완전한 출력이며 요약, 발췌 또는 재정렬되지 않습니다. 민감 정보 제거는 캡처 시점에 적용되는 일회성 변환으로, "원시"를 위반하지 않습니다. 저장된 파일에서 토큰/비밀번호/키를***로 바꾸고, 증거 인덱스와 각 붙여넣은 원시 블록 옆에redacted: <field name> (N occurrence(s))와 파일의 sha256을 기록하여 검토자가 캡처 후 편집이 없음을 확인할 수 있도록 하십시오. 상태 코드, 오류 코드 또는 어설션이 의존하는 값을 민감 정보 제거하지 마십시오. 보고서에<启动命令>/<截图工具>스타일의 플레이스홀더가 남아 있으면 FAIL입니다. 실행한 정확한 명령어로 바꾸십시오. - 먼저 역 사례를 처리하십시오. "하나의 변경된 동작"을 diff에서 추가되거나 수정된 각 분기(if/else, 가드, 유효성 검사 또는 새 라우트)로 정의하십시오. 각각을 보고서에 나열하고 어설션 테이블에 행을 지정하십시오. 경계 사례는 결정 가능합니다. 동일한 입력이 변경 전 구현에서 허용(또는 다르게 동작)되고 변경 후 거부(또는 올바르게 동작)됩니다. 원본을 재구성하여 변경 전 기준선을 캡처하십시오.
git stash, 변경 전 커밋의 작업 트리/체크아웃, 또는 원본 파일의 저장된 복사본을 사용하십시오. 이를 보고서에 명시하고, 동일한 명령어를 실행하여 결과를00-pre-change.log(섹션 11)로 저장하십시오. 이 "변경 전에는 실패함을 보여주는" 단계는 역 사례 기준선이며, 절대 터미널 FAIL 어설션 행이 아닙니다(섹션 9). 그런 다음, 각 변경된 동작에 대해 하나의 역 사례(잘못된 입력, 누락된 권한, 경계 값, 제거된 선행 조건)를 실행하고 예상된 방식으로 실패하는지 기록하십시오. 변경 전에도 실패한 나쁜 사례는 계산되지 않습니다. 변경 후에 사례가 수락되면 테스트가 실제 경로에 있는 것이 아닙니다. 수정하고 다시 수집하십시오. - 데이터 흐름: 수집 전에
report.md에 예상 변환 한 줄(입력 형태 -> 출력 형태)을 작성하고 모든 홉에서 이를 참조하십시오. 그런 다음 홉당 하나의 실제 샘플(입력 -> 중간 -> 영속성 -> 종료)을 동일한 상관 ID로 캡처하십시오. 영속성의 경우 실제 읽기 쿼리와 저장소의 원시 반환 값을 붙여넣으십시오. 작성한 값을 다시 인쇄하는 것은 스냅샷이 아닙니다. 또한 4단계(00-pre-change.log)당 역 사례에 대한 변경 전 기준선을 캡처하십시오. 변경 전에 거부된 값이 종료에 도달하는 것을 보여야 합니다. - DESIGN 관찰 값은 기계적으로 캡처된 소스(계산된 스타일 JSON,
getBoundingClientRect, DOMtextContent, CDP 출력)에서 가져와 파일로 저장해야 합니다. 스크린샷에서 숫자를 눈으로 읽지 마십시오. 기준선은 수치 허용 오차(측면당 <=2px, 채널당 <=8)를 제공해야 합니다. 이를 초과하면 FAIL입니다. 스크린샷은 인간의 눈 검토용일 뿐이며 숫자 소스가 아닙니다. - references/report-template.md에서 보고서를 작성하십시오. 복사하고 형식을 발명하지 마십시오. 선택한 프로필과 관련된 섹션만 유지하고 적용되지 않는 섹션은 완전히 삭제하십시오. 삭제해도 "복사하고 형식을 발명하지 마십시오"를 위반하지 않습니다.
- 게이트 판단(섹션 6): 모든 필수 항목이 필요한 수준에 존재하고, 모든
USER-JUDGMENT가 아닌 어설션이PASS/PASS-BY-USER이고, 하나 이상의 어설션이 기계 판결을 제공하며,depends on순환이 없는 경우에만 PASS입니다. 그렇지 않으면 FAIL, UNAVAILABLE/BLOCKED 또는 PENDING USER입니다(섹션 7).Gate와Result는 동일한 열거형을 사용하며 동일해야 합니다.
6. 하드 게이트 (항목 하나라도 누락 = FAIL)
"완료"는 모든 상자가 체크되어야 합니다. 누락된 파일, 누락된 역 사례, 실제 경로의 모의, 또는 diff 외부의 증거는 설명 여부에 관계없이 FAIL입니다.
- 완전성(알 수 없는 항목 없음): 보고서는 어설션 총계 N을 명시하고 N개의 각 어설션에 대한 상태를 나열합니다. 허용되는 상태는
PASS | FAIL | NOT RUN | UNAVAILABLE | BLOCKED | USER-JUDGMENT | PASS-BY-USER뿐입니다. 빈 상태, 이 집합 외부의 상태, 또는 N과 다른 나열된 개수는 FAIL입니다. PASS는 모든USER-JUDGMENT가 아닌 행이PASS/PASS-BY-USER이고FAIL/NOT RUN/UNAVAILABLE/BLOCKED가 없어야 합니다. USER-JUDGMENT는 결정 가능한 기계 기준이 없는 차원에만 허용됩니다. 기계가 행을 판단할 수 있거나 판단했으며 조건이 유지되지 않는 경우, 해당 상태는 기계 판결(PASS/FAIL)입니다. 절대USER-JUDGMENT가 아닙니다. 기계가 측정할 수 있는 모든 것은 기계 판결이 있는 자체 행이어야 합니다. 이 diff에 바인딩된 어설션(섹션 3)은 절대USER-JUDGMENT가 될 수 없습니다. 모든 어설션이USER-JUDGMENT인 보고서는 진공 상태에서 참인 PASS 조건을 가지며 FAIL입니다. 하나 이상의 행이 기계 판결을 제공해야 합니다. 기계 테스트를 거쳐 기준을 충족하지 못하면USER-JUDGMENT가 아닌 FAIL입니다.depends on은 DAG입니다. 순환은 FAIL입니다. 선행 조건은PASS또는PASS-BY-USER에 의해서만 충족됩니다. 어떤 행도USER-JUDGMENT행에 의존할 수 없으므로 이러한 행은 리프입니다.- 전역: 바인딩이 유효하고(섹션 3), 하나 이상의 어설션이 diff에 바인딩됩니다(섹션 5, 2단계).
USER-JUDGMENT행은 결코 PASS로 계산되지 않으며 다른 항목의 PASS를 차단하지 않습니다.
| 프로필 | 최소 증거 집합 — 모두 필요 |
|---|---|
| DESIGN | (a) 외부 소스가 있는 기준선 결과물: 사전 존재하는 설계 파일 + 생성 커밋, 또는 이를 포함/승인하는 사용자의 축어적 메시지, 또는 구현 파일이 존재하기 전에 기준선 파일로 랜딩된 사양 테이블과 랜딩 시점에 채워진 고정 메타 블록(source_type, source_quote_or_path, captured_at_utc, sha256, baseline_method); 구현에서 기준선으로 값을 역공학하는 것은 금지됨; (b) 변경 커밋에서 실제 렌더링 스크린샷; (c) 범위 내 모든 요소(범위 = 설계 결과물에 명명된 모든 요소; 제외된 요소와 이유 나열)에 대한 크기, 색상, 간격, 텍스트, 상태 비교, 각 행은 기준선 값과 기계적으로 얻은 관찰 값을 인용하며 기준선에 명시된 수치 허용 오차(측면당 <=2px, 채널당 <=8); (d) 허용 오차 경계에 있는 값(예: +/-2px에서 240px 사양에 대한 243px)이 원시 출력을 통해 부재/불일치로 표시된 하나의 역 항목; (e) 명시적으로 선언된 사격 공백: 해석(구현 전에 작성된 기준선 읽기, 위치/매핑만 추가, 사용자 값을 절대 모순하지 않음), 제외됨(기준선 값이 존재하지 않음, 그대로 작성됨), UNAVAILABLE(값은 존재하지만 여기서 측정할 수 없음) — 제외됨 및 UNAVAILABLE은 별도의 보고서 섹션에, 묵시적 누락 금지; (f) diff에 하나 이상의 증거 항목. |
| FEATURE | (a) 변경 커밋에서 변경된 코드 경로를 실행하는 하나의 실제 구동 I/O 기록; (b) 변경된 동작당 하나의 역 사례, 결정 가능한 경계에서 잘못된 입력(변경 전에 허용/다름, 변경 후 거부/올바름), 변경 전 기준선 00-pre-change.log와 올바른 거부를 보여주는 원시 출력 지원 — 변경 전에도 실패한 사례는 계산되지 않음; (c) 정확한 명령어/작업 및 변경 참조 기록; (d) 모든 어설션은 changed path가 채워진 파일에 매핑되고, 하나 이상의 어설션은 변경된 경로를 실행하고 변경된 파일/함수/라우트의 이름을 지정함; (e) 체인을 대체하는 모의/스텁 없음; (f) diff에 하나 이상의 증거 항목. |
| DATAFLOW | (0) 수집 전에 작성되고 각 홉에서 참조되는 예상 변환 라인(입력 형태 -> 출력 형태); (a) 동일한 상관 ID를 가진 홉당 하나의 스냅샷(입력, 중간, 영속성, 종료); (b) 영속성 스냅샷은 저장소의 실제 읽기 쿼리 + 원시 반환을 붙여넣으며, 작성된 값을 재인쇄하지 않음; (c) ... (이하 생략) |