速通 · 命令行:和电脑说话的第二种方式

为什么绕不开它

很多 AI 编程工具(比如 Claude Code)就活在命令行里:你在一个黑(或白)底的窗口里跟它对话,它替你敲命令、跑程序。命令行对你不是"要精通的技能",是"要不害怕的环境"——90% 的命令是 AI 敲的,你要做的是看懂它在干什么、偶尔自己敲一两条。

打开它

• Mac:启动台搜「终端」(Terminal),回车打开
• Windows:开始菜单搜「PowerShell」,回车打开

打开后是一个等你输入的窗口,光标前面那串字是"提示符"(显示你是谁、在哪个文件夹)。输入命令 → 回车执行 → 看输出,就这一个循环。

你只需要会这 6 条

心智模型:命令行里永远"站在某个文件夹里"。pwd 看自己站在哪,ls 看脚下有什么,cd 走来走去——跟访达/资源管理器是同一棵目录树,只是从点图标变成打字。

5 分钟跟做

一条条敲,每条回车后看输出:

pwd                # 我在哪
ls                 # 这里有什么(Windows 用 dir 也行)
cd Desktop         # 进桌面(Mac/Win 通用;若提示不存在,先 ls 看真实名字)
mkdir fde-test     # 建一个文件夹——现在看你的桌面,是不是多了一个?
cd fde-test        # 进去
pwd                # 确认自己进来了
cd ..              # 退出来

做完你可以把 fde-test 文件夹右键删掉,练习结束。

常见坑(卡住先查这里)

你只需要会这些

到此为止。不需要学管道、grep、vim、shell 脚本——真实工作里复杂命令基本都是 AI 生成的,你看不懂时让它解释("这条命令是干嘛的?逐段解释")就是标准做法。别在命令行教程的兔子洞里花时间。

速通 · Git:代码的存档/读档系统

为什么绕不开它

让 AI 大改代码之前先存档,改崩了一键回滚——这是和 AI 协作的安全带,几乎天天用。另外作品集放到 GitHub/Gitee 上给面试官看,推上去(push)也是 Git 的活。

和命令行一样:大部分 Git 命令会是 AI 帮你敲的,你要懂的是"存档点"这个概念和一条基本流。

四个词,四个动作

心智模型:add 是"选中要存档的改动",commit 是"确认存档",log 是"查看存档列表"。一条基本流:改代码 → add → commit(→ 需要给别人看时 push)。

5 分钟跟做(纯本地,不需要注册任何账号)

接着上一篇的命令行,一条条敲:

cd Desktop
mkdir git-test && cd git-test     # 建个练习文件夹并进入
git init                          # 变成 Git 仓库(出现 Initialized empty...)
echo "第一行" > notes.txt          # 造一个文件
git add -A                        # 选中所有改动
git commit -m "第一个存档"          # 打存档点
echo "第二行" >> notes.txt         # 再改一下文件
git add -A
git commit -m "第二个存档"          # 又一个存档点
git log --oneline                 # 看:两个存档点,各带说明

看到两行存档记录,练习完成(文件夹可删)。这就是全部核心——"让 AI 改崩了怎么办"的答案,就是回到某个存档点。

若 commit 报错让你先设置身份,执行环境线里讲过的 git config --global user.name/email 两条后重试。

GitHub 是什么?现在要注册吗

GitHub 是世界最大的代码托管网站(仓库放在云上+给别人看),国内访问偶尔不稳,国内同类是 Gitee。不用急着注册——真要用的时候再弄,push 的账号/密钥配置 AI 能一步步带你做。

你只需要会这些

到此为止。不需要学分支 branch、合并 merge、rebase、解决冲突——那是多人协作的内容,真用到时 AI 能代劳,你只要在它动手前说一句"先 commit 一下"。看到网上教程里花哨的分支图,跳过,不是你现在的事。

速通 · Web / API / JSON:网页背后发生了什么

前端和后端:餐厅模型

把任何一个网站/App 想成一家餐厅:

• 前端 = 大堂:你看到的界面(菜单、桌椅、装修),跑在你的手机/浏览器里
• 后端 = 后厨:真正干活的程序(算账、查库存、存数据),跑在别人的服务器上
• 你点一道菜(点按钮),服务员把单子递进后厨,后厨做好端出来——这一来一回,就是一次"请求/响应"

一个单文件的小工具,是前端后端挤在一个文件里的极简版;真实企业系统前后端分开,中间靠 API 说话。

API:后厨的点菜窗口

API 就是后厨对外开的窗口+菜单:规定好"你这样点,我这样回"。例如:

请求:GET /api/orders/SW1003        (给我看订单 SW1003)
响应:{"status": "运输中", "amount": 129}

• GET 是"要数据",POST 是"提交数据"——先知道这两个动词就够
• 响应开头有个状态码:200=成功,404=没找到,500=后厨炸了。排障时天天看它

FDE 的日常:把 AI 系统通过 API 接进客户的老系统——所以这个词后面三周会反复出现。

JSON:双方约定的单据格式

前后端传数据用的通用格式,长这样:

{
  "order_id": "SW1003",
  "status": "运输中",
  "items": ["蓝牙耳机", "充电线"],
  "amount": 129.0
}

读法就三条:{} 包一组"字段: 值";值可以是文字(带引号)、数字(不带)、列表([]);可以层层嵌套。能读懂就行,永远不需要手写——AI 写,你看。

5 分钟跟做:亲眼看一次请求

1. 用 Chrome/Edge 打开预习资料站(或任意网站)
2. 按 F12(Mac: Cmd+Option+I)打开开发者工具,切到 Network(网络) 标签
3. 刷新页面——看,刚才"打开一个网页"这个动作,背后是一串请求逐条飞出去
4. 随便点开一条,看右侧:Status(状态码,多半是 200)、Response(响应内容)
5. 关掉。你已经看过网页的"后厨小票"了,排障就是这么看的

你只需要会这些

到此为止,四个词能对上号就合格:前端(你看到的)/ 后端(服务器上干活的)/ API(它们之间的窗口)/ JSON(窗口里递的单据)。不需要学 HTML/CSS/JavaScript 语法,不需要背 HTTP 协议细节——真要读的每一段,AI 都能给你翻译成白话。

速通 · 数据库:比 Excel 靠谱一万倍的表格

数据库就是一堆"严格的 Excel 表"

你肯定用过 Excel。数据库(MySQL 这类"关系型数据库")可以先理解成:

比 Excel 严格在哪:每列必须声明类型(数字/文字/日期,存错就报错);每行有个身份证号(主键 id),别的表靠它精确指到这一行;能被程序同时、安全地读写成千上万次。

一个订单表长这样:

眼熟吗?一个"查订单"的小功能,真实系统里查的就是这样一张表。

SQL:对表格说的话

SQL 是查/改数据库的语言,一句顶你在 Excel 里点十下:

SELECT * FROM orders WHERE status = '运输中';
-- 从 orders 表里,把 status 是"运输中"的行全拿出来

SELECT product, amount FROM orders WHERE amount > 100;
-- 只要 product 和 amount 两列,条件是金额大于 100

INSERT INTO orders (order_no, product, amount) VALUES ('SW1011', '键盘', 199);
-- 插入一条新记录

读法:SELECT 拿什么列 / FROM 从哪张表 / WHERE 满足什么条件。就这一个骨架。

5 分钟跟做(纸面练习)

不装软件,看着上面那张 orders 表,口头回答:

1. SELECT * FROM orders WHERE amount < 50; 会拿到哪几行?(答:id=2 那行)
2. "把所有已签收的订单的商品名列出来"——SQL 骨架怎么写?(答:SELECT product FROM orders WHERE status = '已签收';)
3. 为什么每行要有 id?(答:两条订单可能商品金额全一样,id 保证能精确指到某一行)

三题都能答上,这篇过关。

你只需要会这些

到此为止。不需要装 MySQL、不需要学 JOIN/索引/事务、不需要会设计表结构——真实项目里库表通常是现成的、SQL 是 AI 写的;你的活是看懂它在查哪张表、什么条件,以及在需求沟通时能问客户一句"这些数据现在存在哪、几张表"。想深了解的以后再说,现在别陷进去。

速通 · 部署:从"我电脑上能跑"到"别人都能用"

一个应用是怎么到你手机上的

你现在正在看的这个预习资料站,链接是 http://203.0.113.10/prep/。拆开看:

• 203.0.113.10 = 一台云服务器的 IP 地址(服务器就是别人机房里 24 小时不关机的电脑,按月租)
• /prep/ = 那台电脑上的一个目录,里面放着这些网页文件
• 你手机输入网址 → 请求飞到那台电脑 → 它把文件发回来 → 手机浏览器画出页面

部署,就是把你电脑上跑通的程序,搬到那台不关机的电脑上跑起来,让所有人随时访问。 没部署之前,你的程序只活在 localhost(本机)——关机就没,别人也够不着。

五个词,凑齐地图

Docker:装箱发货

一个会反复出现的词,先给白话版:程序在你电脑能跑、搬到服务器就报错,多半是环境不一样(差个依赖/版本不对)。Docker 把"程序+它需要的全部环境"打成一个标准集装箱,在哪台机器上开箱都一样跑。企业私有化交付(把 AI 系统装进客户自己的机房)几乎离不开它。

5 分钟跟做(梳理链路)

不动手装任何东西,回答三个问题(答案就在上文):

1. 你在自己电脑上做出来的一个 .html,算部署了吗?(答:没有——它只在你电脑上,发给别人要传文件;放到服务器上才叫部署)
2. localhost:3000 和 203.0.113.10/prep/ 本质区别是什么?(答:前者只有你自己访问得到,后者全网可达)
3. 客户说"这个系统必须装在我们自己机房里,数据不能出去"——这叫什么交付?(答:私有化部署,FDE 的高频场景)

你只需要会这些

到此为止,能看懂"把它部署到服务器的 8080 端口,配个域名上 HTTPS"这句话在说什么,就合格。不需要现在买服务器、学 Linux 运维、背 Docker 命令——真正要推上线时,AI 能一步步带你走完,不必提前背。

AI 认知 · LLM 白话原理:它到底是怎么"想"的

机制一:它在玩超大规模的文字接龙

大语言模型(LLM,ChatGPT/Claude 这类的统称)干的事,本质是预测下一个词:读了海量文本后,它对"什么词后面通常接什么词"有极强的手感,于是一个词一个词地把回答"接龙"出来。

• 它处理文字的单位叫 token(词元),约等于一个词或半个词;API 按 token 计费——算"这个客服系统一个月成本多少"就是在数 token
• 接龙≠检索:它不是在数据库里查答案,而是在生成"看起来最合理的下一句"。这个区别是理解下面两条的钥匙

机制二:上下文窗口 = 它的工作记忆

模型每次能"看在眼里"的内容是有限的(几万到几十万 token),这个范围叫上下文窗口。窗口里有什么,它就基于什么接龙;窗口里没有的,它一概不知道。

三个直接推论,天天用得上:

1. 它不知道你没告诉它的事:你公司的业务规则、昨天开会的决定——不喂给它就等于不存在。"怎么把对的信息喂进窗口"有个专门的名字叫上下文工程,是腾讯 JD 里点名的技能
2. 长对话它会"忘"前面:窗口滚满了,早期内容被挤出去。重要约定别指望它一直记得,该重申就重申
3. 它的知识有截止日期:训练数据停在某个时间点,之后的新闻它靠猜。要新信息就得联网搜或你贴给它

机制三:幻觉——为什么它会一本正经地胡说

模型没有"我不知道"的本能:接龙机制要求它永远接下去,于是知识缺口处它会编一个最像真的——编造的参考文献、不存在的函数、错误的数字,语气还特别自信。这叫幻觉,是机制的副产品,不是 bug,不会被彻底修好。

怎么跟它安全共处?记瑞士奶酪模型:每片奶酪都有洞(每道防线都有漏洞),但多片叠起来,洞就对不齐了。对 AI 的输出:

• 第一片:给足上下文(资料贴给它,让它"有据可接")
• 第二片:让它引用来源("基于我给的文档回答,注明出处")
• 第三片:关键处人工验证(数字、代码、事实——跑一遍、查一遍)

"信任但验证"这句话,就是这三片奶酪的缩写。哪天你逮住一个客服机器人"自作主张处理退款",干的就是这个活。

5 分钟跟做

打开 WorkBuddy(或任意 AI 对话工具),把下面这句发给它:

用 100 字解释你为什么会产生幻觉,并给我一个"我该怎么验证你输出"的建议。

看它的回答和这篇讲的能不能对上——让 AI 解释 AI,这招很常用。

你只需要会这些

三句话能复述就合格:它靠接龙生成,不是查库;窗口里没有的它不知道;它会自信地编,所以关键处必须验证。 Transformer 架构、注意力机制、训练原理——统统不需要,那是造模型的人的事,你是用模型交付价值的人。

AI 认知 · Prompt 基础十条:把话说明白的手艺

十条(前五条管"说清楚",后五条管"管得住")

1. 说目标,别说过程:先讲你最终要什么,而不是一步步指挥它怎么做。 差:"帮我写个循环遍历订单" → 好:"我要统计这批订单里金额大于 100 的有几单,数据长这样:…"

2. 给背景(上下文):它不知道你没说的事。你是谁、给谁用、什么场景、有什么约束,前置交代。 "我给一家连锁电商做客服工具,用户是不懂技术的客服主管…"——一个像样的开场白就是这么写的。

3. 给例子:一个好例子顶三段描述。要什么格式/风格,贴一个样例:"参照这个格式输出:…"

4. 定输出形态:要表格说表格,要 100 字说 100 字,要 JSON 给字段名。不说,它就自由发挥。

5. 划边界(明确不做什么):"先别写代码""不要引入外部依赖""只改这一个文件"。"先别写代码,先给我 PRD"就是这条——边界往往比目标更能防跑偏。

6. 大活拆小步:别一句话要一个完整系统。先要方案,确认了再要实现,再验收再下一步——"PRD → 生成 → 修改"这样的三步走,就是拆步的节奏。

7. 拿不准就让它先复述:"开工前,先用三句话复述你对这个任务的理解,列出你打算怎么做。"理解偏了当场纠正,比返工便宜十倍。

8. 让它自查:"改完列出你改了哪几处""检查一遍有没有漏掉退款场景"。AI 检查 AI,能兜住不少低级错。

9. 加一句"别做多余的事":AI 有热心过头的毛病——你要改一个按钮,它顺手把配色全换了。护栏句:"只做我要求的,别做任何额外改动。"(讲师在国产工具上实测踩过的坑,这句是特效药)

10. 不满意就迭代,别推倒重来:输出不对,指着具体问题让它改("第二段太啰嗦,压到一半"),而不是换个说法从头再问。对话是有上下文的,迭代比重开便宜。

5 分钟跟做

从你工作里挑一个真实小任务(写通知/整理表格/回复邮件),用这个骨架写一条 Prompt 发给 AI:

【背景】我是…,要给…做… 【目标】帮我… 【要求】输出格式为…;不要… 【自查】完成后检查…

对比一下你平时"一句话甩给它"的效果——差距就是这十条的价值。

你只需要会这些

十条不用背,记三个动作:说人话交代清楚(1-4)、划边界拆步子(5-7)、让它自查+别做多余的事(8-10)。市面上的"神级咒语大全""万能模板"不用收藏——那些花活的底层就是这十条。而且用久了会发现:跟 AI 把话说明白的能力,和跟客户把需求聊明白的能力,是同一块肌肉。

选修 · AI 编程范式简史:五年走完的四级台阶

台阶一:补全时代(2021-2022)——AI 是输入法

GitHub Copilot 上线,AI 第一次进了程序员的编辑器:你写一半,它猜下一半,按 Tab 接受。本质是超强代码输入法——快,但主意全是你的,它只负责把你想好的敲得更快。

台阶二:对话时代(2022-2023)——AI 是搜索引擎升级版

ChatGPT 出现,写代码变成"问答":把报错贴进去、让它写个函数、解释一段正则。程序员的日常从"查 Stack Overflow"变成"问 AI"。但代码还是要你自己复制回项目、自己改、自己拼——AI 在项目外面,你在项目里面。

台阶三:结对时代(2023-2025)——AI 进了项目

Cursor、Trae 这类 AI IDE 出现:AI 能看到你整个项目,能直接改多个文件,能跑命令看报错。你说"给列表加个分页",它自己找到该改哪三个文件。这时一个新词开始流行——Vibe Coding:你用自然语言描述意图,AI 负责实现,你负责判断对不对。

台阶四:代理时代(2025-)——AI 成了干活的人

Claude Code 这类 Agentic 工具把台阶再抬高一级:你交代一个目标("按 PRD 实现这个应用"),它自己拆任务、写代码、跑起来、看报错、修复、再验证——一个循环能自主跑几分钟到几十分钟,你在关键节点把关。"交代一个目标,回来验收"——这就是这一级的体感。

这段历史对你意味着什么

1. 人的角色一路上移:从"敲代码的"→"问问题的"→"描述需求的"→"管 AI 干活的"。每上一个台阶,拼的越来越不是手速,是把需求说清楚 + 判断产出对不对的能力——这正是这个岗位最核心的能力
2. JD 已经追认了这件事:字节 FDE 岗硬性要求"熟练掌握 Vibe coding";DeepSeek JD 写"重度使用 Claude Code、Cursor 优先"(2026-03,量子位)。工具使用方式本身成了岗位技能
3. 台阶越高,验证越重要:AI 自主性每升一级,它"自信地做错"的半径也大一级——所以这个系列的下一篇《信任但验证》,是代理时代的安全带

你只需要会这些

记住四个台阶(补全→对话→结对→代理)和一句话:工具每进化一步,人的价值就往"定义问题、验证结果"移一步。 不需要背年份和产品名——每一级自己亲手摸一遍,比记住谁先谁后有用得多。

选修 · 上下文工程入门:AI 做的为什么跟你想的不一样

好需求三标准

教练不会说"开好一点",会说"方向盘左打半圈,速度 30 码"——数字比感受词有效。"现代感"三个字对 AI 没有意义,"渐变背景+圆角按钮+卡片阴影"它就知道怎么做了。

需求不必一次完美:迭代金字塔

• 第一层(开始对话时):说清核心——谁用、干什么、技术栈。三行就够,先让 AI 动起来
• 第二层(动手前):定好边界——做什么、不做什么、MVP 范围
• 第三层(做的时候):补充细节——颜色值、异常处理("加载失败显示重试按钮,不是空白页")

大部分人的问题不是"不会写好需求",而是"以为要一次写完美所以干脆不写"。需求是迭代出来的,不是一次憋出来的。

连第一层都写不出来?反向提问法

让 AI 当产品经理,反过来问你。万能话术:

我想做一个[你的模糊想法],但我还没想清楚具体要什么。
请你像产品经理一样,问我 5-8 个关键问题,帮我梳理清楚需求。
每次只问一个问题,等我回答后再问下一个。

这招在预习第③步"想好你的项目"时就能用——把你行业的模糊想法喂给它,让它帮你把选题问清楚。

上下文的四种失败模式(自查表)

信息量多少算刚好:一个新手项目的说明文档 200-500 字最合适。判断标准——发给一个没参与过项目的同事,他能看懂你要做什么就够,看着累就删。

AI 输出不对时的五步排查口诀

① 技术对不对? → 有没有说技术栈
② 范围对不对? → 有没有画边界
③ 风格对不对? → 有没有说视觉要求
④ 有没有冲突? → 规范和对话有没有矛盾
⑤ 信息过期吗? → 说明文档跟当前代码是否一致

前三步解决 80% 的问题。

别一上来就说"AI 太笨了"——按这五步查,通常前三步就找到原因。

你只需要会这些

三标准(具体/有边界/可验证)+ 迭代金字塔(先三行启动再补)+ 四种失败模式自查。这些东西看懂不难,难在有意识地用。下次让 AI 做事之前,照着这三条把要求写一遍,差别立刻看得出来。

选修 · Agent 是什么:从"会说"到"会做"

一个任务看懂本质分岔

任务:"帮我规划周六的约会,预算 500。"

普通问答 AI:"好的,你们喜欢什么类型的活动?"……一问一答,真正干活的还是你自己。

Agent:

[思考] 拆成三段:下午茶 → 晚餐 → 晚间活动
[行动] 调用搜索工具找安静的咖啡馆 → 拿到 3 家,选评分最高的
[行动] 再搜适合约会的餐厅、再搜有氛围的酒馆
[思考] 合计 480,在预算内 → 输出一张完整行程卡

核心差异:普通 AI 只能"说",Agent 能"做"。 一个能查订单、能转人工的客服机器人,就是最迷你的 Agent 雏形。

定义一句话 + 四大能力

Agent = LLM(大脑)+ 工具(手脚)+ 记忆(笔记本)+ 自主循环(自己决定下一步)

四个缺一不可:没工具=空谈,没 LLM=传统脚本,没记忆=失忆症,没自主循环=遥控玩具。

反思是 Agent 和脚本最大的差异:脚本错了就崩,Agent 错了会自己调整。

最好用的隐喻:Agent 是实习生

会拆任务、记得主管偏好、会用办公软件、做完自己检查——一个好实习生 = 一个好 Agent。你怎么培训实习生,就怎么"培训"Agent:给背景、画范围、定期同步、必要时干预。

关键视角转变:你不是在写 Agent,你是在管 Agent

写代码的 Agent 已经存在了(Claude Code 就是)。你要学的不是"怎么造 Claude Code",是"怎么让它帮你造产品"。类比:不用学开出租车,要学的是告诉司机去哪、走哪条路、什么时候让他做主。

自主级别 L1-L5(不用背,有感觉即可):L1 问答(ChatGPT 网页)→ L2 建议(代码补全)→ L3 半自主(关键节点确认)→ L4 全自主(交代目标看结果,Claude Code)→ L5 多 Agent 协作。

级别不是越高越好——什么时候放手、什么时候干预,有一张黄金清单:

• 🟢 放手:重复性任务 / 有明确规范 / 可回退 / 低风险读操作
• 🔴 干预:碰钱、碰隐私、碰生产数据 / 影响真实用户(发邮件/支付/删数据)/ 不可逆操作

眼熟吗?某演示项目第③步你拦下"机器人自己处理退款",就是在执行这张清单——配得合适是能力,一律放手是不懂管理。字节 JD 里"识别 AI 可介入 vs 人工兜底的边界",说的就是这件事。

你只需要会这些

能给外行讲清三句话:Agent 是能自己拆任务、用工具、会自查的 AI;把它当实习生管;越碰钱和权限越要人把关。 ReAct 循环、多 Agent 编排、MCP 这些工程细节,真动手时再查不迟,现在不用背。

选修 · 信任但验证:AI 写的代码,哪些能直接收,哪些必须查

为什么不能"全都人工看一遍"

有人说:"AI 写的代码我全部人工 review 不就安全了?"——不可能。1,000 行的项目人工审要 4 小时,10 个项目就是 40 小时。人工全量 review 在 AI 时代不可持续,必须分级:越接近"钱、隐私、权限"的代码,越不能盲信 AI。

信任度金字塔:记住 5 / 15 / 40 / 40

本质就一句:80% 的代码(UI+CRUD)不值得花审查时间,把精力全部集中到那 20% 的命脉上。 高信任层不要浪费时间审;中信任层只做边界审查不做安全审查;低信任以上才动真格。

一个中信任 bug 的典型长相(AI 写的分页接口):没限制 pageSize 上限(前端传 10000 数据库卡死)、没处理 page=0 或负数——测边界一打就现形。

交叉审查:写代码的 AI,不能是审代码的 AI

单个 AI 审自己的代码,命中率约 30%——它"觉得自己写的就是对的",看不见自己的盲点。换一个不同的 AI 来审,命中率能到约 75%:训练数据不同、评判标准不同,一个看不见的洞另一个能看见。

三种用法(由轻到重):

1. 写完即审:A 工具写完提交 → 换 B 工具"审一下这个提交有没有安全问题" → 回到 A 修 → 循环
2. 阶段审查:每个里程碑让另一个 AI 全项目扫一遍,输出一份 Markdown 审计报告,逐项修完再复审
3. 交付前审查:上线前深度审 + 快速扫双管齐下,报告合并去重——这份报告本身就是交付物

三个反模式(新手全踩过):

• ❌ 同一个 AI 既写又审(自带偏见)
• ❌ 只审单个文件不审全项目("漏鉴权"这种问题单文件根本看不出来)
• ❌ 审完只留一段对话不留报告(没有 Markdown 报告等于没审——交付不是审查的副产物,是审查的目的)

你只需要会这些

两个数字一句话:5/15/40/40 分级审查;写和审必须是两个 AI;审查的产出是报告不是对话。 OWASP 十大漏洞的具体条目用到时再查,现在不用背。

选修 · Agent PRD 初见:写给 AI 看的项目说明书

包工头的比喻

想象你是包工头,雇了很多工人。每个工人来,你不可能从头解释整个项目——你会给他一份施工说明书:"项目是这样的,统一用这些材料,风格要这样……"

Agent PRD 就是这份说明书,只不过读者是 AI。 它不是写给人看的产品文档,是写给 AI 看的项目约束。Claude Code 的 CLAUDE.md、Trae 的 Rules,本质都是它的载体——AI 每次干活前先读它,你就不用每次重新解释。

一份合格的 Agent PRD 长什么样

# 二手书交易平台 — Agent PRD

## 项目概述
是什么:在线二手书交易平台 MVP;给谁用:大学生卖买闲置教材

## 技术选型(严格遵守)
前端 Vue3 / 后端 Node.js / 数据库 SQLite;不使用 React、Spring Boot

## 界面风格
主色 #1890ff,圆角 8px 统一,卡片式白底轻阴影

## 编码规范
注释用中文;变量驼峰命名;API 走 RESTful

## 已实现功能(勿重复实现)
书籍列表(GET /api/books)、书籍发布(POST /api/books)

## 当前版本范围(MVP)
包含:发布/浏览/搜索/登录;不包含:支付、物流、评价

注意两个容易被忽视的段落:"已实现功能(勿重复实现)"防 AI 把做过的再做一遍;"不包含"防它热心过头把项目做成三个月的工程。

三种最常见的写错

1. 太模糊:"技术选型:随便,什么都行" → AI 每次用不同技术,项目风格分裂
2. 互相矛盾:选型写 Vue3,界面风格又写"用 React 的 Material UI" → AI 不知道听谁的
3. 过期信息:PRD 写"用 user 表",你上周已改名 account 表 → AI 按旧的生成(上下文四种失败模式里的"过期",最隐蔽)

最重要的一条:PRD 是活文档

• 第一天 200 字就够:技术选型 + 风格 + MVP 范围 + 不做什么
• 做了两天 补一段:已实现功能、已有组件(防重复)
• 一周后 再补:API 返回格式约定、数据库表结构

项目每向前走一步,PRD 就该更新一行。 最怕的不是写得不好,而是做了三天还停在第一天的 200 字版本——省的不是写文档的时间,是 AI 重复劳动和你排查的时间。

和 FDE 的关系(为什么预习就讲它)

腾讯 FDE JD 技术栈第一组词是"上下文、RAG、MCP、SDD"——SDD(规范驱动开发)的核心思想就是"规范是新的源代码":把项目约束写成 AI 可执行的规范,是 2026 年 JD 里的正式技能词。实际动手时,给一个项目写的第一份文档往往就是 Agent PRD —— 它会跟着项目一路长大,最后长成交付文档的底稿。

你只需要会这些

记住结构(概述/选型/风格/规范/已实现/范围)+ 三种写错 + "活文档"心法。模板不用背——让 AI 替你生成即可,你的活是看懂它、维护它、别让它过期。

做 Agent 应用,怎么测它的效果

常被问到的一个问题:「做一个 Agent 应用,怎么去测试它的效果,是自己做一个测试集吗?」 一句话先回答:是,要自己做测试集,而且要分两层来测。

一、为什么 Agent 应用不能只用老办法测

传统系统输入一样输出就一样,写断言就行。Agent 应用有一段是模型在判断,同一句话十次里可能有一次判错,你没法用"等于"去测它。所以要分两层:确定的部分用断言,不确定的部分用评分。 两层都要有,少一层都不算测过。

二、第一层:确定的部分,照老办法测

路由规则、工具契约、数据读写、三态、权限,这些是确定的。一个客服 Agent 示例里的自测命令就是这一层:十五条用例,输入「查订单 YX1003」断言状态等于已签收、金额等于 499;输入「我要退款」断言必转人工。

这一层的要求只有一条:断言内容,不只断言有输出。 "返回了一张卡"不算,"卡上金额等于 499"才算。

三、第二层:不确定的部分,用评估集打分

模型参与判断的环节(意图分类、答案生成、检索命中),要准备一组带期望答案的题,行业里叫评估集,也叫 golden set。看这几样:

评估集的题从哪来?三个地方:PRD 的验收标准、真实用户的措辞、上线后答错的记录。不能从代码里抄。 我们 2026-08 实测过一次,AI 自测十条全绿,上线还是漏,原因就是用例是从它自己的规则表里抄关键词,规则表里没有的话它永远测不到。这叫测试和实现同源,等于拿答案当考题。

四、第三层:回归

三件事发生任何一件,评估集全部重跑一遍:换模型或模型升版本、改提示词哪怕一行、知识库加了内容。条数不减、分数不降,才算没改坏。"切回 mock 数据后自测仍然全绿",就是最小的回归。

五、上线以后

每一轮对话记一条追踪:意图、工具、耗时、有没有兜底。定期看兜底率和各类意图的分布,答错的回流进评估集。再加红队测试:越权查单、诱导退款、提示注入。成本和延迟也是指标。

六、一句话版

确定的用断言,不确定的用评分,题不能从代码里抄,改一次跑一遍。

2026-09 我们在自己抓的大厂 JD 里第一次看到「Agent Benchmark」「自动评测」这样的词进了岗位要求,见观察 #005。

一个 AI 需求来了,怎么判它能不能做

做交付的人常遇到这种开头:「我们数据攒了好几年,让 AI 帮我们做点事。」 一句话先回答:先对七类失败模式,再让 AI 列风险、你逐条判真伪,最后把「不做」说成「换个交法」。

一、AI 项目死得多,但多数不是死在模型上

这几年讲 AI 试点失败率高的报告不少,数字各家不一样,这里不引。做过几次就知道,失败的头号原因不是模型不行,是三件事没人说清:该不该做、做什么、怎么算成功。所以接到需求先别谈方案,先判。

二、七类失败模式,拿着对号

拿到任何一个 AI 需求,先过一遍这七问。答不上来的那一类,就是这个项目最先会死的地方。

这张表的用法不是打分,是找出「答不上来」的那一两格。答不上来的,结论只能是「待确认」,这也是一种合格的答案,比硬给一个「能做」强。

三、同一个需求,行业不同,先问的那一问不一样

同样是「上个 AI 客服」,四个行业卡的地方各不相同:制造先看进不进得去,客服要答的数据在哪个系统,给不给接口,产线数据出不出厂区;零售先看用不用得起来,机器人答错一句谁改知识库,多久改一次,这一条问出来多半是没人;金融先看谁签字,AI 答错一句投诉进来谁负责,合规部知不知道这个项目;医疗先看有没有资质,涉及诊疗建议的回答有准入门槛,不是技术做得好就能上。

举一条通用的:「公司文档太乱,做个什么都能答的问答。」先问三问:「什么都能答」里最常被问的 20 个问题能列出来吗,列不出来成功指标就定不出来;同一项制度有几个版本、哪个现行、谁说了算;上线后文档更新了谁负责同步进系统,没有这个人,三个月后它答的就是旧版。三问里有一问答不上来,先别接。

四、让 AI 列风险,真伪要自己判

用 AI 起草风险清单很快,一条提示词几分钟就出 5 到 8 条,每条带类别和「向客户确认的一问」。但它会编。判真伪只用三个动作:①和需求原话对得上吗 ②这一版的范围里会发生吗 ③它有没有替客户编了事实。三个里有一个答「否」,那条划掉或改成「待确认」。

一个零售客户的例子:「会员数据攒了五年,让 AI 帮我们做精准营销。」AI 起草、人工判过之后,表里留下的几条是这样的:

第一条那个「30%-60%」就是 AI 编的行业数,风险本身是真的,数字要划掉。一张表里一条「编的」都没标出来,大概率是没有逐条判过。另外两条针对 AI 产出的自查:它列的风险里有没有这个行业根本不会发生的,有就划掉;它给的建议里有没有「加个 AI 就行」这种没有代价的,有就退回。

五、不做清单:不做什么、为什么、换成什么

判完风险,接着写不做清单,三行写法,每条都要有「换成什么」。还是上面那个零售例子:

不做清单写的是「不做无关功能」这种话,等于没写。判据是砍范围不是砍功能:缩到一个人群、一个部门、一个流程。这个例子最后选的方案是「从多赚改成少浪费」,预算、券种、节奏都不动,只把发券名单换成模型排序后的头部人群,验收看单位券成本的核销额,基线用客户自己过去六个月的数据。前提是券成本算在客户头上,否则退回更保守的那一版。

还有一句话要在动工前落下来:范围怎么换都解决不了「指标没定义」这个根,第一份交付物应该是一页纸的验收指标定义,看哪个数、基线是什么、谁签字、什么算不达标。指标定下来之后怎么测,见怎么测 Agent 应用的效果。

六、不做的时候怎么说

不说「做不了」,说「这样做我交不出你要的结果,换成 X 我能交」。一段话照四个要素说:承认原需求合理的一句 / 「这样做我交不出你要的结果」的原因 / 换成什么我能交 / 请对方拍板的一件事。

对着 IT 负责人,这个零售例子是这样说的:「老系统撑着全部门店,稳定第一,我认同。原路子要打通三套库、让模型直接写回券系统,一旦写错或外泄,责任在您,产出没法回滚。这版不碰写入:模型只离线出名单,导入仍走你们现有流程。请拍板:这版只读数据、不改系统。」里面没有数字承诺,没有「不可能」,给出的是一个对方能签字的范围。对老板和一线的说法结构一样,只是先回应各自最怕的那件事:老板怕拖,IT 怕出事,一线怕丢活。

什么时候说,分三个时机:干系人之间没对齐的,你在下面说服谁都没用,请客户自己先开一次会;数据、集成、采纳这三类风险占多数的,方向对但范围太大,换范围;数据在不在、质量够不够、接口开不开,不进场看一周谁都答不了的,这一周的工作本身就该收费,当 Discovery 收。

反过来卡自己的一条:客户要一个能出报告的 Agent,你按字面做了个工具交差,不判断该不该做、不证明它可靠,那就是把活接坏了。判断该不该做,本来就是这个岗位的一部分。

七、一句话版

先对七类找出答不上来的那一格,AI 列的风险逐条判真伪,不做清单每条都写换成什么,开口说「换成 X 我能交」而不是「做不了」。

Agent 应用上线以后,怎么看得见它在干什么

评估集回答的是「改好了吗」。上线以后问题变了,变成「今天还好吗」。评估集是考试,看板是体检。这篇只讲体检这一半,考试那一半见怎么测效果。

一、先有追踪,每一轮对话记一条

上线以后能看见什么,取决于每一轮对话你记了什么。我们现在的做法是每轮记一条,五列,不多不少:

五列里常被省掉的是后两列,偏偏不能省。一个连锁零售客服 Agent 的示例里出过这样的事:模型请求失败了,页面上显示的却是「意图未识别」,失败被记成了一个正常分类。所以可观测的第一条不是看板,是失败要明确失败,不吞。追踪里没有 provider 和 ok 这两列,先补这两列,再谈别的。

二、从追踪里算五个数

有了追踪,第一版看板就五个数,每个数写清楚怎么算、基线从哪来。多了没人看。

兜底率单说一句,它容易看反。转人工不算失败,不转还答错才算,所以兜底率不是越低越好。它突然高,先看 provider 那列,是不是模型换了,或者请求失败被算成了 unknown;它突然低,抽几条兜底之外的回答,看库外的问题是不是开始答了。示例里那条 30% 的线只是占位,拿到第一周的真实数就换掉。

另一个坑是分母。让 AI 写看板,它爱把兜底率的分母写成「有回复的轮次」,分母错了整页都错,验收时把它写的每一个「怎么算」逐个对一遍。

采纳率(一线真的用了它答案的比例,不是它答了多少)、每轮成本、漂移这几个数也要盯,不过它们要么要接业务侧的数据,要么要定期重跑评估集,第一版看板可以先不放。

三、看板第一行是版本号

看板页顶两行不能少:版本号,当前 provider。我们自己一个工具翻过车:新版发出去,页面能开,功能是旧的,一句报错都没有,用的人只能问一句「我看的是不是新版」。他问出这句,是因为你没给他判断手段。看板同理,别人看见一个数,得先知道这是哪一版、谁跑出来的。

第二条,数要全量算,不看首屏。凡是说「变了」,先确认上次那个基线是不是全量。你说兜底率涨了,先问一句上周的数是全量算的还是前一百条。

四、告警:先跑一周,再定线

这一段我们在自己的工具上做过,在客户的生产环境里没有搭过一整套,说的是行业里的做法和我们的建议。

上线第一天就拍一个兜底率阈值,第一周基线比它高,天天报,一周后没人看,告警从此是噪音。所以先跑一周不设阈值,拿到每个数的日常范围,阈值等于基线加减一个幅度,幅度怎么来的写明白。

告警第一版只留三条:兜底率越线、工具报错次数越线、时延超时次数越线。成本按天看,不告警。告警发给一个人,就是项目里签字兜底的那个人,发给一个群等于没发。渠道先用群消息不用短信,看一周误报多少再收紧。到了客户现场,先问他们现有告警走什么渠道,别另起一套。

五、答错回流,把环闭上

上线以后一定会漂,来源就三个:模型升版或改名,一家厂商把模型名改了,老名字直接调不通,不改一行代码分数从有到无;知识库加了内容,原来命中的条款被新加的条款挤掉;用户措辞变了,开始问上线时没人问过的东西。

三种漂移各有发现手段。第一种看 provider 分布,加上评估集定期重跑;第二种改完知识库全量重跑;第三种看兜底率上升,然后把答错的原句捞出来。

捞出来之后就是回流:兜底率越线的那些轮次,或者客户挑出来的刺,原句进评估集的异常集,期望和客户对好,全量重跑,分数不降才再上线。这个环转起来,评估集就跟着项目长,因为它装的全是真的问过的话。

六、最小可观测清单

照这个顺序做,前一步没有,后一步是空的。

这份清单不需要 Grafana,也不需要新系统。示例项目里它就是同一个页面上加的一页看板,数据源只有那份追踪记录。

七、一句话版

先有追踪再有数,数旁边写怎么算,看板第一行是版本号,阈值跑一周再定,答错的回流评估集。

做 AI 应用,这笔账怎么算

客户第一句问的往往不是「准不准」,是「这东西一个月要花我多少钱」。 一句话先回答:钱 = 调用次数 × token × 单价。前两个数是你自己的,追踪记录里就有;第三个数是厂商的,按当天官方定价代入。三个数都拿得到,这笔账就算得出来。

一、一次调用花什么

一次调用花的是三个数,前两个在模型返回体的 usage 字段里,第三个从追踪记录里数。

一轮的钱 = Σ(每次调用的 输入 token × 输入单价 + 输出 token × 输出单价)。走规则或走 mock 的那一轮,三个数都记 0。

调用次数比 token 更值钱,它决定量级。我们自己一个客服助手示例里,faq 类问题走「意图判定 → 检索后作答 → 裁判打分」三次调用,真模型平均 7.0 秒;unknown 类一跳判掉,一次调用,1.6 秒。耗时表和钱账是同一个形状:多一跳,就多一次调用的 token,时间和钱一起涨。 数调用次数要打开追踪记录数 provider 不是 mock 的有几条,别按设计图数。

二、上线以后,钱花在哪

一张月账表,单价栏空着,公式写在数旁边。

单价栏为什么空着:价目是厂商定的,今天填的数下个月可能就不对,换厂商改一个数整张表跟着动。没填单价的地方显示「待填单价」,不显示 0,0 会被当成免费。

月账之外有两笔容易漏的。一笔是超时和重试:超时了没等到回复,输入 token 已经花了,厂商按它收到的算;自动重试一次就是两次的钱,而重试那一次和正常那一次在账单上长得一模一样。先去追踪里数一天重试了几次,这个数不看,月账能差一倍。

另一笔是机器。要不要买卡,估法是:日均条数 ÷ 营业秒数得到均值每秒请求数,乘 3 到 5 倍当峰值(倍数看行业,写明为什么),再乘每轮耗时(按最慢的那类或你的 P99),就是同时在处理的轮数。算出来很小也要算,数小说明这个项目的钱在 token 不在机器。

三、怎么省

四个办法,按我们建议的顺序。

缓存。 客服场景重复问题多,同问同答就是缓存。精确缓存:同一句原文再问,直接给上次的答案,一次调用都不花。语义缓存:意思相近的问法命中同一个答案,靠向量相似度判「相近」,判错会答错人,而且它本身也要一次小调用。先做精确的,看一周命中率,上不去再考虑语义。

截断。 输入 token 是你自己写出来的,也是你自己能砍的:系统提示词能不能短、知识库每次塞几条、历史带几轮。少塞选段,时延和成本一起降。取舍见 上下文工程。

模型分级。 简单意图(unknown、转人工、短 faq)交给便宜档,复杂的交给贵档。再往前一步是规则先行:规则命中且置信度够(示例里用 ≥ 0.9)直接用规则结果,不调模型,省的是一整次调用。

批处理。 离线打标、评估集重跑这类不着急的任务,攒着走批量接口而不是一条条实时调。厂商对批量有没有折扣、折多少,按当天价目页看。

四个办法有一条共同的规矩:降级必须显式,追踪里每一轮都写「走了谁」,留空的轮次算它没做。

省了没人知道,等于没省。客户问「今天为什么便宜了」,你要能拿「走了谁」那一列给他看,三成走了规则,一条一条能对。

还有一条:省的是钱,不是分。同一张评估集,开省钱模式前后并排跑,掉一分就是掉一分,掉了不许上;是规则抢答答错了,就抬高那类意图的置信度门槛,不是删题。兜底率也要看,规则把该给模型的判成 unknown,兜底率会变差。评估集怎么跑见 怎么测效果。

四、什么时候该说「这个不划算」

ROI 三行,同一张表客户和你各看一半。

第一行明显小于后两行之和,就该直说不划算。这话在方案阶段说,比上线以后再说便宜得多。

自托管还是 API,也是一条式子。API 花的是月 token 量 × 厂商单价,量小、峰值高、还在试的时候便宜;自托管花的是卡 + 人 + 电 + 机房,不用也在花,量大、稳定、数据不能出网的时候便宜。盈亏点是 月 token 量 × 单价 = 卡月成本 + 运维人月 + 电,月账表就是式子左边。

后一半是给自己的。按人天计价的项目,常见的错是只算清了客户省多少,没算清自己该收多少,复盘时才发现两者差着量级。同一张 ROI 表,客户看省了多少,你看该收多少。真按订阅收,还要写得出 SLA 三个数:可用性、响应时延、故障恢复时间,写不出的订阅别签。

五、一句话版

钱 = 调用次数 × token × 单价,单价按当天定价代入不写死;省钱先缓存后截断再分级,每一轮写「走了谁」,掉分不许上;省的、花的、不出事的三行并排,第一行小就直说不划算。

把重复的工作流做成 Skill:一份 2 到 3 小时的动手手册

起因:常有人问「相同的工作流能不能抽成 skill,有没有工业级的做法和资料」。答案是有,而且已经是开放标准。这份手册按一门小课的顺序写,你照着走一遍,大约 2 到 3 小时,结束时手里有一个能跑的 skill。 例子用「需求可行性体检」四步 —— 接到一句需求后先列风险、判真伪、换范围、写话术。如果你手上有自己跑过三遍以上的流程,直接换成你的。 实测声明:第三节十步在 2026-09-09 用 Claude Code 2.1.259 从空目录完整走了一遍,校验命令、手动触发、自动触发、脚本检查均按下文记录的结果执行过;未实测的两项(/skills 交互菜单、skill-creator 插件)在文中标了「未实测」。实测记录见第八节。

〇、读前须知

你需要什么

• 一个支持 Agent Skills 的工具。本手册以 Claude Code 为例,它是目前对这套标准支持最完整的。Codex、Cursor、Copilot 等也支持同一格式,SKILL.md 通用,只是放置路径和部分扩展字段看各家文档。
• 截至本手册核实时,没有看到 WorkBuddy 支持这套 skill 目录格式的说明,以它的官方文档为准。课上用它没问题,做 skill 这件事请用 Claude Code 或其它明确支持开放标准的工具。
• 一个你已经手工跑过至少三遍的流程。没跑过三遍的流程不要抽,理由见第一节。

这份手册怎么用

• 第一节和第二节是原理,20 分钟读完。
• 第三节是动手,十步,每步有检查点,做完一步再往下。
• 第四节是企业级要多做的事,做完第三节再看。

一、先想清楚:什么值得做成 skill

1.1 一句话定义

skill 就是一个文件夹,里面一个 SKILL.md,写清楚「这件事怎么做」。AI 工具启动时只读它的名字和一句描述;你提出的任务和描述对上了,它才把正文读进来照着做。文件夹里还可以放脚本、模板、参考资料,用到哪个读哪个。

它解决的问题只有一个:同一段话你不用每次再说一遍。

1.2 四个判据,满足三个再抽

四条都不满足的,先当提示词用;满足一两条的,写进 CLAUDE.md 或项目规范;满足三条以上,抽成 skill。

1.3 和另外三样东西的分工

记住一条:确定性的事交给脚本,判断性的事留给模型。 一个好 skill 里两者都有,而且分得清。

二、一个 skill 长什么样

2.1 目录

feasibility-check/
├── SKILL.md          必须:元数据 + 步骤
├── scripts/          可选:脚本,模型运行它,只拿输出
├── references/       可选:参考资料,用到才读
└── assets/           可选:模板、样例文件

规则:文件夹名必须和 SKILL.md 里的 name 一致;引用文件用相对路径,只引一层,不要 A 引 B 引 C。

2.2 SKILL.md 的头部(frontmatter)

开放标准定了六个字段,前两个必填:

Claude Code 在这六个之外还认一些自己的字段(第三节第七步会用到两个),那些在别的工具里不生效。

2.3 正文

正文没有格式限制,写 AI 照着做能把事做对的内容。推荐三块:

1. 分步说明
2. 输入和输出的例子
3. 边界情况怎么处理

正文全文在触发时一次性读入,所以控制在 500 行、约 5000 token 以内。长的东西拆到 references/。

2.4 三层加载,这是它省上下文的原因

所以一个 skill 可以带很多资料而不拖慢启动。也所以,description 写不好,后面写得再好也不会被触发。

2.5 在 Claude Code 里放哪

团队共用的,放项目目录。

三、动手:把「可行性体检」做成 skill

目标:做出 feasibility-check,输入一句需求原话,它带你走完可行性体检的四步,并在「人工判真伪」那一步停下来等你。

第 1 步:先把 SOP 手写成一页

打开一个空白文件,按这四栏写,不写 skill,先写人话:

输入:一句需求原话(可带背景一句)
步骤:
  1 列风险清单 5-8 条(风险 / 七类之一 / 要向客户确认的一个问题)+ 不做清单 3-5 条
  2 【人工】逐条判真伪:标出没出处的数字、"大概率/通常/常见"这类替客户编的断言
  3 假设人工判为真的两条成立,给 2-3 个换范围方案
  4 把选定方案写成对老板 / IT / 一线三段话,每段四要素,无"做不了",无数字承诺
输出:风险判据表、不做清单、方案表、三段话
验收:输出里必须有 风险清单 / 不做清单 / 换范围方案 / 三段话术 四样

检查点:这一页你自己照着能手工跑通吗。跑不通,skill 也跑不通。

第 2 步:建目录

mkdir -p .claude/skills/feasibility-check/{scripts,references,assets}

名字用连字符、全小写。不要叫 skill1,不要叫 check,名字要能让三个月后的你一眼知道它干什么。

第 3 步:写 description,这是最重要的一行

三段式:做什么 + 什么时候用 + 关键词。

差的写法:

description: 帮助做可行性判断。

好的写法:

description: 对一条 AI 需求做可行性体检:按七类失败模式列风险清单和不做清单,停下来让人逐条判真伪,再给换范围方案和对客户的三段话术。当用户拿到一条新需求、问"这个能不能做"、要写不做清单、要准备跟客户谈范围时使用。

写完自己问一句:如果我是模型,看到「客户要做个 AI 客服,能不能接」这句话,凭这一行描述会不会想到用它。会,就对了。

第 4 步:写正文

下面是一份完整的 SKILL.md,直接抄,再按你的口径改:

---
name: feasibility-check
description: 对一条 AI 需求做可行性体检:按七类失败模式列风险清单和不做清单,停下来让人逐条判真伪,再给换范围方案和对客户的三段话术。当用户拿到一条新需求、问"这个能不能做"、要写不做清单、要准备跟客户谈范围时使用。
metadata:
  author: your-name
  version: "0.1"
---

# 可行性体检

输入是一句需求原话。四步走,第 2 步必须停下来等人。

## 第 1 步:风险清单 + 不做清单

扮演做过很多 AI 交付的老手,不写方案,只做两件事:
1. 列出这条需求最可能做不成的 5-8 条风险。每条三列:风险是什么 / 属于哪一类 / 需要向客户确认的一个问题。七类见 references/seven-failure-modes.md。
2. 列不做清单:这一版明确不做的 3-5 件事,每件一句为什么。

规则:拿不准的写「待确认」;不许替客户编事实;不许给"加个 AI 就行"这类没有代价的建议。

产出后运行 `scripts/check_step1.py` 检查产物格式,把检查结果一起给用户看。

## 第 2 步:人工判真伪(停下来)

把第 1 步产物里下面三类东西列出来,然后停止,等用户逐条确认:
- 带数字但没有出处的(例:"行业经验值 30%-60%")
- 用"大概率 / 通常 / 常见 / 一般"替客户定的事实
- 客户没说过、AI 替客户补的背景

用户没有确认之前,不进入第 3 步。

## 第 3 步:换范围方案

用户指定第 N 条和第 M 条风险为真后:给 2-3 个换个做法的方案,每个写清:改成做什么 / 砍掉了什么 / 客户仍然拿到的核心价值一句话 / 需要客户拍板的一件事。不写技术方案。

## 第 4 步:三段话术

把用户选定的方案写成三段对客户说的话,每段 80-120 字:对老板(要结果和时间)/ 对 IT 负责人(怕出事、守着老系统)/ 对一线(怕被替代)。每段四要素:承认原需求合理之处一句 / "这样做我交不出你要的结果"的原因一句 / 换成什么我能交 / 请对方拍板的一件事。不出现"做不了""不可能",不承诺任何数字。

## 输出

按 assets/discovery-draft.md 的格式把四样产物写成一份文件,文件名带日期。

## 边界

- 需求原话少于 10 个字:先追问背景,不开工。
- 用户想跳过第 2 步:提醒一次风险,用户坚持则记录"未判真伪"后继续。
- 涉及医疗诊疗、金融投资建议:第 1 步的合规类风险必须列出准入或担责问题。

检查点:正文有没有超过 500 行;每一步有没有写清输入、动作、输出;停下来等人的那一步有没有写死。

第 5 步:把每次都一样的东西拆出去

正文里不该塞长表。两样东西拆出去:

• references/seven-failure-modes.md:七类失败模式表(模式 / 怎么识别 / 先问哪一句),自己整理一份,每行一个模式。
• assets/discovery-draft.md:产物模板,四个标题、表格骨架。

正文里只留一句「七类见 references/seven-failure-modes.md」。模型用到才读,平时不占上下文。

第 6 步:把脆弱的步骤写成脚本

哪一步最容易走样?第 1 步的产物格式。模型有时少一列、有时把类别写成自造的词。这种检查不该靠模型自觉,写成脚本:

#!/usr/bin/env python3
# scripts/check_step1.py  用法: python3 check_step1.py 产物.md
# 检查第 1 步产物:风险 5-8 条、每条有七类之一、每条有待确认问题;并把要人核的数字和断言点出来
import re, sys
text = open(sys.argv[1], encoding="utf-8").read()
kinds = ["数据", "指标", "干系人", "集成", "合规", "采纳", "阶段"]
problems = []

# 只看「风险清单」这一节(到「不做清单」为止),不同模型产物格式不同,标题式和表格式都认
sec = re.split(r"\n#+ .*不做清单", text)[0]
risks = re.findall(r"^### 风险\s*\d+.*$", sec, re.M)            # 标题式:### 风险 1｜标题 `类别`
if not risks:
    risks = [l for l in sec.splitlines() if re.match(r"^\|\s*\d+\s*\|", l)]  # 表格式:| 1 | 风险 | 类别 | 问题 |
if not 5 <= len(risks) <= 8:
    problems.append(f"风险条数 {len(risks)},要求 5-8")

# 每条风险的正文 = 从这条标题到下一条标题
chunks = re.split(r"^### 风险\s*\d+", sec, flags=re.M)[1:] if risks and risks[0].startswith("###") else risks
for head, body in zip(risks, chunks):
    if not any(k in head for k in kinds):
        problems.append("类别不在七类内: " + head[:40])
    if not any(q in body for q in ("?", "？", "确认")):
        problems.append("没有待确认问题: " + head[:40])

# 要人核的:替客户编的断言词、带区间的数字(连字符 / 长横 / 波浪线都算)
for w in ["大概率", "通常", "常见", "一般"]:
    n = text.count(w)
    if n:
        problems.append(f"出现「{w}」{n} 次,可能是替客户编的事实,第 2 步逐条核")
for m in re.finditer(r"\d+%?\s*[-–~]\s*\d+%", text):
    problems.append("出现区间数字,核出处: " + m.group())

print("通过" if not problems else "\n".join("✗ " + p for p in problems))
sys.exit(0 if not problems else 1)

脚本的三条要求:自包含、报错说人话、边界情况不崩。模型运行它,只拿到「通过」或那几行「✗」,脚本代码本身不进上下文。

检查点:拿你第 1 步手写的那份风险清单跑一下脚本,它应该把里面的区间数(如「30%–60%」)和程度词(如「大概率」)都报出来。报不出来,脚本没写对。

顺带说一件真事:这个脚本第一版是按表格写的,对着预跑产物一跑,全报错。因为模型那次把风险写成了八个小标题,不是表;数字里的横线是长横「–」不是「-」。产物长什么样,要看真产物,不能凭想象写脚本。 上面这版已经两种格式都认,这就是第 9 步「测试」存在的理由。

第 7 步:手动触发、参数、副作用控制

在 Claude Code 里,skill 有两种触发方式:模型看描述自动用,或你输入 /feasibility-check 手动用。手动触发时可以带参数:

argument-hint: "[需求原话]"

/feasibility-check 会员数据攒了五年,让 AI 帮我们做精准营销,斜杠后面的话会一起交给模型。实测里正文没写 $ARGUMENTS,模型也把这句话当成了需求原话;如果你想把它固定放在正文某个位置(比如「需求原话:$ARGUMENTS」),再用 $ARGUMENTS 占位。

两个只在 Claude Code 生效的字段,做企业用的 skill 一定要知道:

可行性体检没有副作用,两个都不用加。

第 8 步:校验

三条命令,依次跑:

# 1 按开放标准校验(不用安装,npx 直接跑;实测最严,先跑它)
npx --yes skills-ref validate .claude/skills/feasibility-check

# 2 Claude Code 自带校验(v2.1.233 起)
claude plugin validate .claude/skills

# 3 看 skill 有没有被加载(在 Claude Code 交互界面里输入;未实测)
/skills

实测里的一个坑,一定要记:把 name 故意改成 Feasibility-Check(大写),第 2 条 claude plugin validate 照样报「Validation passed」,它只检查 YAML 能不能解析;第 1 条 skills-ref 当场抓出两条:「name 必须小写」「目录名和 name 不一致」。所以命名规则靠 skills-ref 把关,别信第 2 条的绿。

第 9 步:测试,先改 description

准备 5 条测试需求:四条你见过的真实需求原话,加你自己项目那条。每条做三件事,记在一张表里:

改的顺序:触发不了先改 description;形状不对再改正文;某一步老走样就把那步写成脚本。 一次只改一处,改完五条重跑。这张表就是你的回归测试集,以后每次改 skill 都重跑一遍。

不想在交互界面里一条条试,可以用命令行批量跑(每条约 1 到 2 分钟):

claude -p "客户是一家连锁药店,想做个 AI 客服替一线答会员问题。你帮我判断一下这个能不能接。" \
  --output-format text --max-turns 12 --allowedTools "Read" "Bash(python3 *)" "Write" > run2.txt

这条没有带 /feasibility-check,是在测「模型凭描述会不会自己用它」。

第 10 步:版本与分享

• metadata.version 从 "0.1" 开始,每次改动加一位,并在 SKILL.md 末尾留三行变更记录。
• 提交进项目仓库的 .claude/skills/,团队拉代码就有。
• 想跨项目、跨团队分发,打成插件。

四、企业级要多做的四件事

个人用到第三节就够。给团队、给客户用,再加四件:

1. 来源与审核。 skill 能指挥模型运行代码,一个恶意的 skill 就是一段能执行的攻击。只用自己写的和可信来源的;拿到外来的 skill,先读完所有文件再装,重点看有没有意外的网络访问、文件读写、和描述不符的操作。会联网取内容的 skill 风险最高,取回来的内容可能藏着指令。

2. 权限最小化。 有副作用的 skill 一律 disable-model-invocation: true;allowed-tools 只批必要的;不在 skill 里全局安装软件包。

3. 评估集。 第 9 步那张表就是雏形。企业级要求:每个 skill 有一份固定的测试集,改动前后都跑,记分。Claude Code 官方的 skill-creator 插件可以自动生成评估用例并出对比报告:

/plugin install skill-creator@claude-plugins-official

装完后对它说「evaluate my feasibility-check skill」。(本手册未实测这个插件,用法以官方文档为准。)

4. 分发与治理。 项目级放仓库;组织级通过企业 managed settings 统一下发;定期用 /skill-doctor 看每个 skill 的上下文开销和使用频率,没人用的下线。

五、常见错误清单

1. description 只写「做什么」不写「什么时候用」,结果永远不触发。
2. 文件夹名和 name 不一致。
3. 正文塞进七八张长表,一触发就吃掉几千 token。
4. 该停下来等人的步骤没写死,模型一路跑到底,把编的风险当真的往下用。
5. 格式检查靠模型自觉,不写脚本,十次里有三次少一列。
6. 一个 skill 干五件不相干的事,描述写不清,触发全靠运气。
7. 没有测试集,改一处坏三处不知道。
8. 有副作用的 skill 允许模型自动触发。
9. 引用文件套三层,模型读到第二层就迷路。
10. 把别人的 skill 直接装进带生产权限的环境。

六、实测记录(2026-09-09,Claude Code 2.1.259)

两次真跑里模型都在第 2 步停下来了,这是正文里那句「用户没有确认之前,不进入第 3 步」在起作用。没写死这句的版本我没测,别省。

七、资料清单(全部核实过,2026-09-09)