Anatomi CONTEXT.md — Spesifikasi yang Dibaca Agen Koding Anda Terlebih Dahulu

Setiap ekspor figmascope dimulai dengan .zip yang berisi tujuh artefak. CONTEXT.md adalah yang dibaca pertama kali — by design. Ini bukan README. Ini bukan dokumen yang dihasilkan. Ini adalah kontrak gaya kompiler antara desain dan agen yang akan mengubahnya menjadi kode.

Artikel ini membahas apa yang ada di dalamnya, mengapa disusun demikian, dan apa yang salah ketika Anda melewatinya.

Seperti apa kontrak dibandingkan dengan dokumen

Dokumentasi mendeskripsikan apa yang ada. Kontrak menentukan apa yang harus benar. Perbedaan itu penting ketika pembaca Anda adalah LLM yang dengan senang hati akan menciptakan nilai spacing, meratakan hierarki tata letak, atau men-hardcode warna hex begitu ia tidak memiliki pilihan yang lebih baik.

CONTEXT.md dibuka dengan deklarasi target:

# CONTEXT.md — Jetpack Compose target

This file is the authoritative spec for generating UI code from this bundle.
Read it before reading any other file.

"Target Jetpack Compose" bukan hiasan. Agen menggunakannya untuk memilih primitif composable, menangani satuan dp vs sp, mengetahui bahwa Modifier.padding() adalah abstraksi yang tepat untuk spacing, dan memahami bahwa Box dengan Alignment adalah cara menangani tata letak overlay. Target React/Tailwind menghasilkan CONTEXT.md yang berbeda dengan primitif yang berbeda dalam batasannya.

Instruksi "baca ini terlebih dahulu" juga disengaja. Agen memproses konteks secara berurutan. Jika aturan token muncul setelah agen sudah mulai bernalar tentang komponen, batasan itu tiba terlambat. Menempatkan kontrak di depan berarti aturan-aturan aktif sejak token generasi pertama.

Bagian batasan ketat

Bagian paling krusial dari CONTEXT.md adalah blok batasan:

## Strict constraints (must follow)

- Never hardcode dp values if a token exists within ±2dp
- Never flatten layout hierarchy — preserve every stack/overlay/absolute node
- Use stringRef values from strings.json, never inline literal text
- Treat missing fields as absent, not zero
- Do not invent component names not present in components/inventory.json

Setiap batasan ada karena kita pernah melihat agen melanggarnya. Aturan token ±2dp adalah contoh yang paling jelas. Tanpanya, agen yang menemukan gap: 14 pada node stack akan menulis Arrangement.spacedBy(14.dp). Dengan aturan itu, ia tahu untuk memeriksa apakah spacing.16 atau spacing.12 berada dalam 2dp dan menggunakan token sebagai gantinya. Itu output yang berbeda — satu yang tetap koheren ketika nilai token berubah, satu yang tidak.

Aturan hierarki ada karena Compose adalah pohon tata letak. Ketika agen meratakan stack bersarang menjadi daftar elemen yang diposisikan datar, ia menghancurkan perilaku responsif yang tersirat oleh struktur aslinya. IR mempertahankan setiap tingkat penumpukan karena suatu alasan — lihat Per-Screen IR — Stack, Overlay, Absolute, Leaf untuk bagaimana penumpukan itu mengodekan maksud tata letak.

Batasannya bukan "gunakan token jika Anda mau." Ini "jangan pernah hardcode jika token ada." Itu larangan, bukan saran. LLM merespons secara berbeda terhadap larangan versus saran.

Aturan stringRef penting untuk i18n. Jika agen meng-inline "Speed Test" alih-alih mereferensikan kunci resource, Anda telah menciptakan lubang lokalisasi. Batasan itu mengarahkan agen ke strings.json secara eksplisit.

Cara agen membaca CONTEXT.md secara berurutan

Context window LLM memproses token dari kiri ke kanan. Struktur CONTEXT.md mengeksploitasi ini. Urutannya adalah:

1. Deklarasi target (menetapkan seluruh frame generasi)
2. Batasan ketat (larangan yang berlaku untuk setiap keputusan)
3. Peta bundle (file apa yang ada dan apa yang dikandung masing-masing)
4. Aturan penggunaan token (cara menyelesaikan spacing, warna, radius, tipografi)
5. Catatan cakupan (kesenjangan yang jujur — apa yang dicakup dan tidak dicakup oleh bundle ini)

Bagian peta bundle memberi tahu agen file mana yang harus dibaca dan dalam urutan apa:

## Bundle contents

- tokens.json — design tokens (spacing, radius, color, typography)
- screens/*.json — per-screen IR in stack/overlay/absolute/leaf format
- components/inventory.json — component identity list
- strings.json — i18n resource keys
- _meta.json — generation metadata and warnings

Tanpa peta ini, agen mungkin tidak tahu bahwa components/inventory.json ada, atau mungkin memperlakukan _meta.json sebagai spesifikasi utama. Enumerasi eksplisit memandu urutan membaca.

Catatan cakupan — apa yang secara jujur tidak dicakup v0.4

Bagian catatan cakupan adalah tempat figmascope mendokumentasikan keterbatasannya sendiri. Ini disengaja dan tidak dapat ditawar. Agen yang tidak tahu bahwa spesifikasi tidak lengkap akan dengan percaya diri mengisi kesenjangan dengan rekaan. Itu lebih buruk daripada mengetahui bahwa kesenjangan itu ada.

## Scope notes (v0.4)

- Gradient fills are not supported. Nodes with gradient fills emit a warning
  in _meta.json under warnings. Treat as a solid fill approximation or TODO.
- Typography tokens require Figma Variables to be populated. If tokensSource
  is "inferred-from-frequency" or "none", typography coverage may be partial.
- This bundle covers UI structure only. Navigation, state management,
  and network calls are outside scope.
- Component instances are identified by componentId. Full component
  source props are not included — the inventory gives identity, not implementation.

Peringatan gradient sangat penting. Figma mendukung fill gradient kompleks yang tidak memiliki padanan Compose langsung tanpa penggambaran kustom. Alih-alih menjatuhkan gradient secara diam-diam atau menghasilkan kode yang rusak, figmascope memancarkan peringatan background-gradient-not-supported:<name> di _meta.json dan mencatatnya di sini sehingga agen tahu untuk memperlakukan node yang terpengaruh sebagai kesenjangan yang diketahui, bukan bug dalam outputnya sendiri.

Catatan tipografi terhubung ke bidang tokensSource di _meta.json. Ketika file Figma tidak memiliki Variables, figmascope menyimpulkan token dari frekuensi — nilai umum menjadi token, nilai langka tidak. Catatan cakupan memberi tahu agen bahwa inferensi ini tidak sempurna dan tidak boleh berasumsi cakupan tipografi penuh. Lihat tokens.json Dijelaskan untuk cara fallback inferensi bekerja.

Contoh SALAH / BENAR

Mari kita konkretkan ini. Diberikan node stack dengan gap: 16 dan file token yang berisi spacing.16: 16:

Tanpa batasan CONTEXT.md (SALAH):

Column(
    modifier = Modifier.padding(horizontal = 24.dp),
    verticalArrangement = Arrangement.spacedBy(16.dp)
) {

Dengan batasan CONTEXT.md (BENAR):

Column(
    modifier = Modifier.padding(horizontal = Spacing.spacing24),
    verticalArrangement = Arrangement.spacedBy(Spacing.spacing16)
) {

Output BENAR direferensikan token. Ketika design system mengubah spacing.16 dari 16dp ke 14dp, kode tetap benar tanpa pencarian-dan-penggantian codebase.

Contoh lain — penanganan string. Diberikan node leaf dengan text: "Speed Test" dan stringRef: "speed.test":

SALAH:

Text(text = "Speed Test")

BENAR:

Text(text = stringResource(R.string.speed_test))

Batasan menunjuk ke strings.json, kuncinya adalah speed.test, dan agen tahu cara memetakan notasi titik ke Android resource ID. Itu hanya mungkin jika agen membaca batasan sebelum menghasilkan komponen.

Mengapa tidak langsung prompt agen sendiri?

Anda dapat menulis instruksi ini secara manual dalam prompt Anda. figmascope mengeksternalisasikannya ke dalam file karena:

• Batasan diturunkan dari bundle yang sebenarnya. Aturan ±2dp hanya masuk akal jika tokens.json ada. CONTEXT.md dibuat dengan mengetahui token apa yang ada.
• Catatan cakupan per-proyek berubah per file. File Figma dengan cakupan Variables penuh mendapatkan catatan tipografi yang berbeda dari yang memiliki token yang disimpulkan.
• File ada dalam zip. Anda dapat mereferensikannya sebagai konteks tanpa copy-paste. Cursor, Claude Code, dan alat serupa semuanya mendukung referensi @-file.
• Dapat direproduksi. Setiap ekspor dari file Figma yang sama menghasilkan CONTEXT.md yang sama. Agen tim Anda membaca kontrak yang sama setiap saat.

Tujuannya bukan untuk melakukan prompt-engineering di sekitar default agen. Ini untuk mengirimkan spesifikasi yang membuat default tidak relevan.

Struktur dibandingkan dengan alternatif

Dev Mode Figma menghasilkan pengukuran, variabel, dan cuplikan kode. Ia tidak menghasilkan spesifikasi. Agen yang menggunakan output Dev Mode harus menyimpulkan aturan dari contoh — yang berarti ia akan menyimpulkan aturan yang salah untuk kasus tepi.

Locofy dan alat serupa menghasilkan kode secara langsung. Mereka tidak memiliki padanan CONTEXT.md karena mereka tidak mengharapkan agen membaca spesifikasi — mereka berharap menjadi agennya. Itu berhasil ketika generasi kode alat tersebut persis cocok dengan stack Anda. Tidak berhasil ketika Anda memiliki konvensi penamaan khusus proyek, pustaka komponen kustom, atau design system dengan token yang tidak diketahui alat tersebut.

CONTEXT.md adalah brief desain yang dapat dibaca mesin. Ini adalah hal yang ada sebagai halaman Confluence atau dokumen Notion di setiap handoff desain pra-LLM, hanya disusun untuk audiens yang benar-benar mengikuti aturan.

Apa yang harus dilakukan dengannya

Ketika Anda membuka ekspor figmascope di Cursor atau Claude Code:

1. Tambahkan @CONTEXT.md ke konteks Anda sebelum prompt apa pun tentang desain.
2. Referensikan JSON layar yang sedang Anda kerjakan: @screens/home.json.
3. Jika Anda menyentuh token, tambahkan @tokens.json.
4. Jika Anda bekerja dengan string, tambahkan @strings.json.

Batasan CONTEXT.md berlaku di seluruh sesi setelah dimuat. Anda tidak menambahkannya kembali per prompt — Anda menambahkannya sekali di awal dan membiarkannya membingkai setiap generasi berikutnya.

Artefak lain dalam bundle dibahas dalam sisa seri ini. Mulailah dengan tokens.json Dijelaskan untuk cara sistem token menangani file dengan dan tanpa Figma Variables, atau Per-Screen IR untuk cara tata letak Figma dipetakan ke node stack/overlay/absolute/leaf. Siap mencobanya? Tempel URL Figma Anda di figmascope.dev dan ekspor bundle pertama Anda.