Internal Package Building Skill
internal-package-building
Guides adding and structuring internal Go packages: when to create a new package, import paths, cmd vs internal boundaries, and domain layout. Use when creating or refactoring code under internal/, adding a new domain, or when the user asks about internal package structure.
SKILL.md
Full skill instructions
Internal Package Building Skill
Use this skill when creating or refactoring internal Go packages.
When to create a new package
- New domain → new directory under
internal/(e.g. new feature area or bounded context). - Existing domain → add or edit files in the existing package; do not split without a clear boundary.
- Shared cross-cutting concern (DB, config, models) → use or extend existing shared packages (
internal/db,internal/models,internal/env) rather than creating a new one unless the concern is clearly separate.
Layout
- One package per directory; package name = directory name (e.g.
internal/candidate_tree→package candidate_tree). - Entrypoints live only in cmd/ (e.g.
cmd/api,cmd/evaluator,cmd/importer). All shared logic lives in internal/. - internal/ must not import cmd/; cmd packages wire and call internal packages.
Imports
- Import internal packages by module path:
tarkov-build-optimiser/internal/<pkg> - Example:
import "tarkov-build-optimiser/internal/models"
Existing internal packages (use, don’t duplicate)
| Package | Role |
|---|---|
internal/db | Database connections and pool |
internal/models | Data types and SQL access (UpsertX, GetXById, etc.) |
internal/env | Environment/config |
internal/helpers | Shared pure helpers (e.g. maths) |
internal/cache | Caching utilities |
internal/candidate_tree | Build candidate tree logic |
internal/evaluator | Build evaluation |
internal/importers | Data import from external sources |
internal/router | HTTP routing and handlers |
internal/tarkovdev | tarkov.dev API client |
Checklist for a new internal package
- Create
internal/<name>/with at least one.gofile; package name =<name>. - Add only code that belongs to that domain; put shared DB/config in
internal/dborinternal/env. - Import other internal packages via
tarkov-build-optimiser/internal/.... - Keep the package focused; if it grows into two clear domains, consider splitting into two packages only when the boundary is obvious.
- Add tests in the same package (
*_test.go); use*_unit_test.goor*_integration_test.goper project conventions.
Boundaries to respect
- No business logic in cmd/ — cmd only parses flags/env, opens DB, and calls internal packages.
- No circular imports — internal packages may depend on each other only acyclically; if you introduce a cycle, extract a shared type or helper into a lower-level package.
- Database access — use
internal/dbfor connections andinternal/modelsfor SQL and data types; do not add new ad-hoc DB packages.