新手前 30 分钟
系列入口：如何使用 Agent。客户端具体怎么挑，看 VS Code 里的 Agent 和 Claude Code CLI。
一、目标：30 分钟内安全地完成第一次
这篇不追求把功能讲全，只想让你在半小时内真的让 Agent 干成一件小事、并且全程心里有底。第一次的体验很关键：走得顺，你才有信心继续；一上来就不知道它在干嘛、或者误开了自动执行被吓到，很容易就此放弃。
建议你准备一个无关紧要的练习项目，或者一个已经 git commit、随时能还原的仓库，别拿重要代码第一次试水。
二、第 1~5 分钟：装好、打开项目、确认权限
安装具体步骤因客户端而异，装好后有三件事一定要确认：
- 它打开的是你想操作的项目目录，不是某个上级或空目录。让它「列出当前项目的文件」，看返回的是不是你熟悉的结构。
- 它具备读写文件和运行命令的能力。多数 Agent 默认在你授权后才执行命令，这是正常的，不要为了省事一开始就全开。
- 看一眼权限/信任设置。很多工具会区分「信任此目录」和受限模式，第一次用默认的、偏保守的设置即可。
如果是在 Windows 上，终端 Agent 还可能遇到 PATH、编码和代理问题，真碰到了再按报错处理，不用提前紧张。
这三步确认不是走过场，它们决定了后面整个体验。给你一个可以直接照着发的验证指令：「请列出当前项目根目录的文件和一级子目录，并告诉我你现在所在的工作目录路径。」一个正常接入项目的 Agent 会返回真实的目录结构和一个你认得的绝对路径。如果它返回的路径是别的盘、是用户主目录、或者它说「我无法访问文件系统」，那就先别往下走——后面两件事分别对应「目录开错了」和「没给工具权限」，都要先解决。
新手在这里最常犯的错，是还没确认目录对不对、权限有没有，就急着下任务，结果 Agent 要么在错误的目录里忙半天，要么只能凭空给建议，最后得出「这工具不行」的结论。其实问题出在第一步没打通。花两分钟做这个验证，是整个前 30 分钟里性价比最高的动作。
三、第 5~10 分钟：先给自己留退路
动手发任务之前，做一个现在看着多余、但能救命的动作：
git status # 确认当前工作区
git checkout -b agent-practice # 新建一个练习分支
# 或者至少 git add . && git commit -m "snapshot before agent"有了这个快照，待会儿不管 Agent 改成什么样，你都能用 git checkout . 或切回分支一键还原。新手最常见的慌，就是改完不知道怎么变回去——这一步直接把这个慌消除。
四、第 10~20 分钟：下一个小任务，先 Plan
选一个范围很小、对错一看便知的任务，比如：
- 「给
utils.ts里的formatDate函数补充单元测试」 - 「把这个文件里的
var改成const/let」 - 「解释一下
main函数从输入到输出做了什么」
发任务时顺手说清范围（在哪个文件、别碰别的地方）。然后关键的一步：先用 Plan 模式。
- Plan（计划）模式：Agent 只分析、出一份「我打算怎么做」的方案，不会真的改文件。你看完方案，确认它理解对了、步骤合理，再放行。
- Act（执行）模式：它真正动手改文件、跑命令。
第一次一定要先看 Plan 再进 Act，这样你能在它动手前就发现「哦它理解偏了」。模式切换一般在输入框附近，不同工具叫法可能是 Plan/Act、Ask/Code、Architect 等，含义相同。
给你一段完整的第一次对话，大致长这样，照着感觉走即可：
你：给
src/utils/format.ts里的formatDate补单元测试。只动这个文件和对应的测试文件，别改其他地方。先给我计划。Agent（Plan）：我打算先读
formatDate的实现，确认它接收什么参数、返回什么格式、对非法输入怎么处理；然后在同目录的format.test.ts里补三类用例：正常日期、边界值（月初月末、跨年）、非法输入；最后跑这个测试文件确认通过。不会修改函数实现本身。你：（确认它理解对了）可以，执行。
Agent（Act）：（读取文件 → 新增测试 → 运行测试）3 个 describe、共 8 条用例全部通过，只改了
format.test.ts，没有动实现。
注意你那句话里的几个关键零件：目标（补单测）、范围（只动两个文件）、节奏（先给计划）。第一次就把这三个零件说全，后面会变成你的本能。如果它的计划里出现了你没要求的东西（比如「我会顺便重构一下这个函数」），就在 Plan 阶段砍掉，别等它动手。
五、第 20~28 分钟：审批执行，看懂安全开关
进入执行后，你会遇到两个反复出现的东西，先认清它们：
- 审批弹窗（Approval）：它要改文件、尤其要跑命令时，会停下来问你。第一次请逐条看、逐条批，不要点「始终允许」。 这是你和它之间最重要的安全闸门。
- 自动执行 / 自动批准开关：开了它，Agent 可以不经确认连续操作。新手阶段请保持关闭；等你清楚哪些命令安全、并学会写 Hooks 之后，再考虑有限度放开。
看着它一步步做，比一次性放权安全得多，也让你更快建立直觉。
第一次你可能会在设置里看到好几个含义相近的开关，这里一次讲清它们分别意味着什么，避免你凭感觉乱开：
- 只读 / 受限模式：Agent 只能看，不能改也不能执行。最安全，适合让它先理解项目、给讲解，但完不成动手任务。
- 正常（每次确认）模式：它可以改文件、跑命令，但每个写操作和命令都要你点同意。新手应停留在这里。
- 自动批准文件编辑：改文件不再逐次问你，但跑命令仍要确认。等你对它的改动质量有信心后可考虑，因为文件改动至少能用 git 回滚。
- 自动执行命令 / 全自动（YOLO）模式：连命令都不再问，连续自主执行。风险最高，只建议在隔离环境、且任务全程可逆可验证时短暂使用，新手阶段不要碰。
记住判断放权程度的两条主线：这个动作可不可逆、出了问题能不能自动发现。 文件编辑多为可逆（有 git），所以比命令更容易放权；命令里只读操作（ls、git status）几乎无害，而写入、删除、外联操作风险陡增。新手不用记具体命令清单，先建立「可逆 + 可验证才放手」这条直觉即可。
还有一个概念顺带说清：审批弹窗里常见的「仅此次允许 / 本会话始终允许 / 拒绝」三选项。第一次请只用「仅此次」，因为「始终允许」会让这条规则在你不再留意的情况下持续生效——你以为自己还在逐条把关，其实对某一类动作已经悄悄放权了。等你明确知道某类命令绝对安全，再使用「始终允许」也不迟。
六、第 28~30 分钟：检查结果，必要时回退
跑完之后别急着关，做三件事验收：
git status # 看它动了哪些文件
git diff # 逐行看改动，是不是只改了你允许的范围
# 如果项目有测试：跑一遍测试- 改动符合预期、测试通过：太好了，第一次成功，commit 保留即可。
- 改得不对或越界：直接回退——
git checkout .（丢弃未提交改动）或删掉练习分支，回到开始前，再来一次，没有任何损失。
这里把回退讲具体一点，新手真到要回退时往往会发慌。分三种情况：
- 改动还没提交，想全部丢弃：先
git status看清楚，确认里面没有你自己想留的东西，然后git checkout .（丢弃所有已跟踪文件的改动）。注意它不会删除新建的未跟踪文件，那些文件确认无用后手动删除即可。 - 改动已经提交了，但想回到开始前：用
git log --oneline找到练习前那个提交的 SHA，然后git reset --hard <那个SHA>，就能精确回到当时状态。 - 只想丢某一个文件的改动：
git checkout -- 路径/文件名，只还原这一个文件，其他保留。
第一次操作前先读懂这三条，你就不会在「想撤销又怕搞坏」之间纠结。还是那句核心建议：第一次最好在专门的练习分支上做，这样主分支永远干净，最坏情况也只是删掉这个分支，几乎不可能伤到正式代码。
| 环节 | 第一次的原则 |
|---|---|
| 项目 | 用练习项目或可还原的仓库 |
| 模式 | 先 Plan 看懂，再 Act |
| 审批 | 逐条确认，不开自动执行 |
| 验收 | git diff + 跑测试，不行就回退 |
七、第一次最容易卡住的几个地方
把新手高频卡点和对应处理列在这里，遇到直接对号入座：
- 它说找不到文件 / 目录是空的。 多半是打开的工作目录不对，或者根本没授权访问。回到第 1 步重新确认工作目录路径和文件权限。
- 命令跑不了，提示权限被拒。 多数 Agent 默认命令需要逐条授权，这是安全设计，点允许即可；如果是终端类工具，检查执行策略和 PATH。
- 它只在对话里给代码，文件没变。 说明你用的是对话（L2）形态，或没切到执行模式。确认当前模式是 Act/Code，并确认它真的调用了写文件的工具。
- 改完测试报错，我看不懂。 先别慌，这正是快照的意义。直接
git checkout .回到开始前，把任务范围说更小、更清楚，再来一遍，没有任何代价。 - Windows 上中文乱码或命令行为异常。 多为编码和环境差异，确认终端用 UTF-8；这类问题按报错具体处理，不影响你理解 Agent 的核心用法。
记住一个原则：第一次遇到任何让你心里没底的情况，优先回退，而不是硬着头皮继续点允许。 有快照兜底，你永远可以安全地重来。
八、第一次的心态：这半小时，慢就是快
最后说点非技术、但很影响第一次体验的事。
新手常有两种冲动：一种是「赶紧看看它有多神」，于是跳过确认、直接放权、挑个大任务，结果要么被越界改动吓到，要么因为看不懂它在干嘛而更不信任；另一种是「我得先把原理都学明白才敢碰」，于是看了一堆教程却迟迟不发第一个任务。这两种都不是好节奏。
这 30 分钟最好的心态是把目标定得极小、把节奏压得极慢：不追求看到惊艳效果，只追求「我清楚地知道它每一步在做什么、为什么做、出了问题怎么退」。你逐条审批、逐行看 diff，看似比全自动慢，但这半小时建立起来的安全感和直觉，会让你后面几个月敢放心地把越来越多的事交给它——这才是真正的快。
换个角度，你可以把第一次当成「带一个能力很强、但完全不了解你项目的新同事」：你不会第一天就把整个系统甩给对方并让他直接上线，你会先让他看、先对齐做法、先做一件小事、你过目，确认靠谱后再逐步加码。对待 Agent 也是一样，这个比喻在整个系列里会反复出现，因为它最能说明人和 Agent 之间健康的关系。
等你走完这五步、看着一件小事真的被它干净利落地做完，你对这个工具的感觉会从「听说很强」变成「我知道怎么让它为我干活」——这一步认知的跨越，比任何功能介绍都重要。
九、30 分钟之后，建议这样继续
走完第一次，你已经跨过最难的门槛。接下来几天可以按这个顺序加码，每一步都等上一步顺手了再进：
- 继续在放手区多练：补测试、改名、查代码、解释逻辑，把「目标 + 范围 + 先计划」的指令方式练到不用想。
- 试着让它做一个跨两三个文件的小重构，仍然先 Plan、逐条审批、用完整测试验收。
- 开始写一份最简单的项目规则，把「包管理器、目录约定、不要做的事」写进去，体会上下文对结果的影响。
- 等你清楚哪些命令绝对安全，再去研究 Hooks 和有限度的自动执行——顺序不要反，先理解风险再放权。
十、常见问题
Q：第一次一定要用 git 吗？我只是随便试试。 强烈建议。git 快照是你敢放心让它动手的心理前提，也是最便宜的后悔药。哪怕只是一个临时练习目录，git init 一下成本极低。没有版本兜底就让工具改文件，等于没系安全带上路。
Q：审批弹窗太多很烦，能不能先放开一点？ 烦，恰恰说明它在认真征求授权。新手阶段请忍住，逐条批的过程就是你最快建立「哪些动作安全」直觉的过程。等你能预判它要做什么、也配好了规则和钩子，再有限度放开才稳妥。
Q：我第一次让它做，结果它改得比我说的多，正常吗？ 常见，但不该放任。这通常是范围没说清，或它「热心」越界。解决办法是在指令里明确边界（只动哪些文件、不要改实现），并在 Plan 阶段就砍掉计划外动作，而不是等改完再后悔。
Q：是不是必须懂命令行才能用？ 不是。IDE 里的 Agent 大多图形化操作，审批、看 diff 都在界面里完成。命令行只是其中一种客户端形态。你完全可以从插件版开始，熟悉概念后再决定要不要碰 CLI。
总结
第一次用 Agent 的正确打开方式是：留好快照、下个小任务、先 Plan 再 Act、逐条审批、用 git diff 验收——把这五步走一遍，你就从「不敢用」跨过了最关键的一道坎。