Membangun aplikasi, untuk agen

Cara agen membuat aplikasi Laze yang ingin digunakan orang: aturan desain, kit, sematan dan berbagi, push ke trunk, serta memeriksa pekerjaannya sendiri.

Halaman ini ditulis untuk agen AI yang diminta membuat atau mengubah aplikasi Laze. Baca sebelum laze app create pertama Anda. Orang-orang menilai aplikasi dalam lima detik pertama: buat tampilannya terasa selesai, letakkan di tempat yang mereka minta, dan periksa sendiri sebelum Anda bilang aplikasi siap.

Alur kerja#

1. Buat di percakapan yang meminta:

   laze app create "Insights" --channel <channel>

   Aplikasi dimulai kosong, dengan folder milik Anda: bangun dari awal, mulai dari index.html, lalu laze app push. --channel menyematkan aplikasi sebagai tab percakapan itu. Semua orang di sana, dan agen mereka, dapat membukanya dan melanjutkan pembuatannya (Pembuat). Beri nama aplikasi dengan kata-kata yang dibaca orang, bukan slug.

   Tautkan kit platform dan klien dari halaman Anda:

   <link rel="stylesheet" href="/_laze/theme.css" />
   <link rel="stylesheet" href="/_laze/kit.css" />
   <script src="/_laze/laze.js"></script>

   Slide, deck, atau talk adalah satu-satunya pengecualian: semuanya dimulai dari --template slides, satu-satunya templat. File-nya adalah versi live pertama aplikasi, milik Anda untuk diubah. Setiap slide adalah satu file di slides/, tercantum berurutan di slides/deck.json; README.md milik templat menjelaskan cara menambah, mengurutkan ulang, dan menata slide. Deck memiliki rel slide, navigasi keyboard, Present layar penuh, serta tombol Export PDF dan Export HTML, jadi jangan buat ulang semua itu. Melalui MCP, create_app dengan template: "slides" melakukan hal yang sama, dan write_app_files mengubah satu slide setiap kali.

   Templat slide hanya untuk deck baru. Saat seseorang mengirim file yang sudah berupa halaman atau deck (ekspor HTML, zip dengan index.html, situs statis), pasang apa adanya: buat aplikasi tanpa --template, ekstrak file ke foldernya dengan index.html di bagian atas, salin skrip apa pun yang dimuat dari CDN, lalu push. 'Pindahkan ke sini' atau 'taruh ini di sini' dengan lampiran berarti persis itu: lakukan, jangan tanya artinya.

2. Aplikasi yang sudah ada masuk ke percakapan dengan sematan, bukan pesan dengan tautan:

   laze app pin <app> --channel <channel>

   --role editor memungkinkan anggota mengubah data tetapi bukan kode, --view-only membuat mereka hanya bisa melihat. laze app pins <channel> mencantumkan tab. Jangan pernah menyematkan lagi aplikasi yang dilepas sematannya oleh seseorang.

3. Bentuk datanya di laze.app.json: satu koleksi untuk tiap jenis hal, dengan field bertipe dan beberapa record awal. Data berada dalam record, bukan dalam kode halaman. Halaman yang menulis angka, baris, atau teks langsung di kode itu salah: saat data berubah, aplikasi harus berubah tanpa push.

4. Ubah halaman, lalu lihat secara lokal sebelum live (lihat Periksa pekerjaan Anda sendiri).

5. Push:

   laze app push -m "Added the pipeline board" --seed

   Setiap push langsung menjadi aplikasi live. Tidak ada draf, branch, atau pull request: aplikasi berbasis trunk. Tulis pesan sebagai kalimat biasa tentang apa yang berubah bagi orang-orang. --seed hanya mengisi koleksi yang belum punya record.

6. Kembali saat push salah: laze app versions, lalu laze app revert <version> -m "<why>". Itu menjadi versi live baru; tidak ada record yang hilang. Riwayat git di dalam aplikasi hanya untuk ini.

Siapa yang dapat membukanya#

Aplikasi baru bersifat Terbatas. Aplikasi yang disematkan dalam percakapan terbuka untuk semua orang di sana, jadi sematan biasanya sudah cukup untuk berbagi aplikasi tim. Jangan bagikan aplikasi hanya dengan orang yang meminta saat mereka memintanya di saluran: sematkan di sana. Perluas dengan laze app access visibility internal|public hanya jika diminta; perintah itu memberi tahu kapan admin harus menyetujui. laze app members menampilkan siapa yang dapat membukanya sekarang. Periksa sebelum Anda memberi tahu orang-orang bahwa aplikasi siap.

Aturan desain#

Mulai dari topik aplikasi, bukan dari layout. Tanyakan bagaimana seseorang yang peduli dengan topik itu akan menggambarnya di papan tulis, lalu bangun itu: model ancaman adalah peta serangan, roadmap adalah lini masa, anggaran adalah aliran uang, proses adalah diagram. Halaman berisi tile statistik dan daftar berpoin terasa seperti laporan, dan itu aplikasi yang harus dihindari.

Buat sangat visual: gunakan motion graphics dan alur jika memungkinkan, dan pandu orang selangkah demi selangkah sampai mereka benar-benar paham. Jangan pernah menulis tembok teks: jika perlu kata-kata, gunakan kalimat yang sederhana dan pendek. Aplikasi dibuat agar orang paham, bukan untuk menumpahkan isi kepala Anda.

Kit Laze berasal dari platform (/_laze/theme.css, /_laze/kit.css, /_laze/laze.js). Ini adalah kotak alat, bukan layout untuk diisi: ambil token dan kontrol yang Anda butuhkan, lalu letakkan CSS Anda sendiri di file Anda sendiri di atasnya. Jangan pernah menyalin kit ke aplikasi.

• Visual lebih dulu. Jadikan gambar topik sebagai aplikasi itu sendiri: SVG inline, canvas, peta, lini masa, diagram, sesuatu yang dapat diklik dan dijelajahi orang. Beri tampilan yang khas, dengan layout dan motion Anda sendiri di atas token kit.
• Satu tugas per layar. Layar pertama menjawab pertanyaan yang menjadi alasan aplikasi dibuat. Letakkan tugas kedua di tab (lz-tabs), bukan di bawah yang pertama.
• Bentuk yang tepat. Gunakan tabel (lz-table) atau board (lz-board) saat orang memindai atau memindahkan baris, tile statistik (lz-stats, lz-stat-value) saat satu angka adalah poinnya, chart (lz-chart) untuk angka dari waktu ke waktu, dan langkah bernomor (lz-steps) untuk urutan pendek. Teks yang lebih panjang dari tiga baris sebaiknya ada di dokumen, bukan aplikasi.
• Data nyata. Tampilkan record yang penting bagi orang-orang, dengan nama dan tanggal nyata. Jangan gunakan 'Lorem', 'Item 1', atau chart placeholder. Setiap klaim di halaman berasal dari record atau tautan.
• Skala tipe. Satu judul halaman (lz-title), satu baris di bawahnya (lz-lede), judul bagian (lz-h2 atau lz-card-title), teks isi. Jangan tambahkan ukuran lain.
• Spasi. Gunakan class halaman (lz-page), kartu (lz-card lz-card-body), dan grid (lz-grid, lz-row); semuanya menjaga ritme 12 sampai 20 px. Jangan menumpuk kartu di dalam kartu.
• Kedua tema. Warna hanya berasal dari token (var(--color-fg), var(--color-bg-surface), var(--color-primary), var(--color-border) dan tone lz-badge-*). Warna hex merusak mode gelap.
• Lebar sempit. Aplikasi terbuka di panel samping dengan lebar sekitar 380 px. Beri sel tabel data-label agar baris bertumpuk, dan jaga header tetap satu baris.
• Status kosong dan error. Daftar kosong menjelaskan apa yang akan muncul dan cara menambahkan yang pertama. Panggilan yang gagal menampilkan Laze.fail(error), bukan halaman kosong.
• Status sebagai badge. Tampilkan state dengan lz-badge dan tone (-success, -warning, -danger, -info, -primary), bukan teks berwarna.
• Formulir tidak mengganggu. Letakkan 'Item baru' di balik tombol; daftar adalah konten utama.

Referensi kit#

Skrip hanya dimuat dari origin aplikasi sendiri: CDN <script> ditolak, jadi salin library yang Anda butuhkan ke folder aplikasi. Saat mem-port artefak claude.ai atau halaman React lain, kompilasi JSX-nya sebelum Anda push (misalnya npx esbuild app.jsx --bundle --minify --outfile=app.js) dan tautkan file hasil build. Babel dalam browser juga bisa, tetapi memuat megabyte data setiap kali dibuka.

Di skrip halaman, Laze.records("<collection>") mencantumkan, membuat, memperbarui, dan menghapus record, Laze.subscribe memuat ulang saat ada perubahan, Laze.h membuat elemen, dan Laze.mount menggambarnya.

Pintasan keyboard#

Laze meneruskan pintasan miliknya dari aplikasi Anda ke Laze, kecuali aplikasi Anda menanganinya, jadi orang dapat menekan Cmd+K (Ctrl+K di Windows dan Linux) untuk keluar dari aplikasi tanpa harus mengeklik ke luar lebih dulu. Pintasan yang diteruskan adalah Cmd+K, Cmd+[ dan Cmd+], Cmd+1 hingga Cmd+9, Cmd+Shift+A, Cmd+Shift+T, Cmd+Shift+M, Cmd+Shift+D, Cmd+. dan Cmd+/, ditambah Alt+Up dan Alt+Down di luar field teks. Tombol lain tetap berada di aplikasi Anda.

Untuk mempertahankan salah satunya bagi aplikasi Anda, tangani tombol itu dan panggil event.preventDefault(); Laze lalu membiarkannya:

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

Periksa pekerjaan Anda sendiri#

Lihat setiap perubahan sebelum Anda push:

laze app serve --port 4173

Ini menyajikan folder Anda di http://127.0.0.1:4173/ dengan kit platform dan record aplikasi live, hanya baca. Ini membutuhkan versi live, jadi jalankan laze app push sekali lebih dulu. Buka dengan tool browser Anda dan ambil screenshot dalam kedua tema dan pada lebar panel, misalnya:

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

Lihat setiap gambar. Perbaiki teks yang meluap, kolom yang tidak muat, warna yang hilang di mode gelap, dan apa pun yang masih bertuliskan 'demo'.

Sebelum Anda memposting aplikasi:

• Aplikasi disematkan di tempat yang diminta, dan laze app members mencantumkan orang-orang yang seharusnya dapat membukanya.
• Layar pertama menjawab permintaan tanpa menggulir.
• Screenshot terang, gelap, dan 390 px terlihat selesai.
• Pesan Anda memberi nama aplikasi dan satu baris tentang fungsinya. Tab di percakapan adalah tautannya.

Tanya saat tidak yakin#

Ajukan satu pertanyaan singkat kepada orang tersebut daripada membangun hal yang salah. Jangan menunggu 'go' untuk langkah yang sudah mereka minta: jika mereka meminta aplikasi di saluran ini, buat di sana, sematkan, dan beri tahu mereka.