CLI·MCP 작업별 가이드

프로젝트 작업 준비

joripspace start PROJECT --json
joripspace knowledge search --query "deployment and diagnostics" --json
joripspace --help

프로젝트에 연결하고 현재 상태를 확인하는 것부터 시작해 보세요. 응답을 바탕으로 기존 소스와 배포 상태에 맞춰 작업을 이어갈 수 있습니다. knowledge search로 작업에 맞는 안내를 찾고, 명령 옵션은 도움말에서 확인하세요.

MCP로 연결했다면 에이전트가 사용 가능한 도구와 매뉴얼에서 필요한 정보를 찾을 수 있습니다. AGENTS.md에는 프로젝트 규칙을 정리하고, 상세 사용법은 필요할 때 찾아보는 방식으로 관리하면 편리합니다.

빌드·배포·검증

먼저 프로젝트에서 사용하는 빌드 명령으로 앱을 준비하세요. GitHub가 연결되어 있다면 설정된 브랜치나 릴리스 방식으로 배포합니다. CLI로 직접 배포할 때는 빌드 파일이 저장된 폴더와 서버 진입점 파일을 확인하세요.

아래 예제는 빌드된 dist 폴더를 배포하며 worker.js를 서버 진입점으로 사용합니다. 폴더와 파일명은 실제 빌드 결과에 맞게 바꿔 주세요.

joripspace deploy --project PROJECT --dir dist --entrypoint worker.js --label "Release" --json
joripspace deployments --project PROJECT --json
joripspace events --project PROJECT --event-type error --json

배포가 끝나면 반환된 서비스 URL을 열어 변경한 기능을 사용해 보세요. 동적 페이지와 오류 응답도 함께 확인하면 좋습니다. 배포 응답이 끊겼을 때는 이미 완료됐을 수 있으므로 다시 실행하기 전에 이력을 조회하세요. 롤백과 복구 방법은 배포와 운영 점검에서 확인할 수 있습니다.

DB 확인과 마이그레이션

joripspace db schema --project PROJECT --json
joripspace db query --project PROJECT --sql "SELECT name FROM sqlite_master WHERE type = 'table'" --json
joripspace db migrate --project PROJECT --file migrations/001_init.sql --json

DB를 변경하기 전에 db schema로 테이블을 살펴보고 앱이 데이터를 읽고 쓰는 방식을 확인하세요. 마이그레이션은 필요한 구조 변경을 SQL 파일로 기록하는 방법입니다. 기존 데이터를 보존하도록 준비하고 조회에 쓰이는 인덱스를 확인한 뒤 한 번 적용합니다. 예제의 SQL 파일은 프로젝트에 필요한 마이그레이션 파일로 바꿔 주세요.

앱과 DB 구조가 맞지 않을 때도 DB를 초기화하기보다 필요한 변경을 마이그레이션으로 반영하는 편이 안전합니다. 업로드 파일은 storage list로 확인할 수 있습니다. 로고나 디자인 이미지 같은 고정 자산은 프로젝트 소스에 함께 보관하세요.

외부 서비스 연결

joripspace secret list --project PROJECT --json
joripspace secret generate --project PROJECT --name SESSION_SECRET --json

secret list로 이미 등록된 키 이름을 확인할 수 있습니다. 앱에 세션 서명 키처럼 임의의 값이 필요하다면 secret generate로 생성하세요. 예제의 SESSION_SECRET은 앱에서 사용할 키 이름으로 바꿀 수 있습니다.

외부 서비스에서 발급받은 키는 secret set --name KEY_NAME --value-stdin으로 표준 입력을 통해 전달하거나 프로젝트 비밀 키 화면에 직접 입력합니다. 키 값은 에이전트 대화에 붙여넣지 마세요. 저장 후에는 키 이름과 상태를 확인하고 실제 서비스 연결도 시험해 보세요.

문제 확인과 피드백

joripspace deployments --project PROJECT --include-failure-details --json
joripspace report --help

문제가 생기면 배포 이력과 로그부터 살펴보세요. 앱 코드에서 발생한 오류인지, 플랫폼 사용 중 생긴 문제인지 파악하는 데 도움이 됩니다. 조립스페이스에 신고할 때는 기대한 결과와 실제 결과, 재현 과정을 정리해 주세요. 개선 아이디어는 feedback 분류로 보낼 수 있습니다.

입력할 수 있는 항목은 신고 명령 안내에서 확인할 수 있습니다. 비밀값과 개인정보를 제외하고 전송한 뒤 성공 응답의 report_id로 접수를 확인하세요. 에이전트와 작업 중이라면 내용을 검토한 뒤 전송을 요청하면 됩니다.