에이전틱 디자인 품질 제어

Codex나 Claude Code로 UI를 만들다 보면 특유의 “AI가 만든 것 같은 화면”이 반복됩니다.

에이전트가 디자인을 못해서가 아닙니다. 대부분의 프로젝트가 디자인 품질을 제어하는 surface를 충분히 주지 않아서입니다.

이 장에서는 DESIGN.md, AGENTS.md, CLAUDE.md, 예제 세트, 시각 평가 루프로 에이전트가 만드는 평균값 디자인에서 벗어나는 방법을 정리합니다.

에이전트가 자주 만드는 특유 디자인

Codex나 Claude Code만의 문제가 아닙니다. 시각 제약이 약한 agentic coding workflow 전체에 깔린 기본 편향에 가깝습니다.

왜 이런 편향이 생기는가

품질을 제어하는 5개의 surface

프롬프트 하나를 잘 쓰는 것으로는 부족합니다. 에이전트가 읽는 입력과 평가 루프를 구조적으로 설계해야 합니다.

1. DESIGN.md로 미학적 기본값을 덮어쓰기

DESIGN.md는 "이 화면이 어떤 성격이어야 하는가"를 에이전트에게 알려주는 상위 문서입니다. do/don't가 약하면 에이전트는 다시 평균적 SaaS 미학으로 돌아갑니다.

## Overview
신뢰감 있고 밀도 높은 운영 화면.
장식보다 정보 구조를 우선하며, 과한 gradient나 유리질 효과를 사용하지 않는다.

## Do's and Don'ts
- Do: border contrast와 typography hierarchy로 깊이를 만든다
- Do: 한 화면의 primary CTA는 하나로 제한한다
- Don't: glossy gradient, neon glow, glassmorphism 사용
- Don't: 카드마다 다른 radius와 shadow를 섞지 않는다
- Don't: marketing hero 같은 과도한 whitespace를 운영 화면에 적용하지 않는다

## Layout Principles
- 표, 리스트, 메트릭 카드의 정보 밀도를 유지한다
- 섹션 간 위계는 색보다 spacing과 type scale로 구분한다

좋은 DESIGN.md는 취향 선언문이 아니라 에이전트가 피해야 할 시각적 습관까지 적어둔 문서입니다.

2. AGENTS.md와 CLAUDE.md로 구현 행동을 제한하기

DESIGN.md가 look and feel을 정한다면 AGENTS.md와 CLAUDE.md는 실제 구현 행동을 제한합니다.

Codex용 AGENTS.md

Codex는 작업 전에 AGENTS.md를 읽으니, 디자인 품질 기준도 구현 규칙으로 올려두는 편이 효과적입니다.

## UI Quality Guardrails

- 기본 디자인 시스템 컴포넌트 외의 임의 스타일링을 우선하지 말 것
- gradient, blur, glow는 DESIGN.md에 명시된 경우에만 사용
- landing page 미학을 제품 화면에 가져오지 말 것
- 정보 위계는 color보다 spacing, type scale, grouping으로 먼저 해결
- 첫 구현 후 반드시 screenshot 기준 self-review를 수행

Claude Code용 CLAUDE.md

Claude Code는 CLAUDE.md, skills, optional output style을 함께 활용하는 편이 좋습니다.

## Design Review Loop

1. 먼저 현재 요청이 marketing page인지 product UI인지 분류한다
2. DESIGN.md와 component spec를 읽고 layout skeleton을 잡는다
3. 구현 후 screenshot 기준으로 아래 항목을 점검한다
   - primary CTA 개수
   - radius/shadow 일관성
   - 정보 밀도
   - token fidelity
4. 어긋난 항목만 좁게 수정한다

여기서 중요한 건 "예쁘게 만들어라"가 아니라 어떤 순서와 체크리스트로 구현할지 못 박는 것입니다.

3. 자유도를 줄이는 제약 레이어

미적 품질은 취향의 문제가 아닙니다. 대부분 선택 가능한 조합 수를 줄이는 문제입니다.

// Bad: 에이전트가 임의 스타일을 직접 조합
<div className="rounded-[28px] bg-gradient-to-br from-cyan-400 to-blue-600 shadow-2xl" />

// Better: 제한된 시스템 조합만 사용
<Card variant="metric">
  <MetricCard tone="default" />
</Card>

고품질 디자인은 자유로운 생성보다 잘 설계된 제약 안에서 생성할 때 나옵니다.

4. 예제와 반례 세트 만들기

에이전트는 좋은 예제만큼이나 나쁜 예제를 통해서도 빨리 교정됩니다.

design-control/
├── good/
│   ├── dashboard-density.md
│   └── table-layout.md
├── bad/
│   ├── over-glossy-marketing.md
│   └── card-soup.md
└── review-rubric.md

특히 bad/*가 효과가 큽니다. 모델은 “무엇을 하지 말아야 하는가”가 적혀 있을 때 훨씬 안정적으로 수렴합니다.

5. screenshot 기반 평가 루프

Codex 공식 use case도 front-end design에서 visual checks를 강조합니다. 코드가 아니라 화면을 기준으로 돌려야 품질이 올라갑니다.

최소 평가 rubric

agent critique 프롬프트 예시

[Task]
현재 구현된 화면을 DESIGN.md, component spec, screenshot 기준으로 리뷰해줘.

[Fail conditions]
- glossy gradient / glow / glass effect가 등장하면 실패
- primary CTA가 2개 이상이면 실패
- 정보 화면인데 marketing hero처럼 whitespace가 과하면 실패
- token spec 밖의 임의 radius/shadow/color가 있으면 실패

[Output]
1. rubric 점수표
2. 어긋난 항목 5개 이내
3. 각 항목별 targeted patch 제안
4. 전체 리라이트 금지

이 루프의 목적은 "다시 만들어"가 아니라 어디가 어긋났는지 좁게 짚어 패치하는 것입니다.

Codex와 Claude Code에 적용하는 방식

Codex에서 특히 잘 듣는 방식

• 작업 명세를 목표 / 제약 / 검증 / 금지선 구조로 준다
• AGENTS.md에 디자인 금지선을 올려 persistent contract로 만든다
• screenshot과 visual reference를 함께 주고, visual check를 검증 항목으로 넣는다
• design-review skill을 따로 만들어 반복 루프를 고정한다

Claude Code에서 특히 잘 듣는 방식

• CLAUDE.md에 design review sequence를 짧게 고정한다
• .claude/skills에 design-critique, design-polish, ui-regression-check 같은 스킬을 둔다
• 필요하면 custom output style로 “더 엄격한 디자인 리뷰어” 성격을 main loop에 부여한다
• /branch로 2~3개의 레이아웃 대안을 만든 뒤, 가장 좋은 방향만 이어간다

Claude Code의 output style을 디자인 리뷰에 쓰는 방법

Claude Code의 output style은 시스템 프롬프트를 직접 바꾸는 계층입니다. 기본 coding loop보다 엄격한 디자인 품질 검토를 걸고 싶을 때 유용합니다.

---
name: Design Critic
description: UI 구현 후 시각 품질과 시스템 일관성을 먼저 점검
keep-coding-instructions: true
---

Always review generated UI against DESIGN.md before finalizing.
Favor restrained hierarchy over decorative gradients.
Flag overuse of rounded corners, shadow stacks, and duplicate CTA emphasis.
When reviewing, prefer targeted patches over full rewrites.

이건 primary control surface가 아니라 보조 bias layer로 보는 게 맞습니다. 핵심은 여전히 DESIGN.md + component constraints + screenshot review입니다.

고품질 디자인을 뽑는 기본 루프

추천 운영 순서

1. 먼저 DESIGN.md와 구현 가드레일을 고정한다.
2. 첫 생성은 넓게 하되, 두 번째부터는 patch 범위를 좁힌다.
3. 매 반복마다 screenshot 기준으로 리뷰한다.
4. “전체 다시”보다 “이 3가지 mismatch만 수정”을 선호한다.

첫 시도에서 완벽한 디자인을 얻으려 하기보다 짧은 생성-평가-수정 루프를 팀의 기본 워크플로우로 만드는 것이 더 중요합니다.

흔한 안티패턴

리뷰 체크리스트

• 이 화면이 generic SaaS UI가 아니라 우리 제품답게 보이는가?
• DESIGN.md의 do/don't가 실제 구현에 반영됐는가?
• primary CTA, radius, shadow, spacing이 한 vocabulary로 정리되는가?
• 임의 색상/간격/장식 값이 시스템 바깥에서 새고 있지 않은가?
• 다음 반복에서 전체 리라이트가 아니라 targeted patch가 가능한가?

관련 장 연결

• 상위 시각 문서 자체는 DESIGN.md 인터페이스에서 다룹니다.
• 지속 규칙 주입은 컨텍스트 주입에서 이어집니다.
• 실제 도입 단계는 실행 플레이북과 함께 보면 좋습니다.

참고 자료

• Codex - Prompting guide
• Codex - AGENTS.md guide
• Codex - Skills
• Codex Use Cases
• Claude Code - Output styles