164 lines
5.2 KiB
Markdown
164 lines
5.2 KiB
Markdown
---
|
||
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 本身就是一个实战范例
|