AgentSkillsCN

cmd-builder

在 cmd/ 目录下添加并规划 Go 命令行入口点的指南：何时新建 cmd，如何进行布局与连线（仅含基础逻辑，不涉及业务逻辑），以及内部包的使用方法。适用于在 cmd/ 目录下进行代码开发或重构、新增可执行文件，或当用户就 cmd 或入口点结构提出疑问时参考。

SKILL.md
--- frontmatter
name: cmd-builder
description: Guides adding and structuring Go command entrypoints under cmd/: when to create a new cmd, layout, wiring only (no business logic), and use of internal packages. Use when creating or refactoring code under cmd/, adding a new executable, or when the user asks about cmd or entrypoint structure.

Cmd Builder Skill

Use this skill when creating or modifying command entrypoints under cmd/.

When to create a new cmd

  • •New executable (new binary, distinct from api/evaluator/importer/migrations) → new directory under cmd/<name>/ with main.go.
  • •Existing executable → add flags or wiring in that cmd; do not add a second main for the same concern.
  • •Shared orchestration or workflow → implement in internal/ and call from cmd; keep cmd thin.

Layout

  • •One entrypoint per directory: cmd/<name>/main.go, package main.
  • •Each cmd builds to a single binary; the directory name is the conventional binary name (e.g. cmd/api → api).
  • •All logic lives in internal/; cmd only parses flags/env, opens resources (DB, etc.), and calls internal packages.

What cmd does (and does not)

  • •Does: Parse flags (e.g. internal/cli) or env (internal/env); create DB client (internal/db); wire and call internal packages; log and exit on startup failure (log.Fatal or zerolog).
  • •Does not: Contain business logic, algorithms, or domain rules; those live in internal/. If a cmd grows a large loop or workflow, consider moving it into an internal/ package so it can be tested and reused.

Existing cmd apps (use as reference)

CmdRole
cmd/apiLoad env, create DB client, start HTTP router (internal/router).
cmd/evaluatorLoad env and CLI flags, create DB and cache, run evaluation workflow via internal/evaluator and internal/candidate_tree.
cmd/importerLoad env, create DB and tarkov.dev client, run internal/importers and internal/models purge/import.
cmd/migrationsParse args, open DB, run goose migrations.

Imports

  • •Cmd imports internal by module path: tarkov-build-optimiser/internal/<pkg>.
  • •Example: import "tarkov-build-optimiser/internal/env".
  • •internal/ must not import cmd/.

Checklist for a new cmd

  1. •Create cmd/<name>/main.go with package main and a main() that exits on error (e.g. log.Fatal).
  2. •Parse config: use internal/env for env vars and optionally internal/cli for flags.
  3. •Open resources (e.g. internal/db); defer or otherwise ensure cleanup where appropriate.
  4. •Construct and call internal packages only; no business logic in main.
  5. •If the workflow is more than a few calls, consider an orchestration function in internal/ and call it from main.

Boundaries to respect

  • •No business logic in cmd/ — cmd wires and invokes; all domain and workflow logic stays in internal/.
  • •One main per binary — one cmd/<name>/main.go per distinct executable.
  • •internal does not import cmd — dependency flow is cmd → internal only.