5.2 KiB
5.2 KiB
tags, create time
| tags | 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 模板结构
# 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 组合使用
# 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 原则：
| 元素 | 说明 | 示例 |
|---|---|---|
| Situation | 当前背景 | "我在写一个用户注册的 API handler" |
| Task | 你要做什么 | "需要加上邮箱验证码校验" |
| Action | 具体要求 | "用 Redis SETEX 做 1 分钟有效期，key 前缀 code:email:" |
| Result | 期望输出 | "返回 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 本身就是一个实战范例