CLAUDE.md — 이 프로젝트에서 Claude Code가 따라야 할 규약

너는 사내 개발 워크스페이스에서 동작하는 코딩 에이전트다. 이 프로젝트는 Node(ESM) 앱이고, 로컬 개발/테스트는 워크스페이스에서 직접 node 실행, 배포는 Kubero(Gitea push → buildpack 자동빌드) 로 한다.

절대 규칙

비밀값을 코드/커밋에 넣지 마라. DB·MinIO 자격증명은 항상 환경변수에서만 읽는다. 값은 프로젝트의 .project-env 에 있고(프로젝트 폴더 cd 시 셸이 자동 export), 이 파일은 절대 커밋 금지(.gitignore에 있음). 참고용 예시는 .project-env.example.
운영 배포를 직접 하지 마라. 배포는 git push → Kubero가 담당한다. 너는 코드만 책임진다.
진입점은 루트의 index.js 다(Kubero buildpack 의 run = node index.js). 서버 구현은 src/server.js, index.js 는 그것을 로드하기만 한다. 진입 파일 구조를 바꾸지 마라(바꾸면 Kubero 배포가 안 뜬다).

외부 연결 (프로젝트 `.project-env` 에서 env로 주입됨)

Postgres: DATABASE_URL (직원 전용 schema로 격리, search_path 고정). 코드는 src/db.js를 통해 접근. DB는 클러스터 내부 OpenEverest(postgresql-6ox)의 appdb 다.
MinIO(S3): API endpoint https://minio.bokdev.in (콘솔 minioc가 아님), 버킷 coolify-user-data. 키는 .project-env의 S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY. 코드는 src/s3.js를 통해 접근.
LiteLLM: AI 호출은 사내 gateway(https://litellm.bok.or.kr) 경유. virtual key는 워크스페이스 전역인 ~/.env(LITELLM_KEY)에서 관리 — update-litellm-key 명령으로 입력. (프로젝트 설정 아님)

로컬 개발 워크플로 (컨테이너 빌드 불필요)

# 이 폴더는 new-project 로 만들어졌고 .project-env(DB/S3)가 이미 채워져 있다.
# 폴더에 들어와 있으면 셸이 .project-env 를 자동 export 한 상태다($DATABASE_URL 등 사용 가능).
npm install
npm run dev                 # node --watch 로 핫리로드, http://localhost:3000

# 배포(Kubero)와 "동일한 방식"으로 한 번 돌려보기 — 이게 가장 정확한 사전 검증이다.
npm start                   # = node index.js (Kubero 의 run 커맨드와 동일)

Kubero buildpack 은 Dockerfile 을 쓰지 않는다. 로컬에서 컨테이너 이미지를 빌드할 필요가 없다. Kubero 가 결국 npm install → node index.js 만 하므로, 위 npm start 가 통과하면 배포도 거의 그대로 된다.

연결 확인: npm run db:check, npm run minio:check, 또는 /db /s3 엔드포인트.

배포 워크플로 (Kubero)

Gitea repo에 push (main 등 배포 브랜치).
Kubero(https://kubero.bokdev.in)가 이 repo를 받아 NodeJS buildpack으로 자동 빌드/배포한다 (build=npm install, run=node index.js, Node 22). Dockerfile 은 쓰지 않는다.
Kubero 앱의 Environment Variables 에 DATABASE_URL, S3_*, PORT 를 채운다(로컬 .project-env와 같은 키).
포트는 3000(PORT). 앱 주소는 https://<앱이름>.apps.bokdev.in.

코드 규약

ESM(import/export), Node 22+. 외부 연결정보는 반드시 src/config.js 한 곳을 거친다.
새 외부 의존성을 추가하면 package.json에 반영하고 npm install로 lock 갱신.
변경 후에는 npm run db:check / npm run minio:check로 연결이 살아있는지 스스로 확인하라.

3.5 KiB Raw Permalink Blame History