Giải phẫu CONTEXT.md — Thông số kỹ thuật mà Coding Agent đọc đầu tiên

Mỗi lần xuất từ figmascope bắt đầu bằng một .zip chứa bảy artifact. CONTEXT.md là tệp được đọc đầu tiên — theo thiết kế. Đây không phải là README. Không phải là tài liệu được tạo ra. Đây là một hợp đồng kiểu compiler giữa thiết kế và agent sẽ chuyển nó thành code.

Bài đăng này đi qua nội dung của nó, lý do tại sao nó được cấu trúc theo cách đó, và điều gì xảy ra sai khi bạn bỏ qua nó.

Hợp đồng trông như thế nào so với tài liệu

Tài liệu mô tả những gì tồn tại. Hợp đồng chỉ định những gì phải đúng. Sự phân biệt đó quan trọng khi người đọc của bạn là một LLM sẽ vui vẻ bịa ra các giá trị spacing, làm phẳng cấu trúc layout, hoặc hardcode màu hex ngay khi nó không có lựa chọn tốt hơn.

CONTEXT.md mở đầu bằng một khai báo mục tiêu:

# 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.

"Jetpack Compose target" không phải là trang trí. Agent sử dụng nó để chọn các primitive composable, xử lý đơn vị dp so với sp, biết rằng Modifier.padding() là abstraction đúng cho spacing, và hiểu rằng Box với Alignment là cách bạn xử lý layout overlay. Mục tiêu React/Tailwind tạo ra CONTEXT.md khác nhau với các primitive khác nhau trong các ràng buộc.

Hướng dẫn "đọc cái này trước" cũng có chủ đích. Các agent xử lý context tuần tự. Nếu một quy tắc token xuất hiện sau khi agent đã bắt đầu suy nghĩ về một component, ràng buộc đến quá muộn. Việc đưa hợp đồng lên đầu có nghĩa là các quy tắc có hiệu lực từ token đầu tiên của quá trình tạo ra.

Phần ràng buộc nghiêm ngặt

Phần quan trọng nhất của CONTEXT.md là khối ràng buộc:

## 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

Mỗi ràng buộc tồn tại vì chúng ta đã thấy các agent vi phạm nó. Quy tắc token ±2dp là ví dụ rõ ràng nhất. Không có nó, một agent gặp gap: 14 trên một stack node sẽ viết Arrangement.spacedBy(14.dp). Với quy tắc đó, nó biết kiểm tra xem spacing.16 hoặc spacing.12 có trong khoảng 2dp không và sử dụng token thay thế. Đó là output khác nhau — một cái duy trì nhất quán khi giá trị token thay đổi, một cái không.

Quy tắc hierarchy tồn tại vì Compose là một layout tree. Khi một agent làm phẳng một stack lồng nhau thành một danh sách các phần tử được định vị, nó phá hủy hành vi responsive được ngụ ý bởi cấu trúc ban đầu. IR bảo tồn mọi cấp độ lồng nhau vì một lý do — xem Per-Screen IR — Stack, Overlay, Absolute, Leaf về cách lồng nhau đó mã hóa layout intent.

Ràng buộc không phải là "sử dụng token nếu bạn thích." Đó là "không bao giờ hardcode nếu token tồn tại." Đó là lệnh cấm, không phải gợi ý. LLMs phản ứng khác nhau với lệnh cấm so với gợi ý.

Quy tắc stringRef quan trọng cho i18n. Nếu một agent inline "Speed Test" thay vì tham chiếu đến khóa resource, bạn đã tạo ra một lỗ hổng localization. Ràng buộc chỉ agent rõ ràng đến strings.json.

Cách agent đọc CONTEXT.md tuần tự

Các cửa sổ context của LLM xử lý token từ trái sang phải. Cấu trúc của CONTEXT.md khai thác điều này. Thứ tự là:

Khai báo mục tiêu (thiết lập toàn bộ khung tạo ra)
Các ràng buộc nghiêm ngặt (các lệnh cấm áp dụng cho mọi quyết định)
Bản đồ bundle (những file nào tồn tại và mỗi file chứa gì)
Quy tắc sử dụng token (cách giải quyết spacing, color, radius, typography)
Ghi chú phạm vi (các khoảng trống thành thật — bundle này làm gì và không làm gì)

Phần bản đồ bundle cho agent biết những file nào cần đọc và theo thứ tự nào:

## 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

Không có bản đồ này, một agent có thể không biết components/inventory.json tồn tại, hoặc có thể coi _meta.json là thông số chính. Việc liệt kê rõ ràng hướng dẫn thứ tự đọc.

Ghi chú phạm vi — điều mà v0.4 thành thật không bao gồm

Phần ghi chú phạm vi là nơi figmascope ghi lại các giới hạn của chính mình. Điều này có chủ đích và không thể thương lượng. Một agent không biết thông số là không đầy đủ sẽ tự tin lấp đầy các khoảng trống bằng sáng tạo. Điều đó tệ hơn là biết khoảng trống tồn tại.

## 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.

Cảnh báo gradient đặc biệt quan trọng. Figma hỗ trợ các gradient fill phức tạp không có tương đương trực tiếp trong Compose mà không cần vẽ tùy chỉnh. Thay vì âm thầm bỏ các gradient hoặc tạo code bị hỏng, figmascope phát ra cảnh báo background-gradient-not-supported:<name> trong _meta.json và ghi chú ở đây để agent biết coi các node bị ảnh hưởng là khoảng trống đã biết thay vì lỗi trong output của chính nó.

Ghi chú typography kết nối với trường tokensSource trong _meta.json. Khi một file Figma không có Variables, figmascope suy ra token từ tần suất — các giá trị phổ biến trở thành token, các giá trị hiếm thì không. Ghi chú phạm vi cho agent biết rằng suy luận này không hoàn hảo và không nên giả định phạm vi typography đầy đủ. Xem tokens.json Giải thích để biết cách fallback suy luận hoạt động.

Ví dụ SAI / ĐÚNG

Hãy làm cụ thể điều này. Cho một stack node với gap: 16 và file token chứa spacing.16: 16:

Không có ràng buộc CONTEXT.md (SAI):

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

Có ràng buộc CONTEXT.md (ĐÚNG):

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

Output ĐÚNG được tham chiếu token. Khi design system thay đổi spacing.16 từ 16dp thành 14dp, code vẫn đúng mà không cần tìm kiếm và thay thế toàn bộ codebase.

Ví dụ khác — xử lý chuỗi. Cho một leaf node với text: "Speed Test" và stringRef: "speed.test":

SAI:

Text(text = "Speed Test")

ĐÚNG:

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

Ràng buộc chỉ đến strings.json, khóa là speed.test, và agent biết cách ánh xạ dot-notation đến Android resource ID. Điều đó chỉ có thể nếu agent đọc ràng buộc trước khi tạo ra component.

Tại sao không chỉ tự prompt agent?

Bạn có thể viết các hướng dẫn này thủ công trong prompt của mình. figmascope đưa chúng vào một file vì:

Các ràng buộc được suy ra từ bundle thực tế. Quy tắc ±2dp chỉ có ý nghĩa nếu tokens.json tồn tại. CONTEXT.md được tạo ra biết những token nào có mặt.
Ghi chú phạm vi theo dự án thay đổi theo file. Một file Figma có đầy đủ Variables coverage nhận được ghi chú typography khác so với một file có token được suy luận.
File nằm trong zip. Bạn có thể tham chiếu nó như context mà không cần sao chép-dán. Cursor, Claude Code, và các công cụ tương tự đều hỗ trợ tham chiếu @-file.
Có thể tái tạo. Mỗi lần xuất từ cùng một file Figma tạo ra cùng một CONTEXT.md. Các agent của nhóm bạn đọc cùng một hợp đồng mỗi lần.

Mục tiêu không phải là prompt-engineer xung quanh các mặc định của agent. Đó là giao một thông số làm cho các mặc định không còn liên quan.

Cấu trúc so với các lựa chọn thay thế

Dev Mode của Figma xuất ra các phép đo, biến, và đoạn code. Nó không tạo ra thông số. Agent sử dụng output Dev Mode phải suy ra các quy tắc từ các ví dụ — có nghĩa là nó sẽ suy ra các quy tắc sai cho các trường hợp ngoại lệ.

Locofy và các công cụ tương tự tạo code trực tiếp. Chúng không có tương đương CONTEXT.md vì chúng không kỳ vọng agent đọc thông số — chúng kỳ vọng trở thành agent. Điều đó hoạt động khi việc tạo code của công cụ khớp chính xác với stack của bạn. Không hoạt động khi bạn có các quy ước đặt tên dự án cụ thể, thư viện component tùy chỉnh, hoặc design system với các token mà công cụ không biết.

CONTEXT.md là một design brief có thể đọc được bởi máy tính. Đây là thứ tồn tại như một trang Confluence hoặc Notion doc trong mọi design handoff trước LLM, chỉ được cấu trúc cho người đọc thực sự tuân theo các quy tắc.

Làm gì với nó

Khi bạn mở một bản xuất figmascope trong Cursor hoặc Claude Code:

Thêm @CONTEXT.md vào context của bạn trước bất kỳ prompt nào về thiết kế.
Tham chiếu screen JSON bạn đang làm việc: @screens/home.json.
Nếu bạn đụng đến token, thêm @tokens.json.
Nếu bạn làm việc với chuỗi, thêm @strings.json.

Các ràng buộc CONTEXT.md áp dụng trên toàn bộ phiên sau khi được tải. Bạn không thêm lại nó mỗi prompt — bạn thêm nó một lần lúc đầu và để nó khung mọi thế hệ tiếp theo.

Các artifact khác trong bundle được đề cập trong phần còn lại của series này. Bắt đầu với tokens.json Giải thích để biết hệ thống token xử lý các file có và không có Figma Variables như thế nào, hoặc Per-Screen IR để biết cách layout Figma ánh xạ đến các node stack/overlay/absolute/leaf. Sẵn sàng thử? Dán URL Figma của bạn trên figmascope.dev và xuất bundle đầu tiên của bạn.