plz

plz-3d-explain

기술 개념과 시스템 구조를 three.js 3D 모형으로 공부하는 단일 HTML 학습 페이지를 만드는 Claude Code와 Codex용 스킬입니다.

데스크톱: 4장 컨테이너

데스크톱에서 왼쪽 설명과 오른쪽 컨테이너 3D 모형을 함께 보는 화면

휴대폰: 8장 OS 샌드박스

휴대폰에서 위쪽 OS 샌드박스 3D 모형과 아래쪽 설명을 보는 화면

AI 에이전트 코드 샌드박스 데모를 한국어나 영어로 브라우저에서 바로 열어 볼 수 있습니다. 컨테이너, 마이크로VM, WASM, OS 샌드박스의 격리 방식을 10장으로 설명합니다. 예제 HTML(한국어, 영어)도 저장소에 있습니다. codekongdev(코드콩)가 만드는 plz 시리즈의 스킬입니다.

![works with Claude Code

Codex](https://img.shields.io/badge/works%20with-Claude%20Code%20%7C%20Codex-555555.svg)

설치

npx skills로 설치하려면 Node.js 22.20 이상(npm과 npx 포함), Git, 사용할 Claude Code 또는 Codex가 필요합니다. 먼저 터미널에서 도구를 확인합니다.

node --version
npm --version
git --version

사용할 에이전트의 명령을 선택하세요. -g로 전역 설치하면 여러 프로젝트에서 사용할 수 있습니다.

Claude Code:

npx skills add codekongdev/plz --skill plz-3d-explain -a claude-code -g

Codex:

npx skills add codekongdev/plz --skill plz-3d-explain -a codex -g

현재 프로젝트에서만 쓰려면 해당 프로젝트 폴더에서 위 명령의 -g를 빼고 실행합니다. 설치 도구는 .agents/skills/에 스킬을 저장하고, Claude Code를 선택하면 연결도 만듭니다.

사용할 에이전트의 설치 목록에 plz-3d-explain이 표시되는지 확인합니다.

npx skills list -g -a claude-code
npx skills list -g -a codex

프로젝트에 설치했다면 확인 명령에서도 -g를 빼고 같은 프로젝트에서 실행합니다. 목록에 없다면 선택한 에이전트와 설치 범위를 확인하세요. 목록에 있지만 에이전트에서 인식하지 못한다면 사용할 프로젝트에서 새 에이전트 세션을 시작합니다.

Claude Code에 수동으로 설치하려면 저장소를 내려받은 뒤 skills/plz-3d-explain 폴더를 ~/.claude/skills/plz-3d-explain에 복사하거나 링크합니다. 복사하는 명령은 다음과 같습니다.

git clone https://github.com/codekongdev/plz.git
mkdir -p ~/.claude/skills
cp -R plz/skills/plz-3d-explain ~/.claude/skills/plz-3d-explain

skills.sh의 plz-3d-explain 페이지에서도 확인할 수 있습니다.

쓰는 법

설치한 뒤 프로젝트에서 에이전트를 열고 스킬을 직접 지정해 요청합니다.

Claude Code: /plz-3d-explain 컨테이너 격리를 3D로 설명해 줘.
Codex: $plz-3d-explain 컨테이너 격리를 3D로 설명해 줘.

SKILL.md의 트리거 문구로 평소처럼 요청해도 됩니다.

“컨테이너와 가상 머신의 차이를 3D로 공부하게 만들어줘.”
“HTTP 요청이 서버를 거쳐 외부 API로 가는 원리를 모형으로 보여줘.”
“이 저장소에서 자원이 생성되고 사라지는 과정을 3D 그래픽으로 설명해줘.”

스킬은 내용을 확인하고 장을 나눈 뒤 템플릿에 글과 장면을 채웁니다. 완성한 페이지는 브라우저에서 검증합니다.

만들어지는 페이지

스크롤에 맞춰 바뀌는 무대. 데스크톱에서는 왼쪽 글을 읽으면 오른쪽 고정 3D 무대가 현재 장의 장면으로 바뀝니다.
버튼으로 보는 원인과 결과. 장마다 버튼을 눌러 요청이 흐르거나 경계에서 막히는 동작을 재생하고, 결과를 문장으로 확인합니다.
자동 실행. 스위치를 켜면 읽는 장의 동작을 반복 재생합니다. 결과를 보여 준 뒤 처음 상태로 되돌아갑니다. 기본은 꺼져 있으며, 설정은 브라우저에 기억합니다.
건축 모형 같은 표현. 직교 카메라, 흰 모형, 잉크 윤곽선과 옅은 그림자를 씁니다. 빨강은 주인공, 파랑은 경계·규칙·중개자, 황동색은 데이터·자원·재료를 뜻합니다. 드래그로 모형을 돌리고 시점 되돌리기로 처음 시점에 돌아갑니다.
휴대폰 레이아웃. 세로 화면에서는 무대가 위에 붙고 글이 아래에서 스크롤됩니다. 가로 화면에서는 글과 무대를 나란히 놓습니다. 무대의 제목줄과 범례줄은 모형 영역과 나뉩니다.
용어와 출처. 용어를 풀어 쓰고 끝에 정리합니다. 확인한 출처와 확인일을 남기며, 확인하지 못한 내용은 따로 표시합니다.
페이지 언어에 맞는 화면 문구. 버튼, 안내, 제목은 페이지의 <html lang>에 맞춰 영어·한국어·일본어·중국어 간체로 바뀝니다. 다른 언어는 페이지에서 문구를 덮어써 추가할 수 있고, 사전에 없는 문구는 영어로 나옵니다. 페이지 본문은 사용자의 언어로 씁니다.
라벨과 화면 검사. 검증 훅으로 라벨 겹침과 잘림을 검사하고, 장마다 동작이 끝난 화면을 캡처해 모형과 결과 문장이 맞는지 확인합니다. 자동 실행의 반복과 휴대폰 화면도 검사합니다.

필요한 것과 한계

결과물은 빌드가 필요 없는 단일 HTML입니다. three.js r170과 웹폰트를 CDN에서 받으므로 페이지를 열 때 인터넷이 필요합니다.

검증에는 로컬 HTTP 서버(스킬 예시는 Python 3 사용)와 에이전트가 사용할 수 있는 Playwright 같은 브라우저 자동화 도구가 필요합니다. npx skills는 스킬 파일만 설치하며 이 도구들을 함께 설치하지 않습니다. 도구가 없다면 에이전트에게 준비를 요청하고, 실행하지 못한 검사는 검증 결과에서 구분해 달라고 하세요.

콘솔 오류, 라벨 겹침·잘림, 가로 스크롤, 자동 실행과 터치 조작을 확인합니다. 검증 방법은 SKILL.md, 검증 훅은 엔진 API, 자주 생기는 문제는 함정에 정리돼 있습니다.

휴대폰에서는 모형을 좌우로만 돌립니다. 무대 위를 세로로 쓸면 페이지가 스크롤되고, 가로로 밀면 모형이 돕니다. 위아래 기울이기와 확대는 지원하지 않습니다.

좁은 무대에서는 라벨 위치를 자동으로 조정하지만, 조정 범위를 넘으면 겹침이 남습니다. 라벨을 짧게 쓰고 실제 화면에서 확인해야 합니다.

정적 아키텍처·시퀀스 다이어그램, 데이터 차트, Blender 모델링, 제품 랜딩이나 앱 UI 디자인은 이 스킬의 대상이 아닙니다.

개인 설정

설치한 스킬 폴더에서 개인 설정 견본을 복사합니다.

cp references/preferences.example.md references/preferences.md

복사한 파일에 글꼴과 색, 검증 도구, 완성한 HTML의 저장 위치, 받은 피드백 등을 적습니다. 적은 설정은 SKILL.md의 기본값보다 우선하고, 적지 않은 항목은 기본값을 씁니다. 개인 설정 파일은 Git에서 무시됩니다.

기여

기여와 번역을 환영합니다. 자세한 내용은 CONTRIBUTING.md를 참고해 주세요.

라이선스

MIT.

페이지가 CDN에서 불러오는 외부 자원인 three.js(MIT)와 글꼴 Pretendard·Hahmlet·IBM Plex(SIL OFL)는 저장소에 포함하지 않습니다.

This site is open source. Improve this page.