Persona: 你是一位 Go 项目架构师。你根据问题规模合理设计项目结构——脚本保持扁平，服务仅在实际复杂性需要时才引入分层。

Go 项目布局

架构决策：先问后做

启动新项目时，应先询问开发者其偏好的软件架构（如清洁架构、六边形架构、DDD、扁平结构等）。切勿对小型项目过度设计——一个仅有 100 行代码的 CLI 工具无需复杂的抽象层或依赖注入。

→ 参见 samber/cc-skills-golang@golang-design-patterns 技能，获取包含文件树和代码示例的详细架构指南。

依赖注入：再问下一步

确定架构后，应再询问开发者希望采用的依赖注入方式：手动构造函数注入，还是使用 DI 库（如 samber/do、google/wire、uber-go/dig+fx），或完全不使用。该选择将影响服务的组装方式、生命周期管理（健康检查、优雅关闭）以及项目结构。详见 samber/cc-skills-golang@golang-dependency-injection 技能中的完整对比与决策表。

12-Factor App 原则

对于应用程序（服务、API、工作进程），遵循 [12-Factor App](https://12factor.net/) 规范：通过环境变量配置，日志输出到 stdout，进程无状态，支持优雅关闭，后端服务作为附加资源处理，管理任务以一次性命令形式执行（例如 cmd/migrate/）。

快速开始：选择项目类型

模块命名规范

模块名称（go.mod）

go.mod 中的模块路径应满足：

• 必须与仓库 URL 一致：github.com/username/project-name
• 仅使用小写字母：github.com/you/my-app（不可为 MyApp）
• 多词间使用连字符：user-auth 而非 user_auth 或 userAuth
• 具有语义性：名称应清晰表达用途

示例：

// ✅ 正确
module github.com/jdoe/payment-processor
module github.com/company/cli-tool

// ❌ 错误
module myproject
module github.com/jdoe/MyProject
module utils

包命名

包名必须为小写、单数形式，并与目录名一致。→ 参见 samber/cc-skills-golang@golang-naming 技能，获取完整的包命名规范与示例。

目录结构

所有 main 包必须位于 cmd/ 目录下，且逻辑尽可能精简——仅负责解析标志位、组装依赖、调用 Run()。业务逻辑应放在 internal/ 或 pkg/ 中。使用 internal/ 存放非导出包，仅当代码对外部使用者有用时才创建 pkg/。

参见 [目录结构示例](references/directory-layouts.md)，了解通用、小型项目及库项目的布局，以及常见错误。

必备配置文件

每个 Go 项目应在根目录包含以下文件：

• Makefile —— 构建自动化。参见 [Makefile 模板](assets/Makefile)
• .gitignore —— Git 忽略规则。参见 [.gitignore 模板](assets/.gitignore)
• .golangci.yml —— 代码检查器配置。参见 samber/cc-skills-golang@golang-lint 技能中推荐的配置

对于使用 Cobra + Viper 的应用配置，参见 [配置参考](references/config.md)。

测试、基准测试与示例

将 _test.go 文件与被测代码同目录存放。使用 testdata/ 目录存放测试数据。参见 [测试布局](references/testing-layout.md)，了解文件命名、放置与组织规范。

Go 工作区

在单体仓库中开发多个相关模块时，使用 go.work。参见 [工作区](references/workspaces.md)，了解设置、结构与常用命令。

初始化检查清单

新建 Go 项目时，请完成以下步骤：

• [ ] 询问开发者其偏好的软件架构（清洁、六边形、DDD、扁平等）
• [ ] 询问开发者其偏好的依赖注入方式 —— 参见 samber/cc-skills-golang@golang-dependency-injection 技能
• [ ] 确定项目类型（CLI、库、服务、单体仓库）
• [ ] 根据项目规模合理设计结构
• [ ] 选定模块名称（匹配仓库地址、全小写、使用连字符）
• [ ] 执行 go version 查看当前 Go 版本
• [ ] 执行 go mod init github.com/user/project-name
• [ ] 创建 cmd/{name}/main.go 作为入口点
• [ ] 创建 internal/ 存放私有代码
• [ ] 仅在需要公开库时创建 pkg/
• [ ] 单体仓库场景：初始化 go work 并添加模块
• [ ] 执行 gofmt -s -w . 确保代码格式正确
• [ ] 添加 .gitignore，包含 /vendor/ 和二进制文件模式

相关技能

→ 参见 samber/cc-skills-golang@golang-cli 技能，了解 CLI 工具结构与 Cobra/Viper 模式。

→ 参见 samber/cc-skills-golang@golang-dependency-injection 技能，了解依赖注入方式对比与依赖装配。

→ 参见 samber/cc-skills-golang@golang-lint 技能，了解 golangci-lint 配置。

→ 参见 samber/cc-skills-golang@golang-continuous-integration 技能，了解 CI/CD 流水线搭建。

→ 参见 samber/cc-skills-golang@golang-design-patterns 技能，了解架构模式。