mcpField
A
agent-ready-go

agent-ready-go

github.com/rshade开发390 次安装2 周前更新
代码仓库

关于 agent-ready-go

agent-ready-go 是一项技能，帮助 Go 应用更适合编码 Agent 使用。它提供审查清单，并指导配置机器可读输出、结构化错误、非交互命令、测试、日志和构建目标。

主要功能

  1. 01审查 Agent 就绪情况
  2. 02配置结构化 JSON 日志
  3. 03添加机器可读命令输出
  4. 04改进错误处理和退出码
  5. 05设置测试、Lint 和 Makefile 目标

适用场景

  1. 01让现有 Go 应用适用于编码 Agent
  2. 02为新 Go 项目设置 Agent 友好默认项
  3. 03检查 CLI 输出和错误处理

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rshade/agent-skills --skill agent-ready-go

安装后在 Claude Code 中输入/agent-ready-go确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

assets/
.golangci.yml
Makefile
references/
config.md
error-handling.md
logging.md
non-interactive.md
services.md
testing.md

详细介绍

面向 Agent 的 Go

确保所有工具都生成机器可读的输出、错误采用结构化形式，并且命令默认以非交互方式运行，让 Go 应用能够与 AI 编码 Agent 高效协作。

工作流

让 Go 应用做好与 Agent 协作的准备，涉及以下步骤：

  1. 审计 — 对照 Agent 就绪清单找出差距
  2. 结构化日志 — 添加或配置 slog、Zap、ZeroLog 或 Logrus，并使用 JSON 输出
  3. 机器可读输出 — 确保所有命令都能输出 JSON
  4. 代码检查 — 添加配置完善的 .golangci.yml
  5. 测试 — 确保 go test -race -count=1 -timeout=5m 通过，并设置覆盖率阈值
  6. 错误处理 — 使用结构化错误和有意义的退出码
  7. 非交互式设计 — 提供 --yes/-y 标志，优先使用环境变量而非提示
  8. Makefile — 统一 build、test、lint、cover 目标

对于全新项目，请执行所有步骤。对于现有项目，请先进行审计，并只处理缺失的部分。

第 1 步：审计

根据以下清单检查项目。处理每个 ❌：

  • 已配置结构化日志记录器（slog / Zap / ZeroLog / Logrus）
  • 非 TTY 环境下或设置 LOG_FORMAT=json 时，日志记录器会输出 JSON
  • CLI 命令支持 --json 或 --output json 标志
  • 存在 .golangci.yml，且配置了完善的检查器集合
  • go test -race 通过
  • 主要导出的 API 在 godoc 中有可运行的 ExampleXxx 测试
  • 优先进行契约测试/行为测试，而非追求任意的行覆盖率
  • go vet ./... 干净通过
  • 所有错误都使用上下文信息包装（fmt.Errorf("...: %w", err)）
  • 退出码：0 表示成功，非零表示失败（CLI 入口不发生 panic）
  • 所有受 I/O 限制的函数都传递 context.Context
  • 交互式提示提供 --yes/-y 绕过标志
  • Makefile 包含 build、test、lint、cover、ci 目标
  • 收到 SIGTERM/SIGINT 时优雅关闭（HTTP 服务）
  • HTTP 服务提供健康检查端点（/healthz、/readyz）
  • govulncheck ./... 干净通过
  • 遵循 NO_COLOR 约定；非 TTY 输出不包含 ANSI 代码
  • 从环境变量加载配置，并在启动时进行验证

第 2 步：结构化日志

请参阅 references/logging.md，了解 slog、 Zap、ZeroLog 和 Logrus 的配置模式。

主要要求：

  • 当 !isatty(os.Stdout.Fd()) 或 LOG_FORMAT=json 时使用 JSON 格式
  • 包含以下字段：level、ts、msg，以及上下文字段
  • 绝不使用 fmt.Println 输出运行日志
  • 将日志写入 stderr；保持 stdout 干净，以便输出机器可读数据

第 3 步：机器可读输出

Agent 会解析 stdout 来验证结果。每个非平凡命令都必须支持 JSON 输出。

var outputJSON bool
cmd.Flags().BoolVar(&outputJSON, "json", false, "output results as JSON")

if outputJSON {
    enc := json.NewEncoder(os.Stdout)
    enc.SetIndent("", "  ")
    _ = enc.Encode(result)
} else {
    fmt.Printf("Created: %s\n", result.Name)
}

规则：结构化数据 → stdout；进度信息/面向用户的信息 → stderr。

fmt.Fprintln(os.Stderr, "Processing...")  // progress to stderr
json.NewEncoder(os.Stdout).Encode(result) // data to stdout

第 4 步：代码检查

将 assets/.golangci.yml 复制到项目根目录，然后：

golangci-lint run ./...

需要 golangci-lint v1.59+（v1.x 系列）。

请参阅 references/testing.md，了解检查器说明和配置调整指南。

第 5 步：测试

请参阅 references/testing.md，了解完整的测试配置。

go test -race -count=1 -timeout=5m -coverprofile=coverage.out ./...
go tool cover -func=coverage.out | tail -1

不要在 CI 中强制要求任意的行覆盖率百分比（例如，强制要求 80%）。相比填充式单元测试，高信号的契约测试对 Agent 和人类都更有益。

相反，应确保所有主要导出的 API 都有可运行的 ExampleXxx 测试：

  1. 示例是由编译检查的文档。
  2. 它们能证明 API 契约如描述所述正常工作。
  3. 它们能避免 Agent 臆造错误的用法模式。

第 6 步：错误处理

请参阅 references/error-handling.md，了解结构化错误模式和退出码约定。

快速规则：

  • 始终包装错误：fmt.Errorf("loading config: %w", err)
  • CLI main() 捕获所有错误，并以适当的代码退出
  • 绝不要在业务逻辑深处调用 os.Exit——应向上返回错误
  • 除 init()/包级设置外，绝不要使用 panic

第 7 步：非交互式设计

模式请参阅 references/non-interactive.md。

任何会阻止 Agent 执行的提示都必须支持通过 --yes/-y 跳过：

if !yes {
    confirmed, _ := promptConfirm("Delete all records?")
    if !confirmed {
        return nil
    }
}
// proceed

第 8 步：Makefile

将 assets/Makefile 复制到项目根目录。根据项目调整 BINARY_NAME 和 MAIN_PKG。

标准目标：make build、make test、make lint、make cover、 make ci（运行完整流水线）。

资源

文件内容
references/logging.mdslog、Zap、ZeroLog、Logrus 的 JSON 配置
references/testing.md竞态检测器、覆盖率、golangci-lint 调优
references/error-handling.md结构化错误、退出代码、上下文
references/non-interactive.md--yes 标志、环境变量、stdin 检测
references/services.mdHTTP 优雅关闭、健康检查、OTel、请求 ID
references/config.md配置管理、环境变量解析、验证
assets/.golangci.yml适用于生产环境的 Linter 配置
assets/Makefile标准构建/测试/Lint/覆盖率目标

评论

支持 Markdown