Claude Code 配置完全指南三自定义 Agent 开发实战——以 Fullstack Developer 为例系列第 3 篇 | 2026-07-22配套仓库C:\Users\zhang\.claude\agents\前言如果说 Skill 是给 Claude Code 装一个专项技能包那 Agent 就是给它雇一个专职工程师。Agent 拥有独立的角色身份、工具权限和工作流程——它不只是回答你而是像一个真正的同事一样完成任务。本文以我生产环境中的fullstack-developerAgent 为例逐段拆解一个完整 Agent 的定义。一、Agent 文件的基本结构每个 Agent 就是一个放在agents/目录下的 Markdown 文件。文件名不重要重要的是 YAML front matter--- name: fullstack-developer description: 全栈开发专家... tools: Read, Write, Edit, Grep, Glob, Bash ---1.1nameAgent 的唯一标识符。在 Claude Code 中用/agent fullstack-developer切换到这个 Agent。命名建议小写 连字符如code-reviewer、api-designer、test-writer。1.2description当 Claude Code 自动选择 Agent 时它根据description来匹配任务。所以描述要写清楚什么场景触发这个 Agent。我的写法description:全栈开发专家。前端使用 Vue 3 Element Plus TypeScript 后端使用 FastAPI Python数据库使用 SQLite。负责从零搭建或维护独立的 全栈应用项目。当用户要求开发包含前后端的完整 Web 应用、或涉及 FastAPI SQLite 后端时触发。关键要素技术栈 职责范围 触发条件。当用户要求……时触发这句话是给 Claude Code 的调度器看的决定了它什么时候激活这个 Agent。1.3toolsAgent 可以使用的工具白名单。我的配置tools:Read,Write,Edit,Grep,Glob,Bash这五个工具覆盖了代码开发的核心需求工具用途为什么给Read读取文件理解现有代码Write创建新文件脚手架和新增模块Edit精确替换修改已有文件比 Write 安全Grep内容搜索查找函数引用、追踪依赖Glob文件名匹配列出目录结构、查找特定类型文件Bash执行命令安装依赖、运行测试、启动服务权限最小化原则如果你只让 Agent 做代码审查就给ReadGrep不给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 langts 语法 # 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什么时候用哪个维度AgentSkill复杂度完整的角色 工具 工作流单项任务的领域知识工具权限独立工具白名单继承当前会话权限触发方式手动/agent或自动匹配手动/skill或系统判断适用场景“做一个全栈项目”“帮我校验这个 API 文档”文件大小通常 100-300 行通常 20-60 行维护成本高需要调试工作流低改改提示词即可我的经验法则如果任务需要执行命令Bash用 Agent如果任务只需要知识和判断用 Skill。四、调试 Agent 的三个技巧从简单任务开始先让 Agent 做一个列出项目文件的任务验证工具权限是否正常。逐步增加复杂度工具权限验证通过后 → 让它读一个文件 → 修改一行 → 创建新文件 → 执行命令。看jobs/和debug/目录Agent 执行失败时错误日志会写到这里。下一篇预告下篇我们进入skills/目录我整理了 27 个自定义 Skill 的设计模式——包括如何用 30 行 Markdown 让 Claude Code 变成一个专业的 API 文档校验器。你给 Agent 设过哪些禁止做的规则有没有被 Agent 坑过的经历评论区聊聊。