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

title: 记忆系统与 Agent 定制完全指南四自定义 Agent 开发一——Agent 的定义与结构date: 2026-07-10category: 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 时自动识别 ↓ 激活 Agentagent-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.md2.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-casedescription是一句话描述用于匹配触发model否指定模型sonnet/opus/haiku/fableeffort否推理强度复杂任务用 high/xhigh三、实战定义一个前端开发 Agent3.1 场景你们团队的前端开发有一套严格的规范Vue 3 Composition API script setupTypeScript 严格模式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 APIscript setup langts - **语言**TypeScript严格模式 - **构建**Vite - **UI 库**Element Plus - **状态管理**Pinia - **路由**Vue Router 4 - **HTTP**Axios通过 /utils/http.ts 封装 - **图表**ECharts通过 vue-echarts 集成 ## 编码规范 ### 组件开发 - 使用 script setup langts 语法 - 组件文件名使用 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 APIdata()、methods() - 不使用 Vuex使用 Pinia - 不直接使用 axios使用 /utils/http.ts 封装 - 不在组件中硬编码 API 地址 - 不生成 JavaScript 代码必须用 TypeScript3.3 使用这个 Agentfrontend-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。五、这一章的核心心得Agent 角色 规范——定义 Agent 就是定义一个专家人设文件是 Markdown——不需要编译不需要打包写即用三个核心字段——name标识、description匹配、model/effort可选规范要具体——越具体的规范生成的代码越符合团队要求禁忌同样重要——告诉 Agent 不做什么和不告诉它做什么一样关键触发方式多样——可以显式 调用也可以自然语言匹配六、下一步认识了 Agent 的定义和结构下一篇我们将深入 Agent 的工具与权限——每个 Agent 可以使用哪些工具如何限制 Agent 的能力范围系列目录初识记忆系统——什么是记忆为什么需要记忆记忆文件编写规范——怎么写一条好的记忆记忆的检索与使用——Claude 如何在对话中调用记忆自定义 Agent 开发一——Agent 的定义与结构← 本篇自定义 Agent 开发二——Agent 的工具与权限待写Agent 编排与调度待写Agent 与工具的深度集成待写记忆系统与 Agent 配合——构建智能开发助手待写