Adopt a repo는 코드베이스를 1DesignTool로 가져옵니다. 앱이 프로젝트를 앱 소유의 워크트리 — 앱 데이터 디렉터리 아래의 1design/<slug> 브랜치 — 에 등록하므로, 에이전트가 체크아웃에 쓰지 않고 실제 UI 안에서 디자인합니다. "무언가를 디자인"에서 "내 것 안에서 디자인"으로 가는 다리입니다.

도입하기

홈 화면에서 **Open folder…**로 리포지토리를 고르면 도입 시트가 열립니다. 폴더를 읽고, 그 안에서 디자인할지 묻고, Design inside this codebase를 누르면 프로젝트를 코드베이스 프로젝트로 등록합니다. 앱이 워크트리를 만듭니다 — 앱 데이터 아래에 체크아웃된 1design/<slug> 브랜치 — 프로젝트는 당신의 체크아웃이 아니라 그 위에서 열립니다.

리포지토리는 손대지 않은 채로 남습니다. 쓰기는 앱의 워크트리에 놓이고, 읽기는 그것을 통해 실제 파일에서 옵니다. 도입 시트는 격리 노트도 보여줍니다 — 워크트리가 무엇이고 왜 체크아웃이 작업 카피가 아닌지요.

워크트리 모델

코드베이스 프로젝트는 1design/<slug> 위에 삽니다 — 앱이 소유하고 앱 데이터 아래에 워크트리로 체크아웃된 브랜치입니다.

읽기 — 에이전트가 워크트리를 통해 실제 UI를 봅니다
쓰기 — 턴의 diff가 브랜치에 놓입니다. 체크아웃에는 절대 쓰지 않습니다
미리보기 — 워크트리의 앱 미리보기, 또는 자체 dev 서버
체크아웃 — 절대 쓰이지 않습니다; 호스트 관리 경로(.1design/, skill 디렉터리)는 .gitignore가 아니라 .git/info/exclude로 숨겨집니다

프로젝트의 브랜치 바가 레인을 보여줍니다 — main에서 갈라진 1design/<slug>, 앞선 커밋 수, 턴이 바꾼 파일들.

코드베이스 안에서 디자인하기

도입되면 다른 프로젝트처럼 스티어링됩니다 — 다만 브리프가 당신의 UI에 관한 것입니다. "헤더를 스티키하게", "프로필 옆에 설정 화면을 추가". 에이전트가 워크트리를 통해 실제 파일을 편집하고, 미리보기는 자체 dev 서버나 앱 미리보기에서 도는 앱을 보여줍니다.

diff 범위 게이트

코드베이스 프로젝트는 전체 design-kit 게이트를 돌리지 않습니다. 리포지토리는 생성된 아티팩트가 아니므로, 그렇게 검사하면 턴이 건드리지도 않은 코드에 플래그가 붙을 것입니다. 대신 검사는 diff 범위입니다. 턴이 바꾼 파일들이 검증되고(tells.mjs가 diff에서 실행), 브랜치 바의 리뷰 액션이 턴이 한 일을 정확히 보여줍니다.

리뷰와 머지

턴의 작업이 좋아 보이면, 브랜치 바의 Review changes가 턴이 만든 diff를 보여주고, Copy merge command나 Merge into main이 브랜치의 작업을 리포지토리로 되돌립니다. Discard는 워크트리 상태를 버립니다. 머지되는 것은 체크아웃의 main입니다 — 워크트리는 샌드박스입니다.

Build mode와 Sketch mode

코드베이스 프로젝트는 라이브 미리보기 위에 두 개의 추가 모드를 갖습니다.

Build mode — 돌고 있는 앱의 UI를 비주얼로 편집하고, 변경이 코드로 다시 씁니다 (Build mode 참조)
Sketch mode — 컴포넌트에 매핑되는 .1d 스케치 (Sketch mode 참조)

Direct mode

워크트리 모델이 기본인 이유는 안전하기 때문입니다 — 앱이 앱 데이터 아래의 자체 브랜치에 쓰고, 체크아웃에는 절대 쓰지 않습니다. 도입 시트의 대안인 Direct mode는 프로젝트를 체크아웃 자체를 가리키게 합니다. 에이전트가 실제 파일을 제자리에서 편집합니다. 더 빠르지만 작업이 작업 카피에 놓이므로, 워크트리 기본값이 존재하는 이유가 있습니다.

강점

실제 앱 안에서 디자인 — 이미 존재하는 화면을 리스타일
기능 작업 — 새 화면이나 플로를 제자리에서
UI 패스 — 전체 앱 비주얼 패스를 diff로
코드베이스 온보딩 — 에이전트가 살아야 할 리포지토리를 읽음

격리 노트

워크트리가 있는 이유는 에이전트의 작업이 머지 전까지 체크아웃을 건드릴 수 없게 하기 위해서입니다 — 등록된 프로젝트 루트는 앱의 브랜치이고, 읽기와 쓰기는 그것을 거치며, 프로젝트가 필요로 하는 호스트 관리 파일들은 .git/info/exclude로 숨겨져 git status가 깨끗하게 유지됩니다. 비용은 한 단계입니다. 작업이 맞으면 브랜치를 머지합니다.

Tip: 머지가 깨끗할 때까지 워크트리를 유지하세요 — 작업이 확인되기 전에 브랜치를 삭제하면 diff를 잃습니다. 머지 버튼이 그것을 한 동작으로 만들지만, 클릭 전에 리뷰하세요.

코드 리포지토리 도입하기