AI编程助手术语速查：Claude、Gemini与Codex实战对比

1. 引言：为什么需要这份术语速查表？

第一次用 Claude Code 调试 API 接口时，我对着报错信息输入了五遍不同的 prompt，每次得到的修复方案都南辕北辙。直到发现需要把 swagger.json 通过 /context 命令加载进会话，问题才迎刃而解——这让我意识到，掌握 Coding Agent 的术语体系不是理论课，而是直接影响工程效率的生存技能。

过去半年，我在三个技术栈迥异的项目中分别使用了 Claude、Codex 和 Gemini 的 Agent 体系。最深刻的教训是：不同工具对相同概念的实现方式可能天差地别。比如：

• 在 Claude 里用 /memory 保存的测试规范，在 Gemini 需要写入 GEMINI.md
• Codex 的 "skills" 和 Gemini 的 "extensions" 本质都是可复用流程包
• 同样叫 "hooks"，有的工具用来拦截危险操作，有的却用来注入动态上下文

这份速查表会从工程实践视角拆解 22 个核心术语，特别标注各工具的具体实现差异。你可以把它当作：

• 新成员 onboarding 的术语对照手册
• 跨工具迁移时的概念转换指南
• 设计 AI 协作流程时的架构参考

实战建议：阅读时打开你的 IDE 和 Agent 工具，遇到关键概念立即用 /help 命令验证本地实现。比如在 Claude Code 输入 /help context 会显示上下文管理命令的具体用法。

2. 概念详解：从输入到执行的完整链条

2.1 Prompt 体系：精准传达意图的艺术

2.1.1 用户 Prompt 的工程化写法

一个高效的 coding prompt 应该包含以下结构化要素（以 API 调试为例）：

markdown复制# 任务目标
修复用户登录接口的 401 认证失败问题

# 输入材料
- 错误日志片段（见下方）
- 涉及的文件：`auth/controller.js` `middleware/jwt.js`
- 测试命令：`npm run test:auth`

# 约束条件
- 保持与现有 passport-jwt 策略的兼容
- 不要新增 npm 依赖
- 修改范围限于认证流程

# 验收标准
- 本地测试通过率从 62% 提升至 100%
- 在返回的 401 响应中添加错误详情头 `X-Auth-Error`

# 错误日志
[2024-03-01T11:23:45] 401 Unauthorized: JWT malformed at verifyToken...

各工具的特殊处理：

• Claude：支持 Markdown 代码块注释，可用 <!-- 注释 --> 添加非执行说明
• Gemini：对 JSON/YAML 结构敏感，建议用三个反引号包裹配置片段
• Codex：会自动识别 // TODO: 注释并优先处理

2.1.2 System Prompt 的配置策略

System prompt 相当于 Agent 的"岗位说明书"，这是各工具的配置方式对比：

踩坑记录：曾因在 Gemini 的 system prompt 中写"尽可能自动修复问题"，导致它未经确认就改动了数据库 schema。建议始终包含 重要修改需人工确认 的约束条款。

2.2 上下文管理：让 Agent 看见该看的东西

2.2.1 Context Window 优化实战

当处理大型代码库时，token 限制是最常见的瓶颈。这是我的分层加载策略：

1. 核心层（必须加载）

   • 报错相关的 3-5 个文件
   • 测试用例
   • 最近 5 条相关 git commit

2. 辅助层（按需加载）

   • 接口文档（swagger/openapi）
   • 相关模块的 TypeScript 类型定义
   • 项目约定（如 CLAUDE.md）

3. 排除项

   • node_modules/ 等依赖目录
   • 编译产物（dist/, build/）
   • 日志文件（用 grep 过滤关键错误）

工具命令对比：

bash复制# Claude 的上下文操作
/context add src/utils/auth.js  # 添加文件
/context exclude *.log          # 排除日志

# Gemini 的检索式加载
@search "JWT middleware"        # 全文搜索加载

# Codex 的智能包含
!include related:error.ts       # 自动关联文件

2.2.2 Context Files 的设计模式

一个高效的 CLAUDE.md 应该像餐厅的备餐清单，包含：

markdown复制## 快速开始
```bash
npm ci && npm run seed  # 安装依赖并初始化测试数据

代码风格

• 缩进：2 个空格
• 字符串：单引号优先
• 异步处理：必须使用 async/await 而非回调

测试规范

• 单元测试：__tests__/unit/
• 集成测试：__tests__/integration/
• 覆盖率要求：branches > 80%

危险操作

!warning 以下目录修改需确认：

• database/migrations/
• config/secrets/

code复制
### 2.3 记忆系统：跨越会话的知识复用

#### 2.3.1 三级记忆体系实践
| 记忆类型       | 存储位置                     | 典型内容                          | 工具实现差异                 |
|----------------|------------------------------|-----------------------------------|------------------------------|
| 短期记忆       | 会话线程                     | 当前对话历史、临时变量            | Claude 用 `/thread` 查看      |
| 长期偏好       | 用户配置文件                  | IDE 主题、默认缩进、快捷键映射     | Gemini 存在 `~/.gemini/prefs` |
| 项目记忆       | 版本控制下的约定文件          | 项目规范、CI/CD 流程、API 约定     | Codex 依赖 `AGENTS.md`        |

#### 2.3.2 避免记忆污染的技巧
- **时间戳标记**：在记忆项添加有效期（如 `#validUntil:2024-12-31`）
- **版本隔离**：当项目升级大版本时，用 `mv CLAUDE.md CLAUDE-v2.md` 创建新记忆
- **环境区分**：通过 `#env:production` 标签隔离不同环境的配置

### 2.4 工具链集成：扩展 [Agent](https://taotoken.net?utm_source=ai) 的能力边界

#### 2.4.1 常用工具配置示例
```yaml
# Claude 的 tools 配置片段（.claude/settings.json）
{
  "allowed_tools": {
    "read": ["src/**", "config/*.json"],
    "write": ["__tests__/**"],
    "bash": {
      "patterns": ["npm run *", "git status"],
      "timeout": 30
    }
  }
}

2.4.2 危险命令防护方案

1. 正则过滤：拦截 rm -rf 等危险模式
2. 沙箱路径：限制文件操作在 /tmp/claude-sandbox
3. 二次确认：对含有 production 关键词的命令强制确认
4. 操作回放：自动记录 history 到 .claude/audit.log

2.5 执行体系：任务编排的工程实践

2.5.1 Subagent 分工模式

在微服务调试场景下的典型分工：

2.5.2 检查点最佳实践

• 代码检查点：每次通过测试后执行 /checkpoint --tag stable
• 会话快照：复杂调试前使用 /thread snapshot bugfix-001
• 差异对比：/diff checkpoint:stable..current

3. 术语速查表：按功能域分类

3.1 输入控制层

3.2 上下文管理层

3.3 执行架构层

4. 实战技巧：从知道到做到

4.1 性能优化组合拳

1. Token 压缩：用 /compact --keep "error stack" 保留关键信息
2. 延迟加载：通过 @lazy-load test-cases 按需获取测试文件
3. 缓存复用：对不变的依赖声明启用 --cache-deps 选项

4.2 异常处理模板

python复制# 在 prompt 中植入错误处理规范
当遇到未处理的异常时：
1. [必须] 捕获原始错误对象
2. [建议] 记录到 `logs/app.log` 
3. [禁止] 直接暴露堆栈给客户端
4. [可选] 通过 hook://error-report 通知监控系统

4.3 团队协作规范

1. 版本控制：将 CLAUDE.md 纳入 git 管理
2. Code Review：检查 Agent 生成的代码时重点关注：
   • 是否符合 context files 的约定
   • 是否包含必要的确认标记（如 #verified）
   • 是否触发了预设的 hooks
3. 知识传递：用 /memory export > onboarding.md 生成培训材料

5. 避坑指南：血泪教训总结

5.1 上下文污染事件

现象：Agent 突然开始用 Python 语法写 JavaScript
根因：之前会话加载过 Python 教程文档未清理
解决方案：

bash复制/context clear  # 重置上下文
/context add --clean *.js  # 重新加载干净版本

5.2 记忆覆盖事故

现象：生产环境配置被测试数据覆盖
根因：未区分 #env:production 和 #env:test
改进方案：

bash复制/memory tag --env=production  # 打环境标签
/memory recall --env=production  # 按标签召回

5.3 工具逃逸漏洞

现象：Agent 试图读取 /etc/passwd
根因：bash 权限配置过于宽松
防护措施：

json复制{
  "sandbox": {
    "chroot": "/project",
    "read_whitelist": ["src/**", "config/*.json"]
  }
}

6. 进阶路线：从使用到精通

6.1 指标监控体系

建议监控这些关键指标：

• 上下文命中率：有效上下文占比
• 工具调用延迟：从请求到执行的耗时
• 记忆召回准确率：正确复用的记忆项比例
• Token 压缩比：compact 前后的体积变化

6.2 自定义扩展开发

典型的插件目录结构：

code复制my-plugin/
├── plugin.json      # 元数据
├── skills/          # 技能脚本
├── hooks/           |_ pre-request.js
├── templates/       # prompt 模板
└── mcp/             # 外部服务对接
    └── jira.js      # JIRA 集成

6.3 性能调优案例

问题：代码生成速度从 2 秒退化到 20 秒
分析步骤：

1. 用 /stats 发现上下文膨胀到 12k tokens
2. 检查 /context list 发现加载了冗余的测试图片
3. 通过 /context compact --aggressive 压缩到 4k tokens
4. 速度恢复至 3 秒以内

7. 工具链整合：融入开发生命周期

7.1 CI/CD 集成方案

yaml复制# .gitlab-ci.yml 片段
stages:
  - agent-review

agent_job:
  stage: agent-review
  image: claude-ci:latest
  script:
    - claude review-changes --risk-level=high
    - claude generate-test --coverage=80%
  rules:
    - changes: ["src/**", "!src/vendor/**"]

7.2 IDE 插件配置

json复制// VSCode 的 settings.json
{
  "claude.autoContext": {
    "onFileOpen": ["related"],
    "onError": ["stacktrace", "git-blame"]
  },
  "gemini.smartPrompt": {
    "framework": "React",
    "styleGuide": "Airbnb"
  }
}

7.3 团队知识图谱

mermaid复制graph LR
A[Agent 术语表] --> B(新成员培训)
A --> C{问题排查}
C -->|上下文问题| D[/context list/]
C -->|工具问题| E[/tools --debug/]
A --> F[架构设计]
F --> G[Subagent 拆分]
F --> H[权限矩阵]

（注：实际使用时需转换为表格形式以满足安全要求）

8. 长效维护策略

8.1 术语表更新机制

1. 每月审核新增的 Agent 功能
2. 用 /memory search "新术语" 扫描项目历史
3. 在 TERMS.md 中维护版本化记录：

markdown复制## v1.2 (2024-03)
- 新增 `LLM Gateway` 词条
- 废弃 `Plugin` 改用 `Extension`

8.2 跨工具迁移检查单

1. 系统提示转换：

   bash复制cat CLAUDE.md | sed 's/\/memory/\/preferences/g' > GEMINI.md
   

2. 权限映射审计：

   bash复制jq '.allowed_tools' .claude/settings.json > .gemini/permissions.yaml
   

3. 上下文文件适配：

   bash复制mv AGENTS.md CONTEXT.md && echo "#include legacy" >> CONTEXT.md
   

9. 终极测试：术语应用实战

9.1 故障排查场景

现象：Agent 生成的 API 文档格式混乱
诊断步骤：

1. 检查 system prompt 是否包含格式约束
2. 用 /context list 确认是否加载了样式模板
3. 查看 hooks 是否配置了自动格式化
4. 通过 /memory recall "文档规范" 检索历史约定

9.2 性能优化挑战

需求：将大型代码库的静态分析速度提升 3 倍
解决方案：

1. 创建 静态分析 subagent 专职处理
2. 配置 LSP 服务提供语义级分析
3. 用 MCP 接入 SonarQube 获取历史指标
4. 通过 LLM Gateway 路由到专用高性能模型

10. 资源索引：延伸学习路径

10.1 官方文档精要

10.2 社区最佳实践

1. Prompt 模式库：github.com/awesome-agent-patterns
2. Hooks 示例集：gitlab.com/agent-hooks-cookbook
3. 性能基准测试：agent-benchmarks.dev/compare

10.3 认证培训体系

1. 初级：Agent 概念与基础操作（4h）
2. 中级：工具链集成与调试（8h）
3. 高级：分布式 Agent 架构设计（16h）

11. 版本更新与反馈

本速查表遵循语义化版本控制，当前版本 v2.1.0 主要更新：

• 新增 Gemini 1.5 的上下文管理策略
• 补充 Codex 的云端线程实践
• 优化术语对照表的移动端显示

发现术语歧义或实践差异？建议通过以下方式反馈：

bash复制/claude feedback --category="术语表" --content="建议明确区分 memory 和 cache"