디자인을 실제 웹 프로젝트로 완성하는 AI 코딩 실전 교안

왜 필요한가

• 순서를 모르고 바로 코딩을 요청하면 AI가 비어 있는 조건을 임의로 채웁니다.
• 문서 작성과 구현, 검수를 한 흐름으로 익혀야 다른 프로젝트에도 같은 방법을 재사용할 수 있습니다.

이렇게 적용하세요

1. 1~7부에서 문서와 도구의 역할을 이해합니다.
2. 8~11부에서 PRD와 프로젝트 지침을 직접 만듭니다.
3. 12~13부의 요청문과 확인표로 구현과 검수를 반복합니다.

이런 실수는 피하세요

• 처음부터 모든 템플릿을 복사한 뒤 내용은 읽지 않는 것
• 한 번의 요청으로 전체 사이트 완성을 맡기는 것

왜 필요한가

• 같은 디자인이라도 기술 스택과 기존 코드 구조에 따라 올바른 구현 방법이 달라집니다.
• 없는 이미지·폰트·API를 AI가 만들어내지 않도록 입력 자료의 범위를 먼저 확정해야 합니다.

이렇게 적용하세요

1. 기존 프로젝트인지 새 프로젝트인지 구분합니다.
2. package.json과 폴더 구조에서 실제 기술 스택을 확인합니다.
3. Figma 링크, 화면 이미지, 로고·사진·아이콘·폰트 파일의 준비 여부를 적습니다.

이런 실수는 피하세요

• 바닐라 프로젝트에 React 설치를 당연하게 요구하는 것
• 없는 에셋을 비슷한 외부 URL로 대체하도록 허용하는 것

왜 필요한가

• 워드프로세서 없이도 코드 저장소 안에서 문서를 함께 관리할 수 있습니다.
• 제목과 목록을 나누면 긴 요구사항에서 기능, 금지사항, 완료 조건이 서로 섞이지 않습니다.

이렇게 적용하세요

1. 파일 이름을 `PRD.md`처럼 정확히 저장합니다.
2. 큰 제목은 하나의 `#`, 하위 항목은 `##`와 `###`로 단계화합니다.
3. 명령어와 파일명은 백틱으로, 긴 예시는 코드 블록으로 구분합니다.

이런 실수는 피하세요

• 제목 단계 없이 모든 문장을 긴 문단 하나에 쓰는 것
• 도구가 인식하는 `AGENTS.md` 같은 대문자 파일명을 임의로 소문자로 바꾸는 것

왜 필요한가

• 도구가 문서 본문을 읽기 전에 이 문서의 이름과 사용 목적을 빠르게 판단할 수 있습니다.
• 정해진 키를 지키면 여러 Skill을 구분하고 알맞은 상황에 불러오기 쉬워집니다.

이렇게 적용하세요

1. 사용하는 도구의 공식 형식에서 frontmatter 필요 여부를 확인합니다.
2. 첫 줄부터 `---`로 시작하고 요구된 키만 작성합니다.
3. 닫는 `---` 다음 줄부터 실제 지침 본문을 작성합니다.

이런 실수는 피하세요

• 일반 PRD에도 이유 없이 frontmatter를 붙이는 것
• 지원 여부를 확인하지 않고 임의의 키를 만들어 넣는 것

왜 필요한가

• 사람과 AI가 같은 목표와 범위를 기준으로 판단하게 합니다.
• 구현 중 새 아이디어가 생겨도 이번 작업에 포함할지 제외할지 결정할 근거가 생깁니다.

이렇게 적용하세요

1. 사용자와 해결할 문제를 먼저 씁니다.
2. 포함 기능과 제외 범위를 분리합니다.
3. 화면별 목적·흐름·상태·데이터를 적고 마지막에 검증 가능한 완료 조건을 둡니다.

이런 실수는 피하세요

• 색상과 레이아웃만 적고 제품 목적을 생략하는 것
• 완료 조건을 ‘전체적으로 잘 동작한다’처럼 측정할 수 없게 쓰는 것

왜 필요한가

• 목적이 불분명하면 디자인의 강조 순서와 기능 우선순위가 뒤섞입니다.
• 수정 요청마다 기준이 바뀌어 같은 영역을 여러 번 다시 만들게 됩니다.

이렇게 적용하세요

1. 현재 모호한 요구를 사용자·행동·결과 문장으로 바꿉니다.
2. 결정되지 않은 내용은 확정 사실과 분리해 질문 목록으로 둡니다.
3. 새 요구가 생기면 코드를 고치기 전에 PRD 범위부터 갱신합니다.

이런 실수는 피하세요

• AI가 만든 첫 결과를 요구사항으로 역추적하는 것
• 서로 충돌하는 요청을 PRD에 그대로 함께 두는 것

왜 필요한가

• 화면 시안이 좋아 보여도 실제 코드의 라우팅, 저장, 오류 처리, 반응형 조건은 자동으로 확정되지 않습니다.
• 코딩 도구는 기존 컴포넌트와 패키지를 보존해야 하므로 저장소 규칙이 필요합니다.

이렇게 적용하세요

1. 공통 제품 목표와 사용자 흐름은 두 문서에 동일하게 둡니다.
2. 코딩용 PRD에는 기술 스택, 파일 규칙, 데이터와 상태, 검증 명령을 추가합니다.
3. Figma 결과는 참고 자료로 취급하고 실제 프로젝트 규칙에 맞게 다시 구현하도록 명시합니다.

이런 실수는 피하세요

• Figma 생성 프롬프트를 그대로 개발 PRD로 사용하는 것
• 시각 결과만 보고 키보드 사용·로딩·오류 상태를 완료로 간주하는 것

왜 필요한가

• 자주 바뀌는 진행 상황 때문에 안정적인 제품 요구가 계속 흔들리는 것을 막습니다.
• 도구별로 읽는 규칙 파일이 달라도 PRD는 하나의 제품 기준으로 공유할 수 있습니다.

이렇게 적용하세요

1. PRD에는 목적·범위·기능·상태·완료 조건을 둡니다.
2. 도구 규칙 파일에는 코드 스타일과 작업 원칙을 둡니다.
3. 반복 절차는 Skill, 현재 진척은 `PROJECT_CONTEXT.md`에 둡니다.

이런 실수는 피하세요

• 모든 내용을 수천 줄짜리 PRD 하나에 계속 추가하는 것
• 같은 규칙을 여러 파일에 서로 다른 문장으로 중복하는 것

왜 필요한가

• 대화가 바뀌어도 파일명, 기술 스택, 에셋 사용, 검증 방식 같은 기준을 반복해서 전달할 수 있습니다.
• 프로젝트 전체 규칙과 특정 작업 규칙을 분리해 필요한 범위만 적용할 수 있습니다.

이렇게 적용하세요

1. 현재 Workspace에서 규칙을 읽는 경로를 확인합니다.
2. PRD 우선, 기존 코드 보존, 실제 에셋 사용, 검증 결과 보고 규칙을 작성합니다.
3. 작업 후 규칙이 실제 응답과 변경에 반영됐는지 확인합니다.

이런 실수는 피하세요

• 확인하지 않은 경로에 규칙 파일을 만들고 적용됐다고 믿는 것
• 제품 요구를 규칙 파일에 복사해 두 문서를 함께 수정해야 하게 만드는 것

왜 필요한가

• 매 요청마다 같은 규칙을 붙이지 않아도 저장소 안에서 일관된 변경을 유도합니다.
• 하위 폴더에 더 구체적인 `AGENTS.md`가 있으면 영역별 규칙을 분리할 수 있습니다.

이렇게 적용하세요

1. 저장소 루트와 작업 디렉터리의 `AGENTS.md`를 먼저 찾습니다.
2. 기술 스택, 기존 코드 재사용, 명명 규칙, 검증 명령을 실제 저장소와 맞게 씁니다.
3. 규칙과 현실이 달라졌다면 코드와 문서 중 무엇을 고칠지 먼저 결정합니다.

이런 실수는 피하세요

• 다른 프로젝트의 `AGENTS.md`를 기술 스택 확인 없이 복사하는 것
• 실행할 수 없는 테스트 명령을 완료 조건에 넣는 것

왜 필요한가

• 도구마다 같은 기준을 다른 문장으로 유지하다 생기는 충돌을 줄입니다.
• Claude Code 전용 명령이나 작업 흐름만 별도로 관리할 수 있습니다.

이렇게 적용하세요

1. 공통 규칙과 Claude 전용 규칙을 나눕니다.
2. 참조 문서가 실제 환경에서 읽히는지 확인합니다.
3. 도구가 지원하지 않는 문법이나 명령을 사실처럼 적지 않습니다.

이런 실수는 피하세요

• `AGENTS.md` 전체를 복제한 뒤 한쪽만 수정하는 것
• Claude Code가 자동으로 모든 관련 문서를 읽을 것이라고 가정하는 것

왜 필요한가

• 도구를 바꿀 때마다 제품 목표가 달라지는 것을 막습니다.
• 규칙을 수정할 때 세 파일을 모두 찾아 고치는 유지보수 비용을 줄입니다.

이렇게 적용하세요

1. `PRD.md`를 모든 도구가 공유하는 제품 기준으로 정합니다.
2. 공통 코딩 규칙의 기준 파일을 하나 선택합니다.
3. 도구별 파일에는 참조 방법과 전용 규칙만 작성하고 서로 충돌하는지 확인합니다.

이런 실수는 피하세요

• 각 도구용 PRD를 따로 만들어 내용이 달라지는 것
• 어떤 문서가 최우선인지 쓰지 않아 충돌 시 임의 판단하게 하는 것

왜 필요한가

• 반복 작업의 누락을 줄이고 작업자나 도구가 바뀌어도 같은 순서를 지킬 수 있습니다.
• 현재 프로젝트의 변하는 상태와 안정적인 작업 절차를 분리할 수 있습니다.

이렇게 적용하세요

1. Skill이 언제 사용되는지 목표와 적용 조건을 씁니다.
2. 확인→계획→구현→검증 순서를 행동 문장으로 적습니다.
3. 현재 완료 화면이나 남은 버그는 `PROJECT_CONTEXT.md`에 기록합니다.

이런 실수는 피하세요

• ‘홈 완료, 상세 진행 중’ 같은 상태 기록을 Skill에 넣는 것
• 특정 프로젝트 파일명만 가득해 다른 작업에 재사용할 수 없게 만드는 것

왜 필요한가

• 용어를 섞으면 연결 설정과 프로젝트 의존성을 구분하지 못해 불필요한 설치가 늘어납니다.
• 무엇이 AI 도구 쪽 기능이고 무엇이 실제 배포 코드에 포함되는지 알아야 성능과 유지보수 영향을 판단할 수 있습니다.

이렇게 적용하세요

1. 필요한 일을 ‘정보 연결’, ‘반복 절차’, ‘실제 화면 기능’으로 나눕니다.
2. 정보 연결은 MCP·Plugin, 반복 절차는 Skill·Workflow, 화면 기능은 Library 후보로 분류합니다.
3. 설치 전 기존 기능과 공식 문서를 확인합니다.

이런 실수는 피하세요

• Figma MCP를 설치하면 디자인이 자동으로 완성된다고 생각하는 것
• AI 도구용 Plugin과 웹사이트에 번들되는 라이브러리를 같은 것으로 보는 것

왜 필요한가

• 도구가 많을수록 설정 충돌, 권한 문제, 학습 비용이 늘어납니다.
• 필요한 순간에 목적이 분명한 도구를 추가해야 결과가 어느 도구에서 나왔는지 추적할 수 있습니다.

이렇게 적용하세요

1. 프로젝트가 요구하는 입력 자료와 완료 검증을 먼저 목록으로 만듭니다.
2. 기존에 설치된 도구와 패키지로 가능한지 확인합니다.
3. 부족한 기능만 공식 설치 방법으로 추가하고 연결 여부를 작은 작업으로 시험합니다.

이런 실수는 피하세요

• 추천 목록을 모두 설치한 뒤 사용하지 않는 것
• Live Server가 필요한 단순 정적 프로젝트와 이미 개발 서버가 있는 프로젝트를 구분하지 않는 것

왜 필요한가

• AI가 새 코드를 만들 때 기존 이름과 연결해야 중복 요소와 상태가 생기지 않습니다.
• 오류가 난 위치를 찾고 수정 범위를 설명하기 쉬워집니다.

이렇게 적용하세요

1. 대상의 역할을 먼저 한국어로 한 문장으로 정합니다.
2. 프로젝트가 정한 표기법으로 바꿉니다.
3. 같은 뜻의 기존 이름이 있는지 검색한 뒤 새 이름을 만듭니다.

이런 실수는 피하세요

• `box1`, `temp`, `data2`처럼 역할이 없는 이름을 쓰는 것
• 같은 헤더를 `top`, `gnb`, `header_area`로 제각각 부르는 것

왜 필요한가

• CSS, JavaScript, 컴포넌트 이름을 눈으로 빠르게 구분할 수 있습니다.
• 검색과 자동 검사에서 같은 역할의 이름을 안정적으로 찾을 수 있습니다.

이렇게 적용하세요

1. CSS class와 HTML id는 프로젝트 규칙의 `snake_case`를 사용합니다.
2. JavaScript 변수·함수는 `camelCase`, 컴포넌트·class·type은 `PascalCase`를 사용합니다.
3. 전역 고정 상수만 `UPPER_SNAKE_CASE`를 사용합니다.

이런 실수는 피하세요

• 한 HTML에서 `product-card`와 `product_card`를 섞는 것
• 모든 값을 대문자 상수로 작성해 지역 변수와 구분되지 않게 하는 것

왜 필요한가

• AI가 기존 코드를 확장할 때 같은 패턴을 재사용하게 합니다.
• 참·거짓 값과 동작 함수를 일반 데이터와 혼동하는 실수를 줄입니다.

이렇게 적용하세요

1. 저장소의 기존 이름을 검색해 실제 규칙을 확인합니다.
2. 규칙 파일에 언어별 예시를 함께 기록합니다.
3. 새 코드가 규칙과 다르면 기능 구현과 함께 이름을 바로 고칩니다.

이런 실수는 피하세요

• `menuState`가 boolean인지 문자열인지 알 수 없게 쓰는 것
• 이벤트 prop과 내부 처리 함수를 모두 `clickMenu`로 쓰는 것

왜 필요한가

• HTML·CSS·JavaScript가 서로 다른 이름을 사용해 동작이 끊기는 문제를 막습니다.
• 상태 class를 보면 현재 화면 상태를 개발자 도구에서 바로 확인할 수 있습니다.

이렇게 적용하세요

1. 기본 구조 class와 상태 class를 분리합니다.
2. JavaScript 선택자가 실제 HTML에 존재하는지 확인합니다.
3. 상태 변경 시 `aria-expanded` 같은 접근성 속성도 함께 갱신합니다.

이런 실수는 피하세요

• CSS에는 `.is_active`, JavaScript에는 `.active`를 사용하는 것
• 보이기만 바꾸고 버튼의 확장 상태를 보조 기술에 알리지 않는 것

왜 필요한가

• 스타일용 class에 데이터 의미까지 억지로 넣지 않아도 됩니다.
• 필터, 탭, 모달 대상처럼 요소와 연결된 작은 값을 명시적으로 전달할 수 있습니다.

이렇게 적용하세요

1. 값이 스타일 상태인지 데이터인지 먼저 구분합니다.
2. HTML에는 `data-product-id`, JavaScript에서는 `dataset.productId`로 읽습니다.
3. 민감 정보나 큰 JSON은 `data-*`에 넣지 않습니다.

이런 실수는 피하세요

• 비밀번호나 비공개 API 키를 넣는 것
• 단순 활성 상태를 `data-active`와 `is_active` 양쪽에 중복 저장하는 것

왜 필요한가

• 필수 class를 바꾸면 라이브러리가 요소를 찾지 못해 동작하지 않습니다.
• 외부 규칙과 프로젝트 규칙을 분리하면 라이브러리를 제거하거나 교체하기 쉽습니다.

이렇게 적용하세요

1. 공식 문서에서 필수 마크업과 class를 확인합니다.
2. 필수 class는 변경하지 않고 프로젝트 class를 함께 추가합니다.
3. CSS 선택자에서 외부 class만 과도하게 덮어쓰지 않습니다.

이런 실수는 피하세요

• `.swiper-wrapper`를 snake_case로 바꾸는 것
• 모든 디자인 스타일을 외부 class에 직접 넣어 다른 슬라이더까지 영향을 주는 것

왜 필요한가

• 작은 소개 사이트나 퍼블리싱 프로젝트에서 빌드 복잡도와 의존성을 줄일 수 있습니다.
• 현재 프로젝트가 바닐라인데 AI가 익숙한 React 구조로 재작성하는 것을 막습니다.

이렇게 적용하세요

1. 기존 파일과 `package.json`에서 실제 스택을 확인합니다.
2. PRD와 규칙에 HTML·CSS·JavaScript 유지 조건을 적습니다.
3. 복잡한 상태 관리가 실제로 필요한지 검토한 뒤 스택 변경을 별도 결정합니다.

이런 실수는 피하세요

• 바닐라라는 이유로 코드 구조와 모듈 분리를 포기하는 것
• AI 예시가 React라는 이유만으로 프로젝트 전체를 React로 변환하는 것

왜 필요한가

• AI가 파일을 임의 위치에 중복 생성하거나 상대 경로를 틀리는 문제를 줄입니다.
• 에셋과 코드의 실제 경로를 PRD와 요청문에서 정확히 가리킬 수 있습니다.

이렇게 적용하세요

1. 현재 폴더를 먼저 확인하고 공통 파일 위치를 찾습니다.
2. 새 프로젝트라면 `assets/images`, `assets/icons`, `assets/fonts`, `css`, `js`처럼 역할별로 최소 분리합니다.
3. 화면이 늘어나면 공통 코드와 화면 전용 코드를 구분하되 빈 폴더를 미리 만들지 않습니다.

이런 실수는 피하세요

• 프로젝트 확인 없이 익숙한 구조로 전면 이동하는 것
• 같은 로고를 여러 화면 폴더에 복제하는 것

왜 필요한가

• AI가 파일 구조, 노드 정보, 변수, 에셋을 추측하지 않고 확인할 수 있습니다.
• 연결된 서비스가 제공하는 범위와 권한을 명확히 구분할 수 있습니다.

이렇게 적용하세요

1. 사용 중인 AI 도구에서 MCP 지원 여부를 확인합니다.
2. 공식 연결 방법으로 서버와 권한을 설정합니다.
3. 작은 읽기 요청으로 연결 성공과 접근 범위를 확인합니다.

이런 실수는 피하세요

• MCP 연결만 하면 모든 파일에 자동 접근한다고 생각하는 것
• 쓰기 권한이 필요한지 검토하지 않고 넓은 권한을 허용하는 것

왜 필요한가

• 스크린샷만으로 알기 어려운 정확한 텍스트와 반복 구조를 확인할 수 있습니다.
• 디자인 변수와 컴포넌트를 실제 CSS 토큰과 공통 컴포넌트 후보로 연결할 수 있습니다.

이렇게 적용하세요

1. 구현할 프레임과 연결된 화면 범위를 확인합니다.
2. 메타데이터와 디자인 컨텍스트로 구조를 읽습니다.
3. 스크린샷과 변수, 에셋을 함께 확인해 코드 값과 시각 결과를 교차 검증합니다.

이런 실수는 피하세요

• 노드 하나만 보고 전체 반응형 규칙을 확정하는 것
• Figma에서 확인한 값이 현재 저장소 토큰보다 항상 우선한다고 가정하는 것

왜 필요한가

• 디자인 파일에 보이는 한 장면과 실제 제품의 모든 상태는 다릅니다.
• 생성된 코드가 시각적으로 비슷해도 기존 저장소 규칙과 접근성을 위반할 수 있습니다.

이렇게 적용하세요

1. Figma에서 확인된 사실과 PRD에서 결정할 내용을 분리합니다.
2. 없는 상태와 반응형 동작은 추정하지 말고 질문하거나 규칙으로 확정합니다.
3. 구현 후 반드시 실제 브라우저와 원본 화면을 비교합니다.

이런 실수는 피하세요

• Figma에 없는 모바일 화면을 데스크톱 축소판으로 자동 결정하는 것
• MCP가 만든 코드이므로 테스트가 필요 없다고 생각하는 것

왜 필요한가

• 도구가 보여 준 코드 형식과 실제 구현 형식을 구분해야 기존 프로젝트를 보존할 수 있습니다.
• 시각 정보는 재사용하되 불필요한 패키지와 컴포넌트 구조를 그대로 가져오지 않게 합니다.

이렇게 적용하세요

1. 예시에서 화면 계층, 텍스트, 값, 에셋만 추출합니다.
2. 현재 프로젝트의 HTML·CSS·JavaScript 구조에 맞게 다시 작성합니다.
3. 동일한 시각 결과와 동작이 나오는지 브라우저에서 비교합니다.

이런 실수는 피하세요

• 예시 코드가 React라서 새 React 프로젝트를 만드는 것
• 유틸리티 class를 프로젝트 CSS 규칙 확인 없이 복사하는 것

왜 필요한가

• 도구 업데이트로 설정 화면과 명령이 달라질 수 있습니다.
• 연결 표시만 보고 실제 파일 권한과 선택 범위를 확인하지 않으면 작업 중 실패합니다.

이렇게 적용하세요

1. 사용하는 AI 도구의 공식 Figma MCP 안내를 엽니다.
2. 필요한 계정 인증과 파일 권한을 최소 범위로 설정합니다.
3. 대상 파일의 작은 프레임을 읽어 이름과 구조가 맞는지 확인합니다.

이런 실수는 피하세요

• 예전 블로그의 명령을 현재 버전에 그대로 실행하는 것
• 개인 파일 전체 권한을 이유 없이 허용하는 것

왜 필요한가

• 디자인부터 읽으면 AI가 저장소 제약을 모르고 새로운 구조를 제안할 수 있습니다.
• PRD의 화면 범위와 Figma의 선택 범위가 다를 때 먼저 충돌을 발견할 수 있습니다.

이렇게 적용하세요

1. Workspace Rule과 PRD의 우선순위를 확인합니다.
2. Figma 링크와 구현 대상 노드를 명시합니다.
3. 분석 보고를 먼저 받고 확인된 범위만 구현하도록 요청합니다.

이런 실수는 피하세요

• ‘이 Figma를 구현해 줘’만 보내는 것
• 분석 결과를 읽지 않고 바로 전체 파일 수정을 승인하는 것

왜 필요한가

• 한 종류의 정보만 보고 생기는 추정을 줄입니다.
• 스크린샷과 에셋의 차이를 알면 화면 전체를 이미지로 붙이는 잘못된 구현을 막을 수 있습니다.

이렇게 적용하세요

1. metadata로 화면과 레이어 범위를 좁힙니다.
2. screenshot으로 실제 시각 결과를 확인합니다.
3. variables와 context로 값과 구조를 읽고 assets로 필요한 원본 파일만 가져옵니다.

이런 실수는 피하세요

• 스크린샷을 웹 화면 배경 이미지로 사용해 구현을 대신하는 것
• 모든 에셋을 내려받아 사용 여부 없이 프로젝트에 넣는 것

왜 필요한가

• 첫 화면에서 공통 간격과 컴포넌트 규칙을 검증한 뒤 재사용할 수 있습니다.
• 화면을 한꺼번에 만들 때 발생하는 대규모 되돌리기를 줄입니다.

이렇게 적용하세요

1. 코드 변경 없이 저장소와 Figma를 분석하게 합니다.
2. 확인된 사실·추정·질문을 분리한 계획을 검토합니다.
3. 공통 구조와 대표 화면 하나를 구현하고 비교한 뒤 승인된 패턴으로 확장합니다.

이런 실수는 피하세요

• 분석과 전체 구현을 한 요청에 묶는 것
• Figma 캡처와 비교하지 않고 코드가 빌드된 것만으로 완료하는 것

왜 필요한가

• 레이어 이름이 `Frame 123`뿐이면 화면 범위와 에셋 역할을 추측하게 됩니다.
• 컴포넌트와 Variant를 확인하면 코드의 공통 컴포넌트와 상태 설계를 더 정확히 만들 수 있습니다.

이렇게 적용하세요

1. Page와 Section에서 제품 영역을 확인합니다.
2. Frame 이름으로 데스크톱·모바일과 화면 종류를 구분합니다.
3. Component·Instance·Variant의 반복과 상태를 코드 재사용 후보로 기록합니다.

이런 실수는 피하세요

• 레이어 순서만 보고 DOM 순서를 확정하는 것
• Instance 하나의 임시 수정값을 전체 컴포넌트 규칙으로 해석하는 것

왜 필요한가

• 검증된 시간 계산과 브라우저 차이 처리를 재사용할 수 있습니다.
• 반대로 단순 효과에는 라이브러리가 오히려 파일 크기와 유지보수 부담을 늘릴 수 있습니다.

이렇게 적용하세요

1. 디자인에 필요한 동작을 문장으로 먼저 정의합니다.
2. CSS와 기본 JavaScript로 가능한지 확인합니다.
3. 부족할 때만 현재 프로젝트와 호환되는 라이브러리를 공식 문서로 검토합니다.

이런 실수는 피하세요

• 라이브러리를 먼저 고른 뒤 쓸 효과를 찾는 것
• 접근성과 모션 감소 설정 없이 자동 재생 효과를 추가하는 것

왜 필요한가

• 필요한 기능만 추가하면 초기 로딩과 디버깅 범위를 줄일 수 있습니다.
• 각 도구의 책임이 분명하면 한 라이브러리를 제거해도 전체 동작이 무너지지 않습니다.

이렇게 적용하세요

1. 기본 레이아웃과 상태 전환은 CSS와 JavaScript로 완성합니다.
2. 복잡한 타임라인에는 GSAP, 스크롤 연결에는 ScrollTrigger처럼 역할을 하나씩 배정합니다.
3. 부드러운 스크롤을 추가한다면 스크롤 기반 애니메이션과 동기화 방법을 함께 검증합니다.

이런 실수는 피하세요

• GSAP와 Anime.js로 같은 요소를 동시에 움직이는 것
• Swiper가 필요한 카드 목록에 별도의 드래그 라이브러리를 겹쳐 쓰는 것

왜 필요한가

• 여러 애니메이션의 시작 시점과 지속 시간을 하나의 타임라인으로 관리할 수 있습니다.
• 단순 hover나 색상 전환까지 GSAP로 만들면 코드가 불필요하게 복잡해집니다.

이렇게 적용하세요

1. 공식 배포 방식에서 프로젝트에 맞는 설치 또는 import 방법을 확인합니다.
2. 초기 상태를 CSS와 충돌하지 않게 정하고 작은 타임라인부터 만듭니다.
3. 컴포넌트가 제거될 때 애니메이션과 이벤트를 정리하고 모션 감소 설정을 반영합니다.

이런 실수는 피하세요

• 존재하지 않는 선택자에 애니메이션을 실행하는 것
• 레이아웃 속성을 매 프레임 바꿔 화면 떨림과 성능 저하를 만드는 것

왜 필요한가

• 복잡한 스크롤 위치 계산과 갱신을 직접 작성하는 부담을 줄입니다.
• 잘못 사용하면 긴 고정 구간과 과도한 움직임으로 콘텐츠 탐색을 방해합니다.

이렇게 적용하세요

1. trigger, start, end, scrub, pin이 각각 필요한지 결정합니다.
2. 이미지와 폰트 로딩 후 위치 계산이 맞는지 확인합니다.
3. 모바일 높이 변화와 모션 감소 환경에서 대체 동작을 검증합니다.

이런 실수는 피하세요

• 모든 섹션을 pin 처리해 일반 스크롤을 막는 것
• Lenis 같은 별도 스크롤 엔진과 갱신을 연결하지 않는 것

왜 필요한가

• 제품 전체의 스크롤 감각을 일정하게 만들 수 있습니다.
• 기본 스크롤을 바꾸므로 링크 이동, 모달, 중첩 스크롤, 모바일 브라우저와 충돌할 위험이 있습니다.

이렇게 적용하세요

1. 기본 브라우저 스크롤로 디자인 요구를 충족하는지 먼저 봅니다.
2. 도입한다면 애니메이션 프레임 루프와 ScrollTrigger 갱신을 공식 방식으로 연결합니다.
3. textarea, 모달, 코드 영역 같은 내부 스크롤을 Lenis가 가로채지 않는지 확인합니다.

이런 실수는 피하세요

• 부드러워 보인다는 이유만으로 모든 프로젝트에 기본 설치하는 것
• 접근성의 모션 감소 설정과 키보드 PageDown 동작을 확인하지 않는 것

왜 필요한가

• 터치 제스처, 페이지 표시, 반복, 반응형 슬라이드 수를 안정적으로 제공합니다.
• 캐러셀은 숨겨진 콘텐츠를 발견하기 어렵게 할 수 있으므로 정보 구조상 필요한지 검토해야 합니다.

이렇게 적용하세요

1. 슬라이드가 필요한 이유와 한 화면에 보일 개수를 정합니다.
2. 공식 필수 class를 유지하고 프로젝트 class를 함께 사용합니다.
3. 이전·다음 버튼, 현재 위치, 키보드 조작, 모바일 드래그를 검증합니다.

이런 실수는 피하세요

• 외부 class를 프로젝트 규칙에 맞춘다고 이름을 바꾸는 것
• 자동 재생만 제공하고 정지나 직접 탐색 방법을 두지 않는 것

왜 필요한가

• 제목의 순차 등장처럼 직접 span을 수십 개 만들기 어려운 효과를 구현할 수 있습니다.
• 텍스트를 잘못 분해하면 스크린 리더 읽기, 줄바꿈, 복사, 검색에 문제가 생깁니다.

이렇게 적용하세요

1. 분할 전 원본 텍스트가 시맨틱하게 존재하도록 합니다.
2. 필요한 제목에만 적용하고 접근성 트리에 중복 텍스트가 생기지 않게 처리합니다.
3. 리사이즈 후 줄 단위 분할을 다시 계산하고 제거 시 원문을 복원합니다.

이런 실수는 피하세요

• 본문 전체를 글자 단위로 분해하는 것
• 유료·라이선스 조건을 확인하지 않고 배포하는 것

왜 필요한가

• 복잡한 벡터 애니메이션을 영상보다 가볍고 해상도 독립적으로 표현할 수 있습니다.
• JSON이 크거나 레이어 효과가 복잡하면 성능과 브라우저 호환 문제가 생길 수 있습니다.

이렇게 적용하세요

1. 실제 JSON 파일과 사용 권한을 확인합니다.
2. 반복·자동 재생·재생 시점을 제품 요구에 맞게 정합니다.
3. 로딩 실패 대체 화면, 모션 감소, 화면 밖 재생 중지를 검증합니다.

이런 실수는 피하세요

• 제공되지 않은 JSON URL을 임의로 만들어 넣는 것
• 장식 애니메이션을 계속 재생해 배터리와 집중을 소모하는 것

왜 필요한가

• 요구에 맞는 작은 API로 상태 전환과 요소 모션을 구성할 수 있습니다.
• 비슷한 목적의 라이브러리를 여러 개 넣으면 번들, 문법, 타이밍 관리가 분산됩니다.

이렇게 적용하세요

1. 기존 의존성과 현재 구현을 먼저 검색합니다.
2. 필요한 기능과 번들·브라우저 조건을 공식 문서로 비교합니다.
3. 하나를 선택해 작은 상호작용으로 검증한 뒤 범위를 넓힙니다.

이런 실수는 피하세요

• 유행하는 라이브러리를 기존 GSAP 프로젝트에 추가하는 것
• 문서 버전이 다른 예제 코드를 섞어 사용하는 것

왜 필요한가

• 전통적인 다중 페이지 사이트에서도 부드러운 페이지 전환을 설계할 수 있습니다.
• 스크립트 재초기화, 브라우저 뒤로 가기, 스크롤 위치, 분석 도구가 복잡해질 수 있습니다.

이렇게 적용하세요

1. 프로젝트가 실제 다중 HTML 문서 구조인지 확인합니다.
2. 전환 없이도 모든 링크와 페이지가 먼저 정상 동작하게 만듭니다.
3. 페이지 진입·이탈 시 이벤트와 라이브러리 인스턴스를 정리하고 뒤로 가기를 검증합니다.

이런 실수는 피하세요

• Next.js 같은 기존 라우터 위에 같은 목적의 전환을 중복 설치하는 것
• JavaScript 실패 시 페이지 링크까지 사용할 수 없게 만드는 것

왜 필요한가

• 브라우저에서 복잡한 3D 장면과 상호작용을 구현할 수 있습니다.
• 모델 용량, GPU 부하, 모바일 발열, 대체 콘텐츠, 입력 방식까지 별도 설계가 필요합니다.

이렇게 적용하세요

1. 3D가 해결하는 사용자 목표와 제공 모델을 확인합니다.
2. 작은 장면으로 기기 성능과 로딩 시간을 측정합니다.
3. 저사양·WebGL 미지원·모션 감소 환경의 정적 대체 화면을 준비합니다.

이런 실수는 피하세요

• 2D 카드 배경을 위해 거대한 3D 엔진을 추가하는 것
• 모바일 성능과 접근 가능한 대체 설명을 생략하는 것

왜 필요한가

• 팀 취향이 아니라 반복 가능한 근거로 기술 선택을 설명할 수 있습니다.
• 불필요한 의존성 추가와 비슷한 도구의 중복을 막습니다.

이렇게 적용하세요

1. 동작, 시작 조건, 종료 조건, 사용자 입력을 적습니다.
2. CSS와 기본 API로 가능한지 먼저 평가합니다.
3. 접근성·성능·라이선스·기존 스택을 통과한 후보 하나만 선택합니다.

이런 실수는 피하세요

• ‘고급스러워 보여서 GSAP’처럼 느낌만으로 선택하는 것
• 선택 결과는 적고 검증 기준과 제거 조건은 적지 않는 것

왜 필요한가

• 기능이 사용자 문제를 해결하는지 항목마다 확인할 수 있습니다.
• 제외 범위와 완료 조건이 있어 구현 중 범위가 끝없이 늘어나는 것을 막습니다.

이렇게 적용하세요

1. 제품 개요·문제·목표 사용자를 한 문단씩 씁니다.
2. 제품 목표와 이번에 하지 않을 일을 목록으로 분리합니다.
3. 화면 목적→사용자 흐름→상태·데이터→개발 조건→완료 조건을 채웁니다.

이런 실수는 피하세요

• 디자인 색상부터 적고 사용자 문제를 마지막에 끼워 넣는 것
• 제외 범위를 ‘추후 결정’으로 모두 비워 두는 것

왜 필요한가

• 처음 작성하는 사람도 상태, 접근성, 반응형, 완료 조건을 놓치지 않습니다.
• 프로젝트마다 같은 순서로 검토할 수 있어 AI 요청과 리뷰가 빨라집니다.

이렇게 적용하세요

1. 아래 실습 영역의 `PRD.md` 템플릿을 현재 내용으로 수정합니다.
2. 대괄호 자리표시자를 전부 검색해 실제 값으로 바꿉니다.
3. 화면별로 목적·진입·행동·상태·완료 조건이 있는지 다시 읽습니다.

이런 실수는 피하세요

• 해당하지 않는 항목을 빈 제목으로 남기는 것
• 완료 조건에 구현할 기능을 다시 반복하고 검증 방법은 쓰지 않는 것

왜 필요한가

• 빈 템플릿만 볼 때 생기는 ‘어디까지 자세히 써야 하나’라는 질문에 기준을 제공합니다.
• 기능 요구가 상태·저장·검증 문장으로 이어지는 방식을 확인할 수 있습니다.

이렇게 적용하세요

1. 아래 완성 예시에서 한 기능을 골라 문제·흐름·상태·완료 조건 연결을 따라갑니다.
2. 자신의 프로젝트에서 같은 연결을 한 기능에 먼저 작성합니다.
3. 예시의 고유 이름과 값을 그대로 남기지 않았는지 검색합니다.

이런 실수는 피하세요

• 캠핑 서비스의 화면과 저장 키를 다른 프로젝트에 그대로 복사하는 것
• 완성 예시를 정답 양식으로 보고 프로젝트에 불필요한 기능까지 추가하는 것

왜 필요한가

• 반복되는 코드 품질 요구를 매 요청에 다시 쓰지 않아도 됩니다.
• AI가 관련 없는 리팩터링이나 패키지 추가를 하기 전에 제한을 확인하게 합니다.

이렇게 적용하세요

1. 현재 저장소의 설정과 명령을 먼저 확인합니다.
2. 반드시 지킬 규칙을 짧은 행동 문장으로 작성합니다.
3. 아래 템플릿의 기술 스택과 경로를 실제 프로젝트 값으로 교체합니다.

이런 실수는 피하세요

• 다른 저장소의 패키지 매니저와 명령을 그대로 복사하는 것
• PRD의 제품 기능을 전부 다시 적는 것

왜 필요한가

• 도구 전용 행동을 공통 제품 요구와 분리할 수 있습니다.
• 같은 규칙의 복제본이 서로 달라지는 문제를 줄입니다.

이렇게 적용하세요

1. 공통 기준 문서를 먼저 정합니다.
2. Claude Code에서만 필요한 규칙이 실제로 있는지 확인합니다.
3. 참조가 동작하지 않는 환경이라면 중복 대신 짧은 핵심 규칙으로 유지합니다.

이런 실수는 피하세요

• 지원 여부를 확인하지 않은 참조 문법을 사용하는 것
• 도구 이름만 바꾼 동일 문서를 여러 개 만드는 것

왜 필요한가

• 디자인 생성 중심 요청에서도 저장소 보존과 검증 절차를 놓치지 않게 합니다.
• 화면 구현과 문서 갱신의 순서를 고정할 수 있습니다.

이렇게 적용하세요

1. 현재 Antigravity가 읽는 규칙 위치를 확인합니다.
2. 프로젝트 공통 규칙을 넣고 특정 화면의 임시 요구는 PRD에 둡니다.
3. 작업 결과에서 규칙 적용 여부를 파일 변경과 검증 보고로 확인합니다.

이런 실수는 피하세요

• Rule이 적용되는지 시험하지 않고 모든 요청이 지켜질 것이라 믿는 것
• 현재 화면의 완료 상태를 영구 규칙으로 작성하는 것

왜 필요한가

• 새 대화나 다른 도구가 이전 작업을 다시 조사하는 시간을 줄입니다.
• 완료했다고 생각한 기능과 실제 검증된 기능을 구분할 수 있습니다.

이렇게 적용하세요

1. 구현 완료·진행 중·알려진 문제를 분리합니다.
2. 검증 명령과 실제 결과, 확인하지 못한 부분을 날짜와 함께 적습니다.
3. 작업이 끝날 때마다 바뀐 사실만 갱신하고 오래된 계획은 정리합니다.

이런 실수는 피하세요

• 성공하지 않은 테스트를 통과했다고 기록하는 것
• 작업 일지를 모두 쌓아 현재 상태를 찾기 어렵게 만드는 것

왜 필요한가

• AI가 익숙한 프레임워크로 임의 전환하는 것을 막습니다.
• 화면마다 공통 구조 확인과 검수 단계를 빠뜨리지 않습니다.

이렇게 적용하세요

1. 적용 조건과 목표를 작성합니다.
2. 확인→구조→스타일→동작→검증 순서로 작업 단계를 씁니다.
3. 프레임워크 도입, 가짜 에셋, 관련 없는 재작성 같은 금지사항을 명시합니다.

이런 실수는 피하세요

• 완성할 화면 목록을 Skill 안에 고정하는 것
• ‘잘 구현한다’처럼 행동을 알 수 없는 단계만 쓰는 것

왜 필요한가

• 화면마다 효과를 과도하게 추가하는 것을 막습니다.
• 마우스뿐 아니라 키보드, 터치, 스크롤, 모션 감소 환경을 함께 확인합니다.

이렇게 적용하세요

1. 동작의 시작·진행·종료 상태를 분석합니다.
2. CSS→기본 JavaScript→기존 라이브러리→새 라이브러리 순으로 선택합니다.
3. 빠른 반복 입력, 화면 이탈, 리사이즈, 모션 감소에서 정리 동작을 검증합니다.

이런 실수는 피하세요

• 디자인에 없는 스크롤 효과를 임의로 추가하는 것
• 동작만 확인하고 이벤트와 애니메이션 인스턴스를 정리하지 않는 것

왜 필요한가

• Figma 정보 조회와 코드 생성을 한 번에 섞어 생기는 추정을 줄입니다.
• 스크린샷 복제나 예시 코드 붙여넣기가 아니라 재사용 가능한 프로젝트 구조로 옮기게 합니다.

이렇게 적용하세요

1. PRD와 저장소 규칙, 대상 노드를 먼저 확인합니다.
2. 확인한 사실과 추정을 구분한 분석표를 작성합니다.
3. 대표 화면을 구현하고 캡처 비교를 통과한 패턴만 나머지 화면에 확장합니다.

이런 실수는 피하세요

• Figma에서 보이지 않는 기능과 에셋을 임의 생성하는 것
• 도구가 출력한 React 코드를 바닐라 프로젝트에 그대로 넣는 것

왜 필요한가

• AI가 요청 한 문장만 보고 범위를 추정하거나 관련 없는 파일을 고치는 것을 줄입니다.
• 완료 보고에 변경 파일과 검증 결과가 남아 다음 수정의 근거가 됩니다.

이렇게 적용하세요

1. 먼저 읽을 문서와 파일을 정확히 적습니다.
2. 이번 요청에서 바꿀 것과 바꾸지 않을 것을 구분합니다.
3. 실행할 검증과 결과 보고 항목을 명시하고 한 단계씩 요청합니다.

이런 실수는 피하세요

• ‘전체적으로 알아서 고쳐 줘’처럼 수정 범위를 비워 두는 것
• 검증하지 못한 부분을 보고하지 않게 하는 것

왜 필요한가

• 잘못된 프레임이나 화면 전체를 구현하는 범위 오류를 막습니다.
• Figma에서 확인한 사실과 저장소에서 지켜야 할 규칙을 함께 적용합니다.

이렇게 적용하세요

1. Figma 링크와 대상 프레임 이름·노드 범위를 적습니다.
2. metadata·screenshot·variables·assets 확인 후 분석만 보고하도록 1차 요청합니다.
3. 승인 뒤 대표 화면을 구현하고 동일 크기 캡처로 비교하게 합니다.

이런 실수는 피하세요

• 링크만 보내고 구현 화면과 상태 범위를 적지 않는 것
• 분석 단계 없이 바로 모든 화면 수정을 허용하는 것

왜 필요한가

• 구현을 시작한 뒤 발견하면 비용이 큰 누락을 문서 단계에서 찾습니다.
• AI가 질문해야 할 미확정 항목과 바로 실행할 확정 항목을 구분합니다.

이렇게 적용하세요

1. 대괄호 자리표시자와 빈 제목을 검색합니다.
2. 각 기능을 문제→화면→상태→완료 조건으로 추적합니다.
3. 충돌·추정·확인 불가 항목을 해결하거나 명시적으로 보류합니다.

이런 실수는 피하세요

• 목차가 모두 있다는 이유로 내용을 검토하지 않는 것
• 실행할 수 없는 완료 조건을 그대로 통과 처리하는 것

왜 필요한가

• 외부 코드가 늘어날수록 보안 업데이트와 호환성 책임도 늘어납니다.
• 효과 구현 후 성능과 입력 접근성이 나빠지는 것을 배포 전에 찾을 수 있습니다.

이렇게 적용하세요

1. 해결할 요구와 라이브러리 없이 어려운 이유를 적습니다.
2. 이미 설치된 대안과 공식 사용법·라이선스를 확인합니다.
3. 모바일 성능, 모션 감소, 키보드, 정리 동작을 실제 화면에서 시험합니다.

이런 실수는 피하세요

• CDN 예제가 동작하면 배포 조건도 모두 충족했다고 생각하는 것
• 사용하지 않는 라이브러리와 초기화 코드를 남기는 것

왜 필요한가

• 문서와 코드, 디자인과 브라우저 사이의 차이를 마지막에 한 번 더 연결합니다.
• 다음 작업자가 검증된 상태에서 이어서 작업할 수 있습니다.

이렇게 적용하세요

1. PRD와 규칙 파일의 완료 조건을 다시 읽습니다.
2. 빌드·테스트와 실제 화면·키보드·반응형 검수를 실행합니다.
3. 변경 파일, 통과 결과, 남은 문제를 `PROJECT_CONTEXT.md`와 최종 보고에 기록합니다.

이런 실수는 피하세요

• 빌드 성공만으로 디자인과 기능 검수를 생략하는 것
• 확인하지 못한 외부 데이터나 화면을 성공했다고 보고하는 것