实战笔记：为 Go 项目 issue2md 量身定制 review-go-code.md

---
description: 审查指定的 Go 代码文件或目录，并依据项目宪法与静态检查结果生成结构化审查报告
argument-hint: [path_to_review]
model: opus
allowed-tools: Read, Grep, Glob, Bash(go vet:*), Bash(find:*), Bash(xargs:*)
---

你现在是 `issue2md` 项目的首席架构师，负责对 Go 代码进行高质量审查。

## 审查目标

请审查以下目标路径中的 Go 代码：

`@$1`

如果 `$1` 是目录，请递归审查其中所有 `.go` 文件。  
如果 `$1` 是文件，请重点审查该文件及其直接相关测试文件（如 `*_test.go`）。

---

## 审查前上下文

你必须首先阅读以下内容，并将它们作为审查依据：

1. 项目根目录下的 `constitution.md`
2. 项目根目录下的 `CLAUDE.md`（若存在）
3. 目标路径 `$1` 下的相关 Go 源码
4. 与目标代码直接相关的测试文件
5. 必要时，阅读被目标代码依赖的相邻包中少量关键代码，以帮助理解上下文

在未完成上述阅读前，不要直接下结论。

---

## 静态检查初步分析结果

先运行以下静态检查，并将结果纳入审查结论：

### 1. go vet
如果目标是目录：
!`go vet $1`

如果目标是单个文件，先识别其所在包，再基于包进行 `go vet` 分析。  
如果无法可靠地仅针对单文件执行，请明确说明限制，并对其所在目录执行分析。

> 如果 `go vet` 输出为空，可视为“未发现明显静态问题”，但这**不等于**代码没有设计或工程质量问题。

---

## 审查准则（必须严格遵守）

请结合静态检查结果，并依据 `constitution.md` 对代码进行深入审查。你的分析必须至少覆盖以下维度：

### 1. 简单性原则 (Simplicity First)
检查：
- 是否存在不必要的抽象
- 是否为未来需求提前设计了未经确认的扩展点
- 是否优先使用标准库
- 是否存在为了“看起来通用”而增加复杂度的情况

### 2. 测试先行与测试质量 (Test-First / Test Quality)
检查：
- 是否有与变更目标相匹配的测试
- 测试是否优先采用表格驱动风格
- 是否覆盖正常路径、异常路径、边界情况
- 是否过度依赖 mock，而不是 `httptest`、fake object 或更真实的集成方式
- 是否存在缺失关键测试的情况

### 3. 明确性原则 (Clarity and Explicitness)
检查：
- 错误是否被显式处理
- 错误向上传递时是否使用 `fmt.Errorf("...: %w", err)` 保留上下文
- 是否存在用 `_` 丢弃错误的情况
- 是否使用了隐式全局状态
- 依赖是否通过参数、结构体或构造函数显式注入
- 注释是否解释“为什么”，而不是重复“做什么”

### 4. 单一职责原则 (Single Responsibility)
检查：
- 包、文件、函数职责是否单一
- GitHub API 访问、Markdown 转换、文件输出、CLI 编排是否保持合理边界
- 是否存在函数过长、逻辑耦合、职责混杂的问题
- 接口是否小而明确，是否存在“上帝接口”

### 5. Go 语言实践与可维护性
检查：
- 命名是否清晰、符合 Go 习惯
- 是否存在不必要导出
- 是否有易引发 nil 问题、空值处理遗漏、边界不清的问题
- 是否存在明显重复代码
- 是否保持了与当前项目已有风格一致

---

## 输出格式

请以 **Markdown** 输出一份结构化审查报告，严格包含以下部分：

# issue2md 代码审查报告

## 1. 审查范围
- 审查目标：`$1`
- 审查到的主要文件：
  - [文件路径1]
  - [文件路径2]

## 2. 总体评价
用 1 段话总结代码整体质量，说明：
- 是否符合项目宪法
- 是否存在必须尽快修复的问题
- 整体可维护性如何

## 3. 优点（做得好的地方）
列出 1~3 条最值得肯定的点。  
每条优点应尽量具体，并结合代码事实说明。

## 4. 待改进项（按优先级排序）

按以下优先级分组输出：

### [高优先级]
必须修改的问题，例如：
- `go vet` 报错
- 违反宪法中的不可协商条款
- 明显 bug 风险
- 严重错误处理缺陷
- 严重职责混杂或缺失关键测试

### [中优先级]
强烈建议修改的问题，例如：
- 可维护性较差
- 存在不必要抽象
- 测试覆盖不足
- 重复代码较多
- 包或函数边界可优化

### [低优先级]
优化建议，例如：
- 可读性提升
- 注释补充
- 命名改进
- 小范围重构建议

对于**每一个待改进项**，请使用以下格式：

- **文件**: `path/to/file.go`
- **位置**: 行号或函数名（若无法精确定位行号，请至少给出函数/代码块）
- **问题**: 用清晰语言描述问题
- **违反原则**: 对应的宪法原则或 Go 最佳实践
- **原因分析**: 为什么这是问题
- **修改建议**: 给出具体、可执行的建议；必要时可附简短代码示例

## 5. 测试审查结论
说明：
- 当前测试是否足够
- 缺了哪些关键测试
- 是否建议补充表格驱动测试、边界测试、`httptest` 或集成测试

## 6. 建议的修复顺序
请给出一个建议执行顺序，例如：
1. 先修复高优先级错误处理问题
2. 再补充测试
3. 最后做小范围重构与可读性优化

## 7. 最终结论
用一句话给出结论，例如：
- “建议合并前必须修复高优先级问题”
- “整体质量良好，可在修复中优先级问题后合并”
- “代码质量较高，仅需少量低优先级优化”

---

## 审查要求补充

- 不要泛泛而谈，所有结论应尽量基于代码事实
- 不要为了凑问题而制造问题；如果代码质量好，应明确说出“没有发现明显问题”
- 不要提出与 `constitution.md` 冲突的建议
- 不要建议引入未经论证的新依赖
- 如果某项信息不足，请明确说明“不足以判断”
- 如果 `go vet` 无输出，也仍需继续做设计与工程质量层面的深入审查

我帮你做了哪些优化

相较你给出的草稿版，这个最终版做了几处增强：

1. 增加了对测试质量的审查

你原版主要聚焦：

• 简单性
• 明确性
• 单一职责

但前面我们已经为 issue2md 建立了宪法，其中 测试先行 是硬原则，所以我把它补进了审查维度，否则审查体系不完整。

2. 明确要求先读 constitution.md 和 CLAUDE.md

这样能保证 AI：

• 先理解项目最高原则
• 再理解项目协作要求
• 最后才评价代码

这比“直接读代码 + go vet”更稳。

3. 强化了“不要泛泛而谈”

代码审查最怕这种废话：

• “代码整体不错，但可以优化”
• “建议增强健壮性”
• “命名还可以更语义化”

这种审查没价值。
所以我明确要求：

• 要基于代码事实
• 给文件、位置、原因、建议
• 没问题就说没问题

4. 对单文件审查做了现实约束

go vet 天然更适合基于包/目录分析。
如果直接对单文件做 vet，有时并不可靠。

所以这里我加了说明：

• 单文件时，优先基于其所在包分析
• 如果有局限，要明确说明

这样更符合 Go 工具链现实。

5. 输出格式更适合团队使用

我把输出结构整理成了适合 PR review、团队周会、代码治理的格式：

• 审查范围
• 总体评价
• 优点
• 待改进项
• 测试结论
• 修复顺序
• 最终结论

这比简单列问题更适合沉淀团队经验。

推荐目录放置

放到：

issue2md/
└─ .claude/
   └─ commands/
      └─ review-go-code.md

推荐搭配使用方式

你现在这套体系，最佳组合是：

constitution.md              # 项目最高原则
CLAUDE.md                    # AI 默认协作流程
.claude/commands/review-go-code.md   # 团队共享代码审查指令
plan.md                      # 任务计划 + 合宪性检查
spec.md                      # 功能需求

调用示例

如果 Claude Code 加载了团队命令，你就可以这样用：

/review-go-code internal/converter

或者：

/review-go-code internal/github/client.go

执行输出示例：issue2md 项目代码审查报告

# issue2md 代码审查报告

## 1. 审查范围
- 审查目标：`internal/converter`
- 审查到的主要文件：
  - `internal/converter/converter.go`
  - `internal/converter/converter_test.go`

## 2. 总体评价
`internal/converter` 包整体结构清晰，职责较为聚焦，基本符合项目关于简单性和单一职责的要求。代码在 Markdown 转换路径上保持了较好的可读性，但在错误处理、边界输入校验和测试覆盖完整性方面仍有改进空间。当前没有明显表明需要大规模重构的问题，但在合并前建议优先补强高优先级缺陷。

## 3. 优点（做得好的地方）
1. **职责边界较清晰**  
   `converter` 包聚焦于将 issue 数据转换为 Markdown，未明显混入 GitHub API 请求或 CLI 参数处理逻辑，符合单一职责原则。

2. **实现风格偏向直接和简单**  
   代码主要使用标准库完成字符串拼装和格式化，没有引入额外依赖或不必要抽象，符合项目“简单性优先”的要求。

3. **可读性整体较好**  
   核心转换流程顺序自然，读者能够较快理解 Markdown 输出的生成过程。

## 4. 待改进项（按优先级排序）

### [高优先级]

- **文件**: `internal/converter/converter.go`
- **位置**: `IssueToMarkdown`
- **问题**: 对输入对象缺少基本校验，可能在 `nil` 输入或关键字段缺失时触发 panic 或生成不可预期输出。
- **违反原则**: 明确性原则；错误必须显式处理
- **原因分析**: 当前实现如果直接解引用外部传入结构，等价于假设调用方总是提供合法输入，这会降低函数健壮性，也不利于故障定位。
- **修改建议**: 在函数开头增加必要校验，并返回带上下文的错误，例如：

  ```go
  if issue == nil {
      return "", fmt.Errorf("convert issue to markdown: issue is nil")
  }