태블로 데이터 앱(Tableau Data Apps)에서 design.md가 바꾸는 것과 바꾸지 못하는 것

What design.md Changes in Tableau Data Apps — 태블로 데이터 앱 design.md 비교 대표 이미지

태블로 데이터 앱(Tableau Data Apps)을 AI 에이전트로 만들면 동작하는 앱은 금방 나오지만, 화면은 어느 회사의 것인지 드러나지 않는 기본 모양이 되기 쉽습니다. 같은 요청으로 앱 두 개를 만들고, 한쪽에만 화면 규칙을 적은 design.md를 넣어 태블로 클라우드(Tableau Cloud)에 게시했습니다. design.md는 숫자 표기, 색, 서체, 제목 쓰는 방식, 첫 화면 구성을 바꿨습니다. 하지만 카드마다 어떤 기간을 보여 줄지 같은 화면 기획의 결정은 대신하지 못했습니다. 회사 공통 규칙은 design.md에, 화면마다 달라지는 결정은 spec.md에 나눠 적으면 에이전트에게 맡길 범위와 사람이 정할 범위가 분명해집니다.


1. design.md는 데이터 앱의 어디에 두나요?

태블로 MCP(Tableau MCP)의 scaffold-data-app 도구가 만드는 데이터 앱 템플릿에는 .twbx 안에 Resources/.agents/ 폴더가 있습니다. 템플릿의 README는 이 폴더를 앱을 만들거나 고치는 AI 에이전트와 사람이 읽는 문서 자리로 설명합니다. 또 태블로는 이 폴더를 무시하며 앱 실행에도 쓰지 않는다고 적고 있습니다. 브라우저로 전달되는 앱 파일은 Packages/<id>/content/에 따로 들어갑니다.

Superstore Sales B.twbx
├─ Superstore Sales B.twb
├─ Packages/<id>/content/   # 브라우저로 전달되는 앱 파일
└─ Resources/.agents/       # 에이전트가 읽는 문서(README.md, design.md)

태블로는 2026년 11월 10일 Tableau Builder & DataDev Live의 데이터 앱 발표에서도 이 리소스 폴더를 소개했습니다. spec.md, design.md, 작업 메모 같은 문서를 넣어 버전을 관리하고 공유하는 자리라는 설명입니다. 문서가 워크북과 함께 게시되고 다운로드되므로, 나중에 앱을 고치는 사람이나 에이전트도 같은 규칙에서 시작할 수 있습니다.

  • 읽게 하기: README에는 앱을 고치기 전에 이 폴더의 파일을 모두 읽으라고 적혀 있습니다. 그래도 작업을 맡길 때 Resources/.agents/의 문서를 먼저 읽으라고 직접 지시하는 편이 확실합니다.
  • 비밀 정보 제외: 워크북을 내려받을 수 있는 사람은 이 폴더도 읽을 수 있으므로 토큰, 비밀번호, 개인정보를 넣으면 안 됩니다. 태블로의 보안 문서도 패키지에 비밀 정보를 넣지 말라고 안내합니다.
  • 다시 패키징할 때: 이 폴더를 빼고 .twbx를 다시 만들면 문서도 함께 빠집니다.

2. 같은 요청에서 무엇이 달라졌나요?

두 앱은 요청과 데이터, 에이전트 조건을 같게 두고 파일 하나만 다르게 만들었습니다.

  • 요청: "Superstore 데이터로 영업 임원이 주간 회의에서 볼 영업 현황 대시보드를 만들어 줘."
  • 공통 조건: Claude Code 에이전트, 태블로 클라우드에 게시된 Superstore Datasource, 외부 출처 없이 queryAsync()로만 데이터를 조회하는 같은 템플릿
  • 공통 지시: 작업 전에 Resources/.agents/의 문서를 모두 읽고, 라이브러리와 서체는 패키지에 넣도록 했습니다. 두 에이전트 모두 보는 사람과 결정부터 생각하라는 같은 기본 지침도 받았습니다.
  • 차이: B의 Resources/.agents/에만 design.md를 넣었습니다. 내용은 Vizney Styles의 Anthropic 스타일 문서로, 공개된 디자인을 읽어 정리한 비공식 문서입니다. A는 작업 중 범용 차트 지침을 스스로 찾아 적용했습니다.
  • 게시: 2026년 11월 18일 두 앱을 태블로 클라우드에 게시하고 실제 데이터로 확인했습니다. 게시에 필요한 권한은 태블로 데이터 앱 게시에 필요한 권한과 관리자 승인 범위에서 다룹니다.

두 앱의 숫자는 같았습니다. 52주차 매출은 전년 같은 주보다 7.8% 줄었고, 연간 누적 매출과 이익은 각각 21.1%, 15.3% 늘었습니다. 연간 이익률은 12.8%로 전년보다 0.6%p 낮았습니다. 숫자는 데이터 원본 조회에서 나오므로, design.md가 바꾼 것은 같은 숫자를 보여 주는 방식입니다.

design.md 없이 만든 A의 첫 화면: 매출·이익·이익률·주문 수 타일 4개와 최근 13주 주간 추이 막대 차트
design.md 없이 만든 A
design.md를 넣은 B의 첫 화면: 52주차 매출과 연간 누적 매출을 말하는 헤드라인 문장, 증감 요인 문단, 핵심 숫자 4개
design.md를 넣은 B
  • 첫 화면: A는 매출, 이익, 이익률, 주문 수 타일 4개로 시작합니다. B는 "52주차 매출은 2.1만 달러로 전년 같은 주보다 7.8% 줄었지만, 연간 누적 매출은 전년보다 21.1% 많습니다."라는 문장과 증감 요인을 짚는 문단으로 시작하고, 핵심 숫자 4개를 오른쪽에 둡니다. design.md에 적힌 첫 화면 순서 그대로입니다.
  • 숫자 표기: A는 $21.4K처럼 K 단위와 ▲▼ 기호를 쓰고, B는 2.1만 달러처럼 만 단위와 부호(+, −)를 씁니다.
  • 색: A는 올해를 파란 막대, 전년을 검은 눈금으로 그립니다. B는 올해를 주황 실선, 전년을 회색 점선으로 그립니다.
  • 제목: A는 "주간 추이", "지역별 실적"처럼 무엇을 그렸는지 적습니다. B는 "중부의 연간 누적 매출만 전년보다 줄었습니다(−0.2%)"처럼 무엇을 발견했는지 적고, "그림 1", "표 1" 같은 번호와 주석도 붙였습니다.
  • 서체: A는 시스템 서체를 씁니다. B는 design.md가 정한 Noto Sans KR과 Noto Serif KR 파일을 라이선스 파일과 함께 패키지에 넣었습니다. design.md에는 웹 화면용 구글 폰트 주소가 적혀 있었지만, 외부 출처를 승인받지 않은 데이터 앱은 패키지 안의 파일만 불러옵니다.

A의 화면도 깔끔하고 숫자도 맞습니다. 차이는 회사가 정해 둔 표기와 관례를 따르느냐에 있고, 이 규칙은 데이터에 없으므로 문서로 알려 줘야 합니다.


3. design.md가 막지 못한 것은 무엇인가요?

B의 그림 1은 제목이 "최근 13주 가운데 8주의 매출이 전년 같은 주보다 많았습니다"입니다. 그런데 부제는 "주별 매출 · 2026년 1–52주차와 2025년 같은 주차"이고, 차트도 1년 전체를 그립니다. 제목이 말하는 13주가 차트에 표시되지 않아, 읽는 사람은 제목을 차트로 확인할 수 없습니다. 아래 화면은 게시한 그대로입니다.

B의 그림 1과 표 1: 그림 1의 제목은 최근 13주를 말하지만 부제와 선 차트는 2026년 1~52주 전체를 보여 준다
제목과 차트의 기간이 다른 B의 그림 1

design.md에는 카드 제목을 발견을 말하는 문장으로 쓰고, 부제에 측정값과 기간을 적으라는 규칙이 있습니다. B는 두 규칙을 모두 지켰습니다. 제목은 design.md의 예시(Orders grew on last year in 11 of 12 months)와 같은 형식이고, 부제는 차트의 기간을 정확히 적었습니다. 빠진 것은 이 카드가 최근 몇 주를 판정하는 카드인지, 한 해의 흐름을 보여 주는 카드인지에 대한 결정입니다. 이 결정은 스타일 규칙이 아니어서 design.md에도 요청에도 없었고, 에이전트가 빈칸을 채우는 과정에서 제목과 차트가 서로 다른 기간을 맡게 됐습니다.

같은 요청에서 A는 주간 추이 카드에 최근 13주만 그렸습니다. 카드의 기간을 정해 두지 않으면 에이전트가 정하게 되고, 그 선택은 같은 요청에서도 달라졌습니다. 이런 어긋남은 design.md에 규칙을 더 적기보다, 카드마다 답할 질문과 비교 기간을 먼저 정해서 막는 편이 좋습니다. 게시 전에는 제목이 말하는 기간과 차트가 그린 기간을 대조해 확인합니다.


4. design.md와 spec.md에는 무엇을 나눠 적나요?

같은 발표에서 발표자는 자신의 spec.md에 앱이 전할 핵심 메시지와 쿼리 로직을 적는다고 설명했습니다. 데이터 모델에 있는 계산식과 시맨틱을 새로 만들지 않고 재사용하라는 내용이 쿼리 로직의 예입니다. design.md에는 서체와 색, 전체 구조를 적으며, 정해진 형식은 아직 없다고 했습니다. 이번 비교에 비추면 회사 전체에 반복해 쓸 규칙은 design.md에, 화면마다 달라지는 결정은 spec.md에 두는 편이 좋습니다.

design.md에 적을 것은 다음과 같습니다.

  • 숫자 표기: 통화 단위와 축약 방식, 소수 자리, 증감 부호, %와 %p의 구분
  • 색: 올해, 전년, 목표, 강조에 쓰는 데이터 색을 브랜드 색과 따로 정하고, 좋고 나쁨에 색을 쓰는 기준
  • 제목과 주석: 제목을 라벨로 쓸지 발견 문장으로 쓸지, 그림·표 번호와 주석 형식
  • 화면 형식: 첫 화면의 배치 순서와 카드 안의 순서(제목 → 부제 → 차트 → 주석)
  • 서체와 라이브러리: 서체 이름과 함께 패키지에 넣을 파일과 라이선스, 외부 출처 없이 쓸 차트 라이브러리

spec.md에 적을 것은 다음과 같습니다.

  • 보는 사람과 결정: 누가 어떤 회의에서 무엇을 결정하는지
  • 판정 기준: 전년 같은 주, 목표, 직전 주 가운데 무엇과 비교해 좋고 나쁨을 판단하는지
  • 카드별 질문과 기간: 카드마다 답할 질문과 보여 줄 기간(예: 주간 추이는 최근 13주)
  • 첫 화면과 뺄 것: 스크롤 없이 보여야 할 지표와 넣지 않을 지표
  • 쿼리 로직과 검증: 데이터 원본의 계산식을 재사용할 것, 게시 전에 숫자와 제목의 기간을 원본 조회 결과와 대조할 것

design.md는 한 번 잘 써 두면 여러 앱에 반복해 쓸 수 있지만, spec.md는 앱마다 새로 써야 합니다. 화면 기획에서 정할 내용은 AI로 만든 대시보드가 그럴듯한데 실무에서 쓰이지 않는 이유에서 더 자세히 다룹니다. 에이전트에게 앱을 맡기기 전에 spec.md의 항목만큼은 사람이 먼저 정하는 편이 좋습니다.


B에 넣은 design.md는 Vizney Styles의 Anthropic 스타일 문서이며, 다른 기업 스타일 문서는 styles.vizney.com에서 볼 수 있습니다. 회사의 design.md와 화면별 spec.md를 함께 정리하려면 문의로 연락할 수 있습니다.

Note:

이번 포스트의 내용은 다음을 기반으로 작성되었습니다: 2026년 11월 18일 태블로 클라우드에서 진행한 테스트, 태블로 데이터 앱 공식 문서와 공식 블로그, 2026년 11월 10일 Tableau Builder & DataDev Live. 태블로 데이터 앱은 베타 단계이며, 공식 문서 기준으로 태블로 클라우드에서만 제공됩니다. 템플릿의 Resources/.agents/ 구성과 문서 관례는 이후 업데이트를 통해 변경될 수 있습니다.