Jul 17, 2026

技术热点落地：Spec-Driven Development + Agent Skills——从 Vibe Coding 到规范工程化（2026-07-17）

适用场景与目标

背景：2026年7月，AI 编码代理生态大爆发

过去48小时内，GitHub Trending 上多个 AI 编码代理相关项目冲击了 10万+ Star：

项目	Stars	定位
github/spec-kit	121K	GitHub 官方出品的 Spec-Driven Development 工具包
addyosmani/agent-skills	78K	生产级 AI 编码代理技能（Chrome 团队 Addy Osmani 出品）
mattpocock/skills	175K	TypeScript 专家 Matt Pocock 的技能集合
affaan-m/ECC	230K	Agent Harness 性能优化系统
multica-ai/andrej-karpathy-skills	193K	基于 Karpathy 观察的 CLAUDE.md 最佳实践

核心趋势：AI 编码代理（Claude Code、Cursor、Codex、Copilot 等）正在从”辅助补全”进化到”自主开发”，而 Spec-Driven Development（规范驱动开发） 和 **Agent Skills（代理技能）**正是让这种进化可控、可复现、可工程化的关键方法论。

适用人群

个人开发者：希望用 AI 代理高效构建项目，但不想陷入”Vibe Coding”的不可控状态
技术团队负责人：需要在团队中规范化 AI 辅助开发流程，确保代码质量和可维护性
AI 工程化实践者：关注如何将 AI 编码代理纳入 CI/CD 流水线
开源维护者：希望通过 Spec 和 Skills 降低贡献门槛

目标

读完这篇文章，你将能够：

理解 Spec-Driven Development 的核心原则
用 specify-cli 初始化一个 Spec-Driven 项目
为你的 AI 编码代理安装生产级 Skills
建立从”需求 → Spec → 实现 → 验证”的工程化流水线
了解常见陷阱并知道如何规避

最小可行方案（MVP）步骤

第一步：安装 Spec Kit CLI

Spec Kit 是 GitHub 官方发布的工具包，核心组件是 specify-cli。推荐使用 uv 安装：

# 安装 uv（如尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装 specify-cli
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.12.11

# 或从 PyPI 安装（更简洁）
uv tool install specify-cli

🔧 配置建议：建议指定版本号安装，避免上游更新破坏兼容性。用 specify self check 检查新版本。

第二步：初始化项目并建立宪法（Constitution）

在一个新的或已有的项目目录中：

# 初始化一个新项目
specify init my-ai-project --integration copilot
cd my-ai-project

# 如果使用 Claude Code，用 --integration claude-code
# specify init my-ai-project --integration claude-code

初始化后，在你的 AI 编码代理中（如 Cursor、Claude Code、Copilot）执行：

/speckit.constitution 制定项目原则：代码质量优先、测试覆盖率>80%、API 设计遵循 RESTful 规范、前后端分离

这将生成项目的 .specify/constitution.md，所有后续开发都将基于这套原则展开。

⚡ 快速启动提示：也可以手动创建 .specify/constitution.md，内容示例见下方”关键实现细节”。

第三步：创建第一个 Spec

用自然语言描述你想构建的功能，关注 “做什么”和”为什么”，而非”怎么做”：

/speckit.specify 构建一个用户认证系统：支持邮箱注册、Google OAuth 登录、JWT Token 刷新、密码重置邮件

Spec Kit 会生成结构化的 PRD（产品需求文档），分解为用户故事、验收标准、技术约束等。这份 Spec 就是你与 AI 编码代理之间的”合同”。

第四步：安装 Agent Skills

Agent Skills 是一套预定义的提示词和工作流，让 AI 代理遵循工程最佳实践。

# 安装所有 24 个技能
npx skills add addyosami/agent-skills

# 或只安装关键技能
npx skills add addyosami/agent-skills --skill code-review-and-quality
npx skills add addyosami/agent-skills --skill interview-me

安装后，你的代理将支持以下斜杠命令：

命令	作用
`/spec`	定义构建内容（Spec before Code）
`/plan`	分解为小粒度任务
`/build`	增量构建（每次一个切片）
`/test`	测试驱动（测试即证明）
`/review`	合并前五维代码审查
`/ship`	安全发布到生产

第五步：走通完整流程

# 1. 定义
/speckit.specify 构建一个博客文章管理 API

# 2. 规划（Skills 自动触发）
/plan

# 3. 构建
/build auto
# （/build auto 在批准计划后自动执行所有任务，每一步都 TDD 驱动）

# 4. 验证
/test

# 5. 审查
/review

# 6. 发布
/ship

关键实现细节

1. Constitution 文件示例

# 项目宪法

## 核心原则
1. **Spec 先行**：任何代码变更前必须先有通过审查的 Spec
2. **测试即证明**：功能完成的标准 = 测试通过
3. **小步提交**：每次提交完成一个独立的原子变更

## 技术约束
- 语言：TypeScript（严格模式）
- 测试：Vitest，覆盖率 > 80%
- API：RESTful，OpenAPI 3.1 文档
- 数据库：PostgreSQL，Prisma ORM

## 性能要求
- P95 响应时间 < 200ms
- 查询 N+1 零容忍

2. Spec 的常见结构

一个生成后的 Spec（PRD）通常包含：

# PRD: 用户认证系统

## 用户故事
- 作为访客，我可以注册邮箱账号
- 作为用户，我可以用 Google 账号登录
- 作为用户，我可以刷新过期的 Token

## 验收标准
- [ ] 注册成功后发送验证邮件
- [ ] JWT Access Token 有效期 15 分钟
- [ ] Refresh Token 有效期 7 天，支持轮换

## 技术架构
- NextAuth.js 处理 OAuth
- bcrypt 密码哈希
- Redis 存储 Refresh Token

## 边界情况
- 重复注册返回 409，不泄露用户是否存在
- 密码重置 Token 有效期 1 小时

3. 与 CI/CD 集成

将 Spec 验证纳入 CI 流水线（.github/workflows/spec-check.yml）：

name: Spec Check
on: [pull_request]
jobs:
  spec-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check for Spec changes
        run: |
          if git diff --name-only origin/main HEAD | grep -q '.specify/'; then
            echo "✅ Spec changes detected - review required"
          fi

4. Skills 自定义

Skills 存储在 .claude/skills/ 或 .cursor/rules/ 目录下，可以手工编辑：

---
name: code-review-and-quality
description: Five-axis code review before merge
---

## Review Checklist
1. 正确性：逻辑是否完整无遗漏？
2. 安全性：是否存在注入/XSS/权限问题？
3. 性能：是否有 N+1 查询或不必要的计算？
4. 可维护性：命名是否清晰？是否有冗余代码？
5. 测试：新代码是否被测试覆盖？

常见坑与规避清单

🚩 坑 1：Spec 写得像技术方案

症状：Spec 里充满了”用 React 18 + Next.js 14 + Prisma”，而不是描述用户需要什么。

解决方法：Spec 是 “什么”和”为什么”，不是 “怎么做”。技术栈选择交给 Architecture Decision Record（ADR）。

🚩 坑 2：所有功能用一个 Spec

症状：一个 Spec 包含认证、博客、评论、通知……长达 50 页。

解决方法：一个 Spec 对应一个独立的功能切片。如果拆不出来，说明需求粒度还不够细。

🚩 坑 3：跳过 Constitution 直接写 Spec

症状：开发到一半发现代码风格不统一、测试标准不一致。

解决方法：Constitution 是 Spec-Driven Development 的”宪法”——先立规矩再做事。花 10 分钟写 Constitution，省 10 小时重构。

🚩 坑 4：Skills 装太多导致代理困惑

症状：安装了 20+ 技能后，AI 代理在多个技能之间来回切换，提示词过长导致 token 浪费。

解决方法：按角色安装。前端开发者只装前端技能，后端只装后端技能。Spec Kit 支持 Bundles（角色预设）：

# 安装前端工程师角色包
specify init --bundle frontend-engineer

🚩 坑 5：过度依赖 `/build auto`

症状：/build auto 一次性构建大量代码，审查时发现设计方向有误。

解决方法：前几次迭代用手动 /build，每次只构建一个任务，审查通过后再继续。确认流程稳定后再用 /build auto。

🚩 坑 6：忽视 Agent Skills 的版本管理

症状：Skills 更新后，代理行为突然改变，产生风格不一致的代码。

解决方法：锁定 Skills 版本或在项目仓库中固定 Skills 副本：

# 锁定到特定版本
npx skills add addyosami/agent-skills@v1.2.3

# 或在项目中固定副本
cp -r ~/.claude/skills/ .skills/
# 然后在 CLAUDE.md 中引用本地副本

🚩 坑 7：Spec 与代码不同步

症状：Spec 写好后，迭代过程中代码发生了变更，但 Spec 没有更新。

解决方法：将 Spec 审查纳入 PR 流程——任何合并请求必须附带 Spec 更新。

🚩 坑 8：忽略团队协作的 Spec 审查

症状：一个人写了 Spec，AI 代理直接生成代码，团队其他成员不了解设计决策。

解决方法：Spec 应该像代码一样走 Review 流程。效率会提升，但不应该省掉人的判断。

成本/性能/维护权衡

成本分析

维度	传统开发	Spec-Driven + Skills
初始投入	低（直接写代码）	中（需要写 Spec + Constitution）
迭代成本	高（沟通成本、返工）	低（Spec 即文档，AI 自动执行）
新人 onboarding	高（需要阅读散落的代码和文档）	低（Spec + Constitution 即活文档）
Token 消耗	中	略高（Spec 和 Constitution 占用上下文）

经验值：在中小型项目（< 5 万行代码）中，Spec-Driven 的初始投入（写 Spec）约占总工时的 10-15%，但可以减少 30-50% 的返工。

性能影响

AI 代理上下文窗口：Spec + Constitution 会占用约 2-4K token 的上下文——对于 128K-200K 的现代模型来说，影响可以忽略
API 调用成本：更多 structured prompt 可能增加 Token 消耗 10-20%，但减少因方向错误而产生的无用调用

维护权衡

优势	劣势
Spec 即活文档，永不过期	需要培养写 Spec 的习惯
AI 代理行为可预测、可复现	初期配置需要 30-60 分钟
团队协作有统一基准	多 Skill 组合需要调试
新人快速上手	需要维护 Skills 版本

一周内可执行行动清单

Day 1：安装与体验

安装 uv 和 specify-cli
specify init 初始化一个测试项目
运行 /speckit.constitution 生成项目宪法

Day 2：安装 Skills 并跑通第一个 Spec

npx skills add addyosami/agent-skills --skill code-review-and-quality
/speckit.specify 创建一个简单的功能 Spec（例如：添加一个健康检查端点）
运行 /plan → /build 完整走一遍

Day 3：建立团队规范

团队讨论并确认 Constitution 内容
制定 Spec 模板（参考上方的 Spec 结构）
将 Spec 审查纳入 PR 流程

Day 4：CI/CD 集成

添加 GitHub Actions Spec 检查工作流
配置 Skills 版本锁定
设置自动化测试门槛

Day 5：落地真实项目

选择一个中等复杂度的小需求
完整使用 Spec → Plan → Build → Test → Review 流程
对比传统方式的效率差异

Day 6-7：复盘与调优

回顾遇到的问题（对照”常见坑”清单）
调整 Constitution 和 Skills
尝试 /build auto（如果手动流程已稳定）
将经验和自定义 Skills 版本提交到团队仓库

总结

2026 年 7 月，AI 编码代理正经历从”玩具”到”工具”的关键转折。Spec-Driven Development（GitHub Spec Kit）和 Agent Skills（addyosmani/agent-skills、mattpocock/skills 等）的出现，标志着行业共识的形成：

AI 编码代理的可靠性 = 规范的 Spec + 高质量的 Skills + 工程化的流程

这不是让 AI 替你写代码——而是让 AI 在你的规范和约束下写代码。Spec 优先，Skills 辅助，人在回路中审查——这才是 AI 时代工程化的正确姿势。

参考资源

GitHub Spec Kit — ⭐121K
Addy Osmani’s Agent Skills — ⭐78K
LM Studio Bionic — 本地模型 Agent 支持
The LLM Critics Are Right. I Use LLMs Anyway — HN 237 分热帖