앱 빌드하기, 에이전트용

사람들이 쓰고 싶어 하는 Laze 앱을 에이전트가 만드는 방법: 디자인 규칙, 키트, 고정과 공유, 트렁크 푸시, 자체 작업 확인.

이 페이지는 Laze 앱을 만들거나 변경해 달라는 요청을 받은 AI 에이전트를 위한 문서입니다. 첫 laze app create 전에 읽으세요. 사람들은 처음 5초 안에 앱을 판단합니다. 완성된 것처럼 보이게 만들고, 요청받은 위치에 두고, 준비되었다고 말하기 전에 직접 확인하세요.

워크플로

요청받은 대화에서 만드세요:
```
laze app create "Insights" --channel <channel>
```
앱은 비어 있는 상태로 시작하며, 에이전트가 사용할 폴더가 있습니다. index.html부터 시작한 다음 laze app push로 처음부터 만드세요. --channel은 앱을 해당 대화의 탭으로 고정합니다. 그 안에 있는 모든 사람과 그들의 에이전트가 앱을 열고 이어서 만들 수 있습니다(빌더). 앱 이름은 슬러그가 아니라 사람들이 읽는 말로 지으세요.

페이지에서 플랫폼 키트와 클라이언트를 링크하세요:
```
<link rel="stylesheet" href="/_laze/theme.css" />
<link rel="stylesheet" href="/_laze/kit.css" />
<script src="/_laze/laze.js"></script>
```
슬라이드, 덱, 발표는 한 가지 예외입니다. 유일한 템플릿인 --template slides에서 시작합니다. 이 파일들이 앱의 첫 라이브 버전이며, 에이전트가 변경할 수 있습니다. 각 슬라이드는 slides/의 파일 하나이며, slides/deck.json에 순서대로 나열됩니다. 템플릿의 README.md에는 슬라이드를 추가하고, 순서를 바꾸고, 스타일을 지정하는 방법이 나와 있습니다. 덱에는 슬라이드 레일, 키보드 탐색, 전체 화면 Present, Export PDF 및 Export HTML 버튼이 있으므로 다시 만들지 마세요. MCP에서는 template: "slides"와 함께 create_app를 사용하면 같은 작업을 할 수 있고, write_app_files은 슬라이드를 한 번에 하나씩 변경합니다.

슬라이드 템플릿은 새 덱에만 사용합니다. 사람이 이미 페이지나 덱인 파일을 보낸 경우(HTML 내보내기, index.html이 포함된 zip, 정적 사이트) 그대로 올리세요. --template 없이 앱을 만들고, index.html을 맨 위에 두고 파일을 폴더에 압축 해제하고, CDN에서 불러오는 스크립트가 있으면 복사해 넣은 다음 푸시하세요. 첨부 파일과 함께 "여기로 옮겨줘" 또는 "여기에 넣어줘"라고 하면 정확히 그 뜻입니다. 그대로 하고, 무슨 뜻인지 묻지 마세요.
이미 있는 앱은 링크가 있는 메시지가 아니라, 고정된 탭으로 대화에 넣습니다:
```
laze app pin <app> --channel <channel>
```
--role editor은 멤버가 데이터를 변경할 수 있지만 코드는 변경할 수 없게 합니다. --view-only은 보기만 허용합니다. laze app pins <channel>은 탭 목록을 보여줍니다. 사람이 고정 해제한 앱은 다시 고정하지 마세요.
데이터 모양을 정하세요. laze.app.json에서 종류별로 컬렉션을 하나씩 만들고, 타입이 지정된 필드와 몇 개의 시드 레코드를 넣으세요. 데이터는 레코드에 있어야 하며, 페이지 코드에 있으면 안 됩니다. 숫자, 행 또는 텍스트를 하드코딩한 페이지는 잘못된 것입니다. 데이터가 바뀌면 푸시 없이 앱도 바뀌어야 합니다.
페이지를 변경한 다음, 라이브로 올리기 전에 로컬에서 확인하세요(직접 작업 확인하기 참고).
푸시하세요:
```
laze app push -m "Added the pipeline board" --seed
```
모든 푸시는 즉시 라이브 앱이 됩니다. 임시저장, 브랜치, pull request는 없습니다. 앱은 트렁크 기반입니다. 메시지는 사람들에게 무엇이 바뀌었는지 평범한 문장으로 쓰세요. --seed은 아직 레코드가 없는 컬렉션만 채웁니다.
뒤로 가기는 푸시가 잘못되었을 때 사용합니다. laze app versions을 실행한 다음 laze app revert <version> -m "<why>"을 실행하세요. 이것이 새 라이브 버전이 됩니다. 레코드는 손실되지 않습니다. 앱 안의 git 기록은 이 용도로만 사용합니다.

누가 열 수 있나요

공개 범위	열 수 있는 사람
제한됨	공유되었거나 고정된 사람, 에이전트, 대화, 그리고 워크스페이스 소유자와 관리자
채널	앱 채널의 멤버
내부	워크스페이스의 모든 사람
공개	주소를 가진 누구나

새 앱은 제한됨 상태입니다. 대화에 고정된 앱은 그곳의 모든 사람이 열 수 있으므로, 팀 앱에는 보통 고정만으로 충분합니다. 채널에서 요청받은 앱을 요청한 사람에게만 공유하지 마세요. 그 채널에 고정하세요. 요청받았을 때만 laze app access visibility internal|public로 범위를 넓히세요. 이 명령어는 관리자 승인이 필요한 경우를 알려줍니다. laze app members은 지금 누가 열 수 있는지 보여줍니다. 앱이 준비되었다고 말하기 전에 확인하세요.

디자인 규칙

레이아웃이 아니라 앱의 주제에서 시작하세요. 그 주제를 중요하게 생각하는 사람이 화이트보드에 어떻게 그릴지 생각하고, 그것을 만드세요. 위협 모델은 공격 맵이고, 로드맵은 타임라인이며, 예산은 돈의 흐름이고, 프로세스는 다이어그램입니다. 통계 타일과 글머리표 목록으로 된 페이지는 보고서처럼 보입니다. 피해야 할 앱입니다.

최대한 시각적으로 만드세요. 가능한 곳에는 모션 그래픽과 흐름도를 쓰고, 사람들이 완전히 이해할 때까지 한 단계씩 안내하세요. 글자로 빽빽한 화면은 절대 만들지 마세요. 글이 필요한 곳에는 쉽고 짧은 문장을 쓰세요. 앱은 사람이 이해하기 위한 것이지, 머릿속 내용을 쏟아내는 곳이 아닙니다.

Laze 키트는 플랫폼에서 제공됩니다(/_laze/theme.css, /_laze/kit.css, /_laze/laze.js). 채워 넣는 레이아웃이 아니라 도구 상자입니다. 필요한 토큰과 컨트롤을 가져오고, 그 위에 자체 파일의 CSS를 넣으세요. 키트를 앱에 복사하지 마세요.

시각적 요소를 먼저 두세요. 주제를 보여주는 그림이 앱 자체가 되게 하세요. 인라인 SVG, canvas, 지도, 타임라인, 다이어그램, 사람들이 클릭하고 탐색할 수 있는 것이어야 합니다. 키트의 토큰 위에서 자체 레이아웃과 모션으로 고유한 모습을 만드세요.
화면 하나에 작업 하나만 두세요. 첫 화면은 앱이 존재하는 질문에 답해야 합니다. 두 번째 작업은 첫 번째 아래가 아니라 탭(lz-tabs)에 두세요.
알맞은 형태를 쓰세요. 사람들이 행을 훑어보거나 옮길 때는 테이블(lz-table) 또는 보드(lz-board)를 쓰세요. 숫자 하나가 핵심이면 통계 타일(lz-stats, lz-stat-value)을 쓰세요. 시간에 따른 숫자는 차트(lz-chart)를 쓰고, 짧은 순서는 번호가 있는 단계(lz-steps)를 쓰세요. 세 줄보다 긴 텍스트는 앱이 아니라 문서에 있어야 합니다.
실제 데이터를 쓰세요. 사람들이 중요하게 여기는 레코드를 실제 이름과 날짜로 보여주세요. "Lorem", "Item 1" 또는 자리 표시자 차트는 쓰지 마세요. 페이지의 모든 주장은 레코드나 링크에서 나와야 합니다.
글자 크기 체계. 페이지 제목 하나(lz-title), 그 아래 한 줄(lz-lede), 섹션 제목(lz-h2 또는 lz-card-title), 본문 텍스트를 사용하세요. 다른 크기를 추가하지 마세요.
간격. 페이지(lz-page), 카드(lz-card lz-card-body), 그리드(lz-grid, lz-row) 클래스를 사용하세요. 이 클래스들은 12~20px 리듬을 유지합니다. 카드 안에 카드를 쌓지 마세요.
두 테마 모두 지원하세요. 색상은 토큰(var(--color-fg), var(--color-bg-surface), var(--color-primary), var(--color-border) 및 lz-badge-* 톤)에서만 가져오세요. hex 색상은 다크 모드를 깨뜨립니다.
좁은 너비를 고려하세요. 앱은 약 380px 너비의 사이드 패널에서 열립니다. 행이 쌓이도록 테이블 셀에 data-label을 주고, 헤더는 한 줄로 유지하세요.
빈 상태와 오류 상태를 만드세요. 빈 목록은 무엇이 나타날지와 첫 항목을 추가하는 방법을 알려줘야 합니다. 호출이 실패하면 빈 페이지가 아니라 Laze.fail(error)를 보여주세요.
상태는 배지로 표시하세요. 상태는 색이 있는 텍스트가 아니라 lz-badge와 톤(-success, -warning, -danger, -info, -primary)으로 보여주세요.
폼은 방해되지 않게 두세요. "새 항목"은 버튼 뒤에 두세요. 목록이 주 콘텐츠입니다.

키트 참조

필요	클래스
페이지와 헤더	`lz-page`, `lz-header`, `lz-title`, `lz-lede`
레이아웃	`lz-row`, `lz-grow`, `lz-grid`, `lz-stats`
카드	`lz-card`, `lz-card-body`, `lz-card-title`, `lz-h2`
테이블	`lz-table-wrap`, `lz-table`, `lz-num`(오른쪽 정렬 숫자)
보드	`lz-board`, `lz-column`, `lz-column-head`, `lz-tile`
숫자	`lz-stat-value`, `lz-chart`, `lz-chart-col`, `lz-chart-track`, `lz-chart-bar`, `lz-chart-value`, `lz-chart-label`
단계	단계마다 `li` 하나가 있는 `ol.lz-steps`
컨트롤	`lz-btn`, `lz-btn-primary`, `lz-btn-ghost`, `lz-input`, `lz-select`, `lz-textarea`, `lz-field`, `lz-form`, `lz-tabs`, `lz-tab`
상태	`lz-badge`(+ 톤), `lz-callout`, `lz-empty`, `lz-muted`

스크립트는 앱 자체 origin에서만 로드됩니다. CDN <script>은 거부되므로 필요한 라이브러리를 앱 폴더에 복사하세요. claude.ai artifact나 다른 React 페이지를 포팅할 때는 푸시하기 전에 JSX를 컴파일하고(예: npx esbuild app.jsx --bundle --minify --outfile=app.js), 빌드된 파일을 링크하세요. 브라우저 내 Babel도 작동하지만, 열 때마다 수 MB를 로드합니다.

페이지 스크립트에서 Laze.records("<collection>")은 레코드를 나열하고, 만들고, 업데이트하고, 제거합니다. Laze.subscribe은 변경 시 다시 로드하고, Laze.h은 요소를 만들고, Laze.mount은 그립니다.

키보드 단축키

앱이 처리하지 않는 한, Laze는 앱 안에서 누른 자체 단축키를 Laze로 전달합니다. 그래서 사람들은 먼저 앱 밖을 클릭하지 않아도 Cmd+K(Windows와 Linux에서는 Ctrl+K)를 눌러 앱을 벗어날 수 있습니다. 전달되는 단축키는 Cmd+K, Cmd+[ 및 Cmd+], Cmd+1부터 Cmd+9, Cmd+Shift+A, Cmd+Shift+T, Cmd+Shift+M, Cmd+Shift+D, Cmd+. 및 Cmd+/, 그리고 텍스트 필드 밖에서 Alt+Up 및 Alt+Down입니다. 다른 모든 키는 앱 안에 남습니다.

이 단축키 중 하나를 앱에서 사용하려면 키를 처리하고 event.preventDefault()를 호출하세요. 그러면 Laze가 건드리지 않습니다:

document.addEventListener("keydown", (event) => {
  if ((event.metaKey || event.ctrlKey) && event.key === "k") {
    event.preventDefault();
    openSearch();
  }
});

직접 작업 확인하기

푸시하기 전에 모든 변경 사항을 확인하세요:

laze app serve --port 4173

이 명령은 플랫폼 키트와 라이브 앱의 레코드를 사용해 폴더를 http://127.0.0.1:4173/에서 제공합니다. 읽기 전용입니다. 라이브 버전이 필요하므로 먼저 laze app push을 한 번 실행하세요. 브라우저 도구로 열고, 두 테마와 패널 너비에서 스크린샷을 찍으세요. 예를 들면 다음과 같습니다:

npx -y playwright install chromium   # once
npx -y playwright screenshot --viewport-size=1100,800 http://127.0.0.1:4173/ light.png
npx -y playwright screenshot --viewport-size=1100,800 "http://127.0.0.1:4173/?theme=dark" dark.png
npx -y playwright screenshot --viewport-size=390,800 http://127.0.0.1:4173/ narrow.png

각 이미지를 확인하세요. 넘치는 텍스트, 맞지 않는 열, 다크 모드에서 사라지는 색상, 아직 "demo"라고 표시되는 모든 것을 고치세요.

앱을 게시하기 전에 확인하세요:

요청받은 위치에 고정되어 있고, laze app members에 앱을 열 수 있어야 하는 사람들이 나열됩니다.
첫 화면이 스크롤 없이 요청에 답합니다.
라이트, 다크, 390px 스크린샷이 완성된 것처럼 보입니다.
메시지에 앱 이름과 앱이 하는 일을 한 줄로 적었습니다. 대화의 탭이 링크입니다.

확실하지 않을 때는 물어보세요

잘못된 것을 만들지 말고 사람에게 짧은 질문 하나를 하세요. 이미 요청한 단계에 대해 "진행해도 될까요"를 기다리지 마세요. 이 채널에서 앱을 요청했다면 그곳에 만들고, 고정하고, 알려주세요.

앱 빌드하기, 에이전트용

워크플로#

누가 열 수 있나요#

디자인 규칙#

키트 참조#

키보드 단축키#

직접 작업 확인하기#

확실하지 않을 때는 물어보세요#