Dependency Management

Dependency Management Expertise

When This Applies

Apply this guidance when:

• Adding, updating, or removing project dependencies
• Resolving version conflicts between packages
• Auditing dependencies for security vulnerabilities
• Maintaining lock files
• Evaluating new dependencies

Evaluating New Dependencies

Before adding a dependency, check:

Decision Framework

• Add it if: Well-maintained, widely used, saves significant work
• Skip it if: Unmaintained, huge dependency tree, simple to implement yourself
• Ask Architect if: Major new framework, changes the architecture

Version Management

Semantic Versioning

• ^1.2.3 — Allow minor and patch updates (recommended for most deps)
• ~1.2.3 — Allow only patch updates (for stability-critical deps)
• 1.2.3 — Exact version (for known-fragile deps only)

Update Strategy

1. Patch updates (1.2.x): Apply regularly, low risk
2. Minor updates (1.x.0): Test thoroughly, check changelogs
3. Major updates (x.0.0): Plan carefully, may have breaking changes — create a task for it

Lock File Management

• Always commit lock files (package-lock.json, poetry.lock, Cargo.lock)
• Never manually edit lock files
• Regenerate if corrupted: delete and reinstall
• Review lock file diffs in commits — large changes deserve scrutiny

Security Auditing

Run security audits regularly:

• npm: npm audit
• Python: pip-audit or safety check
• Rust: cargo audit
• Go: govulncheck

Vulnerability Response

Dependency Conflicts

When two packages require incompatible versions:

1. Check if either can be updated to resolve the conflict
2. Check if an alternative package exists without the conflict
3. If unavoidable, document the constraint and workaround
4. Notify Architect if the conflict affects architecture decisions