서론

Cursor / Claude Code / Codex와 같은 AI 코딩 어시스턴트가 일상적으로 작업을 수행하는 시대가 되면서, 개발의 "정답"이 바뀌고 있습니다.

몇 년 전까지만 해도 개발 환경 구축은 "README를 보며 반나절 동안 직접 손을 움직여야 하는 의식"이었습니다. 이제는 AI가 명령어를 입력하고, 의존성을 설치하며, 서버를 실행하고, 테스트를 작성하고, 커밋까지 하는 시대입니다. 인간이 만지기 전에 AI가 먼저 만지는 환경이 되어가고 있습니다.

이러한 전제를 바탕으로 하면, 개발 환경에 요구되는 요건은 크게 변합니다.

환경 차이 제로 (Zero Environment Difference): AI가 입력한 명령어가 로컬에서도 CI에서도 동일한 결과를 낸다 -
명령어의 일관성: AI가 학습하기 쉽도록 모든 명령어가 동일한 인터페이스로 PATH 상에 존재한다 -
자기 복구성 (Self-healing): 의존성이 깨지면 자동으로 복구된다 (AI에게 매번 절차를 가르칠 필요가 없다) -
관측 가능성 (Observability): AI가 폭주하더라도 로그와 프로세스 상태를 인간이 언제든 옆에서 확인할 수 있다 -
AI 가드레일 (AI Guardrails): 프로젝트 규약 및 베스트 프랙티스를 AI에게 주입하는 메커니즘이 내장되어 있다

이 모든 것을 충족하는 답이 바로 devenv였습니다. 본 기사에서는 Next.js 16 + Expo 55 + FastAPI + Supabase + Drizzle ORM의 풀스택 모노레포(Monorepo)를 devenv 2.0으로 구축한 실례를 바탕으로, Vibe Coding 시대에 효과적인 개발 환경을 만드는 방법을 해설합니다.

대상 독자: 모노레포·풀스택 개발에 참여하며 AI 코딩 어시스턴트를 일상적으로 사용하는 엔지니어

동작 환경: macOS / Linux / WSL2, Docker Desktop, Nix, devenv 1.7+

왜 devenv인가

개발 환경 도구의 선택지를 정리해 보면, 각각이 해결하고자 하는 과제가 다릅니다.

특히 Vibe Coding 맥락에서 효과적인 점은 "호스트 OS의 쉘에서 순수 명령어로 전부 실행할 수 있다"는 점입니다. Docker 컨테이너 안에 있으면 AI 에이전트가 실행하는 npm run dev가 컨테이너 내부 쉘인지 호스트인지에 따라 차이가 발생할 수 있지만, devenv는 cd를 하는 순간 호스트 쉘의 PATH를 전환할 뿐이므로, **AI가 실행하는 명령어의 실행 컨텍스트가 항상 유일(Unique)**하게 유지됩니다.

devenv란 무엇인가

devenv는 Nix 기반의 선언적 개발 환경 도구입니다. devenv.nix 파일 하나에 다음 사항을 모두 기술할 수 있습니다.

languages: 런타임(Node.js / Python / Deno 등)과 그 버전 -
packages: CLI 도구(supabase-cli, maestro 등) -
processes: 상주 서비스(dev server, backend 등) -
tasks: 의존성 그래프가 포함된 배치 명령어(migration, build 등) -
scripts: PATH에 직접 연결되는 단발성 스크립트 -
profiles: 환경별 env 전환(local / dev / staging / production) -
git-hooks: pre-commit hook 선언 -
enterShell/enterTest: 환경 진입 시의 hook

devenv.lock을 통해 모든 패키지의 해시(Hash)가 고정되므로, 팀 멤버와 CI 러너 모두가 동일한 바이너리를 사용할 수 있습니다. asdf의 .tool-versions...

와 달리, Node.js를 설치하는 Nix derivation의 해시까지 고정되어 있으므로 "같은 Node 22.x라도 패치가 달라서 동작하지 않는" 식의 사고가 발생하지 않습니다.

devenv의 주요 기능과 구성 패턴

devenv.nix에서 다루는 구성 요소는 8가지로 정리할 수 있습니다. 스택이 무엇이든(Node / Python / Go / Rust / 어떤 조합이든), 이 8가지 구성 방법만 파악하면 응용이 가능합니다.

지금부터 순서대로 "최소한의 코드로 패턴을 보여주는" 스타일로 소개하겠습니다. 구체적인 예시는 풀스택 모노레포(Full-stack Monorepo, 프론트 + 백 + DB + Edge Functions)를 상정하지만, 동일한 구조는 어떤 스택에도 적용할 수 있습니다.

0. 프로젝트의 최소 구성

your-project/
├── devenv.nix # 개발 환경의 모든 선언
├── devenv.yaml # 입력 소스 정의 (nixpkgs 등)
...

.envrc는 단 2줄뿐입니다.

#!/usr/bin/env bash
eval "$(devenv direnvrc)"
use devenv

cd your-project를 하는 순간 direnv가 devenv를 실행하며, 선언된 런타임과 CLI 도구가 PATH에 정렬됩니다. 로컬 개발의 기점은 이 단 한 번의 액션이 됩니다.

1. languages: 런타임을 파일 하나로 선언

languages.javascript = {
  enable = true;
  package = pkgs.nodejs_22;
  ...

이것만으로 지정된 버전의 런타임 + 패키지 매니저(bun, uv 등)가 devenv.lock에 고정되어 설치됩니다.

asdf의 .tool-versions와 달리 Nix derivation의 해시까지 고정되어 있으므로 "같은 Node 22.x라도 패치가 달라서 동작하지 않는" 사고가 발생하지 않습니다.

2. profiles: local이 기본값, 나중에 적용된 것이 덮어씀

환경마다 env를 전환하는 패턴입니다. base의 enterShell에서 local env를 로드하고, -P staging 등을 붙였을 때는 profile의 enterShell이 나중에 실행되어, set -a; source의 나중에 적용된 값이 우선하는 동작(last-one-wins)으로 덮어씌워집니다.

let
  loadEnvForProfile = profileName: ''
    set -a
    ...

사용법:

devenv up # local 환경에서 실행 (기본값)
devenv shell -P staging -- <command> # staging env에서 명령 실행
devenv tasks run -P production deploy # production에 배포

왜 devenv 표준의 dotenv.enable을 사용하지 않는가

devenv 표준의 dotenv.enable은 dotenv.filename이 .env 접두사를 반드시 가져야 하며, env/<service>/.env.local과 같은 계층적 경로를 허용하지 않습니다 (모듈의 assertion). 게다가 내장 파서가 KEY="value"

따옴표를 문자 그대로 유지해 버리기 때문에, bash의 set -a; source를 사용하는 방식으로 통일하고 있습니다. bash의 파서(parser)는 따옴표, 이스케이프(escape), 주석을 올바르게 처리해 줍니다.

3. processes: 상주 서비스를 TUI로 묶기

devenv 2.0의 native process manager는 process-compose의 대체제로, Rust로 구현된 TUI가 동봉되어 있습니다. devenv up을 실행하면 선언된 상주 서비스가 시작되며, 키보드 조작만으로 실시간 로그 열람 및 개별 프로세스 재시작이 가능합니다.

processes = {
api = {
exec = ''cd backend && exec ./run-server'';
...

ready.http.get을 지정해 두면 "다음 프로세스를 실행하기 전에 healthcheck 엔드포인트로부터 응답이 올 때까지 기다리는" 처리가 자동으로 삽입됩니다. 기동 순서 보장을 코드가 아닌 선언(declaration)으로 작성할 수 있다는 점이 핵심입니다.

4. tasks: 의존 그래프를 포함한 배치(Batch)

태스크(task)는 Make와 유사한 느낌으로 작성할 수 있지만, before / after를 통한 의존성 해결과 execIfModified를 통한 차분(diff) 실행이 가능합니다.

# DB 실행 → API는 DB 실행 이후에 실행됨
"db:start" = {
exec = ''docker compose up -d db && wait-for-it db:5432'';
...

devenv up 한 번으로 DB 실행 → API 실행 순서로 기동되며, devenv tasks run app:migrate를 실행하면 DB가 이미 실행되었음을 보장한 상태에서 마이그레이션 → 타입 생성 파이프라인이 흐르는 선언적인 방식으로 작성할 수 있습니다.

5. CI gate: execIfModified를 이용한 점진적 스킵(incremental skip)

CI 체크는 devenv test로 실행되는 aggregator task에 집약하는 패턴이 효과적입니다.

"lint-ci:frontend" = {
exec = ''cd frontend && bun run lint:ci'';
execIfModified = [ "frontend/**/*.ts" "frontend/**/*.tsx" ];
...

execIfModified는 **mtime + 콘텐츠 해시(content hash)**로 변경을 감지하므로, 관련 없는 파일만 건드렸다면 모든 태스크가 캐시 히트(cache hit)되어 순식간에 끝납니다. 로컬에서도 CI에서도 동일하게 devenv test 한 번으로 해결된다는 점이 매우 큽니다.

6. scripts: PATH에 직결되는 단발성 명령어

"명령어 이름 그대로" 호출할 수 있는 스크립트를 정의할 수 있습니다. Make의 대체제로 가장 효과적인 것이 바로 이 메커니즘입니다.

scripts = {
"lint" = { exec = ''set -e; lint-frontend; lint-backend''; };
"format" = { exec = ''set -e; format-frontend; format-backend''; };
...

devenv shell 내부에서는 lint / format / ci-check / stop이 모두 PATH에 직접 등록된 명령어로서 호출 가능합니다. AI에게 "어떤 명령어를 실행해야 하는지" 학습시키는 비용이 급격히 줄어듭니다.

7. git-hooks: prek + 내장 훅(built-in hook)

pre-commit hook은 git-hooks.nix를 통해 도구 이름 한 줄로 활성화할 수 있습니다. 언어별로 활성화하고 싶은 hook을 나열하기만 하면 됩니다.

git-hooks.hooks = {
# JS/TS: 한 줄로 활성화 (내장된 기능이 types_or / pass_filenames를 적절히 프리셋함)
biome.enable = true;
...

prek(Rust로 구현된 pre-commit)가 구동되므로 Python 오버헤드 없이, 커밋 1회당 200ms 미만으로 모든 lint를 수행합니다.

8. enterShell: 의존성 자동 동기화

setup:*

태스크를 before = [ "devenv:enterShell" ]에 연결하면, devenv shell에 들어가는 순간(= direnv로 cd한 순간)에 "lockfile이 변경되었다면 의존성을 다시 설치하는" 처리가 자동으로 실행됩니다.

"setup:install-frontend" = {
exec = ''cd frontend && bun install --frozen-lockfile'';
execIfModified = [
...

execIfModified 덕분에 "lockfile에 변경이 없을 때는 스킵"되므로, 매번 터미널을 열 때마다 bun install이 실행되는 일은 없습니다. --frozen-lockfile을 통해 lockfile의 의도치 않은 재작성도 방지하고 있습니다.

이를 언어별로 하나씩 정의하면, pull을 받은 직후 cd만 해도 모든 의존성이 동기화되는 상태가 됩니다. 새로 합류한 팀원이 "작동하지 않는데요"라고 말하는 상황이 거의 사라집니다.

Vibe Coding과의 친화성 ─ 여기가 핵심입니다

지금까지는 "편리한 개발 환경 도구"에 대한 이야기였지만, Vibe Coding (AI 에이전트 주도 개발) 관점에서 무엇이 유익한지를 정리하겠습니다. 이것이 본 기사의 핵심입니다.

1. AI가 호출하는 명령의 실행 컨텍스트가 유일함

Docker Compose 기반의 개발 환경에서는 "컨테이너 안에서 npm install을 하는가? 호스트에서 하는가?"가 항상 모호하여, AI에게 지시를 내려도 틀릴 확률이 높습니다. devenv는 호스트 쉘의 PATH를 전환할 뿐이므로, AI가 lint를 호출하면 호스트 OS 상에서 lint가 실행됩니다. 명령의 실행 컨텍스트가 항상 "호스트 쉘 + devenv 환경"이라는 단 한 종류뿐입니다.

2. PATH 추상화로 AI의 학습 비용 최소화

lint, format, ci-check, stop, dev-web, drizzle-studio ─ 프로젝트 내의 명령어가 전부 PATH에 직접 연결되어 있습니다. AI가 package.json을 읽고 npm run ...의 올바른 호출 방식을 구성할 필요 없이, "단어 하나로 호출할 수 있는" 상태입니다. 프로젝트 고유의 지식을 CLAUDE.md / AGENTS.md의 몇 줄로 압축할 수 있습니다.

# CLAUDE.md (일부 발췌)
| Operation | Command |
|-----------|---------|
...

이것만으로도 AI는 망설임 없이 올바른 명령어를 선택합니다. 처음에는 make를 사용하는 방안도 검토했으나, Makefile은 표기법의 차이가 많아 AI가 실수하기 쉽기 때문에 (탭/스페이스 차이로 작동하지 않음, .PHONY 선언 누락, 쉘의 차이 등) devenv의 scripts로 통일했습니다.

3. devenv 자체가 MCP 서버가 됨

.mcp.json에 devenv를 MCP 서버로 등록할 수 있습니다.

{
"mcpServers": {
"devenv": {
...

이를 통해 Claude Code에서 devenv tasks의 목록 취득 및 실행을 MCP를 통해 할 수 있게 됩니다. AI가 "마이그레이션을 실행해줘"라는 요청을 받으면 app:migrate-dev를 직접 호출할 수 있습니다. Bash 도구를 통해 호출하는 것보다 구조화되어 있으며, 무엇을 실행했는지가 MCP 메시지로 남기 때문에 감사(Audit)하기도 쉽습니다.

4. lockfile 자동 동기화로 AI가 대충 의존성을 바꿔도 안전함

AI가 package.json에 새로운 의존성을 추가하더라도, 다음에 cd하는 순간 setup:install-frontend 태스크가 실행되어 bun install --frozen-lockfile이 실행됩니다. AI가 bun install을 호출하는 것을 잊어버리는 사고가 구조적으로 발생하지 않습니다.

--frozen-lockfile 덕분에, AI가 실수로 package.json만 수정하고 lockfile을 업데이트하지 않은 상태라면 에러를 내며 멈추므로, 불일치 상태를 방치하는 일도 없습니다.

5. profiles로 「실수로 운영 DB를 건드리는 일」을 물리적으로 방지

devenv tasks run app:migrate-dev # → local DB
devenv tasks run -P production db:migrate-deploy # → production DB

AI에게 「-P production은 인간의 승인 없이 실행하지 마라」고 CLAUDE.md에 지시하는 것만으로도 가드(Guard)가 작동합니다. env 파일 자체가 분리되어 있으므로, -P를 붙이지 않는 한 production의 DATABASE_URL이 애초에 PATH 상에 존재하지 않습니다. AI의 실수로 로컬 환경 변수 상태에서 스테이징 DB를 건드리는 사고가 발생하지 않습니다.

6. TUI가 인간을 「루프 안」에 머물게 함

devenv up은 Rust로 제작된 TUI (Terminal User Interface)를 자동으로 실행합니다. AI가 프로세스를 실행한 상태에서, 인간은 터미널 하나를 모니터로 열어두기만 하면 각 서비스의 로그, 재시작, 상태를 키보드 조작만으로 전부 확인할 수 있습니다.

AI가 폭주하더라도 물리적으로 「어, 이거 좀 이상한데?」라고 즉시 알아챌 수 있는 시인성. Vibe Coding은 AI에게 고삐를 넘겨주는 스타일이지만, 언제든 옆에서 지켜볼 수 있다는 안심감이 지속성을 담보합니다.

7. CI와 완전히 동일한 명령어가 로컬에서 동작

# .github/workflows/ci.yml
defaults:
  run:
...

CI에서도 devenv shell bash를 경유하므로, 로컬에서 통과한 명령어는 CI에서도 통과합니다. 「로컬에서는 돌아가는데 CI에서 떨어지는...」 디버깅 세션이 격감합니다. AI에게 「ci-check가 통과할 때까지 수정해줘」라고 부탁하면, 로컬에서 재현할 수 있는 이상 AI가 책임지고 통과시킬 수 있습니다.

8. Skills / Rules로 AI 가드레일 구축

이 리포지토리에서는 .claude/rules/와 .claude/skills/에 AI가 준수해야 할 규칙과 가이드라인을 배치하고 있습니다.

.claude/
├── rules/ # 항상 적용되는 정책
│ ├── skills-first.md # 태스크 시작 전 Skill 확인 및 실행을 필수화
...

commands.md에는 「품질 체크는 반드시 devenv의 scripts를 사용할 것 (직접 bun run biome check를 하는 것은 금지)」라고 적혀 있습니다. AI는 이 규칙을 읽어들이므로, 「환경 구축의 관례」가 대화할 때마다 무너지는 사태를 방지할 수 있습니다.

devenv는 「환경의 스냅샷」을 물리적으로 담보하고, Skills/Rules는 「AI 행동의 스냅샷」을 담보합니다. 두 바퀴가 모두 갖춰져야 비로소 Vibe Coding을 안정적으로 돌릴 수 있다는 것이 저의 실감입니다.

Claude Code에서 devenv를 사용하기 위한 실전 설정

Claude Code를 사용한다는 전제하에, .claude/settings.json을 정비하면 devenv와의 연결이 단번에 매끄러워집니다. 실제로 이 리포지토리에서 운용하고 있는 설정 5가지를 소개합니다.

SessionStart hook으로 direnv 자동 활성화

1. Claude Code 세션을 시작하는 순간, direnv가 신뢰(allow)되지 않으면 lint / ci-check 등의 devenv scripts가 PATH에 나타나지 않습니다. 매번 AI에게 direnv allow를 실행하게 하는 것은 낭비이므로, 세션 시작 시 자동으로 실행합니다.

{
  "hooks": {
    "SessionStart": [
      ...
    ]
  }
}

이것만으로 「Claude Code를 연 직후부터 devenv 환경이 PATH에 정렬되어 있는」 상태를 보장할 수 있습니다. Vibe Coding에 있어서 첫 번째 마찰을 제로로 만드는 설정입니다.

PostToolUse hook으로 편집 후 품질 체크 자동 실행

2. 파일 편집이 일어날 때마다 해당 도메인의 lint-* / format-* / type-check-*를 자동으로 실행합니다. 실패하면 exit 2로 Claude에게 에러를 반환하여 수정을 리트라이(Retry)하게 만드는 루프를 구성할 수 있습니다.

{
"hooks": {
"PostToolUse": [
...

quality-check.sh

내용(발췌):

# devenv 스크립트는 devenv shell (direnv)을 통해 PATH에 포함되어 있다.
# direnv가 활성화되지 않은 세션 (CI 등)에서는 devenv shell -- 을 통해 폴백(fallback)한다.
run() {
...

포인트는 두 가지입니다.

• 파일 경로로부터 대상 도메인을 추론하여, 영향 범위만 체크한다 (편집할 때마다 전체 lint를 실행하지 않음)
• PATH에 직접 명령어가 있으면 즉시 실행하고, 없다면 ─ direnv가 활성화되지 않은 세션(CI로부터의 호출 등)에서도 동일한 스크립트가 동작하도록 devenv shell --를 통해 폴백(fallback)

이것이 효과적인 이유는, AI가 「구현 → 자동 lint → 에러 → 수정 → 다시 lint」라는 TDD 라이크(TDD-like)한 자기 수정 루프를 돌리기 때문입니다. 사람이 ci-check를 실행할 때까지 lint 에러를 알아차리지 못하는 상황이 사라집니다.

permissions.allow로 빈번한 devenv 명령어 사전 허용

3. Claude Code는 위험한 Bash 명령어를 매번 확인하지만, devenv를 통한 품질 체크 및 타입 생성 계열은 매번 확인하는 것이 오히려 노이즈가 됩니다. allow 리스트에 넣어 확인을 스킵합니다.

{
"permissions": {
"allow": [
...

포인트는 「로컬에서 완결되는 읽기 / 검증 / 타입 생성 계열」만 allow로 설정하는 것입니다. devenv tasks run model:*나 setup:*는 멱등성(Idempotency)이 있고 부작용(Side effect)이 국소적이므로 매번 확인할 필요가 없으며, devenv shell -- *는 direnv 미활성 경로에서의 폴백(fallback)으로서 포괄적 허용을 하는 설계입니다.

permissions.deny로 파괴적인 명령어 하드 블록(Hard Block)

4. 반대로 「AI가 절대 실행해서는 안 되는」 명령어는 deny에 명시합니다. 확인(confirm) 절차 없이 문답무용으로 거부됩니다.

{
"permissions": {
"deny": [
...

devenv의 프로필(profile) 메커니즘과 결합하면 효과가 매우 큽니다.

• db:migrate-deploy는 -P production이 필요한 운영 환경 마이그레이션
• deploy:*는 Supabase Edge Functions의 운영 환경 배포

둘 다 AI가 실수하더라도 물리적으로 실행할 수 없습니다. CLAUDE.md에 「운영 배포는 인간의 승인이 필수」라고 적어두기만 하면 AI가 상황 판단을 잘못했을 때 사고가 발생할 수 있지만, permissions.deny에 작성하면 가드 메커니즘(Guard mechanism)으로서 확실하게 작동합니다. 설정 하나만으로 「AI가 운영 DB를 날려버리는 사고」를 구조적으로 방지할 수 있습니다.

PreToolUse hook으로 rm -rf를 셸 레벨에서 탐지

5. 최후의 보루로서, AI가 rm -rf 계열의 명령어를 구성하면 실행 전에 차단합니다.

{
"hooks": {
"PreToolUse": [
...

-rf, -fr, -r --recursive 중 어떤 변형이든 탐지합니다. exit 2로 Claude에게 에러를 반환하고, 「trash를 사용하라」는 유도 메시지를 보냅니다.

삼중 통제 ─ CLAUDE.md + rules + memory

설정뿐만 아니라 AI에 대한 지식 계층(Knowledge layer)도 삼중으로 겹쳐 두었습니다.

.claude/
├── CLAUDE.md # ← 세션마다 항상 주입되는 최상위 규약
├── rules/
...

feedback_use_make_commands.md의 내용은 짧은 피드백입니다:

품질 체크(lint, format, type-check, test, build, ci-check)는 반드시 devenv 명령어를 사용할 것.

Why: 원래 Makefile을 사용했으나, 2026-04에 devenv tasks/scripts로 일원화를 실시함. 직접 bun run biome을 사용하는 대신...

, uv run ruff

, npx tsc

등을 실행하면 환경 차이, CI 불일치, profile (env) 미로드(unloaded) 리스크가 발생할 수 있다.

적용 방법:
bun run biome

, uv run ruff

, npx tsc

등을 직접 실행하지 않는다. 대신 lint, format, type-check, ci-check 등과 같은 devenv 스크립트 (scripts)를 사용한다.

CLAUDE.md는 규약 ("이렇게 한다"), rules는 상세 규칙 ("왜, 어디서"), memory는 경험칙 ("과거에 이런 실패가 있었다")이다. 계층을 나눔으로써 AI에 대한 정보의 밀도와 업데이트 빈도를 적절하게 관리할 수 있다.

permissions / hooks는 물리적 가드(guard), CLAUDE.md / rules / memory는 지식 가드(guard). 두 가지가 모두 갖춰져야 비로소 Claude Code × devenv가 안정적으로 동작한다는 것이 이 리포지토리(repository)에서 운용해 온 결론이다.

모노레포(Monorepo)에서의 확장성 ─ 한 줄로 신규 앱 추가

frontend/apps/<name> 하위의 앱을 한 줄로 늘릴 수 있는 구성으로 되어 있다.

frontendApps = {
web = { port = 3000; };
mobile = {
...