메인 콘텐츠로 건너뛰기
로컬 앱 개발은 동기화를 중심으로 이루어집니다. CLI는 매니페스트를 다시 빌드하고, 서버는 워크스페이스에 이미 있는 메타데이터와의 차이만 적용합니다. 이 페이지에서는 어떤 명령을 사용할지, 동기화로 무엇이 변경되었는지 읽는 방법, 그리고 로컬 상태가 일관되지 않아 보일 때 순서대로 무엇을 해야 하는지를 설명합니다.

​
언제 어떤 명령을 사용할지

일상적인 로컬 반복 개발에서는 거의 항상 yarn twenty dev를 사용하면 됩니다. 배포와 게시(publish)는 릴리스를 배포할 때 사용하는 것이며, 로컬 개발 루프용이 아닙니다.
원하는 작업…명령노트
라이브 동기화로 로컬에서 반복 개발yarn twenty dev파일을 감시하고 변경될 때마다 동기화합니다.
한 번만 동기화하고 종료 (CI, 스크립트, 훅)yarn twenty dev --once한 번 빌드 + 동기화한 뒤 종료합니다.
변경 사항을 실제로 적용하지 않고 미리 보기yarn twenty dev --once --dry-run차이를 계산해 출력만 하고, 아무것도 기록하지 않습니다.
워크스페이스에서 앱 제거yarn twenty app:uninstall프롬프트를 건너뛰려면 --yes를 추가하세요.
타르볼을 서버로 전송yarn twenty app:publish --privatepackage.json의 버전이 엄격하게 더 높아야 합니다. 자세한 내용은 Publishing을 참고하세요.
마켓플레이스(npm)에 게시yarn twenty app:publish—
배포된 버전 설치 / 업그레이드yarn twenty app:install현재 배포된 버전을 설치합니다.
로컬 서버를 초기화하고 깨끗하게 시작yarn twenty docker:reset로컬 데이터 전체를 삭제합니다. 최후의 수단입니다.

​
로컬 동기화에는 버전 증가가 필요 없음

엄격히 증가하는 version 규칙(deploy 시 VERSION_ALREADY_EXISTS, install 시 APP_ALREADY_INSTALLED / CANNOT_DOWNGRADE_APPLICATION)은 app:publish / app:install, 즉 릴리스 경로에만 적용됩니다. yarn twenty dev는 매니페스트를 제자리에서 동기화하므로 버전을 변경할 필요가 없습니다. 따라서 반복 개발을 위해 package.json을 수정할 필요가 없습니다. 로컬 변경을 테스트하기 위해 버전을 올리고 있다면, 개발 루프가 아니라 릴리스 경로를 사용하고 있는 것입니다.

​
동기화 출력 읽기

각 동기화는 적용된(또는 --dry-run일 경우 적용될) 메타데이터 변경 사항을 출력합니다. 
Metadata changes: 2 created, 1 updated, 1 deleted
  created objectMetadata rocket
  created fieldMetadata timelineActivities
  updated fieldMetadata launchedAt
  deleted pageLayout legacyTab
✓ Synced
이 출력이 1차 진단 도구입니다. 어떤 객체, 필드, 레이아웃이 변경되었는지 정확히 알려주므로, UI를 확인하기 전에 동기화가 예상대로 동작했는지 검증할 수 있습니다. 동기화가 단일 엔티티에서 실패하면, 오류 메시지에 문제의 엔티티와 그 universalIdentifier가 함께 표시됩니다. 예를 들면 다음과 같습니다. 
Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed
그 식별자를 사용해 매니페스트(필요하다면 워크스페이스)에서 해당 엔티티를 찾아, 어떤 것이 충돌하는지 추측하지 말고 정확히 확인하세요.

​
변경 사항 미리 보기(dry run)

yarn twenty dev --once --dry-run은 매니페스트를 빌드하고, 서버에 마이그레이션 계획을 요청한 뒤, 이를 출력만 합니다. 아무것도 실제로 적용하지 않습니다. “이 동기화로 무엇이 바뀔까?”에 안전하게 답할 수 있는 방법으로, 실제로 적용하기 전에 확인할 수 있습니다. 
yarn twenty dev --once --dry-run

Building manifest...
Computing metadata diff (dry run, nothing will be applied)...
Metadata changes: 1 created, 1 updated
  created fieldMetadata timelineActivities
  updated objectMetadata rocket
✓ Dry run complete for My App — no changes were applied
dry run은 다음과 같습니다.
  • 아무것도 기록하지 않습니다. 메타데이터 마이그레이션, 애플리케이션 레코드 업데이트, 기본 역할/탭 변경, API 클라이언트 생성이 모두 수행되지 않습니다.
  • 실제 동기화에서 적용될 동일한 diff를 반환하므로, 생성/업데이트/삭제되는 엔티티를 미리 검토할 수 있습니다.
  • 위험한 변경 전에, AI가 생성한 변경 사항을 검토할 때, 또는 예기치 않은 변경이 적용되려 하면 실패해야 하는 스크립트에서 유용합니다.
dry run은 메타데이터 변경만 미리 보여 주며, 앱이 최소 한 번 이상 동기화된 상태(워크스페이스가 이 앱을 알고 있는 상태)여야 합니다. 한 번도 동기화된 적이 없는 앱에 대해 dry run을 실행하면, 서버는 앱이 설치되지 않았다고 보고합니다. 먼저 yarn twenty dev를 한 번 실행하세요.

​
복구 단계별 절차

로컬 메타데이터가 잘못된 것처럼 보일 때는, 아래 순서대로 단계를 진행하면서 문제가 해결되는 즉시 멈추세요. 각 단계는 이전 단계보다 더 많은 영향을 미칩니다.
  1. 재동기화. yarn twenty dev --once를 다시 실행하세요. 동기화는 멱등적이므로, 깨끗한 매니페스트를 다시 실행해도 안전하며 일시적인 오류가 이 방식으로 해결되는 경우가 많습니다.
  2. 계획 미리 보기. yarn twenty dev --once --dry-run을 실행해, 다음 동기화가 정확히 무엇을 변경하려 하는지 실제로 적용하지 않고 확인하세요.
  3. 명시적인 오류 읽기. 동기화가 실패하면, 메시지에 포함된 메타데이터 타입과 universalIdentifier(위 참조)를 확인한 뒤, 매니페스트에서 해당 엔티티를 찾으세요. 충돌은 보통 중복되었거나 재사용된 식별자를 가리킵니다.
  4. 삭제 후 재설치. yarn twenty app:uninstall을 실행한 뒤, 다시 동기화합니다(yarn twenty dev). 이 방법은 워크스페이스의 나머지 부분은 그대로 둔 채, 앱의 메타데이터를 깨끗한 상태에서 다시 구축합니다.
  5. 전체 초기화(최후의 수단). yarn twenty docker:reset을 실행한 뒤, 다시 시드하고 재동기화합니다.
yarn twenty docker:reset은 로컬 인스턴스의 모든 데이터를 삭제합니다. 모든 워크스페이스, 레코드, 앱이 제거됩니다. 이전 단계들이 모두 실패했을 때에만 사용하세요.
메타데이터 오류가 발생했나요? 이슈를 생성해 주세요. 이때 실패한 마이그레이션 메시지(메타데이터 타입과 universalIdentifier 포함), 동기화 시 출력된 Metadata changes, 그리고 실행한 명령들을 함께 첨부해 주세요.

​
하나의 워크스페이스에서 동시 동기화 피하기

동기화는 메타데이터 마이그레이션을 적용합니다. 동일한 워크스페이스에 대해 동시에 여러 번 동기화, 배포, 설치 작업을 실행하면(예: 여러 터미널이나 AI 에이전트가 병렬로 반복 실행하는 경우), 마이그레이션이 서로 얽혀 메타데이터가 부분적으로만 적용된 상태로 남을 수 있습니다. 서버는 이를 방지하기 위해 워크스페이스별로 동기화를 직렬화하지만, 그럼에도 중요한 메타데이터 작업은 동시에 실행하지 말고 단일 프로세스를 통해 순차적으로 실행하는 것이 좋습니다. 여러 에이전트로 개발을 오케스트레이션한다면, 이들의 sync/deploy/install 호출을 하나의 큐로 모아 한 번에 하나씩만 실행되도록 하세요.

​
실패 유형 구분하기

문제가 발생했을 때, 메타데이터 diff와 명시적인 오류를 통해 실패 지점을 파악할 수 있습니다.
  • 매니페스트 빌드 오류 — 동기화 전에 CLI가 실패합니다(MANIFEST_BUILD_FAILED, TYPECHECK_FAILED). 앱 소스를 수정하세요.
  • 동기화 / 마이그레이션 오류 — 빌드는 성공했지만 diff를 적용하는 데 실패하며, 메시지에 엔티티와 universalIdentifier가 표시됩니다. 충돌하는 메타데이터를 수정하세요.
  • 앱 코드 런타임 오류 — 동기화는 성공했지만 로직 함수나 컴포넌트가 런타임에 올바르게 동작하지 않는 경우입니다. function logs를 확인하세요.
  • 로컬 인스턴스 상태 — 위의 어느 경우에도 해당하지 않지만 워크스페이스가 여전히 잘못되어 보이는 경우입니다. 복구 사다리를 순서대로 따라가세요.