Go Code Review Skill (v4.0.0)

When to Use This Skill

This skill activates when users need help with:

Reviewing Go code changes against coding standards
Checking code quality and identifying potential issues
Performing PR reviews for Go projects
Validating database operations and data layer correctness
Checking error handling, concurrency safety, and nil safety
Analyzing design philosophy and UNIX principles compliance
Evaluating observability: logging strategy and error message quality
Reviewing naming conventions, code structure, and readability

Architecture: Three-Tier Expert Review

输入：git diff 变更的 Go 文件
         │
         ▼
┌─────────────────────────────────────────────────────┐
│  Tier 1: tools/run-go-tools.sh                      │  → diagnostics.json
│  go build（编译错误, P0）                             │
│  go vet（类型/格式检查, ~0 假阳性）                   │
│  staticcheck（SSA 分析，可选安装）                    │
└─────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────┐
│  Tier 2: tools/scan-rules.sh                        │  → rule-hits.json
│  修复后的 YAML 规则（兜底扫描）                       │
│  预期 <50 条命中，假阳性大幅降低                       │
└─────────────────────────────────────────────────────┘
         │
         ▼
┌──────────────────────────────────────────────────────────┐
│  Tier 3: 5 个领域专家 Agent（并行）                         │
│  🔴 safety      │ 安全与正确性，上下文并发判断              │
│  🗄️  data        │ 数据层，N+1，序列化，类型语义             │
│  🏗️  design      │ UNIX 7 原则，领域模型，代码变坏根源       │
│  📐 quality     │ 综合 metrics.json，命名语义，可读性       │
│  👁️  observability│ 日志分层策略，错误消息质量               │
└──────────────────────────────────────────────────────────┘
         │
         ▼
聚合：P0 → P1 → P2，去重，中文报告输出到 code_review.result

Tier 1 — 量化分析工具

Script: tools/analyze-go.sh Output: /tmp/metrics.json

Measures per file and per function:

File line count (threshold: 800 lines)
Function line count (threshold: 80 lines)
Nesting depth (threshold: 4 levels)

Tier 2 — YAML 规则扫描

Script: tools/scan-rules.sh Output: /tmp/rule-hits.json

Scans against 38 deterministic regex rules across four YAML files:

rules/safety.yaml — SAFE-001 to SAFE-010
rules/data.yaml — DATA-001 to DATA-010
rules/quality.yaml — QUAL-001 to QUAL-010
rules/observability.yaml — OBS-001 to OBS-008

Tier 3 — 5 个领域专家 Agent

Agent	Expert Perspective
safety (red)	安全与正确性：会崩/死锁/数据损坏吗？
data (blue)	数据层：存取正确高效吗？
design (purple)	架构设计哲学：能活过百万行代码吗？
quality (green)	代码质量：新人 5 分钟能看懂吗？
observability (yellow)	可观测性：凌晨 3 点能快速定位吗？

Each agent receives the full code diff plus the subset of rule-hits.json relevant to its domain. Agents confirm Tier 2 hits with business context and surface additional judgment-based issues that regex cannot detect.

Review Workflow

Step 1: 获取变更文件

# --diff-filter=AM 只取新增(A)和修改(M)的文件，排除已删除文件避免工具报 "file not found"
git diff master --name-only --diff-filter=AM | grep '\.go$'
# 或针对特定 commit
git diff HEAD~1 --name-only --diff-filter=AM | grep '\.go$'

Step 2: 运行 Tier 1 工具链分析

git diff master --name-only --diff-filter=AM | grep '\.go$' | bash tools/run-go-tools.sh > /tmp/diagnostics.json

读取 /tmp/diagnostics.json，记录：

build_errors：编译错误（P0，必须修复，来自 go build）
vet_issues：类型/格式问题（P0/P1，来自 go vet）
staticcheck_issues：SSA 分析结果（SA*→P0，S1*/ST1*→P2，来自 staticcheck，未安装则为空）
large_files：行数 > 800 的文件（参考数据）

如未安装 staticcheck，可提前安装：

go install honnef.co/go/tools/cmd/staticcheck@latest

Step 3: 运行 Tier 2 规则扫描

git diff master --name-only --diff-filter=AM | grep '\.go$' | bash tools/scan-rules.sh > /tmp/rule-hits.json

读取 /tmp/rule-hits.json。实际 JSON 结构：

{
  "hits": [
    {
      "rule_id": "SAFE-001",
      "severity": "P0",
      "file": "service/user.go",
      "line": 45,
      "matched": "return fmt.Errorf(\"get user failed: %v\", err)",
      "message": "禁止使用 fmt.Errorf() 创建错误..."
    }
  ],
  "summary": { "total": 12, "P0": 3, "P1": 8, "P2": 1 }
}

字段说明：file（文件路径）、line（行号）、matched（匹配的源码行）、summary.total（总命中数）。

Step 4: 读取代码内容，启动 Agent

先用 Bash 读取变更代码，再将内容以文本形式传给 agents。Agents 自身只使用 Read/Grep，不执行 Bash 命令。

# 读取变更内容（供 agent 分析）
git diff master --diff-filter=AM -- $(git diff master --name-only --diff-filter=AM | grep '\.go$' | tr '\n' ' ')

变更文件数 ≤ 30：并行启动全部 5 个 agent：

safety agent — 读取 diagnostics.json（build_errors + vet_issues + staticcheck SA*）；确认 rule-hits.json 中 SAFE-001~010 命中（按规则说明过滤假阳性）
data agent — 确认 DATA-001~010 命中；处理 N+1/序列化/事务边界判断
design agent — 无 Tier 2 规则；专注 UNIX 7 原则 + 5 大代码变坏根源
quality agent — 读取 diagnostics.json（large_files + staticcheck S1*/ST1*）；确认 QUAL-001~010 命中
observability agent — 确认 OBS-001~008 命中；处理日志分层策略/错误消息质量

变更文件数 > 30（大 diff 分批启动，避免上下文溢出和权限弹窗堆积）：

第一批（高风险域）：safety + data — 等两个 agent 返回后
第二批：design + quality + observability

Step 5: 聚合输出

收集所有 agent 输出后：

合并 Tier 2 命中（已在 rule-hits.json 中）和 agent 补充的判断性问题
去重：同一位置的问题只保留最高严重度
按 P0 → P1 → P2 排序
输出到 code_review.result

Output Format

重要：所有审查输出必须使用中文。

# Go 代码审查报告（v5.0.0）

## 审查摘要

| 指标 | 数量 |
|------|------|
| P0（必须修复） | X 个 |
| P1（强烈建议） | X 个 |
| P2（建议优化） | X 个 |

## 量化违规（Tier 1）

（来自 metrics.json，由 quality agent 报告）

## P0 问题（必须修复）

### 问题 - [P0] <问题类别>（来自：<agent名称>/<rule-id>）
**位置**: path/to/file.go:行号
**类别**: <具体类别>
**原始代码**:
```go
// 问题代码

问题描述: <中文说明> 修改建议:

// 修复代码

P1 问题（强烈建议）

...

P2 问题（建议优化）

...


## Manual Agent Invocation

Individual agents can be invoked directly without running the full orchestrator:

直接调用 safety agent 直接调用 data agent 直接调用 design agent 直接调用 quality agent 直接调用 observability agent

go-code-review