디자이너가 코드 저장소에 접근하는 순간, 보통 두 가지 반응이 나옵니다. "생각보다 별거 없네"와 "이거 건드렸다가 서버 날리는 거 아니야?" 저도 처음 외주에서 GitHub 레포 접근권을 받았을 때 후자였습니다. 그런데 Cursor를 쓰기 시작하면서 그 경계가 조금씩 무너졌고, 지금은 디자인 토큰 동기화부터 Storybook 스토리 생성까지 디자이너 단독으로 처리하고 있습니다.
온보딩 장벽, 디자이너는 어디서 막히나
디자이너가 코드베이스에 합류할 때 가장 먼저 부딪히는 것이 권한 문제와 환경 설정입니다. 실제로 팀 단위 온보딩을 진행해 보면 처음 한 시간이 거의 퍼미션 이슈로 날아가는 경우가 많습니다. 대기업일수록 더합니다. 엔지니어링 리소스가 디자이너에게 미리 프로비저닝(provisioning)되지 않는 경우가 많기 때문인데, 여기서 프로비저닝이란 사용자가 필요한 시스템 자원과 접근 권한을 사전에 설정하는 과정을 말합니다.
그 다음 관문이 Docker입니다. 로컬 환경을 구동하려면 Docker가 설치되어 있어야 하는 경우가 많은데, Docker란 애플리케이션을 컨테이너(container)라는 독립된 실행 단위로 묶어 어떤 환경에서도 동일하게 실행할 수 있도록 해주는 도구입니다. Cursor가 자동으로 "Docker가 설치되지 않았습니다"라는 메시지를 띄우면 디자이너 입장에서는 그 시점에서 멈추게 됩니다. 제가 외주에서 경험한 것도 정확히 이 지점이었습니다. README 파일에 Docker 관련 예외 처리를 한 줄 추가하고 나서야 흐름이 끊기지 않았습니다.
환경 시크릿(environment secret) 문제도 있습니다. 환경 시크릿이란 API 키나 데이터베이스 접속 정보처럼 외부에 노출되면 안 되는 민감한 설정값을 말합니다. 디자이너에게는 프로덕션 환경이 아닌 스테이징 환경의 시크릿만 공유하는 것이 원칙인데, 이게 제대로 안 되어 있으면 로컬 앱이 아예 실행되지 않아 더 이상 진행이 불가능해집니다.
이런 이슈들을 사전에 정리해 두는 가장 효과적인 방법이 README 파일입니다. 레포지토리(repository) 루트에 있는 README는 마크다운 형식의 안내 문서로, 디자이너와 PM이 가장 먼저 열어봐야 하는 파일입니다. 제가 외주 프로젝트에서 팀에 공유한 온보딩 핵심 순서는 다음과 같습니다.
- npm install 실행으로 의존성 설치
- .env.example 파일을 복사해 .env 생성 후 스테이징 시크릿 입력
- Docker Desktop 설치 여부 확인 (필요 시 로컬 빌드 대안 안내)
- npm run dev 실행 후 localhost에서 앱 동작 확인
이 네 단계를 README에 명확히 써두는 것만으로도 온보딩 시간이 눈에 띄게 줄었습니다.
디자인 토큰 동기화, Cmd+K 하나로 끝낸 경험
디자인 토큰(design token)이란 색상, 타이포그래피, 간격처럼 디자인 시스템 전반에 걸쳐 반복 사용되는 값을 변수 형태로 정의한 것입니다. Figma에서 디자이너가 토큰 값을 바꾸면 개발 코드에도 자동 반영되어야 일관성이 유지되는데, 이 연결 고리가 수동 작업으로 남아 있으면 싱크가 깨지는 건 시간 문제입니다.
제가 직접 써봤는데, Cursor의 Cmd+K 기능이 이 구간에서 생각 이상으로 유용했습니다. Cmd+K는 Cursor에서 현재 파일이나 선택 영역에 자연어 명령을 내리는 인라인 편집 기능입니다. "Figma Tokens JSON을 받아서 Tailwind config에 머지해줘"라고 입력했더니 실제로 토큰 구조를 파악하고 tailwind.config.js에 값을 정리해주었습니다. 이 과정을 디자이너 혼자 완수했다는 점이 외주 클라이언트에게도 꽤 인상적으로 받아들여졌습니다.
라고 말하는 분들도 있는데, 물론 이게 처음부터 완벽하게 돌아가지는 않습니다. 토큰 구조가 복잡하거나 중첩이 깊으면 AI가 엉뚱한 값을 넣기도 합니다. 저는 그래서 토큰 동기화 후 반드시 스토리북(Storybook)에서 시각적으로 확인하는 단계를 추가했습니다. Storybook이란 UI 컴포넌트를 독립적으로 렌더링하고 문서화할 수 있는 개발 도구로, npm run storybook 명령 하나로 로컬에서 바로 확인할 수 있어 디자이너가 코드 전체를 건드리지 않고도 컴포넌트 단위 변화를 눈으로 검증할 수 있습니다.
실제로 스탠포드 HAI(Human-Centered AI Institute)의 2024년 보고서에 따르면 디자이너와 엔지니어 협업에서 반복 수정 사이클 단축이 AI 도구 도입의 핵심 가치로 꼽혔습니다(출처: Stanford HAI). 제 경험과도 정확히 맞아떨어지는 지점입니다.
agents.md와 Cursor Rules, 둘 중 뭘 써야 하나
이 주제는 실제로 써본 사람들 사이에서도 의견이 엇갈립니다. Cursor Rules를 선호하는 시각도 있고, agents.md를 밀어야 한다는 쪽도 있습니다.
agents.md란 AI 에이전트가 프로젝트를 이해하는 데 필요한 규칙과 컨텍스트를 담은 마크다운 파일로, Cursor뿐 아니라 Claude, Gemini 등 다양한 LLM(대형 언어 모델)이 읽을 수 있는 범용 형식입니다. Cursor Rules는 Cursor 전용 설정 파일로 glob 패턴을 통해 특정 파일 확장자에만 규칙을 적용할 수 있습니다. 예를 들어 *.stories.tsx 파일에만 Storybook 작성 규칙을 적용하는 방식이 가능합니다.
저는 처음에 Cursor Rules 쪽이 더 세밀하게 제어할 수 있어서 좋다고 생각했는데, 실제로 외주를 여러 건 진행하다 보니 agents.md의 범용성이 훨씬 실용적이라는 쪽으로 생각이 바뀌었습니다. 도구를 Windsurf나 다른 IDE로 전환해야 하는 상황이 생겼을 때 Cursor Rules는 무용지물이 됩니다. 반면 agents.md는 그대로 가져갈 수 있습니다. Windsurf에서도 동일한 개념의 설정 파일이 지원된다는 점에서 미래 호환성(future-proofing) 측면에서 agents.md가 유리합니다.
디자인 시스템 전용 agents.md를 작성할 때 저는 아래 내용을 반드시 포함합니다.
- UI 컴포넌트는 반드시 디자인 시스템 컴포넌트를 먼저 확인하고 사용할 것
- 디자인 토큰(색상, 간격, 타이포그래피) 값을 하드코딩하지 말 것
- Storybook 스토리 파일 작성 시 해당 폴더의 agents.md 규칙을 우선 적용할 것
- 마크다운 파일은 명시적으로 요청받지 않는 한 생성하지 말 것
마지막 항목은 솔직히 이건 예상 밖이었습니다. Cursor에서 Claude를 사용하다 보면 요청하지도 않은 마크다운 문서가 줄줄이 생성되는 경험을 합니다. 규칙으로 명시해두지 않으면 토큰이 낭비됩니다. LLM 토큰(token)이란 AI 모델이 텍스트를 처리하는 기본 단위로, 사용량에 따라 비용이 발생하기 때문에 불필요한 출력을 억제하는 규칙이 실제 비용과 직결됩니다.
IDE 없이도 가능한 코드 수정, 그리고 한계
코드베이스 접근 자체가 어려운 환경도 있습니다. 일부 회사는 PM에게 GitHub 라이선스를 부여하지 않거나, 디자이너가 로컬 환경 설정을 끝까지 완료하지 못하는 경우도 있습니다. 이런 상황을 위한 대안이 몇 가지 존재합니다.
OpenAI Codex는 브라우저에서 바로 코드 변경 사항을 만들고 풀 리퀘스트(Pull Request)까지 생성할 수 있는 도구입니다. 풀 리퀘스트란 변경된 코드를 메인 브랜치에 합치기 위해 검토를 요청하는 절차를 말합니다. 로컬 환경 없이 브라우저만으로 PR을 올릴 수 있다는 점이 PM이나 디자이너에게는 진입 장벽을 크게 낮춥니다. Cursor Background Agent와 Slack 연동도 비슷한 방향입니다. Slack 채널에 자연어로 요청을 보내면 에이전트가 코드 변경을 시도하는 방식인데, 이 역시 IDE 없이 아이디어를 테스트하는 데 유용합니다.
다만 여기서 한 가지 현실적인 이야기를 해야 합니다. 디자이너가 코드를 직접 수정하는 흐름이 아무리 매끄러워도, 이미 프로덕션에서 돌아가고 있는 레포지토리에 디자이너 단독으로 변경을 가하는 것은 여전히 주의가 필요합니다. 제 경험상 이건 좀 다릅니다. 스테이징 환경에서 충분히 검증하고, 엔지니어 리뷰를 거치는 프로세스가 있어야 진짜 안전한 워크플로우가 됩니다. 데이터가 하드코딩되어 있는지, 실제로 동적으로 연결되어 있는지 디자이너가 확인하기 어려운 부분도 있습니다. 이 구간은 여전히 엔지니어와 협력해야 하는 영역입니다.
Anthropic의 Claude 모델이 Cursor 내에서 코드베이스 요약 기능을 제공한다는 점도 온보딩에 활용할 수 있습니다. 처음 레포지토리를 열었을 때 "이 코드베이스의 구조를 설명해줘"라는 한 문장 프롬프트로 전체 폴더 구조와 주요 로직 흐름을 파악하는 것이 가능합니다(출처: Anthropic). 제가 외주에서 신규 프로젝트에 투입될 때마다 사용하는 방식이기도 합니다.
결국 Cursor가 디자이너와 PM에게 열어준 가능성은 "코드를 안다"가 아니라 "코드를 두려워하지 않는다"에 가깝습니다. 영문 프롬프트와 한국어 프롬프트의 인식 효율 차이, Windsurf Cascade Agent와의 비교, 디자인 시스템 자동화 실측 결과까지 정리된 한국어 가이드는 아직 시장에 많지 않습니다. 지금 이 워크플로우를 노션에 정리해 외주 3건에서 재사용하고 있는 저로서는, 이 흐름이 앞으로 디자이너 포지션의 실질적인 차별점이 될 것이라고 봅니다. 한 번 구축해두면 반복 사용이 가능하다는 점, 그게 핵심입니다.