Claude Code -21 Agent 规划化编写范式

系列前言 ：本文是《Claude Code 实战指南》系列中关于 Agent 规范化编写 的一篇。之前的文章主要演示了 Agent 与 Skill 的"用法"，而本文重点讲解如何规范化地编写 Agent，以及它与 Skill 之间的边界与协作关系。

姊妹篇地址：

Claude Code -7 子代理（subagent）实战指南：从内置 Agent 到自定义专业团队

目标

统一 Claude Code 项目中 Agent 的编写方式，强调 Agent 不应承载全部规范，技能应抽离到 Skill 中 。本文以 .claude/agents/backend-architect.md 为通用模板和完整案例，以 .claude/skills/nestjs-backend-developer 为关联 Skill，说明一个规范化 Agent 应该具备哪些结构、内容和边界。

1. Agent 与 Skill 的关系

在 Claude Code 中，Agent 和 Skill 是两种不同层次的"行为说明书"：

维度	Agent	Skill
存放位置	`.claude/agents/<agent-name>.md`	`.claude/skills/<skill-name>/SKILL.md`
核心作用	定义一个具体角色的行为、职责、输出	定义一套可复用的能力、规范、流程
触发方式	由 Claude Code 在满足规则时自动调用	用户通过 `/skill-name` 触发或被 Agent 引用
是否依赖 Skill	常见，通过 `skills` 引用	一般不依赖

核心原则：

Skill 负责沉淀稳定、可复用的规范和工具链。
Agent 负责定义角色视角下的执行方式、输出格式和完成标准。
Agent 不应把 Skill 已经定义好的规范重写一遍 ，而应通过 frontmatter 的 skills 字段引用。

2. Agent 的标准结构

一个规范的 Agent 文件应包含以下部分：

text 复制代码

.claude/agents/<agent-name>.md
├── Frontmatter              # name / description / tools / model / skills
├── Purpose                  # 角色定位
├── Core Philosophy          # 核心工作理念
├── Capabilities             # 能力范围（分场景）
├── 强制约束                 # 不可违反的硬规则
├── 开发完成验证             # 必须执行的验证清单
├── Knowledge Base           # 规范来源和读取规则
├── Response Approach        # 标准工作流程
├── Output Format            # 输出结构
├── Example Interactions     # 典型提问示例
└── Completion Checklist     # 完成前必须确认的事项

2.1 各部分职责

章节	内容	是否必备
Frontmatter	`name`、`description`、`tools`、`model`、`skills`	是
Purpose	一句话定义角色是谁、负责什么	是
Core Philosophy	工作理念，如简单优先、规范优先、安全第一	推荐
Capabilities	分场景列出能力边界	是
强制约束	不可违反的硬规则	推荐
开发完成验证	任务完成后必须执行的检查	推荐
Knowledge Base	引用 Skill 和项目规则，说明何时读取	是
Response Approach	标准执行流程，通常按步骤编号	是
Output Format	最终回复应包含哪些部分	是
Example Interactions	典型用户问题示例	推荐
Completion Checklist	完成前逐项确认	推荐

设计原则：

Agent 不重复定义 Skill 已覆盖的规范。
Agent 只补充"角色视角"的内容：角色定位、工作流程、输出格式、完成标准。
长规范应放在 Skill 的 reference/ 中 ，Agent 通过 skills 引用。

3. Agent Frontmatter 通用结构

yaml 复制代码

---
name: agent-name
description: 专业 XXX，专注于 ... 在本项目中所有 ... 必须基于 ...
tools: Read, Write, Edit, Glob, Grep, manage_core_memory
model: inherit
skills:
  - skill-name-1
  - skill-name-2
---

字段	要求	示例
`name`	小写中划线，保持唯一	`backend-architect`
`description`	描述角色、能力、边界、关联技术栈	`专业 NestJS 后端架构师，专注于可扩展 API 设计...`
`tools`	声明该 Agent 可调用的工具	`Read, Write, Edit, Glob, Grep, manage_core_memory`
`model`	模型策略，`inherit` 表示继承父级	`inherit`
`skills`	引用的 Skill 列表	`nestjs-backend-developer`

3.1 为什么 `skills` 是关键

skills 字段是 Agent 与 Skill 协作的核心：

它告诉 Claude Code：该角色需要预加载哪些规范。
它避免了在 Agent 中重复编写已经沉淀在 Skill 中的内容。
它让多个 Agent 可以复用同一套 Skill，保持规范一致性。

反模式 ：把 Skill 的 Constraints、Validation、Resources 全部复制到 Agent 中。这样会导致：

Agent 文件臃肿，难以维护。
Skill 更新后，Agent 中的副本不会同步。
多个 Agent 引用同一领域时，规范容易分裂。

4. Agent 正文通用骨架

markdown 复制代码

# Agent 名称

## Purpose
一句话定义角色定位。

## Core Philosophy
- 规范优先
- 简单优先于复杂
- 清晰边界
- 安全第一

## Capabilities
### 场景一
- 能力 A
- 能力 B

### 场景二
- 能力 C
- 能力 D

## 强制约束（不可违反）
1. 规则一
2. 规则二

## 开发完成验证
- [ ] 检查项一
- [ ] 检查项二

## Knowledge Base
### 预加载规范
说明通过 `skills` 预加载了哪些 Skill。

### 核心规范资源
按 Skill 的 `Resources` 定义，按需读取相关 reference 文件。

### 项目规则预读取
开始任务前必须读取的项目规则。

## Response Approach
1. 识别任务类型
2. 收集必要输入
3. 加载必要资源
4. 定义服务边界 / 设计 API 契约
5. 执行核心任务
6. 验证输出结果
7. 向用户交付结果

## Output Format
输出结果应包含：
- 架构设计说明
- API 契约
- 代码变更详情
- 关键实现说明
- 验证结果
- 使用说明和注意事项

## Example Interactions
### 场景一
- "问题 1"
- "问题 2"

### 场景二
- "问题 3"
- "问题 4"

## Completion Checklist
- [ ] 已明确本次任务目标
- [ ] 已读取相关 Skill 和项目规则
- [ ] 已列出本次读取、修改、生成的文件路径
- [ ] 已说明变更内容、影响范围
- [ ] 已列出验证命令和结果
- [ ] 已标注遗留问题、风险点
- [ ] 最终结论清晰

5. Agent 中应该放什么、不应该放什么

5.1 应该放在 Agent 中

内容	原因
角色定位（Purpose）	明确"我是谁"
工作流程（Response Approach）	明确"我怎么做"
输出格式（Output Format）	明确"我交付什么"
完成清单（Completion Checklist）	明确"怎样算完成"
角色特有的边界和约束	从角色视角补充
典型示例问题	帮助模型理解触发场景

5.2 不应该放在 Agent 中

内容	应该放在哪里
长篇技术规范	Skill 的 `reference/`
通用编码规范	Skill 的 `reference/`
通用安全规则	Skill 的 `reference/`
通用验证命令	Skill 的 `Validation`
可复用模板文件	Skill 的 `templates/`
可执行脚本	Skill 的 `scripts/`
示例输入输出	Skill 的 `examples/`

判断标准：如果这段内容离开当前 Agent 仍然有用，就应该放到 Skill 中。

6. 案例：backend-architect Agent

6.1 Frontmatter

yaml 复制代码

---
name: backend-architect
description: 专业 NestJS 后端架构师，专注于可扩展 API 设计、微服务架构和 NestJS 项目落地。负责服务边界定义、模块架构、API 契约和可观测性设计。在本项目中所有后端实现必须基于 NestJS + TypeScript + Prisma 技术栈。
tools: Read, Write, Edit, Glob, Grep, manage_core_memory
model: inherit
skills:
  - nestjs-backend-developer
---

这个 frontmatter 的关键点：

description 明确角色、领域、技术栈边界。
tools 声明了该 Agent 可用的工具。
skills: nestjs-backend-developer 把后端开发规范预加载进来，Agent 不需要重复写规范。

6.2 正文结构映射

通用骨架	`backend-architect` 中的体现
Purpose	资深 NestJS 后端架构与开发专家
Core Philosophy	规范优先、简单优先、清晰边界、明确契约、可观测性、不新增依赖、安全第一
Capabilities	系统架构设计、NestJS 项目落地、代码审查辅助
强制约束	10 条不可违反的规则，与 Skill 约束保持一致
开发完成验证	lint、format、tsc、单元测试、checklist、服务启动
Knowledge Base	说明 `nestjs-backend-developer` 已预加载，列出需读取的项目规则
Response Approach	10 步流程，从识别任务到交付结果
Output Format	架构说明、API 契约、代码变更、实现说明、验证结果、注意事项
Example Interactions	架构设计场景和 NestJS 开发场景示例
Completion Checklist	8 项完成前必须确认的事项

6.3 Agent 与 Skill 的协作方式

backend-architect 的工作方式典型地体现了 Agent 与 Skill 的分层：

通过 skills 预加载规范 ：nestjs-backend-developer 中的约束、流程、参考资源已经可用。
通过 Knowledge Base 声明读取规则：项目规则 + Skill reference 按需加载。
通过 Response Approach 定义执行路径：从架构设计到代码实现到验证交付的完整流程。
通过 Output Format 和 Completion Checklist 保证输出质量。

规范细节（NestJS 怎么写、DTO 怎么定义、Prisma 怎么用）全部交给 Skill，Agent 只负责：以架构师角色，按正确流程，产出符合规范的架构和代码。

6.4 backend-architect.md 完整内容

下面是 .claude/agents/backend-architect.md 的完整内容，可直接作为 Agent 编写的参考范本：