README必须明确模块路径、main入口位置、测试标签及配置方式：module需与GitHub路径一致；main.go位置要具体到cmd/子目录；集成测试须加-tags=integration并说明依赖；环境变量需列明必需项及示例值。
README里必须包含go mod init初始化信息
很多新手直接写“本项目使用Go开发”，但别人clone后第一件事是go build失败——因为没说明模块路径。不写module github.com/username/projectname，go mod tidy会报错或拉错依赖。
实操建议：
- 在README开头加一行：
module github.com/yourname/yourproject - 如果项目要发布为库，模块名必须和GitHub路径一致；如果是可执行程序，也建议保持一致，避免本地
replace混淆 - 别只写
go mod init命令，要明确写出完整命令，例如：go mod init github.com/yourname/yourproject
如何写清楚go run和go build的入口文件
Go没有统一的main入口约定，main.go可能在根目录、cmd/下，甚至分散在多个子目录。别人照着README跑不起来，大概率卡在这一步。
实操建议：
- 用
find . -name "main.go" -exec dirname {} /;确认所有main包位置，只列出真正可运行的路径 - 区分场景写法：
- 单命令程序：写
go run cmd/myapp/main.go - 多命令（如
myapp-server和myapp-cli）：分条列出，带简短用途说明
- 单命令程序：写
- 避免写
go run *.go——跨目录时会漏包，且Go 1.21+默认禁用
go test命令要标注是否含集成测试
新手常把单元测试和HTTP调用、DB连接混在一起跑，导致go test ./...在CI里失败，或本地因缺少Redis而卡住。
实操建议：
- 默认只运行纯单元测试：
go test ./... - 集成测试必须显式标记并说明前提：
go test -tags=integration ./...，并在旁边注明“需提前启动PostgreSQL” - 检查
go test -v -tags=integration ./...是否真跳过非集成测试——有些项目忘了在测试文件顶部加//go:build integration
环境变量和配置文件怎么写才不让人踩坑
硬编码localhost:5432或把.env当标配，会导致新协作者启动即报错。Go原生不读.env，得靠第三方库，但README里往往只写“请配置环境变量”，不说清哪些变量必须、哪些可选、值格式是什么。
实操建议：
- 列明所有
os.Getenv()调用的键，例如：DB_URL（必需）、LOG_LEVEL（可选，默认info） - 给出最小可用配置示例，用
pre块展示，比如：DB_URL=postgres://user:pass@localhost:5432/mydb?sslmode=disable API_TIMEOUT=30s
- 如果用了
viper或koanf，务必写清配置文件搜索路径顺序（如config.yaml优先于./config/下的同名文件）
Go项目README最难的不是格式，是准确暴露项目的“隐性契约”：模块路径怎么设、main在哪、测试依赖什么、配置从哪来。漏掉任意一条，协作成本就翻倍。