Agent 是什么？从零配一个属于自己的（以 Claude Code 为准）

一、什么是 Agent：从「会聊天」到「会干活」

你大概已经用过很多大模型：在对话框里问它问题，它给你一段解释、一段代码。然后呢？复制、粘贴、自己跑一遍、报错再回去问——中间那些体力活都是你在干。

Agent 的差别在于它有一双手。它能读你机器上的文件、执行命令、看到报错再改，直到任务做完。你不需要在中间当传声筒。

举个最小对比。你说「我的测试为什么挂了」，这是对话模型擅长的：它给出几种可能。你说「把挂掉的测试修好并跑通」，这才是 Agent：它会自己跑测试、读报错、找到相关代码、改掉、再跑一遍，然后把结果告诉你。

所以可以这么定义：Agent = 模型 + 工具 + 记忆 + 边界。 模型负责判断，工具让它能动手，记忆让它不必每次从零开始，边界决定它能动到什么程度。四样缺一样都不好用——只有模型是个聊天框，只有工具没有边界则是个危险的东西。

下面都以 Claude Code 作基准，因为它的文件约定清晰、公开文档完整，而且这套概念是通用的：换成别的命令行 Agent，模型和工具还在，只是文件名不一样。

二、Agent 有什么用：七件事，你可以现在就想

对话模型与 Agent：从「会说」到「会做」

读文件。 不用你贴上下文。它能自己按关键词、按目录去搜，把相关代码、配置、日志翻出来读（Claude Code 里对应 Read、Grep、Glob 这类工具）。

改文件。 改动直接落到磁盘上，不是给你一段"你可以这样改"。有 diff，能回滚，出问题看得见。

跑命令。 跑测试、装依赖、看日志、跑 git——这是它和对话框最本质的区别，也是"会干活"的入口。

记项目。 项目怎么跑测试、怎么起服务、你不希望它碰哪些目录，写一次，之后每次会话自动生效。Claude Code 里这份文件叫 CLAUDE.md。

连工具。 通过 MCP（Model Context Protocol，一个开放协议）把外部能力接进来：Notion、数据库、公司内部 API、浏览器。接进来之后它们就变成 Agent 可以直接调用的工具。

分活。 有些任务会淹掉主对话的上下文，比如"把整个仓库搜一遍"。这类活交给子代理去干，它跑完只把结论交回来。子代理还能单独指定模型，杂活交给便宜的那个。

技能。 把一套固定流程写成文件，之后一条命令就能复用，同事也能用同一份。Claude Code 里是 .claude/skills/<名字>/SKILL.md，叫法是 /名字。

七件事落到结构上其实是五个部件。

Agent 的五个部件：模型、工具、记忆、技能、权限

三、使用场景：谁在用，用它做什么

四类使用场景

写代码与维护。 修 bug（把报错贴给它，让它自己去找）、小步重构、补测试、升级依赖、读懂一个陌生的仓库。新人第一天最实用的一招：让 Agent 把项目结构讲一遍，比翻文档快。

运维与脚本。 排查日志里的异常、批量改配置、写部署脚本、做例行巡检。这类任务往往是"一串确定步骤 + 少量判断"，正好是 Agent 的舒适区。

信息与文档。 把散落的会议记录整理成一份结构化文档、批量重命名与归档、把乱糟糟的数据清洗成表。注意这类工作更依赖团队自己的规范和模板，写进记忆文件效果最好。

团队协作。 这是被低估的一块。团队规范死在 wiki 里没人看，但写成 CLAUDE.md 和 Skill 之后，它就变成了 Agent 每次干活都会带着的上下文。新人不用再问「我们的测试怎么跑」，Skill 里写着。

需要提醒一句：Agent 能动手，也就意味着它能在不该动的地方动手。所以第五节里，权限配置不是可选项。

四、用起来能带来什么：三件具体的事

少一次转录。 从「它说 → 你抄 → 你跑 → 你回报错 → 它再说」，变成「它自己跑」。省下的不是那几秒钟，是打断：你不需要在任务中途一直被叫回去。

沉淀复利。 一条纠正写进 CLAUDE.md 或一个 Skill，之后每次会话、每个同事都受益。这是 Agent 和对话框最不一样的地方——用得越久，它越贴合你的项目；不用，每次都是从零开始。

成本可控。 三处可控：权限上限定它能不能碰生产配置；模型上把简单活分给便宜模型；记录上所有配置都是仓库里的文件，谁改了什么一目了然。

同时把边界说清楚：Agent 不替你做决定，也不保证改对。它的产出仍然需要你看 diff、跑测试。把它当成一个手脚很快、但需要复核的执行者，比当成"自动完成一切"的工具更接近现实。

五、实战：从零配好一个能用的 Agent

从安装到跑通第一个任务：上手流程

下面九步，按顺序做完大约半小时。命令以 Claude Code 为准。

5.1 安装、诊断、登录

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# 也可以用包管理器
brew install --cask claude-code
npm install -g @anthropic-ai/claude-code   # 需要 Node 18+

装完先做一次体检，这个命令只读诊断、不会真的开一个会话：

claude doctor

它会把安装健康度、配置文件校验结果和注意事项打出来。如果提示找不到命令，先检查 PATH；版本可以随时换：

claude install stable      # 或 latest
claude update

然后在终端里敲 claude 进入会话，登录用 /login。订阅账号和 API key 都能登，登录成功后凭据会保存下来，后面不用反复输。

5.2 第一次进项目：让它自己写第一版记忆

cd ~/projects/your-project
claude

进去第一件事是 /init。它会读你的仓库，生成一份起步用的 CLAUDE.md，里面是构建命令、测试方式、项目约定。之后再 /memory 补充你不满意的地方。

CLAUDE.md 放在哪，决定了它的作用范围：

位置 作用范围
~/.claude/CLAUDE.md 你个人的偏好，所有项目都生效
./CLAUDE.md 或 ./.claude/CLAUDE.md 项目级，提交进仓库，同事共用
.claude/rules/ 按文件类型细分规则，比如只对前端目录生效

写什么最有价值？三类：怎么跑测试、怎么起服务、绝对不能碰的目录。代码风格里 Agent 自己能猜到的部分不用写。

篇幅要克制：单份控制在 200 行以内。 记忆文件越长，占用上下文越多，遵守度反而下降。写不下的按主题拆到 .claude/rules/ 去。

5.3 把重复流程写成技能

每周都做一次的流程，值得写成技能。文件放 .claude/skills/<名字>/SKILL.md（只给自己用就放 ~/.claude/skills/...）：

---
name: release-check
description: 发版前检查：跑测试、清理待办、核对版本号
---

1. 跑 npm test，只要失败就停下并报告失败用例
2. 搜索 TODO 和 FIXME，按文件列出
3. 核对 package.json 里的 version 与最近的 git tag 是否一致

输出一份检查清单。不要修改任何代码。

存好之后，在会话里输入 /release-check 就能叫它。技能文件遵循 Agent Skills 这个开放标准，别的支持该标准的工具也能用同一份。

旧的写法也还支持：.claude/commands/xxx.md 会变成 /xxx，文件里可以用 $ARGUMENTS 接收你传进来的参数——适合做「带一个参数的短流程」，比如 /review-pr 1234。

5.4 接工具：MCP

想让 Agent 用上外部系统，就把 MCP 服务器接进来：

# 远程服务（HTTP）
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 本地进程，需要环境变量就加 --env
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx server

claude mcp list 看已接入的清单，会话里用 /mcp 管理。想让团队共用，把配置落到项目根目录的 .mcp.json 并提交进仓库。

5.5 划权限：先收紧，再按需要放开

这一步最容易被跳过，但它决定了出事时你有多被动。权限写在 settings.json 里：项目共享的放 .claude/settings.json，个人的放 ~/.claude/settings.json。

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Read(./src/**)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "WebFetch(domain:example.com)"]
  },
  "defaultMode": "acceptEdits"
}

规则语法记住三条就够：写成 工具(参数)，参数里可以用 * 通配；路径 ./ 相对当前目录、~/ 相对家目录、// 是绝对路径；deny 优先于 allow。

会话里用 /permissions 可以交互式查看、增删规则，它还会告诉你每条规则来自哪个配置文件。遇到"要不要每次都问我"这个问题，一个好办法是先跑 /plan 进入计划模式——它只读不改，看完它的方案再决定放不放行。

底线两条：.env、密钥、生产配置直接 deny；它改完的代码自己过一遍 diff 再提交。

5.6 让它自动做该做的事：Hooks

Hooks 是"在特定时刻自动执行"的机制，配置也在 settings.json 里。常用的事件有四个：

  • PreToolUse：工具调用前触发，可以拦下这次调用
  • PostToolUse：调用成功后触发，典型用法是自动格式化、跑 lint
  • UserPromptSubmit：你提交提示词时触发，适合做记录或补充上下文
  • Stop：一轮结束时触发，比如发通知、写日志

配置字段的准确格式直接用 /update-config 让 Claude 帮你写，比手抠 JSON 靠谱。

5.7 不开界面也能用：非交互模式

给任何 claude 命令加上 -p，它就变成"跑一次就退出"：

claude -p "找出并修掉 auth.py 里的 bug" --allowedTools "Read,Edit,Bash"
claude -p "这个模块是干什么的" --output-format json
cat logs.txt | claude -p "解释这份日志里的报错"

前面那种交互模式里，权限可以现场问你；非交互模式没有人可以问，所以要显式用 --allowedTools 把工具权限交出去。--output-format json 的输出可以直接喂给你的脚本，放进 CI、发布流程、定时任务都行。

5.8 把重活分给子代理

子代理是独立上下文的助手，适合"搜索类、会淹掉主对话"的任务。文件放 .claude/agents/<名字>.md：

---
name: log-hunter
description: 在日志和仓库里找证据，只读不改，把结论汇报回来
tools: Read, Grep, Glob
model: haiku
---

你负责搜索，不负责修改。给出结论时必须引用文件路径与行号；
找不到相关证据就直接说没找到，不要猜。

好处有两个：主对话的上下文不再被搜索结果塞满；杂活可以指定便宜模型。命令行里 claude agents 可以查看和派发并行的后台会话。

5.9 最小可用清单

最小可用清单与 .claude 目录结构

今天就能做完的五件事：

  1. 装好并登录，claude doctor 没有报错
  2. 项目里跑 /init，然后手工补三行：测试怎么跑、服务怎么起、哪个目录别碰
  3. 写一个 SKILL.md，把每周重复一次的那个流程固化下来
  4. settings.json 里至少加一条 allow（比如你的测试命令）和一条 deny（比如 Read(./.env)）
  5. 挑一个真实的小任务交给它跑完一次——比如「把这个测试修好」，然后亲眼看着它读文件、改代码、跑测试

做完之后，你的目录大概长这样：

your-project/
├── CLAUDE.md              # 项目记忆（提交进仓库）
└── .claude/
    ├── settings.json      # 权限、hooks（提交进仓库）
    ├── skills/release-check/SKILL.md
    ├── agents/log-hunter.md
    └── commands/          # 旧的短命令写法，仍然可用

六、六个容易踩的坑

权限一把梭。 上来就全部自动批准，等于把机器的钥匙交出去。先收紧，用到哪条放哪条。

把密钥写进记忆文件。 CLAUDE.md 和 .claude/ 下的东西是要提交的，密钥、内网地址、客户数据都不该出现在里面。

把 CLAUDE.md 写成流水账。 超过 200 行就该拆，只留 Agent 自己猜不到的约定。

不看 diff 就提交。 Agent 会犯错，而且会很有信心地犯错。测试和 diff 是你的底线；/code-review 这类内置技能能帮忙，但代替不了你自己看。

上下文塞满还硬聊。 一个任务做完就 /clear，长会话中途用 /compact 压缩。上一件事的噪音会实打实降低下一件事的质量。

误以为它说「已修复」就是修好了。 让它跑测试、把通过的输出贴出来，比它的自我评价可靠得多。

一句话收尾：Agent 之间的差距，往往不在模型，而在你怎么给它记忆、工具和边界。先做清单里的第 1、2 条——明天你的 Agent 就开始认识你的项目了。