본문으로 건너뛰기
가이드

코딩 도우미와 함께 작업하기

내 앱 폴더와 공개 계약을 기준으로 코딩 도우미에게 작업을 맡깁니다.

코딩 도우미와 함께 작업하기

터미널에서 공식 계약 찾기

어느 폴더에서나 실행할 수 있으며 프로젝트 연결, 로그인, 플랫폼 소스가 필요하지 않습니다. docs를 지원하는 CLI를 설치하세요. CLI나 선택한 Developers 사이트가 아직 지원하지 않으면 이 웹사이트에서 문서를 직접 읽습니다.

코드 예시
Shell
nexia docs
nexia docs search "리소스 권한" --locale ko
nexia docs read app-sdk-sdk-contracts --locale ko
nexia docs search "Resource" --json

docs는 이 가이드를 읽습니다. 검색은 공개 문서 중 최대 20개를 반환하며 제목·설명 일치를 우선합니다. 공백으로 구분한 검색어가 모두 포함되어야 합니다. 결과의 문서 ID를 docs read에 전달하세요. --json은 구조화된 결과를, 일반 본문 조회는 Markdown을 출력합니다. --locale en|ko로 언어를 선택하며 기본값은 터미널 언어입니다. 원문 URL과 실제 본문 언어도 표시합니다. 번역이 없으면 공개된 다른 언어판을 사용할 수 있습니다. 검색 결과가 없다고 기능이 없는 것은 아닙니다. 다른 용어나 영어로도 확인한 뒤 계약 누락을 보고하세요.

기본 조회 주소는 https://developers.nexia.to이며 NEXIA_ENDPOINT로 운영자가 제공한 Developers 주소를 선택할 수 있습니다. 저장된 로그인 자격증명을 읽거나 프로젝트 연결을 변경하지 않습니다. 조회 대상은 공개 문서이며 설치 버전에 고정된 문서가 아닙니다. PHP·프런트엔드 SDK의 잠금 파일 버전, 해당 가이드의 버전 요구사항과 설치된 공개 인터페이스·타입을 함께 확인하세요. 검색 결과만으로 SDK 호환성을 판단하지 않습니다.

작업구현 전에 읽을 문서
첫 앱과 리소스빠른 시작, 리소스 만들기
모델 필드와 마이그레이션데이터 모델과 마이그레이션
Actor·API·권한PHP SDK, 권한과 역할, API 권한 적용
폼·목록·조직 범위·CSS프런트엔드 계약, 앱 화면 만들기
다른 앱의 데이터Resource References, 앱 간 연동 선택
이벤트와 백그라운드 작업이벤트와 비동기 작업
다국어 처리앱 다국어 처리
검증과 조회 성능앱 테스트
출시앱 출시

프로젝트 루트 지침은 연결·앱 선택·공유 개발 watcher를, 앱 지침은 해당 앱의 책임·도메인 문서·검사를 다룹니다. 신규 템플릿은 이 문서로 연결하며 기존 파일은 다시 쓰지 않습니다. 이 개발 흐름에 별도 skill이나 MCP 연결은 필요하지 않습니다.

먼저 읽을 계약과 빠른 피드백

생성된 앱 AGENTS.md를 읽고 위 표에서 작업에 필요한 문서와 설치된 공개 타입만 확인하세요. 화면은 직접 UI를 만들기 전에 공개 호스트 공통 컴포넌트와 지원 속성을 우선 확인합니다. 공개 계약이 없다면 Core 내부 메서드를 추측하지 말고 지원 요청에 필요한 정보를 정리합니다.

개발 도구 0.2.2부터 nexia check는 $request->user()->getKey() 및 auth()->user()->getKey() 직접 호출에 파일명과 대체 방법을 안내합니다. 모든 변수·별칭을 분석하는 타입 검사는 아닙니다. nexia setup --devtools로 도구를 갱신해도 기존 앱 파일과 지침은 덮어쓰지 않습니다. 기존 AGENTS.md는 개발자가 관리하며 도구 업데이트가 동기화하거나 교체하지 않습니다.

단계확인할 수 있는 것아직 증명하지 않는 것
nexia check선언·PHP 문법·번역 구조·명백한 사용자 계약 오류실제 권한과 저장 성공
nexia dev 후 샌드박스실행 준비, 허용·거부 동작, 저장과 화면 갱신게시 버전의 설치 성공
제출 심사고정 버전의 기계 검사와 AI 분석관리자 승인 또는 게시 완료

에이전트에게 변경 파일, 검사 명령과 결과, 실제로 확인한 동작, 미확인 항목을 구분해 보고하도록 요청하세요. 저장 응답이 불확실하면 결과 확인부터 하고, 성공 응답 뒤 상세·목록이 갱신되는지도 확인합니다.

내 앱 안에서 작업하기

AI와 함께 로컬 개발부터 시작하세요. nexia create app으로 만든 앱 폴더만 코딩 도우미에서 여세요. 생성된 AGENTS.md가 작업 경계를 설명하고 nexia.json이 앱을 선언합니다.

구체적인 화면이나 동작을 요청하세요. 내 앱 안에서만 수정하고 nexia check로 검사한 뒤 샌드박스 작업 탭에서 결과를 확인합니다. Core 복제·재배포, CLI 자격증명 읽기, 존재하지 않는 원격 API 생성을 요청하지 마세요. Core 저장소의 스킬은 내부 운영 도구이며 외부 개발자의 설치 요건이 아닙니다.

로컬 MCP 실행은 공개 CLI에서 제공하지 않습니다. 에이전트는 생성된 AGENTS.md와 공개 문서를 사용합니다.

확인

nexia status로 원하는 프로젝트에 연결됐는지 확인하세요. 프로젝트 콘솔에서 개발 공간을 열고 작업 탭의 앱을 확인합니다.

코드 예시
Shell
nexia status

공통 구현 규칙

설치된 공개 패키지로 앱 저장소 안에서 작업합니다. Core·Sandbox·CLI·SDK 소스나 런타임 이미지를 복사·마운트·수정·배포하지 않습니다. PHP 플랫폼 계약은 nexia-cloud-os/sdk-laravel, 프런트엔드는 @nexia/sdk에서 가져옵니다. Core나 다른 앱을 import하거나 해당 테이블을 조회하거나 설치된 패키지를 수정하지 않습니다. 앱 식별자와 namespace를 보존합니다. 앱 간 연동은 테넌트·Actor 컨텍스트를 복원하는 공개 Resource Reference 계약과 선언된 이벤트를 사용합니다. 비밀과 서버 코드는 공개 브라우저 자산 밖에 둡니다. 필수 데이터는 앱 initializer에, 샘플은 별도 fixture에 둡니다. 다른 앱의 seeder·migration은 수정하거나 실행하지 않습니다. App Family와 launcher 순서는 중앙 카탈로그를 직접 바꾸는 설정이 아니라 심사 요청입니다. 개발자 지원에 보낼 보고서는 민감 정보를 제거하고 개발자가 검토한 뒤 전송합니다.

인증된 Laravel 요청에서는 $request->user()->getAuthIdentifier(), Nexia\Identity\Contracts\Actor에서는 $actor->key()를 사용합니다. 호스트 식별자는 Core Eloquent 모델이 아닌 인터페이스입니다. Party 식별자는 Party::publicId()와 displayLabel()로, legalName 같은 사람 프로필은 BatchPersonProfileDirectory로 조회합니다. 앱 소유 모델은 계속 getKey()를 사용할 수 있습니다.

프런트엔드 권한 조회를 Resource 범위와 맞춥니다. 테넌트 공통 권한이 법인·운영조직 권한을 대신하지 않습니다. 로딩과 거부를 구분하고 백엔드 Policy를 최종 기준으로 둡니다. 비동기 작업 재개 시에도 테넌트·Actor·조직·soft-delete 범위를 보존합니다. 영속 상태를 브라우저 저장소에만 두지 않습니다. 저장 성공 응답을 표시하거나 관련 쿼리를 무효화하고, 응답이 불확실하면 재시도 전에 호스트의 저장 결과 복구를 사용합니다. 불확실한 쓰기를 자동 재제출하거나 요청 사이에 권한 판단을 캐시하지 않습니다.

페이지 조직 범위는 Route Surface organizationScope의 NxOrganizationTargetSelector로 breadcrumb 뒤, 헤더 액션 앞에 둡니다. 액션·테이블 툴바·목록 필터에 중복 배치하지 않습니다. 표준 공통 데이터 화면에는 선택기가 없습니다. 커스텀 화면이 지원 축과 읽기 권한을 명시하고, 소유·적용·권한 범위를 컬럼으로 추측하지 않습니다. 일반 목록은 읽기 권한과 함께 useOrganizationListScope를 사용하고, 관계·복수 권한 화면은 자체 URL adapter를 유지합니다. 레코드 조건은 ResourceTable 필터에 둡니다. 폼은 NxFormSection/NxFormField와 공통 draft binding으로 구성합니다. NxResourceFormLegalEntityField는 생성 시 허용된 대상을 선택하고 편집 시 저장된 소유자의 표시 이름을 보여줍니다. RecordSurface가 조회·생성·편집 모드를 소유합니다. 경로만으로 편집 권한을 추론하거나 마운트된 폼을 숨기거나 조회 화면을 비활성 입력으로 만들지 않습니다. 소유자 선택기나 프런트엔드 Information Schema도 추가로 만들지 않습니다.

@nexia/sdk/vite의 nexiaAppConfig(import.meta.url)을 사용합니다(빌드 SDK 0.8.2부터). 화면·위젯은 지연 로딩하고 호스트 peer는 external로 유지합니다. 공통 설정을 확장해 상대 자산 URL·의존성 preload·호스트 호환 manifest를 보존합니다. Vite library mode는 기본 지연 의존성 preload를 끕니다. SDK 업그레이드 후에는 잠금 파일 버전을 확인하고 앱 자산을 다시 빌드해 게시합니다. 공유 런타임 이미지는 심사된 자산을 다시 빌드하지 않습니다. entry와 lazy 의존성을 확인하고 첫 진입·앱 내부·앱 간 이동을 따로 측정합니다. 제목이 보이거나 빌드가 성공한 것만으로 업무 데이터 준비를 증명하지 않습니다.

페이지네이션 전에 인가·필터를 적용합니다. 허용된 페이지 ID만 공개 batch 계약·eager loading·집계·EXISTS로 보강합니다. 행마다 SQL·호스트 호출을 추가하거나 상태 표시에 필요한 플래그만 얻으려고 자식 레코드 전체를 로딩하지 않습니다. correlated EXISTS가 자식을 반복 스캔하면 페이지 단위 집계로 바꿉니다. 도메인 SQL은 앱에 두고 공통 호스트 비용은 플랫폼에 보고합니다. 표시 플래그가 쓰기 권한은 아니므로 변경 시 권한·의존성을 재확인합니다. 최종 검증에서 인터페이스만 구현한 식별자 대역, 서로 다른 프로필, 날짜 경계, 라이프사이클 우선순위, 여러 행·빈 결과·의존성 변경을 필요한 범위에서 검사합니다. 쿼리·호출 증가가 제한되는지 확인하고 동일한 데이터·Actor 범위·페이지 크기로 cold/warm, 앱 SQL·호스트 호출·HTTP·브라우저 시간을 구분합니다. 지연을 감추려고 모든 화면을 한 번에 묶지 않습니다. 앱 테스트를 참고하세요.

exact-self 참조의 ResourceReferenceSelfServiceContribution은 모든 읽기가 복원된 Actor·조직의 레코드만 반환할 때 사용합니다. 목적을 명시적으로 허용하고 다른 Actor·조직, 위조된 ID·필터·날짜, 원본 권한 회수를 검사합니다. 요청 본문 플래그가 self 권한을 부여하지 않습니다. Resource References를 참고하세요.

번역을 수정할 때는 앱 다국어 처리를 확인하세요. 설명문을 포함한 값은 2,000자까지입니다. 검증 단계에서 nexia check를 실행하고 표시된 카탈로그 필드를 수정한 뒤 재시도하세요. 운영자 확인이 필요한 상태에서는 .nexia와 데이터를 보존합니다.

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

읽기 성능의 책임과 완료 기준

공통 SDK 호출의 전달·권한·카탈로그 비용은 플랫폼이 담당합니다. 앱은 호출 횟수, 조회 범위와 화면의 요청 시점을 담당합니다. 플랫폼의 요청 내 재사용은 최적화이며 앱의 정확성 계약이 아닙니다. 같은 항목을 반복 호출해도 무료라고 가정하지 마세요. 공통 런타임 갱신은 기존 앱 소스를 고치지 않으며, 앱의 반복문·화면 요청을 줄이는 변경은 해당 앱 개발자가 구현하고 테스트해야 합니다.

코딩 도우미에게 다음 기준을 변경 작업과 함께 적용하도록 요청하세요.

  • 사람 목록은 BatchPersonProfileDirectory::findByPartyKeys(), 리소스 참조는 ResourceReferences::resolveMany()로 현재 허용된 페이지의 고유 ID만 조회합니다. 서로 다른 리소스·권한 문맥은 섞지 않습니다.
  • 허용된 조직 대상이나 동작 가능 대상이 필요하면 OrganizationTargetResolver를 사용합니다. 모든 운영 조직을 나열하고 각 조직에서 allowsPermission()을 반복하지 않습니다. 대상 조회는 레코드 Policy나 실제 쓰기 인가를 대신하지 않습니다.
  • 같은 의미의 프런트엔드 조회는 사용자·테넌트·조직·필터·페이지 등 필요한 문맥을 포함한 같은 query key로 공유합니다. 숨겨진 상세/목록은 필요한 때만 조회하고, 화면을 CSS로 숨긴 것만으로 조회가 중지된다고 가정하지 않습니다.
  • 서로 결과가 필요 없는 조회는 독립적으로 시작합니다. 필수 권한·대상 해석을 건너뛰거나 모든 SDK 호출을 무제한 병렬화하지 않습니다. 쓰기 후 무효화·재조회는 현재 보이는 데이터와 영향을 받은 범위를 기준으로 유지합니다.

개발 완료 보고에는 변경된 경로의 호출 수 회귀 테스트와 실제 화면 관측을 포함하세요. nexia check의 통과만으로 N+1, 중복 HTTP, 지연 또는 권한 안전성이 검증되지는 않습니다. 성능 검증 기준과 API의 페이지 단위 조회를 함께 적용합니다.

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