Claude Code와 Codex가 함께 쓰는 디자인 시스템 만들기
두 코딩 도구가 공통 디자인 기준을 참고하도록 파일과 작업 순서를 구성해요.
같은 저장소에서 Claude Code와 Codex를 번갈아 쓰다 보면, 한쪽에는 디자인 규칙을 알려 줬는데 다른 쪽 결과는 기본값으로 돌아가는 일이 생깁니다. 이를 줄이려면 도구별 작업 지침과 제품의 시각 규칙을 구분하고, 두 에이전트가 같은 원본 디자인 기준을 참조하도록 구성하면 됩니다.
핵심은 파일 이름을 하나로 통일하는 것이 아니라, 각 파일이 맡을 역할을 분명히 하는 것입니다.
디자인 원칙과 에이전트 지침
DESIGN.md에는 제품의 시각적 정체성과 UI 규칙을 둡니다. 색상 토큰, 타이포그래피, 간격, 모서리, 핵심 컴포넌트의 상태와 사용 원칙을 기록해요. 반면 CLAUDE.md와 AGENTS.md에는 에이전트가 작업을 수행하는 방식을 적습니다. 예를 들어 프로젝트 구조를 먼저 살펴볼 것, 기존 컴포넌트를 우선 사용할 것, 디자인 규칙과 코드가 충돌하면 무엇을 보고할지 같은 내용입니다.
이렇게 나누면 제품의 브랜드 기준을 바꿀 때 한 곳을 고치고, 도구별 명령이나 검증 절차는 각 지침 파일에서 조정할 수 있습니다. 디자인 파일은 결과물의 기준이고, 도구 지침 파일은 그 기준을 어떻게 찾아 적용할지 설명하는 안내판에 가깝습니다.
CLAUDE.md와 AGENTS.md 구성
Claude Code는 기본 설정에서 CLAUDE.md 계열 파일이 작업 디렉터리나 상위 경로에 있으면 AGENTS.md는 읽지 않고 CLAUDE.md만 읽습니다. 그런 파일이 없을 때는 지원되는 버전(v2.1.277 이상)에서 작업 디렉터리와 상위 디렉터리의 AGENTS.md, .claude/AGENTS.md를 읽습니다. 설정에서 claude-md-and-agents-md를 선택하면 두 종류를 함께 읽게 할 수 있고, CLAUDE.md 안에 @AGENTS.md를 가져오도록 적어 공용 규칙을 공유할 수도 있습니다. Codex는 AGENTS.md를 저장소 지침으로 인식합니다. 따라서 두 도구가 같은 디자인 문서를 참고하게 하되 Claude Code의 기본 로딩 조건을 고려해 구성해야 합니다.
저장소 루트는 다음처럼 시작할 수 있어요.
project/
├── DESIGN.md
├── AGENTS.md
├── CLAUDE.md
├── src/
└── docs/
AGENTS.md와 CLAUDE.md에 같은 긴 규칙을 복사해 넣기보다, 각 파일은 짧은 공통 안내와 해당 도구에서만 필요한 지침을 담고 DESIGN.md를 가리키게 합니다. 두 파일을 더 간결하게 유지할 수 있고, 디자인 내용이 서로 달라지는 복사 오류도 피할 수 있어요.
예를 들어 AGENTS.md는 이렇게 쓸 수 있습니다.
## Project instructions
- Before changing UI, read the root DESIGN.md and relevant component docs.
- Reuse existing tokens and components before adding new values.
- If a request conflicts with the design rules, explain the conflict and use the narrowest change.
- For visual changes, report the pages and states that need review.
CLAUDE.md에는 같은 디자인 참조를 두고 Claude Code에 특화된 규칙만 추가합니다. 조직에서 AGENTS.md 하나로 공유하고 싶다면 Claude Code에서 기본 동작을 유지한다면 CLAUDE.md 안에 @AGENTS.md를 추가하는 방법이 있습니다. 또는 /config에서 claude-md-and-agents-md를 선택하면 두 파일이 함께 로드됩니다. 직접 AGENTS.md를 읽는 기능은 v2.1.277 이상이 필요하며, 일부 세션이나 설정에서는 사용할 수 없으므로 /memory 또는 /context all에서 실제 로드 상태를 확인하세요.
프로젝트 지침 작성 기준
항상 반복하는 원칙은 루트 지침에 둡니다. 예를 들면 ‘새 버튼을 만들기 전에 기존 Button 컴포넌트의 변형을 확인한다’는 규칙은 대부분의 UI 작업에 적용됩니다. 반면 특정 디렉터리의 접근성 검사나 별도 테스트 절차는 해당 작업에서만 필요할 수 있어요. Claude Code는 경로별 규칙을 .claude/rules/에 분리할 수 있고, Codex는 하위 디렉터리의 AGENTS.md로 영역별 지침을 둘 수 있습니다.
범위가 넓은 규칙은 사소한 변경까지 불필요하게 무겁게 만들 수 있습니다. ‘모든 작업 전에 모든 문서를 읽는다’보다 ‘레이아웃을 바꾸면 DESIGN.md를 확인하고, API를 변경하면 API 문서를 확인한다’처럼 적용 조건을 적어 주세요. OpenAI의 Codex 지침 자료도 지침은 구체적이고 관련 있는 맥락을 가리키도록 유지하라고 권합니다.
DESIGN.md의 디자인 규칙
도구 지침에서 디자인 문서를 읽으라고 했더라도, 디자인 문서가 추상적인 형용사로만 채워져 있으면 결과는 여전히 달라집니다. ‘친근하고 미니멀하게’ 대신 실제 선택을 안내하는 규칙을 적으세요.
---
name: Northstar Console
colors:
primary: "#2457D6"
canvas: "#F4F6FA"
ink: "#172033"
border: "#D8DEE9"
rounded:
control: 8px
spacing:
sm: 8px
md: 16px
lg: 24px
components:
button-primary:
backgroundColor: "{colors.primary}"
textColor: "#FFFFFF"
rounded: "{rounded.control}"
padding: 10px
---
## Overview
운영자가 주문 상태를 빠르게 살피는 관리 콘솔입니다.
강한 색은 주요 행동과 선택 상태에만 사용합니다.
카드 그림자는 기본으로 쓰지 않고, 선택된 항목은 테두리로 구분합니다.
예를 들어 Codex에 ‘주문 목록의 빈 상태를 구현해 줘’라고 요청했을 때, DESIGN.md가 비어 있음·오류·선택 상태를 구분하는 색과 문구 원칙을 제공하면 결과를 리뷰하기 쉬워집니다. Claude Code가 같은 작업을 하더라도 동일한 색상 역할과 여백 규칙을 참고할 수 있어요.
AI 생성 결과 검증
Claude Code 공식 문서는 CLAUDE.md와 AGENTS.md를 강제 설정이 아니라 대화 맥락으로 설명합니다. 지침을 읽더라도 모든 규칙이 항상 지켜지는 것은 아니며, 더 구체적이고 간결한 지침이 더 안정적으로 적용됩니다. 반드시 차단해야 하는 작업은 지침 문장만으로 보장할 수 없고, 도구의 권한 설정이나 훅처럼 강제력이 있는 기능을 검토해야 합니다.
DESIGN.md도 모든 에이전트가 자동으로 읽는 표준 지침 파일은 아닙니다. 프로젝트에서 두 코딩 도구가 그 형식을 지원하는지, 실제로 문서를 컨텍스트로 받는지 확인하세요. 필요하면 CLAUDE.md와 AGENTS.md에 참조를 분명히 적고, 작업 프롬프트에도 대상 파일을 명시합니다.
화면과 컴포넌트 상태 점검
처음부터 앱 전체를 디자인 규칙에 맞춰 바꾸지 말고, 작은 화면 하나로 두 도구를 비교합니다. 예를 들어 ‘주문 상세 화면의 기본·오류·비활성 버튼을 구현하고, 기존 컴포넌트를 먼저 확인하라’고 각각 요청해 보세요. 색상과 간격만 보지 말고 키보드 포커스, 비활성 상태, 긴 문구, 좁은 화면에서의 배치까지 살핍니다.
두 결과에서 반복적으로 어긋나는 지점을 찾으면 어느 파일을 고칠지 결정할 수 있어요. 두 에이전트가 같은 버튼 규칙을 놓친다면 DESIGN.md를 보완하고, 한 도구만 지침 문서를 못 찾았다면 해당 도구의 설정이나 프로젝트 안내를 수정합니다. 이 구분이 유지보수 비용을 줄여 줍니다.
디자인 시스템 변경 관리
디자인 기준을 코드와 별도 문서에 둘 때 가장 흔한 문제는 시간이 지나면서 내용이 낡는 것입니다. 실제 CSS 토큰과 컴포넌트 구현이 바뀌면 DESIGN.md도 함께 갱신하고, 변경 사항을 작업 리뷰에서 확인하세요. 규칙이 많아질수록 자주 쓰이는 것과 특정 영역에서만 쓰이는 것을 분리합니다.
두 에이전트가 같은 디자인 시스템을 쓴다는 것은 결과물이 완전히 똑같다는 뜻이 아닙니다. 공통 원칙을 같은 문서에서 시작하고, 그 원칙을 읽고 적용하는 절차를 각 도구의 공식 지침 파일에 연결한다는 뜻이에요. 파일을 읽었는지, 화면에서 어떤 상태를 확인했는지까지 작업 결과에 포함하면 ‘설명해 둔 규칙’이 실제 제품으로 이어지는지 점검할 수 있습니다.