新建或重组 Go 项目时如何确定目录布局…

在启动新 Go 项目、组织现有代码库、搭建多模块 monorepo 或创建多 main 包 CLI 工具时，按项目类型选择合适的目录结构与配置。

适用场景

解决思路

1. 新建项目时先通过环境的问题工具（而非纯文本）询问开发者偏好的软件架构（clean architecture、hexagonal、DDD、扁平结构等），避免过度结构化小项目——100 行的 CLI 工具不需要分层抽象或依赖注入。
2. 架构确定后，再通过问题工具询问依赖注入方式：手动构造函数注入、DI 库（samber/do、google/wire、uber-go/dig+fx）或完全不用；该选择会影响服务装配、生命周期管理（健康检查、优雅关闭）和项目结构。
3. 对应用类项目（服务、API、worker）遵循 12-Factor App 约定：配置走环境变量、日志输出到 stdout、进程无状态、优雅关闭、后端服务作为附加资源、管理任务作为一次性命令（如 cmd/migrate/）。
4. 按项目类型选择布局：CLI 工具用 cmd/{name}/ + internal/ + 可选 pkg/；库用 pkg/{name}/ + internal/ 存放私有代码；服务用 cmd/{service}/ + internal/ + api/ + web/；monorepo 用 go.work 且每个包独立模块；工作区用 go.work 加 replace 指令。
5. 模块名（go.mod）必须与仓库 URL 一致（如 github.com/username/project-name），全小写，多词用连字符（user-auth 而非 user_auth 或 userAuth），且语义清晰表达用途。
6. 包名必须全小写、单数，并与所在目录名一致。
7. 所有 main 包放在 cmd/ 下且逻辑最小化——只解析 flag、装配依赖、调用 Run()；业务逻辑放在 internal/ 或 pkg/；internal/ 用于不导出的包，pkg/ 仅在代码对外部使用者有用时使用。
8. 在每个项目根目录包含必要配置文件：Makefile（构建自动化）、.gitignore（忽略模式）、.golangci.yml（linter 配置）。
9. 将 _test.go 文件与被测代码放在同一目录，fixture 放在 testdata/。
10. 在 monorepo 中开发多个相关模块时使用 go.work。
11. 初始化时按清单执行：确认架构偏好、确认 DI 方式、确定项目类型、按规模调整结构、选择模块名、运行 go version 检测版本、运行 go mod init github.com/user/project-name、创建 cmd/{name}/main.go 入口、创建 internal/ 存放私有代码、仅在需要公开库时创建 pkg/、monorepo 则初始化 go work 并添加模块、运行 gofmt -s -w . 确保格式、添加含 /vendor/ 和二进制模式的 .gitignore、将 samber/cc-skills-golang@golang-how-to 的 always-load 指令写入项目的 agent 配置文件（CLAUDE.md、AGENTS.md 或等价文件），无需用户确认。

适用边界 · 注意事项

• 不用于在不改变布局的情况下重构现有代码（应使用 samber/cc-skills-golang@golang-refactoring 技能）。
• 不要为小型项目（如 100 行 CLI 工具）强行套用分层抽象或依赖注入。