AI 工作流模式
本文档面向两类读者：零基础学生（刚接触编程或 AI 工具）和有经验的开发者。 第一部分帮你建立正确认知，第二部分讲通用工作流模式，第三部分是 Presto 项目的具体实践。 可以按需跳读。
第一部分：AI 辅助开发是什么
AI 编程助手：你的编程搭档
AI 编程助手不是一个"自动写代码的机器"，更像是一个随时在线的编程搭档。
想象你在写一篇论文：你有一个很懂行的朋友坐在旁边，你可以随时问他"这段怎么组织比较好""帮我查一下这个语法"。 他会给你建议，但最终决定权在你手上——你要判断建议是否合理，要不要采纳。AI 编程助手就是这样的角色。
目前主流的 AI 编程助手包括：
- Claude Code：Anthropic 的命令行 AI 工具，Presto 项目的主力工具
- OpenCode：开源的终端 AI 编程助手，兼容多种模型
- Cursor、Windsurf：集成在编辑器中的 AI 助手
本文的模式和原则适用于所有 AI 编程工具，具体操作以 Claude Code 为主演示。
AI 能做什么、不能做什么
AI 擅长的事：
- 根据描述生成代码框架和实现
- 解释现有代码的逻辑
- 发现常见的 bug 和安全问题
- 重构代码、改善命名和结构
- 编写测试用例和文档
- 在你不熟悉的技术栈中快速上手
AI 不擅长的事：
- 理解你的业务需求（它只能根据你的描述推测）
- 保证代码 100% 正确（它会自信地写出有 bug 的代码）
- 做架构决策（它缺乏项目全局视角，除非你提供足够的上下文）
- 处理最新的库和 API（训练数据有截止日期）
- 替代你的判断力（它是工具，不是决策者）
AI 会犯错——这是正常的
这是使用 AI 编程助手最重要的认知：AI 会犯错，而且经常犯错。
常见的错误类型：
| 错误类型 | 表现 | 例子 |
|---|---|---|
| 幻觉 | 编造不存在的 API 或参数 | 建议使用某个库的 v3 方法，但该库只到 v2 |
| 过时信息 | 使用旧版本的语法或做法 | 用 React class 组件而非 hooks |
| 想当然 | 假设你的环境和"常见情况"一致 | 假设你用 amd64 架构，实际你是 arm64 |
| 过度自信 | 对不确定的事给出确定的回答 | "这段代码没有问题"（实际有边界情况未处理） |
正确的心态是：把 AI 的输出当作"初稿"而非"终稿"。 每一段 AI 生成的代码都需要你审查和验证。
第二部分：核心工作流模式
模式 1：上下文工程
零基础解释：AI 不了解你的项目。你需要把"项目规则"写成文件，让 AI 每次对话都自动读取。 这就是上下文工程——给 AI 提供正确的背景信息。
CLAUDE.md 的作用
CLAUDE.md 是放在项目根目录的指令文件。Claude Code 每次启动时会自动读取它， 相当于给 AI 写了一份"新人入职手册"。其他 AI 工具也有类似机制（如 .cursorrules、AGENTS.md），原理相同。
如何组织上下文
好的上下文文件应该包含：
- 项目是什么（一句话描述）
- 技术栈和架构（用了什么语言、框架）
- 代码规范（格式、命名、错误处理方式）
- 硬性约束（安全红线、禁止事项）
- 环境信息（操作系统、架构、包管理器偏好）
真实示例：Presto 的 CLAUDE.md
以下是 Presto 项目实际使用的 CLAUDE.md（节选），展示了上下文文件的典型结构：
# Presto — AI 开发指南
Presto: Markdown → Typst → PDF 文档转换平台（桌面端 Wails + Web 端 Docker）。
## 代码规范
### Go
- gofmt 格式，错误返回 error 不 panic
### 前端 (Svelte 5 + TypeScript)
- Svelte 5 runes ($state, $derived, $effect)
## 安全
代码中 SEC-XX 标注的安全措施不能降级
## 禁止事项
- 不要修改 release.yml
- 不要引入新的第三方 Go 依赖注意几个要点：
- 开头一句话说清项目是什么，AI 立刻有了全局认知
- 代码规范具体到语言级别，不是泛泛的"写好代码"
- 安全和禁止事项用明确的否定句，不留歧义
- 不需要写得很长——精准比详尽更重要
上下文的层级结构
在多仓库项目中，上下文可以分层组织：
| 层级 | 文件 | 作用域 | 内容 |
|---|---|---|---|
| 用户级 | ~/.claude/CLAUDE.md | 所有项目 | 语言偏好、通用习惯 |
| 组织级 | ai-guide.md | 跨仓库共享 | 统一的代码规范、Git 规则 |
| 仓库级 | 项目根 CLAUDE.md | 单个仓库 | 技术栈、安全约束、禁止事项 |
AI 工具会按层级合并这些上下文，仓库级的规则优先级最高。
模式 2：渐进式开发
零基础解释：不要一口气让 AI 把整个功能写完。分步走，每一步确认没问题再继续。
为什么不能一步到位
让 AI 一次性生成大量代码，问题会指数级增长：
- 代码量越大，隐藏的 bug 越多，越难排查
- AI 对后半部分代码的"记忆"不如前半部分准确
- 出了问题你不知道是哪一步引入的
三步走策略
第一步：骨架。 让 AI 生成代码结构和接口定义，不写具体实现。
"帮我设计一个模板管理模块的结构，只要接口定义和文件组织，不要写实现。"第二步：填充。 确认骨架合理后，逐个函数让 AI 实现。
"现在实现 InstallTemplate 函数，需要处理：下载、校验 manifest、注册到本地。"第三步：优化。 功能跑通后，让 AI 帮你改善代码质量。
"审查 InstallTemplate 的错误处理，有没有遗漏的边界情况？"每一步之间，你都要运行代码、跑测试、确认结果。这就是下面要讲的"验证循环"。
模式 3：Prompt 迭代
零基础解释：你对 AI 说的第一句话（prompt）很少是完美的。根据 AI 的回答调整你的提问方式， 就像和人沟通一样——说不清楚就换个方式再说一遍。
迭代的核心思路
- 写一个初始 prompt
- 看 AI 的输出，找到不满意的地方
- 补充信息或调整要求，再来一轮
- 重复直到满意
对话重放示例
以下是一个真实的迭代过程（简化版）：
第 1 轮——初始请求：
"写一个函数，解析模板的 manifest.json。"AI 输出了一个基本的 JSON 解析函数，但缺少错误处理，字段验证也不完整。
第 2 轮——补充约束：
"manifest 的必填字段有 name、version、author、frontmatterSchema。
缺少任何一个都应该返回明确的错误信息，指出是哪个字段缺失。"AI 加上了字段验证，但用了 panic 处理错误。
第 3 轮——纠正做法：
"不要用 panic，用 error 返回。参考项目规范：Go 代码中错误返回 error 不 panic。"这一轮 AI 给出了符合项目规范的实现。
关键观察： 第 3 轮的纠正本可以避免——如果 CLAUDE.md 中已经写了"错误返回 error 不 panic"， AI 第一轮就会遵守。这就是模式 1（上下文工程）和模式 3（prompt 迭代）的配合： 好的上下文减少迭代轮数。
模式 4：验证循环
零基础解释：AI 写完代码后，你必须验证它是否正确。 这不是"不信任 AI"，而是专业开发的基本流程——人写的代码也要测试。
验证循环的四个步骤
AI 生成 → 人类审查 → 测试验证 → 迭代改进
↑ |
└────────────────────────────────────┘- AI 生成： AI 根据你的 prompt 产出代码
- 人类审查： 你阅读代码，检查逻辑是否合理、是否符合项目规范
- 测试验证： 运行代码、跑测试、检查边界情况
- 迭代改进： 发现问题后，回到第 1 步让 AI 修改
如何识别 AI 的常见错误
以下是 Presto 项目中遇到的真实案例：
案例 1：包管理器偏好
AI 建议用 pip install 安装 Python 依赖。但 Presto 项目规定使用 uv（更快、更可靠的 Python 包管理器）。 如果 CLAUDE.md 中写了"Python 用 uv，不用 pip"，AI 就不会犯这个错。
案例 2：架构假设
AI 生成的 Dockerfile 使用 amd64 基础镜像。但开发机器是 Apple Silicon（arm64）。 这类错误很隐蔽——代码语法完全正确，但在你的机器上跑不起来。
案例 3：信息来源
AI 从训练数据中的旧文档复制了一段配置，但项目代码已经更新了接口。 正确做法是让 AI 直接读取当前代码文件（用 @file 引用），而不是凭"记忆"回答。
验证清单：
- [ ] 代码能编译/运行吗？
- [ ] 测试通过了吗？
- [ ] 用的是项目指定的工具和规范吗？
- [ ] 有没有硬编码的环境假设（架构、路径、操作系统）？
- [ ] AI 引用的 API 和方法确实存在吗？
第三部分：Presto 项目的 AI 最佳实践
这一部分面向参与 Presto 开发的贡献者，介绍项目中已经验证有效的 AI 协作方式。
CLAUDE.md 和 CONVENTIONS.md 的分工
Presto 项目用两个文件管理 AI 上下文，各有侧重：
| 文件 | 定位 | 内容 | 谁读 |
|---|---|---|---|
| CLAUDE.md | 仓库级约束 | 代码规范、安全红线、禁止事项 | AI 自动加载 |
| CONVENTIONS.md | 领域知识 | 模板协议、开发流程、Typst 参考 | 开发者按需引用 |
为什么要分开？因为 AI 的上下文窗口有限。CLAUDE.md 保持精简，只放"每次对话都必须知道"的规则； CONVENTIONS.md 放详细的领域知识，开发者在需要时用 @CONVENTIONS.md 手动引入。
组织级 ai-guide.md 的作用
Presto-io 是一个多仓库组织（Presto 主应用、模板仓库、文档仓库等）。跨仓库共享的规则集中在 Presto-homepage/docs/ai-guide.md，包括：
- 统一的 Git commit 规范
- 跨仓库的代码风格约定
- AI 工具的通用配置建议
各仓库的 CLAUDE.md 通过引用指向这个集中文件，避免规则分散和不一致。
模板开发的 AI 工作流
开发 Presto 模板时，推荐以下四步法（来自 CONVENTIONS.md）：
第一步：分析参考文件
把目标文档（PDF 或 DOCX）提供给 AI，让它分析排版特征：
"分析这份简历 PDF 的排版：页边距、字体大小、标题层级、间距、分栏方式。"AI 会提取出可量化的排版参数，作为模板开发的依据。
第二步：交互确认
AI 的分析结果需要开发者确认和补充：
- 哪些排版特征是固定的，哪些应该做成可配置项（放进 frontmatter）？
- Markdown 语法如何映射到排版元素（比如
> 引用映射到"摘要框"还是"侧边注释"）？ - 有没有 AI 遗漏的细节（如页眉页脚、水印）？
第三步：生成代码
确认需求后，让 AI 生成模板代码。注意分步进行（模式 2）：
- 先生成 manifest.json 和基本结构
- 再实现核心转换逻辑（Markdown → Typst）
- 最后处理边界情况和错误处理
第四步：测试预览
用模板的 --example 输出作为测试输入，运行转换，检查 PDF 输出是否符合预期。 这一步必须人工目视检查——AI 无法判断排版效果是否"好看"。
用 @file 引用代码给 AI
在与 AI 对话时，用 @ 引用项目文件可以让 AI 直接读取当前代码，而不是凭训练数据"猜测"：
"@internal/template/install.go 这个函数的错误处理有没有遗漏？""参考 @manifest.json 的 schema 定义，帮我写 frontmatter 验证逻辑。"这比复制粘贴代码片段更可靠——AI 能看到完整的文件上下文，包括 import、类型定义和相邻函数。
不同工具的引用语法略有差异（Claude Code 用 @file，Cursor 用 @ 或拖拽文件）， 但原则相同：让 AI 从代码中获取信息，而非从记忆中检索。
写在最后
AI 编程助手是强大的工具，但它的价值取决于使用者的判断力。
四个模式的核心思想可以浓缩为一句话：给 AI 足够的上下文，分步推进，持续验证。
随着 AI 工具的快速迭代，具体的操作步骤会变，但这些模式背后的原则不会变—— 它们本质上是良好的工程实践，只是在 AI 时代有了新的表现形式。
本文中涉及 AI 工具的具体操作步骤基于 2026 年 2 月的版本，工具更新后请以官方文档为准。