AI编程实用分享

1. AI 编程范式演进

AI 编程在过去几年的演进大体经历了三个阶段：提示词工程 → AI-assisted Coding → AI Coding Workflow。每个阶段对应人与 AI 的协作方式不同，能力边界也不同。

┌────────────────────┐   ┌────────────────────┐   ┌────────────────────┐
│  Prompt Engineering │ → │  AI-assisted Coding │ → │  AI Coding Workflow │
│   "AI 写项目"       │   │   "人写，AI 辅助"    │   │  "人设计，AI 执行"   │
└────────────────────┘   └────────────────────┘   └────────────────────┘

1.1 提示词工程（Prompt Engineering）

时间段：早期 AI 编程（GPT-3.5 / 早期 GPT-4 时代）。

协作模式：用户写一段 PRD 或自然语言描述，AI 一次性生成一个项目/文件。AI 本质上是一个 “PRD → Code” 的翻译机。

特点：

• 一次性生成，交互轮次少。
• 极度依赖提示词质量，”写 prompt” 变成一门玄学。
• 输出粒度大：整个项目 / 整个文件。

优点：

• 门槛低，零基础也能”做出东西”。
• 原型阶段极快，适合”把想法变成能跑的 demo”。

缺点：

• 生成过程不可控，黑盒感强。
• 业务细节难以自定义，修改成本高。
• 为了让生成代码能用，PRD 要写得非常复杂——往往比直接写代码还累。
• 代码一致性、工程规范难以保证。

适用场景：

• 快速原型验证（POC、demo）。
• 0→1 的初始骨架搭建，之后再由人接手迭代。

1.2 AI-assisted Coding（AI 辅助编程）

代表产品：GitHub Copilot、Cursor（Tab / Inline Edit 模式）、Tabnine 等。

协作模式：人主导写代码，AI 在关键点辅助。人保留架构与控制权，AI 负责”缩短写代码这一步”。

主要解决的问题：

• 自动补全代码（行、块、函数级）。
• 根据注释生成函数实现。
• 帮写 SQL、正则、单测。
• 辅助 debug、解释陌生代码。
• 快速做局部重构。

特点：

• IDE 深度集成，交互以 “Tab / Cmd+K / Chat” 为主。
• 交互粒度小：一行、一段、一个函数。
• 输出基本可预期，人随时可否决。

优点：

• 提升速度的同时保留”掌控感”。
• 学习曲线平滑，对老工程师友好。
• 风险可控，不容易把项目带偏。

缺点：

• 上限受限于”人一次能想多远”——AI 很少主动跨文件协作。
• 重复劳动仍然存在：同一个意图要在多个文件手动展开。
• 对”任务级”工作（比如”实现一个完整 feature”）帮助有限。

适用场景：

• 日常开发、维护已有项目。
• 中大型代码库中做局部增删改。

1.3 AI Coding Workflow（AI 编程工作流）

代表产品 / 形态：Cursor Agent、Claude Code、Codex CLI、Cline、Aider，以及各类 spec-driven / multi-agent 工作流。

协作模式：人定义”目标与约束”，AI 在一个受控工作流中自主执行多步任务——读代码、改代码、跑测试、看日志、再改，直到满足验收标准。人退到”架构师 / 审阅者”的位置。

特点：

• 任务粒度从”一行代码”升级为”一个 feature / 一个 bug / 一次重构”。
• 强调规划 → 执行 → 验证的闭环，而不是一次性生成。
• 开始引入：规范（spec）、规则（rules）、记忆（memory）、工具（tools）、并行（worktree / 多 agent）。
• 人机协作从”补全”变成”委派”。

优点：

• 吞吐量大幅提升，能处理完整任务而非片段。
• 可重复、可审计：workflow、spec、日志让过程可回放。
• 能真正”解放脑力”——人做决策与评审，不做体力活。

缺点：

• 对人的要求反而更高：需要会写 spec、会定义验收标准、会做 code review。
• 初期搭建成本高（规则、脚本、流程）。
• 一旦失控，AI 可能在错误方向上”努力几十分钟”，需要好的刹车机制。
• 对模型能力、上下文窗口、工具链稳定性都有要求。

适用场景：

• 有一定规模的工程项目。
• 需要并行推进多任务、多分支。
• 有明确验收标准的 feature 开发、重构、bug 修复、迁移类工作。

1.4 三阶段对比速览

维度	Prompt Engineering	AI-assisted Coding	AI Coding Workflow
主导者	AI 主导	人主导	人设计、AI 执行
交互粒度	整个项目	行 / 函数	任务 / feature
上下文	全靠 prompt	IDE 当前文件	整个仓库 + 规则 + 工具
可控性	低	高	中高（需设计）
天花板	原型 / demo	日常开发提速	工程级交付
对人要求	会写 prompt	会写代码	会做架构与评审

---

2. 编程最佳实践

范式不同，实践方式也完全不同。下面分别展开 AI-assisted Coding 与 AI Coding Workflow 两种模式下的最佳实践。

2.1 AI-assisted Coding 最佳实践

核心心态：AI 是副驾驶，你才是司机。目标是在保留掌控感的前提下最大化提速。

2.1.1 写好”局部上下文”

AI 在这个模式下看到的上下文有限，主要靠：

• 当前文件 / 当前函数。
• 少量相邻 tab 打开的文件。
• 你写的注释 / 函数签名。

实践建议：

• 函数签名即提示：先写清晰的函数名、参数类型、返回类型，再让 AI 补全实现。
• 用注释声明意图：在函数上方写 1-2 行意图注释，比如 // 根据 user.role 过滤菜单，未登录返回空数组。
• 示例驱动：先手写 1 个典型用例，AI 会顺着你的风格补剩余的。

2.1.2 善用三种交互模式

• Tab 补全：写代码过程中被动接受，适合样板代码、重复模式。
• Inline Edit（Cmd+K / ⌘K）：选中一段代码让 AI 改，适合局部重构、修 bug、翻译语言/框架。
• Chat / Ask：提问、解释、方案讨论，不直接改代码。

经验法则：

• 能用 Inline 就不用 Chat：Inline 直接作用于代码，反馈最短。
• 能用 Tab 就不用 Inline：Tab 最轻量，中断感最低。
• Chat 留给”想清楚再动手”的场景。

2.1.3 小步提交、可回滚

• 每一次 AI 生成之后，先读再接受。
• 把 AI 的产出当成同事的 PR——不审阅不合并。
• 保持频繁 commit，出问题好回滚。
• 把 “AI 生成” 和 “人工调整” 尽量分成不同 commit，便于回看。

2.1.4 建立个人 Prompt / Snippet 库

对于反复出现的场景（生成单测、转换数据结构、写 migration 等），沉淀成：

• 个人的 prompt 片段（Cursor 的 Rules / Snippets）。
• 项目级的 .cursor/rules/、AGENTS.md。

让 AI 输出”符合你风格”的代码，而不是每次重新调教。

2.1.5 常见陷阱

• 盲目 Tab：连续 Tab 接受几十行，事后发现整段方向错了。
• 让 AI 做架构决策：AI 在局部上下文做全局决策，通常不靠谱。
• 用 AI 写你看不懂的代码：一旦出 bug，你既不懂又没法调。写代码 ≠ 看代码，看不懂的就不要接受。

2.2 AI Coding Workflow 最佳实践

核心心态：你是架构师 / PM，AI 是执行团队。目标是把”任务”安全、稳定地交出去。

2.2.1 明确任务边界与验收标准

Workflow 模式最大的风险是 AI “努力错方向”。动手前务必想清楚：

• Done 的定义：什么条件下认为完成？（通过哪些测试？满足哪些行为？）
• 边界：哪些文件/模块不能动？
• 约束：性能、兼容性、API 不变等硬约束。

落地形式：

• 一段明确的任务描述（包含背景、目标、非目标、验收标准）。
• 或者使用 spec 文件（见 §3.3 OpenSpec）。

2.2.2 Plan → Execute → Verify 的闭环

推荐流程：

1. Plan：让 AI 先产出一份”改动计划”（哪些文件、大致思路、风险点），不写代码。
2. Review Plan：人审阅、修正方向。
3. Execute：AI 按 plan 执行，小步推进。
4. Verify：跑测试、lint、类型检查、手动 smoke test。
5. Iterate：有问题回到步骤 1 或 3。

关键动作：**每一步都要有”可验证的信号”**——编译过、测试过、lint 过、预览截图 OK。让 AI 自己能看到这些信号，它才有能力自我修正。

2.2.3 为项目建立”AI 可读的知识”

一个 AI 友好的仓库应该具备：

• README / AGENTS.md：让 AI 快速理解项目是什么、怎么跑、约定是什么。
• 规则文件（.cursor/rules/、CLAUDE.md 等）：约束代码风格、目录结构、禁止事项。
• 清晰的脚本：npm test、make lint、pnpm typecheck 等一键可跑。
• 稳定的测试：让 AI 能通过”跑测试”判断自己对不对。

一句话：让 AI 看到的项目，和一个新入职工程师看到的项目一样清晰。

2.2.4 控制上下文，避免”上下文投毒”

• 不要把无关的巨型文件/日志塞进上下文。
• 任务越具体，上下文越应聚焦。
• 长会话出现”跑偏”时，果断重开一轮，别硬救。
• 重要决策、背景写成文件沉淀下来，而不是依赖对话记忆。

2.2.5 永远保留”刹车”与可回滚

• 所有 AI 自主执行都在独立分支 / worktree 上进行（见 §3.1）。
• 开启 git 保护：敏感分支禁止直接 push。
• 危险操作（删文件、改 CI、改依赖）要求人工确认。
• 出问题时第一反应是 git reset / checkout，不是和 AI”争辩”。

2.2.6 Review 永远不能省

AI 产出的代码 ≠ 可以合入的代码。Review 清单至少包含：

• 逻辑是否真的满足验收标准（别被”测试通过”骗了）。
• 有没有过度实现 / 写了一堆没用的抽象。
• 有没有偷偷改到不该改的地方。
• 依赖、配置、迁移是否完整。
• 安全 / 性能明显问题。

---

3. 编程技巧

一些在 AI Coding Workflow 下显著提效的具体技巧。

3.1 Worktree 并行

问题：一个仓库一个工作区时，AI 跑一个任务就占用整个目录——不能同时做 A feature 和修 B bug。

解决方案：用 git worktree 为每个任务开一个独立工作目录，一个任务一个 worktree，互不干扰。

git worktree add ../myproj-feat-login    -b feat/login
git worktree add ../myproj-fix-payment   -b fix/payment
git worktree add ../myproj-refactor-api  -b refactor/api

搭配 AI Workflow 的玩法：

• 多窗口并行：开 3 个 Cursor/IDE 窗口，各自跑一个任务。
• 多 agent 并行：每个 worktree 挂一个 agent，同时推进。
• 物理隔离：一个 agent 乱改不影响其他任务。
• Review 友好：每个 worktree 对应一个 PR，天然干净。

清理：

git worktree list
git worktree remove ../myproj-feat-login

经验：

• 命名规范：<repo>-<type>-<slug>，便于识别。
• 共享的脚本、依赖、环境通过根目录或脚本统一管理，避免每个 worktree 重复配置。
• 一台机器开 3-5 个并行任务是比较舒服的上限，再多人脑 review 跟不上。

3.2 多 Agent 模型

单 agent 容易在”写代码 + 评审 + 决策”之间反复横跳，效果打折。进阶做法是按角色拆分 agent，让每个 agent 专注一件事。

常见角色划分：

• Planner / Architect：负责读需求、拆任务、产出 plan，不写代码。
• Coder / Implementer：按 plan 写代码、跑测试，不做架构决策。
• Reviewer / Critic：专门挑毛病——逻辑漏洞、安全问题、过度设计。
• Tester / QA：专门补测试、跑 e2e、回归。
• Doc Writer：负责注释、文档、changelog。

协作模式：

• 串行流水线：Planner → Coder → Reviewer → Tester，上一个的输出是下一个的输入。
• 并行分工：多 Coder 同时做不同子任务（配合 §3.1 worktree）。
• 对抗式：Coder 写，Reviewer 挑，循环到 Reviewer 挑不出问题。

收益：

• 每个 agent 的 prompt / 规则更聚焦，效果更好。
• 避免”自己写自己评”的盲区。
• 人只需要在关键节点介入，而不是每一步都盯着。

注意事项：

• Agent 之间的交接要有结构化的产物（plan 文件、diff、review 报告），不要靠”记忆”。
• 防止 agent 无限循环：设置最大轮次、预算、超时。

3.3 OpenSpec

定位：一种”spec-driven development”工作流——先写规范，再生成实现，规范本身是可版本化的 markdown 文件。

核心思想：

• 把”我们要做什么、怎么验收”写成 spec（markdown + 结构化字段）。
• spec 成为人与 AI 的共同契约，也是项目的长期资产。
• 所有变更先改 spec，再由 AI 根据 spec 改代码。

典型流程：

1. 新建 change：描述一次变更的动机、目标、受影响的 spec。
2. 草拟 / 修订 spec：在 markdown 中细化行为、接口、验收。
3. AI 基于 spec 实施：生成代码、测试。
4. 验证 & 归档：跑测试，确认符合 spec，合入并归档这次 change。

价值：

• 任务描述被结构化，AI 不容易跑偏。
• spec 随代码一起演进，文档不再过时。
• 新人（包括新 agent）看 spec 就能快速理解系统。
• 天然适合多人 / 多 agent 协作——大家基于同一份 spec 工作。

适用场景：

• 中长期维护的项目。
• 团队协作、多 agent 协作。
• 对行为正确性要求高的模块（计费、权限、协议）。

对比传统 PRD：spec 更贴近代码、更结构化、更可执行（能直接喂给 AI）。

3.4 oh-my-codex（OMX）

定位：围绕 Codex CLI / AI 编程场景的工作流插件集 / 扩展框架，把上面提到的很多实践”打包”成可直接调用的 skill 与模式。

常用能力（按场景）：

• $plan：策略性规划，可选深度访谈（Socratic interview），先把需求聊清楚再动手。
• $autopilot：从想法到可运行代码的全自动执行。
• $ralph：自引用循环，反复迭代直到通过架构师验收。
• $ultrawork：高并发并行执行引擎，吞吐优先。
• $team：多 agent 协作编排（基于 tmux），天然配合 §3.2 多 agent 模型。
• $code-review / $security-review：成体系的代码审查与安全审查。
• $wiki / $note：项目知识沉淀，抗 context 压缩。
• $hud / $trace：运行状态可视化与流程追踪。

它解决了什么：

• 把”好 prompt / 好工作流”从一次性经验变成可复用的 skill。
• 让 AI 编程从”一人一招”变成”团队共享的方法论”。
• 提供统一的 cancel / doctor / setup 入口，降低维护成本。

何时该用：

• 你已经习惯用 Cursor / Codex / Claude Code 做 workflow 级开发。
• 想把个人经验沉淀成可重复的流程。
• 需要并行、多 agent、长任务编排等进阶能力。

---

4. 小结

• 范式上：从 Prompt Engineering → AI-assisted → AI Coding Workflow，人的角色从”写 prompt 的人”变成”定义目标与验收的架构师”。
• 实践上：AI-assisted 关注”局部提速、保持掌控”，AI Coding Workflow 关注”任务委派、闭环验证”。
• 技巧上：worktree 并行 + 多 agent 分工 + OpenSpec 结构化 + oh-my-codex 工作流，可以把 AI 编程从”个人技巧”升级为”工程体系”。

一句话收尾：把 AI 当成团队，而不是工具；把自己当成架构师，而不是码农。