Ai Era Tutorial

---
name: ai-era-tutorial
description: 编写或改写 AI 时代的编程/全栈入门教程、带新人教材时使用。触发场景：设计入门教程或教程结构、重写旧教程、讨论"读者跳过基础""AI 依赖""新人带不动""教程颗粒度"等问题。Use when writing or restructuring beginner/full-stack tutorials for the AI era, where readers execute steps via AI agents and tend to skip fundamentals.
---

# 前提：读者的执行模式已经变了

读者的默认执行方式不是"照着敲"，而是**人指挥 agent**：教程被当成索引，agent 被当成手脚，读者负责指挥和核对输出。所有规则由这个前提推出。

# 结构规则

1. **靶子先行**：目标、积木清单、预期结果放教程最前面，然后才是步骤。三者的区分见"三层内容"。
2. **步骤写"目标 + 验收产物"，不写键位**。不写"点哪里、敲哪条命令"（agent 自己会），写清这一步产出什么、读者亲自核对什么。
3. **每一步先分类**，判据一句话：这一步的过程里有没有学习价值。
   - **代理区**（无学习价值）：不给过程，只给预期结果与验收标准，明示"交给你的 agent 完成"。例：下载、安装、脚手架。
   - **价值区**（有学习价值）：教程写清过程，就地露出积木或认知基础，配验收。例：环境与依赖如何咬合、组件如何拼接。

# 三层内容

## 靶子

放教程最前面的三样东西，各是各的：

- **目标**：读者要做成什么事——一项任务或能力，如"为一个 Web 服务做限流"。
- **预期结果**：做成之后可观察、可核对的样子。目标说"做什么"，预期结果说"做成长什么样"；要细到读者拿它对照 agent 的输出能发现偏差。
- **积木清单**：完成这个目标实际要用到的零件，从预期结果倒推列出，只列用到的。说"零件"不说"知识"——"知识"会和认知基础混在一起。

## 积木（生产中用来拼接的组件）

写作配方：

1. **从靶子倒推清单，不从知识体系顺推**：问"这个结果由哪几个零件拼成"，只列这几个。
2. **每块积木三句话**：它是什么；它和靶子的关系（为什么这个方案需要它）；它的家族（同类还有谁 + "何时用它、何时用别的"的一个判断特征）。
3. **教一块，带一族**：末句把当前积木推广到同类，共性可推。
4. **指派学习**：要读者掌握某个通性时，教材不写讲解过程，明示读者带着任务去自己的 agent 那里学习、实践。教材只写三样：
   - **位置**：这块积木在整个知识体系中的哪一部分、旁边是什么——给它坐标，不笼统说"值得学"。
   - **预期**：读者实践完，拿回来的结果应该长什么样。写成可核对的样子，读者用它检验 agent 给的东西。
   - **场景**：两三个练习场景，让读者自己带着场景再回到 agent 去做。

   位置给坐标，预期当尺子，场景管巩固。三者缺一，指派就退化成"AI 说啥信啥"。

## 认知基础（库、运行环境）

- 认知基础不是积木，是脚下的地；没有它，积木全学完也是纸上谈兵。
- **必须露出**：平台会替读者屏蔽（自动建 env、自动装库），教程不能。第一次用到时就地露出：它是什么、为什么存在。不做前置"背景知识"章节。
- **验收必须在真机**：认知基础是纸面与真实的分界线。"在你的机器上真的跑起来"不可代劳——用 agent 代装可以，跑必须真跑。

# 脱靶提醒

不是人为挖坑，是提前备注：

1. 教程指派读者去做一件事（学一块积木、交给 agent 一个任务）时，提前考虑这一步的脱靶可能性。
2. 把提醒**备注在指派文字的后面**，写两样：这里可能怎么脱靶；脱靶时是什么样子——读者撞上时能认出"我缺的是哪块"。

# 自检清单

- [ ] 靶子三样齐：目标、积木清单、预期结果？预期结果细到能对照出 agent 输出的偏差？
- [ ] 每步有验收产物，无键位级描述？
- [ ] 每步分类过：代理区还是价值区？
- [ ] 积木从靶子倒推、三句话、带一族？
- [ ] 指派学习三样齐：位置、预期、场景？预期可当尺子？
- [ ] 认知基础就地露出 + 真机验收？
- [ ] 每处指派后面有脱靶提醒？
- [ ] 没有写死任何 AI 使用规则？

# 死原则（不要做）

- **不用"能否无 AI 完成"当验收标准**——AI 依赖只会长不会退，逆浪潮的标准很快失效。
- **不写死 AI 使用规则与难度颗粒度**——那是导师面对具体的人的现场手艺，通用教程写死就会把依赖最深的读者挡在门外。

细节、案例与理论依据见 [references/why-and-cases.md](references/why-and-cases.md)。