vibe-coding

Vibe 编码方法论

使用 AI 编码助手高效构建软件的实用策略。

工具格局变化很快。 本技能最近一次梳理是在 2026-05-08。方法论（规划、版本控制、测试、修复 Bug）较为稳定；具体工具名称、指令文件惯例和定价详情每个季度都会变化。请将所列工具视为代表性示例，而非完整清单。

规划流程

先与 AI 合作，在 Markdown 文件中编写详细的实施计划。

范围管理：审查并完善计划，删除不必要的项目，将复杂功能标记为“不做”，并单独保留一个部分，记录以后要实现的想法。这样可以防止范围蔓延，保持专注。

渐进式实施：按章节逐步推进，不要一次性构建所有内容。成功实现后，让 AI 将相应章节标记为已完成；开始下一章之前，先将每个可用章节提交到 Git。

明确跟踪进度：使用待办列表、Markdown 检查清单或行内状态标记，让你和 AI 都能看到已完成和待处理的事项。这样可以避免重复实现已完成的工作，并让会话保持专注。

版本控制策略

Git 是你的安全网，不要只依赖 AI 工具的还原功能。

每次尝试都创建分支：每项新功能都从一个全新的功能分支开始（git switch -c feature/xyz），并在 AI 推进过程中分批提交小块代码。分支边界就是你的“如果事情失控，就把它丢掉”边界：丢弃分支，而不是工作树。

AI 走上错误路线时：优先使用可撤销的命令。git restore . 会丢弃未提交的更改；git stash 会暂存这些更改；git switch - 会跳回上一个分支。只有确认工作树中没有值得保留的内容时，才使用 git reset --hard HEAD；破坏性命令无法享受 reflog 的便利，还可能吞掉未提交的实验性内容。（如果 Agent 创建了新文件，git clean -fd 也属于“真的全部丢掉”操作，注意事项相同。）

干净地重新实现：经过多次尝试后终于找到可行方案时，从 main 创建分支，重新实现该方案，然后丢弃临时分支。AI 多次失败的尝试会留下层层死代码，使后续工作越来越混乱；与其梳理这些杂乱代码，不如干净地重新实现已验证可行的方案，这样更快，也更易维护。

测试框架

优先编写端到端集成测试，而非单元测试。重点模拟用户行为，通过模拟用户在网站或应用中点击操作来测试功能。

防止回归：大模型经常会对无关逻辑进行不必要的更改。测试可以在这些问题不断累积前捕获回归。

将测试作为护栏：可以先编写测试用例，为 AI 明确规定哪些内容可以更改、哪些不应更改。开始下一项功能前，确保测试通过。

高效修复 Bug

错误消息：通常只需复制粘贴错误消息，就能为 AI 提供足够的上下文来识别并修复问题。

先分析，再编码：让 AI 在着手实现前考虑多种可能原因。这样可以避免追查错误的问题。

失败后重置：每次修复尝试失败后，都从干净状态重新开始，不要在有问题的代码上层层叠加修复。

有策略地记录日志：添加日志语句，以便更好地了解难以判断的 Bug 发生了什么。

切换模型：当一个 AI 模型卡在某个问题上时，试试其他模型。

AI 工具格局（截至 2026-05）

当前工具可分为四种形态。根据你的工作场景来选择，而不是跟风。

形态	示例	适用场景
CLI Agent	Claude Code、Aider、Codex CLI、Gemini CLI、GitHub Copilot CLI、opencode、Goose	全仓库修改、多文件重构、自动化、无头模式 / 定时任务
独立 IDE	Cursor、Windsurf、Zed、Kiro	日常编辑，聊天和自动补全紧密集成
IDE 扩展	GitHub Copilot、Continue、Cline、Roo Code、Amazon Q	继续使用现有编辑器（VS Code、JetBrains、Neovim）
云端 Agent	Devin、OpenHands、Jules、GitHub Copilot Coding Agent	通过 PR 异步 / 后台处理任务，无需本地终端

许多开发者逐渐采用的一种常见工具组合是：日常编辑使用 Cursor 或 Copilot + 全仓库 / Agent 式任务使用 Claude Code（或 Codex CLI）。两者相辅相成：在 IDE 中快速进行行内编辑，在终端中运行更长的 Agent 式工作流。

AI 工具优化

指令文件：为 AI 助手编写针对项目的上下文说明。约定虽各不相同，但有几种工具都采用 AGENTS.md 作为通用格式。截至 2026-05，各工具的文件命名如下：

工具	文件	备注
Claude Code	CLAUDE.md（按目录放置，可嵌套）	自动加载；参见 docs.anthropic.com/en/docs/claude-code/memory
Cursor	.cursor/rules/*.mdc（较新的格式），Markdown + YAML frontmatter（description、globs、alwaysApply）	旧版单文件 .cursorrules 仍可使用，但 Cursor 建议迁移
Windsurf	.windsurfrules 或 .windsurf/rules/*.md	与 Cursor 相同的双格式模式
GitHub Copilot	.github/copilot-instructions.md	单个仓库级文件，实际限制约为 4k 个字符
Cline	.clinerules	单个文件
Aider	.aider.conf.yml（配置）+ 聊天历史文件	原生支持 Git；如果指向 CONVENTIONS.md，就会读取它
Continue	.continue/config.json	JSON 配置；按仓库设置
Codex CLI / Gemini CLI / Aider / Continue	AGENTS.md（供应商中立的后备方案）	正逐渐成为跨工具通用标准

使用多个工具时，请将规范说明集中保存在 AGENTS.md 中，并在特定工具的文件中引用它（CLAUDE.md："Also read AGENTS.md."）。这样可以避免同类文件之间出现偏差。

本地文档：将 API 文档下载到项目文件夹中。与回忆训练数据相比，AI 工具依据本地文档工作会更准确；对于发布破坏性变更的速度快于训练数据截止时间的库尤其如此（例如 Sentry SDK、Google GenAI SDK、Selenium）。

运行多个工具：使用 Cursor 进行行内编辑的同时，在另一个终端中运行 Claude Code 或 Codex CLI 会话来处理另一项任务，并不会带来额外损失。不同的工作适合不同的工具形态。

比较输出：对于影响重大的决策，使用来自两家不同供应商的模型生成方案，并根据同一组要求进行比较。不同的模型系列会犯不同的错误。

复杂功能开发

独立原型：先在干净的代码库中构建复杂功能，确认可用后再集成。这样可以隔离问题，让调试更容易。

参考实现：让 AI 遵循可正常工作的示例。现有代码模式能提供具体指导。

清晰的边界：在允许内部改动的同时，保持一致的外部 API。与单体仓库相比，边界清晰的基于服务的架构更适合 AI 辅助开发。

技术栈考量

成熟的框架：Ruby on Rails 等成熟框架因其训练数据中 20 多年来一贯的惯例而表现出色。

训练数据很重要：Rust 或 Elixir 等较新的语言可能训练数据较少，导致出现更多错误或过时模式。

模块化：小型、模块化的文件更便于人类和 AI 使用。避免使用数千行的文件，因为它们会超出上下文窗口并造成混乱。

编码之外

AI 助手不仅能帮助编写代码，还能处理更多任务：

• DevOps：配置服务器、DNS 和托管服务
• 设计：生成 favicon 和其他设计元素
• 文档：起草文档和营销材料
• 教育：逐行讲解实现
• 视觉输入：分享截图，展示 UI 问题或设计灵感。大多数现代助手（通过粘贴使用的 Claude Code、Cursor、Copilot Chat）都能直接接收图像输入。
• 语音输入：基于 Whisper 的转录工具（Whispr Flow、Superwhisper、MacWhisper、Aqua）使用当前的 OpenAI / Whisper.cpp 模型，每分钟可处理 130-180 个单词。适用于长篇提示词和橡皮鸭式思考。

持续改进

定期重构：测试到位后，应频繁重构。请 AI 找出适合重构的部分。

紧跟进展：尝试每个新发布的模型。不同模型擅长不同任务，试验并找出最适合你用例的模型。

参考文件

在进行复杂度检查或重大分支变更前，请阅读 Complexity and readability。

当变更影响已存储状态、信任边界、错误恢复或已报告的 Bug 时，请阅读 Invariants and proportional care。