记忆系统与 Agent 定制完全指南（四）：自定义 Agent 开发（一）

---

title: 记忆系统与 Agent 定制完全指南（四）自定义 Agent 开发（一）------Agent 的定义与结构

date: 2026-07-10
category: AI 开发工具
tags: Claude Code, Agent, 自定义, 定义, 结构

记忆系统与 Agent 定制完全指南（四）：自定义 Agent 开发（一）

Agent 是 Claude Code 的"角色系统"------给它一个人设，它就变成那个领域的专家。本篇带你理解 Agent 的本质，从零开始定义一个专业的 Agent。

前言

Claude Code 内置了多种 Agent 类型：general-purpose、Explore、Plan、等等。但内置的 Agent 是通用的------它不懂你的项目规范、不懂你的技术栈、不懂你的团队习惯。

自定义 Agent 就是解决这个问题------定义一个专属角色，让它成为你项目的"专家"。

一、Agent 的本质

1.1 Agent vs 普通对话

普通对话：
  你说："帮我写个用户列表"
  Claude：生成代码（通用风格）

Agent 对话：
  你说："@frontend-developer 帮我写个用户列表"
  Claude：生成代码（符合团队规范、使用指定技术栈、遵循命名约定）

Agent 的核心区别在于：系统提示词不同。Agent 自带一套专业的人设和规范。

1.2 Agent 的组成

一个 Agent 由三部分组成：

┌─────────────────────────────────────────┐
│              Agent 定义                   │
├─────────────────────────────────────────┤
│  1. 身份信息（name, description）          │
│  2. 系统提示词（人设 + 行为规范）           │
│  3. 工具权限（可以使用哪些工具）            │
└─────────────────────────────────────────┘

1.3 Agent 的生命周期

定义 Agent（写 .md 文件）
    ↓
加载 Agent（启动 Claude Code 时自动识别）
    ↓
激活 Agent（@agent-name 或自然语言匹配）
    ↓
执行任务（按 Agent 的规范生成代码）
    ↓
退出 Agent（任务完成，回到普通对话）

二、Agent 的定义文件

2.1 文件位置

Agent 定义文件放在 .claude/agents/ 目录下：

your-project/
├── .claude/
│   └── agents/
│       ├── backend-developer.md    # 后端开发 Agent
│       ├── frontend-developer.md   # 前端开发 Agent
│       ├── code-reviewer.md        # 代码审查 Agent
│       └── devops-engineer.md      # DevOps 工程师 Agent
├── src/
└── CLAUDE.md

2.2 文件格式

Agent 文件也是一个 Markdown 文件，包含 frontmatter 和正文：

---
name: agent-name
description: 一句话描述这个 Agent 的职责
model: sonnet        # 可选：指定使用的模型
effort: medium       # 可选：推理强度（low/medium/high/xhigh/max）
---

# Agent 名称

## 角色定义
你是谁，你的专业领域是什么

## 职责
你应该做什么

## 规范
你应该遵循哪些规范

## 禁忌
你不应该做什么

2.3 Frontmatter 字段

字段	必填	说明
name	是	Agent 唯一标识，kebab-case
description	是	一句话描述，用于匹配触发
model	否	指定模型（sonnet/opus/haiku/fable）
effort	否	推理强度，复杂任务用 high/xhigh

三、实战：定义一个前端开发 Agent

3.1 场景

你们团队的前端开发有一套严格的规范：

• Vue 3 + Composition API + script setup
• TypeScript 严格模式
• Element Plus 组件库
• Pinia 状态管理
• 统一的 API 封装和类型定义

把这些规范写进一个 Agent，以后说"@frontend-developer 帮我做个页面"，Claude 就自动按团队规范生成代码。

3.2 Agent 定义

---
name: frontend-developer
description: 负责 Vue 3 前端开发，使用 Composition API、TypeScript、Element Plus
model: sonnet
effort: medium
---

# 前端开发 Agent

## 角色定义

你是一个资深 Vue 3 前端开发工程师，拥有 8 年以上企业级应用开发经验。
你精通 Vue 3 Composition API、TypeScript、Element Plus、Pinia 等技术栈。

## 技术栈

- **框架**：Vue 3 + Composition API（`<script setup lang="ts">`）
- **语言**：TypeScript（严格模式）
- **构建**：Vite
- **UI 库**：Element Plus
- **状态管理**：Pinia
- **路由**：Vue Router 4
- **HTTP**：Axios（通过 `@/utils/http.ts` 封装）
- **图表**：ECharts（通过 vue-echarts 集成）

## 编码规范

### 组件开发
- 使用 `<script setup lang="ts">` 语法
- 组件文件名使用 kebab-case（如 `user-list.vue`）
- 组件目录使用 PascalCase（如 `views/UserList/`）
- 每个页面组件应包含：搜索区、表格区、分页区、弹窗表单

### 类型定义
- 所有接口和类型定义放在 `@/types/` 目录
- 接口使用 `interface` 而非 `type`
- 泛型命名使用 `<T = any>` 默认值

### API 调用
- 统一使用 `@/utils/http.ts` 中的 `get/post/put/del` 方法
- API 函数放在 `@/api/` 目录
- 函数命名使用动词+名词：`getUserList`、`createUser`、`updateUser`

### 状态管理
- 使用 Pinia（不是 Vuex）
- Store 文件放在 `@/store/modules/`
- 使用 Setup Store 语法（`defineStore` 函数式）

### 样式
- 使用 scoped CSS
- 样式变量通过 CSS 自定义属性（CSS Variables）管理
- 不内联样式，使用 class 绑定

## 目录结构

src/

├── api/ # API 接口

├── components/ # 公共组件

├── layouts/ # 布局组件

├── router/ # 路由配置

├── store/ # Pinia Store

├── types/ # TypeScript 类型

├── utils/ # 工具函数

├── views/ # 页面组件

└── assets/ # 静态资源

## 常见任务

### 创建页面组件
1. 创建 `src/views/Module/index.vue`
2. 创建 `src/api/module.ts`
3. 创建 `src/types/module.ts`
4. 更新路由配置（如需）

### 创建公共组件
1. 创建 `src/components/ComponentName.vue`
2. 定义 Props 和 Emits 类型
3. 添加 JSDoc 注释

### 创建 Store
1. 创建 `src/store/modules/module.ts`
2. 定义 State、Getters、Actions
3. 在主 Store 中注册

## 禁忌

- 不使用 Options API（`data()`、`methods()`）
- 不使用 Vuex（使用 Pinia）
- 不直接使用 axios（使用 `@/utils/http.ts` 封装）
- 不在组件中硬编码 API 地址
- 不生成 JavaScript 代码（必须用 TypeScript）

3.3 使用这个 Agent

@frontend-developer 帮我创建一个设备列表页面

Claude 会以"前端开发工程师"的身份，按照团队规范生成代码：

好的，我来创建设备列表页面。

按照团队规范，我需要创建：
1. src/views/Device/index.vue --- 设备列表页面
2. src/api/device.ts --- 设备 API
3. src/types/device.ts --- 类型定义
4. 更新路由配置

开始创建...

四、Agent 的触发方式

4.1 显式调用

@frontend-developer 帮我写个搜索功能

4.2 自然语言匹配

帮我写个前端页面

Claude 根据 description 字段匹配到 frontend-developer Agent。

4.3 上下文推断

（当前正在讨论后端代码）
帮我写个后端接口

Claude 推断你需要后端相关的 Agent，匹配 backend-developer。

五、这一章的核心心得

1. Agent = 角色 + 规范------定义 Agent 就是定义一个专家人设
2. 文件是 Markdown------不需要编译，不需要打包，写即用
3. 三个核心字段------name（标识）、description（匹配）、model/effort（可选）
4. 规范要具体------越具体的规范，生成的代码越符合团队要求
5. 禁忌同样重要------告诉 Agent 不做什么，和不告诉它做什么一样关键
6. 触发方式多样------可以显式 @ 调用，也可以自然语言匹配

六、下一步

认识了 Agent 的定义和结构，下一篇我们将深入 Agent 的工具与权限------每个 Agent 可以使用哪些工具？如何限制 Agent 的能力范围？

---

系列目录：

1. 初识记忆系统------什么是记忆？为什么需要记忆？
2. 记忆文件编写规范------怎么写一条好的记忆
3. 记忆的检索与使用------Claude 如何在对话中调用记忆
4. 自定义 Agent 开发（一）------Agent 的定义与结构 ← 本篇
5. 自定义 Agent 开发（二）------Agent 的工具与权限（待写）
6. Agent 编排与调度（待写）
7. Agent 与工具的深度集成（待写）
8. 记忆系统与 Agent 配合------构建智能开发助手（待写）