企业官网建设流程全解析

1. 先搞清楚 Vibe Coding 到底在解决什么问题

Vibe Coding 这个词这两年被聊得很多，但真正落到“从 0 到 1 做一个项目并长期维护”这个场景，很多人其实是懵的。我见过太多人兴冲冲装好工具，敲了半小时提示词，生成了一个能跑的 demo，然后就没有然后了——项目躺在文件夹里吃灰，过两周自己都忘了当时想做什么。问题不在于工具不好用，而在于大多数人把 Vibe Coding 理解成了“让 AI 帮我写代码”，而它真正的价值是“让 AI 帮我维护一个持续演进的工程”。

这两者的差别巨大。前者是一次性的代码生成，后者是一套围绕上下文管理、任务拆解、状态同步和长期可维护性的工作流。你如果只是想让 AI 吐出一段快排或者一个登录页面，那确实不需要什么方法论。但如果你要做一个能活过三个月、半年、甚至更久的项目，那就必须认真对待 Vibe Coding 的工程化问题。

这篇文章面向的是那些想用 Vibe Coding 方式从零启动一个真实项目，并且希望它能长期活下去的人。不管你是独立开发者、小团队的技术负责人，还是想用 AI 辅助自己做一个副业产品的产品经理，这套思路都能直接参考。我会围绕 AGENTS.md、Harness、Codex、Claude Code 这几个核心工具和概念，把从项目初始化到长期维护的完整链路拆开讲清楚。

先说一个我自己的判断：Vibe Coding 的核心不是“写代码快”，而是“上下文不丢”。一个项目能不能长期维护，取决于你和 AI 之间的协作状态能不能被持久化、被复用、被传承。下面所有的工具选型、文件组织、工作流设计，都是围绕这个核心展开的。

2. 工具链选型：Codex、Claude Code 和 Harness 各自扮演什么角色

2.1 为什么不能只靠一个工具打天下

很多人一开始会问：我到底该用 Codex 还是 Claude Code？这个问题本身就问错了。这两个工具在设计哲学上有明显差异，适用的环节也不一样。

Codex 的优势在于它对代码库的理解深度和补全能力。它更像一个“超级 autocomplete”，在你已经明确知道要写什么的时候，它能帮你快速把代码补全、把重复模式批量生成。但它在“理解项目整体意图”和“跨文件重构”方面，相对弱一些。

Claude Code 则更偏向“对话式工程助手”。你可以用自然语言描述一个需求，它会自己去读文件、理解结构、然后给出修改方案。它在处理复杂重构、跨模块改动、以及需要理解业务逻辑的场景下表现更好。但它的响应速度和 token 消耗也更高。

Harness 是这两年被越来越多团队采用的一个概念和工具集。它的核心作用是“把 AI 的能力编排成可重复执行的工作流”。你可以把它理解成一个 CI/CD 系统，只不过流水线里跑的不是编译和测试，而是 AI 驱动的代码生成、审查和验证。Harness 和 Agent 的区别在于：Agent 是一个能自主决策的执行体，而 Harness 是给这些执行体提供运行环境和编排逻辑的框架。简单说，Agent 是演员，Harness 是舞台和导演。

2.2 我的实际组合方案

经过几个项目的折腾，我目前稳定下来的组合是这样的：

• Codex：用于日常的代码补全、单文件内的快速修改、以及生成重复性代码（比如 CRUD、类型定义、测试用例模板）。
• Claude Code：用于跨文件重构、需求理解、架构设计讨论、以及处理那些“我需要它先读懂整个项目再动手”的任务。
• Harness：用于把上面两个工具的能力串起来，形成可重复执行的流程。比如“每次提交前自动跑一遍代码审查”“每次新增功能时自动生成对应的测试骨架”。

这个组合的好处是，每个工具都在自己最擅长的环节工作，不会互相打架。而且通过 Harness 的编排，整个流程是可追溯、可复现的，不会出现“上次 AI 帮我改的东西这次它不认识了”这种情况。

2.3 安装和配置的实操要点

关于安装，网上教程很多，我只说几个容易踩坑的地方。

Claude Code 的安装，在 Ubuntu 上直接用 npm 全局安装就行，但要注意 Node 版本不能太低，建议 18 以上。安装完之后第一件事是配置认证，如果你在国内网络环境下遇到连接问题，那是正常的，需要自己想办法解决网络层面的问题，这里不展开。配置好之后，用claude命令进入交互模式，先跑一个claude --version确认安装成功。

Codex 的安装类似，但它的认证方式不太一样。Codex 用的是 auth token 机制，你需要先在官网登录拿到 token，然后在本地配置。如果遇到 “codex auth token is unavailable” 这个报错，八成是 token 过期了或者没配置对。重新登录官网生成一个新的 token，然后更新本地配置就行。

Harness 的安装相对复杂一些，因为它涉及到插件系统。DeepSeek Harness 是目前比较流行的选择，安装完之后需要配置插件加载路径。如果遇到 “harness failed to load plugins” 的错误，先检查插件目录的权限，再确认插件版本和 Harness 核心版本是否匹配。这两个问题占了这类报错的九成以上。

注意：所有工具的安装路径建议统一放在一个固定的目录下，比如~/ai-tools/，这样后面配置 AGENTS.md 的时候引用路径会方便很多，也不容易因为路径变动导致配置失效。

3. AGENTS.md：让 AI 真正理解你的项目

3.1 AGENTS.md 到底是什么

AGENTS.md 是 Vibe Coding 工作流里最容易被忽视、但最重要的一个文件。你可以把它理解成“给 AI 看的 README”。普通的 README 是给人看的，讲的是项目怎么用、怎么装。AGENTS.md 是给 AI 看的，讲的是项目怎么组织、代码风格是什么、有哪些约定、哪些地方不能动。

为什么需要这个文件？因为 AI 没有长期记忆。你这次跟它聊了半天，把项目结构、命名规范、业务逻辑都讲清楚了，下次开一个新会话，它又什么都不记得了。AGENTS.md 就是用来解决这个问题的——把所有需要 AI 知道的上下文固化下来，每次会话开始时自动加载。

我见过很多人抱怨“AI 写的代码风格不一致”“AI 总是改坏我原来的逻辑”，根本原因就是没有 AGENTS.md。AI 不知道你的项目有什么约定，它只能按照自己的默认习惯来，当然会出问题。

3.2 AGENTS.md 应该写什么

一个合格的 AGENTS.md 至少应该包含以下几块内容：

项目概述：用三五句话讲清楚这个项目是做什么的、核心功能是什么、技术栈是什么。不要写太长，AI 不需要知道所有细节，它只需要一个整体框架。

目录结构说明：把主要的目录和文件列出来，说明每个目录放什么类型的代码。比如src/components/放 UI 组件，src/services/放业务逻辑，src/utils/放工具函数。这样 AI 在需要修改某个功能时，能快速定位到正确的文件。

代码风格约定：命名规范（驼峰还是下划线）、缩进（空格还是 tab，几个空格）、注释语言（中文还是英文）、导入顺序等等。这些细节看起来琐碎，但直接影响 AI 生成代码的一致性。

关键约束：哪些文件不能动、哪些依赖不能升级、哪些接口不能改。这些是项目的“红线”，必须明确告诉 AI，否则它可能在重构的时候把你精心设计的架构给拆了。

常用命令：构建、测试、部署的命令。AI 在需要验证自己的修改时会用到这些。

3.3 一个真实的 AGENTS.md 示例

下面是我一个实际项目里的 AGENTS.md 片段，你可以参考这个结构：

# AGENTS.md ## 项目概述 这是一个基于 Next.js 的内容管理后台，核心功能是文章编辑、发布和数据分析。 技术栈：Next.js 14 + TypeScript + Prisma + PostgreSQL。 ## 目录结构 - src/app/：页面路由，使用 App Router - src/components/：可复用 UI 组件 - src/lib/：工具函数和第三方服务封装 - src/services/：业务逻辑层 - prisma/：数据库 schema 和迁移文件 ## 代码风格 - 使用 TypeScript strict 模式 - 组件文件名用 PascalCase，工具函数用 camelCase - 缩进用 2 个空格 - 注释用中文 - 导入顺序：React → 第三方库 → 内部模块 → 类型 ## 关键约束 - 不要修改 prisma/schema.prisma 中的 User 模型 - 不要升级 next 到 15，当前版本有兼容性问题 - API 路由统一放在 src/app/api/ 下，不要新建其他 API 目录 ## 常用命令 - 开发：npm run dev - 构建：npm run build - 测试：npm run test - 数据库迁移：npx prisma migrate dev

这个文件不需要一次写完，可以在项目推进过程中逐步补充。每次你发现 AI 犯了同样的错误，就把对应的约束加进去。这样 AGENTS.md 会越来越完善，AI 的表现也会越来越稳定。

3.4 AGENTS.md 和 context.md 的配合使用

有些团队会把 AGENTS.md 拆成两个文件：AGENTS.md 放长期不变的约定，context.md 放当前迭代的上下文。比如这个 sprint 在做什么功能、有哪些待办、最近改了什么。这样每次开新会话时，AI 先读 AGENTS.md 了解项目全貌，再读 context.md 了解当前进度。

这个拆分的好处是，AGENTS.md 可以保持相对稳定，不需要频繁修改；context.md 则可以随时更新，反映最新的工作状态。我自己的习惯是每天开始工作前花两分钟更新一下 context.md，把昨天做了什么、今天要做什么写清楚。这样 AI 一上来就能进入状态，不用我反复解释。

4. Harness 工程化：把 Vibe Coding 变成可重复的流程

4.1 为什么需要 Harness

如果你只是一个人做一个玩具项目，可能不需要 Harness。但如果你要长期维护一个项目，或者团队里有多个人在用 AI 辅助开发，那 Harness 就是必需品。

原因很简单：没有 Harness 的 Vibe Coding 是不可重复的。每次 AI 生成代码的质量取决于你当时怎么描述需求、上下文给得够不够、模型当时的状态好不好。这种随机性在短期项目里可以接受，但在长期项目里是灾难。你今天让 AI 写了一个模块，明天让 AI 改一个 bug，后天让 AI 加一个功能，三次生成的代码风格可能完全不一样，最后项目变成一锅粥。

Harness 的作用就是把这些随机的、一次性的 AI 交互，变成标准化的、可重复执行的流程。你可以定义“每次新增一个 API 接口时，必须经过以下步骤：生成路由文件 → 生成类型定义 → 生成测试用例 → 运行测试 → 代码审查”。这个流程一旦定义好，每次执行都是同样的步骤，产出质量就稳定了。

4.2 Harness 的核心概念：Skill 和 Pipeline

Harness 里有两个核心概念需要理解：Skill 和 Pipeline。

Skill 是一个封装好的能力单元。比如“生成 React 组件”是一个 Skill，“生成 API 路由”是另一个 Skill，“运行代码审查”又是一个 Skill。每个 Skill 定义了输入是什么、输出是什么、执行逻辑是什么。你可以把 Skill 理解成一个函数，只不过这个函数的实现是 AI 驱动的。

Pipeline 是多个 Skill 的组合。比如“新增功能”这个 Pipeline 可能包含：解析需求 → 生成代码 → 生成测试 → 运行测试 → 审查代码 → 提交。每个步骤都是一个 Skill，串起来就是一个完整的 Pipeline。

这种设计的好处是，你可以把复杂的开发流程拆解成一个个可复用的 Skill，然后根据不同的场景组合成不同的 Pipeline。比如“修 bug”的 Pipeline 和“加功能”的 Pipeline 可能共享“生成测试”和“代码审查”这两个 Skill，但前面的步骤不一样。

4.3 一个实际的 Harness 配置

下面是我一个项目里的 Harness 配置片段，展示了一个“新增 API 接口”的 Pipeline：

name: add-api-endpoint description: 新增一个 API 接口的完整流程 skills: - name: parse-requirement input: 自然语言需求描述 output: 结构化的接口定义（路径、方法、请求体、响应体） - name: generate-route input: 接口定义 output: 路由文件代码 - name: generate-types input: 接口定义 output: TypeScript 类型定义 - name: generate-test input: 路由文件和类型定义 output: 测试用例代码 - name: run-test input: 测试用例代码 output: 测试结果 - name: code-review input: 所有生成的代码 output: 审查意见

这个配置定义好之后，每次需要新增接口，我只需要在 Harness 里触发这个 Pipeline，输入需求描述，剩下的步骤它会自动执行。如果测试不通过或者审查有问题，它会停下来让我处理，处理完继续往下走。

4.4 Harness 和 Agent 的区别再强调一次

很多人会把 Harness 和 Agent 搞混。简单说，Agent 是“能自己做决定的执行者”，Harness 是“规定执行者怎么做事的框架”。Agent 可以很聪明，但它也可能做出你意想不到的决定。Harness 的价值在于给 Agent 划定边界，让它在可控的范围内工作。

在实际项目里，我通常会用 Harness 来定义流程，然后在每个 Skill 内部调用 Agent 来执行具体任务。这样既有 Agent 的灵活性，又有 Harness 的可控性。

提示：Harness 的配置不要一开始就追求大而全。先从最简单的 Pipeline 开始，比如“生成代码 → 运行测试”，跑通了再逐步增加步骤。我见过太多人一上来就设计了一个十几步的复杂流程，结果调试成本太高，最后放弃了。

5. 从 0 到 1 的完整实操流程

5.1 项目初始化阶段

第一步是创建项目骨架。这一步不需要 AI 参与太多，用你熟悉的脚手架工具生成基础结构就行。比如 Next.js 用create-next-app，Python 项目用poetry new或者cookiecutter。

骨架生成之后，立刻做三件事：

第一，初始化 Git 仓库，做第一次提交。这是你的“基线”，后面 AI 改坏了可以随时回滚。

第二，创建 AGENTS.md，把项目概述、目录结构、代码风格约定写进去。这时候不需要写太详细，有个框架就行。

第三，配置 Harness，把最基本的 Pipeline 搭起来。哪怕只有一个“运行测试”的 Skill 也行，先让流程跑通。

这三件事做完，你的项目就有了一个“可维护的底座”。后面所有的 AI 协作都是在这个底座上进行的。

5.2 第一个功能的开发流程

假设你要做的第一个功能是“用户登录”。不要直接跟 AI 说“帮我写一个登录功能”，这样它生成的东西大概率不符合你的预期。

正确的做法是分步骤来：

第一步，需求拆解。你自己先想清楚这个登录功能需要什么：前端表单、后端接口、数据库查询、session 管理、错误处理。把这些拆成具体的任务。

第二步，逐个任务跟 AI 协作。比如先让 AI 生成数据库 schema，你审查确认后再让它生成后端接口，再确认后再生成前端表单。每个步骤都确认后再进行下一步，不要一次性让 AI 生成所有代码。

第三步，每完成一个任务就提交一次。这样如果后面发现问题，可以精确回滚到某个步骤，而不是全部重来。

第四步，更新 context.md。把这次做了什么、遇到什么问题、怎么解决的记录下来。下次开新会话时，AI 读一下就知道进度了。

这个流程看起来比“一句话让 AI 生成所有代码”慢，但实际上快得多。因为一次性生成所有代码，你审查和调试的时间会非常长，而且很容易出现“改了一个地方，另一个地方又坏了”的情况。分步骤来，每一步都是可控的，出了问题也容易定位。

5.3 长期维护的关键习惯

项目上线之后，维护阶段才是真正的考验。我总结了几个必须养成的习惯：

每天更新 context.md。哪怕只写一句话，也要写。这是你和 AI 之间的“交接日志”，断了就很难接上。

每次修改前先让 AI 读 AGENTS.md。不要假设 AI 记得你的项目约定，每次都要让它重新读一遍。Claude Code 支持在会话开始时自动加载指定文件，配置一下就行。

定期回顾和更新 AGENTS.md。项目在演进，约定也在变。每个月花半小时回顾一下 AGENTS.md，把过时的约束删掉，把新的约定加进去。

保持 Harness Pipeline 的更新。随着项目复杂度增加，你的 Pipeline 也需要调整。比如项目早期可能不需要代码审查这一步，但后期就必须加上。

不要跳过测试。AI 生成的代码一定要跑测试。我见过太多人因为“AI 写的应该没问题”而跳过测试，结果上线后出 bug，排查成本远高于写测试的成本。

5.4 一个真实的踩坑记录

说一个我自己的教训。有一次我用 Claude Code 重构一个模块，它建议把两个 service 合并成一个。我觉得有道理就同意了。结果合并之后，另一个模块依赖了原来其中一个 service 的特定方法，合并后方法签名变了，导致那个模块报错。更麻烦的是，那个模块的测试用例没有覆盖到这个方法，所以测试全过了，问题直到上线后才被发现。

这个坑让我意识到两件事：第一，AI 的重构建议不能无脑接受，必须自己审查影响范围；第二，测试覆盖率不够的情况下，AI 的重构风险极高。

后来我在 AGENTS.md 里加了一条约束：“任何涉及跨模块的重构，必须先列出所有受影响的文件和函数，确认后再执行。”这条约束加上之后，类似的问题就没再出现过。

6. 常见问题与排查技巧实录

6.1 工具安装和配置类问题

6.2 AI 生成代码质量问题

问题一：生成的代码风格不一致。这是最常见的问题，根本原因是 AGENTS.md 没写好或者没被加载。解决方法是把代码风格约定写详细，并且在每次会话开始时确认 AI 已经读取了 AGENTS.md。

问题二：AI 改坏了原有逻辑。这通常是因为 AI 没有理解修改的影响范围。解决方法是在 AGENTS.md 里明确标注哪些是核心逻辑不能动，同时在让 AI 修改前，先让它列出受影响的文件清单。

问题三：AI 生成的代码能跑但性能差。AI 倾向于生成“能工作”的代码，而不是“最优”的代码。解决方法是在 AGENTS.md 里加上性能约束，比如“数据库查询必须使用索引”“避免在循环里做 IO 操作”等。

问题四：AI 反复犯同样的错误。这说明你的约束没有生效。检查 AGENTS.md 里是否明确写了这条约束，以及 AI 是否真的读取了这个文件。有时候需要把约束写得更具体，比如不要写“注意性能”，而要写“列表查询必须分页，每页不超过 50 条”。

6.3 长期维护中的典型困境

困境一：上下文丢失。项目做了几个月，AI 越来越“不懂”你的项目了。这是因为 AGENTS.md 和 context.md 没有持续更新。解决方法是养成每天更新 context.md 的习惯，并且定期回顾 AGENTS.md。

困境二：技术债累积。AI 生成的代码往往偏向“快速实现”，时间长了技术债会越来越多。解决方法是在 Harness Pipeline 里加入定期的代码审查和重构步骤，不要等到问题爆发才处理。

困境三：团队协作混乱。多个人用 AI 辅助开发同一个项目，各自的 AGENTS.md 和 context.md 不一致。解决方法是把这两个文件纳入版本控制，所有人共用同一份，修改需要走 review 流程。

困境四：工具链升级导致流程断裂。AI 工具更新很快，升级后原来的配置可能失效。解决方法是在升级前先在一个分支上测试，确认所有 Pipeline 都能跑通后再合并到主分支。

6.4 几个我踩过的坑和对应的技巧

坑一：过度依赖 AI 的架构建议。AI 给的架构方案往往很“标准”，但不一定适合你的项目。我的经验是，架构决策必须自己拍板，AI 的建议只作为参考。

坑二：AGENTS.md 写得太长。一开始我觉得写得越详细越好，结果 AGENTS.md 写了三千多字，AI 每次加载都要消耗大量 token，而且很多内容它根本用不上。后来我精简到一千字以内，只保留最关键的约定，效果反而更好。

坑三：Harness Pipeline 设计得太复杂。前面提过，一开始就设计复杂流程会导致调试成本过高。我的建议是从最简单的 Pipeline 开始，跑通了再逐步增加步骤。

坑四：忽视测试。这个坑我踩过不止一次。AI 生成的代码看起来没问题，但边界情况往往处理不好。后来我强制要求每个功能必须有测试，而且测试用例也要让 AI 生成，但必须自己审查一遍。

坑五：没有版本控制意识。AI 改代码很快，如果没有 Git 做版本控制，改坏了很难回滚。我的习惯是每完成一个小任务就提交一次，commit message 写清楚这次做了什么。这样即使 AI 改坏了，也能精确回滚到上一个好的状态。

6.5 一个实用的排查清单

当你遇到 AI 协作问题时，按这个清单逐项检查：

1. AGENTS.md 是否存在且内容完整？
2. 当前会话是否加载了 AGENTS.md？
3. context.md 是否反映了最新的项目状态？
4. 需求描述是否足够具体？
5. 是否分步骤进行，而不是一次性让 AI 做太多？
6. 是否在修改前让 AI 列出了影响范围？
7. 测试是否覆盖了修改的部分？
8. 是否有 Git 提交作为回滚点？

这个清单看起来简单，但能解决八成以上的常见问题。我自己的经验是，大部分“AI 不好用”的情况，其实是使用方法有问题，而不是工具本身的问题。

7. 一些关于长期维护的个人体会

项目能不能长期维护，工具只占三成，习惯占七成。我见过用着最先进的工具但项目一团糟的，也见过工具很朴素但项目维护得很好的。差别就在于有没有形成稳定的工作流。

Vibe Coding 的工作流核心就三件事：上下文管理、任务拆解、状态同步。AGENTS.md 解决上下文管理，Harness 解决任务拆解，context.md 解决状态同步。这三件事做好了，项目就能长期活下去。

另外说一个我自己的小技巧：每周花半小时做一次“项目健康检查”。检查内容包括：AGENTS.md 是否需要更新、context.md 是否完整、Harness Pipeline 是否还能跑通、测试覆盖率是否达标、有没有累积的技术债需要处理。这半小时的投入，能帮你避免后面几十小时的救火时间。

最后再分享一个心得：不要追求“全自动”。Vibe Coding 不是让 AI 替你做完所有事，而是让 AI 帮你做那些重复的、机械的、不需要创造力的部分，你把精力放在架构设计、需求判断和质量把关上。这个分工搞清楚了，效率和质量的平衡点自然就找到了。