teardown은 왜 스킬의 모범인가 — 직접 실행해서 확인했다
機械翻訳 / Machine-translated
機械翻訳 / Machine-translated
원문: teardown은 왜 스킬의 모범인가 직접 실행해서 확인했다（cccskills）
스킬 페이지: teardown
이 글의 결론
teardown은 실재하는 기계를 분해할 수 있는 3D 시뮬레이터를 한 장의 HTML로 구성하고, 동영상과 소리까지 출력하는 스킬입니다.
cccskills에서는 스킬 작성법의 모범으로서 '추천' 첫 번째로 선정했습니다.
이 글에서는 모범이라고 부를 수 있는 이유를 세 가지 들고, 직접 실행한 결과와 평소의 실행 검증을 거친 결과를 보고합니다.
teardown은 실재하는 기계를 '분해할 수 있는 3D 시뮬레이터'로서 한 장의 HTML에 구성하는 스킬입니다.
엔진이나 비행기의 착륙 장치, 보행 기구 등을 버튼으로 부품별로 열거나 단면으로 보면서 작동시킬 수 있습니다.
주변의 계기판이나 그래프는 부품을 움직이는 것과 동일한 계산에서 숫자를 출력합니다.
아무도 조작하지 않으면, 페이지는 커서를 직접 움직여 볼거리를 안내하는 구조입니다.
클릭이나 드래그로 조작이 보는 사람에게 넘어가며, 25초 동안 아무것도 하지 않으면 안내 모드로 돌아옵니다.
동일한 대본에서 60fps 동영상을 프레임 단위로 출력하고, 같은 시각표에 맞춰 소리도 생성합니다.
cccskills에서는 이 스킬을 'cccskills 추천' 첫 번째로 선정했습니다.
눈길을 끄는 외관보다 내부 작성 방식이 뛰어나기 때문입니다.
이하에서 모범이라 할 수 있는 이유와 직접 확인한 결과를 순서대로 설명합니다.
teardown의 핵심 규칙은 '실제 치수의 숫자를 먼저 모으고, 하나의 입력으로 모든 것을 움직인다'입니다.
엔진이라면 크랭크 각도, 비행기 착륙 장치라면 0에서 1까지의 신축량, 스트란드비스트라면 풍속이 입력이 됩니다.
부품의 자세도, 패널의 숫자도, 그래프도 그 입력의 함수로 계산합니다.
이렇게 하면 화면의 숫자와 움직임이 어긋나는 일이 원리적으로 발생하지 않습니다.
수동으로 키프레임을 입력하지 않으므로, 조작할 수 있는 페이지와 녹화한 동영상, 소리도 어긋나지 않습니다.
SKILL.md에는 검산 예시까지 작성되어 있습니다.
Cessna의 예에서 32개 이빨 × 모듈 4mm이면 피치원 직경은 128mm.
그 반주가 201mm의 스트로크가 된다.
직접 계산하면 π×128÷2는 201.06mm였습니다.
코드의 상수도 pinionR: 0.064（32개 이빨, 모듈 4mm）와 stroke: 0.201로, 문서와 구현이 일치합니다.
스트란드비스트 작례는 테오 얀센의 13개 치수（a=38에서 m=15까지）를 원전 그대로 가지고 있습니다.
크랭크를 720프레임 돌려 각 링크의 길이를 다시 측정하면 오차는 최대 1e-14였습니다.
발끝의 상하 폭은 22.5이고, 지면으로부터 1단위 이내에 있는 구간은 크랭크 155°분으로, 코드의 주석 '약 155°'와 일치합니다.
스킬에는 V8 엔진, 세스나 337의 주 착륙 장치, 스트란드비스트 세 가지가 완전한 형태로 포함되어 있습니다.
세 가지 모두 같은 구성 방식으로 작성되어 있으며, 새로운 기계는 가장 가까운 작례의 복사본에서 시작하는 규칙입니다.
| 파일 | 역할 |
|---|---|
| kin.js 등 | 계산만. 실제 치수와 하나의 입력에서 자세와 표시 숫자를 출력. three.js 미포함 |
| engine.js 등 | 형태. 코드로 부품을 만들고, update(input)으로 자세를 결정 |
| console.js | 계기판이나 그래프의 오버레이 표시. 프레임 상태에서 다시 그림 |
| film.js | 대본과, 시각만으로 한 프레임을 그리는 render(t) |
| live.js | 조작할 수 있는 페이지. 그대로 두면 대본대로 자동 안내 |
| score.py | 대본의 시각에 맞춘 소리 |
계산과 렌더링이 분리되어 있으므로, 계산만을 Node로 검산할 수 있습니다.
render(t)는 시각만으로 한 프레임을 그리는 순수 함수이며, 난수나 시계를 사용하지 않는 규칙입니다.
촬영용 코드를 검색하면 Math.random과 Date는 하나도 없고, performance.now는 실시간 조작용 live.js에만 있었습니다.
SKILL.md에는 '당신은 동영상을 볼 수 없다.
볼 수 있는 것은 프레임뿐이다'라고 쓰여 있습니다.
그 위에서, 볼거리별 정지 화면을 나열한 시트를 만들고, 체크리스트와 대조하고, 수정하고 다시 촬영하는 절차를 정해 두었습니다.
마쳐도 되는 조건은 '처음부터 끝까지 아무것도 발견되지 않게 되었을 때'입니다.
체크리스트는 구체적입니다.
닿아야 할 부품이 닿아 있는지, 가장자리로부터 60px 이내에 중요한 것이 없는지, 1080 화면에서 글자가 34px 미만이 되지 않는지 같은 항목이 나열되어 있습니다.
발광은 1.0 미만, 큰 금속 면은 거칠기 0.45 이상 등 three.js에서 외관이 무너지는 상황의 수치도 작성되어 있습니다.
또 하나 좋은 점은, 작성자가 실제로 겪은 함정을 남겨 두었다는 것입니다.
Windows의 ANGLE에서 smoothstep의 인수가 역순이면 0이 된다, NaN이 1픽셀 발생하면 블룸으로 화면 전체가 검게 된다 같은 5건이 이유와 함께 나열되어 있습니다.
Apple M2 Ultra Mac에서 README의 절차대로 시도했습니다.
Mac에서는 한 가지 걸림돌이 있었습니다.
Playwright가 기본으로 사용하는 경량 Chromium에서는 WebGL을 생성할 수 없어 촬영이 60초에서 멈춥니다.
환경 변수 CHROMIUM에 일반 Chromium을 지정하면 Metal 경유로 GPU를 사용해 촬영할 수 있었습니다.
촬영할 때마다 사용한 GPU를 표시하는 구조이므로 원인을 바로 알 수 있습니다.
SKILL.md는 '볼거리의 시각은 모두 timeline.json에 작성하고, 소리도 같은 파일을 읽는다'고 정하고 있습니다.
그런데 세 가지의 timeline.json에는 동영상 길이만 들어 있었습니다.
V8의 소리를 생성하는 score.py는 대본의 시각을 CLICKS = (3.5, 6.9, …)처럼 수동으로 옮겨 적고 있습니다.
지금은 값이 일치하고 있으므로 소리는 어긋나지 않습니다.
다만, 대본의 시각을 변경하면 소리만 뒤처지게 됩니다.
볼거리별 정지 화면을 찍는 --stills beats도, 최종 확인에 사용하는 sheet.mjs도, 볼거리의 시각이 없어서 1프레임 또는 0프레임밖에 출력되지 않았습니다.
이번에는 대본에서 시각을 직접 가져와 지정하고 확인을 계속했습니다.
모범으로 추천하는 이상 이 허점도 작성해 둡니다.
자신의 스킬에 도입할 때는 규칙뿐만 아니라 작례가 그것을 지키고 있는지도 확인하세요.
cccskills의 실행 검증은 동일한 의뢰를 '스킬 없음'과 '스킬 있음'의 Claude Code에게 풀게 하여 비교합니다.
검증용 환경에는 Node.js와 Python의 표준 라이브러리만 있고, 패키지 추가도 인터넷도 사용할 수 없습니다.
teardown이 의존하는 three.js, esbuild, Playwright, ffmpeg는 모두 동작하지 않는 환경입니다.
이 조건으로 과제를 자동으로 생성하면 다음 두 문제가 되었습니다.
동일한 두 문제를 직접 스킬 없음과 스킬 있음에 각각 한 번씩 풀게 했습니다.
응답자는 화면을 볼 수 없는 설정이므로, 완성된 페이지는 필자가 브라우저에서 열어 비교했습니다.
엔진 과제는 비슷한 수준이었습니다.
둘 다 90°에서의 피스톤 위치를 30.875mm（수계산과 일치）로 출력하고, 단면 표시, 카메라, 자동 안내까지 작동했습니다.
스킬 있음은 '밝은 배경에 강조색 하나'라는 SKILL.md의 취향에 맞는 화면이 되었습니다.
다만, 스킬 없음의 화면도 충분히 보기 좋았으며 우열을 가리기 어려운 결과였습니다.
차이가 나타난 것은 스트란드비스트였습니다.
자동으로 생성된 링크 표는 결선이 두 곳 뒤바뀌어 있었습니다（d와 e, h와 i）.
표대로 조립하면 필자의 계산으로는 360° 중 264°에서 기구가 조립되지 않습니다.
스킬 없음은 표대로의 결선 그대로, 풀 수 있는 조합을 전수 탐색했습니다.
발의 궤적은 바닥이 평평해지지 않았고, 최하점으로부터 1단위 이내에 있는 것은 크랭크 29°분뿐이었습니다.
접지 판정을 6단위까지 느슨하게 하여 앻숙을 맞추고 있습니다.
스킬 있음은 SKILL.md와 스트란드비스트 작례를 읽은 뒤, 표의 발 삼각형이 원전과 다르다고 지적했습니다.
원전대로의 결선으로 조립하여 최하점으로부터 1단위 이내의 구간은 155°로, 작례와 같은 궤적이 되었습니다.
'상상이 아니라 참조에서 만든다'는 규칙 1과 작례의 존재가 효과를 발휘한 형태입니다.
즉, 도구를 사용할 수 없는 환경에서도 작성 방식 부분은 제대로 효과가 있었습니다.
한편, teardown의 강점인 촬영과 재검토 절차는 이번 검증에서는 측정할 수 없었습니다.
실행 검증의 점수만으로 이 스킬을 판단하면 장점의 절반을 놓치게 됩니다.
teardown에서 가져올 수 있는 작성 방식은 기계의 3D에 국한되지 않습니다.
teardown은 완성되는 3D의 외관보다, 그에 이르는 작성 방식이 뛰어난 스킬입니다.
숫자의 출처를 하나로 모으고, 작례로 패턴을 제시하며, 볼 수 없는 출력을 볼 수 있는 형태로 만들어 확인하게 합니다.
직접 검증에서도 주요 숫자와 외관은 SKILL.md의 기술대로였습니다.
작례의 timeline.json이 비어 있다는 허점은 있지만, 수정 방법은 명확합니다.
스킬을 작성하는 분은 한 번 SKILL.md를 처음부터 끝까지 읽어 보세요.
이 글은 cccskills의 읽을거리 「teardown은 왜 스킬의 모범인가 직접 실행해서 확인했다」의 전재입니다.
스킬의 상세 내용과 설치 방법은 cccskills의 teardown 페이지에 있습니다.
