본문으로 건너뛰기
가이드

AI와 함께 로컬 개발

앱 폴더를 열고 여러 리소스·컬럼·폼을 확장한 뒤 샌드박스에서 확인합니다.

AI와 함께 로컬 개발

에디터와 에이전트에서 열 폴더

빠른 시작으로 프로젝트 연결과 첫 앱 실행을 마쳤다면 my-project/my-app 앱 폴더를 에디터나 코딩 에이전트의 작업 폴더로 여세요. 이름은 본인이 생성한 폴더 이름으로 바꿉니다. Core·SDK·sandbox-manager 저장소를 열거나 복제할 필요는 없습니다.

프로젝트 폴더는 앱들을 담고 Developers 프로젝트와 연결하는 곳입니다. 앱 폴더가 실제 개발·Git 관리 단위입니다. 생성된 AGENTS.md, nexia.json, docs/를 먼저 읽게 하세요. 기존 지침을 덮어쓰지 마세요.

위치하는 일
my-project/nexia connect <project-id>, 프로젝트의 nexia dev 실행
my-project/my-app/코드 수정, 리소스·페이지 생성, 의존성 설치, nexia check
sandbox 작업 공간화면·권한·실제 저장 결과 확인

프로젝트에서 실행한 nexia dev는 켜 둡니다. 별도 터미널에서 앱 폴더로 이동해 작업하세요. 에이전트의 셸은 사용자 터미널의 환경 설정을 자동 상속한다고 가정하지 마세요. 별도 플랫폼의 주소·CLI 설정 디렉터리·필요한 환경 활성화 절차를 전달하고, 같은 셸에서 앱 폴더로 이동한 뒤 연결을 확인합니다. 토큰이나 인증 파일 내용을 전달할 필요는 없습니다.

코드 예시
Shell
# 앱 폴더에서 실행
nexia status

connected와 의도한 프로젝트·sandbox를 확인하세요. 연결 실패는 소스 검증 성공과 별개입니다. 실행 중인 watcher를 중복 시작하거나 연결 대상을 임의로 바꾸지 마세요.

리소스·컬럼·폼을 확장하기

첫 CRUD는 출발점입니다. 다음 순서로 하나의 업무를 완성하세요. 아래 경로는 앱 루트 기준입니다.

작업구현 위치와 확인 기준
리소스 추가nexia make resource로 모델·API·권한·화면 뼈대를 생성. 생성만으로 업무 규칙까지 완성되지 않음
컬럼 추가database/migrations/tenant/의 새 migration, src/Models/, Controller 검증·응답, 프런트 타입을 함께 수정
입력·상세·목록resources/js/resources/에서 폼 초안·제출·저장 후 기준값, 읽기 표시, 목록 컬럼을 연결. resources/lang/ 라벨도 추가
필터·정렬·권한src/Contribution/Resources/의 선언, 실제 조회 로직, src/Policies/를 함께 연결
리소스 관계같은 앱의 업무 모델과 권한 검사로 연결. 다른 앱은 공개 SDK 참조 계약을 사용하고 해당 테이블을 직접 조회하지 않음
독립 업무 화면nexia make page로 뼈대를 만들고 실제 API·조회·저장·권한을 구현. 미구현 Controller는 501을 반환

예를 들어 기존 Note를 유지하면서 고객과 업무를 추가하려면 앱 폴더에서 실행합니다. 아래 예시는 테넌트 공통 데이터를 선택합니다. 법인별 기록은 --record-owner legal_entity와 해당 권한 범위를 사용하세요.

코드 예시
Shell
nexia make resource Customer --record-owner tenant --label-ko 고객
nexia make resource Task --record-owner tenant --label-ko 업무

명령은 기존 리소스에 반복 실행하지 않습니다. 이메일·마감일·업무 상태·고객 선택 관계는 이후 코드로 구현합니다. 하나의 리소스에 생성·수정·업무 처리 폼이 여러 개 있을 수 있으며, 폼마다 별도 리소스를 만들 필요는 없습니다.

필드 하나를 처음부터 연결하는 절차는 데이터 모델과 마이그레이션, 상세·편집·독립 페이지는 App 화면 만들기를 따르세요. 이미 적용된 migration을 수정·삭제하지 말고 새 파일을 추가합니다. 기존 레코드의 기본값·필수값 전환도 정해야 합니다.

에이전트에게 업무 단위로 요청하기

앱 폴더에서 다음과 같이 요청할 수 있습니다.

AGENTS.md, nexia.json, docs를 읽고 이 앱 안에서 작업해줘.
기존 Note와 데이터를 유지하면서 고객과 업무 리소스를 추가해줘.
고객에는 이메일과 분류, 업무에는 마감일과 상태, 고객 선택을 넣어줘.
고객 등록 → 해당 고객의 업무 생성 → 업무 완료 흐름을 구현해줘.
DB migration, 입력 검증, 권한, API, 폼, 목록·상세 표시를 함께 연결해줘.
기존 migration은 수정하지 말고 새 migration을 추가해줘.
프로젝트의 nexia dev는 이미 실행 중이니 중복 실행하지 마.
내가 sandbox UI에서 확인할 메뉴·권한·절차와 미확인 항목을 알려줘.
Core 복제나 인증 정보 읽기, 존재하지 않는 API 추측은 하지 마.

구현한 업무 흐름 확인

nexia dev가 변경을 감지해 프런트엔드를 빌드하고 서버 실행 환경을 준비합니다. 파일을 추가했거나 로컬 빌드가 끝난 것만으로 서버에 반영됐다고 판단하지 마세요. 준비 실패·검토 필요 상태는 원인을 해결한 뒤 재시도합니다.

Core 0.8.163과 Manager 0.1.0-alpha.89에서는 이전 상태로 되돌린 것이 확인된 소스 반영을 실패로 마무리하므로, 개발 데이터를 초기화하지 않고 다음 저장을 진행할 수 있습니다. 반영 결과가 불확실하면 확인이 필요하므로 준비를 계속 차단합니다. 재시도 전에 준비 상태를 확인하고 watcher 재시작만으로 해결됐다고 판단하지 마세요.

  1. CLI에서 새 실행 준비 완료를 확인합니다.
  2. 워크스페이스에서 앱을 엽니다. 권한이 부족하면 설정 → 자격 증명 및 접근 → 역할에서 필요한 앱 권한을 역할에 추가하고, 접근에서 내 사용자에게 해당 역할과 적용 범위를 부여합니다. 역할 생성만으로 권한이 부여되지는 않습니다.
  3. 작업 공간의 화면 갱신 안내를 따르고 해당 앱 메뉴에서 새 리소스를 엽니다. 프로젝트 앱 목록에는 여전히 같은 앱 하나가 보입니다. 역할의 권한 목록에도 새 리소스가 없다면 선언 반영 상태부터 확인합니다.
  4. 생성·수정·새로고침 후 값 유지, 관계 선택, 잘못된 입력, 권한 거부, 목록 검색·필터·정렬을 확인합니다. 추가한 컬럼 적용 뒤 기존 데이터도 확인합니다.
  5. 미저장 입력 중 코드 변경, 취소·다시 열기, 실행 재연결에서도 작업과 데이터가 의도대로 유지되는지 확인합니다.

앱 폴더에서 nexia check로 소스 검사를 수행하고, 업무 변경에 맞는 검사는 App 테스트하기를 참고하세요. 소스 검사·빌드·실제 UI 확인 결과를 구분합니다. 업무가 준비된 뒤 App 릴리스하기로 진행하세요. AI 사용이나 앱 등록이 자동 게시를 의미하지 않습니다.

CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.

원본 위치: docs/developers/content/ko/getting-started/ai-local-development.md