ECC 中的 go-reviewer 智能体：面向 Kiro 的 Go 代码评审工作流与分级检查体系详解

在 ECC（Everything Claude Code）的 Kiro 适配层中，.kiro/agents/go-reviewer.md 定义了一个专职 Go 代码评审智能体：它以只读 + Shell 的最小工具集运行，被调用后先通过 git diff -- '*.go' 圈定变更面，再依次跑 go vet、staticcheck 等静态诊断，然后按「安全 → 错误处理 → 并发 → 代码质量 → 性能 → 最佳实践」的六级优先级输出评审报告，并以 CRITICAL/HIGH/MEDIUM 严重程度给出 Approve / Warning / Block 的明确裁决。读完本文，你将掌握该智能体的完整定义与调用流程、可逐条执行的评审检查清单、配套诊断命令矩阵，以及它在 ECC 多端（Kiro / Claude Code）体系中的部署位置与协同方式。

一、智能体定义：一份可直接装载进 Kiro 项目的角色提示词

go-reviewer 是 ECC 为 Kiro 提供的 33 个专用智能体之一，其定位在 .kiro/README.md 中有明确登记：

go-reviewer — Go code review specialist. Reviews Go code for idiomatic patterns, error handling, concurrency, and performance.

智能体的核心定义文件是 go-reviewer.md，采用「YAML frontmatter + Markdown 提示词」两段式结构。frontmatter 声明了三个字段：

---
name: go-reviewer
description: Expert Go code reviewer specializing in idiomatic Go, concurrency patterns, error handling, and performance. Use for all Go code changes. MUST BE USED for Go projects.
allowedTools:
  - read
  - shell
---

这里有两个值得注意的设计点：

1. description 是触发依据。「Use for all Go code changes. MUST BE USED for Go projects.」这类措辞是在告诉宿主 Agent 框架：只要检测到 Go 项目，就应当把评审任务路由给 go-reviewer，而不是通用 code-reviewer。
2. allowedTools 最小化。仅开放 read 与 shell 两类工具——评审者需要读代码、跑诊断命令，但不需要写文件权限。这与同一体系中 planner、architect 等「只读分析型」智能体的权限模型一致（见 .kiro/README.md 的 Agents 章节）。

双格式分发：IDE 用 MD，CLI 用 JSON

ECC 为每个智能体同时提供 Markdown 与 JSON 两种形态。JSON 版本 .kiro/agents/go-reviewer.json 与 MD 版本提示词完全等价，字段做了 Kiro CLI 化改造：

{
  "name": "go-reviewer",
  "description": "Expert Go code reviewer ... MUST BE USED for Go projects.",
  "mcpServers": {},
  "tools": ["@builtin"],
  "allowedTools": ["fs_read", "shell"],
  "resources": [],
  "hooks": {},
  "useLegacyMcpJson": false,
  "prompt": "You are a senior Go code reviewer ..."
}

对照 MD 版的 read/shell，JSON 版映射为 fs_read/shell，并通过 hooks: {}、mcpServers: {} 显式声明零钩子、零 MCP 依赖——评审逻辑不依赖任何外部服务，装完即用。README 中说明了两种格式的调用入口：IDE 会话中可直接输入 /go-reviewer 显式唤起；CLI 中可通过 /agent swap 切换，或启动时直接指定：

kiro-cli --agent go-reviewer
> "Review the concurrency patterns in this service"

整个 .kiro 目录可通过 .kiro/install.sh 一键安装到任意 Kiro 项目（采用非破坏性拷贝，不覆盖已有文件），README 中的「Example 4: Language-Specific Development」正是以 go-reviewer 作为语言专用智能体的标准用法示例。

Claude Code 端的同族智能体

同一评审角色在仓库顶层的 Claude Code 智能体目录中也有对应实现：agents/go-reviewer.md。两者评审正文完全一致，差异集中在头部：

• 工具声明为 tools: Read, Grep, Glob, Bash，并指定 model: sonnet；
• 正文开头多出一段「Prompt Defense Baseline」防御性基线，要求智能体不变更角色、不泄露机密、将 Unicode 同形字/零宽字符/外部抓取内容等一律视为可疑输入。从源码结构看，这段基线是 ECC 为其跨端智能体统一注入的提示词注入防护层，而 .kiro 版本则依靠 Kiro 平台的工具白名单（allowedTools）做同等的权限收敛。

二、调用流程：被唤起后前 60 秒做什么

MD 与 JSON 两份定义都内嵌了完全相同的「When invoked」启动规程：

1. 运行 git diff -- '*.go' 查看最近的 Go 文件变更；
2. 运行 go vet ./...，如环境装有 staticcheck 则一并运行 staticcheck ./...；
3. 只聚焦本次被修改过的 .go 文件；
4. 立即开始评审。

这套流程把「评审范围收敛」放在第一步：不评审全仓库，只评审 diff 命中的 Go 文件。这既控制 token 消耗，也避免评审报告被历史遗留问题淹没。静态工具先行，则保证了后续人工（LLM）评审建立在 go vet/staticcheck 已经扫过一遍的基础上，LLM 专注于工具规则覆盖不到的语义层问题（如 goroutine 泄漏、错误的包装上下文）。

ECC 还把这个流程封装成了可发现性更强的斜杠命令：commands/go-review.md 声明 /go-review 命令即「invoke the go-reviewer agent」，并把六步工作流（识别变更 → 静态分析 → 安全扫描 → 并发审查 → 惯用法检查 → 生成分级报告）显式写入命令文档，建议使用时机包括：写完/改完 Go 代码后、提交前、评审含 Go 代码的 PR、以及接手陌生 Go 代码库时。

三、评审优先级：六级检查清单全解

智能体提示词的主体是「Review Priorities」部分，按严重程度自上而下组织为六个小节。以下逐级完整继承原文档条目，并结合仓库内配套资料展开。

3.1 CRITICAL — 安全（Security）

检查项	触发特征
SQL 注入	database/sql 查询中使用字符串拼接
命令注入	os/exec 中使用了未校验的外部输入
路径穿越	用户可控的文件路径，缺少 filepath.Clean + 前缀检查
竞态条件	共享状态没有任何同步手段
unsafe 包	无充分理由的使用
硬编码密钥	源码中出现 API key、密码
不安全 TLS	InsecureSkipVerify: true

这些条目与 ECC 仓库中 Go 安全规则的落点相互印证。rules/golang/security.md 要求密钥一律走环境变量（os.Getenv("OPENAI_API_KEY") 并在使用前判空），推荐 gosec ./... 做静态安全扫描；同时强调「超时控制」这一常被忽略的安全面——所有长耗时调用都应挂上 context.WithTimeout(ctx, 5*time.Second) + defer cancel()。评审时，InsecureSkipVerify、os/exec 拼参、SQL 拼接这三类是正则和 LLM 都能稳定识别的高收益检查点。

3.2 CRITICAL — 错误处理（Error Handling）

检查项	反模式	期望写法
被吞掉的错误	用 _ 丢弃 error	显式处理或向上传递
缺少错误包装	return err	return fmt.Errorf("context: %w", err)
可恢复错误用 panic	panic(err)	返回 error
缺少 errors.Is/As	err == target 直接比较	errors.Is(err, target) 以兼容包装链

其中「错误包装」是 Go 1.13 之后错误处理体系的基石：%w 使下游能用 errors.Is 沿 Unwrap 链精确判定哨兵错误，直接 == 比较在任意一层发生包装后即失效。ECC 的 skills/golang-patterns/SKILL.md 给出了标准示范：

func LoadConfig(path string) (*Config, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return nil, fmt.Errorf("load config %s: %w", path, err)
    }
    var cfg Config
    if err := json.Unmarshal(data, &cfg); err != nil {
        return nil, fmt.Errorf("parse config %s: %w", path, err)
    }
    return &cfg, nil
}

注意其包装文案的写法：「动词 + 对象 + %w」，与 go-reviewer 对错误消息的规范要求（小写、不带句末标点，见 3.6）完全一致。

3.3 HIGH — 并发（Concurrency）

• Goroutine 泄漏：启动 goroutine 却没有任何取消机制（应传入 context.Context）；
• 无缓冲 channel 死锁：向没有接收方的无缓冲 channel 发送；
• 缺少 sync.WaitGroup：派生了一批 goroutine 却没有协调收敛；
• 互斥锁误用：加锁后不用 defer mu.Unlock() 解锁。

这四项几乎覆盖了 Go 并发故障的高发面。仓库中可复用的正确范式在 .kiro/skills/golang-patterns/SKILL.md 的 Worker Pool 示例里：wg.Add(1) 前置、defer wg.Done() 后置、for job := range jobs 消费、循环外 wg.Wait() 再 close(results)——四个要点恰好一一对应上面的四条反模式，是评审时可直接引用的「对照答案」：

func workerPool(jobs <-chan Job, results chan<- Result, workers int) {
    var wg sync.WaitGroup
    for i := 0; i < workers; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for job := range jobs {
                results <- processJob(job)
            }
        }()
    }
    wg.Wait()
    close(results)
}

3.4 HIGH — 代码质量（Code Quality）

• 大函数：超过 50 行，应拆分；
• 深层嵌套：超过 4 层；
• 非惯用风格：用 if/else 大包裹而非 early return；
• 包级可变变量：可修改的全局状态；
• 接口污染：定义了无人使用的抽象。

「大函数 + 深嵌套」给了可量化的阈值（50 行 / 4 层），使 LLM 评审能给出可复核的客观依据而非泛泛感受；「early return」偏好与 Go 社区「减少缩进层级」的通用风格一致。接口污染一条则呼应了 ECC Go 模式的另一条原则——「小接口，在使用方而非实现方定义接口」（见 skills/golang-patterns/SKILL.md 的 Small Interfaces 小节），即接口是约束使用方依赖的契约，提前抽象往往意味着臆测需求。

3.5 MEDIUM — 性能（Performance）

• 循环内字符串拼接：应改用 strings.Builder；
• 切片未预分配：已知容量时应用 make([]T, 0, cap)；
• N+1 查询：在循环里逐条发起数据库查询；
• 不必要的分配：热路径上构造临时对象。

这一档问题单项危害低于 CRITICAL/HIGH，但在高 QPS 服务中会累积为可观的分配压力与数据库往返放大，属于「值得在评审中列出、但不单独阻断合并」的范畴。

3.6 MEDIUM — 最佳实践（Best Practices）

• Context 优先：ctx context.Context 应作为函数第一个参数；
• 表驱动测试：测试应使用 table-driven 模式；
• 错误消息：小写开头、不带标点；
• 包命名：短、全小写、不含下划线；
• 循环内 defer：资源在循环结束前不会释放，存在累积风险。

「表驱动测试」一项在 ECC 的配套资料中展开最充分。.kiro/skills/golang-patterns/SKILL.md 与 commands/go-test.md 都给出完整范例：[]struct{name, input, wantErr} 用例表 + t.Run 子测试，/go-test 命令甚至要求 80% 以上覆盖率并用 go test -cover 验证。评审智能体把「测试是否为表驱动」纳入检查，正是为了让「评审」与「TDD 工作流」两端共享同一套测试形态标准。

四、诊断命令矩阵：评审的自动化工具底座

提示词「Diagnostic Commands」一节列出了评审应执行的六条命令：

go vet ./...            # 标准库静态检查：printf 格式、不可达代码等
staticcheck ./...       # SA 系列更深入的静态检查（需另行安装）
golangci-lint run      # 聚合多个 linter 的网关（需另行安装）
go build -race ./...    # 带竞态检测的构建
go test -race ./...     # 带竞态检测的测试运行
govulncheck ./...       # 已知 CVE 的依赖漏洞扫描

可以推断该列表按「工具链成熟度」分层：go vet、-race 属于 Go 工具链自带，任何 Go 项目开箱即用；staticcheck、golangci-lint、govulncheck 是生态工具，提示词中特意写了「if available」，即缺失时应跳过而非报错。commands/go-review.md 中还额外列出了 go test -race ./...，并建议在构建失败时先走 /go-build 修编译错误，再进入评审。竞态检测（-race）在此清单中权重很高：它是唯一能在运行期自动捕获「无同步的共享状态」这一 CRITICAL 项的手段，与静态规则形成互补。

五、审批准则：Approve / Warning / Block 三态裁决

评审的最终输出不是一堆意见，而是一个可被 CI/PR 流程机器消费的门禁结论。原文档「Approval Criteria」三行规则：

• Approve（通过）：没有 CRITICAL 或 HIGH 问题；
• Warning（警告）：仅有 MEDIUM 问题；
• Block（阻断）：发现 CRITICAL 或 HIGH 问题。

commands/go-review.md 将其表格化并给出了带示例的完整报告样例（PASS: Approve / WARNING: Warning / FAIL: Block），其中报告结构为：Files Reviewed（变更文件清单）→ Static Analysis Results（各工具通过与否）→ Issues Found（每条问题标注 [CRITICAL]/[HIGH]/[MEDIUM]、文件与行号、问题代码、修复代码）→ Summary（各级计数）→ Recommendation（合并建议）。例如对「无锁访问共享 map」给出 sync.RWMutex 的具体修复代码，对「裸 return err」给出 fmt.Errorf("get user %s: %w", userID, err) 的包装示范——修复建议直接可粘贴，这是评审报告可操作性的关键。

六、知识联动：golang-patterns 技能与语言感知规则

go-reviewer 提示词的最后一行把细节知识外置给了技能：

For detailed Go code examples and anti-patterns, see skill: golang-patterns.

仓库中 golang-patterns 实际存在三份互补的载体：

载体	路径	形态
Claude Code 主技能	skills/golang-patterns/SKILL.md	676 行完整模式库：简洁优先、零值可用、接受接口返回结构体、错误包装/自定义错误类型/哨兵错误
Kiro 技能	.kiro/skills/golang-patterns/SKILL.md	含 Functional Options、小接口、依赖注入、Worker Pool、Context 传播、包组织、表驱动测试与测试辅助函数
语言感知 steering 文件	.kiro/steering/golang-patterns.md	inclusion: fileMatch + fileMatchPattern: "*.go"，编辑任意 .go 文件时自动注入

其中 steering 文件的 fileMatch 机制（见 .kiro/README.md 的 Steering Files 表）意味着：即使用户没有显式调用 go-reviewer，只要会话中编辑了 Go 文件，Go 惯用法（Functional Options 构造函数、小接口、DI 构造器）就会被自动带进上下文。评审智能体与 steering 规则、rules/golang/ 下的 coding-style / patterns / security / testing / hooks 五份规则共同构成「写代码时注入规范 → 提交时智能体按同一套规范评审」的闭环。Kiro 端与 Claude Code 端共享同一套模式库文本，保证了跨端评审口径一致。

七、适用前提与使用建议

• 前提：目标项目需为 Go 模块（存在 go.mod 的工程约定），且执行诊断命令的环境装有 Go 工具链；staticcheck/golangci-lint/govulncheck 缺失不影响评审主流程，仅减少自动检查面。
• 安装：对 Kiro 项目，在仓库中执行 cd .kiro && ./install.sh /path/to/your/project（详见 .kiro/README.md）；对 Claude Code 侧，agents/go-reviewer.md 由 ECC 主体安装流程分发。
• 推荐链路：按 commands/go-review.md 的集成说明，先 /go-test 确认测试通过 → 出现构建错误用 /go-build → 提交前 /go-review 触发本文介绍的智能体 → 非 Go 专属问题再交由通用 /code-review。

小结：.kiro/agents/go-reviewer.md 的价值在于把「资深 Go 工程师的评审 checklist」固化为一份带严重度分级、带自动诊断命令、带三态裁决、且权限收敛到只读+Shell 的智能体配置。它与 golang-patterns 技能、/go-review 命令、语言感知 steering 规则共同组成了 ECC 的 Go 评审面，既可以直接作为 Kiro 项目内的评审入口，也可作为在任意 Agent 框架下编写「语言专用评审智能体」的参照模板。