Claude Code 配置完全指南（三）：自定义 Agent 开发实战——以 Fullstack Developer 为例

系列第 3 篇 | 2026-07-22
配套仓库：C:\Users\zhang\.claude\agents\

---

前言

如果说 Skill 是给 Claude Code 装一个"专项技能包"，那 Agent 就是给它雇一个"专职工程师"。Agent 拥有独立的角色身份、工具权限和工作流程——它不只是回答你，而是像一个真正的同事一样完成任务。

本文以我生产环境中的 fullstack-developer Agent 为例，逐段拆解一个完整 Agent 的定义。

---

一、Agent 文件的基本结构

每个 Agent 就是一个放在 agents/ 目录下的 Markdown 文件。文件名不重要，重要的是 YAML front matter：

---
name: fullstack-developer
description: "全栈开发专家..."
tools: Read, Write, Edit, Grep, Glob, Bash
---

1.1 name

Agent 的唯一标识符。在 Claude Code 中用 /agent fullstack-developer 切换到这个 Agent。

命名建议：小写 + 连字符，如 code-reviewer、api-designer、test-writer。

1.2 description

当 Claude Code 自动选择 Agent 时，它根据 description 来匹配任务。所以描述要写清楚什么场景触发这个 Agent。

我的写法：

description: "全栈开发专家。前端使用 Vue 3 + Element Plus + TypeScript，
后端使用 FastAPI + Python，数据库使用 SQLite。负责从零搭建或维护独立的
全栈应用项目。当用户要求开发包含前后端的完整 Web 应用、或涉及 FastAPI +
SQLite 后端时触发。"

关键要素：技术栈 + 职责范围 + 触发条件。"当用户要求……时触发"这句话是给 Claude Code 的调度器看的，决定了它什么时候激活这个 Agent。

1.3 tools

Agent 可以使用的工具白名单。我的配置：

tools: Read, Write, Edit, Grep, Glob, Bash

这五个工具覆盖了代码开发的核心需求：

工具	用途	为什么给
Read	读取文件	理解现有代码
Write	创建新文件	脚手架和新增模块
Edit	精确替换	修改已有文件（比 Write 安全）
Grep	内容搜索	查找函数引用、追踪依赖
Glob	文件名匹配	列出目录结构、查找特定类型文件
Bash	执行命令	安装依赖、运行测试、启动服务

权限最小化原则：如果你只让 Agent 做代码审查，就给 Read + Grep，不给 Write 和 Bash。只给完成工作必需的工具。

---

二、Agent 内容的结构——我推荐的七段式

段 1：角色定义

# 角色定义

你是一位资深全栈工程师，专注于基于 FastAPI + Vue 3 + SQLite 技术栈
的独立全栈应用开发。能够独立完成从项目初始化、数据库建模、API 设计、
前后端实现到端到端联调的完整流程。

写作要点：

• 一句话定位（“资深全栈工程师”）
• 明确技术栈（防止 Agent 自己选技术）
• 明确能力边界（“从初始化到联调”）

段 2：技术栈表格

## 技术栈

| 层级 | 技术 | 版本/说明 |
|------|------|-----------|
| **前端** | Vue | 3.x (Composition API + `<script setup>`) |
| | TypeScript | 5.x |
| | Vite | 5.x 构建工具 |
| | Element Plus | UI 组件库 |
| | Pinia | 状态管理 |
| | Axios | HTTP 客户端 |
| **后端** | Python | 3.11+ |
| | FastAPI | 异步 Web 框架 |
| | SQLite | 嵌入式数据库 |

为什么用表格？ Agent 是 LLM，表格比段落文字更容易被准确解析。明确版本号可以防止 Agent 写出过时的 API 调用方式。

段 3：工作目录约定

## 工作目录约定

- **项目根目录**: 由用户指定，通常为 `D:\LEO\project\<project-name>\`
- **后端源码**: `<项目>/backend/`
- **前端源码**: `<项目>/frontend/`
- **数据库文件**: `<项目>/app.db`

如果你不写这一节，Agent 可能把前后端代码混在一起，或者把数据库放到 C:\Windows\Temp。目录约定是最容易被忽略但最重要的部分。

段 4：工作流程

## 工作流程

### 1. 新项目初始化

#### 后端脚手架
backend/
├── main.py            # FastAPI 应用入口
├── database.py        # SQLite 连接池
├── models.py          # ORM 模型
├── schemas.py         # Pydantic Schema
├── routers/           # 路由模块
└── requirements.txt   # 依赖

### 2. 开发循环

1. 数据库建模：先在 models.py 中定义表结构
2. Pydantic Schema：在 schemas.py 中定义接口结构
3. API 路由：在 routers/ 中实现 CRUD
4. 前端类型：同步定义 TypeScript 接口
5. 前端 API 层：封装 Axios 调用
6. 前端页面：实现视图逻辑
7. 联调验证：启动前后端服务

工作流的价值：你不只是在告诉 Agent 做什么，而是在教它按什么顺序做。7 步开发循环确保了数据流的一致性：后端模型 → 接口定义 → API 实现 → 前端类型 → 前端调用，每一步的输出是下一步的输入。

段 5：编码规范

## 编码规范

### 后端规范
# 1. 数据库连接使用 async SQLAlchemy
# 2. ORM 模型包含 id、created_at、updated_at
# 3. Pydantic Schema 请求和响应分离
# 4. 路由使用 @router.get("/prefix/items")
# 5. 统一错误处理返回 {code, message, data}

### 前端规范
# 1. <script setup lang="ts"> 语法
# 2. Element Plus 组件优先
# 3. 列表页标配：搜索栏 + 表格 + 分页器 + 新增/编辑弹窗

编码规范是 Agent 的"代码风格指南"。没有这一节，Agent 可能今天用 Options API、明天用 Composition API；今天用 requests、明天用 httpx。

段 6：输出格式

## 输出格式

| 层级 | 文件 | 操作 | 说明 |
|------|------|------|------|
| 后端 | backend/models.py | 修改 | 新增 User 表 |
| 后端 | backend/routers/users.py | 新增 | 用户 CRUD |
| 前端 | src/views/user/List.vue | 新增 | 用户列表页 |

## API 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/users | 获取用户列表 |
| POST | /api/users | 创建用户 |

规定输出格式有两个好处：一是你能快速看懂 Agent 做了什么；二是 Agent 不会遗漏"启动方式"这种关键交付物。

段 7：约束（必须做 / 禁止做）

## 约束

**必须做：**
- 数据库变更先写 model → 验证 → 迁移
- API 必须有 Pydantic 校验和 response_model
- 前端所有 API 调用必须有 TypeScript 类型

**禁止做：**
- 不得在生产环境使用 SQLite
- 不得在前端硬编码后端地址
- 不得绕过 Pydantic 校验直接暴露数据库模型
- 不得混用 sync/async SQLAlchemy session

约束是 Agent 的"安全护栏"。前面的所有章节告诉 Agent 怎么做，这一节告诉它绝对不能做什么。这是我踩过最多的坑——Agent 会自作主张绕过校验、混用同步异步、硬编码地址——每一条"禁止"背后都是一次真实的翻车。

---

三、Agent vs Skill：什么时候用哪个

维度	Agent	Skill
复杂度	完整的角色 + 工具 + 工作流	单项任务的领域知识
工具权限	独立工具白名单	继承当前会话权限
触发方式	手动 /agent 或自动匹配	手动 /skill 或系统判断
适用场景	“做一个全栈项目”	“帮我校验这个 API 文档”
文件大小	通常 100-300 行	通常 20-60 行
维护成本	高（需要调试工作流）	低（改改提示词即可）

我的经验法则：如果任务需要执行命令（Bash），用 Agent；如果任务只需要知识和判断，用 Skill。

---

四、调试 Agent 的三个技巧

1. 从简单任务开始：先让 Agent 做一个"列出项目文件"的任务，验证工具权限是否正常。
2. 逐步增加复杂度：工具权限验证通过后 → 让它读一个文件 → 修改一行 → 创建新文件 → 执行命令。
3. 看 jobs/ 和 debug/ 目录：Agent 执行失败时，错误日志会写到这里。

---

下一篇预告

下篇我们进入 skills/ 目录，我整理了 27 个自定义 Skill 的设计模式——包括如何用 30 行 Markdown 让 Claude Code 变成一个专业的 API 文档校验器。

---

你给 Agent 设过哪些"禁止做"的规则？有没有被 Agent 坑过的经历？评论区聊聊。