企业官网建设流程全解析

1. 为什么 AI Coding 需要 Rule、Spec、Harness 三层递进

你可能已经体验过这样的场景：对着 AI 编程助手说一句“帮我写个用户登录接口”，它几秒钟就吐出一大段代码，看起来有模有样。但当你把它放进项目里跑起来，问题就来了——命名风格和项目完全不搭、错误处理直接吞掉异常、数据库连接没有走连接池、单元测试一个都没有。你花在修 AI 代码上的时间，比自己从头写还多。

这不是模型能力不行，而是缺少工程化约束。AI Coding 的渐进式建设路径，本质上就是解决“AI 写得快但不可控”这个问题。Rule、Spec、Harness 这三层，分别对应三个核心痛点：风格一致性、需求理解准确性、质量可验证性。

Rule 层解决的是“AI 不知道我们团队的规矩”。就像新员工入职要先看员工手册，AI 也需要一份明确的规则文件，告诉它用什么技术栈、代码风格如何、哪些红线不能碰。没有 Rule，AI 每次生成的代码都像开盲盒。

Spec 层解决的是“AI 不理解我要做什么”。你口头说“做个搜索功能”，AI 可能理解成模糊匹配，而你实际要的是带权重排序的全文检索。Spec 就是一份双方确认的契约文档，把输入输出、边界条件、异常处理全部写清楚，AI 按图施工，返工率大幅下降。

Harness 层解决的是“AI 写的代码到底对不对”。Rule 和 Spec 都是事前约束，但 AI 仍然可能“阳奉阴违”——生成的代码看起来符合规范，实际运行起来一堆问题。Harness 就是自动化质检系统，每一步都验证，错了就反馈让 AI 重试，直到通过为止。

这三层不是替代关系，而是叠加关系。Rule 是地基，Spec 是框架，Harness 是验收标准。缺少任何一层，AI Coding 都停留在“玩具”阶段。而要把这三层串起来，你需要一个稳定的模型调用通道——TaoToken 在这里扮演的角色，就是让 Rule 配置、Spec 生成、Harness 验证脚本都能通过统一的 API 入口调用模型，不用在多个平台之间来回切换 Key 和 Base URL。

我试过把这三层拆开单独用，效果都不理想。只写 Rule 不写 Spec，AI 生成的代码风格对了但逻辑经常跑偏；只写 Spec 不搭 Harness，Spec 改了三版代码还是对不上。只有三层叠加，才能让 AI 从“需要 babysit 的实习生”变成“能独立承担任务的工程师”。

接下来的内容，我会按渐进式路径一步步演示：先配 Rule，再写 Spec，最后搭 Harness，每一步都给出可复制的配置片段和验证命令。你不需要一次性全做完，按周推进即可。

2. TaoToken 前置准备：统一 Key 与 API 通道配置

在开始写 Rule 之前，你需要先解决一个基础问题：模型调用的通道。不管你是用 Cursor、Claude Code 还是自己写脚本调 API，都需要一个稳定的 Base URL 和 API Key。TaoToken 的作用就是提供统一的模型调用入口，让你在 Rule 配置、Spec 生成、Harness 验证脚本里都用同一套凭证，不用每个工具单独配一遍。

2.1 获取 API Key 与确认 Base URL

首先访问 TaoToken 控制台创建 API Key。地址是 https://taotoken.net/api-keys ，登录后点击“创建新密钥”，复制生成的 Key 字符串。这个 Key 只显示一次，建议先存到密码管理器里。

Base URL 固定为https://taotoken.net/api，注意不要加末尾斜杠。如果你用的是 OpenAI 兼容的 SDK，Base URL 填这个地址即可；如果是 Anthropic 兼容的调用方式，同样用这个地址，TaoToken 会自动路由。

注意：API Key 不要硬编码在代码里提交到 Git。建议用环境变量TAOTOKEN_API_KEY存储，在 Rule 文件和 Harness 脚本里通过os.environ读取。

2.2 在 Cursor 中配置 TaoToken 通道

Cursor 支持自定义 OpenAI Base URL。打开 Cursor 设置，找到“Models”选项卡，在“OpenAI API Key”处填入你的 TaoToken Key，然后在“Override OpenAI Base URL”处填入https://taotoken.net/api。保存后，Cursor 的所有模型调用都会走 TaoToken 通道。

如果你用的是 Claude Code，配置方式略有不同。Claude Code 读取环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。在终端执行：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="你的TaoToken密钥"

然后运行claude命令，它会自动使用这个通道。你可以用/status命令确认当前连接的 Base URL 是否正确。

2.3 验证通道连通性

配置完成后，先做一次最简单的连通性验证。用 curl 发一个模型列表请求：

curl -s https://taotoken.net/api/v1/models \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" | head -c 500

如果返回 JSON 格式的模型列表，说明 Key 和 Base URL 都正确。如果返回 401，检查 Key 是否复制完整；如果返回 404，检查 Base URL 是否多了或少了/v1路径。

对于 Claude Code 用户，可以直接在对话里问一句“你当前使用的模型 ID 是什么”，如果它能正常回复，说明通道已经通了。这一步看起来简单，但很多后续的 Rule 和 Harness 问题都源于通道没配好，所以务必先确认这一步通过。

2.4 记录你的 Model ID

TaoToken 支持多个模型，你需要确认自己要用哪个 Model ID。常见的包括claude-sonnet-4-20250514、gpt-4o等。在 Cursor 的模型选择器里可以看到可用列表，或者用上面的 curl 命令查看/v1/models返回的data[].id字段。

记下你选定的 Model ID，后面写 Rule 配置和 Harness 脚本时会用到。如果你不确定选哪个，建议先用claude-sonnet-4-20250514做代码生成，它在代码任务上表现比较均衡。

3. Rule 层可复制配置：给 AI 立规矩的完整片段

Rule 层的核心是让 AI 在生成代码之前就知道“我们团队的规矩”。Cursor 的规则系统支持多级配置，我建议按“全局规则 + 项目规则 + 动态规则”三层来组织。下面给出可直接复制的配置片段。

3.1 项目级规则文件.cursor/index.mdc

在项目根目录创建.cursor/index.mdc文件，这是整个团队的“宪法”。内容如下：

--- description: 项目级 AI 编码规则 globs: ["**/*"] alwaysApply: true --- # 技术栈约束 - 前端：React 18 + TypeScript 5，禁止使用 any 类型 - 后端：Node.js 20 + Fastify，数据库统一用 Prisma ORM - 测试：Vitest + Testing Library，每个新函数必须有对应单测 # 代码风格 - 缩进 2 空格，单引号，语句末尾不加分号 - 函数命名用 camelCase，组件命名用 PascalCase - 禁止使用 console.log，统一用 logger.info/warn/error # 红线规则 - 禁止直接操作数据库连接，必须通过 Prisma Client - 禁止在业务代码中硬编码 API Key 或密钥 - 所有对外接口必须先写 OpenAPI Spec，再写实现代码 - 复杂功能（超过 50 行）必须先写 Spec 文档，再生成代码

这个文件的关键在于alwaysApply: true，它会让 Cursor 在每次对话时都加载这些规则。globs字段指定规则适用的文件范围，**/*表示所有文件。

3.2 动态规则文件.cursor/rules/database.mdc

对于特定领域的规则，放在.cursor/rules/目录下，按需加载。比如数据库操作规则：

--- description: 数据库操作专项规则 globs: ["src/db/**/*.ts", "src/repositories/**/*.ts"] alwaysApply: false --- # 数据库操作规范 - 所有写操作必须包裹在 Prisma $transaction 中 - 批量操作单次不超过 1000 条，超过则分批 - 查询必须指定 select 字段，禁止 select * - 软删除统一用 deletedAt 字段，禁止物理删除 # 错误处理 - 数据库错误必须捕获并转换为业务错误码 - 唯一约束冲突返回 409，外键约束返回 400

alwaysApply: false表示这个规则只在编辑匹配globs的文件时加载，避免污染其他任务的上下文。

3.3 在 Rule 中嵌入 TaoToken 调用约定

如果你在项目里用脚本调用 TaoToken API 做代码生成，可以在 Rule 里写明调用约定，让 AI 生成的代码自动遵循：

# 模型调用约定 - 所有 LLM 调用统一走 TaoToken 通道 - Base URL: https://taotoken.net/api - API Key 从环境变量 TAOTOKEN_API_KEY 读取 - Model ID 统一用 claude-sonnet-4-20250514 - 调用失败时重试 3 次，间隔 1s/2s/4s

这样当 AI 帮你写调用模型的代码时，它会自动使用正确的 Base URL 和 Key 读取方式，不会生成硬编码密钥的代码。

3.4 验证 Rule 是否生效

配置完成后，在 Cursor 里新建一个文件，输入注释// 写一个用户查询函数，看 AI 生成的代码是否符合规则。重点检查：是否用了 TypeScript 类型、是否用了 Prisma、是否有对应的错误处理。如果不符合，检查.cursor/index.mdc的alwaysApply是否为 true，以及文件是否在项目根目录的.cursor/下。

Rule 层不需要追求一次写完美。建议先写 10 条最核心的规则，用一周时间观察 AI 的输出，发现新问题就补充一条。规则文件会随着项目演进逐渐丰富，但不要一次性写 50 条，那样 AI 反而抓不住重点。

4. Spec 层模板与生成流程：先写契约再写代码

Rule 解决了风格问题，但 AI 仍然可能理解错需求。Spec 层的作用就是在写代码之前，先产出一份双方确认的契约文档。下面给出可直接复制的 Spec 模板和生成流程。

4.1 Spec 模板specs/user-search.md

在项目里创建specs/目录，每个功能一个 Markdown 文件。模板如下：

# 功能规格：用户搜索 ## 用户故事 作为管理员，我可以在用户列表中按姓名/邮箱搜索，以便快速定位目标用户。 ## 输入 - keyword: string, 必填, 长度 1-50 - page: number, 可选, 默认 1 - pageSize: number, 可选, 默认 20, 最大 100 ## 输出 - items: User[], 匹配的用户列表 - total: number, 总匹配数 - page: number, 当前页码 ## 边界条件 - keyword 为空字符串：返回 400 错误 - keyword 超过 50 字符：截断到 50 - page 小于 1：重置为 1 - pageSize 超过 100：重置为 100 ## 异常处理 - 数据库连接失败：返回 503，记录 error 日志 - 查询超时（>3s）：返回 504，记录 warn 日志 ## 验收标准 - [ ] 按姓名模糊匹配，不区分大小写 - [ ] 按邮箱精确匹配，不区分大小写 - [ ] 结果按 createdAt 倒序排列 - [ ] 分页参数越界时自动修正 - [ ] 单元测试覆盖上述所有边界条件

这个模板的关键是“验收标准”部分，它直接对应 Harness 层的验证脚本。Spec 写得越具体，Harness 越好写。

4.2 用 TaoToken 通道生成 Spec 初稿

你可以让 AI 帮你生成 Spec 初稿。在 Claude Code 里执行：

claude --model claude-sonnet-4-20250514 \ "根据以下需求生成 Spec 文档：用户搜索功能，支持按姓名和邮箱搜索，需要分页。输出格式参考 specs/ 目录下的模板。"

Claude Code 会读取项目里的模板文件，生成一份符合格式的 Spec。你 review 后手动调整边界条件，确认无误后保存到specs/user-search.md。

如果你用 Cursor，直接在对话里说“参考 specs/ 目录的模板，为用户搜索功能写一份 Spec”，它会自动读取模板并生成。

4.3 从 Spec 生成代码

Spec 确认后，让 AI 按 Spec 生成代码。在 Claude Code 里：

claude --model claude-sonnet-4-20250514 \ "按照 specs/user-search.md 的规格，实现对应的 API 接口和单元测试。遵循 .cursor/index.mdc 的规则。"

关键点是同时引用 Spec 文件和 Rule 文件，这样 AI 既知道要做什么，也知道怎么做。生成完成后，检查代码是否覆盖了 Spec 里的所有验收标准。

4.4 Spec 与 Rule 的联动

你可以在 Rule 里加一条：“所有超过 50 行的功能必须先写 Spec”。这样当你在 Cursor 里直接让 AI 写一个大功能时，它会先提醒你“这个功能超过 50 行，建议先写 Spec”，而不是直接开始生成代码。

Spec 文件本身也可以被 Rule 引用。比如在.cursor/index.mdc里写：“实现新功能时，先读取 specs/ 目录下对应的 Spec 文件”。这样 AI 在生成代码前会自动加载 Spec，减少理解偏差。

5. Harness 层校验脚本与常见报错排查

Harness 层的目标是自动化验证 AI 生成的代码是否符合 Spec。下面给出一个可复制的校验脚本，以及常见报错的排查方法。

5.1 Harness 校验脚本scripts/harness.sh

在项目里创建scripts/harness.sh，内容如下：

#!/bin/bash set -e echo "=== Harness 校验开始 ===" # 1. 类型检查 echo "[1/5] TypeScript 类型检查..." npx tsc --noEmit if [ $? -ne 0 ]; then echo "类型检查失败，反馈给 AI 修复" exit 1 fi # 2. Lint 检查 echo "[2/5] ESLint 检查..." npx eslint src/ --max-warnings 0 # 3. 单元测试 echo "[3/5] 运行单元测试..." npx vitest run --coverage # 4. Spec 验收标准检查 echo "[4/5] 检查 Spec 验收标准..." npx tsx scripts/check-spec.ts specs/user-search.md # 5. 安全扫描 echo "[5/5] 依赖安全扫描..." npm audit --audit-level=high echo "=== Harness 校验通过 ==="

这个脚本把类型检查、Lint、单测、Spec 验收、安全扫描串成一条流水线。任何一步失败就退出，并把错误信息反馈给 AI。

5.2 用 TaoToken 通道做 AI 自动修复

当 Harness 校验失败时，你可以写一个脚本把错误信息发给 TaoToken 通道，让 AI 自动修复：

#!/bin/bash # scripts/auto-fix.sh ERROR_LOG=$(npx tsc --noEmit 2>&1 || true) if [ -n "$ERROR_LOG" ]; then curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"model\": \"claude-sonnet-4-20250514\", \"messages\": [{ \"role\": \"user\", \"content\": \"以下 TypeScript 编译错误，请给出修复方案：\n$ERROR_LOG\" }] }" | jq -r '.choices[0].message.content' fi

这个脚本把编译错误发给模型，模型返回修复建议。你可以手动应用，也可以进一步自动化。

5.3 常见报错排查

报错一：401 Unauthorized

{"error": {"message": "Invalid API key", "type": "invalid_request_error"}}

原因：TaoToken API Key 未设置或复制不完整。排查：执行echo $TAOTOKEN_API_KEY确认环境变量有值；检查 Key 是否包含多余空格；在 TaoToken 控制台确认 Key 未过期。

报错二：local proxy failed / connection refused

Error: connect ECONNREFUSED 127.0.0.1:8080

原因：本地代理配置残留，导致请求被转发到不存在的本地端口。排查：检查HTTP_PROXY和HTTPS_PROXY环境变量是否为空；在 Cursor 设置里关闭“Use Local Proxy”选项；Claude Code 用户检查~/.claude/settings.json里是否有 proxy 配置。

报错三：reading choices 时 panic

panic: runtime error: index out of range [0] with length 0

原因：模型返回的 JSON 里choices数组为空，通常是请求参数不合法或模型 ID 写错。排查：确认 Model ID 拼写正确（如claude-sonnet-4-20250514不要写成claude-sonnet-4）；检查请求体里messages数组不为空；用 curl 直接测试同一请求，看返回的原始 JSON。

报错四：OAuth token expired

Error: OAuth token has expired, please re-authenticate

原因：Claude Code 的 OAuth 凭证过期。排查：执行claude logout然后claude login重新认证；如果用的是 TaoToken 通道，确认ANTHROPIC_API_KEY环境变量已设置，且ANTHROPIC_BASE_URL指向https://taotoken.net/api。

5.4 三件套配置检查清单

如果你用 Claude Code 或 Cline MCP，确保以下三件套都配置正确：

三项都正确后，Harness 脚本才能稳定调用模型做自动修复。如果其中一项缺失，会出现 401 或连接失败。

6. 把三层串起来：可复现的 AI Coding 流水线

到这里，Rule、Spec、Harness 三层已经分别配置完成。最后一步是把它们串成一条可复现的流水线，让每次 AI 生成代码都自动经过这三层约束。

6.1 流水线执行顺序

推荐的执行顺序是：Rule 加载 → Spec 生成 → 代码生成 → Harness 校验 → 失败则自动修复 → 重新校验。对应到具体操作：

第一步，在 Cursor 或 Claude Code 里打开项目，确保.cursor/index.mdc和.cursor/rules/*.mdc已加载。你可以在对话里问“当前生效的规则有哪些”，AI 会列出加载的规则文件。

第二步，用 Spec 模板生成功能规格。在 Claude Code 里执行claude --model claude-sonnet-4-20250514 "参考 specs/ 模板为用户搜索功能写 Spec"，生成后手动 review 边界条件。

第三步，按 Spec 生成代码。执行claude --model claude-sonnet-4-20250514 "按 specs/user-search.md 实现代码，遵循项目规则"。

第四步，运行 Harness 校验。执行bash scripts/harness.sh，观察五步检查是否全部通过。

第五步，如果校验失败，运行bash scripts/auto-fix.sh获取修复建议，应用后重新跑 Harness。

6.2 在 CI 中固化 Harness

把 Harness 脚本加入 CI 流水线，每次 PR 提交自动运行。以 GitHub Actions 为例：

name: AI Coding Harness on: [pull_request] jobs: harness: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - run: bash scripts/harness.sh env: TAOTOKEN_API_KEY: ${{ secrets.TAOTOKEN_API_KEY }}

这样每次 AI 生成的代码提交 PR 时，都会自动经过类型检查、Lint、单测、Spec 验收和安全扫描。任何一步失败，PR 会被标记为不通过，强制修复后才能合并。

6.3 渐进式推进节奏

不要试图一周内把三层全部建完。建议按以下节奏推进：

第一周：只配 Rule。写.cursor/index.mdc和 2-3 个动态规则文件，观察 AI 输出质量变化。

第二周：引入 Spec。为下一个新功能写 Spec，让 AI 按 Spec 生成代码，对比返工率。

第三周：搭建 Harness。写scripts/harness.sh，在本地跑通五步检查。

第四周：接入 CI。把 Harness 加入 GitHub Actions，固化到 PR 流程。

每层单独验证有效后再叠加下一层，这样出问题时容易定位是哪一层的配置有误。

6.4 长期维护建议

Rule 文件每月 review 一次，删除过时规则，补充新发现的坑。Spec 文件按功能模块归档，新功能先搜有没有可复用的 Spec 片段。Harness 脚本根据项目演进增加检查项，比如引入新框架后加对应的 lint 规则。

TaoToken 通道的 Key 建议每 90 天轮换一次，在控制台生成新 Key 后更新环境变量和 CI secrets。Model ID 如果升级，同步更新 Rule 文件和 Harness 脚本里的引用。

这套流水线跑顺之后，你会发现 AI 生成的代码从“需要逐行 review”变成“抽查关键逻辑即可”。Rule 保证了风格一致，Spec 保证了需求对齐，Harness 保证了质量底线。三层叠加，才是 AI Coding 从玩具变成生产工具的关键。