蓝图技能：从一个模糊想法，到彼此理解一致的项目

你可以把蓝图理解成一份“人与 AI 对项目的共同理解”。它先弄清想要的结果、业务怎么运转、现成能力能做什么，再决定怎样实现。它的价值不是文档数量，而是减少“AI 做了很多，但不是你想要的”这种偏差。

这份教程给操作者阅读；简短的 SKILL.md 给 AI 判断什么时候使用、需要读取哪些资料。教程可以详细，AI 的每次工作上下文仍然可以很小。

1. 为什么模型很强，仍然需要蓝图

模型可以越来越擅长写代码、找资料、排错，但无法凭能力推导出你没有表达的偏好。例如“做个项目学习网站”，可能是文件目录、公开博客、带可运行 Demo 的实验室，也可能是售卖课程的平台。每一种都能被做得很好，却不一定是你需要的。

因此，模型越强，通常越适合减少“先写某个文件、必须跑固定几轮评审”这种机械限制，把共同注意力放在三件事上：你想得到什么、哪些含义不能误解、用什么结果判断做对了。必要的权限与真实副作用边界仍然要明确。

蓝图不要求你先学会技术术语。AI 应把抽象问题翻译成场景和选项，比如：“你是要看懂别人的 Skill，还是以后把 Skill 安装到自己的项目？如果两者都要，我建议分别维护学习页面和可携带源文件。”

2. 什么情况下使用，什么情况下不用

你的情况	蓝图介入到什么程度
有一个想法，但目标和范围还模糊	从场景与可见结果开始建立基线
接手一个项目，文档和实际行为对不上	先核对当前实现，再澄清目标；不把旧文档自动当真
新增用户角色、权限、流程或对外行为	从受影响的语义层修订，检查必要下游
把本地工具变成公开网站	核查发布范围、内容可见性、域名与运行边界
改颜色、放大字体、修一个契约内 Bug	直接处理相关实现，无需重写整套蓝图
临时做一个可丢弃小原型	一份短说明可能足够，不必建立四个空文档

判断关键不是“改了多少行代码”，而是“改变了什么含义”。一次一行的权限修改可能需要语义讨论；一次几百行的等价重构可能不需要重开蓝图。

3. 你先提供什么，AI 应该补齐什么

你先用自然语言讲出任务就可以，最好带一个实际例子。比如：“我以后会拖进很多项目，希望打开一个网页就知道它们做什么，能看看 Demo，还能把有用的 Skill 带到别的项目。”

AI 应主动提炼：谁使用、当前哪里不方便、最重要的动作、你希望看到的结果、已有资料和限制。缺口影响结果时再追问，并给推荐和理由。不要一次向你抛出二十个架构问题。

你可能说的话	AI 需要进一步对齐的含义
“要高级一点”	适合长期阅读还是视觉展示？先给具体样例比较
“全部自动”	哪些可自动分析/生成，哪些会发消息、花钱、覆盖数据或公开内容？
“像某个项目一样”	借用配色、布局、交互，还是业务能力？不能全盘复制不相关部分
“以后一直添加”	目录应允许新领域、新类型与关联，不能把当前示例数量写死
“定期同步”	先检查并给差异建议，还是已授权自动更新？两者副作用不同

对齐是贯穿项目的沟通，不是开工前的一次问卷。先做一个代表性闭环给你看，你指出阅读或操作障碍后，AI 应将其转化为可检验的体验标准并调整。

4. 第一层：PRD，定义你要得到什么

PRD 是产品需求说明。它面向用户结果，回答：为什么做、给谁用、这次做哪些事情、哪些暂时不做、怎样判断成功。

以学习空间为例，“使用 React”不是用户结果；“搜索蓝图，点开读懂它，看到完整案例，并下载 Skill”才是可验收结果。技术栈应服务于这个结果。

一个足够具体的 PRD 片段可以是：

用户：不是前端专业人士的项目操作者。
场景：接收到一个陌生 Skill，不清楚用途和实际效果。
结果：能找到说明，理解适用场景，打开 Demo，知道能否复用。
本期：目录、搜索、详情、教程、Demo、Skill 下载与来源检查。
暂不做：课程交易、多人账号、网页直接运行任意服务器命令。
验收：不依赖操作者先认识专业名词，也能完成上述动作。

这一层不需要提前枚举数据库每个字段。先把目的对齐，避免用技术细节掩盖需求分歧。

5. 第二层：BUSINESS，统一对象、流程和规则

BUSINESS 是业务说明，目的是统一大家说的词。学习空间里的“Skill”“学习条目”“Demo”“上游”“学习路线”看似简单，若不区分，后面就会出现误解。

例如：下载 Skill ZIP 只是得到文件，不等于已经在其他项目安装成功；风格原型可以帮助选方向，不等于已经接入官方组件库；FDE 是跨领域的学习路线，不应该把所有内容复制到一个 FDE 文件夹里。

对象	在本项目中的含义	容易误会的地方
学习条目	一个有稳定 ID、用途和来源的学习主题	不等于一套必须安装的工具
Skill	给 AI 调用的可复用方法与必要资源	不等于人类教程全文，也不保证每次都会自动触发
Demo	说明或演示某个效果的可见入口	原型、模拟数据、真实业务要区分
上游来源	当前副本来自哪里、接受了哪个版本	官方首页链接不等于已具备自动更新检查
学习路线	按某个角色或问题串起已有内容	不等于强制执行流程，也不等于完整课程已准备好

流程也需要明白：提供新项目 → 盘点 → 与你确认用途和价值 → 归类 → 登记说明与 Demo → 验证 → 有复用需要时沉淀 Skill。这里描述的是行为含义，不是规定 AI 每一步用什么工具。

6. 第三层：TECHNICAL，用什么承接这些结果

TECHNICAL 是技术方案。它从业务需要推导组成部分、数据如何流转、系统之间的边界、选择理由和关键假设。

学习空间首版选择文件目录、精选 Markdown、生成后的 HTML，是因为当时主要需求是本地浏览与双击打开。当前没有登录与在线编辑需求，就不必先引入账号服务、数据库和管理后台。后来要求公开部署，则增加明确发布清单、域名、Web 服务、HTTPS 与回滚办法。

这不是“越少技术越好”的固定结论。如果未来需要多人编辑、权限隔离或在线执行，技术边界会变，应该重新评估成熟平台和必要后端。蓝图记录的是当前合理的路线，不是永远不可修改的承诺。

技术初稿里的未知项应明确写成假设。例如“域名已可控制”“服务器能监听 HTTPS”“图表库支持需要的交互”。写出来以后还要核验，不能因为文字完整就当作具备实施条件。

7. 第四层：CAPABILITIES，先查成熟方案，再验证能不能做

CAPABILITIES 保存能力依据。核心问题是：当前官方工具、成熟项目和目标环境究竟支持什么，有哪些条件、限制与成本。

优先复用不意味着见到开源仓库就安装。AI 应比较目标是否匹配、维护是否活跃、版本是否兼容、接入是否比自建更简单，最后说明“直接用”“适配一部分”“只保留参考”或“暂不引入”。

本项目研究了 VitePress、Storybook 与 Backstage：它们分别擅长文档站、组件状态展示和软件目录平台。首版小型离线目录暂时不需要整个大型平台；真正开始积累组件代码时，Storybook 可能比持续手写展台更合适。这是按当前需求作出的选择，不是对工具的永久排名。

能力记录至少要让后来的人知道：查了什么来源、什么时候查的、针对什么版本/环境、得到什么结论、哪一步还没有验证。

问题：这套图表原型是否已经使用 Highcharts？
证据：查看页面导入与脚本，只有 Tailwind 和自写 SVG。
结论：它能说明视觉方向，不能证明 Highcharts 集成或图表交互已完成。
下一步：若项目真正需要该能力，核查官方方案并实现代表性图表。

官方文档说“支持”与“你的账号/服务器实际可用”是两种证据。域名控制权、端口、权限、配额和区域，都可能让方案需要调整。

8. 四层不是直线填表：证据会反过来改变方案

发现现实不支持原设想时，应修订受到影响的最早一层。例如所选组件只能处理固定数据量，可能只需调整 TECHNICAL；若它无法满足用户必须完成的任务，就要重新讨论 PRD 的范围或更换方案。

一个典型反馈链是：

用户结果 → 业务含义 → 技术假设 → 官方/环境证据
                                      ↓
                    修正技术；必要时修正业务与产品承诺

不需要每次把四份文档全部重写。修字体属于局部实现；把原先“本地私用”改成“公开访问”，会触及可见内容与部署边界，应同步相关说明。

9. 完整案例：从“自动整理资料”到可验收流程

假设你说：“帮我做一个自动整理项目资料的工具。”先不选框架，先拿三个真实文件夹对齐结果：一个前端组件库、一个安全扫描器、一份产品需求文档。

对齐用户结果。 你需要知道每份资料做什么、能否运行、下次在哪里找到。PRD 因此确定首个闭环：导入资料 → 看见用途和分类建议 → 接受或改分类 → 能再次搜索找到。自动运行陌生项目暂不纳入。

统一业务含义。 “导入”是登记本地副本还是下载远端？“删除”是移出目录还是删除源文件？“自动分类”可否覆盖你手动改的标签？这些问题会影响数据和操作结果，必须在 BUSINESS 明确。本例选择保留原件、人工标签优先，移出目录不删原件。

提出实现。 单人、文件量较少时，可以先用文件目录和清单；多人同时编辑时再评估数据库和账号系统。TECHNICAL 记录当前选择、边界，以及文件移动后如何找到原始资料。

反验能力。 检查成熟目录工具是否支持本地路径、中文搜索、保留标签及导出。如果某工具上传所有文件才能分类，而你的材料含私有内容，就不能直接采用。可以改用本地索引；若仍不能满足需求，再回到产品范围讨论。

验收一个闭环。 导入三个文件夹，修改安全扫描器的分类，再次导入同一项目，确认没有重复副本、手动分类被保留、搜索能找到、原始文件没有改动。通过后再增加批量整理或更新检查。

这里的对齐集中在影响结果的选择。按钮圆角、函数命名等可逆细节，由 AI 根据既有约定完成。

10. 蓝图最终应该交给你什么

你应该能读懂当前要做什么、各概念是什么意思、为什么选这条路线、哪些结论有证据、哪些还要验证，以及下一步可以怎样验收。你不应该只得到一堆写着“待完善”的文件。

实施模块最好按一个你能检查的结果划分。例如“打开条目、阅读完整教程、切换 Demo、返回后保留搜索”，就比“完成前端大包”更具体。

蓝图结束不代表项目实现完毕。部署、真实数据、服务运行和用户主路径各自需要执行与验证。蓝图负责明确这些结果和边界，执行工作按你已授权的范围继续推进。

11. 在其他项目里引入蓝图 Skill

在本页下载蓝图 ZIP，解压到目标项目的 .agents/skills/，保留下面的结构：

你的项目/
  .agents/
    skills/
      blueprint-framework/
        SKILL.md
        agents/
        assets/templates/

然后在目标项目会话中明确说：

使用 $blueprint-framework。
我想做的是……，主要给……使用。
先复述你对目标的理解，并研究成熟方案。
一次只对齐少量关键分歧，不要要求我先懂技术名词。
已有文档能沿用就沿用；不要为了模板完整批量建空文件。

文件放好、会话能发现、实际调用成功，是三个不同检查。若当前会话没有显示这个 Skill，可重新进入项目会话并明确引用源文件；不要把“下载成功”说成“所有项目已自动安装”。

Skill 中的模板用于补遗漏，不是每个项目都要填完。读一份相关模板通常比一次加载全部模板更有效。目标项目已有合适的文档名称和结构时，保持它自己的约定。

12. 与 AGENTS.md、教程、Demo 和执行计划怎样分工

资产	主要读者	应保存什么
AGENTS.md	进入项目的 AI	少量稳定、会改变行为的项目约定
SKILL.md	执行某类任务的 AI	触发范围、方法与按需资源入口
本教程	操作者与学习者	概念解释、例子、对话、常见误解与使用方法
项目蓝图	操作者与实施者	当前产品、业务、技术和能力事实
Demo	想直观看效果的人	可见效果与明确的验证边界
实施计划 / 当前状态	正在执行的人与 AI	本轮结果、验证、剩余事项与恢复入口

不要把这些资产合并成一个越来越长的 Prompt。详细教程留在学习层，相关引用按需进入 AI 上下文；同一事实不要在五个文件里同时维护。

13. 新 Skill 以后如何加入这个学习库

先带来一个明确需求或项目链接。AI 解释它做什么、查官方来源和成熟替代、核对当前内容，然后为它建立用途、场景、案例、Demo 与复用边界。教程是给你学的，Skill 源是给其他项目调用的，两者分别维护。

不是所有资料都要做成 Skill。只想理解一套架构，可以先做学习案例；已有成熟工具，可能只需要一个使用说明；出现重复且有价值的协作任务时，再提炼成 Skill。FDE、产品和安全可以各有专用能力，也可以引用共同的蓝图知识，不必挤进前端 Skill。

上游检查先判断“有变化吗”，再判断“对我们的版本有影响吗”。本地定制和上游更新应分开比较；只有审查后决定接受的版本才更新基线，不让定期检查自动覆盖你的资产。

14. 看完后，你可以怎样开始

选一个你真实想学或想做的项目，给出一句任务和一个例子。先检查 AI 能否准确复述你的目标，再让它给两个有明显区别的可见选项。讨论有分歧的地方，做出一个小结果，再继续扩展。

你可以用这三个问题判断对齐质量：它是否解释清楚为什么做？是否区分事实与假设？你能否通过一个具体动作判断做对了？ 如果这些还不清楚，再多的文件也不能替代沟通。