Spec-First 已成往事，欢迎来到 Skill-First 时代

随着 AI Agent 的出现，API 开发正在发生变革。Skill-First 将规范（Specs）、测试和场景封装成可执行、可验证的技能（Skills），为 Agent 时代补充了现有的方法论。

Spec-First 时代

多年来，许多开发团队的协作流程都是 Spec-First（规范优先）。

核心内容

原则	描述
优先设计 API	在实现之前先定义 API
围绕文档协作	团队参考共享的规范
早期 Mock	前端可以基于 Mock 进行开发
共同调试	问题在共享格式中清晰可见
基于规范测试	验证实现是否符合设计
准备就绪后发布	发布文档齐全、经过测试的 API

价值所在

收益	为什么重要
清晰的契约	前后端都清楚预期结果
并行开发	团队可以独立工作
减少摩擦	沟通误解能被及早发现
稳定的测试	测试符合文档定义的行为
活文档	规范随产品同步演进

对于以人类驱动的 API 开发来说，Spec-First 是正确的方法。

新的消费者：AI Agent

在 AI Coding 出现后，API 资产的消费者发生了变化。

Agent 也开始消费这些资产。

Agent 需要什么

Agent 活动	所需资产
读取端点	API 文档
添加测试	端点定义、Schemas
运行自动化	测试场景、环境
根据报告修复代码	失败详情、响应数据
判断变更是否可用	测试结果、覆盖率

在这种背景下，Apifox 中的 API 文档、测试用例和测试场景不再仅仅是供人类阅读的协作材料。

它们是 Agent 的确定性可调用资产。

资产转型

资产	Spec-First (人类视角)	Skill-First (Agent 视角)
API 文档	协作材料	可调用的数据源
测试用例	质量产物	可执行的验证
测试场景	测试工作流	自动化目标
环境	配置	运行时上下文
报告	评审输出	反馈信号

资产从“可读”转变为“可调用”。

Skill-First 的定义

在 Spec-First 的基础上构建：

保留项	原因
端点规范	仍然需要清晰的契约
测试用例	仍然需要质量产物
业务场景	仍然需要工作流覆盖
文档	仍然需要人类参考

新增项：

新增项	目的
可执行技能	Agent 可以调用工作流
可验证步骤	每个阶段的质量门禁
可追溯链条	Agent 行为的审计追踪

Skill-First = Spec-First + Agent 执行层。

系统架构

层级	职责	示例
Apifox	管理 API 和测试资产	Endpoints, schemas, test cases, scenarios
CLI	提供确定性执行	Commands, validation, output
SKILL	提供任务判断和路径	Workflow guidance, sequence rules
Agents	理解目标、执行、调整	Claude Code, Cursor, Trae, Codex

每一层都有其特定的角色。

它们如何协同工作

用户: "为退款 API 生成测试并运行验证"
        ↓
Agent: 理解任务类型 (SKILL 辅助)
        ↓
Agent: 调用 CLI 读取端点 (CLI 执行)
        ↓
Agent: 生成测试用例 (Agent 创建)
        ↓
CLI: 校验结构 (cli-schema 校验)
        ↓
Agent: 写入测试用例 (CLI 执行)
        ↓
CLI: 返回 agentHints (CLI 引导)
        ↓
Agent: 回读并调整 (Agent 遵循 hints)
        ↓
Agent: 运行测试 (CLI 执行)
        ↓
CLI: 返回报告 (CLI 提供反馈)
        ↓
Agent: 向用户总结 (Agent 完成)

工作流转型

Spec-First 工作流（人类驱动）

人类设计规范
        ↓
人类编写文档
        ↓
人类创建 Mock
        ↓
人类进行调试
        ↓
人类编写测试
        ↓
人类发布

特征：

维度	描述
驱动者	人类
重点	协作
反馈	人工评审
速度	受限于人类步调
错误	由人类发现

Skill-First 工作流（Agent 辅助）

人类指定目标
        ↓
Agent 读取现有资产
        ↓
Agent 生成变更
        ↓
CLI 进行校验
        ↓
Agent 写入
        ↓
CLI 引导后续步骤
        ↓
Agent 进行验证
        ↓
人类评审结果

特征：

维度	描述
驱动者	Agent (由人类目标引导)
重点	执行
反馈	自动化校验
速度	Agent 步调
错误	由 CLI 拦截

团队应该做什么

立即采取的步骤

步骤	行动
1. 安装	`npm install -g apifox-cli@latest`
2. 安装 SKILL	`apifox skill install`
3. 尝试小任务	给 Agent 分配低风险任务
4. 学习模式	观察 Agent 的工作流
5. 扩大范围	逐渐增加任务复杂度

第一个 Agent 任务示例

使用 Apifox CLI 帮我在 Apifox 中创建我的第一个 API 端点。
首先，检查我的 Apifox CLI 设置并列出我可以访问的项目。
询问我要使用哪个项目。在我确认后，创建一个简单的 GET /health
端点，命名为 Health Check，并包含一个 200 响应示例。
在写入之前验证任何结构化输入，然后回读该端点并总结创建的内容。

这将带来：

收益	描述
环境检查	Agent 验证环境配置
项目选择	Agent 在写入前征得同意
小规模创建	低风险的初步尝试
校验	写入前通过 cli-schema 校验
回读	确认实际创建的内容
总结	人类获得清晰的结果

入门命令

# 安装 Apifox CLI
npm install -g apifox-cli@latest

# 安装配套 SKILL
apifox skill install

# 检查版本 (需要 2.2.5+)
apifox -v

# 身份验证
apifox auth login

# 列出项目
apifox project list

未来展望

趋势	方向
Agent 参与度	更多的 API 开发任务由 Agent 处理
CLI + SKILL 模式	成熟、标准化的工作流
更多 Skills	针对不同场景的领域特定 Skills
更好的收敛性	关键节点的工程化改进
人机协作	人类与 Agent 之间的无缝交接

未来是 Agent 辅助的 API 开发时代。

全系列总结

我们已经完成了整个旅程：

篇章	主题	核心洞察
1	问题	126 个 MCP 工具 → 杂乱的工具墙
2	转向	复杂性从上下文转移到工程化
3	哲学	CLI 校验，Agent 生成
4	设计	agentHints 引导后续步骤
5	经验	SKILL 封装工作流知识
6	验证	减少 30% 调用，减少 25% Token
7	实践	PRD → OpenAPI → 测试 → 验证
8	基础	CI/CD 仍是基石
9	诚实	仍面临四个挑战
10	愿景	Spec-First → Skill-First