개발 참여

Multica 로컬 개발 환경을 설정하고 테스트를 실행하며 저장소 규칙에 따라 변경 사항을 제출합니다.

Multica는 Go backend와 pnpm monorepo로 구성됩니다. 로컬에서 시작하는 가장 간단한 방법은 make dev입니다. 현재 checkout의 환경, 데이터베이스, migration을 준비한 뒤 Web과 API를 시작합니다.

환경 요구 사항

Node.js 22
pnpm 10.28.2
Go 1.26.1
Docker Engine 또는 Docker Desktop
Git과 Make

버전은 루트 package.json, server/go.mod, CI workflow를 기준으로 확인합니다.

처음 시작

git clone https://github.com/multica-ai/multica.git
cd multica
make dev

기본 checkout은 .env를 사용합니다. 파일이 없으면 make dev가 .env.example에서 만들고 공유 PostgreSQL을 시작한 뒤 의존성을 설치하고 migration을 실행해 API와 Web을 시작합니다.

기본 주소:

Web: http://localhost:3000
API: http://localhost:8080

로컬 고정 인증 코드는 개발 환경 설정에서 가져옵니다. 로컬 .env를 공개 인터넷 배포에 사용하지 마세요.

worktree에서 개발

저장소는 기본 checkout과 여러 worktree를 동시에 실행할 수 있습니다. 하나의 PostgreSQL 컨테이너를 공유하지만 서로 다른 데이터베이스와 port를 사용합니다.

git worktree add ../multica-feature -b feat/my-change main
cd ../multica-feature
make setup-worktree
make start-worktree

make setup-worktree는 .env.worktree를 만들고 경로를 기준으로 데이터베이스 이름과 port를 정합니다. 다시 시작하려면 다음을 실행합니다.

make start-worktree

현재 worktree의 Web과 API를 중지하려면 다음을 실행합니다.

make stop-worktree

make dev를 바로 실행할 수도 있습니다. 스크립트가 .git 파일을 통해 worktree를 감지하고 .env.worktree를 선택합니다.

worktree는 PostgreSQL 컨테이너만 공유하며 데이터베이스는 공유하지 않습니다. worktree마다 새 Compose project를 시작하지 마세요. 먼저 .env.worktree의 POSTGRES_DB, PORT, FRONTEND_PORT를 확인하세요.

자주 사용하는 명령

전체 절차

make dev              # 현재 checkout 준비 및 시작
make start            # 기존 환경으로 API와 Web 시작
make stop             # 현재 checkout의 프로세스 중지
make check            # 전체 로컬 검증 절차 실행
make build            # server, CLI, migrate binary 빌드

프런트엔드

pnpm install
pnpm dev:web
pnpm dev:desktop
pnpm build
pnpm typecheck
pnpm lint
pnpm test

루트 명령은 기본적으로 Mobile을 제외합니다. Mobile에는 별도 스크립트와 CI가 있으므로 변경하기 전에 apps/mobile/CLAUDE.md를 읽으세요.

Backend

make server
make daemon
make test
make migrate-up
make migrate-down
make sqlc

소스에서 CLI 명령을 실행하려면 다음을 사용합니다.

make cli ARGS="issue list"

프런트엔드 기능 변경

Web과 Desktop에 모두 필요한 기능은 역할에 따라 배치합니다.

API 유형, query, mutation, 플랫폼 독립 로직은 packages/core/에 둡니다.
기본 UI는 packages/ui/에 두며 비즈니스 코드에 의존하면 안 됩니다.
비즈니스 페이지와 컴포넌트는 packages/views/에 둡니다.
Next.js, Electron, 라우팅 adapter는 해당 app에 남깁니다.
공유 페이지는 Web과 Desktop 양쪽에 연결합니다.

서버 데이터는 TanStack Query가 관리하고 필터, 초안, 레이아웃 같은 클라이언트 상태는 Zustand가 관리합니다. 구체적인 경계는 프로젝트 아키텍처와 루트 CLAUDE.md를 참고하세요.

API를 추가하거나 변경하면 packages/core/api/의 zod schema도 업데이트하고 누락된 필드, 알 수 없는 enum, 잘못된 형식에 대한 parsing 테스트를 추가해야 합니다.

데이터베이스 변경

Migration은 server/migrations/에 있고 query는 server/pkg/db/queries/에 있습니다.

다음 사용하지 않은 숫자 접두사를 사용해 .up.sql과 .down.sql을 모두 만듭니다.
데이터베이스 foreign key, cascade delete, cascade update를 추가하지 않습니다. 관계 검사와 정리는 애플리케이션 계층에서 수행합니다.
모든 새 index는 CREATE INDEX CONCURRENTLY 또는 CREATE UNIQUE INDEX CONCURRENTLY를 사용합니다.
concurrent index 하나는 해당 문장만 포함한 별도 migration 파일에 둡니다.
query를 수정한 뒤 make sqlc를 실행하고 생성된 server/pkg/db/generated/ 변경 사항을 commit합니다.
sqlc 생성 파일을 직접 수정하지 않습니다.

여러 쓰기 작업이 함께 성공하거나 rollback되어야 하면 service 계층에서 애플리케이션 transaction을 사용합니다.

테스트 위치

변경	테스트 위치
공유 비즈니스 로직, query, store	`packages/core/*.test.ts`
공유 페이지와 컴포넌트	`packages/views/*.test.tsx`
Web 또는 Desktop 플랫폼 wiring	해당 `apps/*` 디렉터리
end-to-end 흐름	`e2e/*.spec.ts`
Backend	관련 Go package의 `*_test.go`

변경 사항과 가장 가까운 검사를 먼저 실행한 뒤 범위를 넓히세요. Docs만 변경한 경우:

pnpm --filter @multica/docs typecheck

공유 프런트엔드 변경:

pnpm typecheck
pnpm test

Backend 변경:

make test

제출 전:

make check

make check는 TypeScript typecheck와 단위 테스트, Go 테스트, Playwright E2E를 실행합니다. CI는 변경 범위에 따라 build와 lint를 수행하고 플랫폼 또는 installer 전용 테스트도 실행합니다.

현재 개발 데이터베이스 초기화

깨끗한 데이터가 필요하면 현재 checkout의 환경 파일에 지정된 데이터베이스를 초기화할 수 있습니다.

make stop
make db-reset
make start

make db-reset은 현재 POSTGRES_DB를 삭제하고 다시 만들며 원격 데이터베이스 연결을 거부합니다. 실행 전에 .env 또는 .env.worktree를 확인해 대상 데이터베이스가 맞는지 확인하세요.

제출 전 확인

루트 CLAUDE.md와 관련 하위 디렉터리 안내를 읽습니다.
현재 태스크에 필요한 범위만 변경합니다.
코드 주석은 영어로 작성합니다.
.env, token, 빌드 결과물, 로컬 경로를 commit하지 않습니다.
feat(scope), fix(scope), docs 같은 conventional commit을 사용합니다.
PR에 동작 변경과 실제 실행한 검증 명령을 작성합니다.

다음 단계

개발 규칙 — 이름, 용어, 중국어 문구에 관한 저장소 규칙을 확인합니다.
프로젝트 아키텍처 — 계층, 공유 패키지, 한 번의 실행 코드 경로를 알아봅니다.

이 페이지에서