코딩 에이전트가 디자인 시스템을 지키게 만들기 — 프롬프트가 아니라 게이트로
에이전트가 하드코딩 색과 임의 간격을 만들어내는 원인을 진단하고, 디자인 토큰을 기계가 읽는 컨텍스트로 제공하고 린트와 시각 회귀를 CI 게이트로 거는 해법을 정리했습니다. 에이전트 시점의 디자인 시스템 가드레일 플레이북입니다.
코딩 에이전트가 디자인 시스템을 지키게 만들기 — 프롬프트가 아니라 게이트로
에이전트에게 “디자인 시스템 지켜서 만들어”라고 부탁한 경험은 대부분 비슷합니다. 첫 컴포넌트는 그럴듯하고, 세 번째 컴포넌트부터 color: #3b82f6와 margin: 13px가 섞여 나옵니다. 사람 신입도 겪는 문제지만 에이전트는 더 심합니다. 사람은 디자이너의 눈을 기억하지만, 에이전트는 컨텍스트에 없는 규칙은 존재하지 않는 규칙이기 때문입니다. 이 글은 디자인 시스템의 안전한 롤아웃 자체가 아니라(그건 별도 플레이북으로 정리했습니다), 에이전트가 규칙을 지키게 만드는 장치에 집중합니다.
문제 정의
에이전트 산출물에서 반복 등장하는 위반 패턴:
- 하드코딩 색: 토큰(
var(--color-primary)) 대신 헥스 코드 직접 기입 - 임의 간격: 4px 그리드가 아닌
13px,22px같은 눈대중 값 - 컴포넌트 재발명:
<Button>이 있는데<button>+ 인라인 스타일로 조합 - 일관성 없는 타이포: 토큰이 아닌 arbitrary font-size
이게 “모델이 나쁜” 문제가 아닌 이유는, 같은 에이전트도 규칙이 기계적으로 주어지면 잘 지킨다는 데 있습니다. 문제는 규칙의 전달 경로입니다.
원인 — 규칙이 에이전트의 세계에 없다
세 가지 원인으로 분해됩니다.
- 규칙이 사람용 문서에만 있다: Figma와 스토리북 설명은 사람이 읽는 산문입니다. 에이전트가 파일을 열지 않으면 규칙은 컨텍스트에 들어오지 않습니다.
- 규칙이 있어도 검증이 없다: 지키라고 말은 했지만 위반이 CI에서 터지지 않으면, 에이전트는 자기 출력이 규칙을 어겼는지 알 방법이 없습니다.
- 지키는 게 더 비싸다: 토큰 이름을 찾으려면 여러 파일을 뒤져야 하는데 그 비용이 크면, 에이전트는 그냥 값을 쓰는 지름길을 선택합니다.
즉 해법의 방향은 “더 강하게 부탁하기”가 아니라 규칙을 읽게 싸게 만들고, 어겼을 때 즉시 터뜨리는 것입니다.
해법 1 — 디자인 토큰을 기계가 읽는 컨텍스트로
첫 단계는 토큰을 디자인 토큰 포맷(W3C Design Tokens Community Group) 기반의 tokens.json으로 관리하는 것입니다. 이 포맷은 2025년 10월 최종 커뮤니티 그룹 보고서로 정리돼 있어, 도구 간 교환 포맷으로 쓸 수 있습니다.
{
"color": {
"primary": { "$type": "color", "$value": "#3b5bdb" },
"text": {
"default": { "$type": "color", "$value": "#1f2933" },
"muted": { "$type": "color", "$value": "#7b8794" }
}
},
"space": {
"1": { "$type": "dimension", "$value": "4px" },
"2": { "$type": "dimension", "$value": "8px" },
"3": { "$type": "dimension", "$value": "16px" }
}
}
여기서 포인트는 전체를 AGENTS.md에 넣지 않는 것입니다. 토큰 파일이 수백 줄이면 컨텍스트 예산만 잡아먹습니다. AGENTS.md에는 요약과 탐색 경로를 둡니다.
## 디자인 시스템
- 모든 색/간격/타이포는 디자인 토큰을 통해서만 쓴다. 하드코딩 금지.
- 토큰 정의: design/tokens.json ($type/$value 구조)
- 새 값이 필요하면 임의 값을 만들지 말고 토큰 추가를 제안한다.
- CSS 변수 매핑: src/styles/tokens.css
- 공통 컴포넌트: src/components/ui — Button, Stack, Text를 우선 사용한다.
이렇게 하면 에이전트는 “토큰이 어디 있는지”를 알게 되고(지키는 비용 하락), 규칙 요약은 항상 컨텍스트에 남습니다.
해법 2 — 린트를 CI 게이트로
컨텍스트 제공은 “지키고 싶게” 만들 뿐 “무조건 지키게” 만들진 못합니다. 강제는 린트가 합니다. Stylelint의 color-no-hex 규칙은 헥스 색을 금지하고, declaration-property-value-disallowed-list로 임의 수치를 갖는 속성값을 차단할 수 있습니다.
{
"rules": {
"color-no-hex": true,
"declaration-property-value-disallowed-list": {
"/^margin/": ["/^[0-9]+px$/"],
"/^padding/": ["/^[0-9]+px$/"],
"/^gap/": ["/^[0-9]+px$/"]
}
}
}
단, 이 설정은 var(--space-2) 등 토큰 사용은 허용하므로 “전면 금지”가 아니라 “토큰 강제”입니다. 이 게이트가 에이전트에게 잘 먹히는 이유는 피드백 루프의 속도입니다. 로컬에서 저장 즉시, CI에서는 PR 직후 터지고, 에러 메시지가 규칙 그 자체라서 에이전트가 다음 수정에서 스스로 교정합니다. 프롬프트로 10번 당부하는 것보다 린트 에러 한 번이 쌉니다.
컴포넌트 사용 규칙은 문서와 린트로 이중화합니다. “버튼은 <Button>을 쓴다”를 AGENTS.md에 쓰는 동시에, ESLint 규칙(예: no-restricted-syntax, no-restricted-imports)으로 원시 태그 사용 감지를 스크립트로 걸어두는 겁니다. 문서는 에이전트의 첫 선택을 바로잡고, 린트는 새어 나온 것을 잡습니다.
해법 3 — 시각 회귀로 잡히지 않는 위반까지
린트가 못 잡는 영역이 남습니다. 토큰을 “잘못” 쓴 경우 — 문맥에 맞지 않는 색, 잘못된 계층의 간격 — 는 문법적으로는 합법입니다. 여기서 시각 회귀가 필요합니다. Storybook의 시각 테스트 문서는 스토리 스냅샷을 기준선과 비교하는 흐름을 제공하고, Chromatic의 visual tests는 UI 변경을 PR 단위로 검수하는 운영층 도구입니다.
에이전트 워크플로에 붙이는 규칙:
- 에이전트가 컴포넌트를 고치면 해당 스토리의 스냅샷 diff가 PR에 자동 첨부된다.
- diff가 의도된 변경인지 예상치 못한 회귀인지 사람이 승인한다. “의도된 변경” 승인이 기준선을 갱신한다.
- 의도하지 않은 픽셀 변화는 에이전트에게 그대로 되돌려 재수정을 시킨다.
이 구조의 강점은 판정 기준이 사람의 눈에 남는다는 것입니다. 에이전트는 규칙의 글자를 지키고, 사람은 규칙의 정신을 승인합니다.
원칙 — 프롬프트가 아니라 게이트로
정리하면 에이전트의 디자인 시스템 준수는 세 겹의 게이트로 확보합니다.
1차 컨텍스트 게이트 tokens.json + AGENTS.md 요약 → 지키는 게 저렴해짐
2차 정적 게이트 Stylelint/ESLint in CI → 위반이 즉시 실패
3차 시각 게이트 스토리 스냅샷 diff + 사람 승인 → 의미 위반 검수
프롬프트(부탁)는 어디에도 없습니다. 부탁은 모델이 바뀌거나 컨텍스트가 흐려지면 소멸하지만, 게이트는 소멸하지 않기 때문입니다. 이건 PR 리뷰 에이전트를 통제했던 계약과 하네스 글의 가드레일과 같은 설계 철학입니다 — 에이전트를 믿는 대신 검증 가능한 지점을 늘리는 것.
체크리스트
- 디자인 토큰이 DTCG 포맷(json)으로 단일 진실 공급원에 있는가
- AGENTS.md에 토큰 전체가 아니라 요약과 탐색 경로가 있는가
- 색 헥스 금지 린트(color-no-hex)가 켜져 있는가
- 간격 속성의 임의 수치가 린트로 차단되는가
- 컴포넌트 사용 규칙이 문서와 린트로 이중화되어 있는가
- 린트가 CI에서 에러(경고 아님)로 실패하는가
- 컴포넌트 변경 시 시각 회귀 diff가 PR에 자동 첨부되는가
- 기준선 갱신이 사람 승인으로만 일어나는가
마치며
에이전트에게 디자인 시스템은 컨텍스트에 들어온 만큼만 존재합니다. 그러니 규칙을 읽기 쉬운 형태(tokens.json + 요약)로 주고, 어겼을 때 기계적으로 터뜨리는 게이트를 두 겹(린트, 시각 회귀)으로 깔면, “부탁해서 되는” 준수가 “구조적으로 되는” 준수로 바뀝니다. 디자인 시스템을 지키는 주체를 에이전트의 성실함에서 저장소의 구조로 옮기는 것 — 그것이 이 플레이북의 결론입니다.
레퍼런스
- Design Tokens Community Group — 디자인 토큰 포맷의 공식 사이트
- Design Tokens Format Module 2025.10 — W3C CG 보고서 — DTCG 토큰 포맷 최종 보고서 (2025-10-28)
- color-no-hex — Stylelint — 헥스 색 금지 규칙 문서
- declaration-property-value-disallowed-list — Stylelint — 속성값 차단 규칙 문서
- Visual tests — Storybook docs — 스토리 스냅샷 기반 시각 테스트 공식 문서
- Visual tests — Chromatic docs — PR 단위 UI 검수 도구 문서
- 디자인 시스템 안전 롤아웃 플레이북 — 본 블로그의 디자인 시스템 출시 관리 글 (2026-04-10)
- PR 리뷰 에이전트 가드레일 — 검증 지점을 늘리는 설계 철학 글 (2026-03-27)