跳转至

Vibe Coding 实战手册

面向已经有编程基础、会用 Linux / 终端 / Git 的开发者。
它不是零基础教程，而是围绕 Claude Code、Codex、OpenCode、MCP、skills 和 Harness Engineering 的本地 Agent 实战手册。

这本手册解决什么问题

你可能已经会用 ChatGPT、Claude、Gemini、Cursor、Trae 或 Windsurf 写一点代码，但一进入真实项目就会遇到这些问题：

  • AI 不知道项目结构，只能靠你复制粘贴。
  • prompt 写得不错，但一改多文件就开始跑偏。
  • 每次都要重复告诉 AI 测试命令、目录约定、代码风格。
  • Web 对话能给建议，但不能自己读 repo、跑测试、看 diff。
  • MCP、skills、AGENTS.md、CLAUDE.md、Trellis、CCG 都听过，但不知道什么时候该用。
  • 长任务做到一半上下文爆了，重新开会话又要从头解释。

这本手册把这些碎片放回一条可执行的主线：

flowchart TD
  A[网页对话] --> B[Prompt Engineering]
  B --> C[Context Engineering]
  C --> D[本地 TUI Agent]
  D --> E[MCP / skills]
  E --> F[Harness Engineering]
  F --> G[可验证、可复用、可恢复的开发系统]

如何阅读这本书

这本手册按递进主线组织，不按工具热度排名。先建立任务和上下文，再进入本地执行；先让单个 Agent 稳定工作，再讨论工具扩展、harness 和长期项目系统。

flowchart LR
  A["0-2<br/>定义任务与上下文"] --> B["3-5<br/>本地执行与工具扩展"]
  B --> C["6<br/>Harness 系统治理"]
  C --> D["7-8<br/>实战路径与最佳实践"]
  D --> E["9<br/>开发系统收束"]

阅读时注意两种关系：

关系 怎么读
递进章节 按编号读，后面的内容建立在前面之上
并列工具 按任务缺口选，不要强行排第一第二

比如 Claude Code / Codex / OpenCode 是并列工具；网页对话 -> Prompt -> Context -> Harness 是能力升级路径；OpenSpec / Superpowers / GSD / OMC / ECC / Trellis 是 Harness 不同层的补位路线。

段落 负责什么 不负责什么
0-2 明确读者位置、网页对话边界，以及 Prompt / Context / Harness 的基本概念 不展开完整 harness 搭建
3-5 让本地 Agent 跑起来，并理解工具选型、MCP、skills 的扩展位置 不把所有工具排成单一榜单
6 设计 harness 层次、框架路线和落地顺序 不替代日常执行清单
7-8 练习路径、执行规则、提示词和 review 标准 不再引入新的架构层
9 把前面的做法收束成项目模板和长期系统 不重讲每个工具的入门细节

总目录

0. 起步与定位

文件 内容
0-start-here/index.md 起步路线和阅读顺序
0-start-here/1-reader-position.md 读者画像和前置能力
0-start-here/2-what-vibe-coding-means.md 本手册里的 Vibe Coding 定义
0-start-here/3-learning-path.md 建议学习路径
0-start-here/4-mental-model-glossary.md 核心术语和心智模型地图

1. 从网页对话进入 Vibe Coding

文件 内容
1-web-chat/index.md 网页对话的边界和交接方式
1-web-chat/1-web-chat-boundary.md 网页 GPT / Claude / Gemini 的边界
1-web-chat/2-gpt-claude-gemini-roles.md 三类网页模型适合什么
1-web-chat/3-turn-chat-into-task.md 把聊天结果变成可执行任务
1-web-chat/4-web-to-local-handoff.md 网页对话到本地 Agent 的交接卡

2. Prompt / Context / Harness 三层工程方法

文件 内容
2-engineering-layers/index.md 三层方法和升级边界
2-engineering-layers/1-prompt-engineering.md Prompt Engineering 的正确用法
2-engineering-layers/2-context-engineering.md Context Engineering：让 AI 知道正确的东西
2-engineering-layers/3-harness-engineering.md Harness Engineering 的概念边界
2-engineering-layers/4-upgrade-signals.md 什么时候从 prompt 升级到 context / harness
2-engineering-layers/5-context-doc-patterns.md 上下文文档的分层与维护模式

3. 本地 Agent：Claude Code / Codex / OpenCode

文件 内容
3-local-agents/index.md 本地 Agent 路线与共通 loop
3-local-agents/1-why-local-agents.md 为什么需要本地 TUI Agent
3-local-agents/2-codex-operating-model.md Codex 的操作模型
3-local-agents/3-claude-code-operating-model.md Claude Code 的操作模型
3-local-agents/4-opencode-operating-model.md OpenCode 的操作模型
3-local-agents/5-common-agent-loop.md 三者共通的 Agent Loop
3-local-agents/6-prompt-templates.md 可直接复用的任务模板
3-local-agents/7-first-session-walkthrough.md 第一次真实任务会话 walkthrough
3-local-agents/8-debugging-and-recovery.md Agent 跑偏、报错、卡住时如何恢复
3-local-agents/9-cli-comparison-and-selection.md CLI Agent 对比与选型

4. 工具选型：本地 TUI Agent 与编辑器 Agent

文件 内容
4-tool-selection/index.md 编辑器 Agent 与 TUI Agent 的选择边界
4-tool-selection/1-editor-vs-tui.md Editor-first 与 TUI-first 的差异
4-tool-selection/2-cursor-trae-windsurf.md Cursor / Trae / Windsurf 什么时候用
4-tool-selection/3-selection-matrix.md 按任务选工具的矩阵
4-tool-selection/4-scenario-playbook.md 按真实场景选择工具

5. MCP 与 skills

文件 内容
5-mcp-skills/index.md MCP 与 skills 的分工
5-mcp-skills/1-mcp-basics.md MCP 入门和安全边界
5-mcp-skills/2-skills-basics.md skills 的定位和写法
5-mcp-skills/3-mcp-plus-skills.md MCP + skills 如何组合
5-mcp-skills/4-minimal-stack.md 最小可用扩展栈
5-mcp-skills/5-skill-authoring-workshop.md 从重复流程提炼一个 skill
5-mcp-skills/6-mcp-selection-catalog.md MCP 类型目录与风险分级
5-mcp-skills/7-skill-catalog-and-sources.md 常见 skills 类型、来源和评估方法

6. Harness Engineering：分层搭建开发系统

文件 内容
6-harness-engineering/index.md Harness 结构、工具路线和落地顺序
6-harness-engineering/1-harness-map.md Harness 全景图
6-harness-engineering/2-agents-md-claude-md.md AGENTS.md / CLAUDE.md 怎么写
6-harness-engineering/3-workflow-tools.md 工作流工具的粗分类
6-harness-engineering/4-multi-agent-workflow.md 多 Agent 与 worktree
6-harness-engineering/5-validation-and-eval.md 验证、评测和质量闸
6-harness-engineering/6-build-minimal-harness.md 为一个项目搭最小 harness
6-harness-engineering/7-long-task-governance.md 长任务治理、恢复和交接
6-harness-engineering/8-harness-frameworks-catalog.md Harness 相关工具和框架怎么选
6-harness-engineering/9-harness-adoption-roadmap.md 从轻量到生产级 harness 的落地路线
6-harness-engineering/10-six-harness-routes.md OpenSpec / Superpowers / GSD / OMC / ECC / Trellis 六条路线
6-harness-engineering/11-harness-composition-patterns.md Harness 组合策略

7. 实战路径

文件 内容
7-practice-paths/index.md 按项目类型练习
7-practice-paths/1-web-project.md Web 项目实战路径
7-practice-paths/2-automation-project.md 自动化脚本实战路径
7-practice-paths/3-workflow-project.md 工作流工具实战路径
7-practice-paths/4-bugfix-refactor.md Bug 修复与重构路径
7-practice-paths/5-30-day-route.md 从上手到独立开发的 30 天路线

8. 最佳实践

文件 内容
8-best-practices/index.md 执行清单、提示词和评审标准
8-best-practices/1-personal-workflow.md 个人工作流
8-best-practices/2-team-workflow.md 团队工作流
8-best-practices/3-checklists.md 检查清单
8-best-practices/4-anti-patterns.md 常见反模式
8-best-practices/5-prompt-library.md 常用提示词库
8-best-practices/6-review-rubric.md Agent 产出的评审标准
8-best-practices/7-comprehensive-playbook.md 综合最佳实践：从想法到交付

9. 可验证、可复用、可恢复的开发系统

文件 内容
9-development-system/index.md 开发系统收束与模板
9-development-system/1-verifiable-system.md 可验证：让完成标准落到证据
9-development-system/2-reusable-system.md 可复用：把经验沉淀成资产
9-development-system/3-recoverable-system.md 可恢复：长任务、跑偏和中断后的回收
9-development-system/4-minimal-template.md 最小项目模板和落地步骤

99. 参考资料

文件 内容
99-references/index.md 公开资料与延伸阅读

开源协议与贡献

这个仓库是文档型项目。除特别说明外，正文、图示、示例和模板按 CC BY 4.0 发布。转载或引用时，请保留标题、仓库链接和许可证说明；第三方项目名称、商标和外部链接仍归各自权利人。

想修内容、补链接或补真实实践，请先看 CONTRIBUTING.md。协作讨论遵守 CODE_OF_CONDUCT.md；敏感信息、危险链接或示例命令风险按 SECURITY.md 处理；普通问题和支持边界见 SUPPORT.md。