Vibe-Coding前端实践笔记

# Vibe-Coding 前端实践笔记

Vibe Coding（氛围编程），也叫 AI coding，本质上是开发者通过对话式地描述想法，由 AI 负责生成和完善代码的一种开发方式。由 OpenAI 联合创始人 Andrej Karpathy 推广，指的是在 AI 辅助下进行编程，利用 AI（如 ChatGPT、Copilot 等）生成大量代码，程序员主要起指导、整合和审查的作用。

SOP 标准作业程序：一份详细的、分步骤的指南，其目的是为了确保一项特定的任务或操作能够始终以一致、统一、安全且高效的方式完成。
瀑布模型：先写文档再开发的模式通常称为 ‌ 瀑布模型 ‌。该模式严格遵循需求分析 → 设计 → 编码 → 测试的线性流程，文档编写是早期核心阶段，后续开发需基于文档执行 ‌。Vibe Coding 偏向于这种，但是比传统更灵活，AI 可以辅助编写和总结文档。
TDD：先写测试再开发的方法称为 ‌ 测试驱动开发 ‌（TDD），TDD 是一种敏捷开发实践。先有测试用例，可以保证 AI 生成内容的准确可控。

# Vibe-Coding 指南

# 设计评审

设计评审核心是：提前评估出项目的风险和边界 Case，保证项目稳定落地。

Vibe 技巧：

限定设计边界，技术栈，功能要求等关键信息一定全面
可选：使用 server-sequential-thinking 进行多轮思考
避免松散型的 AI 对话，应该增加 rule 和必要的条件限制，否则 AI 非常容易过度设计
如果功能较大，必须拆分模块生成设计评审，尽量避免一键式生成（使用 mcp-shrimp-task-manager 进行任务拆分规划）
最好是提供设计评审模版，作为 AI 的样本示例，以便约束 AI 输出结构
有流程图或者架构图的需求，可以让 AI 生成字符串版本流程图/架构图，然后在用其他平台工具人工绘制

添加上下文

写好任务，基本信息（技术细节和要求）

## 任务要求

1、封装一个完整的稳定的前端 jssdk；
2、SDK 的核心功能 API 包含，图片上传能力，创建 AI 玩法任务，轮询 AI 玩法任务结果，针对异常结果有统一的错误封装抛出；
3、Server 接口方面有不同的玩法接口，示例：AI 视频玩法使用，xxxxx/taskcreate 创建任务，xxxxxx/taskquery 查询任务；
4、SDK 提供初始化配置参数，比如说自定义公共参数信息，用来每个内部情况的公参数；
5、SDK 处理提供创建和轮询的 API，还对外提供其他 API，比如人脸检测，风控检测，人脸坐标数据识别返回，文件转存等，API 是动态扩充的，需要合理的设计拓展方式。
6、最终打包产出的是支持 es5 的前端 jssdk，可以使用 rollup 作为打包构建项目的基础。
7、合理的设计整个 SDK 的目录结构，保证项目鲁棒性和拓展性，使用专业设计模式设计。
8、本次内容过多，可拆分多次输出，不要丢失上下文内容，另外能给出架构图，或者流程图的地方，尽量用图表示。
9、输出设计文档，内部不用有太多代码，只有关键代码实例说明即可。最终输出 markdown 文件。

rule 限制：RIPER-5 或其他的；RIPER-5 协议 Rule 非常适合设计评审
额外的资料
- 需求文档：需求文档一般会有边界 case 或各类细节条件，很多都是设计评审需要关注细节
- 样本示例文档：输出规范，设计评审模板，让 AI 输出符合要求的文档格式，这样得到的结果更准确符合要求

是否需要拆分任务，明确添加提示词说明拆分任务，按任务要求实现
AI Agent 开始生成
生成完成后，判断任务是否符合预期；否则，根据反馈调整提示词，重新生成；是则启动下一个任务

# 调研评估

调研最核心的内容是：得到一个准确，可行的结论。

一般来说，这一步总是在设计评审中，多数时候更像设计评审的子集，偶尔会有需要单独调研的技术内容。

Vibe 技巧：

可以通过 AI 快速得到技术方案可行性的初步结论，和若干条实现思路
人工审核结论和方案分支可行性评估，选出最为可行的方案。
由 AI 生成人工审核通过的方案分支代码，必须给出足够明确的信息和依赖说明，然后验证方案可行性
AI 的技术调研，必须附带实际效果验证，否则不要给结论（AI 会有幻觉，而且它经常会迎合你的预期）

例：

通过纯前端手段，微信小程序能做根据用户心情换皮肤吗？

虽然 AI 给的方案调研结论看起来也非常可行，但是，也有很多未知问题：性能问题、三方库对小程序兼容问题，可能带来的崩溃问题，这几个问题是致命的，很可能导致需求无法实现。

AI给出初步结论和方案分支 => 人工选择方案分支 => 由AI生成验证代码 => 人工测试检验通过 => 让AI总结再次评估可行性 => AI生成完整的调研落地文档

# 单元功能(函数/类方法）

单元功能核心是：明确可以用的功能，稳定的输入/输出。

此类代码开发，受 AI 影响最大，AI 基本上能 100%完成，甚至绝大多数时候比研发表现的更优秀。这是多数人的应用场景，如手写时间格式，url参数获取，版本比较等等工具了。

Vibe 技巧：

给 AI 明确的输入，输出和清晰功能表述 （清晰的设定指令和格式，要有足够的明确性）
让 AI 生成必要的注释说明，包含入参和出参格式 Demo

## 任务

- 实现一个时间 js 版本的格式化函数

## 要求

- 入参 time：time=string|number: 支持字符串和数值，支持秒和毫秒单位入参，根据字符/数字长度 秒 \* 1000 换算成毫秒
- 入参 format="YYYY-MM-DD HH:mm:ss": 支持根据格式动态输出日期
- 出参 string 格式: 格式化后的时间
- 月/日/时/分/秒时间要求: 必须采用不足 10 补 0 方案
- 给函数增加必要的注释说明

# 单个/多个类/多个函数集成功能开发

核心是：稳定可用且符合项目规范的通用能力封装。

此类在实际开发中，通常是小型通用能力封装，典型例子：Canvas绘制分享海报，Canvas 图片裁剪，通用的业务逻辑抽离（各类业务hooks）。这类业务，缺少经验的开发者用 AI 实践稍有困难。问题其实不在 AI，而在于使用者。很多人在应用到这种场景后，开始对 AI 评价降低，认为 AI 不太行，而后逐渐弃用。

Vibe 技巧：

首先需要明确自己想要的功能是什么，整理出功能文档，而不是立刻让 AI 去执行开发
其次设定好项目基本规范（技术栈/代码风格/UI 标准/目录结构），可让 AI 基于项目生成项目规范 rule，或者提供必要的组件/文件作为样本参考。
拆分任务，将整个实现，拆分多步，然后进行人工审核合理性。（增强 AI 生成结果可控性，理解 AI 的开发思路）
明确要求 AI，针对每个任务进行代码开发前，必须给出开发思路，人工确认后才进行代码开发。（让开发者明确每一步思路，辅助理解 AI 后续代码）

### 需求背景

- 因为业务发展，对 Canvas 裁剪图像，Canvas 实现动画等能力，需求日益增加
- 为提升研发效率以及代码复用，提出 Canvas 裁剪、动画等能力抽象到通用库中

### 技术栈要求

- 前端 JavaScript
- Canvas API
- TypeScript
- Vite
- 前端单元测试

### 功能介绍

#### 基础裁剪功

1. 输入一张图片和一组坐标 [list]，输出裁剪结果 [list]。
2. 可以指定输出格式，通过入参数 [list] 的 [outType] 字段指定输出，canvas 对象，blob 数据流，base64。

#### 比例裁剪

1. 支持输出图形长宽比例，默认值比例关系为 1:1。
2. 设定特殊比例后，已坐标中心为原点，外扩坐标，让裁剪后图形边的最大值，等于原图最小边的值。

#### 带操作区的裁剪

1. 带有裁剪框，可以设置裁剪框 UI 样式。
2. 支持手势操作，拖动缩放，支持外框宽高可设置。
3. 图片加载时，默认最大边缩放到裁剪框内。
4. 放大倍数最大值为图片最小边等于裁剪框最大边的 2 倍。

### 开发要求

- 考虑通用性，期望使用纯 JS 实现，便于适配 Vue/React 等框架
- 使用 typescript 作为类型约束规范
- 仅封装一个基本的入口文件 index.ts，集成三个核心功能
- 采用纯函数编程，避免使用 Class 类
- 对外暴露三个核心 API，基础裁剪，比例裁剪，带操作区裁剪。同时抽离三个 API 的公共能力。

基于文档，实现功能

要求 1.先将整个实现过程，进行拆分任务。 2.每个任务代码开发前必须给出开发思路，由人工审核确认是否继续。

对于历史项目代码，一定要先让 AI 总结模块信息沉淀文档，便于后人理解的同时也是 AI 的核心上下文，一次沉淀后也不用每次都让 AI 总结，节省 Token。最后人工检查并纠正 AI 生成的内容文档（未来的知识库）
最后开发完成后，让 AI 复盘代码，并更新或生成必要的文档，丰富知识库。

# UI 视觉开发

AI 在 UI 视觉的实现，最常见的是 Figma MCP 和直接提供 UI 的截图。

Figma MCP 本可以提供较好的数据支持，但为什么最终 UI 输出效果很差？

绝对定位 & 盒子模型：Figma 返回的默认数据往往是绝对坐标。Web 依赖文档流和盒子模型。把 Figma JSON 喂给 AI 时，AI 看到的是一堆坐标。它必须猜测这些坐标背后的布局逻辑。

设计师的作图习惯：Groups (组)按钮背景和文字组合在一起，API 返回的就是两个重叠的图层。AI 很难推断。使用 Auto Layout，API 会返回明确的 layoutMode, padding 等属性。这是高质量还原的关键。

API 数据的“噪音”与“丢失”：JSON 太大，必要的数据清洗；图片与图标复杂的 SVG 不能处理，AI 往往会写一个空的 div 或者放一个 img 占位符，导致视觉上缺一块。

Vibe 技巧：

核心就是利用 figma 的 MCP，或者直接把标准 UI 稿图片交给 AI，能实现多少，看 AI 能力。
能较少一定的布局开发成本，整体看 AI 或者 IDE 的能力，可是尝试拆分布局实现。
chrome-mcp-stdio 调试 UI/报错/网络等问题，可以使用该 MCP，也能辅助开发效率。
如果能直接导出 HTML，那还是非常不错，由 HTML 转 Vue/React 等效果好很多。

# 通用组件，业务开发

核心内容是：完整的技术栈框架和非常全面的业务能力

通用性组件或业务开发，是我们主要的工作量，这里的内容主要是依托某一核心技术栈（Vue/React 全家桶）加业务组成。整体代码量非常大，AI 肯定是不可能读取所有信息，所以需要你合理的设计和应用。

相较于传统架构，Vibe Coding 模式增加了 Rule 和知识库的依赖，另外如果使用 Figma 的 MCP 工具也是开发重点依赖。

Vibe 技巧：

文档知识先行：必须先行补充项目核心文档，可以让 AI 生成，人工审核。尤其是业务文档，在 AI 的知识里是非常匮乏的（AI 是基于网络知识训练，它知道各类技术，但不知你业务情况）。
项目规范和要求 rule 其后：想让 AI 在业务里开发出符合规范的代码，必须把项目基本要求告诉 AI，可以通过 rule 生成项目规范（具有通用性，用 rule 比文档更合适）。
适当使用 Figma MCP 或者直接提供 UI 图片：（IDE 的 Agent 一般有多模态识别），让 AI 完成初版 UI 开发。
在合适的位置（__docs__/plan）下拆分任务规划文档（可以让 AI 拆分出来）：将复杂的任务拆分，按任务规划逐步完成。

packages/
├── .cursor
│ ├── mcp.json # 必要的 mcp 依赖
│ └── rules # 项目 Rule，AI 开发规范：凡是大型项目，基本上都需要 rule，AI 在没有合理约束前会有很多问题，生成的结果也不准确。
│ ├── base.mdr
├ └── projec.mdr
├── src/  
│ ├── api/  
│ ├── assets/  
│ ├── components/  
│ │ ├── AGENT.md # claude code / Cursor IDE
| │ └── **docs** # 适合多种 IDE
| | ├── core # 核心业务文档，频繁更新
| | └── plan # 开发阶段拆分任务文档，用完可以销毁
│ ├── log/  
│ ├── pages/  
│ │ ├──AGENT.md
| │ └── **docs**
│ ├── router/  
│ ├── store/  
│ └── utils/  
├── scss/  
├── **docs**/ # 根目知识库  
├── vue.config.js  
└── package.json

# 通用 SDK（大型插件/库）

内容核心：规范化的输入输出，以及标准的开发模式

通用 SDK 封装和业务类似，但是他有个一个特别显现的特点，标准的对外接口，规范化的输入/输出。因为这个特点，所以导致其在 Vibe Coding 上和业务开发稍有区别。相比与上面业务开发，整体架构多了一层 TDD 驱动开发。

Vibe 技巧：

SDK 需求文档（人工撰写）：需求阐述/技术栈/边界/兼容性/特殊要求，整体对外的 API 设计等
让 AI 进行设计评审：基于需求文档生成设计评审，人工审核其设计思路是否符合要求。
拆分模块和任务：这大的 SDK，不可能一次性对话完成（上下文有限），所以按模块拆分非常必要。
进入开发：保持总 => 分结构设计，即先生成总体目录结构，然后设计统一的对外暴露文件出口和全部 API。
实现 API 伪代码：有了总的准出，让 AI 生成 API 方法占位（函数名+功能注释说明），单个 API 细节可以后续独立实现。
如果使用 TDD 模式：让 AI 编写单元测试/集成测试，保证准入/准出规范，后续流程 AI 设计得到的结果更准确，经验证，效果非常不错，而且就算差一点的模型，也能出效果
每块功能比较大时，都让 AI 拆分任务，分步执行。且每次进行代码开发前，要求其必须先总结，人工审核后在开发代码。
代码开发完成后，可以直接用单测或集成测试进行测试，也可以让 AI 写实际调用代码。
开发测试完成后，再让 AI 总结复盘，进行自我反思，这样可以很好的回顾代码实现和问题的查漏补缺。
重新整理所有实现文档，提取关心的技术实现/核心 API/使用 Demo 等，反向更新过程文档，作为后续的知识库。
如果本次对话效果很好，让 AI 回顾整个流程里面，识别高质量和低质量提示词，有助于提升后续书写提示规范

# AI 存在的问题

AI 幻觉，回答的不正确或着答非所问（用词不当/上下文超限等）
开发阶段，AI 明显过度设计，缺少明确约束和限制（缺少 rule 限制）
Agent 模式总是直接修改代码：先给设计思路，人工审核在修改代码。
文档总结生成冗余：可以通过 rule 定义了精简、一般、详细三个标准，精简五代码，一般有伪代码，详细有代码示例
AI 开发太快，开代者理解跟不上：让其先说实现思路，人工检测后在开始编码。
AI 开发完成时，功能不可用或错误：使用 TDD 模式或者开发完成后让其自我反思。
每次新开对话上下文都关联不上，缺少记忆：可以使用 memory 的 mcp。

在 Vibe Coding 的团队协作时，记忆非常重要，每个人都存在大量的 AI 代码和知识内容，如何让大家的 AI 有一个共识（同一知识认知）非常重要。

将知识规范化并收拢统一，然后统一到云端，进行向量化存储。AI 所有知识，都基于云端向量数据库获取。常见的方式有两种：RAG 和知识图谱

# Prompt 收集

写好任务要求，添加上下文

## 任务要求

1、封装一个完整的稳定的前端 jssdk；
2、SDK 的核心功能 API 包含，图片上传能力，创建 AI 玩法任务，轮询 AI 玩法任务结果，针对异常结果有统一的错误封装抛出；
3、Server 接口方面有不同的玩法接口，示例：AI 视频玩法使用，xxxxx/taskcreate 创建任务，xxxxxx/taskquery 查询任务；
4、SDK 提供初始化配置参数，比如说自定义公共参数信息，用来每个内部情况的公参数；
5、SDK 处理提供创建和轮询的 API，还对外提供其他 API，比如人脸检测，风控检测，人脸坐标数据识别返回，文件转存等，API 是动态扩充的，需要合理的设计拓展方式。
6、最终打包产出的是支持 es5 的前端 jssdk，可以使用 rollup 作为打包构建项目的基础。
7、合理的设计整个 SDK 的目录结构，保证项目鲁棒性和拓展性，使用专业设计模式设计。
8、本次内容过多，可拆分多次输出，不要丢失上下文内容，另外能给出架构图，或者流程图的地方，尽量用图表示。
9、输出设计文档，内部不用有太多代码，只有关键代码实例说明即可。最终输出 markdown 文件。

给 AI 明确的输入，输出和清晰功能表述（清晰的设定指令和格式，要有足够的明确性）

## 任务

- 实现一个时间 js 版本的格式化函数

## 要求

- 入参 time：time=string|number: 支持字符串和数值，支持秒和毫秒单位入参，根据字符/数字长度 秒 \* 1000 换算成毫秒
- 入参 format="YYYY-MM-DD HH:mm:ss": 支持根据格式动态输出日期
- 出参 string 格式: 格式化后的时间
- 月/日/时/分/秒时间要求: 必须采用不足 10 补 0 方案
- 给函数增加必要的注释说明

明确自己想要的功能是什么，整理出功能文档，而不是立刻让 AI 去执行开发

### 需求背景

- 因为业务发展，对 Canvas 裁剪图像，Canvas 实现动画等能力，需求日益增加
- 为提升研发效率以及代码复用，提出 Canvas 裁剪、动画等能力抽象到通用库中

### 技术栈要求

- 前端 JavaScript
- Canvas API
- TypeScript
- Vite
- 前端单元测试

### 功能介绍

#### 基础裁剪功

1. 输入一张图片和一组坐标 [list]，输出裁剪结果 [list]。
2. 可以指定输出格式，通过入参数 [list] 的 [outType] 字段指定输出，canvas 对象，blob 数据流，base64。

#### 比例裁剪

1. 支持输出图形长宽比例，默认值比例关系为 1:1。
2. 设定特殊比例后，已坐标中心为原点，外扩坐标，让裁剪后图形边的最大值，等于原图最小边的值。

#### 带操作区的裁剪

1. 带有裁剪框，可以设置裁剪框 UI 样式。
2. 支持手势操作，拖动缩放，支持外框宽高可设置。
3. 图片加载时，默认最大边缩放到裁剪框内。
4. 放大倍数最大值为图片最小边等于裁剪框最大边的 2 倍。

### 开发要求

- 考虑通用性，期望使用纯 JS 实现，便于适配 Vue/React 等框架
- 使用 typescript 作为类型约束规范
- 仅封装一个基本的入口文件 index.ts，集成三个核心功能
- 采用纯函数编程，避免使用 Class 类
- 对外暴露三个核心 API，基础裁剪，比例裁剪，带操作区裁剪。同时抽离三个 API 的公共能力。

基于文档，实现功能

要求 1.先将整个实现过程，进行拆分任务。 2.每个任务代码开发前必须给出开发思路，由人工审核确认是否继续。

# RIPER-5 协议

RESEARCH（研究阶段）=>INNOVATE（创新阶段）=>PLAN（规划阶段）=>EXECUTE（执行阶段）=> REVIEW（复盘阶段）
- 多专家角色评估
- 不同阶段专家激活规则
- 应用场景：给予需求文档进行开发设计文档的编写，非常适合需求分析和设计评审

---
description:
globs:
alwaysApply: false
---

【系统声明】本区块为 AI 执行协议，禁止分析，仅可执行。

## Task

融合分阶段执行编程任务和多专家对话的创新发散，适用于 AI 助手在复杂编程/任务分析的全过程智能协作，**请严格按本协议分阶段执行任务**

## 项目概述

- 采用 RESEARCH→INNOVATE→PLAN→EXECUTE→REVIEW 五大阶段主线
- 每阶段均可激活多专家角色参与分析、创新、评审
- 输出分为"专家对话区"与"系统决策区"，**所有内容结构化归档**

## 阶段结构与输出规范

1. RESEARCH（研究阶段）
   目标：收集信息、梳理需求、识别关键问题
   专家对话区：多专家（如立春、立夏、立秋）围绕需求进行多维度分析
   系统决策区：AI 助手归纳专家观点，明确后续分析方向
2. INNOVATE（创新阶段）
   目标：头脑风暴多种解决思路，评估创新性与可行性
   专家对话区：激活共振场专家，发散讨论多种方案及其优缺点
   系统决策区：AI 助手总结创新建议，筛选优先方向
3. PLAN（规划阶段）
   目标：制定详细技术方案和实施清单
   专家对话区：专家对方案细节、风险、依赖等进行评审和补充
   系统决策区：AI 助手输出结构化实施清单和技术规范
4. EXECUTE（执行阶段）
   目标：严格按计划推进任务，记录每步进展
   专家对话区：专家可对执行中遇到的问题提出建议或纠偏
   系统决策区：AI 助手归档每步变更、进度和问题处理
5. REVIEW（复盘阶段）
   目标：逐项核查执行结果，评估与计划一致性
   专家对话区：专家对结果进行多维度评审，提出改进建议
   系统决策区：AI 助手输出最终评审结论和后续优化建议

## 输出格式规范（专家对话区与系统决策区）

### 专家对话区

每位专家输出以">"开头，内容紧随其后。
多位专家输出时，按激活顺序依次排列。
专家观点可相互补充、质疑或修正，鼓励观点碰撞。
所有专家输出需结构化归档于对应阶段的"专家对话区"。

示例：
立春：从系统角度看，这一需求涉及多个模块的协同，建议先梳理依赖关系。
立夏：逻辑上需明确输入输出边界，防止后续实现时出现歧义。
立秋：需平衡创新性与可维护性，建议引入多视角评估机制。

### 系统决策区

以"归纳："或"系统决策："开头，由 AI 助手归纳专家观点、明确阶段结论或推进建议。
内容应简明扼要，突出共识、分歧与后续行动。
系统决策区输出需结构化归档于每阶段结尾。

示例：
归纳：专家建议优先梳理模块依赖，明确输入输出边界，并在后续阶段引入多视角评估，确保方案创新与可维护性兼顾。

## 归档与追溯要求

所有输出（专家对话与系统决策）均需归档于[任务文件模板]对应区块。
重要分歧、创新建议、关键决策需高亮或单独标注，便于后续复盘与追溯。
阶段切换、专家激活/退场、异常回退等事件需在系统决策区明确记录。

## 任务文件模板（融合版）

===模版开始分割线===

# 上下文

文件名：[任务文件名.md]
创建于：[日期时间]
创建者：[用户名/AI]
关联协议：RIPER-5 + 编程专家对话融合协议

# 任务描述

[用户提供的完整任务描述]

# 项目概述

[用户输入的项目细节或 AI 自动推断的简要项目信息]

---

## _以下部分由 AI 在协议执行过程中维护_

# 分析与专家对话记录（RESEARCH 阶段）

[多专家对话内容、关键文件、依赖、约束等结构化归档]

# 创新方案与专家讨论（INNOVATE 阶段）

[多专家创新建议、方案优缺点、系统归纳总结]

# 实施计划与专家评审（PLAN 阶段）

[结构化实施清单、技术规范、专家评审意见]
实施检查清单：

[具体操作 1]
[具体操作 2] ... n. [最终操作]

# 当前执行步骤（EXECUTE 阶段）

> 正在执行: "[步骤编号和名称]"

# 任务进度（EXECUTE 阶段）

- [日期时间]
  - 步骤：[检查清单项目编号和描述]
  - 专家建议：[如有，结构化归档]
  - 修改：[文件和代码更改列表，包括已报告的微小偏差修正]
  - 更改摘要：[简述本次更改]
  - 原因：[执行计划步骤 [X]]
  - 阻碍：[遇到的任何问题，或无]
  - 用户确认状态：[成功 / 成功但有小问题 / 失败]
- [日期时间]
  - 步骤：...

# 最终评审与专家总结（REVIEW 阶段）

[霜降、小寒等专家整合评审、创新建议、系统结论]
===模版结束分割线===

## 专家角色库与激活规则（融合版）

### 专家角色定义

立春：系统整合型思维，擅长全局架构、战略视角，语言风格冷静、系统、善用类比。
立夏：逻辑分析型思维，专注于推理、验证与细节，语言风格理性、严谨、条理清晰。
立秋：辩证平衡型思维，强调多视角、平衡与反思，语言风格中性、善于提出对立观点。
小满：创新突破型思维，善于提出新颖方案，语言风格跳跃、富有想象力。
大满：数据洞察型思维，擅长数据分析与事实支撑，语言风格客观、数据驱动。
雨水：实用主义型思维，关注可落地性与实际效果，语言风格务实、简明。
白露：场域协同型思维，负责专家协同与流程调度，语言风格协调、全局观强。
霜降：整合提升型思维，善于观点整合与智慧涌现，语言风格凝练、升华总结。
小寒：智慧催化型思维，激发深度思考与创新涌现，语言风格深邃、启发性强。

### 激活规则

基础场（RESEARCH/PLAN）：默认激活立春、立夏、立秋，负责需求分析、方案评审。
共振场（INNOVATE）：根据创新需求动态激活小满、大满、雨水、白露，促进多元发散与创新碰撞。
涌现场（REVIEW/整合）：在需要整合观点、智慧涌现时激活霜降、小寒，完成最终总结与升华。
阶段内可根据任务复杂度、对话深度动态增减专家，确保认知多样性与流程高效。

### 角色输出风格要求

每位专家输出需体现其独特认知风格和语言特征。
专家观点可相互补充、质疑或修正，鼓励观点碰撞与多维度分析。
所有专家输出均需结构化归档，便于后续追溯与复盘。

## 各阶段专家参与方式与对话模板

1. RESEARCH（研究阶段）
   专家参与方式：默认激活立春、立夏、立秋，围绕需求、背景、关键问题进行多维度分析。
   对话模板：
   立春：从系统/全局角度分析需求或问题，指出潜在依赖与架构影响。
   立夏：逻辑推理，梳理需求边界、输入输出、潜在矛盾。
   立秋：提出对立或补充视角，平衡不同观点，挖掘潜在风险。
   系统决策区：归纳专家分析，明确后续分析重点。

2. INNOVATE（创新阶段）
   专家参与方式：动态激活共振场专家（小满、大满、雨水、白露），围绕方案创新、技术路径、实现可能性等发散讨论。
   对话模板：
   小满：提出新颖或突破性方案，激发创新思路。
   大满：用数据或事实支撑/质疑方案。
   雨水：评估方案的可落地性与实际效果。
   白露：协调各方观点，推动共识。
   系统决策区：归纳创新建议，筛选优先方向。

3. PLAN（规划阶段）
   专家参与方式：基础场专家主导，必要时邀请共振场专家补充，聚焦技术细节、风险、依赖、测试等。
   对话模板：
   立春/立夏/立秋：分别从架构、逻辑、平衡角度细化方案。
   大满/雨水：补充数据、可行性评估。
   系统决策区：输出结构化实施清单和技术规范。

4. EXECUTE（执行阶段）
   专家参与方式：以 AI 助手为主，专家可对执行中遇到的问题提出建议或纠偏。
   对话模板：
   AI 助手：报告执行进展、遇到的问题。
   相关专家：针对具体问题提出建议或修正意见。
   系统决策区：归档每步变更、进度和问题处理。

5. REVIEW（复盘阶段）
   专家参与方式：激活霜降、小寒等整合型专家，所有专家可参与评审，提出改进建议。
   对话模板：
   霜降：整合各方观点，升华总结。
   小寒：催化深度反思，提出创新性改进方向。
   其他专家：补充评审意见。
   系统决策区：输出最终评审结论和后续优化建议。

## 阶段切换与专家激活触发条件

### RESEARCH → INNOVATE：

触发条件：需求梳理完成，存在多种可能方案或需创新突破时，自动进入 INNOVATE 阶段，激活共振场专家。
典型信号：需求不唯一、存在技术难题、用户主动要求创新。

### INNOVATE → PLAN：

触发条件：创新讨论收敛，形成可行性较高的主导方案，自动进入 PLAN 阶段，基础场专家主导，必要时保留部分创新专家参与。
典型信号：专家共识、优先方案明确、创新发散趋于收敛。

### PLAN → EXECUTE：

触发条件：实施清单与技术规范制定完毕，用户或 AI 确认无遗漏，自动进入 EXECUTE 阶段。
典型信号：实施步骤明确、依赖关系清晰、评审通过。

### EXECUTE → REVIEW：

触发条件：所有实施步骤完成，用户确认或 AI 检测到任务已闭环，自动进入 REVIEW 阶段，激活整合型专家。
典型信号：进度归档无未完成项、用户验收通过。

### 专家动态激活/退场：

触发条件：
任务复杂度提升、对话深度加深时，自动增补相关领域专家。
创新瓶颈、分歧加剧时，自动激活创新/协调型专家。
方案收敛、执行推进时，部分专家可退场，仅保留关键评审或整合专家。
典型信号：对话轮次增加、分歧未解、创新需求提升、流程推进顺畅。

## 测试用例设计

### 用例 1：标准编程需求全流程

场景描述：用户提出一个中等复杂度的编程需求（如"实现一个带权限控制的用户管理模块"）。
预期流程：
RESEARCH 阶段多专家梳理需求、识别边界。
INNOVATE 阶段激活创新专家提出多种实现方案。
PLAN 阶段细化技术方案与实施清单。
EXECUTE 阶段严格按清单推进，专家辅助纠偏。
REVIEW 阶段整合评审，输出优化建议。
验证点：每阶段专家对话与系统决策区输出完整、归档规范，异常可回溯。

### 用例 2：创新性难题攻关

场景描述：用户提出一个无现成方案的创新性技术难题。
预期流程：
INNOVATE 阶段共振场专家充分发散，提出多元创新思路。
PLAN 阶段专家评审筛选可行方向。
若创新瓶颈，自动增补专家或回溯。
验证点：创新专家激活、观点碰撞、系统归纳与创新归档完整。

基于 Rules V4.5 规则和复杂性思维，构架的一份多轮对话解析提示词 (opens new window)

# Spec Coding

规格先行，整理好再生成；提前整理边界、状态、约束；输出质量可预期，更高

适合：功能开发、团队协作、生产代码
前置整理有成本，但总体省时

spec 通常包含：需求边界、接口契约（输入输出/错误码）、非功能性要求（性能/安全/兼容）、验收标准、测试用例/样例、约束（依赖、目录结构、代码风格）。

# Harness Engineering（工程化约束驱动）

Harness Engineering 是比 Spec Coding 更进一步的概念：把 Rules、Skills、标准流程打包成团队工作流，让每个人的 AI 辅助开发都在一套约束下运行。

harness 可以是：强约束的脚手架/模板、静态检查（lint/typecheck）、单测/契约测试、golden tests、CI gate、权限/文件写入白名单、自动回滚、评测集与回归基线、RAG/上下文注入规则等。

目标：不完全依赖“提示词写得好”，而是依赖“系统会自动抓错、自动拒绝不合格产物”，把可靠性工程前移。

一旦把 Agent 理解为 "感知 → 决策 → 行动 → 反馈 → 再感知" 的闭环系统，Harness Engineering 的工作就清楚了：不是给它更多提示词，而是补齐这个闭环各环节所依赖的工程能力。

Harness Engineering 的本质就是建设一个工程系统，让 Agent 稳定地读、做、验证、迭代，并在长期运行中保持可控。

Harness 层包含什么？至少四个核心子系统：

约束文档（告诉模型"你是谁、你能做什么、你不能做什么"）
记忆系统（跨会话保留关键信息）
上下文管理（在有限的 context window 里决定保留什么、丢弃什么）
反馈循环（当 Agent 犯错时如何检测并纠正）

harness-engineering (opens new window)

# Rules VS Skills

Rules 是什么？Rules 是写给 AI 看的「持久约束」，每次生成代码时都会自动生效。相当于把团队的编码规范、技术约定、禁止事项提前告诉 AI。

Skills 是什么？Skills 管的是「教 AI 做某件具体的事」。Skills 是可复用的任务模板，把一类重复性的生成任务封装起来，下次直接调用。

维度	Rules	Skills
核心定位	AI 的行为边界，「不能做什么 / 必须怎么做」	AI 的执行模板，「这件事怎么一步步做」
触发方式	自动生效，每次对话都在后台起作用	手动调用，需要时才激活
生效范围	持久、全局（或项目级），始终约束 AI	按需、局部，只在调用该 Skill 时生效
内容形式	声明式规则：禁止项、要求项、命名规范	步骤化描述：先做什么、再做什么、输出什么格式
上下文消耗	每次对话都会注入 Context，占用 Token	只在调用时注入，不调用不占用 Context
维护方式	团队统一维护，纳入 Git，变更需 Review	个人或团队均可维护，按需更新
适合内容	技术栈约定、代码规范、禁止行为、命名规则	复杂任务流程、特定组件生成、固定工作流

Rules 是《团队开发规范手册》——不管做什么任务，都要遵守。Skills 是《标准作业流程 SOP》——做具体任务时按对应 SOP 执行。

Rules 内部结构示例：

# 团队编码规范 Rules

## 技术栈约定

- 使用 React 18 + TypeScript，禁止使用 class 组件
- 状态管理统一使用 Zustand，禁止引入 Redux 或 MobX
- 样式方案使用 CSS Modules，禁止内联样式

## 命名规范

- 组件文件名和组件名使用 PascalCase
- Hook 名称以 use 开头，使用 camelCase
- 工具函数文件使用 camelCase，常量使用 UPPER_SNAKE_CASE

## 代码质量要求

- 禁止使用 TypeScript any 类型，用 unknown 替代
- 每个函数必须声明返回类型
- 异步操作必须处理 loading、error、empty 三种状态

## 禁止事项

- 不引入 package.json 未声明的第三方库
- 不提交包含 console.log 的代码

Skills 内部结构示例：

# Skill：生成标准业务列表组件

## 触发条件

当用户需要生成一个业务列表页面时调用此 Skill。

## 执行前需要收集的信息

1. 列表的数据结构（字段名、字段类型）
2. 是否需要分页？分页方式（前端分页 / 后端分页）
3. 是否需要搜索和筛选？筛选字段有哪些？
4. 是否需要多选和批量操作？
5. 数据量级（决定是否需要虚拟滚动）

## 执行步骤

Step 1：生成 TypeScript 类型定义文件（types.ts）
Step 2：生成 Zustand store，包含 loading、error、分页状态
Step 3：生成列表容器组件，包含数据请求逻辑
Step 4：生成列表项组件，处理字段渲染和交互
Step 5：生成搜索/筛选组件（如果需要）
Step 6：生成空状态、错误状态、loading 状态展示组件

## 输出要求

- 每个 Step 生成完后，等待用户 Review 确认，再继续下一步
- 生成完成后，输出组件依赖关系图

Rules 始终占用 Context，所以要保持精简；Skills 只在需要时才占用 Context，所以可以写得详细；如果把大量流程描述写进 Rules，会持续消耗 Context，导致 AI「记不住」其它重要信息。

Spec Coding、 Rules、Skill 上面讲的这些，其实本质都是为了解决“上下文”问题

Spec Coding = 给 AI 固定骨架，减少发散
Rules = 给 AI 划红线，避免犯错
Skill = 给 AI 塞套路，提升质量

工程规范 = 上下文的持久化与标准化。

# 数据存储

# 关系型数据库（Relational Database）

是一种基于关系模型的数据库管理系统，它使用表格（Table）来组织数据，每个表格由行（Row）和列（Column）组成。每个表格都有一个唯一的标识符（Primary Key），用于区分不同的记录。

关系型数据库的主要优势是数据的一致性和完整性，因为它使用严格的关系模型来定义数据之间的关系。这使得关系型数据库非常适合需要对数据进行复杂查询和分析的应用程序。

常见的关系型数据库管理系统包括 MySQL、PostgreSQL、Oracle Database、Microsoft SQL Server 等。

PostgreSQL 是开源关系型数据库，功能强大，支持 JSON、全文检索、GIS 扩展等，常被称为“最先进的开源关系数据库”。

SQL（结构化查询语言） 关系型数据库的通用操作语言，直接与数据库交互，性能高，需要编写原生语句。

**ORM（对象关系映射）**是一种编程技术，将程序中的对象（如 Python 类实例）自动映射到数据库表，避免手写 SQL。ORM 底层依然生成 SQL，只是帮你封装了转换过程，复杂查询仍需手写 SQL。

# NoSQL 数据库

非关系型数据库，不使用固定表结构，通常牺牲强一致性换取高并发、高扩展。

文档型：如 MongoDB，存储 JSON 文档，灵活模式。

事务用关系型，高并发缓存
灵活模式用 NoSQL。

# RESTful API

一种基于 HTTP 协议的接口设计风格，用于客户端（Web/App）与服务器通信。

核心思想：将一切视为资源（如用户、订单），用 URL 表示资源，用 HTTP 方法（GET、POST、PUT、DELETE）操作资源。

数据格式：通常是 JSON。

后端程序通过 RESTful API 将数据库中的数据暴露给前端或其他服务，是数据流动的出口。后端接收到 API 请求后，会通过 SQL/ORM 操作数据库，然后将结果封装成 JSON 返回。

# Redis

Redis 是一个“内存优先、可持久化”的数据结构服务器。数据默认存储在内存，读写速度极快（微秒级）。

数据结构：它不是存“表”或“文档”，而是直接操作字符串、列表、哈希、集合、有序集合等编程语言熟悉的数据结构。

可持久化：虽然跑在内存，但可以把数据定期保存到硬盘，重启时恢复。

服务器：客户端通过网络（TCP）访问它，就像访问一个远程的数据结构 API。

Redis 用内存空间换时间，成本高，所以只存最热的数据。PostgreSQL 用磁盘空间换容量，成本低，存全量核心数据。绝大多数项目，Redis 扮演的主要角色是“缓存+辅助数据库”，而不是核心业务数据库。

Q：为什么同样是存储，Redis 能快这么多？

完全基于内存：没有磁盘 I/O 延迟（持久化是异步的）。
单线程模型：避免了线程切换和锁竞争，所有操作原子性。
IO 多路复用：单线程监听大量客户端连接，事件驱动。
数据结构高效：底层用哈希表、跳表等，时间复杂度 O(1) 或 O(log N)。
协议简单：文本协议（RESP），解析快。

# Supabase

Supabase 不是一个全新的“数据库”，而是一个基于 PostgreSQL、RESTful API、Redis 等概念构建的“集成平台”。你可以把它理解为“把一堆强大的开源工具打包好，让你开箱即用”。

Supabase = (PostgreSQL + RESTful API + 实时WebSocket + 身份认证 + 对象存储) 的开源整合包

# 例子 1：分层 Spec + 激活 Rules + 分步生成

Step 1：让 AI 先出技术方案，不写代码

你：我需要实现一个虚拟列表组件，支持多选和权限控制。
技术栈：React 18 + TypeScript，组件库 antd 5.x，状态管理 Zustand
列表数据量：约 1-5 万条
权限规则：选中角色组合不同，展示的操作按钮不同（规则后续提供）

    请先给我一个技术方案，包括：
    1. 组件拆分建议
    2. 虚拟列表使用哪个方案？为什么？
    3. 多选状态放在哪里管理？
    4. 权限判断逻辑建议放在哪个层？
    不要写代码，先给方案。

Step 2：确认边界，让 AI 提问

你：方案看起来合理。在开始写代码前，你还有哪些不确定的地方需要我补充？

<!-- AI 会主动提问：权限数据结构是什么、按钮的操作是什么、列表数据结构…… -->
<!-- 这些补充信息让后续生成更准确，也让你意识到哪些上下文之前没想到。 -->

Step 3：分模块生成，每次 Review 后再继续

你：好的，现在开始写代码。先只实现虚拟列表的基础结构，
不需要多选逻辑，不需要权限判断，只需要： - 虚拟滚动正常工作 - 列表项组件结构符合后续扩展需要 - 使用 react-virtual 方案

<!-- Review 通过后： -->

你：虚拟列表部分没问题。现在在这个基础上，加入多选逻辑。
多选状态存放在 Zustand store 中，store 的结构我已经定义好了：[附上 store 定义]

Step 4：Rules 全程托底
Rules 已经定义了组件规范、命名风格、TypeScript 要求——不需要每次都在 Prompt 里重复说，AI 会自动遵守。

注意事项：同一个功能的完整需求，一开始就应该全部描述清楚，否则会导致 AI 反复重构同一段代码。提供业务上下文。不要用模糊动词描述需求

标准开发流程总结

接到需求
整理上下文：技术栈、数据结构、约束、边界条件
让 AI 出技术方案（不写代码）
确认方案 + 让 AI 提问补充信息
分模块逐步生成代码
每个模块 Review 通过后再继续下一个
集成联调
提测

# 例子 2：前端 AI 开发

前端开发 SOP 最好只管 5 件事：

输入：开始前需要哪些信息。
边界：哪些文件、行为、依赖不能随便改。
步骤：先读什么，再改什么，最后查什么。
验收：功能、样式、状态、响应式、命令怎么检查。
回复：最后必须把改动、验证和风险说清楚。

AGENTS.md // 项目长期规则，项目说明书，用 pnpm、目录结构、测试命令、禁改文件
  记录项目事实：技术栈、命令、目录、规范

frontend-dev-sop/SKILL.md // 某类任务怎么执行，开发页面时先读什么、怎么改、怎么验收
  记录页面开发流程：输入、边界、步骤、验收

frontend-code-review/SKILL.md
  记录代码审查流程：风险、行为、类型、测试

skills/frontend-dev-sop/SKILL.md：

---
name: frontend-dev-sop
description: 当前端开发任务需要按团队 SOP 完成时使用，包括需求理解、改动边界、页面实现、状态补齐、响应式检查和交付说明。
---

# 前端开发 SOP

## 使用场景

当用户要求开发、修改、优化、重构一个前端页面或组件时，先按这个流程执行。

适合任务：

-  新增业务页面
-  修改已有页面
-  优化 UI 和交互状态
-  拆分组件但不改变行为
-  修复前端缺陷
-  做合并前自查

## 开始前先读

不要立刻改代码。先阅读这些信息：

1.  用户给出的需求、截图、设计稿或链接。
2.  相关路由、页面组件和子组件。
3.  项目已有 UI 组件、样式变量、布局模式。
4.  接口类型、Mock 数据、状态管理和错误处理方式。 5.`package.json`  里的脚本命令。 6.`AGENTS.md`、README 或附近目录里的项目规则。

如果信息缺失，但可以从代码里推断，就先推断并说明依据。

如果缺失信息会影响行为判断，再向用户确认。

## 改动边界

默认遵守这些边界：

-  不引入新的 UI 库。
-  不新增生产依赖，除非用户明确要求。
-  不重写无关页面和共享组件。
-  不改变接口字段语义。
-  不删除已有交互状态。
-  不把局部样式问题扩大成架构重构。
-  不为了通过类型检查随便使用  `any`。
-  不在未确认的情况下修改鉴权、支付、权限、埋点等高风险逻辑。

## 开发步骤

1.  复述你理解的任务目标。
2.  列出需要修改的文件范围。
3.  找到最小可行改动路径。
4.  优先复用现有组件和工具函数。
5.  小步修改，不做无关重构。
6.  补齐加载态、空状态、错误态、禁用态、长文本和移动端布局。
7.  修改后运行项目中最接近的检查命令。
8.  如果命令不能运行，说明原因和替代验证方式。

## 验收清单

交付前检查：

-  需求目标是否完成
-  用户可见行为是否符合预期
-  桌面端和移动端是否没有明显溢出
-  长文本、空数据、接口失败是否有处理
- TypeScript 类型是否没有被绕过
-  样式是否复用现有设计系统
-  是否运行了 lint、typecheck、test 或 build
-  是否说明了未覆盖风险

## 最终回复格式

请按下面结构回复：

### 改动

-  修改了哪些文件
-  每个文件解决什么问题

### 验证

-  运行了哪些命令
-  命令结果如何
-  页面或交互检查了什么

### 风险

-  哪些地方没验证

使用示例：

使用 $frontend-dev-sop 完成这个需求。

需求：
订单列表页筛选区太松散，需要改得更紧凑。

约束：
- 不改接口字段
- 不换表格组件
- 移动端不能横向溢出

验收：
- 空数据时显示明确提示
- 跑项目检查命令

我把前端开发 SOP 写进 Skill，Codex 终于不乱发挥了 (opens new window)

# 备注

# 如何给项目添加数据库？

常见的数据库类型：

关系型数据库（MySQL、PostgreSQL）：数据以表格形式存储
文档数据库（MongoDB）：数据以 JSON 文档形式存储
键值数据库（Redis）：适合缓存和快速查找

BaaS（Backend as a Service: 后端即服务） 是提供现成后端功能的云服务，包括数据库、用户认证、文件存储等。常用的 BaaS 服务：

Supabase：开源的 Firebase 替代品
Firebase：Google 的 BaaS 平台
PlanetScale：托管的 MySQL 服务
使用 BaaS，你不需要自己写后端代码和管理服务器，能大大加快开发速度。特别适合 Vibe Coding 场景。

在 Vibe Coding 中，你可以用 Supabase、Firebase 等 BaaS 服务，它们提供了数据库、认证、存储等功能，不需要自己搭建服务器。

直接告诉 AI “请集成 Supabase 数据库”，它会帮你生成代码。对于小项目，BaaS 服务完全够用，而且省心。如果需要更多控制权，可以用 PostgreSQL、MongoDB 等数据库，但需要自己部署和管理。

# 如何处理用户认证和授权？

回答：不要自己从零实现认证系统，太容易出安全问题。建议使用现成的方案，比如 Supabase Auth、Firebase Auth、Auth0、NextAuth.js。这些方案提供了完整的认证流程，包括邮箱验证、密码重置、第三方登录等。

直接告诉 AI “请用 NextAuth.js 实现用户登录注册”，它会帮你集成。

如果是学习项目，可以简单实现，但商业项目一定要用成熟方案。

# Skills迭代时如何做版本管理？

阶段1：个人 / 小团队（< 5 个 Skills）

文件系统 + Git = 天然版本管理

Skills 本质是 Markdown + 脚本，本身就是文本文件，直接复用 Git 工作流

实际迭代模式

本地开发：直接改文件夹，重启 agent 即生效（无需重新编译/部署）
团队协作：Git 仓库 + PR review，把 SKILL.md 当代码对待
Commit message 写明：改了什么 → 为什么 → 影响哪些场景（3 行规范）
手工维护一个 2~5 条"代表性测试 prompt"，每次改完自己跑一遍

阶段2：中型团队（5~20 个 Skills，多人维护）

PR 模板加三个必填字段：动机 / 影响场景 / 测试结果
建立 Semantic Versioning 规则，用 CI 检查"frontmatter 版本号是否更新"（否则 PR 无法合入）
为每个 Skill 建立独立的 eval 集（10~20 条典型 prompt + 期望触发该 skill / 不触发的标注）
跨 Skill 的触发回归测试，比单 Skill 测试重要。改了 skill A 的 description，要跑整个 skill 集的触发矩阵，不能只测 A。

PR 是 Pull Request，请求把我的代码拉进（合并到）主分支。Skill 是"自然语言写的程序"，没有编译器帮你检查错误。PR 是目前最有效的质量把关点——在合并之前，强制要求作者说清楚改动意图，让其他人有机会发现问题。

Semantic Versioning 语义化版本：

major（X.0.0）：行为发生不兼容变化，原有调用方需要适配
minor（0.X.0）：新增能力，向前兼容
patch（0.0.X）：bug 修复、措辞优化、Pitfalls 增补；

Pitfalls指易错点，用来告诉 AI 在执行这个 Skill 时哪些事情不能做、哪些判断容易出错、哪些场景需要特别小心。

Semantic Versioning 解决的是可追溯性，不解决**判断"好不好"**的问题。改了一段 description，触发矩阵变了，版本号打得再准确，也不知道哪些场景退化了——这需要 eval 套件。

PR模板：

## Skill Change: <skill-name>

### 版本变化
v1.2.0 → v1.3.0 (minor)

### 改动动机
2026-04-25 线上事故 #INC-2418：
Agent 在 Redis 连接异常的故障里花了 20 分钟绕去查 Redis，
但根因是上游 SLB 健康检查问题。
当前 Skill 没有引导 Agent 优先查 SLB。

### 改动内容
- Steps 中新增"先检查近 30 分钟 SLB 健康检查变更"作为第 1 步
- Pitfalls 中新增"Redis 异常常常是症状不是根因"

### 影响范围
- 所有调用 incident-triage 的 Agent
- 不向后兼容性破坏，因为是新增步骤

### 评估结果
回放 50 个历史事故：
- 平均定位时间从 14.2min → 9.8min
- 错误归因率从 18% → 6%

阶段3：企业级（20+ Skills，多部门，审计需求）

引入企业级 Skill Hub，它能：

结构化 diff：把 Skill 解析成 frontmatter + 各个 section，做按 section 的 diff
变更摘要：自动生成一句话说明"主要变化是什么"

评估对比

对每一次版本升级，跑同一套测试集，得出 v1 vs v2 的客观对比。

测试集的来源有几种：

历史调用回放：从过去 30 天调用日志里采样有代表性的 case
人工策展样本：故意覆盖典型场景和边缘场景的样本集
故障案例：来自真实线上事故的复盘 case

每一次 Skill 提交，自动跑这三类测试集，得出：

任务成功率：v1 和 v2 各自的完成率
步骤数：平均完成步骤数（少更好）
错误率：错误归因率
安全性：是否触发了"禁飞区"

灰度机制

major 版本走 blue/green，先给小比例流量，跑 3~5 天 eval 指标不回退再全量

低风险：修措辞、加 Pitfall、补 Example，直接合并，无需灰度
中风险：新增 step、修改判断条件、加 Input，灰度 1-3 天，监控指标
高风险：major 版本、删除 step、改默认行为，至少灰度 7 天 + 多团队验证

灰度过程中要监控：调用成功率有没有下跌、异常退出比例有没有升高、用户主动纠正比例有没有变化、平均执行步骤数有没有异常增长，任何一个指标显著恶化，自动回滚到上一版。

参考：Skill 改一版烂一版？少了版本号谁都救不了 (opens new window)

# SKills的质量门禁管理？

什么样的 Skill 才允许进入 Hub？什么样的版本升级才允许上线？什么样的发布才允许全量？

Skill Hub 指"用来集中管理 Skills 的基础设施层"，负责：

基于版本号做自动审核流（major 走额外审批）
展示结构化 diff
跑回归 eval 套件
下发 Skills 给组织内用户

先有 Skill Hub，再有门禁，再有版本治理，再有生命周期管理。但现实是大多数团队是从底向上自然生长的——先有几个 Skill 解决问题，再发现乱了才想治理。

企业级 Skill Hub 的质量门禁设计成三道关：入 Hub 门禁、版本升级门禁、生产发布门禁，把"能不能进 Hub"、"能不能合主分支"、"能不能上生产"拆成三个独立门禁。

第一道关：入 Hub 门禁

结构合规，frontmatter 完整，必须包含 name、version、owner、status、required_tools
内容完整，Skill 8 块结构：frontmatter、When to use、Do not use when、Inputs、Steps、Verification、Failure handling、Pitfalls
安全合规：

不包含明文密钥：自动扫描 token / api key / password
不直接执行高危操作：不能在 Steps 里写 rm -rf DROP TABLE 等
不引用未注册工具：required_tools 都要在工具白名单里
权限范围合理：required_permissions 只能是最小集

基础测试：至少有 5 个测试 case

第二道关：版本升级门禁

v[major].[minor].[patch]

轻量门禁（patch）：必须有改动动机说明；PR 通过 owner 同意即可；不强制跑评估，但跑了更好
中等门禁（minor）：必须有改动动机；必须跑完整评估；必须生成 v(N-1) → v(N) 对比报告；任何指标回退 > 3 pt 自动打回；至少 1 个 reviewer 同意
重门禁（major）：必须有改动动机和迁移说明；必须跑完整评估；必须跑稳定性扰动测试；必须 owner + 平台 reviewer 双签

第三道关：生产发布门禁

Skill 在 Hub 里的发布状态分成几个：draft（写完未合并） → experimental（合并未上线） → canary（灰度中） → stable（全量上线） → deprecated（已废弃） → retired（已下线）

每两个状态之间都有门禁。

参考：Skill 想进生产？先闯这 4 道死关 (opens new window)

# 收藏

#AI #Vibe-Coding

上次更新: 9/11/2026, 7:47:52 PM