用一个 Skill 跑通需求开发全流程
问题
如果用户给我的不是一句完整 Prompt，而是一个 Figma 链接、一篇飞书 PRD、几张截图、一份 PDF、一个接口文档和若干聊天补充，怎样让 AI 从前端视角完成需求理解、代码定位、技术方案、开发、测试、浏览器验收、交接的完整闭环？
这个流程应该怎样设计成一个可复用的 Agent Skill？如何兼容 Codex、Claude Code、GitHub Copilot 等不同工具？怎样避免 AI 看漏长图、猜错需求、改错文件，或者只凭一句“已完成”就结束任务？
一个真正能跑通需求交付的 Skill，不是一篇很长的 Prompt，而是一个受约束的工程流水线：
- 收料：用对应连接器读取 Figma、飞书、PDF、图片、Issue 和接口契约，保证每份材料都有稳定定位信息。
- 建模：把材料拆成事实、推断、冲突、待确认项，再形成范围、状态矩阵和可观察验收标准。
- 定位：先看项目地图，再用搜索矩阵定位模块，最后追踪页面到组件、状态层、API 和测试的调用链。
- 拆解：每个子任务都绑定来源、允许修改路径、验收标准和验证命令。
- 实现：按契约/类型 → 数据 → 状态 → UI/无障碍 → 埋点/开关 → 测试的顺序做小步修改。
- 验证：类型、Lint、测试、构建、真实浏览器、响应式、无障碍、视觉、控制台和网络请求共同举证。
- 审查与交接：逐条把验收标准映射到代码和运行证据，留下可跨会话、跨人的交接文档。
Skill 负责流程、规则和模板；MCP/连接器负责访问 Figma、飞书等外部系统；脚本负责精确校验；AGENTS.md 负责每次任务都要遵守的仓库约定。四者不能互相替代。
本文最后给出一套可以直接复制的完整 Skill 示例包，不是伪代码。
一、从参考文章中保留什么，又要改什么
本文参考了《AI代码生成率94%：我们用一个Skill跑通需求开发全流程》中展示的工程方法。文章把移动端需求开发拆成设计稿筛选、需求拆解、代码定位、实现、编译验证、模拟器验证、沉淀和提交，并用项目 Wiki、规则文件、脚本与落盘产物控制过程。
其中最值得保留的不是某个脚本名，而是五条思想：
| 思想 | 为什么有效 | Web 前端中的落地方式 |
|---|---|---|
| 流水线化 | 防止一句模糊需求直接跳到改代码 | 每阶段定义输入、产物和退出标准 |
| 模型做判断，脚本做精确动作 | LLM 不擅长精确计数、批处理和判断命令是否真正完成 | 模型解释需求；API、rg、测试器和校验脚本获取事实 |
| 红线前置 | 在越界发生时立即停止，而不是事后补救 | 权限、计费、数据删除、公共契约、外部写操作设风险门禁 |
| 机器可验证 | “看起来对”不等于运行正确 | 用退出码、测试报告、截图、Trace、网络和控制台证据判断 |
| 知识落盘 | 新会话和新成员可接续 | 保存证据账本、需求契约、子任务、验证报告和交接文档 |
但不能原样照搬：
- 平台不同：原文主要围绕 iOS、Objective-C、Bazel 和模拟器；Web 前端还要处理响应式、SSR/水合、浏览器差异、请求竞态、缓存、路由、无障碍和 Web 性能。
- 不能只靠关键词硬规则判断范围：关键词可以缩小范围，却不能代替段落结构、文档标题、表格关系和人工确认。它适合做高召回提示，不适合成为唯一事实来源。
- Figma 不能只筛“像移动端”的画板：要读取精确 node ID、变量、组件属性、Auto Layout、注释、交互和 Code Connect 映射；截图只是其中一种证据。
- 固定八阶段不是目的：流程应按风险和项目能力裁剪。纯逻辑需求不需要视觉对比，单页活动不一定需要完整架构设计，但关键证据和退出条件不能丢。
- 自修次数不是质量标准：限制两三轮是防止死循环，不表示第三次一定要成功。若错误属于需求、环境或测试路径，继续改业务代码反而更危险。
- 提交不是默认动作：本地改代码通常属于实现范围；Commit、Push、创建 PR、回写飞书、更新 Issue 和部署都可能产生外部影响，必须遵循用户授权和仓库流程。
- 代码生成率不能单独代表收益：更重要的是需求交付周期、返工率、缺陷逃逸率、Review 轮次、验证覆盖和接手成本。
- Skill 目录应渐进加载：当前 Agent Skills 规范鼓励
SKILL.md + references/ + scripts/ + assets/，不应把安装说明、变更记录和所有项目知识都塞入每次激活的核心上下文。
二、一个 Skill 在系统里负责什么
需求开发闭环至少有五类资产。把所有内容都写进 Skill，会让它臃肿、越权而且难以迁移。
| 资产 | 回答的问题 | 适合放什么 | 不适合放什么 |
|---|---|---|---|
AGENTS.md | 在这个仓库里始终怎么工作 | 技术栈、目录、构建命令、禁止项、完成定义 | 某个需求的一次性内容、几十页操作教程 |
| Skill | 这类任务按什么流程做 | 阶段、条件分支、检查清单、模板、脚本路由 | 密钥、长期运行服务、默认生产权限 |
| MCP / 连接器 | 怎样读取或操作外部系统 | Figma、飞书、Jira、GitHub、浏览器、监控平台 | 产品判断和跨阶段流程 |
| Scripts / CI / Hooks | 哪些动作必须确定执行 | 初始化、Schema 校验、Lint、测试、构建、范围检查 | 依赖模糊语义的产品决策 |
| 任务产物 | 这次需求到底决定了什么 | 证据、需求契约、子任务、验证报告、交接 | 应该长期复用的通用规则 |
2.1 为什么只用一条超级 Prompt 不够
一条几千字的 Prompt 有四个问题：
- 无法选择性加载：这次只有截图，却仍把飞书、PDF、发布流程全塞进上下文。
- 没有可执行部件：它可以要求“检查所有材料”，却不能保证真的遍历了 60 页 PDF 或 5 万像素长图。
- 缺少结构化产物：一旦会话压缩、切换模型或换人，需求决定和验证证据就丢失。
- 难以测试：无法单独验证模板、脚本、触发条件和阶段退出标准。
Skill 的价值是把这些内容拆成三层：
- 发现层：
name + description，让 Agent 知道何时使用。 - 指令层：核心
SKILL.md，只放总流程、关键红线和引用路由。 - 执行层：按需加载
references/，运行scripts/，复制assets/templates/。
三、第一步不是写代码，而是完整收料
“读 PRD”不是一个单一动作。不同载体需要不同通道和不同完整性证明。
3.1 多源输入路由
| 输入 | 首选读取方式 | 必须获取 | 不能只做什么 |
|---|---|---|---|
| Figma 链接 | Figma 官方 MCP / 授权 API | 精确节点、结构化上下文、截图、变量、组件/变体、注释、资产、Code Connect | 只看整页缩略图或让模型猜 CSS |
| 飞书 PRD | 已登录连接器/MCP 或飞书 OpenAPI | 标题、版本、所有 Block、表格、图片、附件；评论视工具能力获取 | 对私有链接用普通网页抓取，拿到登录壳就算读完 |
| 文本提取 + 每页渲染 | 页码、正文、表格、图、批注、页眉脚关系 | 只读 OCR 文本，遗漏架构图和表格结构 | |
| 图片/截图 | 原图视觉读取 | 原始尺寸、区域顺序、所有可见文字、状态和布局 | 只看聊天缩略图 |
| 超长截图 | 等宽重叠切片 | 每个切片、10%～15% 重叠、已读清单、空白/模糊区说明 | 随机看开头、中间、结尾三段 |
| Issue / TAPD / Jira / Linear | 对应连接器/API | 描述、验收、状态、评论、附件、关联任务 | 只读标题或最新一条评论 |
| OpenAPI / GraphQL / Proto | 仓库生成物或授权服务 | 字段、必填性、枚举、错误、鉴权、幂等 | 从 UI 文案反推接口字段 |
| 聊天补充 | 当前对话或授权消息连接器 | 原话、发言人、时间、与原需求的修订关系 | 把讨论建议当成已确认规则 |
| 视频/可交互原型 | 浏览器/播放器 + 关键帧与操作记录 | 时间点、状态变化、操作前后、字幕/讲解 | 用一帧静态图代表整个交互 |
Figma、飞书、Jira 等链接经常依赖登录态、组织权限和动态 API。普通抓取可能只拿到登录页或空壳 HTML。正确做法是使用用户已授权的连接器、官方 API 或导出能力，并保留文档 ID、版本、Block ID、node ID 等稳定定位信息。
3.2 Figma 要同时读取“结构”和“像素”
Figma MCP 的作用不是一键生成生产代码，而是给 Agent 提供设计结构。完整读取至少包含：
- 精确节点：从链接中解析 node ID，不要默认扫描整份 File 后凭外观挑图。
- 设计上下文：组件层级、Auto Layout、约束、属性、变体、文本和可见性。
- 视觉截图：用于确认真实渲染、叠层、裁切、渐变、图片和整体节奏。
- 变量与 Token：颜色、间距、圆角、字体、阴影，映射到项目语义 Token。
- 组件映射：优先读取 Code Connect，让设计中的 Button、Modal、Table 对应真实代码组件。
- 状态与交互：Prototype 连接、注释、悬停/禁用/错误/加载状态、多端 Frame。
- 资产：下载已提供的 SVG、图片和图标，不要用 CSS 或第三方图标近似重画。
3.3 飞书文档要递归读取 Block 和附件
飞书 PRD 常见的遗漏点是：正文读到了，表格里真正的验收没读；图片看到了占位符，却没下载图片；Wiki URL 的 Token 被误当成底层文档 ID。
推荐流程：
- 根据 URL 判断它是新版文档、Wiki 节点还是云盘文件。
- Wiki 先解析到底层对象，再获取文档标题和当前版本。
- 递归读取所有 Block，保留标题层级、表格、Callout、任务列表和代码块结构。
- 根据资源 Token 下载图片和附件；不要把“附件存在”当作“附件已读”。
- 如果连接器无法返回布局、评论或嵌入内容，经权限允许后导出 Word/PDF 再做二次读取。
- 在证据账本记录缺失能力，例如“当前连接器无法读取评论”，不要静默忽略。
3.4 长图和 PDF 的“全部读完”怎样证明
模型看到的聊天预览可能只有几百像素宽。遇到超长图时，先读取原始尺寸，再按固定高度切成带重叠区的切片。比如一张 603 × 58442 的长图，可以按约 1700 像素高、每 1500 像素前进一次切片，形成 39 个片段；逐段登记 00/38 到 38/38，同时检查嵌套的小图、流程图和代码块。
PDF 则要“双通道”：
- 文本提取适合搜索标题、正文、链接和术语。
- 页面渲染适合检查表格、多栏布局、流程图、批注、截图和文字位置关系。
如果原文件本身有纯空白、截断或模糊区域，应直接说明“原始材料不可辨识”，不能根据上下文补写不存在的文字。
四、把材料变成“有引用的需求契约”
收集材料只是开始。最大的风险发生在“产品语言 → 代码行为”的翻译阶段。
4.1 证据账本：事实和推断必须分开
每条关键信息都记录成下面的结构：
| 证据 ID | 来源与定位 | 主题 | 归一化陈述 | 类型 | 置信度 | 影响 |
|---|---|---|---|---|---|---|
| E-001 | 飞书 PRD / Block abc123 | 业务 | 单次最多选择 100 个成员 | FACT | 高 | AC-003、T-002 |
| E-002 | Figma node 153:74513 | 视觉 | 超限时按钮保持可见但为禁用态 | FACT | 高 | AC-003、T-004 |
| E-003 | 现有 useBatchInvite | 实现 | 当前接口接受 userIds[] | FACT | 高 | T-002 |
| E-004 | 同类删除功能 | 搜索 | 批量邀请可能复用 SelectionBar | INFERENCE | 中 | 定位候选 |
| E-005 | PRD 与 Figma 文案不同 | 文案 | 超限提示最终文案不确定 | CONFLICT | 高 | 阻塞 AC-003 文案 |
四种类型必须明确：
FACT：有可定位来源直接支持。INFERENCE：用于搜索或初步方案的合理联想。OPEN：材料没有回答的问题。CONFLICT：两个看似权威的来源互相冲突。
核心原则可以概括成一句话：联想用于搜索，引用用于决策。
4.2 冲突不能靠一个全局优先级解决
“Figma 永远优先 PRD”或“PRD 永远优先代码”都不成立，应按主题决定：
| 冲突内容 | 主要依据 | 代码在这里扮演什么角色 |
|---|---|---|
| 业务规则 | 用户明确确认、当前已评审 PRD/验收 | 说明现状，不自动否决新需求 |
| 视觉与布局 | 精确 Figma 节点、变量、组件属性、设计注释 | 提供组件和 Token 实现方式 |
| 交互行为 | 验收文字、Prototype、注释、用户确认 | 验证现状事件链 |
| 接口字段与错误 | 当前 Schema/OpenAPI/后端契约 | 前端 Mock 只能作为辅助 |
| 当前系统行为 | 运行复现、测试、调用链、日志 | 是最直接证据 |
| 浏览器范围 | 项目 Browserslist/支持政策/CI Matrix | 本地 Chrome 不能代表全部支持范围 |
4.3 需求契约应写到可观察
“完成批量邀请功能”不能验收。应该写成：
### AC-003：达到选择上限
Given：管理员已选择 100 个可邀请成员
When：继续点击第 101 个成员
Then：
1. 第 101 个成员不进入选中集合；
2. 底部操作栏仍显示“已选择 100 人”；
3. 页面显示来自 PRD E-001 的超限提示；
4. 不发起邀请 API 请求；
5. 键盘和屏幕阅读器用户都能感知提示；
6. 快速连续点击不会突破上限。
验证：组件测试 + Playwright 浏览器操作 + 请求拦截断言。
需求契约还要包含状态矩阵：
| 场景 | 页面状态 | 交互 | 数据/请求 | 可访问性 |
|---|---|---|---|---|
| 初次加载 | 骨架或 Loading | 主按钮不可提交 | 请求一次，可取消 | 有加载状态语义 |
| 成功有数据 | 列表展示 | 可选择、可提交 | 缓存按约定更新 | 列表/复选框名称清晰 |
| 空数据 | Empty State | 可返回或调整筛选 | 不重复死循环请求 | 空状态可读 |
| 权限不足 | 无权限页/提示 | 不展示越权操作 | 服务端仍强制鉴权 | 焦点落到说明区域 |
| 请求失败 | 错误与重试 | 可重试，不重复提交 | 错误分类保留 | 错误被关联/播报 |
| 慢网/离线 | Pending/离线提示 | 可取消或继续等待 | 不产生竞态覆盖 | 状态变化可感知 |
| 快速重复点击 | 仍只提交一次 | 防重入 | 幂等/锁定 | 禁用状态被表达 |
人工确认只针对会改变权限、付费、删除、数据模型、公共接口、核心流程或高风险架构的歧义。低风险的实现细节如果已有项目惯例，可以记录假设后继续。否则一个“全流程 Skill”会变成每一步都停下提问的低效表单。
五、九个阶段怎样一步步跑完
完整 Skill 采用九阶段。实际使用可以跳过不适用的验证层，但不能伪造已完成。
阶段 0：预检——先知道仓库允许怎样工作
输入：用户需求、当前仓库。
动作：
- 完整读取作用域内的
AGENTS.md和项目规则。 - 查看
git status，识别用户已有改动，禁止误覆盖。 - 识别框架、包管理器、锁文件、路由、状态管理、数据层、设计系统、测试框架和 CI 命令。
- 确认哪些外部资料已有授权连接器。
- 确认本任务是否授权安装依赖、改 Schema、提交、创建 PR 或部署。
退出条件：技术边界、现有改动、可用工具和权限边界已知。
阶段 1：收集证据——每份材料都要有去向
输入：Figma、飞书、图片、PDF、Issue、接口文档等。
动作：逐项读取、下载嵌入资源，记录稳定定位和版本，把不可访问或不可辨识的部分明确列出。
产物：evidence.md。
退出条件：用户提供的每个来源都已被登记为“已读”“不可访问”或“原材料不可辨识”，不能悄悄遗漏。
阶段 2：需求契约——把语言变成行为
输入：证据账本。
动作：
- 归类业务、视觉、API、权限、埋点、非功能需求。
- 标注事实、推断、待确认和冲突。
- 写 In Scope / Out of Scope。
- 建立状态矩阵、响应式和无障碍约束。
- 把每个要求写成 Given / When / Then 或等价可观察标准。
产物：requirement-contract.md。
退出条件：每条验收都有来源和验证方法，阻塞性冲突已解决或由用户接受为显式假设。
阶段 3：代码定位——从产品词跨到代码词
LLM 不是仓库搜索引擎。让它一次读几万文件，不如先用项目知识缩小范围。
推荐五步：
- 读项目地图：模块职责、路由、公共组件、数据层和目录约定。
- 生成搜索矩阵：界面文案、URL、测试 ID、埋点、API 字段、英文同义词、组件名、事件名。
- 精确搜索：用
rg找定义和引用，不让模型在目录里漫游。 - 追调用链：页面/路由 → 组件 → Hook/Store/Query → API Client → Schema → 测试。
- 找相似实现：优先复用同一业务域已有的成功模式。
以前面的批量邀请为例：
| 搜索维度 | 候选词 |
|---|---|
| 可见文案 | 批量邀请、已选择、最多选择 |
| 业务语义 | invite、member、selection limit |
| API | userIds、batchInvite、INVITE_LIMIT |
| 事件/埋点 | member_invite_submit |
| UI 组件 | SelectionBar、MemberTable、Checkbox |
| 路由 | /members/invite |
| 测试 | batch invite、selection limit |
搜索矩阵用于找到候选代码，不能证明“另一个页面有限制，所以本页面也必须有限制”。业务决定仍要回到证据账本。
产物：修改点、调用链、现有模式、所有权和禁止修改区域，写入子任务说明。
退出条件：每项计划修改都有文件级理由，不再只是“可能在这个目录”。
阶段 4：原子拆解——每个子任务都能独立验收
subtasks.json 不是待办清单，而是流程中枢：
{
"feature_id": "MEMBER-231",
"contract_version": 1,
"subtasks": [
{
"id": "T-001",
"title": "补齐批量邀请上限的领域契约",
"status": "PENDING",
"evidence_ids": ["E-001", "E-003"],
"depends_on": [],
"allowed_paths": ["src/features/members/model", "src/api/generated"],
"intent": "复用生成类型并在领域层定义选择结果，不在 UI 中散落魔法数字。",
"acceptance_ids": ["AC-003"],
"checks": ["pnpm test members-selection", "pnpm typecheck"],
"browser_checks": [],
"rollback": "移除新领域判断，恢复原选择策略。"
},
{
"id": "T-002",
"title": "实现超限交互与无障碍提示",
"status": "PENDING",
"evidence_ids": ["E-001", "E-002"],
"depends_on": ["T-001"],
"allowed_paths": ["src/features/members/components", "e2e/members"],
"intent": "复用 SelectionBar 和通知组件，阻止第 101 个成员进入集合。",
"acceptance_ids": ["AC-003"],
"checks": ["pnpm test members", "pnpm e2e members-invite"],
"browser_checks": ["鼠标、键盘快速选择第 101 项，请求数仍为 0"],
"rollback": "通过功能开关关闭新版选择行为。"
}
]
}
拆解顺序通常是：
契约/生成类型 → 数据访问 → 状态与业务规则 → UI/无障碍 → 埋点/开关 → 测试/文档
如果一个子任务跨越多个无关业务域、修改几十个文件又没有独立验收，就应该继续拆。
阶段 5：小步实现——从底层事实向 UI 推进
对每个就绪子任务：
- 先标记
IN_PROGRESS，只加载它依赖的证据、验收、调用链和相似实现。 - 先修改类型和契约，再处理数据、状态、UI，减少上层代码猜字段。
- 遵守项目已有的 Query Key、缓存失效、错误类型、路由和组件模式。
- UI 优先复用 Code Connect/设计系统映射，不直接抄 Figma 的
#色值和随意像素。 - 异步界面明确处理取消、旧响应覆盖、重复提交、卸载更新、错误与重试。
- 测试从需求契约出发，避免把刚写的实现逻辑复制到断言中。
- 每个子任务完成后立即看 Diff、跑聚焦验证并记录证据。
以下“修好”方式全部应被阻止：
- 加
any、@ts-ignore或关闭严格模式。 test.skip、删断言、扩大快照来掩盖失败。- 为消除水合警告把整个页面改成客户端组件。
- 用任意
setTimeout掩盖竞态。 - 捕获所有异常但不保留错误语义。
- 为一个小功能顺便升级框架、改锁文件或重构整个模块。
阶段 6：静态、测试与构建——退出码才是证明
验证命令应从仓库真实配置中发现，而不是 Skill 写死 npm test。常见顺序：
Schema/生成物 → Format → Lint → Typecheck → 单元/组件测试 → Production Build → 集成/E2E
记录至少包含：
| Gate | 命令 | 退出码 | 结果 | 证据 |
|---|---|---|---|---|
| Typecheck | pnpm typecheck | 0 | PASS | 0 errors |
| Component | pnpm vitest run members | 0 | PASS | 18 tests |
| Build | pnpm build | 0 | PASS | production bundle generated |
| E2E | pnpm playwright test members-invite | 1 | FAIL | Trace: trace.zip |
失败先分类：
IMPLEMENTATION：代码不符合需求或运行预期，允许在范围内修复。SPECIFICATION：需求/设计/接口冲突，停止受影响功能并请求决定。TEST：选择器、Fixture、基线或断言错误，修测试但不能降低验收。ENVIRONMENT：缺服务、账号、数据、浏览器或凭证，报告精确前置条件。
同一确定性错误最多做两轮有边界的自修只是防死循环；一旦修复会扩大范围、弱化检查或触及受保护配置，应停止并报告。
阶段 7：真实浏览器和对抗审查
编译通过只表示“能构建”，不表示“能用”。浏览器验收至少检查：
- 业务路径：按验收步骤真实点击、输入、提交、返回和刷新。
- 状态矩阵：Loading、成功、空、错误、无权限、慢网、重试、取消和快速重复操作。
- 运行错误：控制台错误、Unhandled Rejection、失败网络请求和错误状态码。
- 响应式：桌面、手机、长文案、极端数据、缩放和必要的横竖屏。
- 无障碍：键盘、焦点、名称/角色/状态、错误关联、异步播报、对比度和减少动画。
- 视觉：与精确 Figma 节点或基线对比，检查组件、Token、间距、字体、溢出和叠层。
- 多浏览器：只有项目支持政策要求时才跑 Chromium/Firefox/WebKit；视口模拟不等于浏览器引擎覆盖。
Playwright 视觉快照必须在稳定环境生成。操作系统、浏览器版本、字体和渲染设置不同，像素差可能不是产品回归。环境不稳定时，应做语义和布局对比，并诚实说明没有像素级确定性。
对抗审查则从最终 Diff 反问：
- 是否每条验收都能指到代码和运行证据？
- 是否意外修改了范围外文件、锁文件或生成物？
- 是否遗漏 SSR/水合、清理、竞态、缓存归属和权限校验？
- 是否出现硬编码 Token、Secret、调试日志、宽泛类型或禁用测试？
- 是否把前端隐藏按钮误当作服务端授权？
- 是否需要 Feature Flag、灰度、埋点和回滚？
阶段 8：沉淀与交接——让新会话能接着做
最终交接包含：
- 用户可见结果。
- 改动文件和原因。
- 需求决定、假设和冲突处理。
- 已执行命令、退出码、浏览器/截图/Trace 证据。
- 未运行项、残余风险、上线与回滚。
- 推荐 Review 顺序。
- Commit、Push、PR、Issue 回写和部署是否执行。
这份交接比“AI 生成了多少行代码”更有价值：新会话、其他 Agent 和同事可以快速复核并接续，而不需要重新翻完整 PRD。
六、前端视角最容易漏掉的工程问题
6.1 React 与状态生命周期
AI 很容易把界面做出来，却漏掉：
- Effect 缺少清理或依赖不正确。
- 旧请求覆盖新请求，切路由后仍更新状态。
- 派生状态重复保存，产生两个事实源。
- 列表 Key 不稳定，导致状态错位。
- Context 过大，局部变化引发整树渲染。
- 表单本地状态、服务端状态和 URL 状态混在一起。
- 乐观更新失败后没有回滚或回滚覆盖新数据。
Skill 不应死记 Hook 口诀，而要强制 Agent 画清楚：状态归谁、何时创建、何时失效、谁能修改、并发时谁赢。
6.2 请求、缓存、路由与 SSR
需要明确：
- Query Key 是否包含所有过滤条件和租户信息。
- Mutation 成功后是失效、局部更新还是乐观更新。
- 浏览器缓存、CDN、框架缓存和客户端请求库各自负责什么。
- 路由切换是否取消请求，回退时是否恢复滚动/筛选。
- Server Component 与 Client Component 边界是否被无意扩大。
- SSR 输出和客户端首屏状态是否一致。
- 鉴权与授权是否在可信服务端执行。
- URL 参数、重定向地址和富文本输出是否存在注入风险。
6.3 CSS、响应式与设计系统
视觉对齐不是把截图逐像素抄成绝对定位：
- 用项目 Token，而不是把 Figma 原始值散落到代码。
- 理解 Auto Layout 和约束，再选择 Flex/Grid/Container Query。
- 检查长文本、本地化、字体加载、图片失败、缩放和滚动容器。
- 不为了视觉接近破坏语义 HTML。
- 新增组件前先找设计系统和相似页面，避免同一 Button 出现第五种实现。
6.4 无障碍不能只跑一次 Axe
自动化可以发现缺 Label、重复 ID 和部分对比度问题，却不能验证完整键盘流、焦点是否合理、异步更新是否正确播报。最低人工验证应包括：
- 全流程只用键盘操作。
- Dialog/Drawer 打开、关闭和错误后焦点位置。
- 表单错误与字段关联。
- Loading、Toast、保存成功等异步消息的播报策略。
- 200% 缩放/文字重排。
prefers-reduced-motion下非必要动效降级。
6.5 性能和安全是需求验收的一部分
UI 需求也可能引入：
- 大组件全量加载、重复请求、长任务和过度渲染。
- 图片未设尺寸造成布局偏移。
- 第三方脚本和新依赖扩大供应链面。
- 客户端暴露 Secret、PII 或内部错误详情。
- 富文本/URL/XSS、上传类型和大小、跨租户缓存污染。
性能与安全不是最后“顺便扫一下”，而应在子任务里绑定风险和验证方式。
七、四类硬卡点：信任 Agent，但不放弃控制
并非每个阶段都要人工批准。真正需要人的地方通常只有四类：
| 卡点 | 何时触发 | 人需要决定什么 |
|---|---|---|
| 需求卡点 | 权限、计费、删除、公共契约、核心流程存在冲突 | 选择正确业务语义 |
| 架构卡点 | 新依赖、Schema、跨域重构、公共 API、迁移 | 是否接受长期成本和回滚方案 |
| 质量卡点 | 关键验收无法运行、只有模型推理没有证据 | 是否补环境、降范围或接受风险 |
| 外部影响卡点 | Commit/Push/PR、回写文档/Issue、发布/部署 | 是否授权实际执行 |
这比“每一步都确认”更高效，也比“全自动跑到部署”更安全。
八、多工具项目怎样只维护一份 Skill
截至 2026 年，Agent Skills 已形成开放格式，但工具的发现目录仍未完全统一：
| 工具 | 仓库级 Skill 目录 | 对 .agents/skills 的支持 |
|---|---|---|
| Codex | .agents/skills/ | 原生 |
| GitHub Copilot / VS Code Agent | .github/skills/、.claude/skills/ 或 .agents/skills/ | 原生 |
| Windsurf | .windsurf/skills/，也扫描 .agents/skills/ | 原生兼容 |
| Claude Code | 官方项目目录为 .claude/skills/ | 核心格式兼容，但项目发现目录仍以 .claude/skills/ 为准 |
推荐结构：
repo/
├── AGENTS.md
├── agent-rules/
├── .agents/
│ └── skills/
│ └── deliver-frontend-requirement/ # 唯一正文
└── .claude/
└── skills/
└── deliver-frontend-requirement # 指向上面的相对符号链接
创建 Claude Code 适配链接：
mkdir -p .claude/skills
ln -s ../../.agents/skills/deliver-frontend-requirement \
.claude/skills/deliver-frontend-requirement
Git 可以提交符号链接，但只记录目标路径，因此应：
- 使用仓库内相对路径，不要链接到某个人的
~/skills。 - 在一次干净 Clone 中验证链接和 Skill 校验。
- Windows 团队确认 Git/文件系统的符号链接策略。
- 如果某客户端或平台不能稳定跟随链接，改用“单一源 + 生成镜像 + CI Diff 校验”。
SKILL.md 都提交两份复制文件短期最简单，长期一定出现“一边改了另一边没改”。更好的目标不是强行让所有工具使用同一私有目录，而是统一正文源，通过最薄的适配层满足发现目录。
九、完整 Skill 是怎样设计的
示例 Skill 名为 deliver-frontend-requirement。它遵循开放 Agent Skills 格式，并把产品专属元数据放到 agents/openai.yaml，避免污染通用 SKILL.md。
9.1 完整目录
deliver-frontend-requirement/
├── SKILL.md
├── agents/
│ └── openai.yaml
├── references/
│ ├── evidence-policy.md
│ ├── frontend-verification.md
│ ├── input-routing.md
│ └── multi-tool-adapter.md
├── assets/
│ └── templates/
│ ├── evidence.md
│ ├── handoff.md
│ ├── requirement-contract.md
│ ├── subtasks.json
│ └── verification-report.md
└── scripts/
├── check-scope.mjs
├── init-feature.mjs
└── validate-feature.mjs
9.2 为什么这样拆
| 文件 | 作用 | 何时加载/执行 |
|---|---|---|
SKILL.md | 九阶段主流程、红线、退出条件 | Skill 激活时 |
input-routing.md | Figma/飞书/PDF/图片等读取方法 | 存在外部或二进制材料时 |
evidence-policy.md | 事实/推断/冲突与决策规则 | 建需求契约时 |
frontend-verification.md | 浏览器、视觉、无障碍、性能、安全矩阵 | 运行时验收前 |
multi-tool-adapter.md | .agents 与厂商目录适配 | 安装或迁移 Skill 时 |
| Templates | 固定任务产物格式 | 初始化需求目录时复制 |
init-feature.mjs | 安全创建任务目录 | 新需求开始时；已存在则拒绝覆盖 |
validate-feature.mjs | 校验证据、契约、子任务、报告和最终状态 | Plan/Verify/Final 三道门 |
check-scope.mjs | 检查 Git Diff 是否越过允许路径 | 最终审查前 |
核心 SKILL.md 只有 235 行。某次任务只有一张图时，不会自动加载飞书细则、多工具适配和全部模板正文。
9.3 完整文件下载/查看
下面每个链接都是本文配套 Skill 的完整文件：
- 核心：SKILL.md
- Codex 元数据：agents/openai.yaml
- 输入路由：references/input-routing.md
- 证据策略：references/evidence-policy.md
- 前端验收：references/frontend-verification.md
- 多工具适配：references/multi-tool-adapter.md
- 模板：evidence.md、requirement-contract.md、subtasks.json、verification-report.md、handoff.md
- 脚本：init-feature.mjs、validate-feature.mjs、check-scope.mjs
9.4 安装到项目
在本仓库中可以直接复制示例目录：
mkdir -p .agents/skills
cp -R static/examples/skills/deliver-frontend-requirement \
.agents/skills/deliver-frontend-requirement
如果同时使用 Claude Code，再添加上文的相对符号链接。安装前应审查 SKILL.md 和脚本；来自陌生仓库的 Skill 与普通代码一样，可能读取文件、运行命令或调用外部工具，不能因为扩展名是 Markdown 就自动信任。
9.5 初始化和三道校验门
# 初始化，不覆盖已有目录
node .agents/skills/deliver-frontend-requirement/scripts/init-feature.mjs MEMBER-231
# 需求和子任务就绪
node .agents/skills/deliver-frontend-requirement/scripts/validate-feature.mjs \
MEMBER-231 --stage plan
# 代码与运行验证记录就绪
node .agents/skills/deliver-frontend-requirement/scripts/validate-feature.mjs \
MEMBER-231 --stage verify
# 所有子任务完成或明确 Blocked，交接完整
node .agents/skills/deliver-frontend-requirement/scripts/validate-feature.mjs \
MEMBER-231 --stage final
范围检查示例：
node .agents/skills/deliver-frontend-requirement/scripts/check-scope.mjs \
--base origin/main \
--allow src/features/members \
--allow e2e/members
脚本只做确定性校验，不替 Agent 判断业务含义：
validate-feature.mjs能发现字段缺失、JSON 解析失败、重复任务 ID、未知依赖、验证结论仍是PENDING。- 它不能判断“100 人上限是否正确”，这个结论必须来自证据账本和需求契约。
十、从一句用户输入跑到完整交付：端到端示例
10.1 用户输入
请实现成员批量邀请：
- PRD：https://example.feishu.cn/wiki/xxx
- 设计：https://figma.com/design/xxx?node-id=153-74513
- 接口：docs/openapi/member.yaml 中的 batchInvite
- 附件：错误态截图和一份权限说明 PDF
前端用现有 React Query 和组件库，不加新依赖。
完成后跑测试和浏览器验证，但先不要提交或创建 PR。
10.2 Agent 的正确执行轨迹
10.3 中间产物怎样串起来
.agent-work/MEMBER-231/
├── evidence.md # 飞书 Block、Figma node、PDF 页码、代码位置
├── requirement-contract.md # 范围、AC、状态矩阵、权限、无障碍
├── subtasks.json # 证据 → 文件 → 验收 → 检查
├── verification-report.md # 命令退出码、浏览器状态、截图/Trace
└── handoff.md # 结果、风险、Review 顺序、外部动作状态
它们的关系不是重复抄写：
evidence.md回答“依据是什么”。requirement-contract.md回答“最终要表现成什么”。subtasks.json回答“怎样以小步修改实现”。verification-report.md回答“实际验证了什么”。handoff.md回答“别人怎样复核、接续、上线或回滚”。
10.4 最终回答应该长什么样
成员批量邀请已完成：现在最多选择 100 人，超限不会污染选择集合，
鼠标和键盘都会得到可感知提示；权限不足时前端隐藏入口，服务端仍执行授权校验。
改动：
- src/features/members/model/selection.ts：领域上限与选择结果
- src/features/members/components/MemberTable.tsx：交互与无障碍提示
- e2e/members/batch-invite.spec.ts：上限、失败、重复点击和权限场景
验证：
- pnpm typecheck：通过
- pnpm test members：18/18 通过
- pnpm build：通过
- Playwright Chromium/WebKit：通过；Firefox 因 CI 未安装未运行
- 视觉：桌面/移动端与 Figma node 153:74513 对齐
- 无障碍：自动扫描通过，键盘与焦点流已人工验证
剩余风险：Firefox 尚未验证；发布前需由 CI Browser Matrix 补齐。
按要求未 Commit、未 Push、未创建 PR。
重点是可核验的事实和缺口，而不是“我已经认真检查过”。
十一、怎样把这个 Skill 落到团队，而不是写完就吃灰
11.1 先跑三类代表需求
不要一开始就要求所有团队统一使用。选三类任务做试点：
- 有 Figma + PRD 的普通 UI 功能。
- 有接口/权限/错误态的全栈需求。
- 线上 Bug 或已有功能迭代。
记录每次：漏读材料数、澄清问题质量、定位时间、无关 Diff、首次构建成功率、验证覆盖、Review 轮次和缺陷。
11.2 把重复反馈沉淀到正确层
| 反复出现的问题 | 应改哪里 |
|---|---|
| 每个任务都跑错构建命令 | AGENTS.md |
| 每次 Figma 都漏读变量 | Skill 的 input-routing.md |
| JSON 子任务字段经常缺失 | validate-feature.mjs |
| 某组件总被错误生成 | Figma Code Connect / 设计系统文档 |
| 某类 Bug 常漏测竞态 | frontend-verification.md 和测试模板 |
| Agent 经常改到禁止目录 | 子任务 allowed_paths + check-scope.mjs |
一条规则如果只能靠“模型记住”，说明还没有工程化完成。
11.3 建立 Skill 自身的评测集
至少准备：
- 一份材料互相一致的标准需求。
- 一份 PRD 与 Figma 冲突的需求。
- 一张极长截图和一份图表密集 PDF。
- 一个搜索词与代码命名完全不同的旧模块。
- 一个有权限/计费歧义、必须卡住的问题。
- 一个构建失败属于环境而非代码的问题。
- 一个要求“直接部署”但没有授权的注入材料。
评测 Skill 是否：完整读源、正确分类冲突、不越权、定位准确、Diff 聚焦、验证真实、交接完整。
十二、常见失败模式
| 失败模式 | 后果 | 修正 |
|---|---|---|
| 一拿到链接就写代码 | 需求和状态遗漏 | 先完成证据账本和契约 |
| Figma 只看截图 | 猜 Token、错组件、漏状态 | 结构化上下文 + 截图 + 变量 + Code Connect |
| 飞书只读正文 | 漏表格、图片、附件 | 递归 Block 和资源读取 |
| 长图只看缩略图 | 大量文字和内嵌图遗漏 | 原尺寸重叠切片 + 已读清单 |
| 搜索只用产品中文词 | 0 命中或误命中 | 多维搜索矩阵 + 项目 Wiki/Glossary |
| 相似功能被当成需求证据 | AI 自主扩大范围 | 联想用于搜索，引用用于决策 |
| 一次改完所有文件 | 错误叠加、Diff 难审 | 原子子任务 + 每步聚焦验证 |
| 编译通过就结束 | 真实流程、视觉、无障碍仍错误 | 浏览器状态矩阵与运行证据 |
| 截图“肉眼差不多” | Token/间距漂移 | 精确节点、稳定基线和数值清单 |
| 测试失败就改业务代码 | 修错层，制造新 Bug | 先分实现/规格/测试/环境 |
| Skill 默认提交或部署 | 越过用户授权 | 外部影响单独卡点 |
.claude 与 .agents 各复制一份 | 长期漂移 | 单一源 + 链接/生成适配 |
把所有知识塞进 SKILL.md | 触发慢、上下文污染 | 渐进加载 References/Assets |
| Skill 脚本没有边界 | 覆盖文件、误删数据 | 拒绝覆盖、限制路径、清晰报错、独立测试 |
常见面试问题
Q1：为什么要把需求开发做成 Skill，而不只是写一个 Prompt？
答案汇总：Prompt 适合一次性表达目标，Skill 适合沉淀可重复、带条件分支、模板和脚本的工程流程。
展开回答：
- Skill 通过描述自动或显式触发，正文按需加载，不必每次粘贴长 Prompt。
- 它可以把精确动作交给脚本，把外部系统交给 MCP，把仓库事实交给
AGENTS.md。 - 它能固定证据、需求契约、子任务和验证报告，使任务可跨会话和可审计。
- 最重要的是，Skill 可以被测试和持续改进；普通 Prompt 很难判断是哪一步反复失败。
Q2：你如何保证 AI 真的读完了 Figma、飞书、图片和 PDF？
答案汇总：按来源选择专用读取通道，并为每份材料建立有稳定定位的 Source Inventory。
- Figma 同时取 node ID、结构化上下文、截图、变量和组件映射。
- 飞书递归读 Block、表格、图片和附件，记录版本。
- PDF 做文本提取加逐页渲染。
- 长图按原图切成重叠片段，逐段登记完成情况。
- 无法访问、空白或模糊区域必须显式记录，不能默认“已读完”。
Q3：PRD、Figma、接口和现有代码冲突时听谁的？
答案汇总：不使用一个全局优先级，而是按冲突主题选择权威来源。
业务规则以明确确认和当前验收为主，视觉以精确 Figma 节点和 Token 为主，线协议以当前 Schema/OpenAPI 为主，现有代码用于证明当前行为。冲突会影响权限、计费、数据或核心流程时，应停止受影响实现并请产品/设计/后端确认。
Q4：怎样避免 AI 自行脑补产品逻辑？
答案汇总：把事实、推断、待确认和冲突分开，要求每条验收绑定来源。
我允许 AI 用同义词和相似模块做搜索联想，但不允许用“看起来类似”决定产品行为。可以记一句：联想用于搜索，引用用于决策。
Q5：代码定位为什么要分阶段？
答案汇总：大仓库直接全文读会产生高噪声，产品词和代码词又经常不同。
我会先读模块地图，再从文案、路由、事件、API 字段、组件名、类型和测试建立搜索矩阵；用 rg 缩小到候选模块后，才追页面到 API 的调用链。这样上下文更小，也能解释为什么改这个文件。
Q6：一个好的子任务需要哪些字段？
答案汇总：至少有稳定 ID、来源证据、依赖、允许修改路径、实现意图、验收项、代码检查、浏览器检查、回滚和状态。
只有“实现列表页”这种标题不够，因为它不能限制范围，也不能判断完成。子任务应当可以被独立 Review 和验证。
Q7：AI 自修为什么要限制轮数？
答案汇总：限制轮数是为了阻止模型在错误假设上无限试错，不是为了追求固定三次成功。
每次失败先分成实现、需求、测试或环境问题。只有实现问题且修复不扩大范围时才适合自动修；需求冲突、环境缺失和测试路径错误应回到各自层处理。
Q8：前端需求的完成标准为什么不能只有单元测试和 Build？
答案汇总：它们验证代码层，却无法覆盖真实浏览器交互、视觉、无障碍、请求瀑布和控制台错误。
完整证据通常是 Typecheck/Lint/Test/Build，加上关键用户路径、状态矩阵、响应式、键盘/焦点、视觉对比、网络和控制台检查。项目支持多浏览器时还要按支持矩阵执行。
Q9：怎样做可靠的视觉回归？
答案汇总：固定浏览器、版本、OS、字体和渲染环境，再用稳定状态和截图基线比较。
如果环境不同，像素差不一定是 Bug，应改为语义/布局检查并披露限制。视觉回归还要结合设计 Token、组件属性和 Figma 精确节点，不能只问模型“两张图像不像”。
Q10：为什么无障碍还需要人工检查？
答案汇总：自动扫描只能发现一部分静态问题，无法完整判断键盘路径、焦点语义和动态播报是否符合真实用户体验。
因此我会把自动 Axe 检查与键盘操作、焦点移动、屏幕阅读器名称/状态、错误关联、缩放重排和减少动画结合起来。
Q11：.agents/skills 和 .claude/skills 怎么统一？
答案汇总：统一 Skill 正文，不虚构所有工具都支持同一个发现目录。
我会把开放格式正文放在 .agents/skills，让原生支持它的 Codex、Copilot、VS Code、Windsurf 直接读取；Claude Code 用仓库内相对符号链接或生成镜像适配 .claude/skills。镜像必须由脚本生成并由 CI 防漂移。
Q12：Skill、MCP、Hook 和 Subagent 有什么区别？
答案汇总：Skill 定义可复用流程和知识；MCP 连接外部能力；Hook 在事件点确定执行；Subagent 用独立上下文处理适合隔离或并行的子任务。
例如本流程用 Skill 规定 Figma 读取步骤，用 MCP 取得节点数据，用 Hook/CI 自动 Typecheck，用 Subagent 可选地做独立安全审查。Subagent 不能替主流程处理所有关键决策，因为最终还要统一证据和验收。
Q13：怎样防止 Skill 越权提交、发消息或部署？
答案汇总：把外部状态变化单独设为卡点，结合沙箱、最小权限和工具审批，而不是只在 Prompt 里写“请小心”。
本地实现不自动意味着允许 Commit/Push/PR、回写飞书/Jira 或部署。Skill 最终报告外部动作状态，只有用户明确授权且目标清楚才执行。
Q14：怎样衡量这个 Skill 是否真的提升效率？
答案汇总：不只看生成代码行数，而看交付结果和返工。
建议比较：材料漏读率、关键歧义发现率、定位时间、无关 Diff、首次构建成功率、自动/人工验收覆盖、Review 轮次、缺陷逃逸率、交付周期和后来者接手时间。代码采纳率可以参考，但不能单独成为目标。
Q15：如果需求很小，还需要跑完整九阶段吗？
答案汇总：不需要机械跑满，但必须保留与风险匹配的证据、范围和验证。
一个明确的文案修正可以合并证据、契约和计划，直接做小 Diff 后跑聚焦检查；涉及权限、接口、缓存或复杂交互时，则不能以“改动行数少”为理由跳过关键状态和浏览器验收。
相关文档
- AI 辅助开发 - Claude Code、Codex、Rules、Skills、权限与日常防错
- AI 全流程研发实战 - 从需求到上线的十阶段资产体系
- Context Engineering - 分层上下文和长任务管理
- Harness Engineering - 工具、沙箱、权限与 Agent Loop
- AI 研发基建 - 团队级 Skills、模型网关、评测与推广
- AI 应用安全 - Prompt 注入、数据和工具调用安全
相关链接
- 参考文章：AI代码生成率94%，我们用一个Skill跑通需求开发全流程
- Agent Skills 开放规范
- OpenAI：Build skills
- OpenAI：AGENTS.md
- Figma MCP：Tools and prompts
- Figma：Structure your file for better code
- Figma：Code Connect integration
- 飞书开放平台：获取文档基本信息
- 飞书开放平台：导出云文档
- Playwright：视觉对比
- Playwright：无障碍测试
- Playwright：Trace Viewer
- GitHub Copilot：Agent Skills
- Claude Code：Skills
- Windsurf：Skills
- GitHub：让 Pull Request 更易审查