Claude Design 핸드오프 규칙

한국어 번역본

이 문서는 원문(영어)의 한국어 번역이다. 정본은 원문이며, 계약·게이트 판단이 갈리면 원문을 따른다. 원문: docs/process/claude-handoff-rules.md

Updated: 2026-07-23

이 문서는 Codex와 Claude Design 사이의 작업 흐름만을 서술한다.

기능 디자인 계약의 단일 진실 원천(source of truth)은 다음이다:

docs/process/claude-free-design-contract.md

전달 채널 원칙(무엇이 Codex 배선의 규범적 입력으로 인정되는지)은 다음이 관장한다:

docs/process/design-codex-transfer-contract.md

여기에 계약을 중복 기술하지 않는다. 훅, 상태, 슬롯, 필드, 액션 규칙이 바뀌면 docs/process/claude-free-design-contract.md만 갱신한다.

화면 흐름, 입력, 액션, 내비게이션, 상태에 대한 기능 요구사항 브리프는 보관 처리되었다 (역사적 참조 전용 — 살아 있는 원천은 src/react/contracts/designContract.ts와 docs/contracts/*-props.md다):

docs/archive/claude-functional-requirements.md

브랜치와 소유권 규칙은 다음에 있다:

docs/process/branch-workflow.md

Claude Design 작업은 통상 claude/ui에서 이루어져야 하며, 거기에 서술된 UI 소유권 경계 안에 머물러야 한다.

경계는 책임 기반이다. Claude는 시각 표면을 소유하고, Codex는 프로덕션 동작과 배선을 소유한다. 따라서 Codex는 승인된 디자인을 보존하는 한 src/react/ui/** 안에서 최소한의 바인딩 변경을 할 수 있다. 정본 R&R과 프리뷰 경계는 docs/process/claude-free-design-contract.md의 "R&R: Visual Design vs. Functional Integration" 절에 있다.

역할 분담

Claude Design이 전달한 표면이 시각 UI의 진실 원천이다. 기능적 상태 전이와 프로덕션 동작은 합의된 계약을 따른다. Codex는 이전 앱 구조에 맞추려고 표면을 다시 빚어서는 안 된다.

Codex가 소유하는 것:

백엔드 함수와 서비스 어댑터
Claude의 흐름을 뒷받침하는 데 필요한 앱 상태
데이터 계층
Supabase 저장
계산과 테스트
제어 입력, 검색/필터/IME, 내비게이션, 콜백, 비동기 동작, 그리고 Claude의 시각 디자인을 바꾸지 않는 모든 프로덕션 배선

Claude Design이 소유하는 것:

시각적 흐름과 화면 연출(choreography)
레이아웃
구성(composition)
타이포그래피
여백
컴포넌트 형태
모바일·데스크톱 UI 구조
CSS 클래스 이름과 시각 스타일링
디자인 표면의 프레임워크 선택. Claude가 React를 전달하면 앱 표면은 React를 써야 한다.

Codex → Claude

Codex가 Claude에게 보내야 하는 것:

대상 화면
필요한 제품 흐름과 액션 의미론
앱 상태
데이터 형태
동적 슬롯과 리스트
docs/process/claude-free-design-contract.md가 요구하는 계약 마커
docs/contracts/*-props.md 중 관련 화면 계약
긴 이름, 많은 세트, 빈 데이터, 큰 숫자 같은 스트레스 케이스
동작에 영향을 주는 경우에 한해 현재의 기능 제약

Codex가 처방해서는 안 되는 것:

시각적 연출이나 구성
정확한 여백
카드 형태
색 취향
타이포그래피 스케일
데스크톱/모바일 구성
선호 레이아웃을 암시하는 정적 픽스처 HTML/CSS
시각 기준선으로서의 현재 index.html이나 앱 CSS
사용자가 그 방향을 명시적으로 승인하지 않은 한, 필수 구조로서의 스크린샷이나 스켈레톤

구현 맥락을 위해 현재 HTML/CSS를 언급해야 한다면, 그것이 디자인 참조가 아니라 통합 대상일 뿐임을 명시한다.

Claude → Codex

Claude는 완전한 교체용 디자인 산출물을 보내야 한다:

화면 HTML, 컴포넌트 HTML, 또는 React 컴포넌트
화면 범위로 한정된 CSS
상태 노트
반응형 노트
보존된 계약 마커
프리뷰 상태 매트릭스와 시각 검증 노트

Claude의 프리뷰는 시각 상태와 의도 방출을 보여주기 위해 픽스처와 목 콜백을 포함할 수 있다. 그러나 그것이 프로덕션 검색, 저장, 인증, RPC, 정규화, 계산의 대체 구현이 되어서는 안 된다.

프리뷰와 픽스처는 Claude Design의 로컬 환경에만 존재한다. 이 레포지토리에 없고, 전달 범위 (src/react/ui/** + docs/contracts/**)의 일부가 결코 아니며, zip에 실수로 섞여 들어오면 쿠리어가 걷어낸다. 동작과 상태 선택 규칙은 오직 props 계약 문서를 통해서만 전달된다 (docs/process/design-codex-transfer-contract.md).

Claude는 이전 레이아웃 CSS가 살아 있어야만 성립하는 CSS 패치를 보내서는 안 된다. Claude는 현재 DOM 구조, 래퍼 위계, 표현용 클래스, 여백 체계를 무시해도 된다.

Codex 통합

Codex가 Claude의 디자인을 적용할 때:

화면 루트를 식별한다.
패치를 덧대는 대신 이전 화면 표면을 교체한다.
데이터/인증/저장에 필요한 기능 경계만 보존하거나 적응시킨다.
더 이상 적용되지 않는 이전 화면 전용 CSS를 제거한다.
사용자가 제품 방향을 명시적으로 바꾸지 않는 한 Claude의 시각 흐름과 구성을 그대로 유지한다.
Claude의 컴포넌트를 옛 아키텍처에 맞게 다시 쓰는 대신, Claude 앱 주변에 백엔드/서비스 함수를 덧붙인다.
제어 prop, 콜백, IME 이벤트, 의미론적 마커를 컨테이너만으로는 연결할 수 없을 때에 한해 UI 컴포넌트 내부에 필요한 최소한의 바인딩 변경을 가한다. 레이아웃과 스타일링은 그대로 보존한다.

컨테이너 병합 규칙

src/react/app.jsx는 React 앱 컨테이너이지 디자인 표면이 아니다. Claude Design은 통상적인 UI 작업에서 이 파일을 직접 편집하지 않아야 하지만, Claude의 UI 변경 때문에 Codex가 여기에 새 props, 콜백, 라우트 상태, 데이터 복원을 배선해야 하는 경우는 흔하다.

병합 중 app.jsx가 충돌하면:

기능 수정, 백엔드 배선, 인증, 저장, 테스트, 데이터 로딩에 대해서는 main을 진실 원천으로 삼는다.
최신 승인된 Claude UI 흐름과 필요한 컴포넌트 props/콜백에 대해서는 디자인 브랜치를 진실 원천으로 삼는다.
어느 한쪽을 통째로 고르지 않는다. 둘을 합성한다.
컨테이너 충돌을 해소하는 동안 src/react/ui/**의 시각 디자인을 변경하지 않는다. 정본 R&R 아래에서 최소한의 기능 바인딩은 허용된다. 시각적 충돌은 Claude Design의 몫으로 남긴다.

상세한 한국어 정책은 docs/process/branch-workflow.md의 "React Container Merge Policy" 절에 있다.

Claude Design 시작 프롬프트

다음은 바로 복사해 쓸 수 있는 작업 서두다. 그 뒤에 대상 화면, props 계약, 필요한 상태, 스트레스 케이스를 덧붙인다.

txt

먼저 docs/process/claude-free-design-contract.md의
“R&R: Visual Design vs. Functional Integration”과 대상 화면의
docs/contracts/*-props.md를 읽어줘.

너는 화면의 시각 디자인을 소유해. layout, markup composition, CSS,
typography, spacing, responsive structure, animation, 그리고 loading/empty/
error/pending/selected 상태가 어떻게 보이는지를 자유롭게 설계해줘.

실제 기능 배선은 Codex가 소유해. production search/filter/IME,
canonical ID, navigation, auth, persistence, RPC, data merge, domain 계산을
screen component나 preview에 구현하지 말고, agreed props와 callbacks로
값을 받고 user intent만 올려줘.

preview에서는 fixture와 mock callback으로 모든 시각 상태와 intent 발생을
시험해도 돼. 단, preview 전용 adapter는 fixture/preview 경로에 격리하고
production app에서 import되지 않게 해줘. preview 통과는 시각 상태와
contract 확인이고, 실제 기능 및 회귀 테스트는 Codex가 맡아.

전달물에는 component/CSS, preserved props·callbacks·markers, responsive
notes, preview state matrix, long/empty/loading/error stress 확인 결과를 포함해줘.

Claude Design 핸드오프 규칙 ​

역할 분담 ​

Codex → Claude ​

Claude → Codex ​

Codex 통합 ​

컨테이너 병합 규칙 ​