개발의 시작이자 끝 ..

개발의 시작이자 끝

개발명세서, 간트차트, 프레임워크 세팅 — 이게 생각보다 정말 중요하다

1. 일단 코딩부터 시작하면 벌어지는 일

아이디어가 생기면 바로 코드를 치고 싶어진다. "대충 머릿속에 그림이 있으니까 하면서 맞추면 되지"라는 생각으로 시작한다.

그렇게 2~3주가 지나면 이런 말을 듣게 된다.

"근데 이 기능, 이렇게 하는 게 맞아?"

그 시점에는 이미 라우팅, DB 스키마, 권한 구조가 첫 번째 판단 위에 전부 쌓여 있다. 다시 설계하면 절반을 다시 짜야 한다.

이번엔 다르게 해보기로 했다.

2. 만들려는 것 — 흩어진 사내 업무를 하나로

우리 팀은 여러 개의 업무 툴을 사용하고 있다. 일정 관리, 입찰 공고 조회, 파일 저장, 견적 시스템이 각각 다른 화면에 흩어져 있다.

문제는 "본인이 직접 들어가서 확인해야만 알 수 있다" 는 것이다.

마감 D-3인 입찰 공고도, 대표님 승인이 필요한 견적서도, 오늘 현장 일정이 잡힌 업무도 — 누가 알려주지 않으면 그냥 지나친다.

만들려는 건 이 흩어진 것들을 하나로 모아, 지금 내가 봐야 할 것을 먼저 알려주는 툴이다. 사람이 일일이 확인하던 것을 시스템이 대신 챙겨주는 구조.

3. 명세서를 먼저 쓴다는 것의 의미

코드를 치기 전에 스펙 문서를 먼저 작성했다. 처음에는 "어차피 바뀔 건데 왜?" 싶었는데, 써보니 생각보다 많은 결정을 강제로 앞당기게 된다는 걸 알았다.

인증 방식 하나만 봐도 그렇다. 처음에는 JWT Access/Refresh Token 구조로 설계했다. 그런데 막상 정책을 정리하다 보니 이런 조건들이 나왔다.

사용자는 최대 200명 이하
회원가입 없음, 관리자가 계정 발급
자동 로그아웃 60분, 최대 세션 8시간

JWT의 Refresh Token 갱신 로직이 이 규모에는 불필요한 복잡도였다. 결국 Server Session + HttpOnly Secure Cookie로 전환했다. 문서를 쓰기 전이었다면 이 결정을 코드 짜다가 중간에 뒤집었을 것이다.

명세서는 "나중에 참고할 문서"가 아니라 "결정을 앞당기는 도구" 다.

간트차트도 마찬가지였다. 기능을 우선순위별로 나눠 일정에 배치하고 나서야, "이번 배포에서 반드시 완성해야 하는 화면"이 명확해졌다. 중요하지 않은 화면에 시간을 쓰는 낭비가 사라졌다.

4. Figma MCP + Claude Code로 와이어프레임을 코드로 생성하다

기획과 우선순위가 확정된 시점에서 와이어프레임 작업을 시작했다. 이번엔 Figma에서 직접 도형을 배치하는 대신, Claude Code + Figma MCP를 연결해서 JavaScript 코드로 Figma 프레임을 직접 생성했다.

Figma MCP는 Figma 플러그인 API를 Claude가 직접 실행할 수 있게 해주는 인터페이스다. 코드를 작성하면 Claude가 Figma 캔버스에 실시간으로 프레임을 그린다.

먼저 Figma API의 반복 호출을 줄이기 위한 헬퍼 함수를 정의한다.

// 사각형 생성

function R(parent, x, y, w, h, color, cornerRadius) {

  const node = figma.createRectangle();

  node.x = x; node.y = y; node.resize(w, h);

  if (color) node.fills = [{ type: 'SOLID', color }];

  if (cornerRadius) node.cornerRadius = cornerRadius;

  parent.appendChild(node);

  return node;

}

// 텍스트 생성

function T(parent, x, y, text, fontSize, color, fontWeight) {

  const node = figma.createText();

  node.fontName = { family: 'Inter', style: fontWeight || 'Regular' };

  node.characters = String(text);

  node.fontSize = fontSize;

  node.fills = [{ type: 'SOLID', color }];

  node.x = x; node.y = y;

  parent.appendChild(node);

  return node;

}

// 프레임 생성

function F(parent, x, y, w, h, color, name) {

  const frame = figma.createFrame();

  frame.x = x; frame.y = y; frame.resize(w, h);

  frame.fills = color ? [{ type: 'SOLID', color }] : [];

  if (name) frame.name = name;

  parent.appendChild(frame);

  return frame;

}

이 헬퍼 위에서 실제 UI 컴포넌트를 조립한다. 예를 들어 KPI 카드 4개를 한 번에 생성하는 코드는 이렇다.

const KPI_DATA = [

  { label: '이번 달 총 주행거리', value: '1,240 km',   icon: '🏎', bg: { r:.93, g:.96, b:1   } },

  { label: '이번 달 총 주유비',   value: '382,000원',  icon: '⛽', bg: { r:1,   g:.98, b:.9  } },

  { label: '사용 차량',           value: '3 대',        icon: '🚗', bg: { r:.92, g:1,   b:.94 } },

  { label: '미첨부 영수증',       value: '2 건',        icon: '📋', bg: { r:1,   g:.93, b:.93 } },

];



KPI_DATA.forEach((kpi, i) => {

  const card = F(mainFrame, 4 + i * (cardW + 12), KPI_Y, cardW, 80, white, KPI_${i});

  card.cornerRadius = 10;

  R(card, 12, 18, 46, 46, kpi.bg, 23);                       // 아이콘 배경 원

  T(card, 66, 20, kpi.label, 10, textMuted);

  T(card, 66, 36, kpi.value, 18, textDark, 'Semi Bold');

});

각 화면 오른쪽에는 개발자용 주석 박스도 자동으로 생성된다. API 엔드포인트, 권한 정책, DB 필드 기준, 오류 처리 케이스까지 — 기획 내용이 와이어프레임 옆에 바로 붙어 있다.

이 방식으로 인증 화면, 대시보드, 알림, 견적서, 차량/주유비 등 15개 이상의 화면을 단 몇 시간 만에 완성했다.

5. 마치며 — AI는 모호함을 싫어한다

이번 작업에서 확신하게 된 것이 하나 있다.

AI를 빠르게 쓰려면 기획이 먼저 명확해야 한다.

"화면 좀 만들어줘"라고 하면 AI는 임의로 판단한다.

"최대 200명, Server Session, 권한 3단계, 이 필드들로 이 화면을 만들어줘"라고 하면 AI는 정확하게 만든다.

명세서와 간트차트는 AI에게 건네는 가장 정밀한 설계도다. 이게 없으면 AI는 빠르지 않다. 오히려 사람이 매 대화마다 맥락을 다시 설명하는 데 시간을 쓴다.

개발의 시작이자 끝 ..