AI 작업 지침

AI가 Cake20 코드를 정확하게 수정하기 위해 따라야 하는 순서입니다.

권장 작업 순서

항상 get_guide를 가장 먼저 실행합니다.
편집 전 git_status로 작업 트리를 확인하고 기존 변경을 덮어쓰지 않습니다.
첫 변경 직전에 begin_work로 실제 AI·모델 이름과 작업 내용을 밝히고 수정 중 상태를 기록합니다. 미완료 상태가 있으면 새 작업으로 교체합니다.
begin_work 성공 후 finish_work 전까지 매 3분 구간에 Cake20 MCP 요청이 하나라도 있으면 작업 중입니다. 일반 MCP 요청·알림과 ping 중 하나면 충분하며, 요청을 주고받거나 실행 중이면 별도 ping 없이 3분을 다시 계산합니다. 그 외에만 AI가 ping 도구를 직접 호출합니다. 오래 생각하거나 계획·대기할 것으로 판단하면 시작 전에 ping을 보내고, 무신호 상태가 계속되면 3분마다 반복합니다. HTTP keep-alive·열린 연결·로컬 작업은 활동이 아닙니다.
외부 API, 메일, CORS, 도메인 또는 실행 제한이 필요하면 get_settings를 먼저 읽고 사용자가 요청한 값만 update_settings로 변경합니다.
list_files로 현재 구조를 확인하고 관련 파일을 모두 읽습니다.
기존 텍스트 파일은 수정 직전에 read_file로 다시 읽고 전체 내용을 write_file로 저장해 다른 변경을 보존합니다.
기존 바이너리는 전체 base64 내용으로 write_asset에서 교체하고, 여러 새 이미지와 폰트는 upload_files에 전달합니다.
MCP 파일 도구는 파일당 2MB까지 사용합니다. 더 큰 정적 리소스가 꼭 필요하면 사용자에게 정확한 대상 경로를 알려 에디터의 로컬에서 업로드를 요청하고, 완료 후 list_files로 경로만 확인합니다.
샘플 데이터는 list_tables와 read_table로 구조를 확인한 뒤 insert_rows로 추가합니다.
기존 데이터는 read_table로 확인한 기본 키를 사용해 update_rows로 수정합니다.
삭제는 사용자가 명시적으로 요청한 행만 delete_rows로 처리합니다.
복잡한 조회는 query_db, 스키마와 데이터 변경은 execute_db를 사용합니다.
사용자가 요청하지 않았다면 DB 구조와 데이터를 임의로 변경하지 않습니다.
DB·Redis는 에디터·검수·운영이 공유합니다. target: test와 target: production은 같은 데이터를 가리키는 호환 별칭입니다.
공유 데이터 수정은 현재 사용자 요청에서 지정한 대상과 범위 안에서만 실행하며 별도 승인 창이나 반복 확인을 요구하지 않습니다.
삭제와 넓은 데이터 변경은 현재 요청이 정확히 그 작업을 포함할 때만 실행합니다.
DB 쓰기는 release를 멈추지 않고 직전 백업을 만들며 실패하면 자동 복구합니다. 스키마 변경이나 넓은 데이터 수정 전에는 create_site_backup으로 별도 복구 지점을 만듭니다.
레디스 변경 전 list_redis와 query_redis로 대상 키와 현재 값을 확인합니다.
사용자가 요청한 키만 execute_redis로 변경하고 전체 삭제는 clear_redis를 사용합니다.
사용자가 요청하지 않았다면 레디스 값, TTL과 로그인 세션을 임의로 변경하지 않습니다.
소스를 확인해 자체 API, 파일 저장소, Task, Queue, WebSocket, SSE, DB 또는 그 밖의 server 실행 코드가 없으면 package.json에 mode: "static"을 명시합니다. 서버 기능을 추가하면 mode: "fullstack"으로 변경합니다. mode 생략과 빈 값은 auto이지만, 정적임을 확인한 사이트를 auto로 남기지 않습니다.
실행 중인 웹사이트는 소스를 읽고 수정하고 저장하는 동안 중지하지 않습니다.
Cake20 View의 Cake20 UI 컴포넌트는 U 접두어 없이 Card, Button, Input처럼 작성합니다.
Cake20 View TSX에서는 class, bind, onClick 같은 직관적인 속성을 사용합니다.
페이지와 레이아웃에는 라우팅, 데이터 연결과 화면 조합만 두고, 독립적인 섹션·목록·폼·모달과 반복 UI는 app/components의 책임별 Cake20 View 컴포넌트로 분리합니다. 큰 TSX 파일 하나에 UI와 로직을 몰아넣지 않습니다.
템플릿도 일회용 데모가 아니라 다운로드 후 학습하고 계속 수정할 수 있는 운영 소스로 작성하며 같은 코드 분리 기준을 적용합니다.
API 파일은 입력 검증, 권한 확인과 응답 연결에 집중하고, 공유 순수 함수와 타입은 shared/utils와 shared/types로 분리합니다.
app, server, shared의 직계 폴더는 Cake20 표준 목록만 사용합니다. 허용된 직계 폴더 안에서는 필요한 깊이의 폴더로 정리하며, 폴더 이름은 컴포넌트 이름이나 URL 경로에 반영됩니다.
로그인과 Role 기반 1차 접근은 package.json auth에 페이지와 실제 /api 경로를 각각 선언합니다. app/middleware는 인증 외의 특수한 클라이언트 이동 조건에만 사용합니다.
app/types·utils는 화면에서만, server/types·utils는 서버에서만 자동 import합니다. shared/types·utils는 양쪽에서 전역 자동 import하며 공통 타입과 순수 함수는 shared에 둡니다.
API에 config.filter를 만들면 유효한 config.sample도 함께 작성합니다.
server/hooks의 *.hook.ts는 default async 함수로 내보냅니다.
DB schema는 server/db/*.db.ts에서 export const Name = {...} 객체로 작성하고 scalar, 배열, enum, 관계와 네이티브 타입을 z 메서드로 선언합니다. Cake20이 객체를 내부적으로 z.model()로 감쌉니다.
날짜 네이티브 타입은 정밀도 0일 때 문자열 db 이름 대신 timestamp() 또는 timestampTz()를 사용합니다. 1부터 6만 숫자를 전달하며 기존 (0)과 db(name, ...args)도 호환됩니다.
DB 테이블은 원칙적으로 테이블마다 server/db/<name>.db.ts 파일을 하나씩 만듭니다. 관계 모델도 z.ref로 파일 사이에서 참조하며 한 파일에 여러 테이블을 몰아넣지 않습니다.
DB 모델과 함수가 많으면 server/db 아래에서 필요한 깊이의 폴더로 정리할 수 있습니다.
Cake20은 *.db.ts를 숨겨진 .prisma로 변환하며 기존 Prisma-only 웹사이트에는 *.db.ts를 자동 생성합니다.
초기 데이터와 Preview 샘플은 각 *.db.ts의 seed에서 row로 반환합니다. Cake20은 신규·변경된 seed를 최신 스키마로 검사한 뒤 upsert합니다.
재사용 DB 함수는 server/db 아래의 *.sql.ts에 named 함수로 작성하고 서버 어디서든 db.sql.<함수명>()으로 호출합니다.
generator와 datasource는 Cake20이 관리하므로 웹사이트 DB 파일에는 선언하지 않습니다.
public/privacy-policy.html과 public/terms-of-service.html은 영문 기본 문서입니다. 실제 운영자와 데이터 처리 내용으로 모든 표시 항목을 수정하고 홈페이지에서 두 공개 URL을 링크합니다.
DB의 모든 nullable scalar ? 필드는 "", undefined, null을 DB NULL 하나로 처리하고 검색에도 일반 null 하나만 사용합니다.
필수 Json의 빈 값은 {}, Json?의 빈 값은 DB NULL입니다. Json?의 {}는 NULL과 구분되는 실제 JSON 값입니다.
update에서 undefined가 들어 있는 키는 NULL로 지워집니다. 기존 값을 유지하려면 해당 키 자체를 data에서 생략합니다.
단일 필드 index는 z.string().index()처럼 작성합니다. 복합·고급 index는 모델 attr("@@index([...])")을 사용합니다.
build, node_modules, tmp와 .cake 같은 시스템 생성 경로를 수정하지 않습니다.
모든 파일 저장 후 git_diff를 검토하고 git_commit을 작업당 한 번 호출합니다.
모든 저장이 끝나면 beta_service를 호출해 검수합니다.
UI도 기본적으로 소스, 대상 테스트, check_readiness, request_service와 로그로 검증합니다. Preview 이미지 도구는 사용자가 현재 요청에서 화면 캡처나 시각 확인을 명시한 경우에만 사용합니다.
request_service로 루트 HTML과 변경한 API를 실제 호출합니다. 로그인 응답의 set-cookie는 다음 인증 요청의 cookie header로 전달합니다.
사용자가 배포를 명시하지 않았다면 검수 주소와 결과를 안내하고 종료합니다. 최종 운영 적용은 사람이 수행합니다.
사용자가 배포·게시·운영 적용까지 명시한 경우에만 publish_service를 호출하고 check_service로 운영 상태를 확인합니다.
BUILD_FAILED, 요청 오류, 시작 실패 또는 task 문제는 get_logs로 확인합니다.
running과 reachable이 모두 true인지 확인한 뒤 finish_work로 수정 상태를 마치고 완료를 보고합니다.

사용자에게 보고할 내용

수정하거나 생성한 파일
API URL과 입력 형식
DB model 변경 여부
빌드 성공 여부와 남은 수동 작업
이미지는 사용자가 현재 요청에서 명시적으로 요구한 경우에만 첨부