qlxxkj Tutorials

1. 为什么需要标准化流程

1.1 AI编程的最大痛点

AI会跑偏：同样的需求，每次生成的代码结构可能完全不同
输出不稳定：今天能用的代码，明天重新生成就失效了
项目越写越乱：没有规范约束，代码越来越难以维护
上下文丢失：AI对话超过一定长度就会遗忘前面的关键信息
无法复用：每次都是从零开始，没有积累

这些问题不是AI不够聪明，而是缺少一套标准化的开发流程。

1.2 标准化流程的价值

可预测：知道每一步该产出什么，不会偏离方向
可复用：流程和模板可以跨项目使用
可迭代：基于已有成果持续改进，而不是推倒重来
可协作：多人可以按照同一套规范使用AI

1.3 从"随机生成"到"工程化产出"的转变

随机生成模式	工程化产出模式
直接告诉AI"帮我做一个XX"	先写PRD，明确要做什么
AI想到哪写到哪	Spec定义结构，AI按规格执行
每次对话都是全新的	Skill固化经验，越用越熟练
代码写完就结束	有验收标准和测试流程
无法追溯问题出在哪	每个环节都有文档记录

1.4 标准化流程的整体架构

PRD：用自然语言描述产品需求
Spec：将PRD转化为结构化规格说明
Skill：把AI的开发行为固化为可复用的模块
MCP：统一AI与外部工具的连接协议
三者结合，形成从想法到代码的完整流水线

2. PRD（产品需求文档）怎么写

2.1 PRD的本质

PRD是用自然语言描述产品应该做什么的文档。它不是技术文档，不需要写代码结构或数据库设计。PRD回答的是三个问题：

这个产品为谁服务？
解决什么具体问题？
怎么判断做成功了？

2.2 PRD的核心要素

一份合格的PRD包含以下内容：

产品名称和一句话描述
目标用户：谁会用这个产品，他们的特征是什么
核心功能：必须有的功能列表，按优先级排序
使用场景：用户在什么情况下会使用这个产品
成功指标：怎么衡量产品是否达到预期
约束条件：技术限制、时间要求、预算等

2.3 PRD与传统需求文档的区别

传统需求文档	AI时代PRD
几十页甚至上百页	1-3页即可
包含大量技术细节	聚焦功能和场景
需要产品经理专职写	任何人用自己的语言写
一次性交付	持续迭代的活文档
面向开发团队阅读	面向AI和人共同阅读

2.4 实战案例：待办清单App的PRD

以下是一个完整的PRD示例：

产品：QuickTodo - 极简待办清单

一句话描述：一个专注于"今天要做的事"的轻量级待办清单应用。

目标用户：
- 自由职业者和学生
- 每天需要管理3-10个任务的人
- 不喜欢复杂项目管理工具的人

核心功能（按优先级）：
1. 添加待办事项（标题+截止日期）
2. 标记完成/未完成
3. 按日期筛选查看
4. 删除已完成事项
5. 本地数据持久化（刷新不丢失）

使用场景：
- 早上起床后打开App，列出今天要做的事
- 完成任务后打勾，获得完成感
- 晚上回顾今天完成了多少

成功指标：
- 用户能在10秒内完成一条待办的添加
- 数据在浏览器关闭后不丢失
- 页面加载时间在1秒以内

约束条件：
- 不需要登录注册
- 数据存储在本地浏览器
- 支持手机和电脑访问

2.5 写PRD的常见错误

写太长：超过5页的PRD说明你没想清楚。PRD不是论文，说清楚就行。
写太短：只有一句话的需求，AI会自由发挥到不可控的方向。至少要把核心功能和成功指标写明白。
缺乏优先级：所有功能都标为"重要"，等于没有重点。用P0/P1/P2分级。
面向AI写：不要在PRD里写技术选型或数据库设计，那是Spec的事。
写完就不管：PRD是活的，随着开发推进不断修正。

3. Spec驱动开发（OpenSpec）

3.1 什么是Spec

Spec（Specification，规格说明）是将PRD中的自然语言需求转化为结构化数据的文档。如果说PRD回答"做什么"，Spec回答"具体怎么做"。

Spec的核心价值：

结构化：把模糊的需求变成明确的规则
可验证：每条规格都可以单独检查和测试
可追踪：从需求到实现有一条清晰的链路
AI友好：结构化数据比自然语言更容易被AI理解和执行

3.2 OpenSpec的四个阶段

OpenSpec是一个完整的规格生命周期管理流程：

propose（提出）：基于PRD创建规格草案，定义产品应该满足的条件
explore（探索）：分析规格的完整性，检查是否有遗漏的场景和边界条件
apply（执行）：将规格转化为AI可执行的指令，指导代码生成
archive（归档）：版本化管理已完成的规格，支持回滚和对比

3.3 Spec的格式

Spec通常使用JSON或YAML格式，包含以下字段：

yaml

spec:
  name: todo-app-v1
  version: 1.0.0
  features:
    - name: add-todo
      description: 用户可以添加一条新的待办事项
      inputs:
        - title: string (required, max 200 chars)
        - due_date: date (optional)
      outputs:
        - success: boolean
        - todo_id: string
      validation:
        - title cannot be empty
        - due_date must be a valid date
    - name: mark-complete
      description: 用户可以标记待办事项为已完成
      inputs:
        - todo_id: string (required)
      outputs:
        - success: boolean
        - updated_todo: object

3.4 从PRD到Spec的转换过程

以刚才的待办清单App为例：

第一步，提取PRD中的核心功能，每个功能对应一个Spec条目。

第二步，为每个功能定义输入和输出。输入是用户操作的数据，输出是系统返回的结果。

第三步，添加验证规则。比如标题不能为空、截止日期必须是有效日期。

第四步，补充边界情况。比如用户连续添加相同标题怎么办？超过100条待办怎么显示？

第五步，将Spec交给AI执行，AI根据规格说明生成对应的代码。

3.5 Spec vs PRD的分工

维度	PRD	Spec
语言	自然语言	结构化数据
读者	人和AI	主要是AI
粒度	功能级别	接口级别
变更频率	低（方向性变更）	高（细节调整）
验证方式	人工审阅	自动化测试

3.6 实战：Spec驱动的AI开发

有了Spec之后，给AI的提示词会变成：

请根据以下Spec生成待办清单应用的完整代码：

spec: todo-app-v1
features:
  - add-todo
  - mark-complete
  - delete-todo
  - list-todos

请确保：
1. 每个功能的输入输出与Spec一致
2. 验证规则在代码层面生效
3. 数据结构符合Spec定义

这种提示词生成的代码质量远高于直接说"帮我做一个待办清单"。

4. Skill体系：把AI行为固化为可复用模块

4.1 什么是Skill

Skill是Markdown格式的行为定义文件，描述AI在执行特定任务时应该遵循的步骤、规范和约束。它不是代码，而是"教AI如何工作的说明书"。

Skill解决的核心问题：

同样的开发任务重复出现时，不需要每次都重新描述
不同开发者使用AI时，可以保证输出风格和质量一致
团队可以共享和积累最佳实践

4.2 Skill的结构

一个完整的Skill包含以下部分：

markdown

# Skill: Web应用开发

## 输入
- 用户的自然语言需求描述
- 相关Spec文件路径

## 输出
- 完整的前后端代码
- 项目结构说明
- 依赖安装命令

## 执行步骤
1. 分析需求和Spec，确定技术栈
2. 创建项目目录结构
3. 生成前端页面代码
4. 生成后端API代码
5. 配置数据库连接
6. 编写测试用例
7. 运行构建和lint检查

## 约束条件
- 使用React + TypeScript作为前端框架
- 使用Node.js + Express作为后端
- 所有API必须有类型定义
- 代码必须通过ESLint检查
- 每个功能模块至少有一个单元测试

4.3 Skill与Spec的关系

Spec定义"产品是什么"：产品的功能、接口、数据结构
Skill定义"AI怎么做"：AI生成代码时的步骤、规范、质量要求
两者配合：Spec告诉AI目标，Skill告诉AI方法

4.4 如何编写一个Skill

编写Skill的最佳实践：

从实际项目中提炼：每次开发完成后，总结AI做得好的地方和有问题的地方
记录关键决策：为什么选这个技术栈？为什么用这种方式实现？
量化质量标准：不只是"代码要整洁"，而是"函数不超过50行"、"变量命名遵循camelCase"
持续迭代：Skill不是一次写成的，而是在使用中不断优化

4.5 Skill库的积累

随着使用次数增加，你会建立自己的Skill库：

Skill类别	示例
前端开发	React组件生成、Tailwind样式规范
后端开发	API设计、数据库建模、认证实现
测试	单元测试生成、E2E测试编写
部署	Docker配置、CI/CD流程、Vercel部署
调试	Bug排查流程、性能优化 checklist

Skill库的价值在于复利效应：用得越多，积累的经验越丰富，AI输出的质量越高。

5. MCP协议：统一AI与外部世界的连接

5.1 MCP是什么

MCP（Model Context Protocol，模型上下文协议）是由Anthropic提出的一种开放标准协议，用于在大模型与外部工具、数据和资源之间建立标准化连接。

简单理解：MCP是AI的"USB接口"。插上一个设备，AI就能使用它。

5.2 为什么需要协议层

在没有MCP之前，AI访问外部资源的方式是混乱的：

每个工具需要不同的集成方式
权限管理和数据流转没有统一标准
AI和工具之间的通信格式不兼容
更换工具需要重写整个集成逻辑

MCP解决了这些问题：

统一的连接标准：任何工具只要实现MCP协议，AI就能使用
标准化的数据传输：请求、响应、错误处理都有规范
安全的权限管理：明确AI可以访问哪些资源、执行哪些操作
即插即用：新增工具不需要修改AI侧的代码

5.3 MCP的核心概念

概念	说明	类比
MCP Server	提供工具和服务的端点	外设本身
MCP Client	调用工具的客户端（如AI IDE）	USB接口
Resource	可被AI读取的数据源	文件/数据库
Tool	可被AI执行的操作	函数/API
Prompt	预定义的对话模板	快捷指令

5.4 实战：用MCP连接外部资源

场景一：连接数据库

MCP Server配置：
- 类型：database
- 连接字符串：postgresql://user:pass@localhost/mydb
- 暴露的Tools：
  - query(sql): 执行SQL查询
  - migrate(schema): 执行数据库迁移
- 暴露的Resources：
  - db:schema: 数据库表结构
  - db:stats: 数据统计信息

AI拿到这些配置后，可以直接用自然语言操作数据库：

"帮我查一下今天新增了多少用户"
→ AI自动调用query("SELECT COUNT(*) FROM users WHERE created_at = TODAY")
→ 返回结果：127

场景二：连接API

MCP Server配置：
- 类型：api-gateway
- 基础URL：https://api.example.com
- 暴露的Tools：
  - get_user(user_id): 获取用户信息
  - create_order(payload): 创建订单
  - search_products(query): 搜索商品

场景三：连接文件系统

MCP Server配置：
- 类型：filesystem
- 根目录：/projects/myapp
- 暴露的Resources：
  - file:./src/index.ts: 读取指定文件
  - dir:./src/: 列出目录内容
- 暴露的Tools：
  - read(path): 读取文件内容
  - write(path, content): 写入文件
  - search(pattern): 全文搜索

5.5 MCP的实际意义

对于AI编程来说，MCP的意义在于：

AI不再只是"凭空写代码"，而是可以读取你的项目文件、查询数据库、调用API
开发者可以把已有的基础设施（数据库、API、文件存储）暴露给AI
项目的上下文被完整地传递给AI，开发质量和效率都更高

6. 避免AI跑偏的策略

6.1 上下文工程的必要性

AI有一个根本限制：它能"记住"的上下文是有限的。对话过长时，早期的关键信息会被遗忘或稀释。这就是为什么：

同一个项目，第一天和第七天的AI输出质量可能差异很大
对话超过一定长度后，AI开始忽略之前设定的规则
没有上下文管理的项目，代码风格会越来越不一致

解决方案：主动管理上下文，而不是被动等待AI记住。

6.2 Spec + Skill + Context 三位一体

防止AI跑偏的核心策略是建立三层防护：

第一层：Spec作为锚点

每次让AI执行任务时，附带当前的Spec版本
AI生成的代码必须与Spec保持一致
不符合Spec的代码直接在Code Review阶段驳回

第二层：Skill作为行为规范

Skill规定了AI的编码习惯和质量标准
即使Spec没有覆盖的细节，Skill也能保证输出风格一致
新项目可以直接复用已有的Skill，减少磨合成本

第三层：Context作为记忆补充

定期将项目关键信息整理为Context文件
包括：技术栈选择、架构决策、已知问题和解决方案
每次新对话开始时，先加载Context文件，让AI快速恢复状态

6.3 定期回顾和对齐

建议的节奏：

每个功能开发完成后：对照Spec检查实现是否正确
每个里程碑（如完成3个功能）：整体Review一次代码结构和质量
每周：更新Skill库，沉淀新的最佳实践
每月：回顾PRD，确认产品方向没有偏移

6.4 红队测试

红队测试是指主动扮演挑刺者的角色，专门找AI输出的问题：

功能完整性：AI是否实现了Spec中的所有功能？有没有遗漏？
边界情况：空值、异常输入、并发操作，AI考虑了吗？
安全问题：有没有硬编码密钥？SQL注入风险？XSS漏洞？
性能问题：数据库查询是否加了索引？前端有没有不必要的重渲染？
代码质量：命名是否规范？函数是否过长？有没有重复代码？

每次让AI生成代码后，用红队测试的思路审查一遍，能发现大部分问题。

6.5 防跑偏的检查清单

开发过程中随时对照：

[ ] 当前任务是否在PRD范围内？
[ ] 实现是否符合Spec的定义？
[ ] 代码风格是否与Skill要求一致？
[ ] 上下文文件是否需要更新？
[ ] 是否有新的最佳实践需要加入Skill库？

7. 完整流水线案例演示

7.1 案例：从零开发一个个人博客系统

下面展示从想法到上线的完整流程，每个环节标明产出物和耗时。

7.2 环节一：PRD撰写

动作：用自然语言描述博客系统的功能需求
产出物：一份1-2页的PRD文档
内容：目标用户（个人作者）、核心功能（写文章、发布、评论）、成功指标（首屏加载<2秒）
耗时：30分钟
验收标准：PRD中的每个功能都能被后续环节引用

7.3 环节二：Spec定义

动作：将PRD转化为结构化的规格说明
产出物：一个或多个Spec文件（YAML/JSON格式）
内容：每个API的输入输出、数据模型定义、验证规则
耗时：1-2小时
验收标准：Spec可以通过自动化测试验证

7.4 环节三：Skill准备

动作：选择或创建适用于博客项目的Skill
产出物：一组Skill文件（Markdown格式）
内容：React组件开发规范、API设计模式、部署流程
耗时：30分钟（首次创建约2小时）
验收标准：Skill中包含该项目所需的全部技术规范

7.5 环节四：AI执行开发

动作：将PRD + Spec + Skill + Context一起喂给AI
产出物：完整的源代码和项目文件
内容：前端页面、后端API、数据库Schema、配置文件
耗时：2-4小时（取决于功能复杂度）
验收标准：代码通过Spec验证和红队测试

7.6 环节五：测试与修复

动作：手动测试核心功能，让AI修复发现的问题
产出物：可运行的应用程序
内容：功能测试、边界测试、性能测试
耗时：1-2小时
验收标准：所有P0和P1级别的Bug已修复

7.7 环节六：部署上线

动作：使用Skill中的部署规范，将应用发布到生产环境
产出物：公网可访问的应用
内容：域名配置、SSL证书、CDN加速、监控告警
耗时：30分钟
验收标准：应用在生产环境正常运行，核心功能可访问

7.8 全流程时间估算

环节	首次开发	后续迭代
PRD撰写	30分钟	15分钟
Spec定义	1-2小时	30分钟
Skill准备	2小时（新建）	10分钟（复用）
AI执行开发	2-4小时	1-2小时
测试与修复	1-2小时	30分钟
部署上线	30分钟	15分钟
总计	7-11小时	1.5-3小时

7.9 关键洞察

首次开发需要半天到一天，后续迭代只需要几十分钟
Skill库的积累是速度提升的关键：用得越多，复用率越高
Spec的质量直接决定AI输出的质量：Spec写得越细，返工越少
标准化流程不是束缚，而是让AI发挥更大价值的杠杆

7.10 流水线的可扩展性

这套流程不仅适用于小型项目，也适用于复杂产品：

小项目（个人工具、简单网站）：一个Spec + 几个Skill，半天搞定
中等项目（SaaS产品、电商平台）：多个Spec + Skill组合，几天完成
大型项目（多模块系统）：分层Spec架构 + 专业Skill库，一周到数周

核心不变：PRD定义方向，Spec定义结构，Skill定义方法，三者配合让AI稳定输出高质量代码。

1. 为什么需要标准化流程 ​

2. PRD（产品需求文档）怎么写 ​

3. Spec驱动开发（OpenSpec） ​

4. Skill体系：把AI行为固化为可复用模块 ​

5. MCP协议：统一AI与外部世界的连接 ​

6. 避免AI跑偏的策略 ​

7. 完整流水线案例演示 ​