TL;DR
•
MacBook에서만 사용하던 Codex 개발 환경을 Mac mini에도 구축하는 과정에서 pnpm dev가 실행되지 않는 문제를 만났다.
•
원인은 pnpm 11의 dependency build approval 정책이었고, pnpm 버전 고정과 allowBuilds 설정으로 해결했다.
•
추가로 next-env.d.ts가 Next.js가 생성하는 파일이라는 점을 다시 확인했고, Git Worktree를 사용하면 AI 에이전트별 작업 공간을 분리할 수 있다는 점도 정리하게 됐다.
최근까지는 MacBook Pro에서만 Codex를 사용해 개발했다.
그런데 AI 에이전트가 코드 생성, 테스트 실행, 빌드 검증을 반복하다 보니 생각보다 리소스를 많이 사용했다. 집에 항상 켜져 있는 Mac mini가 있으니 여기에 동일한 개발 환경을 구축해두고 원격으로 작업하는 편이 낫겠다고 생각했다.
작업 자체는 특별할 것이 없었다.
저장소를 새로 clone하고 의존성을 설치한 뒤 개발 서버를 실행하면 된다.
git clone ...
pnpm install
pnpm dev그런데 pnpm dev 단계에서 바로 실패했다.
맥북에서는 정상 동작하는 프로젝트였기 때문에 환경 차이를 먼저 확인하기 시작했다.
확인한 내용은 다음과 같다.
•
맥북과 맥미니의 pnpm 버전 차이
•
개발 서버와 로컬 환경의 차이
•
최근 pnpm 정책 변경 여부
•
프로젝트 설정 누락 여부
•
Git에 포함된 생성 파일들
원인: pnpm 11의 Build Approval 정책
로그를 확인해보니 Next.js나 애플리케이션 코드가 실행되기 전에 pnpm 단계에서 실패하고 있었다.
에러는 다음과 같았다.
ERR_PNPM_IGNORED_BUILDS조사해보니 pnpm 11부터 dependency build script 실행 정책이 더 엄격해졌다.
pnpm 10에서는 별다른 설정 없이 지나가던 패키지들이 pnpm 11에서는 명시적으로 허용되어 있어야 했다.
프로젝트마다 개발자 환경이 달라질 수 있으므로 pnpm 버전을 고정했다.
{
"packageManager": "pnpm@11.6.0"
}그리고 필요한 패키지만 build script를 실행할 수 있도록 설정했다.
allowBuilds:
'@carbon/react': true
'@carbon/icons-react': true
'@ibm/plex': true
'@parcel/watcher': true
sharp: true
unrs-resolver: true전체 허용 옵션도 있었지만 사용하지 않았다.
새로운 dependency가 추가될 때마다 어떤 build script가 실행되는지 확인할 수 있는 편이 관리하기 쉽다고 판단했다.
설정 후 아래 항목들을 확인했다.
pnpm install --frozen-lockfile
pnpm dev
pnpm build
pnpm test
pnpm lint모두 정상 동작했다.
next-env.d.ts는 Git에 포함해야 할까?
문제를 확인하는 과정에서 next-env.d.ts 변경도 발견했다.
원래는 다음과 같았다.
import "./.next/types/routes.d.ts";그런데 실행 후에는 아래처럼 변경되어 있었다.
import "./.next/dev/types/routes.d.ts";처음에는 누군가 수정한 파일인 줄 알았는데 확인해보니 Next.js가 자동 생성하는 파일이었다.
next dev, next build, next typegen 과정에서 환경에 맞게 다시 생성된다.
사람이 직접 수정하는 파일도 아니고 환경에 따라 내용이 달라질 수 있기 때문에 Git 추적 대상에서 제외했다.
브랜치만 나눠도 작업은 분리된다고 생각했었다
이번 작업을 하면서 Git Worktree도 다시 정리하게 됐다.
평소에는 기능마다 브랜치를 만들어 사용했다.
git checkout -b feature-a
git checkout -b feature-b브랜치를 나눴으니 작업도 분리된다고 생각하기 쉽다.
그런데 실제로는 작업 폴더는 그대로다.
같은 디렉터리에서 브랜치만 바꿔가며 작업하면 아래 항목들을 계속 공유한다.
•
node_modules
•
.next
•
생성 파일
•
임시 파일
•
개발 서버 상태
혼자 순차적으로 작업할 때는 큰 문제가 없다.
하지만 Codex나 Claude Code 같은 AI 에이전트를 여러 개 돌리기 시작하면 상황이 달라진다.
예를 들어
•
UI 수정
•
백엔드 API 수정
•
테스트 코드 작성
을 각각 다른 에이전트에게 맡긴다고 가정해보자.
브랜치만 다르고 같은 워크트리를 사용하면 생성 파일이나 임시 파일이 서로 섞일 수 있다.
개발 서버를 실행하면서 생성된 변경 사항이 의도하지 않은 diff로 남는 경우도 있다.
Worktree를 사용하면
Worktree는 같은 저장소를 여러 작업 폴더에 펼쳐놓는 기능이다.
예를 들어
git worktree add ../dds-web-pnpm-fix -b fix/pnpm-build-approvals
git worktree add ../dds-web-ui -b feature/some-ui-work를 실행하면 다음과 같이 된다.
dds-web/
dds-web-pnpm-fix/
dds-web-ui/각 폴더는 독립적으로 작업할 수 있다.
•
각자 개발 서버 실행 가능
•
각자 .next 보유
•
각자 변경 사항 관리
•
각자 다른 브랜치 사용 가능
Git 히스토리는 공유하지만 작업 디렉터리는 분리된다.
AI 에이전트를 병렬로 사용하는 경우라면 브랜치만 만드는 것보다 Worktree를 만드는 편이 훨씬 안전하다.
정리
이번 작업은 원래 맥미니에 Codex 개발 환경을 복제하는 과정에서 시작됐다.
직접 수정한 내용은 pnpm 설정과 Next.js 생성 파일 정리 정도였지만, 작업하면서 Git Worktree를 다시 살펴보게 됐다.
예전에는 새로운 작업이 생기면 브랜치부터 만들었다.
요즘처럼 여러 AI 에이전트를 동시에 사용하는 환경에서는 작업 단위별로 Worktree를 따로 만드는 편이 더 잘 맞는 것 같다.
특히 개발 서버를 실행하거나 빌드 결과물이 많이 생성되는 프로젝트라면 차이가 꽤 크다.
