sample/CLAUDE.md

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

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

절대 규칙

• 비밀값을 코드/커밋에 넣지 마라. DB·MinIO 자격증명은 항상 환경변수(.env, 워크스페이스 env)에서만 읽는다. .env 는 절대 커밋하지 않는다(.gitignore에 있음). 새 비밀 키가 필요하면 .env.example 에 placeholder만 추가.
• 컨테이너는 docker 명령으로 실행해도 되지만 실제 런타임은 rootless podman이다(docker는 podman 별칭).
• 운영 배포를 직접 하지 마라. 배포는 git push → Coolify가 담당한다. 너는 코드/Dockerfile만 책임진다.

외부 연결 (이미 워크스페이스 env로 주입됨)

• Postgres: DATABASE_URL (직원 전용 schema로 격리, search_path 고정). 코드는 src/db.js를 통해 접근.
• MinIO(S3): API endpoint https://minio.bokdev.in (콘솔 minioc가 아님), 버킷 coolify-user-data. 키는 직원이 .env의 S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY에 채운다. 코드는 src/s3.js를 통해 접근.
• LiteLLM: AI 호출은 ~/.config/litellm/key 의 virtual key를 쓰는 사내 gateway(https://litellm.bok.or.kr)를 경유.

로컬 개발 워크플로 (podman)

npm install
cp .env.example .env        # 그리고 MinIO 키 등 채우기 (DB는 자동주입이면 비워둬도 됨)
npm run dev                 # node --watch 로 핫리로드, http://localhost:3000

# 컨테이너로 동일하게 돌려보기
podman build -t starter .
podman run --rm -p 3000:3000 --env-file .env \
  -e DATABASE_URL="$DATABASE_URL" starter
# 또는
podman compose up --build

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

배포 워크플로 (Coolify)

1. Gitea repo에 push (main 등 배포 브랜치).
2. Coolify가 이 Dockerfile로 자동 빌드/배포한다(로컬 podman 빌드와 동일 Dockerfile).
3. Coolify 쪽 Environment Variables 에 DATABASE_URL, S3_* 를 채운다(로컬 .env와 같은 키).
4. 포트는 컨테이너 3000. Coolify에서 도메인/포트 매핑.

코드 규약

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