---
tags: [ai, claude-code, dev-env]
create time: 2026-07-01 00:00
---

# AI Coding Agent 用法指南

## 概述

在实训环境中使用 AI 辅助开发的规范化方法：Claude Code 作为首选 Coding Agent，配合 GitHub CLI 等工具形成闭环工作流。重点在于 **提示词工程、权限边界、上下文组织** 三要素。

## 核心概念

### Prompting 四原则

无论使用何种 AI 编码工具，以下原则通用：

| 原则 | 要点 | 反面示例 |
|------|------|---------|
| **具体** | 精确到文件名、行号、函数名 | "帮我优化一下登录页面" |
| **限定范围** | 明确说"只改什么"，不说"改什么" | 无范围约束 → 过度改动 |
| **可验证** | 给出预期结果或验收标准 | "让它能跑就行" |
| **分步** | 复杂任务拆成小步骤逐步确认 | 一次性描述整个重构 |

### Claude Code 上下文注入机制

Claude Code 在启动后会自动收集以下上下文：

```
当前工作目录结构
├── CLAUDE.md                    ← 知识库/项目规范（固定注入）
├── .claude/settings.local.json  ← 权限配置（可选）
├── .gitignore
├── src/                         ← 当前打开/选中的文件
└── ...
```

| 注入方式 | 说明 |
|---------|------|
| **CLAUDE.md** | 项目级指令，Claude Code 启动时自动加载到 system prompt |
| **当前文件** | 你正在查看/编辑的文件自动加入 context |
| **选中文本** | 在编辑器选中后用 `@` 引用或直接在对话中使用 |
| **文件附件** | 用 `@file` 语法显式追加任意文件到上下文窗口 |

### CLAUDE.md 模板结构

```markdown
# Project Context

## 技术栈
- Go 1.23 + Gin, Node.js 20 + React 19

## 代码规范
- 错误处理必须 wrapping（fmt.Errorf("failed to X: %w", err)）
- API handler 命名：HandlerSuffix（CreateUserHandler）

## 工作流约定
- PR 标题格式：type(scope): description（feat(auth): add login endpoint）
- 每个 commit 必须是 squash-friendly 的小粒度
```

## 代码示例

### 典型任务工作流

#### 场景 1：实现一个 API 接口

```
在 internal/handler/user.go 中增加 GetUserByID handler，
只改这一个文件，不要动其他代码。
要求：参数绑定使用 gin 的 query binding，错误码使用 pkg/errno 包定义的常量。
```

#### 场景 2：审查已有改动

```
审查刚才的改动（src/auth/middleware.ts），有没有潜在 bug 或性能问题。
重点关注：token 过期处理、中间件执行顺序、内存泄漏风险。
```

#### 场景 3：围绕 Issue 工作

```
查看 #42 issue 的描述，创建一个修复分支 fix-42-rate-limit，
实现限流逻辑后提交并创建 PR。PR 描述中包含复现步骤和修复说明。
```

### 与 GitHub CLI 组合使用

```bash
# Step 1：查看任务清单
gh issue list --state=open --label="internship"

# Step 2：让 Claude Code 直接在这个上下文中工作
# （在 Claude Code 中直接输入上述命令的输出或使用 @）

# Step 3：完成后再切回来发 PR
gh pr create --title "feat(limit): add rate limiter for signup API" \
  --body "@@projects/rate-limiter-design.md"
```

## 常见陷阱与最佳实践

### 1. 上下文窗口溢出

Claude Code 的上下文窗口有限，当项目很大时不要一次性追加太多文件：

```
# ❌ 不好：把整个 src/ 文件夹丢进去
@src/*.go

# ✅ 好：只追加当前文件和相关接口定义
@internal/handler/user.go
@pkg/errno/code.go
```

需要跨文件理解时，先用 Grep 定位关键词再精准追加。

### 2. AI 生成代码不直接提交

AI 生成的代码可能存在 **隐蔽的逻辑错误或安全隐患**，务必经过人工审查：

```
审查流程：
1. 让 Claude Code 生成代码 → diff 输出
2. 人工阅读 diff，逐行检查
3. 如有问题，用自然语言指出（"这里少了 nil check"）→ 让其修正
4. 确认无误后再手动 staged + commit
```

> [!warning] 绝对不要做的事
> - 不要信任 AI 生成的数据库 migration SQL 不经 review 就执行
> - 不要 trust AI 生成的敏感信息（AK/SK、token）直接 commit
> - 不要在 prod 环境让 AI 直接操作

### 3. Prompt 太长反而降低质量

一个超过 500 字的 prompt 通常意味着意图不够聚焦。遵循 **STAR 原则**：

| 元素 | 说明 | 示例 |
|------|------|------|
| **S**ituation | 当前背景 | "我在写一个用户注册的 API handler" |
| **T**ask | 你要做什么 | "需要加上邮箱验证码校验" |
| **A**ction | 具体要求 | "用 Redis SETEX 做 1 分钟有效期，key 前缀 `code:email:`" |
| **R**esult | 期望输出 | "返回 Go struct 并在注释中标明 error code" |

### 4. 利用会话历史进行迭代

不要试图一次性完美。采用增量反馈循环：

```
第一轮：实现功能 → AI 出代码 → 我 review
第二轮："这个实现有个问题，XX 没处理" → AI 修正
第三轮："再加个单元测试" → AI 补测试
第四轮："把错误处理改为 errors.Is 兼容风格" → AI 微调
```

每轮控制在 2-3 次交互内，超出就停下来自己总结。

## 延伸阅读

- [[mac-dev-env-setup/homebrew-intro]] — Claude Code 安装前置（npm/nvm 环境）
- [[CLAUDE.md]] — 本笔记库的 CLAUDE.md 本身就是一个实战范例