7장 IT 프로젝트 및 소프트웨어 개발

소프트웨어를 만드는 일은 집을 짓는 과정과 비슷합니다. 설계도를 그리고, 자재를 고르고, 골조를 세우고, 내부를 마감하고, 누수가 없는지 점검합니다.

이 과정에서 가장 많은 시간이 걸리는 작업은 벽돌을 쌓는 행위가 아니라, 벽돌을 어디에 어떻게 쌓을지 결정하고, 제대로 쌓았는지 확인하는 과정입니다. 클로드 코드(Claude Code)와 코워크(Cowork) 는 이 결정과 확인의 영역에서 개발자와 기획자의 부담을 줄여줍니다.

이 장은 앞선 1~6장과 성격이 다릅니다. 코드를 다루는 장이지만, 코딩 경험이 없는 독자도 요구사항 정의서(PRD) 작성이나 테스트 케이스 문서 생성 같은 기획 영역은 따라 할 수 있도록 문턱을 낮추었습니다. 반면 에이전트 팀 운용이나 코드 마이그레이션처럼 개발 경험이 필요한 영역은 개념 이해에 비중을 두되, 실행은 중급 이상의 독자를 대상으로 안내합니다.

1 에이전트 팀 기반 병렬 작업

가 혼자서 네 사람 몫을 해야 하는 개발자의 하루

웹 애플리케이션 하나를 만든다고 생각해 보겠습니다.

사용자가 보는 화면(프론트엔드)을 만들어야 하고, 화면 뒤에서 데이터를 처리하는 서버(백엔드)를 구축해야 하며, 데이터를 저장하는 데이터베이스를 설계해야 합니다. 마지막으로 이 셋이 제대로 맞물려 돌아가는지 테스트해야 합니다.

한 사람이 이 네 가지를 순서대로 하면, 앞의 작업이 끝나야 뒤의 작업을 시작할 수 있습니다. 백엔드가 완성되지 않으면 프론트엔드에서 데이터를 불러올 수 없고, 데이터베이스 구조가 확정되지 않으면 백엔드 코드를 짤 수 없습니다. 이 순차적 병목이 개발 기간을 늘리는 가장 큰 원인입니다.

실제 기업에서는 이 문제를 팀으로 해결합니다. 프론트엔드 개발자, 백엔드 개발자, 데이터베이스 관리자, QA 엔지니어가 각자 맡은 영역을 동시에 작업하고, 필요할 때 서로 소통하며 조율합니다. 에이전트 팀(Agent Teams)은 이 인간 팀의 구조를 AI로 재현한 것입니다.

나 에이전트 팀이란 무엇인가

에이전트 팀은 여러 개의 클로드 코드 인스턴스(Instance, 동시에 실행되는 개별 AI 세션)가 각각 독립된 역할을 맡아 하나의 프로젝트를 병렬로 수행하는 기능입니다. 2026년 2월 클로드 오퍼스 4. 6(Opus 4.6) 출시와 함께 연구 미리보기(Research Preview) 형태로 공개되었습니다.

이전에도 서브 에이전트(Sub-agent)라는 개념이 있었습니다.

서브 에이전트는 메인 에이전트가 작업을 지시하면 독립적으로 수행한 뒤 결과만 돌려보내는 방식이었습니다. 문제는 서브 에이전트끼리 서로 대화할 수 없다는 점이었습니다. 프론트엔드 서브 에이전트가 백엔드 서브 에이전트에게 "API 주소가 바뀌었으니 코드를 고쳐라"라고 직접 말할 방법이 없었습니다. 모든 메시지가 메인 에이전트를 거쳐야 했고, 이 병목 때문에 복잡한 프로젝트에서는 서로의 코드가 충돌하는 일이 잦았습니다.

에이전트 팀은 이 구조를 바꿨습니다. 팀원 에이전트끼리 메시지를 직접 주고받을 수 있습니다. 공유 작업 목록(Shared Task List)을 통해 누가 어떤 일을 하고 있는지 확인하고, 하나의 작업이 끝나면 다음 작업을 스스로 가져갑니다. 팀 리드(Team Lead) 역할의 에이전트가 전체를 조율하되, 실무적인 소통은 팀원끼리 직접 합니다.

[알아두기] 에이전트 인스턴스란? 하나의 클로드 코드 세션을 뜻합니다. 각 인스턴스는 자기만의 문맥 창(Context Window, AI가 한 번에 기억할 수 있는 정보의 범위)을 갖고 독립적으로 작동합니다. 클로드 오퍼스 4.6은 인스턴스당 100만 토큰(약 75만 단어)의 문맥 창을 지원하므로, 대규모 코드베이스를 통째로 올려놓고 작업할 수 있습니다.

다 에이전트 팀은 어떻게 쓰는가

(1) 기본 사용: 에이전트 팀 활성화와 첫 실행 에이전트 팀은 실험 기능이므로 별도로 켜야 합니다.

① 클로드 코드의 설정 파일(settings.json)을 엽니다.

② 다음 한 줄을 추가합니다. "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"

③ 설정을 저장하고 클로드 코드를 재시작합니다.

④ 터미널에서 다음과 같이 지시합니다. "이 프로젝트의 README.md 파일과 전체 폴더 구조를 분석한 뒤, 보안 검토 담당과 코드 품질 검토 담당 두 명의 에이전트 팀을 만들어서 코드 리뷰를 수행해줘."

⑤ 클로드 코드가 팀 리드 역할을 자임하고, 두 개의 팀원 에이전트를 생성합니다. 터미널에 각 에이전트의 활동 로그가 표시됩니다.

⑥ 팀원 에이전트들이 각자 코드를 분석하고, 발견한 문제를 서로에게 메시지로 공유합니다. 팀 리드가 결과를 종합하여 최종 리뷰 보고서를 생성합니다.

(2) 응용 사례: tmux로 에이전트별 화면 분리 tmux(터미널 다중화 도구)를 설치해 두면, 각 에이전트의 작업 화면을 분할하여 동시에 관찰할 수 있습니다.

① tmux가 설치된 상태에서 에이전트 팀을 실행하면, 화면이 여러 패널로 나뉘어 각 에이전트의 터미널이 따로 보입니다.

② Shift + 방향키를 눌러 특정 에이전트의 패널로 이동한 뒤, 그 에이전트에게만 개별 지시를 내릴 수 있습니다.

"프론트엔드 에이전트야, 방금 만든 로그인 페이지의 버튼 색상을 파란색에서 남색으로 바꿔줘."

③ 해당 에이전트가 지시를 받아 수정하고, 변경 사항을 팀원들에게 알립니다.

(3) 실전 활용: 블로그 플랫폼 구축 프로젝트 중소규모 블로그 플랫폼을 구축하는 시나리오입니다.

① 프로젝트 폴더에 요구사항 문서를 준비합니다. (PRD 작성 방법은 이 장의 2절에서 다룹니다.)

② 클로드 코드에 다음과 같이 지시합니다.

"이 PRD를 읽고, 백엔드 API 담당, 프론트엔드 UI 담당, 데이터베이스 스키마 담당, 테스트 작성 담당으로 구성된 에이전트 팀을 만들어줘. 백엔드 에이전트는 Node.js와 Fastify로 REST API를 구현하고, 프론트엔드 에이전트는 React로 UI를 구현해. 데이터베이스 에이전트는 PostgreSQL 스키마를 먼저 확정해서 다른 에이전트에게 공유해줘. 테스트 에이전트는 각 API 엔드포인트에 대한 단위 테스트를 작성해."

③ 클로드가 팀을 구성하고 작업을 분배합니다. 데이터베이스 에이전트가 스키마를 먼저 확정하면, 백엔드 에이전트와 프론트엔드 에이전트가 그 스키마를 기준으로 동시에 코드를 작성합니다.

④ 작업이 진행되는 동안 팀 리드가 진행 상황을 요약하여 보여줍니다. 충돌이 발생하면 우선순위를 판단하여 해결합니다.

라 에이전트 팀을 쓸 때 알아두어야 할 것

에이전트 팀은 토큰 소모량이 많습니다. 각 팀원이 독립된 문맥 창을 유지하면서 서로 메시지를 주고받기 때문에, 같은 작업을 단일 에이전트로 할 때보다 비용이 4~7배 늘어날 수 있습니다. 간단한 스크립트 작성이나 파일 정리 같은 일에는 에이전트 팀을 쓸 이유가 없습니다.

에이전트 팀이 효과를 내는 상황은 분명합니다. 여러 계층(프론트엔드, 백엔드, 데이터베이스, 테스트) 을 동시에 건드려야 하는 프로젝트, 서로 다른 가설을 동시에 검증해야 하는 디버깅, 대규모 코드 리뷰처럼 병렬 탐색이 실질적 가치를 만드는 경우입니다.

한 가지 더. 에이전트 팀이 만들어낸 코드는 개별적으로는 깔끔해 보여도, 전체 시스템의 맥락에서 예상치 못한 충돌을 일으킬 수 있습니다. 한 에이전트가 성능을 위해 도입한 캐싱 구조가 다른 에이전트

가 만든 실시간 동기화 로직과 부딪히는 식입니다. 에이전트가 코드를 짜는 속도는 빨라졌지만, 그 코드가 전체 시스템 안에서 어떻게 작동하는지 판단하는 책임은 여전히 사람에게 있습니다.

마 이런 문제가 생겼다면

(1) 에이전트 팀을 생성했는데 한 개의 메시지만 보내고 세션이 종료되는 경우 settings.json에 에이전트 팀 설정이 올바르게 저장되었는지 확인합니다. 큰따옴표와 콜론 위치가 정확한지 살펴보고, 클로드 코드를 완전히 종료한 뒤 재시작합니다.

(2) 팀원 에이전트끼리 같은 파일을 동시에 수정하여 코드가 깨지는 경우 프롬프트에서 파일 소유권을 명시합니다. "각 에이전트는 자기 담당 폴더의 파일만 수정하고, 다른 에이전트의 파일은 읽기만 해"라고 지시하면 충돌을 줄일 수 있습니다.

(3) 토큰 사용량이 예상보다 훨씬 많은 경우 팀원 수를 줄입니다. 3명이면 충분한 작업에 5명을 투입하면 조율 비용만 커집니다. 프로(Pro) 요금제보다 맥스(Max) 요금제가 에이전트 팀 작업에 적합합니다.

2 소프트웨어 요구사항 정의서 및 아키텍처 문서화

가 "결제 기능 있는 앱 만들어줘"가 실패하는 이유

AI에게 코드를 시키는 일에서 가장 흔한 실패는 AI의 능력 부족이 아니라 지시의 모호함에서 옵니다. " 결제 기능이 있는 프로젝트 관리 앱을 만들어줘"라고 말하면, AI는 수많은 빈칸을 스스로 메웁니다. 결제 수단은 카드인가 계좌이환인가, 사용자 인증은 이메일인가 소셜 로그인인가, 프로젝트 관리의 단위는 팀인가 개인인가. AI가 채워넣은 가정이 사용자의 의도와 다를 때, 결과물은 누구도 원하지 않던 것이 됩니다.

요구사항 정의서(PRD, Product Requirements Document)는 이 빈칸을 미리 채우는 문서입니다. 무엇을 만들 것인지, 누구를 위한 것인지, 성공의 기준은 무엇인지, 이번에 하지 않을 것은 무엇인지를 명확하게 적습니다. PRD의 품질이 프로젝트의 성패를 좌우합니다.

나 클로드 코드가 만드는 PRD는 어떤 것인가

클로드 코드의 계획 모드(Plan Mode)를 활용하면, AI가 코드를 한 줄도 쓰지 않고 오직 분석과 설계에만 집중합니다. 머릿속에 떠다니는 파편적인 아이디어를 입력하면, AI가 체계적인 질문을 던져 빈틈을 메우고, 그 결과를 수십 페이지짜리 기획 문서로 정리해 냅니다.

최종 산출물에는 다음과 같은 내용이 담깁니다. 서비스의 목적과 성공 기준, 핵심 사용자 여정(User Journey), 기능 요구사항과 비기능 요구사항(성능, 보안, 가용성), 데이터베이스 스키마(테이블 간 관계, 데이터 타입, 제약 조건), 시스템 아키텍처(기술 스택, 인프라 배치, 인증 체계), 그리고 테스트 시나리오입니다.

다 PRD를 만들어 보겠습니다

(1) 기본 사용: 아이디어에서 질문 목록 뽑기

① 클로드 코드 터미널을 열고 계획 모드로 전환합니다.

② 다음과 같이 입력합니다.

"중고 물품 거래 앱을 만들고 싶어. 위치 기반 검색, 채팅, 에스크로 결제가 핵심이야. 코드를 짜기 전에, 내 프로젝트에 대한 가정을 줄이기 위해 명확화 질문을 10가지 이상 던져줘."

③ 클로드가 다음과 같은 질문을 제시합니다. "위치 기반 검색의 기본 반경은 몇 킬로미터로 설정할까요?" "채팅에서 이미지 전송을 지원할까요?" "에스크로 결제의 수수료율은 얼마로 잡을까요?" "회원가입은 이메일 인증 방식인가요, 소셜 로그인인가요?" "판매자 인증 절차가 필요한가요?"

④ 각 질문에 답합니다.

⑤ 클로드가 모든 답변을 바탕으로 PRD 초안을 생성합니다.

(2) 응용 사례: 데이터베이스 스키마와 API 명세까지 포함하기

① 기본 사용에서 생성된 PRD 초안을 확인한 뒤, 추가 지시를 입력합니다.

"이 PRD를 바탕으로 데이터베이스 스키마를 Prisma 형식으로 설계해줘. User, Product, Transaction, Chat, Review 테이블을 포함하고, 각 관계와 인덱스를 명시해. 그리고 핵심 API 엔드포인트를 OpenAPI 형식으로 정리해줘."

② 클로드가 Prisma 스키마 파일과 OpenAPI 명세를 생성합니다.

③ 생성된 문서를 열어 내용을 검토합니다.

(3) 실전 활용: PRD를 에이전트 팀의 실행 지침서로 쓰기 PRD의 진짜 가치는 이 문서가 코딩의 출발점이 된다는 데 있습니다.

① PRD가 완성되면 클로드 코드 세션을 초기화합니다. 문맥 창에 이전 대화가 섞이면 혼란이 생기기 때문입니다.

② 새 세션에서 다음과 같이 지시합니다.

"이 폴더에 있는 PRD.md 파일과 schema.prisma, openapi.yaml을 읽어. 이 문서에 적힌 대로 에이전트 팀을 구성해서 앱을 구현해줘. 백엔드는 Fastify, 프론트엔드는 React, 데이터베이스는 PostgreSQL을 써."

③ 에이전트 팀이 PRD를 '실행 지침서(Source of Truth)'로 삼아 작업을 시작합니다.

라 AI가 만든 PRD를 그대로 쓰면 안 되는 이유

AI가 만든 PRD는 출발점이지 최종본이 아닙니다. AI는 논리적으로 빈틈없는 구조를 잘 만들지만, 비즈니스 맥락의 미묘한 차이를 완전히 이해하지 못합니다. 한국의 에스크로 결제 규정, 개인정보보호법의 데이터 보관 요건, 대상 고객의 연령대에 따른 UX 선호도 같은 현실적 제약은 사람이 반드시 검토해야 합니다.

검토 순서는 이렇게 잡는 편이 좋습니다. 제품 책임자가 목표와 범위를 확인합니다. 엔지니어가 기술적 실현 가능성을 봅니다. 보안 담당이 인증, 암호화, 로그 정책을 점검합니다. 운영 담당이 배포와 모니터링 체계를 살펴봅니다. 좋은 설계서는 한 번에 완성되는 문서가 아니라, 검토를 거치며 결정을 명확하게 남기는 문서입니다.

마 비개발자도 할 수 있는 영역

PRD 작성은 코딩 경험이 없어도 충분히 할 수 있습니다. 서비스의 아이디어를 말로 설명하고, AI의 질문에 답하는 과정은 비즈니스 감각의 영역입니다. 코워크(Cowork)의 데스크톱 인터페이스에서도 동일한 과정을 수행할 수 있으므로, 터미널이 낯선 독자는 코워크에서 시작하는 것을 권합니다.

바 이런 문제가 생겼다면

(1) PRD가 너무 일반적이고 우리 프로젝트에 맞지 않는 느낌인 경우 명확화 질문 단계를 건너뛰고 바로 PRD를 요청하면 이런 결과가 나옵니다. AI에게 질문을 먼저 던지게 하고, 구체적으로 답한 뒤에 문서를 생성하게 하면 품질이 올라갑니다.

(2) 생성된 데이터베이스 스키마에 필요한 테이블이 빠져 있는 경우 "감사 로그(Audit Log), 알림(Notification), 파일 첨부(Attachment) 테이블을 추가해줘"처럼 누락된 요소를 구체적으로 지정합니다.

3 코드 마이그레이션 및 자동 테스트

가 기술 부채라는 보이지 않는 빚

기술 부채(Technical Debt)는 오래된 코드가 쌓아올린 보이지 않는 비용입니다. 새 기능을 추가할 때마다 예상 못한 곳에서 오류가 터지고, 새로운 개발자가 합류하면 코드를 파악하는 데만 몇 주가 걸리고, 보안 패치를 적용하려면 의존성 문제에 빠집니다. 그래서 기업들은 주기적으로 코드 마이그레이션(Migration, 기존 프레임워크를 새 프레임워크로 전환하는 작업)을 수행합니다.

이 작업은 개발팀이 가장 꺼리는 업무 중 하나입니다. 새 기능을 만드는 것이 아니라 기존 기능을 유지하면서 내부 구조만 바꾸는 일이기 때문입니다. 사용자 눈에 보이는 변화는 없는데 투입되는 시간과 비용은 막대합니다.

나 클로드 코드가 마이그레이션을 돕는 방식

클로드 오퍼스 4.6의 100만 토큰 문맥 창은 수십만 줄의 코드베이스 전체를 한 번에 분석할 수 있게 합니다. 기존 AI 도구들은 코드를 잘게 쪼개서 입력해야 했기 때문에 파일 간 의존성을 놓치기 쉬웠지만, 이제는 전체 구조를 파악한 상태에서 변환 계획을 세울 수 있습니다.

마이그레이션은 대체로 네 단계를 거칩니다. 첫째, 현재 코드의 경계를 파악합니다. 라우트, 미들웨어, 인증, 에러 처리, 데이터베이스 접근, 외부 API 호출을 분리합니다. 둘째, 현재 API의 구조를 OpenAPI 나 JSON Schema로 고정합니다. 셋째, 새 프레임워크의 구조에 맞게 재구성합니다. 넷째, 기존 버전과 새 버전을 나란히 두고 동작 차이를 검증합니다.

다 Express에서 Fastify로 전환하기

(1) 기본 사용: 마이그레이션 분석 보고서 생성① 기존 Express 프로젝트 폴더를 클로드 코드에 연결합니다. ② 다음과 같이 지시합니다.

"이 프로젝트 전체를 분석해줘. Express의 app.get, app.post 패턴을 사용하는 모든 라우트를 찾고, 미들웨어 체인을 매핑하고, 데이터베이스 쿼리가 어디서 실행되는지 정리해줘. 코드를 수정하지 말고, Fastify로 전환할 때의 위험도를 1(낮음)에서 5(높음)까지 평가한 마이그레이션 분석 보고서를 만들어줘."

③ 클로드가 프로젝트를 스캔하여 전체 파일의 상호 참조 관계와 위험 요소를 분석한 보고서를 생성합니다.

(2) 응용 사례: 단계별 전환 실행

① 분석 보고서를 검토한 뒤, 위험도가 낮은 모듈부터 전환을 시작합니다.

"위험도 1~2로 평가된 라우트부터 Fastify 형식으로 변환해줘. Express의 req, res 객체를 Fastify의 request, reply 객체로 바꾸고, 각 라우트에 JSON Schema 기반 요청 검증을 추가해줘."

② 클로드가 해당 파일들을 변환합니다. 이때 기계적 치환이 아니라, Express의 미들웨어 방식과 Fastify의 플러그인 방식의 구조적 차이를 반영합니다.

(3) 실전 활용: 자동 테스트 생성과 검증

코드를 옮기는 것만큼 중요한 일이 옮긴 코드가 제대로 작동하는지 확인하는 것입니다.

① 다음과 같이 지시합니다. ②"변환된 Fastify 라우트 각각에 대해 단위 테스트를 생성해줘. 정상 요청, 잘못된 파라미터, 인증 실패, 리소스 없음, 서버 에러 시나리오를 포함해. Fastify의 inject 방식으로 네트워크 포트를 열지 않고 테스트할 수 있게 해줘."

② 클로드가 각 엔드포인트에 대한 테스트 코드를 생성합니다.

③ 생성된 테스트를 실행하여 통과 여부를 확인합니다. "방금 만든 테스트를 전부 실행해줘."

④ 클로드가 테스트를 돌리고, 실패한 항목이 있으면 원인을 분석하여 코드를 수정합니다. 이 과정을 모든 테스트가 통과할 때까지 반복합니다.

E2E(End-to-End) 테스트까지 필요하면 Playwright(브라우저 자동화 도구)를 연동합니다. "Playwright를 사용해서 사용자가 로그인하고, 상품을 검색하고, 장바구니에 담고, 결제하는 전체 흐름을 테스트하는 E2E 테스트 코드를 만들어줘."

라 AI가 만든 테스트의 한계

AI가 생성한 테스트는 코드의 현재 동작을 그대로 검증합니다. 현재 동작 자체에 버그가 있다면, 그 버그를 정상으로 간주하는 테스트가 만들어질 수 있습니다. 그래서 AI가 생성한 테스트 코드도 사람이 검토해야 합니다. "이 테스트가 검증하는 동작이 우리가 의도한 동작이 맞는가"를 확인하는 과정은 자동화할 수 없습니다.

과거 개발자가 남겨둔 비합리적으로 보이는 로직이 사실은 특정 운영 환경의 버그를 우회하기 위한 해결책이었을 수도 있습니다. AI는 이런 이면의 역사를 모른 채 코드를 정리해 버릴 수 있습니다. 마이그레이션에서 보존해야 할 것이 무엇인지 판단하는 일은 사람의 몫입니다.

마 이런 문제가 생겼다면

(1) 마이그레이션 도중 "Cannot find module" 에러가 반복되는 경우 의존성 패키지가 새 프레임워크와 호환되지 않는 경우입니다. 클로드에게 "package.json의 의존성 목록을 분석해서 Fastify와 호환되지 않는 패키지를 찾아줘"라고 지시합니다.

(2) 테스트가 전부 통과하는데 실제 서비스에서 오류가 나는 경우 테스트가 커버하지 못한 시나리오가 있다는 뜻입니다. 운영 환경의 실제 데이터 패턴이나 네트워크 지연 같은 조건을 테스트에 반영해야 합니다.

4 UI/UX 웹 디자인 및 피그마 동기화

가 디자이너와 개발자 사이의 오래된 강

디자이너가 피그마(Figma, 웹 기반 디자인 도구)에서 정교하게 만든 시안이 개발자의 코드로 구현되면, 미묘하게 달라집니다. 여백이 4픽셀 어긋나고, 폰트 굵기가 세미볼드 대신 볼드로 적용되고, 그림자의 투명도가 달라집니다. 디자인 시안을 개발자에게 넘기는 과정을 핸드오프(Handoff)라 부르는데, 이 구간이 제품 개발에서 마찰이 가장 큰 지점 중 하나였습니다.

AI는 이 핸드오프의 마찰을 줄이고 있습니다. 세 가지 방향에서 접근합니다.

나 피그마 MCP 연동이란 무엇인가

MCP(Model Context Protocol)는 AI가 외부 도구와 데이터를 주고받는 통신 규격입니다. 피그마가 MCP 서버를 제공하면서, 클로드 코드가 피그마 캔버스의 디자인 정보를 직접 읽고 쓸 수 있게 되었습니다. 2026년 2월 17일에 공개된 '코드 투 캔버스(Code to Canvas)' 기능으로 양방향 동기화가 가능해졌습니다.

피그마 MCP 서버는 스크린샷의 픽셀만 보는 것이 아닙니다. 컴포넌트의 계층 구조, 색상 코드, 폰트 크기, 여백 수치, 디자인 토큰(Design Token, 디자인의 기본 단위를 정의한 값) 같은 구조적 정보를 읽어냅니다.

다 피그마와 클로드 코드를 연결하고 써보겠습니다

(1) 기본 사용: 피그마 MCP 서버 설정

① 피그마 데스크톱 앱을 최신 버전으로 업데이트합니다.

② 클로드 코드 터미널에서 다음 명령어를 입력합니다.

claude mcp add --transport http figma https://mcp.figma.com/mcp

③ 클로드 코드에서 /mcp 명령어를 입력하여 피그마 서버가 연결되었는지 확인합니다.

④ 피그마에서 인증을 요청하면 "Allow Access"를 클릭합니다.

(2) 응용 사례: 피그마 디자인을 코드로 변환하기

① 피그마에서 변환하고 싶은 프레임(화면 단위)을 선택합니다.

② 클로드 코드에 피그마 링크를 붙여넣고 다음과 같이 지시합니다.

"이 피그마 디자인을 분석해서 React 컴포넌트로 변환해줘. Tailwind CSS를 사용하고, 반응형 브레이크포인트를 적용해줘. 디자인에 정의된 색상 코드와 폰트 크기를 그대로 반영해."

③ 클로드가 피그마 MCP를 통해 디자인의 구조적 정보를 읽어들이고, React 컴포넌트 코드를 생성합니다.

④ 생성된 코드를 로컬 서버에서 실행하여 디자인 시안과 비교합니다.

(3) 실전 활용: 코드에서 피그마로 역방향 전송

이 기능이 양방향 동기화를 실현하는 핵심입니다. 개발자가 코드로 만든 UI를 피그마 캔버스로 보내, 디자이너가 편집 가능한 프레임으로 받아볼 수 있습니다.

① 클로드 코드에서 로컬 서버를 실행한 상태에서 다음과 같이 지시합니다.

"내 앱의 로컬 서버를 시작하고, 현재 화면을 캡처해서 새 피그마 파일로 보내줘."

② 클로드가 브라우저 창을 열고, 캡처 도구 모음을 표시합니다. 페이지 전체, 특정 요소, 여러 화면을 연속으로 캡처할 수 있습니다.

③ 캡처가 완료되면 클로드가 피그마 파일 링크를 제공합니다. 이 링크를 열면 캡처된 화면이 편집 가능한 피그마 프레임으로 변환되어 있습니다.

④ 디자이너가 피그마에서 색상이나 여백을 수정하면, 클로드 코드가 그 변경 사항을 감지하여 코드에 반영할 수 있습니다. "피그마에서 이 프레임의 변경 사항을 확인하고, 변경된 부분만 코드에 반영해줘."

라 알아두어야 할 제약 사항

피그마 MCP 서버의 일부 기능은 특정 조건에서만 작동합니다. 코드 투 캔버스(Code to Canvas) 기능은 현재 클로드 코드, OpenAI 코덱스(Codex), VS Code에서만 지원됩니다. 피그마 플랜도 Dev 또는 Full 시트, Organization 또는 Enterprise 플랜이 필요합니다. API 호출에는 속도 제한(Rate Limit) 이 있으므로, 대량의 프레임을 한꺼번에 변환하면 속도가 느려질 수 있습니다.

AI가 생성하는 UI 코드의 시각적 정확도는 높아지고 있지만, 접근성(Accessibility) 기준을 자동으로 충족하지는 못합니다. 스크린 리더(Screen Reader, 시각 장애인용 화면 읽기 프로그램) 호환성, 키보드 내비게이션, 색상 대비 비율 같은 세부 사항은 사람이 별도로 검증해야 합니다. 드래그 앤 드롭, 무한 스크롤, 복잡한 폼 검증 같은 인터랙션 로직은 AI가 만든 코드의 품질이 들쭉날쭉합니다.

디자인의 겉모습은 AI가 빠르게 만들 수 있습니다. 하지만 사용자의 손끝에 전해지는 반응의 속도감, 스크롤할 때 화면이 나타나는 호흡, 오류 메시지가 전하는 어조 같은 것은 여전히 사람이 다듬어야 하는 영역입니다.

마 실무 도입은 세 단계로

한 번에 모든 기능을 붙이려 하면 팀이 지칩니다. 첫 단계에서는 디자인 시안을 코드로 변환하는 기본 흐름을 익힙니다. 두 번째 단계에서 피그마 MCP를 연결하여 디자인 문맥(색상, 여백, 컴포넌트 계층) 을 AI에게 공급합니다. 세 번째 단계에서 Code Connect(피그마의 디자인 컴포넌트와 코드 저장소의

실제 컴포넌트를 연결하는 도구)를 설정하여, AI가 새 컴포넌트를 발명하는 대신 팀이 이미 쓰고 있는 컴포넌트를 가져다 쓰게 합니다. 질서 있게 올라가는 편이 결국 더 빠릅니다.

바 이런 문제가 생겼다면

(1) 피그마 MCP 서버를 연결했는데 generate_figma_design 도구가 보이지 않는 경우 이전에 연결했던 피그마 MCP 인스턴스가 남아 있으면 충돌이 생깁니다. 기존 연결을 해제하고 클로드 코드를 재시작한 뒤 다시 연결합니다. 피그마 플러그인을 통해 설치하는 방식이 안정적입니다.

claude plugin install figma@claude-plugins-official

(2) 피그마에서 코드로 변환한 결과가 원본과 많이 다른 경우 스크린샷만 보고 추정하는 것과 MCP를 통해 구조를 읽는 것은 결과가 다릅니다. MCP가 정상 연결되어 있는지 /mcp 명령어로 확인하고, 프롬프트에 "피그마 MCP에서 디자인 문맥을 가져와서 변환해줘"라고 명시합니다.

(3) 코드 투 캔버스(Code to Canvas) 기능이 작동하지 않는 경우 이 기능은 원격 MCP 서버(https://mcp.figma.com/mcp)를 통해서만 지원됩니다. 로컬 MCP 서버(데스크톱 앱의 Dev Mode MCP Server)만 연결한 상태라면 코드에서 피그마로 보내는 기능이 작동하지 않습니다. 원격 서버를 추가로 연결합니다.

이 장에서 다룬 네 가지 영역은 각각 독립된 기능이지만, 실제 프로젝트에서는 하나의 흐름으로 연결됩니다.

PRD로 요구사항을 정의하고, 에이전트 팀이 코드를 구현하며, 자동 테스트가 품질을 검증하고, 피그마 동기화가 디자인과 코드의 간격을 좁힙니다. AI가 코드를 짜는 속도는 사람보다 빠릅니다. 그러나 무엇을 만들어야 하는지 결정하고, 만들어진 결과가 사업의 맥락에 맞는지 판단하는 일은 화면 앞에 앉은 사람의 몫으로 남아 있습니다. 기계가 구축한 뼈대 위에 우리 조직만의 판단과 경험을 얹는 것. 그것이 이 도구들을 제대로 쓰는 방법입니다.