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

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

# 验证安装
claude --version

Claude Code v1.0.x

claude

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

> 

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

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

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

# 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

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

> 

> /plan

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

## 架构设计

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

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

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)
    }
}

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

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

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

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

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
}

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

# 先创建一些测试 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: "...适合构建高并发服务。"

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

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

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

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

git init
# 创建 .gitignore
git add .
git commit -m "feat: initial project structure with search and version commands"

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

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

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

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

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

$ 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)

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

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

# 继续上次对话
claude --continue

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

> 在 searcher.go 第 42 行添加 strings.ToLower 调用

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

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

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

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

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

# 仅允许读取文件，不允许写入和执行命令
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 *"]
  }
}

# 使用 .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                 # 构建产物