实战笔记：打造高质量通用 Go 项目 `CLAUDE.md` 模板

一、核心目标

1. 这份文档是什么

CLAUDE.md 不是普通说明文档，而是面向 AI Agent 的项目协作规范。

2. 这份文档解决什么问题

它主要解决 4 类问题：

统一行为：让 AI 按团队约定工作
降低幻觉：避免 AI 乱猜技术栈、命令、目录结构
保证一致性：输出代码风格、测试方式、提交信息统一
提升协作效率：先审查再实现，先规划再编码

3. 一句话理解

CLAUDE.md = 项目级 AI 协作宪章
keywords: AI Agent, workflow, constraints, convention

二、学霸级结论先行

1. 高质量 `CLAUDE.md` 的本质

不是“告诉 AI 一些知识”，而是“约束 AI 的决策方式”。

2. 设计原则

一份优质模板通常要覆盖：

角色设定
技术栈锚定
架构规范
代码风格
测试策略
Git 规范
协作流程
个人偏好扩展

3. 记忆框架

可以用下面这个结构记忆：

人设 → 环境 → 规范 → 流程 → 产出

keywords: role, stack, style, process, output

三、通用 Go 项目 `CLAUDE.md` 模板（优化版）

# [项目名] Go 项目 AI Agent 协作指南

你是一位精通 Go 语言的资深软件工程师，熟悉云原生开发、后端系统设计与软件工程最佳实践。你的任务是协助我以高质量、可维护、可测试的方式完成本项目开发。

---

## 1. 技术栈与环境 (Tech Stack & Environment)

- **语言**: Go (>= 1.25)
- **依赖管理**: Go Modules
- **Web 框架/HTTP 库**: [例如: Gin, Chi, Echo, net/http]
- **数据库访问**: [例如: GORM, sqlx, pgx, database/sql]
- **配置管理**: [例如: env, viper, koanf]
- **日志**: 标准库 `log/slog`
- **测试**: 标准 `go test`
- **构建**: `go build` 或 `Makefile`
- **格式化**: `gofmt`, `goimports`
- **静态检查**: `golangci-lint`（配置文件：`.golangci.yml`）

### 执行命令约定
- 在执行构建、测试、Lint 相关操作前，优先查看 `Makefile`、`Taskfile.yml`、`package.json`（若存在工具链桥接）等文件。
- 若项目已定义统一命令，优先使用项目命令，而不是自行猜测。

---

## 2. 架构与代码规范 (Architecture & Code Style)

- **项目结构**: 遵循标准 Go 项目布局。核心业务逻辑必须放在 `internal/` 目录下。
- **分层设计**: 优先按职责拆分为 `handler` / `service` / `repository` / `model` 等层次，避免循环依赖。
- **接口设计**: 遵循“接口由消费者定义”原则，优先小接口、单一职责接口。
- **依赖注入**: 优先显式依赖注入（constructor injection），避免隐式全局状态。
- **上下文传递**: 涉及请求链路、数据库、RPC、外部调用时，必须正确传递 `context.Context`，不得滥用 `context.Background()`。
- **错误处理**: **[强制]** 所有错误返回必须保留上下文，优先使用 `fmt.Errorf("...: %w", err)` 包装错误；禁止无上下文地直接 `return err`，除非是在最底层且错误信息已足够明确。
- **日志**: **[强制]** 使用 `log/slog` 进行结构化日志记录，字段中应包含关键上下文，如 `request_id`、`trace_id`、`user_id`、`order_id` 等。
- **命名风格**: 命名应简洁、语义化，避免无意义缩写；导出标识符需体现业务意图。
- **注释规范**: 对外暴露的类型、函数、接口在必要时添加 Go 风格注释；复杂逻辑必须解释“为什么”，而不只是解释“做了什么”。

---

## 3. 测试规范 (Testing Guidelines)

- **[强制]** 编写测试时，优先采用**表格驱动测试（Table-Driven Tests）**。
- **测试范围**:
  - 单元测试优先覆盖核心业务逻辑
  - 集成测试用于数据库、缓存、消息队列、外部 API 交互
- **边界条件**: 必须关注正常路径、异常路径、边界值、空值、并发场景。
- **可测试性**: 代码设计应便于测试，避免强耦合、隐藏依赖、难以 mock 的实现。
- **测试命名**: 用例名称应清楚表达输入条件与预期行为。

---

## 4. 并发与可靠性 (Concurrency & Reliability)

- **[强制]** 涉及 goroutine、channel、mutex、waitgroup 等并发结构时，必须明确说明：
  - 是否存在竞态条件风险
  - 如何避免资源泄漏
  - 如何处理超时、取消、退出
- **共享状态**: 对共享变量的访问必须说明同步策略，如 `sync.Mutex`、`sync.RWMutex`、`atomic`、channel ownership。
- **goroutine 生命周期**: 所有 goroutine 必须可控退出，避免泄漏。
- **超时控制**: 外部调用必须考虑 `context timeout` 或 `deadline`。

---

## 5. Git 与版本控制 (Git & Version Control)

- **Commit Message 规范**: **[严格遵循]** Conventional Commits
- **格式**: `<type>(<scope>): <subject>`
- **示例**:
  - `feat(auth): add jwt refresh support`
  - `fix(order): handle nil payment callback`
  - `refactor(user): simplify profile update logic`
  - `test(cart): add table-driven tests for discount rules`

当被要求生成 commit message 时，必须严格遵循以上格式。

---

## 6. AI 协作指令 (AI Collaboration Directives)

- **[原则] 优先标准库**: 若标准库可满足需求，优先使用标准库，谨慎引入第三方依赖。
- **[流程] 审查优先**: 实现新功能前，先阅读相关代码，理解现有逻辑，再输出实现计划，待确认后再编码。
- **[流程] 最小改动**: 优先做最小必要修改，避免无关重构。
- **[流程] 先对齐再实现**: 若需求存在歧义、缺少上下文或可能影响架构，先提出澄清问题。
- **[实践] 保持风格一致**: 新代码必须与现有项目风格保持一致，包括目录结构、命名方式、错误处理和日志风格。
- **[实践] 解释复杂代码**: 生成复杂实现后，需简要说明核心逻辑、关键设计决策和风险点。
- **[实践] 变更可追踪**: 若修改多个文件，应说明每个文件的职责和改动目的。
- **[实践] 安全优先**: 涉及认证、鉴权、加密、SQL、文件操作、反序列化、外部输入时，必须主动检查安全风险。
- **[实践] 不臆造 API**: 若项目中不存在某个函数、结构或接口，不要假设其存在；应先查阅代码再实现。
- **[实践] 迁移谨慎**: 若涉及数据库 schema、配置项或接口变更，必须提示兼容性与迁移风险。

---

## 7. 输出要求 (Output Expectations)

- 输出代码时，优先给出完整可用片段，必要时说明放置路径。
- 若只修改局部逻辑，应明确指出修改点。
- 若生成测试代码，应同时说明测试关注点。
- 若生成命令，应确保与本项目现有工具链一致。
- 对不确定的信息，明确标注“需确认”，不要伪造结论。

---

## 8. 禁止事项 (Do Not)

- 不要跳过阅读上下文直接大规模编码
- 不要无理由引入新依赖
- 不要随意改动公共接口
- 不要输出与现有架构冲突的实现
- 不要忽略错误处理、日志记录、上下文传递、测试补充
- 不要生成看似能跑但不可维护的代码

---

## 9. 个人偏好导入区 (Personal Imports)

# @~/.claude/my-personal-go-prefs.md

四、模板结构拆解

1. 角色设定：先给 AI 一个“工程师身份”

模板内容

你是一位精通 Go 语言的资深软件工程师……

为什么重要

这是在做 Role Prompting。

作用：

提高回答的工程化水平
让 AI 更重视可维护性与可扩展性
减少“只求跑通”的一次性代码

本质理解

AI 的输出质量，很大程度取决于你给它设定的身份边界。

keywords: role, senior, engineering

2. 技术栈与环境：给 AI 建立“上下文坐标系”

作用

明确：

Go 版本
框架
数据库
构建命令
测试命令
Lint 工具

为什么重要

如果不写，AI 很可能：

猜错框架
猜错命令
给出不符合项目习惯的方案
推荐不兼容版本的写法

本质

这是在压缩 AI 的搜索空间，减少幻觉。

keywords: stack, environment, context

3. 架构与代码规范：这是“硬约束区”

重点规则

1）项目结构

要求核心逻辑放在 internal/

目的：

保持 Go 项目边界清晰
避免业务逻辑乱放
保持目录可维护

2）错误处理

要求使用：

fmt.Errorf("query user failed: %w", err)

而不是：

return err

目的：

保留错误上下文
便于排查问题
形成错误链

keywords: error wrapping

3）日志规范

要求使用 log/slog 结构化日志。

目的：

便于日志检索和聚合
支持 observability
便于排障与监控分析

keywords: slog, structured logging

4）接口设计

要求“小接口、消费者定义接口”。

目的：

降低耦合
提高可测试性
减少过度抽象

keywords: interface, consumer-defined

4. Git 规范：让 AI 的提交也像团队成员

规则

必须遵循 Conventional Commits

格式：

<type>(<scope>): <subject>

为什么重要

Git 历史更清晰
便于自动生成 changelog
支持自动化发布工具
保持团队提交语言统一

keywords: commit, convention

5. AI 协作指令：这是模板最核心的部分

这一部分不是“写知识”，而是在“写 AI 的 SOP”。

指令一：优先标准库

为什么

Go 社区很强调：

简单
稳定
少依赖

如果标准库能解决，就不需要额外依赖。

好处

降低维护成本
减少安全风险
减少版本冲突

keywords: stdlib

指令二：审查优先

规则

实现前必须：

先看相关代码
理解现状
输出计划
等确认后再编码

为什么

这是最能提升可控性的指令之一。

解决的问题

AI 不了解上下文就乱写
改动范围失控
与现有实现风格冲突

本质

先 review，再 plan，最后 implement

keywords: review, plan, implement

指令三：表格驱动测试

为什么适合 Go

Go 测试生态中，表格驱动测试是非常主流的写法。

优势

结构统一
易扩展
易读
易覆盖边界场景

典型格式

tests := []struct {
	name string
	input string
	want string
}{
	{
		name: "normal case",
		input: "a",
		want: "A",
	},
}

keywords: table-driven test

指令四：并发安全提醒

为什么重要

Go 强大，但并发也最容易出错。

常见问题：

data race
goroutine leak
deadlock
channel misuse
uncontrolled lifecycle

这条规则的价值

不是只让 AI “写并发代码”，而是强制它“解释风险与保护措施”。

学霸记忆

并发代码 = 功能正确 + 生命周期正确 + 共享状态正确

keywords: race, mutex, channel, lifecycle

指令五：解释复杂代码

为什么

AI 生成代码快，但如果不解释：

人类难以维护
团队难以评审
后续难以扩展

所以要求

复杂实现后必须补充：

核心思路
关键设计点
风险说明

keywords: explain, design

五、为什么说它是一份“活文档”

1. 不是一次写完就结束

CLAUDE.md 应该随着项目演化不断更新。

2. 什么时候更新

以下情况要及时更新：

技术栈变化
目录结构调整
测试策略变化
新增团队规范
出现重复的 AI 协作问题

3. 更新原则

遵循：

能约束行为的内容优先写
高频踩坑优先写
项目特有规则优先写

keywords: living document

六、落地方法：如何按自己项目定制

1. 通用部分直接保留

建议保留：

角色设定
技术栈
代码规范
Git 规范
协作流程
输出要求

2. 项目差异化部分重点改

根据项目实际修改：

Web 项目

补充：

路由规范
中间件约定
API 返回格式
鉴权方式

微服务项目

补充：

service boundary
RPC 规范
tracing
配置中心
熔断重试策略

数据密集型项目

补充：

SQL 风格
事务边界
索引要求
慢查询约束

云原生项目

补充：

Dockerfile 规范
Kubernetes manifests
health check
graceful shutdown

keywords: API, RPC, tracing, transaction, graceful shutdown

七、考试级/面试级总结

1. 高频考点

什么是高质量 `CLAUDE.md`

能够把团队经验、项目约束和 AI 工作流程固化下来的协作规范文档。

它和普通 README 的区别

README 面向人类开发者
CLAUDE.md 面向 AI Agent 行为约束

最核心的价值

降低幻觉
提高一致性
固化最佳实践
提高协作效率

2. 一句话模板总结

好的 CLAUDE.md，本质上是在给 AI 写项目级操作系统规则。

keywords: policy, workflow, alignment

八、速记版

# 速记

## 高质量 CLAUDE.md 的核心
- 不是写说明，而是写约束
- 不是告诉 AI 知识，而是规定 AI 行为

## 必备模块
- 角色设定
- 技术栈
- 架构规范
- 错误处理
- 日志规范
- 测试规范
- Git 规范
- AI 协作流程
- 输出要求

## Go 项目重点
- 优先标准库
- internal/ 放核心业务
- 错误要 wrapping
- 日志用 slog
- 测试优先 table-driven
- 并发必须解释安全措施
- 实现前先 review 再 plan

## 本质
CLAUDE.md = AI Agent 协作宪章

【AI生成】学霸笔记：06｜实战笔记：打造高质量通用 Go 项目 `CLAUDE.md` 模板

实战笔记：打造高质量通用 Go 项目 CLAUDE.md 模板

一、核心目标

1. 这份文档是什么

2. 这份文档解决什么问题

3. 一句话理解

二、学霸级结论先行

1. 高质量 CLAUDE.md 的本质

2. 设计原则

3. 记忆框架

三、通用 Go 项目 CLAUDE.md 模板（优化版）

四、模板结构拆解

1. 角色设定：先给 AI 一个“工程师身份”

模板内容

为什么重要

本质理解

2. 技术栈与环境：给 AI 建立“上下文坐标系”

作用

为什么重要

本质

3. 架构与代码规范：这是“硬约束区”

重点规则

1）项目结构

2）错误处理

3）日志规范

4）接口设计

4. Git 规范：让 AI 的提交也像团队成员

规则

为什么重要

5. AI 协作指令：这是模板最核心的部分

指令一：优先标准库

为什么

好处

指令二：审查优先

规则

为什么

解决的问题

本质

指令三：表格驱动测试

为什么适合 Go

优势

典型格式

指令四：并发安全提醒

为什么重要

这条规则的价值

学霸记忆

指令五：解释复杂代码

为什么

所以要求

五、为什么说它是一份“活文档”

1. 不是一次写完就结束

2. 什么时候更新

3. 更新原则

六、落地方法：如何按自己项目定制

1. 通用部分直接保留

2. 项目差异化部分重点改

Web 项目

微服务项目

数据密集型项目

云原生项目

七、考试级/面试级总结

1. 高频考点

什么是高质量 CLAUDE.md

它和普通 README 的区别

最核心的价值

2. 一句话模板总结

八、速记版

实战笔记：打造高质量通用 Go 项目 `CLAUDE.md` 模板

1. 高质量 `CLAUDE.md` 的本质

三、通用 Go 项目 `CLAUDE.md` 模板（优化版）

什么是高质量 `CLAUDE.md`