AI 에이전트 개발 필수 용어 총정리 (2): 패키지 매니저와 의존성 관리

Think harder. Think systematically.

[Context]
I am a new junior developer who has absolutely zero background in modern AI agent development and software infrastructure. I have recently joined a development team to build AI agents, but I find myself completely lost when my seniors use terms like 'Bun' or 'pi' as if they are common knowledge. I now need to master the essential vocabulary of AI agent development and its underlying infrastructure to build and manage agents effectively in a software development setting.

I have never studied, practiced, or even casually encountered modern runtimes, package managers, or agentic frameworks. My knowledge in this area is completely blank.

Therefore, do NOT skip over terms, actions, or concepts that a senior software engineer would consider so obvious they go without saying. The things that are "too basic to mention" are precisely what I need explained — the implicit, taken-for-granted knowledge that experts forget is not universal.

[Request]
Create an encyclopedia-level deep-dive terminology dictionary covering these sub-domains: JavaScript and TypeScript Runtimes, Package Managers and Dependency Management, Agentic Orchestration Frameworks, Vector Databases and Memory Management, Execution Environments and Sandboxing, API Integration and Tool Calling.

For each term, explain not just the definition but also: why the term exists (historical or practical origin), how it connects to neighboring concepts, common beginner mistakes or misconceptions, edge cases or exceptions that practitioners know from experience, and how the term is actually used in day-to-day work (not just textbook definitions).

[Output Constraints]

Output Language: ALL output MUST be written in Korean. English original terms should appear in parentheses where they aid understanding (e.g., 런타임(Runtime)).

Output Volume: Use your FULL output token capacity with ZERO abbreviation. Absolute maximum verbosity.

Output Format: Use long-form descriptive paragraphs, NOT short bullet points. No emojis.

Depth: Expand on every nuance, edge case, historical context, and common real-world mistake for each term.

If you reach the output limit, end with ">>> 여기서부터 이어서 작성 <<<" so the user can prompt you to continue.

2부: 패키지 매니저와 의존성 관리 (Package Managers & Dependency Management)

패키지(Package)와 패키지 매니저(Package Manager)의 본질

패키지(Package)란 다른 사람이 이미 작성해 둔 코드의 묶음으로, 특정 기능을 수행하는 라이브러리(Library)다. 예를 들어 AI 에이전트에서 OpenAI API를 호출할 때, 모든 HTTP 요청 로직을 직접 작성하는 것은 비효율적이다. 대신 openai라는 패키지를 설치하면, OpenAI가 공식으로 제공하는 클라이언트 라이브러리가 설치되어 훨씬 간단한 코드로 API를 사용할 수 있다. langchain, @langchain/openai, chromadb, @pinecone-database/pinecone 같은 것들이 모두 패키지다.

패키지 매니저(Package Manager)는 이 패키지들을 프로젝트에 설치, 업데이트, 삭제, 버전 관리하는 도구다. 패키지 매니저 없이 모든 라이브러리를 수동으로 다운로드하고 관리한다고 상상해보면 그 필요성이 명확해진다. 수십 개, 수백 개의 패키지와 그 패키지들이 의존하는 또 다른 패키지들(의존성의 의존성)을 수동으로 관리하는 것은 사실상 불가능하다. 자바스크립트 생태계에서 현재 사용되는 주요 패키지 매니저는 npm, Yarn, pnpm, 그리고 Bun의 내장 패키지 매니저가 있다.

npm(Node Package Manager)

npm은 Node.js와 함께 기본으로 설치되는 공식 패키지 매니저다. npm이 중요한 이유는 단순히 도구의 역할을 넘어서, npm 레지스트리(Registry)라는 세계 최대의 오픈소스 패키지 저장소를 운영하기 때문이다. 2025년 기준 npm 레지스트리에는 200만 개 이상의 패키지가 등록되어 있으며, LangChain, OpenAI SDK, Pinecone 클라이언트 등 AI 에이전트 개발에 필요한 거의 모든 패키지가 여기서 배포된다. npm install 명령어를 실행하면 이 레지스트리에서 패키지를 다운로드하는 것이다.14

npm의 역사는 2010년으로 거슬러 올라간다. 아이작 슐레터(Isaac Schlueter)가 만든 npm은 Node.js 패키지 생태계의 폭발적 성장을 이끌었지만, 시간이 지나면서 속도 문제와 node_modules의 비대함 문제가 커다란 불만 요인이 되었다. node_modules 폴더는 프로젝트에 설치된 모든 패키지와 그 의존성들이 저장되는 폴더인데, 작은 프로젝트에서도 수백 MB에서 수 GB까지 커지는 일이 흔하다. 자바스크립트 커뮤니티에서 “node_modules의 질량이 블랙홀보다 무겁다”는 농담이 있을 정도다. 실무에서 Git 저장소(Repository)에 node_modules 폴더를 포함시키지 않는 것이 기본 원칙이며, 이를 위해 .gitignore 파일에 node_modules를 추가한다.15

초보 개발자가 npm을 쓸 때 자주 저지르는 실수 중 하나는 npm install과 npm ci의 차이를 모르는 것이다. npm install은 package.json을 기준으로 패키지를 설치하되, 락파일(lockfile)인 package-lock.json이 있어도 버전 범위 내에서 최신 버전으로 업데이트할 수 있다. 반면 npm ci(clean install의 약자)는 반드시 package-lock.json을 기준으로 정확히 그 버전만 설치하고, 설치 전에 기존 node_modules를 완전히 삭제한다. CI/CD(지속적 통합/배포) 파이프라인이나 Docker 이미지 빌드 시에는 반드시 npm ci를 사용해야 재현 가능하고(Reproducible) 일관된 빌드를 보장할 수 있다.16

Yarn

Yarn은 2016년 페이스북(현 Meta)이 주도하여 구글, 엑스포넌트(Exponent) 등과 함께 npm의 단점을 개선하기 위해 만든 패키지 매니저다. Yarn이 출시됐을 당시 가장 혁신적인 기능은 두 가지였다. 첫째, 병렬 다운로드(Parallel Download)다. npm 초기 버전은 패키지를 순차적으로(Sequential) 하나씩 다운로드했지만, Yarn은 여러 패키지를 동시에 병렬로 다운로드하여 설치 속도를 크게 높였다. 둘째, 락파일(Lockfile)의 대중화다. Yarn이 도입한 yarn.lock 파일은 패키지의 정확한 버전을 기록하여, 어떤 컴퓨터에서 설치하더라도 동일한 버전의 패키지가 설치되도록 보장한다. 이 아이디어는 이후 npm도 수용하여 package-lock.json을 도입하게 만들었다.17

Yarn은 이후 두 가지 계열로 나뉘었다. Yarn Classic(v1)과 Yarn Berry(v2 이상)이다. Yarn Berry는 PnP(Plug’n’Play)라는 혁신적인 방식을 도입했는데, 이것은 아예 node_modules 폴더를 생성하지 않고 모든 패키지를 하나의 압축 파일(.zip)로 관리하는 방식이다. 이를 통해 설치 속도가 극적으로 향상되고 디스크 사용량도 크게 줄어든다. 그러나 PnP 방식은 기존 node_modules를 전제로 설계된 일부 도구들과의 호환성 문제를 야기하여, 팀에 따라 호불호가 갈린다.18

실무에서 Yarn을 사용하는 프로젝트를 인계받은 초보 개발자가 모르고 npm install을 실행하는 경우가 있는데, 이것은 절대 하면 안 된다. Yarn 프로젝트(yarn.lock 파일이 있는 경우)에서 npm을 사용하면 두 개의 서로 다른 락파일이 공존하는 상황이 생기고, 팀원들이 서로 다른 버전의 패키지를 설치하게 되어 “내 컴퓨터에서는 되는데 네 컴퓨터에서는 안 된다”는 악명 높은 문제가 발생한다. 항상 프로젝트 루트에서 어떤 락파일이 존재하는지 확인하고, 그에 맞는 패키지 매니저를 사용해야 한다.

pnpm(Performant npm)

pnpm은 “퍼포먼트 npm(Performant npm)”의 약자로, 2016년 러슬란 셰프체코(Zoltan Kochan)이 만든 패키지 매니저다. pnpm이 해결하려 한 핵심 문제는 node_modules의 중복(Duplication) 문제다. npm과 Yarn의 기본 방식에서는 프로젝트 A와 프로젝트 B가 동일한 버전의 lodash 패키지를 사용해도, 각 프로젝트의 node_modules 폴더 안에 같은 파일이 두 번 저장된다. 컴퓨터에 수십 개의 프로젝트가 있다면, 동일한 파일이 수십 번 복사되어 디스크 공간을 낭비한다.19

pnpm은 이를 하드 링크(Hard Link)와 심볼릭 링크(Symbolic Link, symlink)를 통해 해결한다. pnpm은 모든 패키지를 컴퓨터의 전역 저장소(Global Store, 보통 ~/.pnpm-store)에 단 한 번만 저장하고, 각 프로젝트의 node_modules에서는 이 전역 저장소의 파일을 가리키는 하드 링크를 생성한다. 따라서 동일한 버전의 패키지는 디스크 어디에서도 딱 한 번만 저장된다. 이는 디스크 사용량을 획기적으로 줄이고 설치 속도도 크게 높인다.20

pnpm이 AI 에이전트 개발에서 특히 주목받는 또 다른 이유는 팬텀 의존성(Phantom Dependency) 문제를 해결한다는 점이다. 팬텀 의존성이란 내가 직접 설치하지 않은 패키지를 코드에서 사용하는 상황을 말한다. 예를 들어 내가 설치한 패키지 A가 내부적으로 패키지 B를 의존성으로 가지고 있다면, npm/Yarn 환경에서는 node_modules에 패키지 B도 같이 설치된다. 이때 개발자가 별도로 설치하지 않았음에도 코드에서 require(‘B’)를 해도 작동한다. 이것이 팬텀 의존성이다. 이는 패키지 A가 버전 업데이트로 B를 의존성에서 제거하면 갑자기 코드가 깨지는 원인이 된다. pnpm은 엄격한 node_modules 구조를 통해 직접 설치하지 않은 패키지에는 접근할 수 없도록 막아, 이러한 문제를 사전에 차단한다.21

package.json — 프로젝트의 설계도

package.json 파일은 모든 Node.js/자바스크립트 프로젝트의 핵심 설정 파일이다. 이 파일은 프로젝트의 이름, 버전, 진입점(Entry Point), 스크립트(Scripts), 의존성 목록 등을 JSON 형식으로 정의한다. 팀에서 새 프로젝트를 받았을 때 가장 먼저 확인해야 하는 파일이 바로 package.json이다. 여기서 어떤 패키지들이 사용되는지, 어떤 명령어로 개발 서버를 시작하는지, 빌드를 어떻게 하는지 모두 알 수 있다.

package.json에서 의존성은 두 가지로 나뉜다. dependencies(의존성)와 devDependencies(개발 의존성)다. dependencies에 포함된 패키지는 프로덕션(Production, 실제 운영 환경)에서도 필요한 패키지다. 예를 들어 openai, langchain, @pinecone-database/pinecone 같은 실제 기능 구현에 사용되는 패키지들이 여기에 포함된다. devDependencies는 오직 개발 과정에서만 필요한 패키지로, 예를 들어 typescript(타입스크립트 컴파일러), jest(테스트 프레임워크), eslint(코드 품질 검사 도구) 같은 것들이다. Docker 이미지를 만들 때 npm install –production이나 npm ci –omit=dev를 사용하면 devDependencies를 제외하고 설치할 수 있어 이미지 크기를 줄일 수 있다.

scripts 섹션은 특히 중요하다. “dev”: “bun run index.ts” 혹은 “build”: “tsc -p tsconfig.json” 같은 명령어를 정의해두면, 팀원 누구나 bun run dev, npm run build 같은 통일된 명령어로 동일한 작업을 수행할 수 있다. AI 에이전트 프로젝트에서 흔히 볼 수 있는 scripts 항목으로는 dev(개발 서버 시작), build(프로덕션 빌드), start(프로덕션 서버 시작), test(테스트 실행), lint(코드 스타일 검사), migrate(데이터베이스 마이그레이션) 등이 있다.

락파일(Lockfile)과 시맨틱 버저닝(Semantic Versioning)

락파일(Lockfile)은 package-lock.json(npm), yarn.lock(Yarn), pnpm-lock.yaml(pnpm), bun.lockb(Bun)이라는 이름으로 프로젝트 루트에 자동 생성되는 파일이다. 락파일의 목적은 “재현 가능성(Reproducibility)”을 보장하는 것이다. package.json에서는 보통 패키지 버전을 ^1.2.3처럼 범위로 지정한다. 이 기호(^)는 1.2.3 이상의 버전이면서 주 버전(1)이 바뀌지 않는 범위 내의 최신 버전을 허용한다는 의미다. 그렇다면 어떤 개발자는 1.2.3이 설치되고, 나중에 합류한 팀원은 1.3.0이 릴리스된 이후라 1.3.0이 설치될 수 있다. 이 미세한 차이가 버그를 만들 수 있다. 락파일은 실제로 설치된 모든 패키지의 정확한 버전과 체크섬(Checksum, 무결성 확인용 해시값)을 기록하여, 누가 어디서 설치해도 동일한 결과를 보장한다.

시맨틱 버저닝(Semantic Versioning, SemVer)은 패키지 버전을 MAJOR.MINOR.PATCH 형식으로 표기하는 규약이다. 예를 들어 1.4.2라면 MAJOR=1, MINOR=4, PATCH=2다. MAJOR 버전은 하위 호환성(Backward Compatibility)이 깨지는 변경이 있을 때 올린다. MINOR 버전은 하위 호환성을 유지하면서 새로운 기능이 추가될 때 올린다. PATCH 버전은 버그 수정처럼 하위 호환성을 유지하면서 내부를 수정할 때 올린다. AI 에이전트 개발에서 LangChain 같은 라이브러리가 0.x 버전에서 1.x 버전으로 올라갈 때 API가 완전히 바뀌어 기존 코드가 전부 작동하지 않는 경우가 실제로 빈번하게 발생한다. package.json에서 ^(캐럿) 기호 대신 틸다(~) 기호를 쓰면 PATCH 버전만 업데이트를 허용하는 보수적인 설정이 되고, 아무 기호 없이 정확한 버전을 명시하면 그 버전 딱 하나만 설치된다.

모노레포(Monorepo)와 워크스페이스(Workspace)

모노레포(Monorepo, Monolithic Repository)는 여러 개의 독립적인 프로젝트나 패키지를 하나의 Git 저장소 안에서 관리하는 방식이다. 대규모 AI 에이전트 시스템에서는 에이전트 코어 로직, 프론트엔드 대시보드, API 서버, 공통 유틸리티 라이브러리 등 여러 프로젝트가 존재할 수 있는데, 이것들을 각각 별도의 저장소로 관리하는 멀티레포(Multirepo) 방식보다 하나의 저장소에서 함께 관리하는 것이 코드 공유, 일관된 버전 관리, 통일된 빌드 파이프라인 면에서 유리할 때가 있다.

npm, Yarn, pnpm은 모두 워크스페이스(Workspace) 기능을 통해 모노레포를 지원한다. package.json에 “workspaces”: [“packages/*”]처럼 설정하면, packages 폴더 아래에 있는 각 하위 프로젝트를 독립적인 패키지로 인식하면서도 최상위 node_modules를 공유하여 중복 설치를 방지한다. pnpm은 특히 모노레포 지원이 뛰어나 대형 AI 에이전트 프레임워크들(LangChain, Vercel AI SDK 등)이 내부적으로 pnpm 워크스페이스를 사용하는 경우가 많다. Turborepo나 Nx 같은 모노레포 전용 도구와 함께 사용하면 빌드 캐싱(Build Caching)을 통해 변경된 패키지만 재빌드하는 효율적인 파이프라인을 구성할 수 있다.22