Files

infra 499e48f2e2 refactor: .project-env 일원화 + starter→sample 리네임

- 프로젝트 설정을 .project-env 로 통일(셸 cd 시 자동 export, 앱은 process.env 사용)
- .env.example → .project-env.example, .gitignore/.dockerignore 에 .project-env 추가
- new-project 복사 흐름 기준으로 README/CLAUDE/MANUAL 갱신
- LiteLLM 키는 ~/.env(update-litellm-key)로 분리 안내

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-14 19:10:14 +09:00

2.9 KiB

Raw Blame History

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

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

절대 규칙

비밀값을 코드/커밋에 넣지 마라. DB·MinIO 자격증명은 항상 환경변수에서만 읽는다. 값은 프로젝트의 .project-env 에 있고(프로젝트 폴더 cd 시 셸이 자동 export), 이 파일은 절대 커밋 금지(.gitignore에 있음). 참고용 예시는 .project-env.example.
컨테이너는 docker 명령으로 실행해도 되지만 실제 런타임은 rootless podman이다(docker는 podman 별칭).
운영 배포를 직접 하지 마라. 배포는 git push → Coolify가 담당한다. 너는 코드/Dockerfile만 책임진다.

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

Postgres: DATABASE_URL (직원 전용 schema로 격리, search_path 고정). 코드는 src/db.js를 통해 접근.
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 명령으로 입력. (프로젝트 설정 아님)

로컬 개발 워크플로 (podman)

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

# 컨테이너로 동일하게 돌려보기
podman build -t sample .
podman run --rm -p 3000:3000 --env-file .project-env sample
# 또는
podman compose up --build

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

배포 워크플로 (Coolify)

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

코드 규약

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

2.9 KiB Raw Blame History