혼자 서비스 만들면서 제일 어려운 게 개발이 아니라 기획/디자인
혼자 서비스를 만들 때 발목을 잡는 건 코드가 아니라 화면이다. 레이아웃을 잡지 않으면 디자인은 매번 예측 불가능해진다.
이 아티클의 핵심 내용 요약과 글로벌 검색·AI 엔진을 위한 테이크어웨이입니다.
✦ KR 주제: AI로 UI를 개선할 때 상상 대신 실제 코드에서 출발하는 design-from-code 워크플로
✦ KR 핵심 요약: design-from-code는 컴포넌트 JSX와 데이터 모델을 읽어 사실을 검증하고, 현재 화면을 AS-IS로 재현한 뒤 자기완결 HTML 목업으로 TO-BE를 합의하고, 그 결과를 .md 문서로 고정해 구현을 위임하는 Claude Code 플러그인 겸 Codex 스킬이다.
🌐 Global Takeaway: Instead of letting a model imagine a screen, the skill verifies facts in the real source code, reproduces the current UI, and iterates self-contained HTML mockups until approved. The agreed design is then locked into a markdown document and handed off for implementation.
혼자 서비스를 굴려본 사람이라면 공감할 것이다. 막상 손이 안 가는 지점은 코드가 아니라 화면이다. 레이아웃을 제대로 잡아두지 않으면 디자인은 매번 뒤죽박죽이 되고, 다음에 무엇이 나올지 예측이 안 된다. 원문 작성자도 같은 지점에서 막혔고, 그 불편을 그대로 스킬로 만들었다고 말한다. 이름은 design-from-code, Claude Code 플러그인이자 Codex 스킬이며 MIT 라이선스로 공개돼 있다.
문제는 ‘그림’을 먼저 그린다는 순서에 있다
AI에게 “이 화면 좀 더 예쁘게 바꿔줘”라고 하면 결과물은 꽤 그럴듯하게 나온다. 문제는 그 그림이 실제 서비스의 데이터 구조와 맞는지다. 리포지토리 README는 대부분의 “UI 변경 디자인해줘” 프롬프트가 똑같은 두 가지 방식으로 실패한다고 설명한다.
첫째, 모델이 데이터가 어떻게 동작하는지 추측한다. “이 방문자 수는 대체 무엇을 세는 숫자인가”라는 질문에 상상으로 답하면 거의 100% 틀린다는 표현이 README에 나온다. 둘째, 목업이 도식적이라서 실제 화면과 맞지 않는다. 그래서 그럴듯한 시안과 실제 구현 사이에 간극이 생기고, 그 간극을 메우는 비용이 고스란히 개발자 몫으로 돌아온다.
AI가 상상으로 화면 그리는 게 아니라 → 실제 소스코드를 읽고 → 지금 화면을 그대로 재현하고 → HTML 목업으로 같이 보면서 맞춰가는 방식.
이 순서 하나가 바뀌면 결과가 달라진다는 것이 이 도구의 주장이다.
design-from-code가 제안하는 워크플로
README에 적힌 한 줄 요약은 이렇다. 코드에서 사실을 검증하고(Verify facts in code), HTML로 합의하고(agree on HTML), 그 합의를 .md로 고정한 뒤(lock it in a .md), 구현은 위임한다(delegate the build).
| 단계 | 하는 일 | 남는 것 |
|---|---|---|
| 1. 사실 검증 | 실제 컴포넌트 JSX를 읽고 데이터 모델을 따라간다 | 추측이 아닌 확인된 전제 |
| 2. 현재 재현 | 지금 화면을 AS-IS로 그대로 재현한다 | 비교 가능한 기준선 |
| 3. 목업 반복 | 자기완결 HTML 목업을 승인할 때까지 고친다 | 눈으로 합의된 TO-BE |
| 4. 문서화·위임 | 합의 내용을 .md로 고정하고 구현을 넘긴다 | 사실에 근거한 디자인 문서 |
데이터 추적은 handler에서 schema까지
특히 눈에 띄는 부분은 데이터 확인 절차다. 화면을 그리기 전에 handler → use-case → repository → schema 순서로 코드를 따라가며, 이 화면에 뿌려지는 값이 무엇인지 사실로 확정한다. 화면을 예쁘게 만드는 일보다, 그 화면이 말하는 숫자가 무엇인지 먼저 맞추는 일이 우선이라는 태도다. 혼자 개발할 때 가장 자주 놓치는 게 정확히 이 지점이다. 레이아웃이 흔들리는 이유도 대개 데이터가 무엇을 의미하는지 확정하지 않은 채 배치부터 정했기 때문이다.
산출물은 하나의 HTML 파일이다
README에 실린 예시는 실제 nlook 기능(이슈 #976)을 다룬 것이다. 결과물에는 세 가지가 한 파일에 담긴다. MobileBottomBar.tsx에서 재현한 현재 상태(AS-IS), 제안하는 변경(TO-BE, 초록은 신규·노랑은 변경), 그리고 데이터가 0건일 때의 빈 상태(empty state)다. 전부 하나의 자기완결 HTML 파일이고 의존성이 없다. 브라우저로 열면 바로 확인할 수 있는 형태라, 말로 설명하는 대신 같은 화면을 보면서 맞춰갈 수 있다. 이 점이 “어떻게 나올지 예측이 안 된다”는 불만에 직접 대응하는 부분이다.
핵심 정리
- 혼자 만드는 서비스에서 병목은 개발이 아니라 기획과 디자인, 그중에서도 레이아웃을 잡지 않는 습관이다.
- design-from-code는 상상으로 화면을 그리지 않고, 실제 소스코드에서 사실을 확인한 뒤 현재 화면을 재현하는 방식으로 시작한다.
- 합의는 자기완결 HTML 목업으로 하고, 그 합의를 .md 문서로 고정한 다음 구현을 위임한다.
- Claude Code 플러그인과 Codex 스킬 두 형태로 제공되고, MIT 라이선스로 공개돼 있다.
실무 적용 포인트
원문에서 강조한 사용 조건이 하나 있다. “어느 정도 만들어진 상태에서 디자인 개선할 때 특히 잘 맞는다”는 것이다. 이미 화면과 코드가 존재해야 읽을 소스가 있고, 재현할 기준선이 생기기 때문이다. 반대로 아무것도 없는 백지 상태의 신규 화면 설계에서는 이 워크플로의 장점이 상대적으로 줄어든다.
적용할 때 챙길 점을 정리하면 다음과 같다.
- 디자인 요청 전에 데이터 의미를 먼저 확인한다. 방문자 수, 잔여량, 상태값처럼 해석이 갈리는 값은 코드에서 근거를 찾는다.
- 목업은 승인용 중간 산출물로 쓴다. 최종 결과물은 구현자에게 넘길 .md 문서라는 점을 분리해서 생각한다.
- AS-IS와 TO-BE, 그리고 빈 상태를 함께 그린다. 데이터가 없을 때의 화면이 빠지면 실제 구현 단계에서 다시 흔들린다.
- 혼자 개발할 때는 “내가 정한 레이아웃”을 문서로 남기는 것 자체가 다음 작업의 예측 가능성을 만든다.
확인되는 범위에서의 한계
이 도구가 모든 디자인 문제를 해결한다고 단정하기는 어렵다. 공개된 자료를 기준으로 보면, 이 스킬이 다루는 범위는 기존 UI를 코드라는 사실 위에서 개선하는 워크플로다. 브랜드 아이덴티티나 카피라이팅, 정보 구조 설계 같은 기획의 상위 단계까지 대신해 주는 것은 아니다. 또한 결과물의 품질은 결국 읽어낸 코드와 사용자가 승인한 목업에 의존한다. 다만 “레이아웃이 예측 불가능하다”는 혼자 개발자의 흔한 문제에 대해, 추측을 줄이고 합의를 눈에 보이게 만드는 방법을 제시한다는 점은 분명하다.
마무리
개발 실력이 부족해서 화면이 흔들리는 경우는 생각보다 적다. 대개는 순서의 문제다. 그림을 먼저 그리고 데이터를 나중에 맞추면 매번 뒤죽박죽이 되고, 데이터를 먼저 확인하고 현재 화면 위에서 합의하면 결과가 예측 가능해진다. design-from-code는 그 순서를 스킬로 굳혀둔 사례다. 이미 서비스를 어느 정도 만들어둔 상태라면, 다음 디자인 개선 작업에서 이 순서를 한 번 따라가 볼 만하다.
자주 묻는 질문
Q. design-from-code는 어떤 도구인가요?
A. 기존 UI 변경을 실제 소스코드에 근거해 설계하는 워크플로 스킬로, Claude Code 플러그인과 Codex 스킬 두 형태로 제공되며 MIT 라이선스로 공개돼 있습니다. 코드에서 사실을 검증하고 HTML 목업으로 합의한 뒤 .md로 고정해 구현을 위임하는 순서를 따릅니다.
Q. 어떤 상황에서 특히 유용한가요?
A. 원문 작성자는 어느 정도 만들어진 상태에서 디자인을 개선할 때 특히 잘 맞는다고 설명합니다. 읽을 실제 소스와 재현할 현재 화면이 있어야 하므로, 백지 상태의 신규 화면 설계보다는 기존 화면 개선에 적합합니다.
Q. 결과물은 어떤 형태로 나오나요?
A. 하나의 자기완결 HTML 파일로 나옵니다. 예시에서는 MobileBottomBar.tsx에서 재현한 현재 화면(AS-IS), 제안 변경(TO-BE, 초록은 신규·노랑은 변경), 데이터 0건일 때의 빈 상태가 한 파일에 담겼고 의존성이 없습니다. 이후 합의 내용은 .md 디자인 문서로 정리됩니다.



댓글 0개