新人上手指南

欢迎加入使用 AI 辅助编程的团队。对于刚接触 AI 编程工具的开发者来说，工具本身不难学，难的是建立正确的协作心态——知道什么时候信任 AI，什么时候质疑它，什么时候完全依靠自己。

本指南提供一条循序渐进的学习路径，帮助你在 2-4 周内从"偶尔试用"过渡到"高效日常使用"。

---

学习路径总览

第 1 周：建立基础认知
    └── 了解工具能力边界，完成配置，阅读团队规范

第 2 周：补全模式（Completion）
    └── 用 AI 补全代码，学会主动接受或拒绝建议

第 3 周：对话模式（Chat）
    └── 用自然语言描述需求，生成代码片段并迭代

第 4 周：Agent 模式（自主任务）
    └── 让 AI 执行多步骤任务，学会验证和修正结果

---

第一步：工具配置与基础认知

环境配置

按照团队规范完成工具安装（参考团队 AI 编程公约中的工具标准化章节）。完成后逐项确认：

• [ ] IDE 插件已启用并连接到团队账号
• [ ] 已阅读并理解团队 AI 编程公约
• [ ] 了解哪些场景禁止使用 AI（安全模块、敏感数据处理）
• [ ] 已加入团队 Prompt 库仓库并浏览了一遍目录
• [ ] 已设置 .cursorignore 或对应的忽略配置，排除敏感文件

第一周必读材料

资源	说明	预计时间
团队 AI 编程公约	了解使用边界和责任归属	30 分钟
本文档站工具使用章节	了解 Cursor/Copilot 的核心功能	1 小时
团队 Prompt 库 README	了解如何查找和使用团队积累的模板	15 分钟
所用 AI 工具官方文档	了解工具的最新能力和限制	1 小时

不需要在第一周内精通所有内容。重点是建立对工具能力边界的基本认知，以及对安全规范的理解。

---

第二步：补全模式入门

补全（Completion）是最容易上手的模式，AI 在你打字时实时建议代码，你可以选择接受或忽略。

核心技巧

用注释引导 AI

在函数前写清晰的注释，然后按 Tab 触发补全：

# 计算列表中所有正数的平均值，如果没有正数则返回 0
def average_positive(numbers: list[float]) -> float:
    # AI 会在这里生成实现

函数签名先行

写好函数名、参数和返回类型，让 AI 补全实现：

async function fetchUserWithRetry(
  userId: string,
  maxRetries: number = 3
): Promise<User> {
  // AI 会建议完整的重试逻辑实现
}

主动拒绝不合适的建议

按 Escape 拒绝当前补全，继续自己写。不要因为 AI 给了建议就感到"有义务接受"。主动拒绝错误建议，并继续自己的思路，是建立良好使用习惯的关键。

第二周练习任务

• 用补全模式完成一个 CRUD 模块（从零到可运行）
• 有意识地记录自己拒绝了哪些建议，以及原因
• 尝试用不同详细程度的注释引导 AI，观察输出质量的变化

---

第三步：对话模式进阶

对话模式（Chat）让你用自然语言描述需求，适合生成较长的代码段或解释复杂逻辑。这一模式对 Prompt 质量更敏感。

提问技巧：从具体到通用

越具体越好。模糊的问题会得到模糊的答案：

❌ 差的提问：帮我写一个用户认证功能

✓ 好的提问：
使用 Express.js + JWT，实现用户登录接口：
- POST /api/auth/login
- 接受 email 和 password
- 密码用 bcrypt 验证
- 登录成功返回 accessToken（有效期 1h）和 refreshToken（有效期 7d）
- 登录失败返回 401，不透露是邮箱还是密码错误（安全考虑）
- 使用项目统一错误格式：{ error: string, code: string }

提问技巧：提供上下文

当问题与现有代码相关时，提供相关代码片段，避免 AI 凭空推断：

我有以下 User 模型（TypeScript）：
[粘贴相关代码]

请帮我生成对应的 Zod 验证 Schema，用于 API 输入验证。
要求与项目现有的验证风格保持一致（schema 变量命名为 xxxSchema）。

提问技巧：分步骤迭代

不要一次要求太多。先生成核心逻辑，再逐步添加细节：

第一轮：先实现基础的登录核心逻辑
第二轮：帮我加上速率限制（每 IP 每分钟最多 5 次）
第三轮：帮我加上登录日志记录，格式符合项目日志规范

分步迭代的好处：每步输出更可控，更容易发现问题，也更容易针对性地修改。

第三周练习任务

• 用对话模式完成一个之前手写会花 2 小时以上的功能
• 练习用迭代方式精炼 AI 输出，而不是接受第一版
• 从团队 Prompt 库中选一个模板实际使用，并记录使用体验

---

第四步：Agent 模式（自主任务）

Agent 模式（如 Cursor Agent、Claude Code）可以让 AI 自主执行多步骤任务：读文件、写代码、运行命令、调用工具。这是效率最高但风险也最高的模式。

使用原则

• 沙箱优先：在测试分支或临时目录中尝试 Agent 任务，不要在主分支或生产相关分支上直接运行
• 分阶段确认：将大任务拆成若干阶段，每阶段 Review 后再继续，不要让 Agent 一次性完成过多步骤
• 保持监控：在 Agent 运行期间保持关注，不要完全放手等结果，尤其是涉及文件写操作的任务

适合 Agent 的任务

✓ 批量重构（如统一替换旧 API 调用为新版本）
✓ 生成一套完整的测试文件（基于现有实现）
✓ 根据现有代码生成 API 文档或类型定义
✓ 初始化新模块的脚手架代码（目录结构、基础文件）
✓ 代码库范围内的重命名或格式统一

不适合 Agent 的任务

✗ 涉及生产数据库的操作（Agent 操作不可逆风险高）
✗ 需要深度理解业务上下文的核心逻辑编写
✗ 跨多个服务的架构级调整
✗ 安全敏感模块的编写

第四周练习任务

• 用 Agent 模式完成一个批量任务（如为某个目录下所有函数生成测试）
• 记录 Agent 完成后你实际修改了哪些内容，积累对 Agent 输出质量的判断经验

---

新手常见错误与规避方法

错误类型	具体表现	规避方法
过度信任 AI	不 Review 直接提交，出 bug 后说"AI 写的"	每次提交前用自检清单逐项核对
无效 Prompt	描述模糊，反复重试却不反思提问方式	参考团队 Prompt 库模板，学习提问结构
把 AI 当权威	直接用 AI 查的 API，不去官方文档确认	重要 API 必须对照官方文档核实
忽略测试	AI 生成代码后觉得"任务完成了"	将测试纳入 AI 任务的一部分，生成代码同时生成测试
泄露敏感信息	为求方便直接贴生产配置、用户数据	提问前检查并替换敏感内容为占位符
上下文切换低效	频繁在 AI 和编辑器间切换，割裂工作流	优先使用集成在 IDE 内的 AI 工具
接受第一版输出	不迭代精炼，接受质量参差的第一版	将迭代精炼作为标准流程，至少审视 2-3 轮

---

技能发展路径

完成基础上手后，继续提升的方向：

短期目标（1-3 个月）

• 掌握所有常用任务类型的提问技巧，形成肌肉记忆
• 能够独立识别并修复 AI 生成代码的常见问题（幻觉 API、安全盲区）
• 开始向团队 Prompt 库贡献自己验证过的模板

中期目标（3-6 个月）

• 形成"AI 优先，人工把关"的自然工作节奏，不再需要刻意提醒自己
• 能够根据任务类型选择最合适的 AI 工具和使用模式（补全、对话、Agent）
• 能够指导其他新人上手，成为团队内的 AI 使用参考点

长期目标（6 个月以上）

• 参与团队 AI 使用规范的制定和迭代，将实战经验转化为团队规范
• 发现并推广新的 AI 使用场景，拓展团队的工具使用边界
• 在团队中成为 AI 编程最佳实践的推动者和知识传递者

---

推荐资源

内部资源（优先）

资源	位置
团队 AI 编程公约	本文档站 > 团队协作规范
AI 代码 Review 要点	本文档站 > 团队协作规范
团队 Prompt 库	内部 Git 仓库（team-prompts）
工具使用章节	本文档站 > 工具链指南

外部资源

资源	说明
Anthropic Claude 官方文档	Prompt 工程最佳实践
GitHub Copilot 文档	补全模式高级技巧
Cursor 官方教程	Agent 模式实战案例
AI 工具各自的 Discord 社区	实时技巧分享和问题解答

---

导师制建议

如果你是团队负责人，建议为 AI 编程新人安排一位有经验的导师：

• 第一周：导师陪同完成第一个 AI 辅助任务，讲解使用思路而非替代操作
• 每周 Check-in：15-30 分钟，交流本周遇到的问题和发现的技巧
• 首次 PR：导师对第一个包含 AI 代码的 PR 进行详细 Review，解释每条反馈的原因
• 四周评估：确认新人是否已建立安全的 AI 使用习惯，可以独立作业

好的导师不是替新人做决定，而是帮助他们建立独立的判断能力。AI 工具变化很快，最终目标是让新人掌握"如何判断 AI 输出质量"的元能力，而不只是会用某一个具体工具。