제품 진실성
제품이 실제로 할 수 없는 기능을 보여주는 제품 비디오는 비디오가 없는 것보다 더 나쁩니다. 이 스킬이 비롯된 프로덕션에서 가장 비용이 많이 든 순간은 모두 진실성 실패였습니다: 잘못된 크기와 잘못된 제품 이름이 적힌 수제 배지, 제품이 별도의 트리거를 통해서만 결과를 반환하는데 '호출 결과를 기다리는 중'이라고 설명된 워크플로, 아무도 종단 간 검증하지 않은 확정 예약으로 다시 레이블이 붙은 테스트 호출, 팀이 합의한 포지셔닝과 모순되는 헤드라인이 있는 회사 문서. 각각은 검토자에 의해 늦게 발견되었고, 버전 하나를 추가로 소모했습니다.
이 스킬은 점검을 명시적이고 기계적으로 만듭니다: 모든 줄과 모든 화면은 TRUTH.md에 소스와 함께 행을 가지며, truth_check.py는 어떤 행이든 누락되거나, 오래되었거나, 뒷받침되지 않으면 비디오를 거부합니다.
입력
videos/<video>/audio/lines.tsv(내레이션, 문장 ID당 한 줄)videos/<video>/SOURCES.md(source-recon에서: 화면과 해당 코드)videos/<video>/BRIEF.md,COVERAGE.md,CLAIMS.md(비디오가 설명해야 하는 것, 포지셔닝, 피해야 할 문구, 승인이 필요한 주장)product.yaml:positioning,never_say,names(정식 이름에서 레거시 문자열로),banned_termssources/<role>/및sources.lock(source-recon에 의해 고정됨; 없으면 먼저 source-recon 실행, 인용은 잠긴 커밋을 가리켜야 하므로)
1. 주장 나열
lines.tsv의 각 줄을 그것이 하는 주장으로 분할하십시오. "Acme Tasks는 캘린더를 읽고 기한이 지난 작업을 내일로 이동합니다"는 두 가지 주장입니다: 캘린더를 읽는다, 그리고 기한이 지난 작업을 이동한다. SOURCES.md와 챕터에서 화면당 하나의 주장과 화면상의 동작당 하나의 주장을 추가하십시오("Plan my day를 클릭하면 세 가지 제안과 함께 플래너가 열립니다").
해당 주장이 제기하는 질문을, 코드가 답할 수 있도록 작성하십시오: 무엇이 이것을 트리거하는지, 무엇이 저장되는지, 어떤 옵션이 있는지, 사용자가 무엇을 어디서 보는지, 서버에서만 발생하는 것은 무엇인지.
2. 코드와 문서에서 답하기
제품 영역(프론트엔드 동작, 각 백엔드, 문서)당 하나씩, references/product-facts-prompt.md의 프롬프트와 함께 읽기 전용 하위 에이전트를 병렬로 실행하십시오. sources/<role>/를 가리키고, 사용자의 체크아웃은 절대 가리키지 마십시오. 그래야 줄 번호가 잠금과 일치합니다. 코드나 문서에서만 답하고, 모든 사실을 인용하며, 추측하는 대신 "찾을 수 없음"이라고 말합니다.
3. 각 주장 분류
| 가시성 | 의미 | 비디오에서 할 수 있는 것 |
|---|---|---|
ui | 프론트엔드에 의해 렌더링됨; 템플릿 또는 i18n 줄 인용 | 표시하고 내레이션 가능 |
backend | 서버에서 참이지만, 화면에 아무것도 표시되지 않음 | 내레이션은 가능하지만 UI로는 절대 그리지 않음 |
docs | 문서만 말함 | 문서 URL과 함께 내레이션 가능; 가능할 때 코드가 동의하는지 확인 |
mock | 디자인된 조각, 제품 UI 아님 (전화 통화 화면, 엔드 카드, 생성된 텍스트) | 표시 가능, BRIEF에서 설계된 것으로 표시됨 |
| 판정 | 의미 |
|---|---|
backed | 소스가 정확히 이것을 말함 |
approved | 필요한 서명(제한됨, 미출시, CLAIMS.md가 나열하는 주장)을 검토자가 CLAIMS.md에서 부여함 |
needs-approval | 사실이지만, 제한됨, 게이트됨, 미출시 또는 CLAIMS.md에 나열됨; 검토자 대기 중 |
rewrite | 부분적으로 사실임; 메모에 뒷받침되는 표현을 제안함 |
cut | 사실이 아니거나 소스를 찾을 수 없음 |
unbacked | 아직 확인되지 않음 |
mock | 가시성이 mock인 경우에만 |
내레이션된 줄에는 backed와 approved만 통과합니다. 일부 역할, 플랜 또는 내부 팀에만 표시되는 제한된 기능, 플래그 뒤에 있는 기능, 또는 병합되지 않은 브랜치에 있는 기능은 검토자가 CLAIMS.md에서 승인할 때까지 needs-approval이며, BRIEF는 이것이 제한된 기능임을 명시합니다. 이것은 소스 프로덕션에서 발생했습니다: 내부 직원만 볼 수 있는 기능이 검토자의 요청에 따라 표시되고 표시되었습니다.
4. 맞지 않는 것 수정
- 부분적으로 사실인 문장을 소스가 지원하는 가장 강력한 버전으로 재작성하십시오. 작가가 원했던 의미는 유지하고, 메커니즘은 실제 메커니즘으로 변경하십시오.
- 소스가 없는 것은 잘라내십시오. 모호하게 부드럽게 만들지 마십시오; 모호한 주장은 여전히 주장입니다.
- 레이블이 표류하지 않도록 하십시오. "예시용"으로 표시된 디자인 조각은 레이블이 없는 버전이 만드는 주장을 다시 확인하지 않고 미적 이유로 나중에 해당 레이블을 잃어서는 안 됩니다.
- 포지셔닝이 문서보다 우선합니다. 덱이나 PRD가
never_say또는 CLAIMS.md가 금지하는 것을 말하면, 규칙이 이기고 문장이 변경됩니다. - 현재 이름만 사용하십시오. 라이브 UI나 코드에 여전히 레거시 문자열이 표시되더라도
product.yaml names의 정식 이름을 사용하십시오. lines.tsv, 스펙 및 템플릿에서 모든 레거시 문자열과 모든banned_terms항목(경쟁사, 팀이 화면에 표시하지 않는 타사 공급업체, 실제 고객)을 검색하고 각각을 수정하십시오.
5. 요청이 제품과 충돌할 때
브리프나 검토자가 코드가 지원하지 않는 것을 요청할 때, 가짜를 만들거나 조용히 버리지 마십시오. 옵션과 권장 기본값이 있는 하나의 폐쇄형 질문을 하고, 라운드당 최대 세 개의 질문으로 유지하십시오. 거부권의 공개 목록은 답변되지 않고 침묵은 아무도 내리지 않은 결정이 되기 때문입니다. "실제만" 패턴:
브리프는 Acme Tasks가 회의실을 직접 예약한다고 보여줍니다. 코드는 작업을 생성하고 회의실 캘린더를 연결할 뿐입니다(frontend/src/rooms/LinkRoom.tsx:22@1a2b3c4); 예약은 캘린더 앱에서 발생합니다. 어떤 것을 선택하시겠습니까?
- 실제만 (권장): 연결 단계를 보여주고 "회의실 캘린더를 연결합니다"라고 말합니다.
- 캘린더 앱의 예약 화면을 레이블이 있는 디자인 조각으로 표시하고 캘린더 단계로 내레이션합니다.
- 해당 비트를 삭제합니다.
답변을 CLAIMS.md에 기록하고 그로부터 판정을 설정하십시오.
6. TRUTH.md 작성
# 진실: <video>
잠금: 프론트엔드 main@1a2b3c4, 백엔드 main@5d6e7f8. 확인: 2026-01-12.
| id | 문장 | 소스 | 가시성 | 판정 | 메모 |
|---|---|---|---|---|---|
| N1 | Acme Tasks가 캘린더에서 하루를 계획합니다. | frontend/src/planner/plan.ts:31@1a2b3c4; https://docs.example.com/planner | ui | backed | |
| N2 | 기한이 지난 작업은 자정에 내일로 이동합니다. | backend/jobs/rollover.py:12-30@5d6e7f8 | backend | backed | 화면에 표시되지 않음 |
| screen:board | 세 개의 작업이 있는 보드, 하나는 기한 초과 | frontend/src/pages/board/BoardPage.tsx:14@1a2b3c4 | ui | backed | |
| screen:call | 고객과의 전화 통화 | (설계됨) | mock | mock | BRIEF에 표시됨 |
## 열린 질문
1. <권장 답변이 있는 폐쇄형 질문>
lines.tsv의 줄 ID당 하나의 행, 문장은 정확히 복사됨(검사가 비교하므로, 진실성 패스 후 줄을 편집하면 다시 확인할 때까지 실패함). 화면당 하나의 행, id는 screen:<name>이며 SOURCES.md와 일치함. 여러 인용은 세미콜론으로 구분하여 한 셀에 들어갑니다.
7. 확인
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/product-truth/scripts/truth_check.py" <video_dir>
다음과 같은 경우 실패합니다: 행이 없는 줄, 변경된 문장, 내레이션된 줄에서 backed 또는 approved 이외의 판정, 잠기지 않은 역할의 인용, 잠긴 sha가 아닌 sha(코드가 이동함; 다시 확인), 내보내기에 없는 파일, 또는 파일 끝을 넘는 줄. 모든 실패를 수정하십시오; 검사는 편집하지 마십시오.
사용자에게 보고: 뒷받침된 줄과 화면 수, 재작성하고 잘라낸 내용(이유 포함), 승인 대기 중인 내용, 및 열린 질문.