HTML Demo와 프론트엔드 프로젝트를 위한 Prototype Notes Skill입니다.
최근 저는 AI에게 프로토타입 페이지와 프론트엔드 코드를 직접 생성하게 하는 일이 점점 익숙해졌습니다.
페이지는 빠르게 만들어지지만 새로운 문제가 함께 생겼습니다.
“이 버튼을 클릭하면 2차 확인이 필요합니다.”
“여기 이미지는 보기 좋지 않으니 다른 방식으로 바꿔 주세요.”
“표에서 카테고리를 전환하면 아래 데이터도 함께 필터링해야 합니다.”
이런 내용은 대체 어디에 적어야 할까요?
스크린샷을 보내고, 빨간 박스를 그리고, 문서를 작성하고, 단체 채팅에 한마디를 덧붙이면 개발자가 페이지에서 해당 위치를 한참 찾아야 합니다. 페이지가 수정되면 기존 스크린샷은 다시 쓸 수 없고, 의견이 많아지면 채팅의 맥락도 쉽게 사라집니다.
그래서 Prototype Notes(프로토타입 주석)라는 Skill을 만들었습니다. HTML 프로토타입이나 프론트엔드 개발 환경에 독립적인 주석 도구를 추가해 요구사항과 수정 의견을 페이지 현장에 직접 남길 수 있습니다.
정확히 어떤 기능인가요?
간단히 말하면 웹페이지에 “현장 메모”를 붙이는 것과 같습니다.
주석 모드를 켠 뒤 페이지의 원하는 위치에서 마우스 오른쪽 버튼을 클릭하면 두 가지 유형의 내용을 추가할 수 있습니다.
요구사항 설명: 제품 관리자가 새로운 요구사항이나 변경 사항을 작성하는 용도입니다. 우선순위와 상태를 설정하고 여러 설명을 추가할 수 있습니다.
수정 의견: 검토자가 리뷰 의견을 제시하는 용도입니다. 작성자 이름은 입력해야 하지만 우선순위와 상태는 설정하지 않습니다.
>주석 모드를 켠 뒤 마우스 오른쪽 버튼을 클릭해 추가할 주석 유형을 선택합니다
제출하면 설명은 페이지 위의 작은 아이콘으로 접힙니다. 개발자는 아이콘을 클릭해 맥락을 확인할 수 있으므로 “스크린샷에서 말하는 위치가 어디인지” 다시 추측할 필요가 없습니다.
주요 기능
01 요구사항 설명과 검토 의견을 분리
제품 요구사항과 검토 의견은 원래 서로 다른 정보입니다. Skill은 이를 하나의 폼에 억지로 넣지 않고, 오른쪽 버튼 메뉴에서부터 명확하게 구분합니다.
>요구사항 설명: 여러 내용, 우선순위, 신규 또는 변경 상태, 저장 시간
>수정 의견: 검토자 이름을 입력하고 리뷰 의견을 바로 기록합니다
02 하나의 마커에 여러 설명을 담기
같은 위치의 관련 요구사항을 아이콘 여러 개로 채울 필요가 없습니다. 하나의 요구사항 마커에 여러 설명을 계속 추가할 수 있고, 수정 의견 마커에도 여러 의견을 추가할 수 있으며 배지로 개수를 표시합니다.
03 마커와 플로팅 창을 모두 이동
마커 위치가 정확하지 않으면 직접 드래그해 다시 배치할 수 있습니다. 플로팅 창도 옮길 수 있어 현재 보고 있는 페이지 내용을 가리지 않습니다. 마커는 상대 위치를 기록하므로 페이지를 스크롤하거나 크기가 바뀌어도 대상 요소에 최대한 붙어 있습니다.
04 설명에 이미지를 바로 붙여넣기
텍스트만으로 설명하기 어려울 때는 스크린샷을 복사해 현재 설명에 바로 붙여넣으면 됩니다. 이미지는 자동으로 압축되어 주석 데이터와 함께 저장되며, 별도로 삭제할 수도 있습니다.
05 주석 모드가 아니면 엄격한 읽기 전용
일상적으로 페이지를 볼 때는 실수로 내용을 수정할 수 없고 일반적인 오른쪽 버튼 메뉴도 가로채지 않습니다. 주석 모드를 직접 켠 경우에만 주석 추가, 편집, 이동, 가져오기 또는 삭제가 가능합니다.
>일반 보기 모드: 설명은 볼 수 있지만 편집 및 삭제 작업은 할 수 없습니다
06 Git 저장소의 JSON에 자동 저장
주석 데이터는 프로젝트 루트 디렉터리의 다음 파일에 저장됩니다.
.prototype-notes/annotations.json
저장, 이동, 가져오기 또는 삭제 후 개발 환경이 이 파일을 자동으로 다시 기록합니다. 팀원이 Git에 커밋하면 주석도 프로젝트와 함께 공유되고 검토되며 이력이 보존됩니다. 수동 가져오기와 내보내기도 장애 복구 방법으로 계속 지원합니다.
07 정식 빌드에는 주석 코드가 포함되지 않음
이 도구는 단순히 “숨기기”를 클릭해 안전한 것처럼 보이게 하는 방식이 아닙니다. Vite 프로젝트는 개발 모드에서만 런타임을 로드하며, 저장 API도 개발 서버에만 연결됩니다. 정적 HTML 프로젝트는 배포 전에 제거 작업을 실행할 수 있습니다. 배포 점검의 목표는 프로덕션 결과물에 주석 런타임과 주석 내용이 아예 포함되지 않도록 하는 것입니다.
제가 특히 마음에 든 몇 가지 세부 기능
파란색 문서 아이콘과 주황색 의견 아이콘. 플로팅 창을 열지 않아도 제품 요구사항인지 검토 의견인지 알 수 있습니다.
주석 모드에서만 오른쪽 버튼을 제어. 평소에는 웹페이지 자체의 동작을 방해하지 않고, 기록이 필요할 때만 켤 수 있습니다.
모든 설명에 가장 최근 저장 시간이 표시. 개발자는 현재 보고 있는 내용이 최신 버전인지 판단할 수 있습니다.
로컬 캐시로 보완. 자동 기록에 실패해도 브라우저의 초안이 바로 사라지지 않으며 도구 모음에 “동기화 실패”가 표시됩니다.
출처 식별자를 기본 제공. 현재 버전은 “泥嚎的AI实验室”를 표시하며 런타임, 개발 도구 및 내보낸 JSON에 통일된 검증 가능 식별자를 유지합니다.
어떤 문제를 해결하나요?
첫째, 요구사항 맥락의 손실을 줄입니다. 요구사항이 더 이상 페이지와 분리되어 채팅 기록이나 문서에 따로 흩어지지 않습니다.
둘째, 제품과 개발자의 위치 확인 비용을 줄입니다. 특정 컨트롤에 마커가 붙어 있어 페이지를 열면 어디를 수정해야 하는지 바로 알 수 있습니다.
셋째, 제품 요구사항과 리뷰 피드백을 분리합니다. 누가 제안했는지, 어떤 성격의 내용인지 한눈에 구분할 수 있습니다.
넷째, AI 프로토타입을 실제 반복 개발 과정에 포함합니다. AI가 빠른 생성을 담당하고, 주석 레이어가 이후 피드백을 다시 AI나 개발자에게 전달합니다.
다섯째, 배포 안전성을 해치지 않습니다. 주석은 개발 및 검토 환경에만 속하며 정식 제품 기능이 되지 않습니다.
상황별 활용 방법
상황 1: AI가 생성한 단일 페이지 HTML Demo
AI가 Prototype Notes Skill을 사용해 주석 레이어를 설치하고 함께 제공되는 로컬 개발 서비스를 시작하도록 합니다. 제품 담당자가 페이지에서 마우스 오른쪽 버튼을 클릭해 요구사항을 작성하면 저장 후 프로젝트 JSON에 자동으로 들어갑니다. 확인이 끝나면 런타임을 제거하고 정적 페이지를 배포합니다.
상황 2: Vue / React + Vite 프론트엔드 프로젝트
Skill은 런타임을 개발 도구 디렉터리에 넣고 개발 서버에서만 실행되는 저장 플러그인을 설치합니다. 평소처럼 프로젝트의 개발 명령을 실행하면 사용할 수 있으며, 정식 빌드에서는 주석 런타임이 로드되지 않습니다.
상황 3: 제품 담당자와 개발자가 하나의 Git 저장소에서 협업
제품 담당자가 마커를 저장한 뒤 annotations.json을 커밋하면 개발자는 코드를 가져와 원래 페이지에서 확인할 수 있습니다. 수정이 끝나면 계속 커밋하면 됩니다. Git은 버전, 병합 및 이력을 담당하고 주석 도구는 페이지 현장의 의사 표현을 담당합니다.
상황 4: 디자인 또는 업무 검토
검토자가 “수정 의견 추가”를 선택하고 이름을 남긴 뒤 제안을 기록합니다. 제품 요구사항이 검토 의견과 섞이지 않으며 개발자도 의견을 누가 제시했는지 알 수 있습니다.
상황 5: 보기 권한만 있는 검토 회의
주석 모드를 끄면 참가자는 계속 아이콘을 클릭해 내용을 볼 수 있지만 편집할 수는 없습니다. 모든 마커를 한 번에 숨겨 페이지를 깔끔한 보기 상태로 되돌릴 수도 있습니다.
Skill 설치 및 호출 방법
이 Skill은 현재 아직 오픈 소스로 공개되지 않았습니다. 사용해 보고 싶다면:
“泥嚎的AI实验室”를 팔로우하세요
다음 키워드를 포함해 DM을 보내 주세요: 原型批注
Skill 압축 파일과 사용 설명서를 보내 드립니다.
압축 파일을 받은 뒤 개인 Codex Skill 디렉터리에 압축을 풉니다.
C:\Users\사용자 이름\.codex\skills\prototype-notes
Codex 작업을 다시 열면 다음과 같이 호출할 수 있습니다.
$prototype-notes를 사용해 현재 HTML 프로토타입에 주석 기능을 추가해 줘.
자연어로 직접 말해도 됩니다.
“이 Vue/Vite 프로젝트에 프로토타입 주석을 설치하고, 데이터를 Git JSON에 자동 저장해 줘. 프로덕션 빌드에는 주석 코드가 포함되지 않게 해 줘.”
“이 단일 페이지 HTML Demo에 요구사항 설명과 이름을 남기는 수정 의견을 추가하고 로컬 미리보기도 시작해 줘.”
사용 중 자주 발생하는 문제
1. 페이지는 열리지만 저장 후 JSON이 바뀌지 않음
대부분 일반 정적 서버를 사용한 경우입니다. 브라우저는 Git 파일에 직접 쓸 수 없으므로 Skill이 설치한 HTML 개발 서비스를 사용하거나 Vite에서 함께 제공되는 개발 플러그인을 활성화해야 합니다. 도구 모음에 “동기화 실패”가 표시되어도 로컬 캐시에 초안이 보존됩니다.
2. 다른 컴퓨터에서 주석이 보이지 않음
.prototype-notes/annotations.json이 Git에 커밋되었는지, 상대방이 최신 코드를 가져왔는지 확인하세요. localStorage는 로컬 컴퓨터의 보완 수단일 뿐 팀 공유 저장소가 아닙니다.
3. 오른쪽 버튼을 클릭해도 주석 메뉴가 나타나지 않음
먼저 오른쪽 아래의 “주석” 버튼을 클릭해 주석 모드로 들어가세요. 일반 모드에서는 브라우저의 기본 오른쪽 버튼 메뉴를 유지해 일상적인 작업을 방해하지 않습니다.
4. 페이지를 개편한 뒤 마커 위치가 어긋남
주석 모드에서 아이콘을 새 위치로 드래그하세요. 자주 구조가 변경되는 중요한 영역에는 AI가 안정적인 data-prototype-anchor를 추가하도록 하면 변경되기 쉬운 DOM 계층에 의존하는 일을 피할 수 있습니다.
5. Git에서 annotations.json을 병합할 때 충돌이 발생함
이 도구는 비동기 협업에 적합하며 실시간 다중 편집 도구는 아닙니다. 주석을 시작하기 전에 최신 브랜치를 먼저 가져오세요. 여러 사람이 동시에 수정할 때는 마커 ID와 업데이트 시간을 기준으로 충돌을 확인하세요. 진정한 실시간 다중 동기화가 필요하다면 데이터베이스 서비스 도입을 고려하세요.
6. 내부 요구사항이나 스크린샷이 외부로 유출될까 걱정됨
주석 내용, 검토자 이름, 페이지 라우트 및 붙여넣은 이미지에는 민감한 정보가 포함될 수 있습니다. 프로젝트는 비공개 저장소를 사용해야 합니다. 로컬 개발 서비스를 신뢰할 수 없는 네트워크에 노출하지 말고 .prototype-notes 디렉터리를 온라인에 배포하지도 마세요.
7. 이미지가 너무 많아 브라우저에 저장할 수 없음
런타임이 이미지를 압축하고 설명 하나에 포함되는 이미지 개수를 제한하지만, 스크린샷은 여전히 JSON 용량을 늘립니다. 문제와 직접 관련된 화면만 남기고 큰 이미지는 먼저 잘라낸 뒤 붙여넣는 것을 권장합니다.
마지막으로
AI 덕분에 “페이지를 만드는 일”은 점점 빨라지고 있지만, 페이지에서 실제 제공 가능한 제품으로 나아가려면 여전히 명확한 요구사항과 검토, 협업이 필요합니다.
제가 이 Skill을 만든 것은 거대한 프로젝트 관리 시스템을 다시 만들기 위해서가 아니라, 작지만 구체적인 빈틈 하나를 메우고 싶었기 때문입니다.
의견이 실제로 발생한 그 자리에 남도록 하는 것.