명령은 저장소 루트(folioo)에서 실행합니다.
에디터도 이 폴더를 워크스페이스로 열어 .vscode/settings.json을 적용합니다.
mise로 개발 도구를 관리합니다. macOS에서는 brew install mise로 설치할 수 있습니다.
| 도구 | 버전 |
|---|---|
| Node.js | 24.22.1 |
| pnpm | 10.33.0 |
| Python | 3.12.14 |
| uv | 0.11.7 |
정확한 설치 버전은 mise.toml이 기준입니다. Node 지원 범위와 pnpm 버전은 루트 package.json에도 명시합니다.
기존 mise 설정을 읽어 확인한 뒤 신뢰하고 설치합니다.
mise trust
mise install
mise exec -- pnpm install --frozen-lockfilemise install은 Python·uv도 설치하지만 AI의 Python 프로젝트 의존성 설치와 DB 준비는 별도입니다.
웹 개발과 공통 검사는 AI 서버·테스트 DB 없이 진행할 수 있습니다.
이 문서는 명령에 mise exec --를 명시합니다. zsh에서 자동 전환하려면 ~/.zshrc에
eval "$(mise activate zsh)"를 한 번 추가하고 새 터미널을 엽니다. 기존 nvm 초기화가 있다면 그 아래에 둡니다.
이후 저장소에서 node --version, pnpm --version으로 위 버전을 확인합니다.
다른 버전 관리 도구로 이 프로젝트의 버전을 별도로 변경하지 않습니다.
명령 (mise exec -- 뒤에 실행) |
범위·사전 조건 |
|---|---|
pnpm dev |
현재 웹 개발 서버와 선행 BUD 빌드. AI 서버 제외 |
pnpm build |
정의된 패키지 빌드. 현재 BUD·웹 |
pnpm check |
공통 포맷·공통 린트·웹 린트·타입 검사·빌드를 순서대로 실행. AI 전용 검사 제외 |
pnpm web:dev |
웹 개발 서버와 선행 BUD 빌드 |
pnpm web:lint |
웹의 Next.js·React·TypeScript 린트 |
pnpm web:check-types |
선행 의존성 빌드 후 웹 타입 검사 |
pnpm web:build |
선행 의존성 빌드 후 웹 프로덕션 빌드 |
pnpm web:start |
빌드된 웹 프로덕션 서버 실행 |
pnpm web:check |
웹 린트 → 타입 검사 → 빌드. 공통 포맷·린트와 AI 검사 제외 |
pnpm ai:setup |
AI 기본·개발 의존성 설치 |
pnpm ai:setup:local |
로컬 DB 실행 지원을 포함한 AI 의존성 설치 |
pnpm ai:dev |
로컬 DB 도구를 포함한 AI 서버. 환경 변수·DB 준비 필요 |
pnpm ai:dev:external |
외부 PostgreSQL을 사용하는 AI 서버. 환경 변수·DB 준비 필요 |
pnpm ai:check |
AI 린트·포맷·테스트. 전용 테스트 DB 등 준비 필요 |
pnpm api:setup |
서버 의존성 설치. 서버는 workspace 밖이라 루트 pnpm install에 포함되지 않음 |
pnpm api:dev |
서버 개발 서버(watch). api:setup과 apps/server/.env, DB 준비 필요 |
pnpm api:check |
서버 린트·포맷 검사·빌드·단위 테스트. api:setup 선행, DB 불필요 |
pnpm api:test:e2e |
서버 e2e 테스트. api:setup과 DB 준비 필요 |
pnpm check:all |
기존 공통·프론트·토큰 검사 성공 후 AI 전체 검사, 이어서 서버 전체 검사. 서버 의존성은 api:setup으로 먼저 설치 |
mise exec -- pnpm run web:devmise exec -- pnpm check린트 담당 범위는 다음과 같습니다.
- 루트
pnpm lint: 루트 설정·스크립트와 BUD 등 공통 JS/TS 코드.apps/web은 제외합니다. - 웹
pnpm web:lint:apps/web의 Next.js·React·TypeScript 코드. - AI
pnpm ai:lint: AI Python 코드의 Ruff 검사. - 서버
pnpm api:lint:apps/server의 NestJS·TypeScript 코드. 서버 자체 ESLint·Prettier 설정을 사용하고 루트 검사에서는 제외합니다.
CI의 repo job은 공통 포맷과 루트 린트를 담당합니다. 변경 영향에 따라 실행되는 web job은
웹 린트 → 타입 검사 → 빌드 순서를 유지합니다. 로컬 pnpm check도 웹 린트를 타입 검사·빌드보다 먼저 실행합니다.
api job은 서버 린트 → 포맷 검사 → 빌드 → 단위 테스트를 로컬과 같은 api:* 명령으로 실행하며, 운영 이미지와 같은 Node 20을 사용합니다.
AI 패키지가 Turbo의 scope에 표시되더라도 check-types·build 스크립트가 없는 AI 패키지의 테스트가 실행되는 것은 아닙니다.
AI 검증 완료 여부는 별도 ai:check 결과로 판단합니다.
현재 check는 기존 공통·프론트·토큰 검사 범위를 유지합니다. 웹만 검사하려면 pnpm run web:check를 사용합니다.
check:all은 check, ai:check, api:check를 순차 실행하며, web:check를 추가로 중복 실행하지 않습니다.
공통 검사는 Prettier·ESLint를 사용하고, AI Python 검사는 별도로 Ruff를 사용합니다.
후속으로 check에서 프론트 검사를 완전히 분리하고 check:all에서 공통 검사와 각 파트 검사를 취합할 예정입니다.
백엔드 api:* 명령은 pnpm -C apps/server로 서버 스크립트를 실행합니다. 서버는 pnpm workspace 밖에서 자체 lockfile을 쓰므로
루트 pnpm install 뒤에 pnpm api:setup을 따로 실행하고, Turbo 태스크와 --filter는 서버를 대상으로 하지 않습니다.
api:build·api:lint·api:format·api:format:check·api:test도 같은 방식으로 서버의 스크립트를 실행합니다.
명령 예시는 macOS·Linux의 sh/bash/zsh 기준입니다. Windows에서는 셸과 AI 로컬 DB 지원 여부를 확인하고, AI 환경 구성은 해당 문서를 따릅니다.
기본 브랜치는 dev이며 기능 작업 PR은 dev를 대상으로 엽니다. main 반영은 별도 배포·릴리스 흐름으로 관리합니다.
PR 본문은 템플릿의 Closes #이슈번호를 Draft 단계부터 작성하고, Ready for review 전 최종 변경 내용과 검증 결과를 갱신합니다.
Draft 작성이나 push만으로 이슈가 닫히지는 않습니다. 이슈 자동 종료 설정이 활성화된 상태에서 기본 브랜치 dev에 머지되면 종료됩니다.
CI의 ci-ok는 plan·repo와 실행 대상 파트의 결과를 취합합니다. 실패한 필수 job이나 예상하지 못한 skip을 성공으로 처리하지 않습니다.
병합 차단은 워크플로 파일만으로 적용되지 않으므로 GitHub Ruleset의 Require status checks to pass에 ci-ok를 필수 체크로 등록해야 합니다.
dev·main은 각각 명시적인 브랜치 대상으로 설정합니다. main 보호가 목적이라면 기본 브랜치를 뜻하는 ~DEFAULT_BRANCH를 사용하지 않습니다.