TencentCloudBase/CloudBase-AI-Toolkit

CloudBase All-In-One

워크플로우

모든 CloudBase 작업은 다음 3단계 프로세스를 따릅니다:

1. 탐색 → 코드를 작성하기 전에 먼저 해당 스킬을 완전히 읽습니다.
          필요한 경우 검색하여 전체 SKILL.md 내용을 읽습니다.
          스킬 문서에서 API 패턴, 함정, 올바른 사용법을 이해한 후에만 구현을 시작합니다.
2. 구현
   ├── 2a. 리소스 준비 → MCP를 우선 사용하여 백엔드 리소스를 준비합니다.
   │     (인증 제공자 활성화, 데이터베이스 테이블 생성, 스토리지 도메인 구성,
   │      보안 규칙 설정 — 프론트엔드 코드를 작성하기 전에).
   │     현재 세션에 MCP 도구가 없으면 다음 번을 위해 MCP를 구성하고
   │     지금은 `tcb` CLI를 사용합니다 (`./cloudbase-cli/SKILL.md`).
   └── 2b. 프론트엔드 구현 → 코드 작성, 의존성 설치, 서버 시작, 테스트
3. 마무리 → cloudbase-code-review를 실행하고 모든 오류를 수정한 후 완료를 선언합니다.

주요 제약사항:

• 2a 단계(리소스 준비)는 프론트엔드 코드보다 먼저 수행되어야 합니다. MCP 도구를 우선 사용하고, 아직 로드되지 않은 경우(첫 세션/재시작 전) MCP를 구성한 후 tcb CLI를 대체로 사용합니다. 아직 생성되지 않은 리소스(테이블, 인증 제공자, 스토리지 버킷)에 의존하는 프론트엔드 코드를 작성하지 마십시오 — 평가기가 실패 처리합니다.
• 3단계를 건너뛰지 마십시오. 마무리 단계는 에이전트가 구현 중 흔히 놓치는 알려진 함정을 잡아냅니다.

범위

CloudBase 애플리케이션 구축, 통합 또는 유지 관리의 일부인 작업만 처리합니다. 여기에는 UI 디자인, 스펙 기획 및 CloudBase 앱을 위한 기타 개발 활동이 포함됩니다. 요청에 CloudBase 애플리케이션 컨텍스트가 전혀 없으면 중단하고 이 스킬이 CloudBase 기반 개발만 다룬다고 사용자에게 알립니다.

활성화 계약

다음 경우에 먼저 사용하세요

• 작업이 CloudBase 앱 빌드, 통합 또는 수리이고 워크스페이스에 이미 애플리케이션 구현이 포함된 경우.
• 요청이 하나의 CloudBase 애플리케이션 작업에서 인증, 데이터베이스, 스토리지 및 프론트엔드 작업을 혼합하는 경우.

광범위한 탐색 전에 다음을 수행하세요

• 코드를 작성하기 전에 관련 스킬을 읽으세요. searchKnowledgeBase(mode="skill", skillName=...)로 일치하는 스킬을 검색한 다음, 반환된 파일 경로를 Read하여 전체 SKILL.md 내용을 가져옵니다. 검색 결과 요약만으로 구현을 시작하지 마십시오 — 전체 문서에는 API 시그니처, 파라미터 스키마 및 함정 경고가 포함되어 있습니다.
• 기존 구현 표면을 먼저 검사하세요:
  • src/lib/backend.*
  • src/lib/auth.*
  • src/lib/*service.*
  • 라우트 가드
  • 활성 양식 제출 버튼에 바인딩된 페이지 핸들러
• 이러한 파일에 TODO가 포함되어 있으면 새 도우미, 예제 또는 대체 페이지를 만들기 전에 해당 위치에서 TODO를 구현하세요.
• 사용자가 명시적으로 시각적 변경을 요청하지 않는 한 UI 재설계 또는 디자인 스펙 출력으로 시작하지 마십시오.
• 작업이 단일 타겟 수리일 때 반복된 TaskCreate/TaskUpdate와 같은 프로젝트 관리 루프로 시작하지 마십시오. 활성 파일을 읽고 직접 편집하세요.

필요한 최소 스킬로 빠르게 라우팅

• 최소 Web + 데이터베이스 데모 / Lovable 스타일 BaaS 빠른 경로 -> ./minimal-web-baas-demo/SKILL.md (최소 전후단 데모 기본값, BaaS 우선, 클라우드 함수 없음)
• 웹 앱 실행 -> ./web-development/SKILL.md
• 웹 인증 제공자 준비 -> ./auth-tool/SKILL.md
• 웹 인증 구현 -> ./auth-web/SKILL.md
• CloudBase PostgreSQL / PG 앱 데이터 -> ./postgresql-development/SKILL.md
• CloudBase 통합 센터를 통한 WeChat Pay / 공식 계정 OAuth -> ./cloudbase-wechat-integration/SKILL.md
• 브라우저 측 문서 데이터베이스 CRUD -> ./no-sql-web-sdk/SKILL.md
• 브라우저 측 파일 업로드 -> ./cloud-storage-web/SKILL.md
• 기능 선택이 여전히 불명확한 경우에만 플랫폼 개요 -> ./cloudbase-platform/SKILL.md
• searchKnowledgeBase(mode="skill")을 사용하는 경우, 추측된 별칭이 아닌 postgresql-development-cloudbase 또는 minimal-web-baas-demo와 같은 참조 디렉토리 ID를 전달하세요.

수확량이 높은 가드레일

• 프론트엔드 코드를 작성하기 전에 백엔드 리소스를 준비하세요. 인증 제공자, 데이터베이스 테이블, 스토리지 도메인 및 보안 규칙에는 MCP를 우선 사용하십시오. 현재 세션에 MCP 도구가 없으면 다음 세션을 위해 MCP를 구성하고 지금은 tcb CLI를 사용하십시오 — 재시작을 기다리며 지체하지 마십시오. 존재하지 않는 리소스에 대해 작성된 프론트엔드 코드는 평가기 실패를 초래합니다.
• 변경 안전 프로토콜: 중요하지 않은 코드 또는 구성 변경 전에 반드시 cloudbase-platform/references/protocols/change-safety-protocol.md를 엄격히 따라야 합니다(영향 선언 → 사용자 확인 획득 → 변경 후 확인 → 동일 증상 3회 발생 후 근본 원인 분석으로 에스컬레이션).
• 배포 게이트: 배포, 게시, 사용자 정의 도메인, CloudRun 또는 공개 노출 작업 전에 cloudbase-platform/references/protocols/deployment-gate.md의 검사를 완료하고 필수 선언 템플릿을 제시해야 합니다.
• 동일한 경로가 2-3회 실패하면 재시도를 중단하고 경로를 변경하세요. 더 많은 코드를 편집하기 전에 플랫폼 스킬, 인증 도메인, 런타임 및 권한 모델을 확인하십시오.
• CloudBase 클라이언트를 초기화하거나 관리자 작업을 수행할 때 코드, 구성 및 명령 예제에서 항상 EnvId를 명시적으로 지정하십시오. 현재 CLI 선택 환경 또는 암시적 기본값에 의존하지 마십시오.
• 대화에 환경 별칭, 닉네임 또는 기타 약어만 제공된 경우 envQuery(action=list, alias=..., aliasExact=true)로 이를 확인하고 auth.set_env 호출, 콘솔 링크 생성 또는 구성/코드 작성 전에 반환된 정식 전체 EnvId를 사용하십시오. 별칭이 모호하거나 누락된 경우 중단하고 사용자에게 확인을 요청하십시오.

다음 용도로 사용하지 마십시오

• 코드를 건드리기 전에 모든 CloudBase 스킬을 읽는 이유.
• 기존 코드가 이미 스택과 누락된 부분을 드러낼 때 플랫폼 개요부터 시작하는 이유.

작업 규칙

1. BaaS 우선, 함수는 최후의 수단:

   • 최소 전후단 / Lovable 스타일 데모의 경우 먼저 ./minimal-web-baas-demo/SKILL.md로 라우팅하세요. 순서: 커넥터 준비 → 자격 증명 대기 중 템플릿 워밍업 → envQuery → 하나의 DB 잠금 → MCP 스키마 → @cloudbase/js-sdk CRUD → 미리보기. 기본 클라우드 함수 수 = 0.
   • 클라우드 함수 또는 CloudRun 서비스를 작성하기 전에 질문하세요: 올바른 JS SDK 표면이 이를 직접 처리할 수 있습니까? 확인된 NoSQL 컬렉션에만 db.collection(...).get()을 사용하고, CloudBase PG 테이블에는 app.rdb().from(...)을 사용하며, 해당 스킬의 auth/storage를 사용하십시오.
   • 데이터 읽기/쓰기, 파일 업로드, 실시간 업데이트, 리더보드, 목록, 집계를 포함한 간단한 쿼리에는 일치하는 JS SDK 표면을 직접 사용하십시오.
   • 로직이 데이터베이스 규칙/RLS로 표현할 수 없는 서버 측 권한 적용, 타사 서비스 호출(결제, SMS, 외부 API) 또는 사용자에 의해 트리거되지 않은 백그라운드 작업이 필요한 경우에만 클라우드 함수로 내려가십시오.
   • 영구 연결(WebSocket), 장기 실행 컴퓨팅 또는 사용자 정의 런타임이 진정으로 필요한 경우에만 CloudRun으로 내려가십시오.

2. TODO가 있는 기존 애플리케이션:

   • 이를 새 프로젝트 구축이 아닌 타겟 수리 작업으로 취급하십시오.
   • 현재 코드에서 작동하는 흐름까지 최단 경로를 선호하십시오.

3. 인증 작업:

   • 계정 식별자가 admin, editor 등 @ 없이 일반 사용자 이름인 경우 usernamePassword 로그인을 차단 전제 조건으로 취급하십시오.
   • 먼저 queryAppAuth(action="getLoginConfig")를 호출하십시오.
   • loginMethods.usernamePassword !== true인 경우 즉시 manageAppAuth(action="patchLoginStrategy", patch={ usernamePassword: true })를 호출하십시오.
   • 웹 로그인 코드에서 auth.signInWithPassword({ username, password })를 사용하십시오.
   • 모든 환경 또는 SDK 버전에서 직접 웹 auth.signUp({ username, password })를 사용할 수 있다고 가정하지 마십시오. 먼저 sdkHints / 설치된 SDK 동작을 확인하십시오. 사용자 이름 등록이 필요하고 직접 가입이 지원되지 않는 경우, 브라우저 코드에 비밀 키를 노출하지 않고 CloudBase Auth 사용자를 생성하는 백엔드 또는 관리 API 경로를 통해 등록을 라우팅하십시오.
   • 이러한 사용자 이름 스타일 계정 흐름에는 signUpWithEmailAndPassword 또는 signInWithEmailAndPassword를 절대 사용하지 마십시오.
   • 준비가 확인되면 활성 프론트엔드 핸들러로 돌아가 실제 로그인/등록 흐름을 완료하십시오.

4. 데이터베이스 및 스토리지 작업:

   • 병렬 SDK 래퍼를 만드는 대신 기존 공유 app, auth, db 및 스토리지 도우미를 재사용하십시오.
   • 작업에 CloudBase PG, PostgreSQL, Postgres, PG 모드, JS SDK v3 PostgreSQL, app.rdb(), queryPgDatabase, managePgDatabase, mysqldb OpenAPI 또는 RLS가 언급된 경우 데이터베이스 코드를 건드리기 전에 ./postgresql-development/SKILL.md를 읽으십시오.
   • CloudBase PG의 경우 스키마 및 관리를 위해 queryPgDatabase/managePgDatabase를 사용하십시오. PG 작업을 MySQL queryMysqlDatabase/manageMysqlDatabase 또는 NoSQL 컬렉션 API로 라우팅하지 마십시오.
   • OpenAPI 조회는 searchKnowledgeBase({ mode: "openapi", apiName: "mysqldb" })를 직접 호출하십시오. getApiDocs 또는 listEndpoints와 같은 추측된 action 값을 전달하지 마십시오. 이는 지원되는 도구 모드에 속하지 않습니다.
   • CloudBase PG 웹 CRUD의 경우 원시 HTTP보다 JS SDK v3 app.rdb() 및 문서화된 스토리지 app.storage.from() API를 선호하십시오.
   • 로컬 Vite/미리보기에서 브라우저 측 CloudBase 스토리지 업로드의 경우 먼저 보안 도메인에서 실제 브라우저 host:port를 확인하십시오(envQuery(action="domains") 후 누락된 경우 envDomainManagement(action="create")). 실패한 커버 업로드는 후속 PG 기사 삽입을 조용히 건너뛰어서는 안 됩니다.

• CloudBase Web SDK db.collection(...).add(...)의 경우 result._id에서 생성된 문서 ID를 유지하십시오.
• 쓰기의 경우 성공을 가정하지 말고 실제 SDK 결과를 검증하십시오.
• 레거시 API 중지 카드: 작업에 PostgreSQL, CloudBase PG, PG 모드, app.rdb(), queryPgDatabase, managePgDatabase, PostgREST 또는 RLS가 포함된 경우 기억에서 NoSQL 예제를 작성하지 마십시오. 웹 CRUD에는 app.rdb().from(...), 관리를 위해 queryPgDatabase/managePgDatabase, 웹 인증 가드에 auth.getSession()을 사용하십시오. PG/인증 기본값으로 app.database(), db.collection(...), .where(), .orderBy(), app.uploadFile(), getLoginState() 또는 auth.getUser()를 사용하지 마십시오.

5. 타겟 수리 작업:
   • 기능적 마무리가 탐색보다 우선합니다.
   • 광범위한 저장소 검색, UI 재설계 및 분리된 데모 코드를 피하십시오.
   • 파일 발견 범위를 좁게 유지하십시오. 전체 프로젝트에 걸친 Glob/광범위한 검색보다 알려진 활성 파일의 직접 읽기를 선호하십시오.