DESIGN.md는 Atlassian의 표준이 아니라, AI에게 디자인 맥락을 건네는 관행입니다

AI에게 UI를 만들게 하면 결과가 그럴듯한 평균으로 수렴하기 쉽습니다. 버튼은 익숙한 파란색이고, 카드는 적당히 둥글고, 간격은 무난하지만 우리 제품의 이유는 없습니다. 모델이 디자인을 모르는 것이 아니라, 팀의 디자인 시스템과 결정의 맥락을 읽지 못했기 때문입니다.

이 문제를 해결하는 방법으로 DESIGN.md라는 이름이 자주 등장합니다. 다만 먼저 사실관계를 바로잡아야 합니다. DESIGN.md는 Atlassian이 공인한 표준 파일 형식으로 확인된 이름이라기보다, 프로젝트의 디자인 지침을 마크다운으로 정리해 AI 에이전트가 참조하게 하는 관행에 가깝습니다. Atlassian Design System은 훌륭한 참고 사례지만, Atlassian이 DESIGN.md 자체를 공식 표준화했다는 뜻은 아닙니다.

파일 하나가 디자인 시스템을 만들지는 않습니다

DESIGN.md에 들어갈 수 있는 정보는 간단합니다. 제품의 원칙, 색상과 타이포그래피 토큰, 컴포넌트 경로, 간격 규칙, 접근성 기준, 금지 사례, 예외와 검토 방법입니다.

중요한 것은 파일의 이름보다 연결입니다. “기존 Button을 사용하라”는 문장이 실제 코드의 컴포넌트 경로와 연결되지 않으면 에이전트는 비슷한 버튼을 새로 만들 수 있습니다. “8px 그리드를 사용하라”는 문장도 토큰 이름과 적용 범위가 없으면 장식적인 조언에 머뭅니다.

좋은 컨텍스트는 다음 네 가지를 함께 가집니다. 규칙, 적용 예시, 예외, 현재 상태입니다. 무엇을 해야 하는지뿐 아니라 언제 하지 말아야 하는지와 이 규칙이 아직 유효한지도 적어야 합니다.

MCP와 파일은 경쟁재가 아닙니다

디자인 시스템을 MCP나 도구로 직접 연결하면 에이전트가 실제 컴포넌트와 토큰을 조회할 수 있습니다. 반면 파일은 도구에 덜 종속된 설명과 원칙을 전달하는 데 유리합니다. 하나는 살아 있는 시스템에 가깝고, 다른 하나는 사람이 편집할 수 있는 계약에 가깝습니다.

파일을 매번 전체 주입하면 입력 컨텍스트는 커집니다. 그렇다고 토큰이 92% 줄거나 결과 편차가 2.7배 감소한다고 일반화할 수는 없습니다. 그런 수치는 동일한 모델·프롬프트·평가 기준으로 측정한 실험이 있어야 말할 수 있습니다. 실제 비용은 파일의 길이, 재작업 횟수, 컴포넌트 문서 품질에 따라 달라집니다.

우리 팀에 적용한다면

처음부터 모든 디자인 원칙을 옮기기보다 반복적으로 실패하는 한 가지 영역을 골라야 합니다. 예를 들어 버튼과 폼부터 시작해 실제 컴포넌트 경로, 상태, 금지 사례, 접근성 라벨, 사용 예시를 적습니다. 에이전트가 만든 결과에서 기존 컴포넌트 재사용률과 접근성 오류를 확인하고 문서를 고칩니다.

이 과정은 문서 작성이 아니라 테스트에 가깝습니다. AI가 자꾸 잘못 읽는 규칙은 애초에 사람이 읽기에도 모호할 가능성이 큽니다. 반대로 팀이 말로만 공유하던 판단을 파일에 적는 순간, 그 판단의 소유자와 폐기 조건도 드러납니다.

좋은 점

디자인 시스템을 사람이 기억하는 암묵지에서 에이전트가 참조할 수 있는 명시적 지식으로 옮깁니다. 도구가 바뀌어도 원칙과 토큰의 설명을 가져갈 수 있다는 점도 장점입니다.

한계

파일만으로는 최신 코드와 디자인의 불일치를 해결할 수 없습니다. 문서가 오래되면 AI는 낡은 기준을 더 빠르게 반복합니다. 또한 모든 시각적 판단과 맥락을 텍스트로 표현하면 중요한 뉘앙스가 사라질 수 있습니다.

남는 긴장

이식성을 높일수록 실제 컴포넌트와의 연결은 약해지고, 시스템과 밀접하게 연결할수록 특정 도구에 종속됩니다. 어떤 팀에는 파일이 충분하고, 어떤 팀에는 MCP와 코드 검사가 더 중요합니다. 정답은 파일명보다 실패 비용에 달려 있습니다.

질문

• 에이전트가 반드시 재사용해야 하는 컴포넌트는 무엇인가요?
• 규칙마다 적용 범위·예외·최종 검토일이 있나요?
• 문서와 코드가 달라졌을 때 어느 쪽을 기준으로 삼나요?
• AI 결과의 일관성을 어떤 지표로 측정할 건가요?

DESIGN.md의 핵심은 새로운 표준 파일을 만드는 데 있지 않습니다. 팀의 디자인 판단을 기계가 읽을 수 있을 만큼 구체적으로 만들고, 그 판단이 여전히 유효한지 계속 검증하는 데 있습니다.