企业官网建设流程全解析

1. 为什么 Claude 写代码总在“返工”？需求漂移的真实代价

用 Claude 写代码最让人抓狂的，不是它不会写，而是它写得太“自由”。你明明说的是“给登录接口加个失败次数限制”，它给你顺手重构了整个鉴权模块；你说“把文章列表按时间倒序”，它把分页逻辑也一起改了，还引入了项目里根本没用的状态管理库。几轮对话下来，代码越改越乱，最后只能git checkout .从头再来。

我试过在一个已经跑了两年的老项目里加一个“文章管理”功能，当时只丢给 Claude 一句“做个后台写文章、前台展示的功能”。结果它直接生成了一套带评论、点赞、用户等级的完整博客系统，数据库表结构和现有 ORM 完全对不上，删掉重写花了整整一个下午。问题不在 Claude 的能力，而在于需求没有变成可执行的规范——AI 只能靠猜，猜错就是返工。

这类问题的根源有三个。第一是需求模糊：自然语言本身有歧义，“优化一下”可以指性能、可读性、还是修 bug，Claude 无法像人一样追问确认。第二是上下文丢失：聊天记录驱动的开发，几轮之后早期约定就被挤出上下文窗口，Claude 开始“失忆”，你又得重新解释一遍。第三是缺少可追溯的决策记录：改了什么、为什么改、影响哪些文件，全散落在对话里，团队协作时根本对不上账。

OpenSpec 要解决的就是这三件事。它是一套轻量级的规范驱动工作流，核心思路是“先把要做什么写清楚，再让 AI 动手”。它不替代 Claude Code，而是给 Claude 一份结构化的项目上下文和变更提案，让每次代码生成都有据可依。配合 Claude 使用时，需求漂移会显著减少，因为 Claude 在写第一行代码之前，已经读过project.md里的技术栈约定和proposals里的变更范围。

这一篇会从 OpenSpec 的初始化配置讲起，给出 Claude 对接规范文件的完整参数，再用一个文章管理功能的案例，演示需求变更前后如何验证代码一致性。适合正在用 Claude Code、Cursor、Cline 等工具做开发，但被反复返工困扰的团队和个人。下面先从环境准备和 TaoToken 接入讲起，因为 Claude 的稳定调用是整条链路的前提。

2. Claude 接入前置：用 TaoToken 拿到稳定可用的 API 通道

OpenSpec 本身不需要 API 密钥，它只负责生成规范文档和提案。真正调用 Claude 生成代码的是 Claude Code 这类客户端，所以你需要先给客户端配一个可用的模型通道。这里用 TaoToken 做接入，它的 API 地址是https://taotoken.net/api，兼容 Anthropic 的接口格式，Claude Code、Cline、Codex 都能直接对接。

先拿 Key。打开https://taotoken.net/api-keys（带上下文的 deep link 是https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite），登录后在控制台创建一个新的 API Key，复制出来形如sk-xxxxxxxx。这个 Key 就是后面所有配置里的ANTHROPIC_AUTH_TOKEN或OPENAI_API_KEY，取决于你用的客户端。

拿到 Key 之后，记下三个核心参数，后面配置会反复用到：

如果你用的是 Claude Code，它读取的是环境变量。在~/.claude/settings.json或项目级.claude/settings.json里写入：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxx", "ANTHROPIC_MODEL": "claude-sonnet-4-5-20250929" } }

如果你用的是 Cline 或 Roo Code 这类 VS Code 插件，在设置面板里选 “Anthropic” 作为 Provider，Base URL 填https://taotoken.net/api，API Key 填刚才复制的值，Model ID 填claude-sonnet-4-5-20250929。Codex 用户则编辑~/.codex/auth.json：

{ "OPENAI_API_KEY": "sk-xxxxxxxx", "OPENAI_BASE_URL": "https://taotoken.net/api" }

配置完成后，先用一条最小请求验证通道是否通。在终端里执行：

curl https://taotoken.net/api/v1/messages \ -H "x-api-key: sk-xxxxxxxx" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-4-5-20250929", "max_tokens": 64, "messages": [{"role": "user", "content": "回复 OK 两个字母"}] }'

如果返回的 JSON 里content字段包含OK，说明 Key、Base URL、Model ID 三件套都对。如果返回 401，检查 Key 是否复制完整、有没有多余空格；如果返回local proxy failed或连接超时，检查 Base URL 是否写成了https://taotoken.net/api/（多了尾斜杠有时会 404），以及本机网络是否能正常访问该域名。这一步通了，再往下装 OpenSpec，否则后面 Claude 调不通会误以为是 OpenSpec 的问题。

3. OpenSpec 初始化与 Claude 对接规范文件的完整配置

环境通了之后，装 OpenSpec。前提是本机有 Node.js 18 以上版本，执行node -v确认。然后全局安装：

npm install -g @fission-ai/openspec@latest openspec -v

能打印出版本号就说明装好了。接着进入你的项目根目录，执行初始化：

cd /path/to/your-project openspec init

初始化时会让你选择使用的 AI 工具，选 Claude Code（如果列表里没有就选 Other，后续手动配）。完成后项目根目录会多出一个openspec/文件夹，结构如下：

openspec/ ├── project.md # 项目上下文：技术栈、约定、目录规范 ├── AGENTS.md # AI 助手工作流说明 ├── proposals/ # 变更提案存放处 │ └── (每个变更一个子目录) └── archive/ # 归档的历史提案

project.md是整个工作流的基石，Claude 每次生成代码前都会读它。你需要把项目的真实情况填进去，比如技术栈、包管理器、代码风格、禁止使用的库。一个填好的示例：

# Project Context ## Tech Stack - 后端：Node.js 20 + Express 4 + Prisma ORM - 数据库：PostgreSQL 15 - 前端：原生 EJS 模板 + 少量 Alpine.js - 包管理：pnpm（禁止使用 npm install） ## Conventions - 所有数据库操作必须通过 Prisma Client，禁止裸 SQL - 路由文件放在 src/routes/，控制器放在 src/controllers/ - 新增接口必须写 JSDoc 注释 - 禁止引入 React/Vue 等前端框架 ## Directory Rules - 文章相关代码放在 src/modules/article/ - 公共工具放在 src/utils/

这份文件写清楚之后，Claude 就不会再给你生成 React 组件或者裸 SQL 了。接下来配置 Claude Code 读取 OpenSpec 的规范。在项目根目录创建或编辑CLAUDE.md，加入以下内容，让 Claude 每次会话自动加载规范：

# Claude 工作约定 本项目使用 OpenSpec 规范驱动开发。每次开始任务前，必须： 1. 读取 openspec/project.md，确认技术栈和约定 2. 读取 openspec/AGENTS.md，了解工作流 3. 涉及变更时，先读取 openspec/proposals/ 下对应的提案文档 4. 生成代码必须符合 project.md 中的 Conventions，不得引入未声明的依赖 变更流程： - 新功能：先创建 proposal，再执行 - 修 bug：在提案的 tasks.md 中记录，再修改

AGENTS.md是 OpenSpec 自动生成的，里面定义了提案的生命周期：proposal → review → apply → archive。你不需要改它，但要让 Claude 读它。配置完成后，在 Claude Code 里发一条验证指令：

请读取 openspec/project.md 和 openspec/AGENTS.md，用三句话总结本项目的技术栈和变更流程。

如果 Claude 能准确说出“Node.js + Express + Prisma”“先提案后执行”，说明规范文件已经成功注入上下文。这一步是整个方案的关键，很多人跳过它直接让 Claude 写代码，结果又回到需求漂移的老路。配置对了，后面每次生成都会自动带上项目约束。

4. 实战验证：用提案驱动 Claude 开发文章管理功能

规范配好之后，走一遍完整流程。假设要给现有网站加一个文章管理功能，需求是“后台登录写作，前台按分类展示”。不要直接让 Claude 写代码，而是先创建提案。在 Claude Code 里输入：

我想添加文章管理功能：后台登录后可写文章，前台按分类展示。 请按照 OpenSpec 流程，在 openspec/proposals/ 下创建变更提案。

Claude 会读取project.md和AGENTS.md，然后在openspec/proposals/下生成一个子目录，比如add-article-management/，里面包含三个文件：

openspec/proposals/add-article-management/ ├── proposal.md # 需求描述、影响范围、技术方案 ├── design.md # 数据模型、接口设计 └── tasks.md # 拆解后的开发任务清单

proposal.md会写明这次变更涉及哪些现有文件、新增哪些文件、是否影响首页。design.md会给出 Prisma 的 Article 模型定义和路由设计。tasks.md把开发拆成可勾选的小项，比如“创建 Article 模型”“实现后台登录中间件”“实现前台分类查询接口”。你先审查这三个文件，确认无误后再让 Claude 执行：

提案已确认，请按照 openspec/proposals/add-article-management/tasks.md 逐项实现，每完成一项在 tasks.md 中标记。

Claude 会按任务清单逐条生成代码，并且因为project.md里写了“禁止裸 SQL”“路由放 src/routes/”，它生成的代码会自然落在正确的位置。生成过程中，你可以随时让它停下来解释某一步，或者修改design.md后重新执行。这就是规范驱动的价值：需求变更先改文档，再改代码，代码和文档始终一致。

功能跑通后，验证需求变更前后的一致性。假设后来要加一个“文章标签”功能，不要直接让 Claude 改代码，而是新建一个提案：

新增需求：文章支持标签，前台可按标签筛选。 请在 openspec/proposals/ 下创建新提案，并说明对现有 Article 模型和前台路由的影响。

Claude 会生成新提案，并在proposal.md里列出需要修改的文件：prisma/schema.prisma加 Tag 模型、src/modules/article/下的控制器加筛选逻辑、前台模板加标签入口。你审查后执行，完成后用git diff对比，会发现改动范围严格限定在提案声明的文件内，没有误伤首页或其他模块。这就是“需求变更前后代码一致性验证”的落地方式：提案是契约，diff 是证据。

最后归档提案：

请将 add-article-management 提案归档到 openspec/archive/。

归档后，openspec/archive/里保留了这次变更的完整决策记录，以后接手的人翻 archive 就能知道当时为什么这么设计。整个流程走下来，从提案到功能可用大约一小时，其中大部分时间花在审查提案上，而不是反复修改 AI 生成的乱代码。

5. 常见报错排查：401、local proxy failed、reading choices 怎么解

接入和运行过程中，最容易卡在几个固定报错上。下面按真实遇到的顺序列出来，对照排查。

401 Unauthorized / invalid api key。这是 Key 的问题。先确认sk-开头有没有复制完整，前后有没有空格或换行。然后确认 Base URL 是https://taotoken.net/api，不是https://taotoken.net/api/v1（路径会重复）。如果用 Claude Code，检查settings.json里的ANTHROPIC_AUTH_TOKEN字段名有没有写错，有些版本读的是ANTHROPIC_API_KEY，两个都写上最稳。改完重启 Claude Code 再试。

local proxy failed / ECONNREFUSED。这个报错通常出现在客户端配置了本地代理端口但代理没启动，或者 Base URL 指向了localhost。检查你的客户端设置里有没有http.proxy之类的字段，清空它。如果用的是 Cline，在 VS Code 设置里搜 “proxy”，把http.proxy和https.proxy都设为空。然后确认ANTHROPIC_BASE_URL是https://taotoken.net/api，不是本地地址。

reading 'choices' of undefined。这个报错说明客户端按 OpenAI 格式解析响应，但服务端返回的是 Anthropic 格式，或者反过来。Claude Code 用 Anthropic 格式，Cline 选 Anthropic Provider 时也用 Anthropic 格式。如果你在 Cline 里选了 “OpenAI Compatible” 却填了 Anthropic 的 Base URL，就会报这个。解决办法是 Provider 选 Anthropic，Base URL 填https://taotoken.net/api，Model ID 填claude-sonnet-4-5-20250929。三件套对齐就不会报。

OAuth error / authentication failed。Claude Code 某些版本会尝试 OAuth 登录，如果你已经用 API Key 配置了环境变量，它会冲突。在settings.json里加上"forceApiKey": true，或者删除~/.claude/下的 OAuth 缓存文件重新登录。确认ANTHROPIC_AUTH_TOKEN存在且有效，OAuth 流程就不会被触发。

OpenSpec 命令找不到 / openspec: command not found。说明全局安装没成功，或者 npm 的全局 bin 目录不在 PATH 里。先npm list -g @fission-ai/openspec确认是否装上，如果装上了还找不到，执行npm config get prefix拿到全局路径，把这个路径下的bin目录加到 PATH。Windows 用户用管理员权限重开终端再试。

提案生成了但 Claude 不读。检查CLAUDE.md里有没有写“每次任务前读取 openspec/proposals/ 下对应提案”。如果没写，Claude 不会主动读。另外确认提案目录名和你在指令里写的一致，大小写敏感。可以在指令里直接给出绝对路径，比如“读取 openspec/proposals/add-article-management/proposal.md”，这样最稳。

排障的核心思路是：先确认三件套（Base URL + Key + Model ID）对齐，再确认客户端 Provider 格式和服务端一致，最后确认 OpenSpec 的规范文件真的被 Claude 读到了。这三层都通了，基本不会再有玄学报错。

6. 把规范变成习惯：让 Claude 长期稳定干活的接入方式

走到这里，你已经有了完整的链路：TaoToken 提供稳定的 Claude 调用通道，OpenSpec 提供规范驱动的变更流程，Claude Code 负责按规范生成代码。剩下的就是把它变成日常习惯。每次新需求，先写提案再动手；每次改 bug，先在tasks.md里记一笔再改；每次功能完成，归档提案。坚持两三周，你会发现返工次数明显下降，因为 Claude 不再靠猜，而是按你写好的规范执行。

如果你还在选客户端，Claude Code 适合终端党，Cline 适合 VS Code 用户，Codex 适合习惯 OpenAI 生态的人，三者都能对接 TaoToken。想先试试模型对话效果，可以打开https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite直接体验。需要长期跑编码任务或 Agent 的，建议看 Coding Plan，额度更划算，地址是https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite。接入文档在https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite，里面有各客户端的详细配置示例。控制台在https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite，Key 管理和用量查询都在那里。

最后给一个实用技巧：把openspec/project.md当成项目的“宪法”，每次 Claude 生成代码跑偏，不要急着改代码，先回头看project.md里有没有写清楚对应的约束。约束写清楚了，Claude 自然就听话了。规范不是负担，是让 AI 少犯错的最省力方式。