<!-- title: Claude Code Go实战：CLI工具从零到发布 -->

# Claude Code Go实战：CLI工具从零到发布

## 概述

本教程面向零基础开发者，手把手教你用 Claude Code 开发一个实用的 Go CLI 工具。你将学会 Claude Code 的安装配置、项目初始化、对话式开发、测试调试、Git 工作流和发布全流程。通过构建一个真实可用的 Markdown 文件搜索工具 `mdfinder`，在实战中掌握 AI 辅助编程的核心技能。

**适合人群**：Go 语言初学者、想快速上手 Claude Code 的开发者、对 AI 辅助编程感兴趣的工程师

**学习目标**：
- 完成 Claude Code 环境搭建与认证
- 掌握 `CLAUDE.md` 项目配置技巧
- 用对话式开发构建完整的 Go CLI 应用
- 理解 Plan Mode、权限管理、上下文压缩等核心功能
- 实现 Git 工作流自动化与项目发布

---

## 前置条件

| 工具 | 最低版本 | 安装方式 |
|------|---------|---------|
| Node.js | ≥ 18.0 | `brew install node` 或 [nodejs.org](https://nodejs.org) |
| Go | ≥ 1.21 | `brew install go` 或 [go.dev/dl](https://go.dev/dl) |
| Git | ≥ 2.30 | `brew install git` |
| 终端 | 任意 | macOS Terminal / Linux bash / Windows WSL |

**无需基础**：Go 语法会在开发过程中由 Claude Code 解释，你不需要提前学 Go。

---

## 第一步：安装与认证 Claude Code

### 1.1 安装 Claude Code

打开终端，执行安装命令：

```bash
# 通过 npm 全局安装
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version
```

**预期输出**：
```
Claude Code v1.0.x
```

> **Windows 用户注意**：Claude Code 需要 WSL2 环境。在 PowerShell 中执行 `wsl --install`，然后在 WSL 终端内操作。

### 1.2 首次认证

```bash
claude
```

首次运行会进入交互式认证流程：

```
╭──────────────────────────────────────────╮
│  Welcome to Claude Code!                 │
│                                          │
│  Choose an authentication method:        │
│  1. Anthropic API Key                    │
│  2. Claude App Subscription (Pro/Team)   │
│  3. Enterprise SSO                       │
╰──────────────────────────────────────────╯
```

**推荐选择**：
- 如果你有 Claude Pro/Team 订阅 → 选 2，会打开浏览器完成 OAuth 登录
- 如果你有 API Key → 选 1，粘贴 `sk-ant-xxx` 格式的密钥
- 企业用户 → 选 3，使用公司 SSO

认证成功后，你会看到 Claude Code 的交互提示符：

```
> 
```

### 1.3 常见安装问题

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| `command not found: claude` | npm 全局路径未加入 PATH | 执行 `npm config get prefix`，将 `/bin` 加入 PATH |
| `EACCES permission denied` | npm 全局目录权限不足 | 使用 `nvm` 管理 Node.js，或 `sudo npm install -g` |
| Node.js 版本过低 | 需要 ≥ 18.0 | `node -v` 检查，升级 Node.js |
| WSL 中网络错误 | DNS 配置问题 | 在 `/etc/resolv.conf` 添加 `nameserver 8.8.8.8` |

---

## 第二步：创建项目与配置 CLAUDE.md

### 2.1 初始化 Go 项目

```bash
# 创建项目目录
mkdir mdfinder && cd mdfinder

# 初始化 Go module
go mod init github.com/yourname/mdfinder

# 创建基本目录结构
mkdir -p cmd internal
```

### 2.2 编写 CLAUDE.md — 最重要的配置文件

`CLAUDE.md` 是 Claude Code 的"项目说明书"，它告诉 Claude 你的项目结构、编码规范和开发约定。

在项目根目录创建 `CLAUDE.md`：

```markdown
# mdfinder - Markdown 文件搜索工具

## 项目概述
一个用 Go 编写的 CLI 工具，用于递归搜索目录中的 Markdown 文件，
支持按标题、标签、内容关键词搜索，输出彩色高亮结果。

## 技术栈
- Go 1.21+
- 使用标准库为主，仅允许以下外部依赖：
  - cobra：CLI 框架
  - fatih/color：终端彩色输出

## 项目结构
- `cmd/` — 命令入口
- `internal/searcher` — 搜索引擎核心逻辑
- `internal/parser` — Markdown 解析器
- `internal/formatter` — 输出格式化

## 编码规范
- 所有公共函数必须有 GoDoc 注释
- 错误处理使用 `fmt.Errorf` 包装，不使用第三方 errors 库
- 测试文件与源文件同目录，命名为 `*_test.go`
- 变量命名使用驼峰，常量使用驼峰或全大写

## 常用命令
- `go build -o bin/mdfinder ./cmd/mdfinder` — 构建
- `go test ./...` — 运行全部测试
- `go run ./cmd/mdfinder search ./docs --keyword "API"` — 运行
```

**为什么要写 CLAUDE.md？** Claude Code 在每次对话开始时自动读取这个文件。它相当于给 AI 一个永久的"项目上下文"，避免重复解释项目结构。根据 Anthropic 官方博客的建议，`CLAUDE.md` 是提高 Claude Code 输出质量的**单一最高影响因素**。

### 2.3 启动 Claude Code 会话

```bash
claude
```

Claude Code 启动后会自动扫描项目目录：

```
╭──────────────────────────────────────────╮
│  Claude Code • claude-sonnet-4-6         │
│  Project: mdfinder                       │
│  Context: 3 files indexed                │
╰──────────────────────────────────────────╯

> 
```

此时 Claude Code 已经读取了你的 `CLAUDE.md`、`go.mod` 和目录结构，准备好协助开发了。

---

## 第三步：用 Plan Mode 设计 CLI 架构

### 3.1 进入 Plan Mode

在 Claude Code 提示符下，按 **Shift+Tab** 或输入 `/plan` 进入 Plan Mode。Plan Mode 让 Claude 只分析和规划，不修改文件——这是设计阶段的最佳实践。

```
> /plan
```

然后输入需求：

```
设计 mdfinder 的 CLI 命令结构。需要支持三个子命令：
1. search — 搜索 Markdown 文件（支持 --keyword, --tag, --title 参数）
2. index — 建立搜索索引（加速后续搜索）
3. version — 显示版本信息
请给出命令架构设计和文件结构建议。
```

**Claude 的规划输出示例**：

```
## 架构设计

mdfinder/
├── cmd/
│   └── mdfinder/
│       └── main.go          # 入口，初始化 cobra rootCmd
├── internal/
│   ├── searcher/
│   │   ├── searcher.go      # 搜索引擎接口与实现
│   │   └── searcher_test.go
│   ├── parser/
│   │   ├── markdown.go      # Markdown 解析（提取标题、标签）
│   │   └── markdown_test.go
│   ├── formatter/
│   │   ├── color.go         # 彩色输出
│   │   └── color_test.go
│   └── index/
│       ├── indexer.go       # 索引构建与持久化
│       └── indexer_test.go
├── go.mod
├── go.sum
├── CLAUDE.md
└── README.md

命令注册流程：
rootCmd → searchCmd / indexCmd / versionCmd
```

### 3.2 确认方案后退出 Plan Mode

按 **Shift+Tab** 或输入 `/plan` 退出 Plan Mode，回到正常编码模式。

---

## 第四步：对话式开发核心功能

### 4.1 搭建项目骨架

```
> 按照 Plan 中的架构，创建所有文件的骨架代码。
> 使用 cobra 库，先实现 version 子命令。
> 先不要实现 search 和 index 的完整逻辑，只留 TODO 注释。
```

Claude Code 会：
1. 执行 `go get github.com/spf13/cobra` 安装依赖
2. 创建 `cmd/mdfinder/main.go`，注册 rootCmd 和三个子命令
3. 在各文件中写入骨架代码

**预期输出**（`cmd/mdfinder/main.go`）：

```go
package main

import (
    "fmt"
    "os"

    "github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
    Use:   "mdfinder",
    Short: "A Markdown file search tool",
    Long:  "mdfinder recursively searches directories for Markdown files, supporting keyword, tag, and title search.",
}

var versionCmd = &cobra.Command{
    Use:   "version",
    Short: "Print the version number",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("mdfinder v0.1.0")
    },
}

func init() {
    rootCmd.AddCommand(versionCmd)
}

func main() {
    if err := rootCmd.Execute(); err != nil {
        os.Exit(1)
    }
}
```

验证骨架代码：

```bash
> 帮我运行 go build 和 version 子命令，确认能正常工作。
```

Claude Code 会执行构建和运行命令：

```bash
go build -o bin/mdfinder ./cmd/mdfinder
./bin/mdfinder version
# 输出: mdfinder v0.1.0
```

### 4.2 实现 Markdown 解析器

```
> 实现 internal/parser/markdown.go，需要：
> 1. 解析 Markdown 文件，提取一级标题
> 2. 提取 YAML front matter 中的 tags 字段
> 3. 返回结构化数据 Document{Path, Title, Tags, Content}
> 同时写好测试文件 markdown_test.go
```

Claude Code 会生成完整的解析器实现和测试。关键交互技巧：

- **一次一个模块**：不要一次要求实现全部功能，逐模块交付
- **要求测试同步**：每次实现都要求同时写测试
- **指定边界条件**：如"YAML front matter 可能有也可能没有"

### 4.3 实现搜索引擎

```
> 实现 internal/searcher/searcher.go：
> 1. 接收搜索参数（keyword, tag, title）
> 2. 递归遍历目录查找 .md 文件
> 3. 用 parser 解析后按条件过滤
> 4. 返回匹配的 Document 切片
> 要支持大小写不敏感搜索。
```

**预期核心逻辑**：

```go
type SearchParams struct {
    Keyword string
    Tag     string
    Title   string
    Path    string
}

type Document struct {
    Path    string
    Title   string
    Tags    []string
    Content string
}

func Search(params SearchParams) ([]Document, error) {
    var results []Document
    err := filepath.WalkDir(params.Path, func(path string, d fs.DirEntry, err error) error {
        if err != nil || !strings.HasSuffix(path, ".md") {
            return nil
        }
        doc, parseErr := parser.ParseFile(path)
        if parseErr != nil {
            return nil
        }
        if matches(doc, params) {
            results = append(results, doc)
        }
        return nil
    })
    return results, err
}
```

### 4.4 实现 search 子命令

```
> 在 cmd/mdfinder/main.go 中实现 search 子命令的完整逻辑：
> 1. 接收 --keyword, --tag, --title, --dir 参数
> 2. 调用 searcher.Search
> 3. 用 formatter 彩色输出结果
> 4. 没有匹配时输出友好提示
```

构建并测试：

```bash
# 先创建一些测试 Markdown 文件
mkdir -p testdata
cat > testdata/golang.md << 'EOF'
---
tags: [go, programming, backend]
---
# Go 语言入门

Go 是一门静态类型、编译型的编程语言，适合构建高并发服务。
EOF

cat > testdata/react.md << 'EOF'
---
tags: [react, frontend, javascript]
---
# React 快速上手

React 是一个用于构建用户界面的 JavaScript 库。
EOF

# 搜索测试
./bin/mdfinder search ./testdata --keyword "编程"
./bin/mdfinder search ./testdata --tag "frontend"
```

**预期输出**：

```
Found 1 result:

📄 golang.md
   Title: Go 语言入门
   Tags: go, programming, backend
   Match: "...适合构建高并发服务。"
```

---

## 第五步：测试与调试

### 5.1 运行测试

```
> 运行所有测试，确保通过。如果有失败，修复后重新运行。
```

Claude Code 会执行 `go test ./... -v` 并处理失败的测试。

### 5.2 调试技巧

当遇到 bug 时，描述现象而非猜测原因：

```
> 运行 ./bin/mdfinder search ./testdata --tag "go" 没有返回结果，
> 但 golang.md 的 tags 字段确实包含 "go"。请排查原因。
```

Claude Code 会：
1. 读取 `searcher.go` 和 `parser.go` 中的 tag 匹配逻辑
2. 定位问题（可能是大小写比较、字符串 trim 等问题）
3. 修复并重新运行测试

### 5.3 上下文管理

长对话中上下文可能接近窗口限制。使用以下命令管理：

```
/compact          # 压缩对话历史，保留关键信息
/cost             # 查看当前会话 token 使用量
/clear            # 清空对话，从头开始（文件修改保留）
```

**最佳实践**：每完成一个功能模块后执行 `/compact`，保持上下文清洁。

---

## 第六步：Git 工作流与发布

### 6.1 初始化 Git 仓库

```
> 初始化 Git 仓库，创建合适的 .gitignore，做第一次提交。
```

Claude Code 会：
```bash
git init
# 创建 .gitignore
git add .
git commit -m "feat: initial project structure with search and version commands"
```

### 6.2 使用 Claude Code 管理提交

每完成一个功能模块后：

```
> 查看当前修改，帮我写一个规范的 commit message 并提交。
```

Claude Code 会执行 `git diff` 分析变更，生成 Conventional Commits 格式的提交信息。

### 6.3 自动生成 README

```
> 根据当前代码和 CLAUDE.md，生成一个专业的 README.md，
> 包含安装方式、使用示例、参数说明。
```

### 6.4 发布到 GitHub

```bash
# 在 GitHub 创建仓库（需安装 gh CLI）
gh repo create yourname/mdfinder --public --source=. --push

# 打 tag 发布
git tag v0.1.0
git push origin v0.1.0
```

---

## 实战案例：完整工作流演示

以下是一个完整的 Claude Code 会话实录，展示从零到交付的全过程：

```mermaid
flowchart TD
    A[安装 Claude Code] --> B[创建项目目录]
    B --> C[编写 CLAUDE.md]
    C --> D[启动 claude 会话]
    D --> E["/plan 设计架构"]
    E --> F[搭建项目骨架]
    F --> G[实现 parser 模块]
    G --> H[实现 searcher 模块]
    H --> I[实现 CLI 命令]
    I --> J[运行测试]
    J --> K{测试通过?}
    K -->|否| L[调试修复]
    L --> J
    K -->|是| M[Git 提交]
    M --> N[生成 README]
    N --> O[发布到 GitHub]
    O --> P["v0.1.0 发布完成 🎉"]

    style A fill:#4A90D9,color:#fff
    style E fill:#F5A623,color:#fff
    style J fill:#7ED321,color:#fff
    style P fill:#BD10E0,color:#fff
```

### 完整会话记录（精简版）

```bash
$ mkdir mdfinder && cd mdfinder
$ go mod init github.com/yourname/mdfinder

$ claude
╭──────────────────────────────────────────╮
│  Claude Code • claude-sonnet-4-6         │
│  Project: mdfinder                       │
╰──────────────────────────────────────────╯

> /plan
> 设计一个 Go CLI 工具，递归搜索目录中的 Markdown 文件...
[Plan Mode 输出架构设计]

> 按 Plan 创建项目骨架，先实现 version 子命令
[创建 cmd/mdfinder/main.go, go get cobra]

> 实现 parser 模块，解析 Markdown 提取标题和标签
[创建 internal/parser/markdown.go + _test.go]

> 运行 parser 测试
[go test ./internal/parser/ -v → PASS]

> /compact
[上下文压缩，保留关键设计决策]

> 实现 searcher 模块
[创建 internal/searcher/searcher.go + _test.go]

> 实现 search 子命令和彩色输出
[修改 main.go, 创建 internal/formatter/color.go]

> 创建测试数据并验证端到端搜索
[创建 testdata/, 运行搜索命令 → 正确输出]

> 运行所有测试
[go test ./... -v → 全部 PASS]

> 帮我初始化 Git，创建 .gitignore，提交
[git init, git commit]

> 生成 README.md
[创建 README.md]

> 查看总 token 使用量
/cost
# Session cost: ~$0.85 (120K input, 8K output tokens)
```

---

## Claude Code 核心命令速查

| 命令 | 用途 | 使用场景 |
|------|------|---------|
| `/plan` | 进入/退出规划模式 | 设计架构、分析需求时 |
| `/compact` | 压缩对话历史 | 对话超过 20 轮时 |
| `/clear` | 清空对话 | 切换任务时 |
| `/cost` | 查看 token 消耗 | 控制预算时 |
| `/help` | 查看帮助 | 忘记命令时 |
| `Shift+Tab` | 切换 Plan Mode | 快捷键 |
| `Escape` | 取消当前生成 | Claude 走偏时 |

### CLI 非交互模式

```bash
# 单次执行，适合脚本和 CI
claude -p "运行所有测试并报告结果" --output-format json

# 管道输入
cat error.log | claude "分析这个错误日志的根本原因"

# 继续上次对话
claude --continue

# 指定模型
claude --model claude-opus-4-6
```

---

## 进阶技巧：让 Claude Code 更高效

### 技巧 1：分阶段开发

不要一次性提出所有需求。将开发分为设计 → 骨架 → 核心逻辑 → 测试 → 打磨五个阶段，每阶段结束后 `/compact` 一次。

### 技巧 2：善用 Plan Mode

复杂功能先在 Plan Mode 中讨论方案，确认后再实现。这避免了 Claude 写了大量代码后你发现方向不对。

### 技巧 3：描述问题而非解决方案

**差的提示**：
```
> 在 searcher.go 第 42 行添加 strings.ToLower 调用
```

**好的提示**：
```
> 搜索 --tag "Go" 时匹配不到 tags: ["go"]，应该是大小写敏感导致的，请修复
```

让 Claude 自己决定修复方案，通常比你指定更优。

### 技巧 4：利用 CLAUDE.md 渐进式积累

随着项目演进，让 Claude Code 更新 CLAUDE.md：

```
> 根据目前项目的实际结构，更新 CLAUDE.md 中的项目结构和技术栈部分
```

### 技巧 5：并行处理独立任务

使用多个终端窗口运行独立的 `claude` 会话，分别处理不同的模块。每个会话有自己的上下文窗口，互不干扰。

```mermaid
flowchart LR
    subgraph "终端 1"
        A1["claude"] --> A2["实现 parser"]
    end
    subgraph "终端 2"
        B1["claude"] --> B2["实现 formatter"]
    end
    subgraph "终端 3"
        C1["claude"] --> C2["编写测试"]
    end

    A2 --> D["git merge"]
    B2 --> D
    C2 --> D
```

---

## 常见问题与解决方案

### Q1：Claude Code 生成的代码不符合项目规范怎么办？

在 `CLAUDE.md` 中添加更具体的编码规范。例如：

```markdown
## 编码规范
- 错误处理：所有 error 必须检查，使用 `fmt.Errorf("functionName: %w", err)` 包装
- 命名：接口名以 `-er` 结尾（如 `Searcher`），实现名加 `Default` 前缀
- 测试：表驱动测试优先，使用 `t.Parallel()` 标记无依赖测试
```

规范越具体，Claude Code 的输出质量越高。

### Q2：对话中 Claude 忘记了之前的设计决策？

使用 `/compact` 时 Claude 会总结关键信息。如果仍然丢失，在 `CLAUDE.md` 中添加"设计决策"部分：

```markdown
## 设计决策
- 搜索默认大小写不敏感，使用 `--case-sensitive` 开启敏感搜索
- YAML front matter 解析使用正则而非第三方库，减少依赖
- 索引格式使用 JSON，便于跨平台兼容
```

### Q3：如何控制 Claude Code 的权限？

```bash
# 仅允许读取文件，不允许写入和执行命令
claude --permission-mode ask

# 完全信任（仅用于 CI 或自动化）
claude --dangerously-skip-permissions

# 在 settings.json 中精细配置
# ~/.claude/settings.json
{
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": ["Bash:rm *", "Bash:git push *"]
  }
}
```

### Q4：如何处理大型项目？

```bash
# 使用 .claudeignore 排除不需要的目录
echo "vendor/\nnode_modules/\n*.min.js" > .claudeignore

# 在 CLAUDE.md 中指定关键文件路径
```

---

## 完整项目文件一览

最终项目结构：

```
mdfinder/
├── CLAUDE.md                    # 项目配置
├── README.md                    # 自动生成
├── go.mod
├── go.sum
├── .gitignore
├── .claudeignore                # 排除 vendor/ 等
├── cmd/
│   └── mdfinder/
│       └── main.go              # CLI 入口 + cobra 命令
├── internal/
│   ├── parser/
│   │   ├── markdown.go          # Markdown 解析器
│   │   └── markdown_test.go
│   ├── searcher/
│   │   ├── searcher.go          # 搜索引擎
│   │   └── searcher_test.go
│   ├── formatter/
│   │   ├── color.go             # 彩色输出
│   │   └── color_test.go
│   └── index/
│       ├── indexer.go           # 索引构建
│       └── indexer_test.go
├── testdata/
│   ├── golang.md
│   ├── react.md
│   └── python.md
└── bin/
    └── mdfinder                 # 构建产物
```

---

## 延伸阅读

- [Claude Code 官方文档](https://code.claude.com/docs/en/overview) — Anthropic 官方完整文档，涵盖所有功能
- [Using CLAUDE.md Files](https://claude.com/blog/using-claude-md-files) — Anthropic 博客详解 CLAUDE.md 最佳实践
- [Claude Code Cheat Sheet 2026](https://computingforgeeks.com/claude-code-cheat-sheet/) — 命令速查表，快捷键和 CLI 标志完整列表
- [Go CLI with Cobra 教程](https://github.com/spf13/cobra/blob/main/user_guide.md) — Cobra 框架官方教程

---

## 训练营适用性评估

| 训练营类型 | 适用性 | 教学时长 | 说明 |
|-----------|--------|---------|------|
| Go 语言入门营 | ★★★★★ | 4-6 小时 | 通过实战项目学习 Go 语法和 CLI 开发 |
| AI 辅助编程营 | ★★★★★ | 3-4 小时 | Claude Code 核心工作流全覆盖 |
| 全栈工程师训练营 | ★★★★☆ | 3 小时 | 作为工具链入门模块 |
| DevOps 自动化营 | ★★★☆☆ | 2 小时 | CLI 工具开发思路可迁移 |

**前置训练**：无需前置课程，本教程从零开始。

**后续推荐**：
1. Claude Code Skills 开发实战 — 创建自定义 Skill
2. Claude Code MCP 服务器开发 — 扩展 Claude Code 能力
3. Claude Code 自动化与 CI/CD 集成 — 无人值守工作流

---

## 参考来源

1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — Anthropic 官方快速入门指南，涵盖安装认证流程
2. [Using CLAUDE.md Files - Claude Blog](https://claude.com/blog/using-claude-md-files) — 官方博客详解 CLAUDE.md 配置最佳实践
3. [Claude Code Tutorial for Beginners - CodeWithMukesh](https://codewithmukesh.com/blog/claude-code-for-beginners/) — 2026 年完整初学者教程，涵盖安装到高级功能
4. [Claude Code Cheat Sheet - ComputingForGeeks](https://computingforgeeks.com/claude-code-cheat-sheet/) — 命令速查表，包含快捷键、CLI 标志和配置参考
5. [How to Use Claude Code - Builder.io](https://www.builder.io/blog/how-to-use-claude-code) — Vishwas Gopinath 撰写的实用入门指南，侧重最佳实践

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)