smyw로 코딩 Agent가 코드를 작성하기 전에 프로토타입을 그리게 하기: 설치, 검토 및 피드백 완벽 가이드

smyw란 무엇인가

smyw는 “show me you want”의 약자로, Claude Code, DeepSeek Harness 등 SKILL.md를 지원하는 코딩 Agent를 위한 skill입니다. Agent가 페이지, 상호작용 흐름 또는 프런트엔드와 백엔드 간 인터페이스를 수정하기 전에 먼저 코드를 읽고 구조화된 spec을 작성한 다음, 오프라인에서 열 수 있는단일 파일 HTML 프로토타입을 생성하도록 합니다.

이 프로토타입은 최종 비주얼 시안이 아니라 모듈 구성, 배치 위치, 트리거 관계 및 기능 변화를 표현하기 위한 저충실도 와이어프레임입니다. 실제 구현은 여전히 프로젝트의 기존 디자인 규칙을 따라야 합니다.

어떤 문제를 해결하나요

기존 Agent 코딩 프로세스는 텍스트 요구사항에서 곧바로 구현으로 들어가는 경우가 많아 페이지 구조, 상호작용 방식 또는 인터페이스 경계에 대한 이해가 어긋나기 쉽습니다. smyw는 요구사항과 코드 사이에 시각적으로 확인할 수 있는 단계를 추가합니다.

1. 사용자가 기능 요구사항을 제시합니다.
2. Agent가 프로젝트 코드를 읽고 spec.json을 생성합니다.
3. 빌드 스크립트가 spec을 검증하고 preview.html을 출력합니다.
4. 사용자가 브라우저에서 방안을 확인하고, 시연하고, 드래그하고, 주석을 추가합니다.
5. 사용자가 피드백을 복사해 대화로 돌려보냅니다.
6. Agent가 피드백을 적용하고 다음 버전의 프로토타입을 생성합니다.
7. 사용자가 방안을 확인한 후에야 Agent가 코드를 작성하기 시작합니다.

smyw의 핵심은 디자인 도구를 대체하는 것이 아니라, 구현 전에 사용자와 코딩 Agent가 “무엇을 바꾸고, 어디에 배치하며, 어떻게 트리거할지”에 대해 일치된 이해를 갖도록 하는 것입니다.

핵심 기능

번호 표시와 변경 전후 비교

프로토타입은 실제 페이지 레이아웃에 맞춰 전체 화면을 그리고 색상으로 변경 사항을 구분합니다. 노란색은 수정, 초록색은 추가, 빨간색은 삭제를 의미합니다. 가장 바깥쪽 모듈에 변경이 발생한 경우에만 번호를 표시하여 내부 요소에 반복되는 표시가 대량으로 생기지 않도록 합니다.

캔버스의 번호 또는 왼쪽 변경 목록을 클릭하면 캔버스가 해당 영역에 초점을 맞추고, 오른쪽에 변경 전후의 부분 와이어프레임, 필드 차이, Agent 설명, 코드 컴포넌트 및 관련 함수나 인터페이스가 표시됩니다.

모듈 전체가 새로 추가된 내용이라면 상세 정보의 “변경 전”에는 해당 모듈이 원래 존재하지 않았다고 표시되며, 내부 버튼과 텍스트에는 항목별 번호가 더 이상 표시되지 않습니다.

컴포넌트 이동을 정확하게 표현

컴포넌트가 한 위치에서 다른 위치로 이동하면 기존 위치에는 빨간색 “이동 전”, 새 위치에는 초록색 “이동 후”가 표시됩니다. 두 기록은 서로 이동할 수 있어, 이것이 삭제 한 번과 무관한 추가 한 번의 조합이 아님을 확인할 수 있습니다.

레이어, 메뉴 및 펼쳐지는 콘텐츠

팝업, 서랍, 드롭다운 메뉴, 말풍선 및 클릭 후에만 펼쳐지는 콘텐츠는 메인 화면 옆의 독립 패널에 배치되며 연결선으로 트리거 버튼을 가리킵니다. 하나의 레이어는 여러 트리거 진입점과 연결할 수 있고, 삭제된 레이어는 빨간색 점선으로 표시됩니다.

다단계 메뉴는 인접한 패널로 계속 나뉩니다. 현재 위치에서 펼쳐지는 콘텐츠는 페이지에 보라색 점선 슬롯으로 남아 펼쳐진 후 나타날 위치를 보여줍니다. 페이지 이동과 상태 전환 연결선은 기본적으로 숨겨져 있으며, 관련 요소를 선택하면 확인하거나 “모든 연결선”을 통해 한꺼번에 열 수 있습니다.

클릭 가능한 시연 모드

오른쪽 상단의 “▶ 시연”을 클릭하면 프로토타입이 변경 프레임을 숨기고 한 화면에서 실제 조작을 시뮬레이션합니다. 메뉴 펼치기, 서랍 슬라이드, 팝업 열기, 버튼 상태 변경 및 페이지 이동 등을 시연할 수 있습니다.

조작할 수 없는 영역을 클릭하면 현재 클릭 가능한 모든 위치가 파란색 프레임으로 잠시 표시되고 왼쪽에도 실행 가능한 작업이 나열됩니다. 시연에서는 뒤로 가기, 처음부터 시작하기 및 “변경 전”과 “변경 후” 사이 전환을 지원합니다.

직접 편집과 통합 피드백

• 구조 편집: 컴포넌트를 드래그해 순서나 컨테이너 소속을 조정하고 텍스트, 유형, 너비 및 배치를 수정합니다.
• 형태 변환: 인라인 모듈을 팝업, 드롭다운 메뉴, 서랍 또는 말풍선으로 변환하면 시스템이 트리거 버튼과 연결선을 생성합니다.
• 실행 취소와 다시 실행: Ctrl 또는 Command와 Z를 함께 눌러 작업을 실행 취소할 수 있습니다.
• 요소 주석: 지정한 요소에 위치, 상호작용, 컴포넌트 유형, 스타일, 문구 또는 기능 누락 등의 범주로 의견을 추가합니다.
• 의견 수준: 주석을 “필수 수정”, “제안” 또는 “질문”으로 표시할 수 있습니다.
• 전체 피드백: 스타일 의견과 참고 방향을 기록하고 Agent가 미리 제시한 확인 질문에 답합니다.
• 패치 전달: 구조 수정은 ID로 위치를 지정하는 패치 형태로만 피드백 마지막에 첨부되므로 전체 방안을 다시 전달할 필요가 없습니다.

설치 전 준비

sm yw 프로토타입을 빌드하려면 Node.js 18 이상만 필요하며, 프로젝트 자체에는 서버나 실행 종속성이 필요하지 않습니다. 먼저 Node.js 버전을 확인합니다.

node --version

저장소의 엔드투엔드 테스트를 실행하거나 스크린샷을 다시 생성하려면 Google Chrome도 설치해야 합니다. 기본 설치 경로가 아닌 경우 CHROME 환경 변수로 경로를 지정할 수 있습니다.

smyw skill 설치

1단계: 저장소 클론

git clone https://github.com/nishuzumi/show-me-you-want-skill.git
cd show-me-you-want-skill

2단계: Agent가 읽을 수 있는 위치에 skill 배치

Claude Code 사용자는 전역 심볼릭 링크를 만들어 모든 프로젝트에서 smyw를 사용할 수 있습니다.

ln -s "$PWD/skills/smyw" ~/.claude/skills/smyw

Agent가 공용 skills 디렉터리를 읽는 경우 다음 위치에 연결할 수도 있습니다.

ln -s "$PWD/skills/smyw" ~/.agents/skills/smyw

특정 프로젝트에서만 활성화하려면 해당 프로젝트의 로컬 skill 디렉터리에 복사합니다.

cp -r skills/smyw <프로젝트>/.claude/skills/smyw

설치가 완료되면 Agent에 인터페이스나 API를 수정하는 요구사항을 제시하거나, 바로 “먼저 프로토타입을 만들어 보여줘.”라고 말할 수 있습니다.

저장소 예제 먼저 실행

저장소에는 이미 생성된 HTML 예제 두 개가 제공되므로 서버를 시작할 필요 없이 브라우저에서 바로 열 수 있습니다.

• skills/smyw/examples/helpdesk-ai/preview.html: 고객 지원 워크벤치에 AI 추천 답변을 추가한 전체 단일 화면 예제입니다.
• skills/smyw/examples/task-tags/preview.html: 전체 페이지 추가와 전체 페이지 삭제를 보여주는 다중 페이지 예제입니다.

예제의 spec을 수정한 후 다음 명령으로 미리보기를 다시 생성할 수 있습니다.

node skills/smyw/scripts/build.mjs skills/smyw/examples/helpdesk-ai/spec.json

빌드 결과물은 순수 프런트엔드 단일 파일이므로 오프라인에서 열고 검토할 수 있습니다.

요구사항에서 프로토타입까지의 기본 사용법

1단계: Agent에 요구사항 설명

비즈니스 목표와 제약사항을 가능한 한 구체적으로 설명하되, 모든 인터페이스 세부사항을 미리 결정할 필요는 없습니다. 예를 들면 다음과 같습니다.

고객 지원 티켓 상세 화면에 AI 추천 답변을 추가해 주세요. 기존 페이지와 인터페이스를 먼저 읽고 바로 코드를 작성하지 마세요. smyw를 사용해 프로토타입을 만들고, 서랍 진입점, 답변 교체 흐름 및 관련 인터페이스를 확인할 수 있게 해 주세요.

2단계: 생성된 spec과 미리보기 확인

Agent는 다음과 비슷한 디렉터리에 구조화된 방안을 저장합니다.

.smyw/<날짜>-<이름>/spec.json

그다음 build.mjs를 사용해 검증하고 preview.html을 생성합니다. 미리보기를 연 후 다음 순서로 확인할 수 있습니다.

1. 먼저 “맞춤”을 사용해 전체 캔버스를 뷰포트에 맞춥니다.
2. 노란색, 초록색, 빨간색 변경 프레임이 요구사항에 맞는지 확인합니다.
3. 변경 목록을 차례로 클릭해 변경 전후 비교와 필드 변화를 확인합니다.
4. 관련 컴포넌트, 함수 및 인터페이스가 기존 코드와 대응하는지 확인합니다.
5. “흐름 변화”와 “백엔드 변화”를 열어 계층 간 영향을 확인합니다.
6. 시연 모드로 들어가 실제로 메뉴, 팝업, 서랍 및 상태 버튼을 클릭합니다.

3단계: 방안 편집 및 주석 추가

구조가 예상과 다르면 “방안 편집”으로 전환해 컴포넌트를 직접 드래그하거나 인라인 콘텐츠를 레이어로 변환할 수 있습니다. 직접 수정하기에 적합하지 않은 의견은 요소를 선택한 후 주석을 추가하고 범주와 우선순위를 설정합니다.

다음 세 가지 피드백을 명확히 구분하는 것이 좋습니다.

• 필수 수정: 구현 전에 반드시 반영해야 하는 문제입니다.
• 제안: Agent가 채택 여부를 판단할 수 있지만, 채택하지 않을 경우 이유를 설명해야 합니다.
• 질문: 먼저 답변하고 명확히 한 뒤 조정 방법을 결정해야 합니다.

4단계: 피드백을 복사해 Agent에 전달

“피드백” 페이지로 이동해 전체 스타일 의견을 보완하고 확인이 필요한 질문에 답한 다음 “피드백 복사”를 클릭합니다. 생성된 Markdown을 Agent 대화에 붙여 넣으면 됩니다.

Agent는 일반적으로 피드백을 feedback-v<N>.md로 저장한 후 다음을 실행합니다.

node skills/smyw/scripts/apply-feedback.mjs .smyw/<dir>/feedback-v1.md .smyw/<dir>/spec.json
node skills/smyw/scripts/build.mjs .smyw/<dir>/spec.json

apply-feedback.mjs는 기존 spec을 백업하고 피드백의 패치를 적용한 뒤 버전 번호를 증가시킵니다. 피드백 버전이 현재 spec과 일치하지 않으면 최신 방안을 덮어쓰지 않도록 스크립트가 적용을 거부합니다.

5단계: 확인 후 코딩 시작

다음 버전의 프로토타입을 확인하고 모든 “필수 수정” 의견이 반영되었으며 “질문”에 답변되었는지 확인합니다. 다른 문제가 없으면 “방안 확인, 시작 가능”을 클릭한 후 Agent가 정식 구현 단계로 들어가도록 합니다.

spec의 기본 구조 이해

smyw는 하나의 트리를 사용해 변경 전후의 인터페이스를 동시에 설명합니다. 각 노드는 change로 변화를 표시하고, 상호작용과 상태는 on, hidden 및 states로 설명합니다.

{
  "id": "reply",
  "type": "form",
  "label": "고객에게 답변",
  "component": "<ReplyBox>",
  "change": "modified",
  "before": { "label": "답변" },
  "children": [
    {
      "id": "reply-quick",
      "type": "select",
      "text": "빠른 답변",
      "change": "removed"
    },
    {
      "id": "reply-polish",
      "type": "button",
      "label": "AI 다듬기",
      "change": "added",
      "fn": "openDraftDrawer({ mode: \"polish\" })",
      "on": [
        { "action": "open", "target": "ai-drawer" }
      ]
    }
  ]
}

이 예시는 답변 양식 제목이 “답변”에서 “고객에게 답변”으로 변경되고, 기존 빠른 답변이 삭제되며, AI 서랍을 여는 버튼이 추가된 것을 보여 줍니다. component는 코드 구성 요소를 나타내고, fn은 관련 동작 또는 API 자리 표시자를 의미합니다.

전체 필드 설명은 spec-format.md에서 확인할 수 있으며, Agent의 실행 규칙은 SKILL.md에서 확인할 수 있습니다.

고급 사용 팁

인터페이스, 흐름, 백엔드를 함께 확인하기

페이지 레이아웃만 검토하지 마세요. API 또는 데이터 변경이 포함된 기능이라면 프로세스 스윔레인과 백엔드 변경 사항도 확인해야 합니다. 프로세스 스윔레인은 사용자, 프런트엔드, 백엔드, 데이터베이스 및 외부 서비스를 기준으로 변경 전후를 비교하며, 단계의 위치 지정 진입점을 통해 해당 인터페이스 요소로 돌아갈 수 있습니다.

툴바로 코드 영향 이해하기

• “ƒ 함수”를 열어 요소 이면의 동작 또는 API 자리 표시자를 확인합니다.
• “구성 요소”를 열어 모듈에 대응하는 코드 구성 요소를 확인합니다.
• “변경되지 않은 항목 흐리기”를 열어 이번 요구 사항의 영향 범위에 집중합니다.
• 전체 트리거 관계를 검토해야 할 때만 “모든 연결선”을 엽니다.

데모 모드로 상태 변경 검증하기

데모 모드는 이동 경로를 확인하는 데 그치지 않고 상태 연동을 검증하는 데도 적합합니다. 예를 들어 “답변 상자로 교체” 버튼은 초안을 답변 상자에 입력하고 서랍을 닫을 수 있습니다. 주석은 당시 표시된 페이지, 열려 있던 콘텐츠 및 클릭 기록을 자동으로 기록하므로 Agent가 문제를 재현하는 데 도움이 됩니다.

ID를 안정적으로 유지하기

피드백의 구조 변경은 노드 ID를 기준으로 위치를 찾습니다. 따라서 여러 차례 반복 작업을 진행할 때는 기존 노드 ID를 최대한 안정적으로 유지해야 합니다. 요소 자체가 삭제되었거나 의미가 완전히 변경된 경우가 아니라면 ID를 임의로 바꾸지 마세요.

빌드 검증 중시하기

build.mjs는 중복 ID, before가 없는 변경 노드, 실제 모듈 대신 “（변경 없음）”을 사용하는 경우, 트리거가 없는 팝업 등 일반적인 문제를 확인합니다. 오류가 발생하면 먼저 spec을 수정한 뒤 생성 결과를 검토해야 합니다.

좁은 창과 샌드박스 제한 처리하기

Agent 측면 미리보기와 같은 좁은 창에서는 변경 목록이 “☰ 변경” 버튼 안으로 들어가고, 세부 정보는 캔버스 위에 표시됩니다. 제한된 샌드박스에서는 브라우저가 진행 상황 저장 또는 자동 복사를 차단할 수 있습니다. 복사에 실패하면 페이지가 피드백 내용을 자동으로 선택하므로 Ctrl 또는 Command와 C를 함께 누르면 됩니다.

프로젝트 개발 및 테스트

smyw 자체를 수정해야 한다면 엔드투엔드 테스트를 실행하거나 README 스크린샷을 다시 생성할 수 있습니다.

node tests/e2e.mjs
node tests/readme-shots.mjs

테스트에는 Node.js 18 이상 버전과 Google Chrome이 필요합니다. Chrome이 기본 경로에 없으면 다음과 같이 지정할 수 있습니다.

CHROME=/path/to/chrome node tests/e2e.mjs

이 프로젝트는 MIT 라이선스를 사용합니다.

정리

smyw는 코딩 Agent의 작업 흐름을 “요구 사항을 이해한 후 바로 코드를 작성”하는 방식에서 “먼저 코드를 읽고, spec을 생성하고, 상호 작용 가능한 프로토타입을 보여 주고, 구조화된 피드백을 수집한 다음 구현을 시작”하는 방식으로 바꿉니다. 특히 페이지 레이아웃, 팝업, 상태 전환, 여러 페이지로 이루어진 흐름 또는 프런트엔드와 백엔드 간 API가 포함된 요구 사항에 적합합니다.

저장소 예시부터 사용해 보고 Agent가 skill을 읽을 수 있는지 확인한 후 실제 프로젝트에 적용하세요. 변경 표시, 데모 모드, 직접 편집, 주석 및 버전 관리 피드백을 활용하면 요구 사항 이해의 차이를 크게 줄이고, 이미 확인된方案을 바탕으로 정식 코딩을 시작할 수 있습니다.