Aider + Figma — 컨텍스트 번들로 UI 페어 코딩하기

Aider는 터미널 기반 AI 페어 프로그래머입니다. 지정한 파일을 읽고, unified diff 형태로 편집 내용을 생성하며, 이를 코드베이스에 직접 적용합니다. 모든 변경 사항은 적용 전에 검토할 수 있습니다. 이러한 diff 우선 워크플로는 토큰 인식 디자인 핸드오프와 잘 어울립니다 — 생성된 코드가 토큰 파일의 spacing.16을 사용하는지 아니면 하드코딩된 16px로 벗어났는지 정확히 확인할 수 있습니다.

이 가이드는 전체 Aider + figmascope 파이프라인을 다룹니다: 번들 생성, Aider 세션에 로드, 초기 스캐폴드를 위한 Architect 모드 사용, 그리고 목표 지향적인 편집 프롬프트로 반복 개선하기.

사전 준비

Aider가 설치되지 않았다면 설치하세요:

pip install aider-chat
# 또는
brew install aider

Aider는 여러 모델 백엔드를 지원합니다. 여기서는 Anthropic API를 통한 Claude Sonnet을 예시로 사용하지만, OpenAI나 로컬 모델을 사용해도 워크플로는 동일합니다.

export ANTHROPIC_API_KEY=sk-ant-...
# 또는 GPT-4o의 경우 OPENAI_API_KEY

1단계: 번들 생성

figmascope.dev로 이동하여 Figma 파일 URL을 붙여넣고 에이전트 컨텍스트 내보내기를 클릭하세요. 내보내기는 브라우저에서 실행됩니다 — Figma 개인 액세스 토큰은 localStorage에 저장되며 절대 외부로 전송되지 않습니다.

다운로드 파일은 context-bundle.zip으로 저장됩니다.

2단계: 프로젝트에 압축 해제

unzip ~/Downloads/context-bundle.zip -d ./design/

ls design/
# CONTEXT.md  _meta.json  components/  screens/  strings.json  tokens.json

3단계: 번들 파일을 포함하여 Aider 실행

필요한 번들 파일을 명령줄에 전달하세요. Aider는 이를 읽기 컨텍스트로 로드합니다 — 모델이 참조할 수 있지만 명시적으로 /add를 사용하여 편집 가능한 파일로 승격시키지 않는 한 편집하지 않습니다.

aider \
  --read design/CONTEXT.md \
  --read design/tokens.json \
  --read design/strings.json \
  design/screens/home.json \
  src/screens/HomeScreen.kt

패턴: 번들 파일에는 --read를 사용하여 컨텍스트 전용(편집 불가)으로 지정하고, Aider가 수정할 소스 파일은 위치 인자로 전달합니다. 이렇게 하면 번들이 깨끗하게 유지됩니다 — Aider의 diff 기계가 tokens.json을 편집하려 하지 않습니다.

기존 파일이 아닌 새 파일을 생성하길 원하면, 아직 존재하지 않는 대상 경로를 지정하면 됩니다. Aider가 파일을 생성해 줍니다.

4단계: 참조 PNG 추가

Aider는 멀티모달 모델에서 이미지를 컨텍스트로 포함할 수 있습니다. 실행 후 /add 명령을 사용하세요:

/add design/screens/home.png

PNG는 Figma의 2배 렌더링입니다. 멀티모달 모델(Claude Sonnet, GPT-4o)을 사용하면 Aider가 이를 시각적 참조로 포함합니다. 검토 중 정상 확인용으로 사용하되 — 정식 명세는 JSON이지 이미지가 아닙니다.

5단계: Architect 모드 — 초기 스캐폴드

Aider의 /architect 명령은 두 단계 모델을 사용합니다: 계획 수립 한 번, 구현 한 번. 전체 화면에서 일관된 구조를 먼저 잡고 싶을 때 적절한 시작점입니다.

/architect Implement design/screens/home.json as a Jetpack Compose screen.

Context:
- Read CONTEXT.md for framework constraints and target conventions.
- All spacing, color, and radius values come from tokens.json.
  Map token keys directly: spacing.16 → 16.dp, color.7f5cfe → Color(0xFF7F5CFE).
- Use string keys from strings.json via stringResource() with the fallback field as the literal fallback.
- IR node kinds: stack(vertical)→Column, stack(horizontal)→Row, overlay→Box,
  absolute→Box+Modifier.offset, leaf(text)→Text, leaf(rect)→Box+Modifier.background.
- Do not hardcode any value that has a token equivalent.

Output to: src/screens/HomeScreen.kt

Aider가 먼저 계획을 생성하여 보여주고, 그 다음 diff를 생성합니다. 계획을 검토하세요 — 노드 매핑이 잘못되어 보이면 구현 단계가 실행되기 전에 수정하세요.

6단계: 토큰 참조를 사용한 특정 파일 편집

스캐폴드가 완성되면, 목표 지향적인 /edit 프롬프트로 특정 문제를 수정하세요. 각 편집이 전체 재생성이 아닌 작고 검토 가능한 변경이기 때문에 Aider의 diff 워크플로가 빛을 발하는 순간입니다.

The card component in HomeScreen.kt uses hardcoded 12dp for corner radius.
Check tokens.json for the correct radius token and replace it.

Aider는 최소한의 diff를 생성합니다: 한두 줄만 변경되고 나머지는 건드리지 않습니다. 무엇이 바뀌었는지 정확히 확인할 수 있습니다.

전체 파일에 걸친 간격 감사의 경우:

Audit every .dp value in src/screens/HomeScreen.kt against the spacing tokens in design/tokens.json.
Produce a diff that replaces any hardcoded value with its token equivalent where one exists.
Leave a // TODO comment for any value that doesn't match a spacing token.

7단계: 명세에 대한 diff 검토

Aider의 diff 뷰가 검토 인터페이스입니다. 변경 사항을 수락하기 전에 다음을 확인하세요:

추가된 줄이 리터럴 값이 아닌 토큰 키를 참조하는가?
문자열 리터럴이 strings.json에 있는가, 아니면 하드코딩된 UI 문구인가?
생성된 코드의 노드 중첩이 IR JSON의 부모-자식 순서와 일치하는가?

diff가 잘못되어 보이면 프롬프트에서 n으로 거부하고 Aider에게 무엇을 수정해야 하는지 알려주세요. 짧은 피드백 루프 — 프롬프트, diff, 수락/거부, 개선 — 덕분에 큰 코드 블록이 들어온 후가 아니라 즉시 벗어남을 포착할 수 있습니다.

Aider의 diff 워크플로가 번들과 잘 어울리는 이유

토큰 드리프트가 diff에서 보입니다. 생성된 줄이 color = tokens.colorPrimary 대신 color = Color(0xFF7F5CFE)라면 병합 전에 확인할 수 있습니다. "나중에 확인하자"가 없습니다 — 검토가 인라인으로 이루어집니다.

반복 개선이 저렴합니다. 모든 변경에 전체 화면을 재생성하지 않습니다. 각 후속 프롬프트는 목표 지향적인 diff를 생성합니다. 번들이 안정적인 컨텍스트를 제공하고 Aider가 정밀한 편집을 제공합니다.

번들이 코드와 함께 버전 관리됩니다. 디자인이 업데이트되면 figmascope에서 번들을 재내보내기하고, 이전 버전과 diff를 비교한 다음 Aider에게 변경된 노드만 적용하도록 요청하세요. 전체 재구현 없이 여러 디자인 반복에 걸쳐 워크플로가 확장됩니다.

일반적인 패턴과 함정

한 번에 모든 화면을 추가하지 마세요. 화면 JSON을 한 번에 하나씩 전달하세요. 더 많은 컨텍스트가 항상 더 낫지는 않습니다 — Aider(및 기반 모델)는 파일의 모든 화면을 덤프하는 것보다 집중된 컨텍스트에서 더 잘 수행합니다.

번들에는 위치 인자가 아닌 --read를 사용하세요. tokens.json을 위치 인자로 전달하면 Aider가 편집하려 할 수 있습니다. --read를 사용하여 읽기 전용 컨텍스트로 표시하세요.

첫 번째 프롬프트 전에 _meta.json을 확인하세요. warnings 배열에는 내보내기가 완전히 해결하지 못한 채우기와 효과가 나열되어 있습니다. 에이전트에게 미리 알려 조용히 근사치를 계산하지 않게 하세요:

cat design/_meta.json | python3 -c "import sys,json; w=json.load(sys.stdin).get('warnings',[]); print('\n'.join(w))"

architect 프롬프트에 경고를 포함하세요: "히어로 배경 채우기 건너뛰기 — 그라데이션이 지원되지 않음. TODO 주석 남기기."

Aider는 정밀하고 검토 가능한 편집에 적합합니다 — 여러 파일에 걸친 전체 세션 컨텍스트가 필요할 때는 Cursor나 Claude Code를 사용하세요. 세 가지 워크플로 모두 동일한 방식으로 시작합니다: figmascope 메인 앱이 브라우저에서 내보내기를 처리합니다.