zhaoqqiu299/interactive-3d-portfolio

인터랙티브 3D 포트폴리오

사용자가 방을 탐험하듯 둘러볼 수 있는 포트폴리오를 만드는 것을 도와줍니다: '소개'는 칠판, '프로젝트'는 노트북, '스킬'은 책장, '연락처'는 우편함. 보통 사용자는 코딩을 할 줄 모릅니다. 여러분이 만들면 사용자는 보고 평가하고 방향을 지시합니다. 품질의 대부분은 짧은 피드백 라운드를 여러 번 반복하는 데서 나오므로, 각 라운드를 빠르고 눈에 보이게 만드세요.

프로세스는 4단계, 13개 스테이지로 구성됩니다. 처음에는 순서대로 진행하고, 이후 요청은 보통 한 스테이지(가장 자주는 스테이지 8)에 해당합니다.

단계	스테이지	참고 자료
계획 및 구축	1 계획 · 2 첫 프롬프트 · 3 참조 사진 · 4 3D 빌드 · 5 차용한 인터랙션	references/build-patterns.md
내용 채우기	6 콘텐츠 및 디자인 노트 · 7 Google 파일	references/content-and-docs.md
다듬기	8 반복 · 9 테스트	이 파일, 그 다음 scripts/screenshot_site.js
출시 및 보호	10 배포 · 11 도메인 · 12 GitHub 자동 업데이트 · 13 보호	references/launch-and-protect.md

사용자와 협업하기

• 평범한 일상 언어로 된 요청을 예상하세요. 어떤 언어든 상관없습니다. "바닥에 누워있는 책들이 긴 판자처럼 보여요" 같은 말이면 충분한 지침입니다. 직접 변경 사항으로 번역하세요. 사용자의 언어로 답변하고, 사이트 텍스트는 사이트 언어로 유지하세요.
• 번호가 매겨진 요청은 하나씩 처리하고 같은 번호로 결과를 보고하여, 어떤 요청도 조용히 무시되지 않도록 하세요.
• 설명하지 말고 보여주세요. 시각적 변경 후에는 스크린샷을 찍고 완료했다고 말하기 전에 확인하세요. 레이아웃이나 외관에 관한 변경이라면 스크린샷을 사용자에게 보내세요. 소프트웨어 WebGL은 느리므로, 스크린샷에는 충분한 타임아웃을 주세요(스테이지 9 참조).
• 실제 선택지가 있을 때는 절충안을 간략히 설명하고 하나를 추천하세요 ("Testimonials" 대 "Testimony": 첫 번째를 추천하고 이유를 한 문장으로 설명). 문맥에서 답할 수 있는 질문은 하지 마세요.
• 사용자가 단어(DNS, 커밋, 저장소)를 잘 모를 때는 한 줄로 설명한 후 계속 진행하세요.

정직함과 배려

포트폴리오는 사람을 고용할지 결정하는 사람들이 읽는 것이므로, 반드시 진실해야 합니다.

• 사용자가 확인하지 않은 기술, 도구, 결과, 테스트 또는 협력자를 추가하지 마세요. 사용자가 실제로 사용하지 않은 도구를 나열해 달라고 요청하면 ("내가 Blender를 아는 척 해줘"), 면접관이 그에 대해 물어볼 수 있다고 솔직히 말하고, 실제적이고 종종 더 강력한 프레이밍(예: "모든 객체가 코드로 모델링됨")을 제시하며, 대신 Skills 섹션에 실제 기술을 나열할 것을 제안하세요.
• 디자인 근거를 작성할 때는 모든 주장을 아티팩트가 실제로 하는 일에 근거하세요. 계획된 사용은 "수업에서 어떻게 사용할 것인가" 같은 제목 아래에 두고, 실제로 일어난 일인 것처럼 쓰지 마세요.
• 추론한 문장(들려받지 않은 내용)은 표시하고 사용자에게 확인을 요청하세요.
• 학습자를 보호하세요: 이름, ID, 성적, 개인 댓글을 제거하고, 사진 게시 전에 얼굴(배경 인물 포함)을 흐리게 처리하며, 감독관 승인 없이는 연구 데이터와 코드를 비공개로 유지하세요. 스테이지 13을 참조하세요.

스테이지 1 · 프롬프트 전에 계획하기

만들기 전에 세 가지를 합의하세요: 대상 및 목표(예: "학습 디자인 인턴십 채용팀, 지원자당 3~5분"), 섹션 목록, 그리고 각 객체의 일상적인 기능이 해당 섹션과 일치하는 방 지도. 객체와 그 의미가 일치하지 않으면 객체를 변경하세요(여행가방은 떠나는 느낌, 우편함은 편지를 쓰는 느낌). 모든 섹션은 일반 메뉴에서도 접근 가능해야 합니다.

스테이지 2~5 · 방 만들기

씬을 작성하기 전에 references/build-patterns.md를 읽으세요. 기본 아키텍처:

• import map을 통해 고정된 CDN 버전의 Three.js를 로드하는 하나의 index.html, 모든 객체는 기본 도형(모델 파일 없음)으로 코드에서 모델링, 캔버스 생성 텍스처, 왼쪽 상단 메뉴.
• 자주 변경되는 콘텐츠(프로젝트 폴더, 갤러리 항목)는 index.html 옆에 있는 작은 JSON 파일에 저장하여, 사용자가 3D 코드를 건드리지 않고 프로젝트나 사진을 추가할 수 있게 함.
• 사용자가 참조 사진(스테이지 3)을 가져오면 레이아웃, 팔레트, 조명을 먼저 일치시키고, 스타일 세부 사항은 나중에. 예시 인터랙션(React Bits, Codrops)을 가져오면 사이트 고유 스타일로 원본을 만들고, 라이선스가 있는 코드는 붙여넣지 마세요.

첫 빌드 체크리스트: 모든 섹션에 호버 시 빛나고 레이블이 있는 객체; 클릭 시 카메라가 그곳으로 이동하고 섹션이 열림; 3D 방 없이도 메뉴 작동; 약 5초 이내 로딩; 휴대폰 화면 너비에서 작동.

스테이지 6과 7 · 실제 작업물로 채우기

references/content-and-docs.md를 읽으세요. 요약: 실제 자료(이력서, LinkedIn 텍스트, 프로젝트 파일)를 요청하고, 그것을 바탕으로 초안을 작성한 후 사용자가 수정하게 하세요. 실제 결과물을 먼저 배치하고 그 옆에 결정 사항과 그背后的 학습 이론을 명명한 번호가 매겨진 디자인 노트로 근거를 제시하세요. 중요하지 않은 오래된 날짜는 삭제하세요. Google 링크의 경우 공유 설정이 "링크가 있는 모든 사용자, 뷰어"인지 확인하고, 파일에 대학 로그인이 필요하면 사이트에서 직접 호스팅하세요.

스테이지 8 · 반복

대부분의 작업이 여기서 이루어집니다. 실제 라운드에서 얻은 규칙:

• "클릭 가능"에 대한 단일 신호. 클릭 가능한 모든 것은 호버 시 빛나고, 장식적인 것은 빛나거나 클릭 가능해 보이지 않아야 함. 잘못된 신호(빛나는 종이, 떠다니는 수식, 방치된 포스트잇)를 제거하세요.
• 숨겨진 상호작용을 안내하세요. 방문자가 보드에 그림을 그릴 수 있다면, 그 위에서 포인터를 분필 모양으로 바꾸고, 도구를 바로 아래에 배치하여 첫 사용 전까지 빛나게 하세요. 갤러리가 스크롤되면 작은 범례(화살표 키, 휠, 두 손가락 스와이프, 터치 드래그)를 표시하세요. 섹션이 열리면 그 안에서 다음 클릭 가능한 항목을 은은하게 빛나게(펄싱 아웃라인)하여 사람들이 눈치챌 수 있게 하세요.
• 상호작용 가능한 물체를 사람들이 보는 곳 가까이에 두세요. 패널이 오른쪽에 열리면 상호작용 가능한 객체를 씬의 오른쪽에 배치하세요.
• 실제 비율. 책, 머그잔, 가구를 실제 크기로 만들면 올바르게 보이고, 늘린 모양은 즉시 이상해 보입니다.
• 클릭 후에만 소리를 재생하세요 (브라우저가 자동 재생을 차단함): 음악을 시작하는 "입장" 버튼과 함께 작은 볼륨 옵션.
• 콘텐츠를 이야기 순서로 정렬하세요. 사용 후기에서는 사진보다 단어(편지, 메모, 메시지)를 먼저 배치하고, 가장 개인적인 항목을 먼저.
• 섹션 이름은 평범하게 지으세요. 메뉴 레이블은 그 안에 무엇이 있는지 알려야 함("다음 장"이 아닌 "연구").
• 클릭을 방해하는 요소를 확인하세요. Three.js Line 및 LineSegments 객체는 기본적으로 약 1미터 거리에서 광선을 포착하므로, 장식용 와이어프레임에 obj.raycast = () => {}를 설정하지 않으면 그 근처의 클릭이 잘못된 객체로 전달됩니다.

각 라운드 후에 변경된 뷰의 스크린샷을 찍고, 눈에 띄게 잘못된 것을 한 번 수정한 후, 무엇이 변경되었는지 평범한 말로 보고하세요.

스테이지 9 · 테스트

scripts/screenshot_site.js <사이트_디렉토리> <출력_디렉토리> about projects contact (섹션 ID는 메뉴 버튼의 data-go 값)를 실행하여 데스크톱 및 휴대폰 뷰를 캡처하고 페이지 오류를 출력하세요. 그런 다음 사용자와 함께 수동 검사를 진행하세요: 모든 객체 및 메뉴 항목이 열림, 모든 링크가 개인 창에서 작동, 문의 양식이 도착함(FormSubmit은 일회성 활성화 이메일 필요), 소리 끄기 작동, 키보드 전용 탐색 작동, 한 명의 친구가 도움 없이 방문.

스테이지 10~13 · 출시 및 보호

references/launch-and-protect.md를 읽으세요. GitHub 및 Vercel 배포(메인 페이지는 최상위에 index.html이어야 함, GitHub 웹사이트는 한 번에 최대 100개 파일 업로드), 커스텀 도메인, Claude GitHub 앱을 통한 변경 사항 푸시, 그리고 보호: 비공개 저장소, AI 크롤러를 위한 assets/robots.txt 및 assets/vercel.json, Vercel의 AI 봇 차단, 저작권 표시를 다룹니다. 공개된 것은 복사 방지가 불가능하다는 점을 솔직히 알리세요.

선택적 결과물

완료한 사용자들은 종종 이 프로세스를 가르치고 싶어합니다. 13개 스테이지를 따르는 유인물과 슬라이드 데크를 만들 수 있습니다. 실제 사이트 스크린샷(전후)을 사용하고, 재고 이미지는 사용하지 마세요. 발표자 노트는 사용자의 목소리로 작성하세요. scripts/html_to_docx.py는 디자인 노트가 포함된 프로젝트 문서를 Word로 변환합니다.

일반적인 실패

증상	원인	해결책
Vercel에서 404	메인 파일이 index.html이 아니거나 폴더 안에 있음	이름을 바꾸고 최상위로 이동
노트북 폴더 또는 갤러리가 온라인에서 비어 있음	projects/ 또는 다른 폴더가 업로드되지 않음	index.html 옆에 업로드
이전 버전이 표시됨	캐시 또는 배포가 아직 실행 중	Ready 상태를 기다린 후 강력 새로고침
"X before initialization" 오류	함수 또는 텍스처가 const 선언 전에 사용됨	호이스팅(function 선언)하거나 사용을 나중으로 이동
객체 클릭 시 이웃이 열림	장식용 라인 객체가 광선을 포착함	obj.raycast = () => {}
GitHub 푸시 거부	Claude GitHub 앱이 저장소에 설치되지 않음	해당 저장소에 앱 설치, 새 세션이 필요할 수 있음