pnpm vs npm vs yarn: AI Rules for Each

Three Managers, One Ecosystem

pnpm, npm, and yarn all install packages from the npm registry, resolve dependencies from package.json, and produce a lockfile. But their behaviors differ: pnpm uses a content-addressable store with symlinks (strict node_modules, disk-efficient), npm uses a flat node_modules (hoisted, potential phantom dependencies), and yarn (Berry/v4) uses Plug'n'Play (no node_modules by default, zip-based resolution). Each has different CLI commands, lockfile formats, and workspace configurations.

Without package manager rules: AI generates npm install in a pnpm project (creates package-lock.json alongside pnpm-lock.yaml, corrupts the lockfile), uses yarn add in an npm project (creates yarn.lock, team members get conflicting lockfiles), or runs npx in a pnpm project (npx may resolve differently than pnpm exec). The package manager determines every install, add, remove, and run command. One rule prevents every dependency management error.

This article provides: the key differences between each package manager, the AI rules needed for each, and copy-paste CLAUDE.md templates. The rules tell the AI: this project uses pnpm (use pnpm add, pnpm exec, pnpm-lock.yaml) — preventing the AI from generating commands for a different package manager.

Lockfiles and Install Behavior

pnpm lockfile: pnpm-lock.yaml. Install behavior: strict node_modules with symlinks. Each package gets only its declared dependencies (no phantom dependencies — you cannot import a package you did not declare). The content-addressable store shares packages across projects (install the same version once, symlink everywhere). AI rule: 'pnpm: lockfile is pnpm-lock.yaml. Never edit it manually. Never run npm install or yarn install (creates a conflicting lockfile). Strict resolution: every import must be a declared dependency.'

npm lockfile: package-lock.json. Install behavior: flat node_modules with hoisting. Dependencies are hoisted to the top level for deduplication. Phantom dependencies: you can accidentally import packages that a dependency installed (not in your package.json but accessible in node_modules). AI rule: 'npm: lockfile is package-lock.json. Never run pnpm install or yarn install alongside it. Hoisted: packages may be accessible without being declared (but should still be declared).'

yarn lockfile: yarn.lock. Install behavior: depends on version. Yarn Classic (v1): flat node_modules similar to npm. Yarn Berry (v4): Plug'n'Play (PnP) — no node_modules directory, dependencies resolved from .pnp.cjs and stored as zip files in .yarn/cache. PnP is the most aggressive change: no node_modules means: faster installs, stricter resolution (like pnpm), but some packages need patching for PnP compatibility. AI rule: 'yarn: lockfile is yarn.lock. Berry PnP: no node_modules. Classic: flat node_modules. Specify which yarn version in the rules.'

• pnpm: pnpm-lock.yaml, strict symlinked node_modules, no phantom dependencies
• npm: package-lock.json, flat hoisted node_modules, phantom dependencies possible
• yarn: yarn.lock, Classic (flat) or Berry PnP (no node_modules, zip cache)
• Never run a different package manager's install: creates conflicting lockfiles
• Lockfile in git: always committed, reviewed in PRs, ensures reproducible installs

Commands: add, install, run, exec

pnpm commands: pnpm install (install all), pnpm add react (add dependency), pnpm add -D vitest (add dev dependency), pnpm remove lodash (remove), pnpm run build (run script), pnpm exec tsx script.ts (execute a package binary), pnpm dlx create-next-app (download and execute without installing). Workspace: pnpm add react --filter packages/web (add to specific workspace). AI rule: 'pnpm: use pnpm add/remove/install/run/exec. Workspace filter: --filter package-name. Exec: pnpm exec. One-time run: pnpm dlx.'

npm commands: npm install (install all), npm install react (add dependency), npm install -D vitest (add dev), npm uninstall lodash (remove), npm run build (run script), npx tsx script.ts (execute binary or download and run), npm exec tsx script.ts (explicit exec). Workspace: npm install react -w packages/web (add to workspace). AI rule: 'npm: use npm install/uninstall/run. Workspace: -w package-name. Exec: npx or npm exec. Scripts: npm run script-name.'

yarn commands: yarn (install all), yarn add react (add dependency), yarn add -D vitest (add dev), yarn remove lodash (remove), yarn build (run script — no run keyword needed for common scripts), yarn dlx create-next-app (download and execute). Workspace: yarn workspace packages/web add react (add to workspace). AI rule: 'yarn: use yarn add/remove. Scripts: yarn script-name (no run needed for some). Workspace: yarn workspace package-name command. Exec: yarn dlx.'

• Add: pnpm add vs npm install vs yarn add — three different commands for the same action
• Remove: pnpm remove vs npm uninstall vs yarn remove
• Exec: pnpm exec/dlx vs npx vs yarn dlx
• Workspace filter: pnpm --filter vs npm -w vs yarn workspace
• AI error: npm install react in a pnpm project = wrong lockfile format generated

Workspace Configuration

pnpm workspaces: defined in pnpm-workspace.yaml at the project root. packages: ['packages/*', 'apps/*']. pnpm install installs all workspaces. Cross-workspace dependencies: "@org/shared": "workspace:*" in package.json. pnpm supports: workspace protocol (workspace:*), --filter for targeted commands, and --recursive for running across all workspaces. AI rule: 'pnpm workspaces: pnpm-workspace.yaml. Dependencies: workspace:* protocol. Filter: pnpm --filter package-name command.'

npm workspaces: defined in the root package.json. "workspaces": ["packages/*", "apps/*"]. npm install installs all workspaces. Cross-workspace dependencies: npm handles linking automatically. npm -w packages/web add react adds to a specific workspace. AI rule: 'npm workspaces: workspaces array in root package.json. Target: -w flag for specific workspace. Linking: automatic for workspace packages.'

yarn workspaces: defined in the root package.json (Classic) or package.json with Plug'n'Play (Berry). "workspaces": ["packages/*"]. yarn install installs all. yarn workspace packages/web add react targets a workspace. Yarn Berry adds: constraints (enforce rules across workspaces), plugins (extend yarn functionality), and protocols (workspace:, patch:, portal:). AI rule: 'yarn workspaces: workspaces array in package.json. Target: yarn workspace package-name command. Berry: constraints for workspace rules.'

When to Choose Each

Choose pnpm when: you want strict dependency resolution (no phantom dependencies), disk efficiency matters (shared content-addressable store across projects), you use monorepos (pnpm workspaces with --filter are the most ergonomic), or you want the fastest install times (pnpm is typically the fastest). pnpm is the default recommendation for new projects in 2026. AI rule: 'Default for new projects: pnpm. Strict, fast, disk-efficient, excellent workspace support.'

Choose npm when: your team is most familiar with npm (lowest learning curve — npm is the default Node.js package manager), your project does not need strict resolution (phantom dependencies are acceptable), or your CI/CD pipeline is configured for npm (changing package managers in CI requires configuration updates). npm is the safe default: installed with Node.js, no additional setup. AI rule: 'npm: if team familiarity is the priority. No additional installation needed. Hoisted node_modules is the traditional Node.js model.'

Choose yarn when: your project already uses yarn (migration cost is real), you want Plug'n'Play for zero node_modules (fastest installs, strictest resolution), or you need yarn-specific features (constraints, offline cache, patch protocol). Yarn Berry is the most innovative but also the most different from traditional npm workflows. AI rule: 'yarn: if already in use or PnP is desired. Berry for strict PnP. Classic for npm-compatible workflow with yarn.lock.'

• pnpm: strict, fast, disk-efficient, best monorepo ergonomics — 2026 default recommendation
• npm: installed with Node.js, lowest learning curve, hoisted node_modules
• yarn Berry: PnP (no node_modules), constraints, plugins — most innovative, most different
• Migration cost: changing package managers means: new lockfile, CI update, team training
• Consistency rule: entire team uses the same manager. Mixed managers = corrupted lockfiles

Ready-to-Use Rule Templates

pnpm CLAUDE.md template: '# Package Manager (pnpm). Lockfile: pnpm-lock.yaml (never edit manually). Install: pnpm install. Add: pnpm add package (pnpm add -D for dev). Remove: pnpm remove package. Run: pnpm run script or pnpm script. Exec: pnpm exec binary. One-time: pnpm dlx package. Workspaces: pnpm-workspace.yaml, --filter for targeting. Protocol: workspace:* for local deps. Never: npm install, yarn add, npx — these create wrong lockfiles.'

npm CLAUDE.md template: '# Package Manager (npm). Lockfile: package-lock.json (never edit manually). Install: npm install. Add: npm install package (npm install -D for dev). Remove: npm uninstall package. Run: npm run script. Exec: npx binary. Workspaces: workspaces in package.json, -w for targeting. Never: pnpm install, yarn add — these create wrong lockfiles.'

yarn CLAUDE.md template: '# Package Manager (yarn). Version: Berry (v4) with PnP. Lockfile: yarn.lock (never edit manually). Install: yarn. Add: yarn add package (yarn add -D for dev). Remove: yarn remove package. Run: yarn script-name (no run keyword). Exec: yarn dlx package. Workspaces: workspaces in package.json, yarn workspace name command. Never: npm install, pnpm install — these create wrong lockfiles and node_modules.'

Comparison Summary

Summary of pnpm vs npm vs yarn AI rules.

• Lockfiles: pnpm-lock.yaml vs package-lock.json vs yarn.lock — never mix
• Add: pnpm add vs npm install vs yarn add — three commands for the same action
• Exec: pnpm exec/dlx vs npx vs yarn dlx — different binary execution patterns
• Workspaces: pnpm-workspace.yaml vs package.json workspaces — different config locations
• Resolution: pnpm strict (no phantoms) vs npm hoisted (phantoms possible) vs yarn PnP (no node_modules)
• 2026 default: pnpm for new projects. npm for familiarity. yarn for PnP or existing usage
• Consistency: entire team uses one manager. Mixed = corrupted lockfiles and CI failures
• Templates: lockfile name + command names + never-mix rules prevent every package manager error