Adopt a repo đưa một codebase vào 1DesignTool: app đăng ký dự án trên một
worktree do app sở hữu — một branch 1design/<slug> nằm dưới thư mục
app-data — để agent thiết kế bên trong UI thật của bạn mà không bao giờ ghi
vào checkout của bạn. Đây là cây cầu từ "thiết kế một cái gì đó" sang "thiết
kế trong cái của tôi".
Adopt một repo
Từ màn hình home, Open folder… chọn repo và mở sheet adopt: nó đọc thư
mục, hỏi có thiết kế bên trong không, và khi bạn chọn Design inside this
codebase sẽ đăng ký dự án thành một codebase project. App tạo worktree —
một branch 1design/<slug> được checkout dưới app-data — và dự án mở trên
branch đó, không phải checkout của bạn.
Repo của bạn vẫn nguyên vẹn: ghi rơi vào worktree của app, đọc lấy từ các file thật của bạn qua worktree đó. Sheet adopt cũng hiển thị ghi chú về cách ly — worktree là gì và tại sao checkout của bạn không phải bản làm việc.
Mô hình worktree
Một codebase project sống trên 1design/<slug> — một branch app sở hữu, được
checkout như một worktree dưới app-data:
- Đọc — agent thấy UI thật của bạn qua worktree
- Ghi — diff của các lượt rơi vào branch, không bao giờ vào checkout
- Preview — preview của app trên worktree, hoặc dev server của riêng bạn
- Checkout của bạn — không bao giờ bị ghi; các đường dẫn do host quản lý
(
.1design/, thư mục skill) được ẩn qua.git/info/exclude, không phải.gitignore
Thanh branch trên dự án hiển thị làn — 1design/<slug> từ main, số commit
đang đi trước, và các file mà lượt đã đổi.
Thiết kế bên trong codebase
Sau khi adopt, nó điều hướng như mọi dự án — nhưng brief nói về UI của bạn: "làm header sticky", "thêm màn settings cạnh profile". Agent sửa các file thật qua worktree; preview hiển thị app chạy trên dev server của bạn hoặc preview của app.
Cổng giới hạn theo diff
Codebase project không chạy cổng design kit đầy đủ — repo của bạn không phải
artifact được sinh ra, nên kiểm tra nó như một artifact sẽ gắn cờ cả code mà
lượt không hề chạm vào. Thay vào đó các kiểm tra được giới hạn theo diff:
các file đã đổi của lượt được verify (tells.mjs trên diff), và hành động
review trên thanh branch hiển thị chính xác lượt đã làm gì.
Review và merge
Khi công việc của một lượt trông ổn, Review changes trên thanh branch
hiển thị diff mà lượt đã tạo ra; Copy merge command hoặc Merge into
main đưa công việc của branch về repo của bạn. Discard vứt bỏ trạng
thái worktree. main trên checkout của bạn mới là thứ merge — worktree là
sandbox.
Build mode và Sketch mode
Một codebase project mang thêm hai chế độ bên trên live preview:
- Build mode — chỉnh UI của app đang chạy một cách trực quan, và thay đổi ghi ngược lại vào code (xem Build mode)
- Sketch mode — sketch
.1dánh xạ sang component (xem Sketch mode)
Direct mode
Mô hình worktree là mặc định vì nó an toàn — app ghi vào branch của nó dưới app-data, không bao giờ vào checkout của bạn. Direct mode — lựa chọn khác trên sheet adopt — trỏ dự án thẳng vào checkout của bạn; agent sửa file thật tại chỗ. Nhanh hơn nhưng công việc rơi vào working copy của bạn, nên mặc định worktree tồn tại là có lý do.
Nó giỏi gì
- Thiết kế bên trong app thật của bạn — màn hình đã tồn tại, restyle lại
- Làm feature — một màn hình hay flow mới, đặt đúng chỗ
- Pass UI — một lượt trực quan toàn app, có diff
- Onboarding vào codebase — agent đọc repo mà nó phải sống cùng
Ghi chú cách ly
Worktree tồn tại để công việc của agent không thể chạm vào checkout của bạn
cho đến khi bạn merge — root dự án đã đăng ký là branch của app, đọc ghi đều
đi qua nó, và các file do host quản lý mà dự án cần được ẩn qua
.git/info/exclude để git status của bạn vẫn sạch. Cái giá là một bước:
khi công việc đã ổn, bạn merge branch.
Mẹo: Giữ worktree cho đến khi merge sạch — xóa branch trước khi công việc được xác nhận sẽ mất diff. Nút merge biến nó thành một thao tác; hãy review trước khi bấm.