这套教程能到 2 万 Star，说实话我一开始真没料到。更没料到的是，AI 助手豆包会在一次“怎么入门 AI 编程”的相关推荐里带上它，那几天仓库访问量直接翻了将近十倍，评论区涌进来一大批第一次用 AI 写代码的人。很多人私信问我是不是运气好——运气确实占一部分，但如果只靠运气，页面上的 Star 早就掉下去了。今天这篇东西，我想把我做这套 AI 编程教程的完整思路、核心内容设计、实战流程和踩坑经历摊开讲一遍。它不只是教你“怎么写出几段好用的提示词”，而是告诉你怎样把 AI 当成一个靠谱的结对程序员来用，又怎么避免被它一本正经地带偏。适合两类人：一类是想用 AI 提升开发效率、但不太清楚边界在哪的工程师；另一类是打算自己做 AI 编程内容、想让作品被更多人看到的作者。
1. 从一个想法到 2 万 Star：这套 AI 编程教程到底在讲什么
1.1 我为什么会写这套教程
早几年我开始用 AI 辅助写代码的时候，最大的感受不是“震撼”，而是“别扭”。你让它写个函数，它给你吐一大段看起来很完整的代码，贴到编辑器里一跑，报错信息比代码还长。大多数人那时候把 AI 当成搜索引擎的升级版，丢一句“帮我写个爬虫”就等着收货，结果拿到的代码要么依赖了不存在的库，要么逻辑根本对不上需求。
市面上的内容也分成两个极端。一种是工具说明书，把某个模型或者某个插件的接口挨个介绍一遍，看完你还是不知道怎么用它做完一个真实项目；另一种是特别虚的理念文章，讲“AI 会取代程序员”“人机协同是未来”，听起来有道理，但回到工位上你还是不知道怎么问第一句。
我想写的是一套“实战流”的教程，核心就一句话：把 AI 当成一个经验不错但偶尔会胡说的结对程序员来管理。你不可能外包一个程序员之后什么都不管，你至少要给他讲清楚需求、审他的方案、检查他交出来的代码、让他按你的规范修改。把这些环节固化成方法，就是这套教程的内容。所以标题里没有用“速成”“精通”这类词，我的定位很清楚：这是一套能跟着一步步做下来的操作手册。
1.2 教程内容地图
整套教程不是按工具分类的，而是按“你实际写一个项目时遇到的问题”分类。我列了一张表：
| 模块 | 要解决的核心问题 | 适合基础 |
|---|---|---|
| 提示词工程基础 | 让 AI 的输出稳定可控，不再“凭感觉” | 零基础也能看 |
| 工具链与本地工作流 | 把 AI 接进编辑器、终端和版本管理 | 会基本命令行操作 |
| AI 辅助调试与验证 | 让 AI 帮你找 bug，同时别信它的一面之词 | 有一点编程经验更佳 |
| 完整项目实战 | 从零交付一个可用的小工具 | 建议有基础语法功底 |
| 团队协作与规范 | 多人一起用 AI 时不乱套 | 中高级开发者 |
这个顺序我调整过很多版。一开始我把工具链放在最前面，结果新手一上来就被各种插件的配置劝退了。后来才意识到，最先要解决的其实是“怎么把需求说清楚”，也就是提示词工程。你会跟 AI 对话之后，才有必要去折腾工具；有了工具之后，才知道调试和验证有多重要；最后再拿一个完整项目把前面所有环节串起来。这个逻辑是层层递进的，跳一步就容易卡住。
2. 核心内容设计：把“AI 编程”讲清楚需要抓住哪些关键点
2.1 提示词不是用来“问”的，而是用来“约束”的
很多教程会把提示词说得特别玄，什么“角色扮演”“思维链”“Few-shot”，听得人一头雾水。我在这套教程里反复强调一个观点：在 AI 编程场景里，提示词的核心不是提问，而是约束。
为什么？因为代码生成跟写作文不一样。写作文跑题了还能圆回来，代码跑偏了直接编译不过，或者编译过了但逻辑是错的。大模型的输出空间很大，你不给它足够强的约束，它就会用最“顺嘴”的方式写代码，而最顺嘴往往意味着用了过时的 API、忽略了边界条件、命名一塌糊涂。
我教程里有一个对比示例，特别能说明问题。先看一个很弱的提示词：
帮我写一个批量重命名文件的 Python 函数。这个提示词不是不能用，但结果通常很随机。模型可能用 os.rename，可能返回 None，可能不处理目录情况，也可能把扩展名逻辑写错。你还要来回修很多轮。
再看我教程里推荐的写法：
你是一名熟悉 Python 的工程师。请实现一个批量文件重命名工具的核心函数。 需求：传入目录路径、旧文件扩展名、新文件扩展名，把目录下所有匹配的普通文件重命名。 约束： 1. 使用 pathlib 处理路径，不要用 os.path 2. 只处理普通文件，跳过子目录和符号链接 3. 重命名前检查目标文件名是否已存在，若存在则跳过并记录下来 4. 返回一个字典，键为原路径，值为新路径 5. 提供完整的函数签名和 docstring前后对比一下，差的不是“问得更详细”，而是加了一堆约束。你指定了技术方案（pathlib），指定了行为边界（跳过子目录和链接），指定了异常处理策略（已存在则跳过），指定了返回值结构。这些约束本身就是你作为一个工程师平时写代码时要做的决策。你把决策做完了，AI 只是帮你执行。
我在教程里给了一个很好记的公式：提示词 = 角色 + 需求 + 约束条件 + 验收标准。你不用面面俱到，但这四样越明确，AI 的输出就越接近能直接用的状态。很多学员第一次按照这个公式改写提示词之后，回来跟我说“原来 AI 不傻，是我没说清楚”——其实也不全是他的问题，模型就是这样，你给它多大的自由度，它就有多大的发挥空间，而发挥空间在代码这件事上通常不是什么好事。
2.2 让 AI 写代码前，先让它写出系统设计思路
这是整套教程里被引用最多的一个技巧，但也是很多新人最不愿意做的一步。大家总觉得，我都用 AI 了，不就是为了省掉设计、直接拿代码吗？恰恰相反。你让 AI 直接写大段代码，是最贵的用法。
原因不难理解。你在和 AI 对话时，上下文是有限窗口，当你让它一口气生成 200 行代码，模型在生成后半段的时候，很可能会忘记前面已经定下的变量名、函数签名和边界约定，结果就是自相矛盾。但是如果你先让它输出一个设计方案，这个方案的文本量小很多，模型有充足空间把逻辑捋顺，而且你可以在动手前发现它理解偏了。
用一个例子来说明。比如我想做一个 CSV 清洗合并工具，我第一轮不会说“写代码”，而是说：
我正在做一个数据分析项目，需要清洗并合并多个 CSV 文件。 请先输出一个设计方案，包含下面几点，不要写代码： 1. 功能模块划分（至少包括文件读取、清洗、合并、输出） 2. 数据流方向：从输入文件到最终结果的每一步 3. 关键算法的选择：比如去重策略、缺失值处理策略 4. 需要处理的边界情况 5. 预计要用到的依赖库及大致版本方案回来之后，我会先看它的模块划分是否合理，清洗规则的顺序对不对。比如它会说“先做缺失值填充，再做去重”，但你的真实需求可能是“先按时间列去重，再填充数值列”，顺序不同结果完全不一样。这些事在方案阶段改，成本几乎为零；等它把代码写出来了再改，就要连带改好几处。
这个思路其实很像现实里你请一个外包程序员干活。如果你上来就说“给我写个商城系统”，他给你写出来的东西你大概率不敢上线；但如果你先让他出一个技术方案，你审完并确认，再让他按模块实现，最后的结果会靠谱得多。把 AI 当作外包程序员来管理，你会发现它的“能力”瞬间提升一大截。本质上不是模型变强了，而是你的管理方法变好了。
2.3 验证与审查：AI 代码的“质检环节”
AI 生成的代码看起来越像样，越需要认真验证，这是我在教程里给读者打的预防针。很多初学者被 AI 生成代码的“流畅感”迷惑，觉得它逻辑清晰、注释规范，应该没问题。实际上，大模型生成代码时有一个显著特点：它优先保证“语法正确”和“风格自然”，而不是“逻辑正确”。它会在你毫无察觉的地方偷换概念。
我教程里专门有一节讲怎么给 AI 代码做质检，核心是三步：
第一步，让 AI 自己生成一组“最小测试用例”。你问它：“为了验证这个函数，请给出最关键的五个测试用例，包括正常输入和边界输入。”这一步能让 AI 暴露出它对需求的真实理解。如果它给出的测试用例本身就跑偏了，说明它的实现思路大概率也有问题。
第二步，用真实数据或真实环境跑一遍。AI 生成代码时经常假设环境里有某些依赖，但你的环境往往没装。你先在干净的虚拟环境里装上 requirements.txt，然后跑最小用例，这一步能过滤掉大部分低级问题。
第三步，反向追问。把跑出来的报错信息原样贴给 AI，问它“这个错误是什么原因？应该怎么改？”但注意，不要直接让它改完就算。你要追问一句“这个修改会影响其他部分吗？”很多时候 AI 会为修一个错误而弄坏另一个功能。
我见过最典型的案例，是让 AI 写一个日期格式化函数，它正确使用了 strftime，但把表示月份的 %m 和表示分钟的 %M 搞混了。代码不报错，输出也是字符串，但日期完全不对。这类错误靠编译器查不出来，必须靠测试用例和人工审查。所以我常说：AI 写代码是低成本的，审查 AI 代码是需要投入的，你投入的审查时间省不下来。但好消息是，总的成本仍然比你一个人从零写要低得多。
3. 实战流：从零用 AI 做一个可用的小工具
3.1 需求拆解与工程初始化
理论知识讲再多，不如带着做一遍。我教程里最受欢迎的是一个“批量文件重命名工具”的实战项目，因为它足够小，能完整展示流程，又涉及文件操作、错误处理、日志记录这些真实工程问题。
第一步是需求拆解。我不会直接让 AI 写，而是先自己写一句话需求：“做一个命令行工具，输入目录和旧/新扩展名，把目录下所有匹配的普通文件重命名。”然后把它拆成几个问题：输入怎么接收？用命令行参数还是配置文件？文件匹配规则是严格小写还是大小写不敏感？目标文件已存在怎么办？要不要返回操作记录？这些问题拆完之后，再带着它们和 AI 对方案。
第二步是工程初始化。我们用一个虚拟目录来做：
mkdir file-renamer cd file-renamer python -m venv .venv source .venv/bin/activate这里有个非常关键的细节：你得把环境信息告诉 AI。比如你用的是 Python 3.11 和 venv，那就明确写进提示词里。我见过太多人让 AI 生成 requirements.txt，结果 AI 给了个不兼容当前 Python 版本的依赖，或者推荐了 pipenv 这类根本没用上的工具。AI 不知道你的环境，所以环境信息就是你给它的约束条件之一。
初始化做完之后，再让 AI 生成目录结构。一个小工具不需要太复杂，一般就是：
file-renamer/ ├── renamer.py ├── requirements.txt └── README.md你甚至可以把这个目录结构交给 AI 去细化，让它建议还需要加什么测试文件。我会提醒读者，千万不要在这一步就让 AI 把所有文件内容一次性写出来，因为一次生成多个文件的代码，跨文件的函数调用非常容易对不上。分文件、分轮次生成才是稳妥的。
3.2 核心功能实现：分步让 AI 产出代码
到了实现阶段，我的习惯是分三轮对话来推进，绝不贪多。
第一轮，只生成类或函数的骨架。我会说：
请为批量重命名工具定义 FileRenamer 类，包含 __init__、collect_files、rename_files、summary 四个方法。现在先输出类结构和方法签名，方法体可以写 pass，docstring 要写清楚每个参数的用途。这样做的好处是，我能在写逻辑前先检查接口设计合不合理。比如我发现 collect_files 和 rename_files 之间需要传递一个文件列表，这个列表的结构如果一开始没定好，后面就会乱。骨架阶段改接口，成本极低。
第二轮，实现核心方法。这时候上下文还是干净的，AI 记住类结构不会有压力。提示词可以这样写：
继续实现 rename_files 方法。约束： 1. 使用 pathlib 处理路径 2. 只处理普通文件，跳过子目录和符号链接 3. 目标文件名已存在时，添加前缀 "dup_" 而不是跳过 4. 将重命名前后的 Path 对象对应关系存到 self.records 字典 5. 输出完整方法实现，并补齐必要的辅助方法这轮生成完，代码应该已经可以跑通主流程了。接下来第三轮，才是补边界情况和测试用例。很多新人喜欢第一轮就要求“把所有边界情况都考虑全”，但 AI 在信息不足时会把边界情况处理得特别冗长且不准确。分步做的好处是每一步都可以快速验证，出了问题也容易定位。
我在教程里反复强调，这种“分步对话”本质上是在维护一个稳定的上下文窗口。你每轮只让它做一件事，AI 就不容易在 200 行代码的中途“失忆”。这比你把所有需求一次性倒给它要可靠得多。
3.3 联调与交付：把 AI 代码变成可交付的结果
主流程跑通之后，真正的工程量才开始。我在这套教程里专门加了一个章节，记录一次“真实翻车现场”：AI 生成的代码在小写扩展名时工作正常，但遇到 .JPG 这种大写扩展名就完全没反应。因为 AI 在判断扩展名时用了精确匹配，没有做大小写归一化。
这类问题靠“让 AI 再想想”是修不好的，最有效的办法是把失败样本贴给它，再补约束条件：
当前实现有一个 bug：当文件名扩展名为 .JPG 时，没有被匹配到。 原因应该是判断时做了大小写敏感匹配。请修改 collect_files 方法的匹配逻辑，使其大小写不敏感，并补充一个覆盖该场景的测试用例。注意，我没有直接告诉它“用 lower()”，而是描述了现象和期望，让 AI 自己决定实现方式。这样它给出的修改方案通常会更完整，比如它可能会在读取目录时做归一化，或者在比较时统一小写。无论哪种，只要测试覆盖住就行。
联调之后的交付清单，我整理成了一张 checklist，教程里要求读者一项项勾掉：
- 最小可运行脚本能在干净环境跑通
- 至少覆盖一个边界用例（大写扩展名、空目录、文件名冲突）
- 对照原始需求，逐条确认功能点
- 错误路径验证过（比如传入不存在的目录）
- requirements.txt 锁定了关键依赖版本
- README 里有基本的使用示例
这个清单能帮你省掉很多“回头补锅”的时间。我见过太多人用 AI 生成完代码，本地能跑就着急提交，结果在别人机器上环境一换就崩。交付前的验证做扎实，其实也是 AI 编程工作流里最容易被跳过、最不该被跳过的一环。
4. 常见问题与排查技巧：AI 编程路上的真实坑
4.1 模型幻觉与“一本正经胡说八道”
用 AI 编程遇到的第一个大坑就是模型幻觉。大模型在生成代码时，会为了“看起来正确”而编造一些不存在的东西。最典型的几种表现我整理成了表格：
| 问题类型 | 常见表现 | 排查思路 |
|---|---|---|
| 不存在的库 | AI 推荐了一个名字很合理但实际不存在的第三方库 | 先 pip install 试一下，或者让 AI 先查阅官方文档 |
| 虚构的 API | 调用了某个标准库中并不存在的函数或参数 | 跑一个最小示例代码，直接看解释器报错 |
| 过时的语法 | 使用了旧版本 Python 的写法或已废弃接口 | 在提示词里明确“基于 Python 3.11”，让 AI 按版本输出 |
| 想当然的算法 | 代码逻辑看起来完整，但算法复杂度或行为不符合常识 | 用特定输入跑一遍，比对期望输出 |
我碰到的印象最深的一次，是 AI 给我推荐了一个“专用于批量重命名的库”，我按名字去查，发现这个库根本不存在。它的包名太像真的了，导致我多花了十分钟确认。从那以后，我养成了一个习惯：AI 提到任何我不熟悉的第三方库时，第一件事就是复制库名去官方索引查一下，而不是直接装。让 AI 提供依据，而不是让 AI 说了算，这是第一条原则。
4.2 上下文窗口与“聊着聊着就失忆”
第二个高频问题是长会话里的上下文丢失。你开头跟 AI 约定“用 FastAPI”，聊到第六轮它突然给你生成 Flask 代码；你前面说“变量用 snake_case”，后面它又冒出个 camelCase。
这不是 AI“变笨了”，而是上下文窗口有限，早期信息被慢慢挤出去了。解决思路不是让 AI“记住”，而是你主动提供一份“项目共识”文档。
我教程里给了一个文件模板，叫 AGENTS.md（也可以叫项目约定.md），放在项目根目录：
# 项目约定 - 语言/框架：Python 3.11 + FastAPI - 包管理：pip + venv，禁用 poetry - 代码风格：snake_case，类型注解必须完整 - 数据存储：使用 PostgreSQL，禁止 SQLite - 当前进度：已完成用户模块，正在做权限模块每次开新对话时，第一句话就是“请先阅读项目根目录的 AGENTS.md”，然后开始提问。这个文件相当于给 AI 的“入职手册”，它能显著减少长会话中的跑偏。测试下来，修复上下文失忆最有效的就是这个办法，比任何“记住之前对话”的插件都靠谱。
4.3 版本与依赖地狱
AI 编程的第三个坑是依赖地狱。AI 默认会给你推荐“最新版本”的依赖，但最新版本不等于兼容。尤其是当你项目的其他部分对某个库有固定版本要求时，AI 生成的新增依赖常常会跟老依赖打架。
我遇到过的情况：项目里已经用了某个库的 2.x 版本，AI 新生成代码要求引入同一库的 3.x 版本的新特性，结果一安装，把所有老代码的 API 全弄崩了。排查了很久才发现是依赖冲突。
对策其实很简单：
- 在提示词里明确“请基于项目现有 requirements.txt 版本范围推荐依赖，不要升级主版本”
- 每次安装新依赖后，立刻跑一遍已有测试
- 使用虚拟环境，避免污染全局 Python
这个坑几乎每个人都会踩，我在教程里把它放在“新手必看”的位置，就是因为它的破坏力最强，而且报错信息往往误导性很大——你可能花很久查代码，其实问题在依赖。
4.4 安全问题：别盲目信任 AI 写出的代码
最后这个坑最隐蔽，也最不能跳过。AI 生成代码时不会主动考虑安全性，它只会按照你的需求输出。如果你让它“写一个根据用户输入拼 SQL 的查询函数”，它大概率会直接给你拼字符串，因为你说得不够细，它默认按最简单的方式实现。这就可能引入注入风险。
我教程里有一张“安全自检清单”，专门给 AI 生成的代码用：
- 是否出现了直接拼接 SQL 的行为
- 是否使用了 eval()、exec() 执行字符串
- 文件路径操作是否做了越界检查
- 输出的 HTML 内容是否做了转义
- 是否硬编码了账号密码或密钥
- 上传文件类型和大小是否有校验
你不需要对每一段生成代码都做完整的安全审计，但凡是涉及用户输入、网络请求、文件读写、权限校验的代码，一定要逐条过一遍这张清单。你可以把清单直接粘进提示词里，要求 AI“按安全清单逐条自检并修正”，但依然要人工确认。安全这件事，AI 不能完全替你兜底。
5. 从技术教程到 2 万 Star：做内容的一些经验
5.1 为什么会被豆包推荐
写教程的时候我从来没想过会被豆包推荐，但事后复盘，被推荐也不是完全没规律。AI 助手推荐内容时，通常不是看谁的标题更吸引眼球，而是看这个内容能不能真正解决用户的问题。我的教程能被选进推荐，我自己总结了几个原因：
第一，内容可验证。教程里的每一个提示词示例都可以直接复制去用，每段代码都在真实环境里跑过。AI 产品做推荐时，肯定倾向于选那些“用户照着做就能跑通”的内容，而不是纯讲概念的文章。
第二，关键词匹配度高。教程标题和正文里反复出现“提示词”“代码审查”“AI 编程实战”这些词，当用户问“怎么写提示词”时，助手很容易把这篇内容当作高质量候选。
第三，更新节奏稳定。AI 编程领域变化太快，几个月前的教程可能就过时了。我一直保持每个季度做一轮内容修订，这个习惯让教程里的示例始终跟得上主流模型的能力。对推荐系统来说，一个持续维护的文档，比一篇写完就不管的文章可信度高很多。
被推荐之后 Star 涨得确实很快，但我也观察到一个现象：推荐带来的流量是脉冲式的，热度过去之后，每天自然增长的 Star 才是内容真实价值的反应。所以我的态度是：被推荐是运气，接住运气靠内容。
5.2 维护一个 AI 编程教程的日常
很多人以为教程写完就结束了，其实维护才是大头。我每周大概要花五六个小时处理这块内容，主要做四件事：
第一，看 issue 和评论区。读者在实践中遇到问题会反馈，这是最好的教程改进来源。比如有人告诉我某段提示词在新版模型下结果不稳定，我就会去复现并调整提示词。
第二，做版本修订。AI 模型迭代快，我会给教程里的示例加一个“适用环境”说明，如果某种写法已经被更好的方式取代，就替换掉。
第三，更新行业变化。比如新的工具链、新的工程实践出现时，我会有选择地补充进教程，而不是照单全收。保持“少而准”比“多而全”更能维持教程质量。
第四，回答核心问题。评论区里反复出现的问题，我会整理成 FAQ 加进教程，这能减少大量重复回答，也能让后来者更快找到答案。
维护教程这件事，本质上和维护一个开源项目是一样的。代码会腐化，内容也会过时，没有人维护的教程会慢慢变成“古董”，失去被推荐的价值。
5.3 给想做类似教程的人的建议
最后这部分写给想自己做 AI 编程内容的朋友。我见过程很多不错的教程最后“死掉”，大多不是写不出来，而是不想改。观察下来，有几个建议值得参考。
第一，切入点尽量窄。不要写“AI 编程完全指南”这种包罗万象的题目，而应该写“用 AI 写一个批量处理脚本”“让 AI 帮你重构遗留代码”这种具体场景。窄切口更容易做深，也更容易在搜索和推荐场景里被匹配到。
第二，用真实案例，不要编造示例。真实案例里有各种奇怪的小问题，比如编码、权限、平台差异，这些细节才是有价值的经验。编造的示例往往太干净，读者学完之后遇到真实问题照样不会处理。
第三，把“思路”放在“工具”前面。市面上讲工具的文章太多，今天介绍这个插件，明天安利那个框架，但读者真正缺的是“遇到问题该怎么思考”。我教程里最受欢迎的部分，从来不是工具安装说明，而是那些“为什么这一步要先做方案”“为什么要分轮对话”的思路讲解。
第四，做好反馈闭环。写完教程后一定要关注读者的使用反馈，根据反馈持续修订。一个能根据读者需求演变的内容，比一个固守初稿的内容更有生命力。
我写教程这几年，最大的体会是：AI 编程教程的核心不是教人“更快地要答案”，而是教人“更好地提问题”。前天还有个读者问我，为什么我教程里的提示词看起来不复杂但结果很稳，我说因为复杂的是约束条件，而不是提问的句子。你愿意花多少时间把需求想清楚，AI 就能帮你省下多少时间改代码。
最后再分享一个我自己的小习惯：每次更新教程，我都会在仓库顶部放一个变更记录文件，写清楚这次改了什么、为什么改。很多老关注用户会定期回来刷这个文件，因为它代表教程还有生命力。内容创作和写代码一样，交付不是终点，持续维护才是真正的分水岭。希望这篇东西能帮到你，哪怕只帮你少踩一个坑，也算值了。
