1. Vidocoding 开发流程到底解决什么问题Vidocoding 这个词最近在开发者圈子里出现得越来越频繁它本质上说的是「用 AI 辅助完成从需求到代码的整条链路」而不是单纯让 AI 帮你补全几行函数。很多人第一次接触 Vidocoding会以为就是打开对话框说一句「帮我写个博客系统」然后等着 AI 吐出一堆代码。真这么做结果通常是项目跑不起来、目录乱成一团、改一个功能崩三个地方。问题不在 AI 能力不够而在于你没有给它一套可执行的开发流程。我理解的 Vidocoding 开发流程核心是把「人负责决策、AI 负责执行」这件事拆成清晰的阶段先想清楚要做什么再写成 PRD然后做技术设计接着用 AGENTS.md 给 AI 立规矩最后才是分步实现和迭代。这套流程适合谁适合那些已经会用 AI 写代码、但项目一复杂就失控的开发者也适合想带团队用统一规范协作的人。它不要求你是架构师但要求你愿意在动手前花时间把需求和技术方案写清楚。为什么流程比工具更重要因为 AI 的上下文窗口是有限的它不会自动记住你三天前的设计决策。你今天让它写用户模块明天让它写订单模块如果中间没有一份稳定的文档约束它生成的代码风格、命名习惯、目录结构会前后矛盾。等你发现的时候重构成本已经很高了。Vidocoding 的价值就在于用 PRD 锁定「做什么」用 TECH_DESIGN.md 锁定「怎么做」用 AGENTS.md 锁定「按什么规矩做」三者叠加AI 每次生成代码时都有明确的参照物。这篇文章会按真实开发顺序走一遍先讲怎么把模糊想法整理成 PRD再讲技术设计文档怎么写然后给出 AGENTS.md 的骨架接着用 TaoToken 统一 Key 配置好模型调用环境最后演示一次从需求到代码的验证动作。每一步都有可复制的模板和命令你可以直接拿去改。整个流程走完你会得到一套能反复使用的 Vidocoding 工作方式而不是一次性的提示词技巧。2. 用 PRD 把模糊需求变成 AI 能执行的地图2.1 PRD 不是给老板看的是给 AI 看的传统产品经理写 PRD 是给开发和设计看的讲究排版和话术。Vidocoding 里的 PRD 目标读者是 AI所以写法要反过来少用形容词多用结构化字段少写「用户体验流畅」多写「点击按钮后 200ms 内返回结果」。AI 不需要你说服它它需要你告诉它边界在哪。一份能直接喂给 AI 的 PRD我建议至少包含这几块产品概述一句话说清是什么、目标用户谁用、什么场景用、核心功能列表按模块拆、功能优先级MVP 必须做的和后续版本再做的分开、界面要求布局、交互、响应式、技术栈建议语言、框架、数据库、代码风格命名、注释、目录约定、边界场景空数据、超时、权限不足怎么处理。其中功能优先级最容易被忽略但恰恰最重要。你不标优先级AI 会把所有功能都塞进第一版最后你的 MVP 比别人的正式版还臃肿。2.2 一份可复制的 PRD 模板下面这份模板你可以直接存成PRD.md把方括号里的内容替换成你的项目信息。注意每个功能都带验收标准这是后面验证 AI 输出是否合格的依据。# PRD: [项目名称] ## 1. 产品概述 [一句话描述产品是什么解决什么问题] ## 2. 目标用户 - 用户画像[谁] - 使用场景[什么时候、在哪用] - 核心痛点[现在怎么解决的哪里不爽] ## 3. 核心功能 ### 3.1 [功能模块 A]MVP - 描述[做什么] - 验收标准[可测量的结果如输入 1-100 字符超出提示错误] - 优先级P0 ### 3.2 [功能模块 B]MVP - 描述[做什么] - 验收标准[可测量的结果] - 优先级P0 ### 3.3 [功能模块 C]后续版本 - 描述[做什么] - 优先级P2 ## 4. 界面要求 - 布局[移动端优先 / 桌面端优先] - 关键页面[列出页面和跳转关系] - 交互细节[加载态、错误态、空态怎么展示] ## 5. 技术栈建议 - 前端[框架 语言] - 后端[框架 语言] - 数据库[类型 版本] - 部署[方式] ## 6. 代码风格 - 命名[驼峰 / 下划线] - 注释[哪些地方必须写] - 目录约定[按功能分 / 按类型分] ## 7. 边界场景 - 空数据[怎么展示] - 网络超时[重试几次怎么提示] - 权限不足[跳转还是提示]2.3 写 PRD 时最容易踩的坑第一个坑是把 PRD 写成愿望清单。「支持多种登录方式」这种描述 AI 没法执行你得写成「支持邮箱密码登录和手机号验证码登录两种方式在同一个页面用 Tab 切换」。第二个坑是优先级不分。我试过把十几个功能全标成 P0结果 AI 生成的项目里每个模块都只做了一半因为它在有限的输出里要兼顾所有功能。后来我改成只留三个 P0其余全标 P2第一版反而跑通了。第三个坑是验收标准写得太虚。「性能好」不是标准「列表页 100 条数据渲染时间小于 300ms」才是。你写得越具体后面验证 AI 输出时越省事。PRD 写完后不要急着让 AI 写代码先让它复述一遍你的需求。你可以这样问「请阅读 PRD.md用你自己的话总结这个项目的核心功能和 MVP 范围并指出哪些地方描述不够清晰。」如果 AI 的复述和你的预期一致说明 PRD 合格如果它理解偏了说明你写得不清楚回去改。这一步花五分钟能省后面几小时的返工。3. 技术设计与 AGENTS.md 给 AI 立规矩3.1 TECH_DESIGN.md 要写什么PRD 回答「做什么」技术设计回答「怎么做」。这一步要创建TECH_DESIGN.md内容包括技术栈选择、项目结构、数据模型、关键技术点。技术栈选择要写清楚版本比如「Node.js 20 Express 4 PostgreSQL 15」不要只写「用 Node」。项目结构要提前规划目录代码放哪、组件怎么组织、工具函数放哪都写明白。不然 AI 生成的代码东一块西一块后期找 Bug 像大海捞针。数据模型是技术设计里最关键的部分。你要存哪些表、每个字段什么类型、表之间什么关系都要定义。我踩过的坑是没定义字段类型AI 把金额字段定义成字符串把日期字段定义成布尔值。后来我在技术设计里强制写字段类型这类问题就没了。下面是一个数据模型示例## 数据模型 ### users 表 | 字段 | 类型 | 约束 | 说明 | |------|------|------|------| | id | bigint | PK, auto | 用户 ID | | email | varchar(255) | unique, not null | 登录邮箱 | | password_hash | varchar(255) | not null | bcrypt 哈希 | | created_at | timestamp | default now() | 创建时间 | ### posts 表 | 字段 | 类型 | 约束 | 说明 | |------|------|------|------| | id | bigint | PK, auto | 文章 ID | | user_id | bigint | FK - users.id | 作者 | | title | varchar(200) | not null | 标题 | | content | text | not null | 正文 | | status | varchar(20) | default draft | draft/published |3.2 AGENTS.md 骨架让 AI 输出风格统一AGENTS.md 可以理解为给 AI 立的规矩。有了它AI 生成的代码就像同一个师傅教出来的风格统一、规范一致。这份文件放在项目根目录AI 工具在读取项目时会自动加载。骨架如下# AGENTS.md ## 项目背景 [一句话说明项目是什么指向 PRD.md 和 TECH_DESIGN.md] ## 技术栈 - 语言[如 TypeScript 5.x] - 框架[如 Next.js 14 App Router] - 数据库[如 PostgreSQL 15 Prisma] - 测试[如 Vitest] ## 代码规范 - 命名变量和函数用 camelCase类型和组件用 PascalCase常量用 UPPER_SNAKE_CASE - 缩进2 空格不用 Tab - 引号单引号JSX 属性用双引号 - 分号必须写 - 注释公共函数必须写 JSDoc复杂逻辑写行内注释 ## 目录约定 - src/app页面和路由 - src/components可复用组件 - src/lib工具函数和第三方封装 - src/types全局类型定义 - tests测试文件与被测文件同结构 ## 提交规范 - 格式type(scope): subject - type 取值feat / fix / docs / refactor / test / chore ## 禁止事项 - 禁止在组件里直接写 fetch统一走 src/lib/api.ts - 禁止使用 any必要时用 unknown 加类型守卫 - 禁止提交 console.log调试用 logger3.3 三份文档怎么配合使用PRD、TECH_DESIGN、AGENTS.md 不是孤立的。PRD 定义范围和验收标准TECH_DESIGN 定义实现路径和数据结构AGENTS.md 定义编码规矩。每次让 AI 写代码前你可以用一句话把三者串起来「请根据 PRD.md 的 3.1 功能、TECH_DESIGN.md 的 users 表结构、AGENTS.md 的代码规范实现用户注册接口。」这样 AI 的输入上下文是完整的输出质量会明显提升。如果你用的是支持项目级配置的 AI 编码工具可以把这三份文档的路径写进工具的配置文件里让它每次自动加载。下面是一个config.toml示例把模型调用统一走 TaoToken同时指定文档路径# config.toml [model] provider taotoken base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model_id claude-sonnet-4-20250514 [project] prd PRD.md tech_design TECH_DESIGN.md agents AGENTS.md [generation] temperature 0.3 max_tokens 8192这里base_url用https://taotoken.net/api不要加多余路径。model_id按你实际使用的模型填。temperature设低一点代码生成任务不需要太发散。配置好后AI 工具每次请求都会带上项目文档作为上下文生成结果会更贴合你的设计。4. 用 TaoToken 统一 Key 打通模型调用4.1 为什么需要统一 KeyVidocoding 流程里你可能会用到多个 AI 工具一个用来做需求分析一个用来写代码一个用来做代码审查。如果每个工具都单独配 Key管理起来很麻烦而且不同工具的计费和额度是分开的。用 TaoToken 统一 Key 的好处是一个 Key 走所有工具计费集中切换模型也方便。TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的接口大部分 AI 编码工具都能直接对接。4.2 获取 Key 并配置到项目第一步打开 TaoToken 控制台创建 API Key。地址是https://taotoken.net/console登录后在 API Keys 页面生成一个新 Key复制保存。注意 Key 只显示一次丢了要重新生成。第二步把 Key 写进项目配置。不要硬编码在代码里用环境变量。在项目根目录创建.env文件# .env TAOTOKEN_API_KEYsk-你的TaoToken密钥 TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELclaude-sonnet-4-20250514然后在.gitignore里加上.env避免 Key 被提交到仓库。如果你用的是 Node.js 项目可以用dotenv加载// src/lib/ai-client.js import OpenAI from openai; import dotenv/config; const client new OpenAI({ apiKey: process.env.TAOTOKEN_API_KEY, baseURL: process.env.TAOTOKEN_BASE_URL, }); export async function askAI(prompt) { const res await client.chat.completions.create({ model: process.env.TAOTOKEN_MODEL, messages: [{ role: user, content: prompt }], temperature: 0.3, }); return res.choices[0].message.content; }4.3 在 AI 编码工具里配置 TaoToken如果你用的是 Claude Code 这类命令行工具可以在项目里创建.claude/settings.json把模型请求指向 TaoToken{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Cline 这类 VS Code 插件在插件设置里找到 API Provider选 OpenAI CompatibleBase URL 填https://taotoken.net/apiAPI Key 填你的 TaoToken KeyModel ID 填claude-sonnet-4-20250514。保存后插件就会通过 TaoToken 调用模型。这里要提醒一点Base URL 只填到/api不要在后面加/v1或其他路径。有些工具会自动补全路径你多写了反而会 404。Model ID 要和你实际使用的模型一致写错了会报模型不存在。4.4 验证配置是否生效配置完成后用一条最简单的请求验证。在项目里跑curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 OK 两个字母}], max_tokens: 10 }如果返回的 JSON 里choices[0].message.content包含OK说明 Key 和 Base URL 都正确。如果返回 401检查 Key 是否复制完整如果返回 404检查 Base URL 是否多写了路径如果返回模型不存在检查 Model ID 拼写。这一步验证通过后再回到 AI 编码工具里测试能省很多排查时间。5. 从需求到代码的验证与常见报错排查5.1 一次完整的验证动作前面四步准备好后现在做一次从需求到代码的验证。假设 PRD 里有一个 P0 功能「用户注册」TECH_DESIGN 里定义了 users 表AGENTS.md 规定了代码规范。你可以这样给 AI 下指令请根据以下上下文实现用户注册功能 1. PRD.md 中 3.1 功能模块 A邮箱密码注册验收标准为邮箱格式校验、密码至少 8 位、重复邮箱返回 409 2. TECH_DESIGN.md 中 users 表结构 3. AGENTS.md 中代码规范TypeScript、camelCase、JSDoc 注释 输出要求 - 生成 src/app/api/register/route.ts - 生成 src/lib/validators.ts 中的邮箱和密码校验函数 - 生成对应的 Vitest 测试文件AI 返回代码后不要直接合并。先跑测试npm run test -- tests/register.test.ts测试通过后再手动验证接口curl -X POST http://localhost:3000/api/register \ -H Content-Type: application/json \ -d {email:testexample.com,password:12345678}预期返回 201 和用户 ID。再用同一个邮箱请求一次预期返回 409。如果两个都符合说明这个功能从需求到代码的链路是通的。接下来按同样方式做下一个 P0 功能每做完一个就验证一个不要攒着一起测。5.2 常见报错对照排查报错一401 Unauthorized{error:{message:Invalid API key,type:invalid_request_error}}原因通常是 Key 没配好。检查.env里的TAOTOKEN_API_KEY是否完整有没有多余空格。如果你用的是 Claude Code检查.claude/settings.json里的ANTHROPIC_API_KEY是否和 TaoToken 控制台生成的一致。还有一种情况是 Key 被撤销了去控制台重新生成一个。报错二local proxy failed / connection refusedError: connect ECONNREFUSED 127.0.0.1:8080这个报错说明工具在尝试走本地代理但代理没启动。检查你的环境变量里有没有HTTP_PROXY或HTTPS_PROXY如果有临时取消掉unset HTTP_PROXY unset HTTPS_PROXY然后重新请求。TaoToken 的 API 地址是直连的不需要额外代理配置。报错三reading choices 时 undefinedTypeError: Cannot read properties of undefined (reading choices)这个报错说明 API 返回的结构和你代码里解析的结构不一致。常见原因是 Base URL 写错了请求打到了别的端点返回的不是标准 OpenAI 格式。检查baseURL是否为https://taotoken.net/api不要加/v1。另外检查 Model ID 是否正确模型不存在时有些网关会返回非标准错误结构。报错四OAuth 相关错误Error: OAuth token expired如果你用的是 Claude Code 的 OAuth 登录方式而不是 API Key可能会遇到这个。解决办法是改用 API Key 方式在.claude/settings.json里配置ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL不要用 OAuth。TaoToken 走的是 API Key 鉴权不涉及 OAuth 流程。5.3 迭代阶段的注意事项核心功能跑通后进入迭代阶段。这时候不要一次性让 AI 重构整个项目而是按功能点逐个改。每次改之前先更新 PRD 或 TECH_DESIGN 里对应的描述再让 AI 按新描述改代码。改完跑测试测试通过再提交。提交信息按 AGENTS.md 里的规范写比如feat(auth): add password reset。如果 AI 生成的代码不符合 AGENTS.md 规范不要手动改而是把规范文件重新贴给它让它按规范重写。这样能保证规范始终生效。时间长了你会发现AI 的输出越来越稳定因为你的文档越来越完善上下文越来越清晰。这就是 Vidocoding 流程的复利效应前期投入的文档时间会在后期每次生成代码时省回来。6. 把流程固化成可复用的工作方式走到这里你已经有了 PRD 模板、TECH_DESIGN 结构、AGENTS.md 骨架以及 TaoToken 统一 Key 的配置方式。接下来要做的是把这套流程固化成习惯。我的做法是在项目根目录建一个docs/文件夹把三份文档放进去然后在 README 里写清楚每次开发前先读这三份文档。新项目直接复制这套结构改内容就行不用从零想。如果你经常做同类项目可以把 PRD 和 AGENTS.md 做成模板库按项目类型分类。比如 Web 应用一套、CLI 工具一套、数据处理脚本一套。下次开新项目选对应模板改改字段就能用。TaoToken 的 Key 可以跨项目复用配置一次所有项目共享。这样你的启动成本会越来越低。最后说一个实用技巧每次让 AI 生成代码前先让它复述一遍当前任务涉及的 PRD 条目、技术设计约束和 AGENTS.md 规范。如果复述正确再让它写代码如果复述有偏差先纠正理解再动手。这个习惯能挡掉大部分「AI 理解错需求」的问题。流程不是束缚是让 AI 的输出可控、可预期、可复用。把这套跑顺之后你会发现 Vidocoding 真正省下的不是打字时间而是返工时间。
Vidocoding 开发流程实战：用 AGENTS.md 与 PRD 打通技术设计到落地
1. Vidocoding 开发流程到底解决什么问题Vidocoding 这个词最近在开发者圈子里出现得越来越频繁它本质上说的是「用 AI 辅助完成从需求到代码的整条链路」而不是单纯让 AI 帮你补全几行函数。很多人第一次接触 Vidocoding会以为就是打开对话框说一句「帮我写个博客系统」然后等着 AI 吐出一堆代码。真这么做结果通常是项目跑不起来、目录乱成一团、改一个功能崩三个地方。问题不在 AI 能力不够而在于你没有给它一套可执行的开发流程。我理解的 Vidocoding 开发流程核心是把「人负责决策、AI 负责执行」这件事拆成清晰的阶段先想清楚要做什么再写成 PRD然后做技术设计接着用 AGENTS.md 给 AI 立规矩最后才是分步实现和迭代。这套流程适合谁适合那些已经会用 AI 写代码、但项目一复杂就失控的开发者也适合想带团队用统一规范协作的人。它不要求你是架构师但要求你愿意在动手前花时间把需求和技术方案写清楚。为什么流程比工具更重要因为 AI 的上下文窗口是有限的它不会自动记住你三天前的设计决策。你今天让它写用户模块明天让它写订单模块如果中间没有一份稳定的文档约束它生成的代码风格、命名习惯、目录结构会前后矛盾。等你发现的时候重构成本已经很高了。Vidocoding 的价值就在于用 PRD 锁定「做什么」用 TECH_DESIGN.md 锁定「怎么做」用 AGENTS.md 锁定「按什么规矩做」三者叠加AI 每次生成代码时都有明确的参照物。这篇文章会按真实开发顺序走一遍先讲怎么把模糊想法整理成 PRD再讲技术设计文档怎么写然后给出 AGENTS.md 的骨架接着用 TaoToken 统一 Key 配置好模型调用环境最后演示一次从需求到代码的验证动作。每一步都有可复制的模板和命令你可以直接拿去改。整个流程走完你会得到一套能反复使用的 Vidocoding 工作方式而不是一次性的提示词技巧。2. 用 PRD 把模糊需求变成 AI 能执行的地图2.1 PRD 不是给老板看的是给 AI 看的传统产品经理写 PRD 是给开发和设计看的讲究排版和话术。Vidocoding 里的 PRD 目标读者是 AI所以写法要反过来少用形容词多用结构化字段少写「用户体验流畅」多写「点击按钮后 200ms 内返回结果」。AI 不需要你说服它它需要你告诉它边界在哪。一份能直接喂给 AI 的 PRD我建议至少包含这几块产品概述一句话说清是什么、目标用户谁用、什么场景用、核心功能列表按模块拆、功能优先级MVP 必须做的和后续版本再做的分开、界面要求布局、交互、响应式、技术栈建议语言、框架、数据库、代码风格命名、注释、目录约定、边界场景空数据、超时、权限不足怎么处理。其中功能优先级最容易被忽略但恰恰最重要。你不标优先级AI 会把所有功能都塞进第一版最后你的 MVP 比别人的正式版还臃肿。2.2 一份可复制的 PRD 模板下面这份模板你可以直接存成PRD.md把方括号里的内容替换成你的项目信息。注意每个功能都带验收标准这是后面验证 AI 输出是否合格的依据。# PRD: [项目名称] ## 1. 产品概述 [一句话描述产品是什么解决什么问题] ## 2. 目标用户 - 用户画像[谁] - 使用场景[什么时候、在哪用] - 核心痛点[现在怎么解决的哪里不爽] ## 3. 核心功能 ### 3.1 [功能模块 A]MVP - 描述[做什么] - 验收标准[可测量的结果如输入 1-100 字符超出提示错误] - 优先级P0 ### 3.2 [功能模块 B]MVP - 描述[做什么] - 验收标准[可测量的结果] - 优先级P0 ### 3.3 [功能模块 C]后续版本 - 描述[做什么] - 优先级P2 ## 4. 界面要求 - 布局[移动端优先 / 桌面端优先] - 关键页面[列出页面和跳转关系] - 交互细节[加载态、错误态、空态怎么展示] ## 5. 技术栈建议 - 前端[框架 语言] - 后端[框架 语言] - 数据库[类型 版本] - 部署[方式] ## 6. 代码风格 - 命名[驼峰 / 下划线] - 注释[哪些地方必须写] - 目录约定[按功能分 / 按类型分] ## 7. 边界场景 - 空数据[怎么展示] - 网络超时[重试几次怎么提示] - 权限不足[跳转还是提示]2.3 写 PRD 时最容易踩的坑第一个坑是把 PRD 写成愿望清单。「支持多种登录方式」这种描述 AI 没法执行你得写成「支持邮箱密码登录和手机号验证码登录两种方式在同一个页面用 Tab 切换」。第二个坑是优先级不分。我试过把十几个功能全标成 P0结果 AI 生成的项目里每个模块都只做了一半因为它在有限的输出里要兼顾所有功能。后来我改成只留三个 P0其余全标 P2第一版反而跑通了。第三个坑是验收标准写得太虚。「性能好」不是标准「列表页 100 条数据渲染时间小于 300ms」才是。你写得越具体后面验证 AI 输出时越省事。PRD 写完后不要急着让 AI 写代码先让它复述一遍你的需求。你可以这样问「请阅读 PRD.md用你自己的话总结这个项目的核心功能和 MVP 范围并指出哪些地方描述不够清晰。」如果 AI 的复述和你的预期一致说明 PRD 合格如果它理解偏了说明你写得不清楚回去改。这一步花五分钟能省后面几小时的返工。3. 技术设计与 AGENTS.md 给 AI 立规矩3.1 TECH_DESIGN.md 要写什么PRD 回答「做什么」技术设计回答「怎么做」。这一步要创建TECH_DESIGN.md内容包括技术栈选择、项目结构、数据模型、关键技术点。技术栈选择要写清楚版本比如「Node.js 20 Express 4 PostgreSQL 15」不要只写「用 Node」。项目结构要提前规划目录代码放哪、组件怎么组织、工具函数放哪都写明白。不然 AI 生成的代码东一块西一块后期找 Bug 像大海捞针。数据模型是技术设计里最关键的部分。你要存哪些表、每个字段什么类型、表之间什么关系都要定义。我踩过的坑是没定义字段类型AI 把金额字段定义成字符串把日期字段定义成布尔值。后来我在技术设计里强制写字段类型这类问题就没了。下面是一个数据模型示例## 数据模型 ### users 表 | 字段 | 类型 | 约束 | 说明 | |------|------|------|------| | id | bigint | PK, auto | 用户 ID | | email | varchar(255) | unique, not null | 登录邮箱 | | password_hash | varchar(255) | not null | bcrypt 哈希 | | created_at | timestamp | default now() | 创建时间 | ### posts 表 | 字段 | 类型 | 约束 | 说明 | |------|------|------|------| | id | bigint | PK, auto | 文章 ID | | user_id | bigint | FK - users.id | 作者 | | title | varchar(200) | not null | 标题 | | content | text | not null | 正文 | | status | varchar(20) | default draft | draft/published |3.2 AGENTS.md 骨架让 AI 输出风格统一AGENTS.md 可以理解为给 AI 立的规矩。有了它AI 生成的代码就像同一个师傅教出来的风格统一、规范一致。这份文件放在项目根目录AI 工具在读取项目时会自动加载。骨架如下# AGENTS.md ## 项目背景 [一句话说明项目是什么指向 PRD.md 和 TECH_DESIGN.md] ## 技术栈 - 语言[如 TypeScript 5.x] - 框架[如 Next.js 14 App Router] - 数据库[如 PostgreSQL 15 Prisma] - 测试[如 Vitest] ## 代码规范 - 命名变量和函数用 camelCase类型和组件用 PascalCase常量用 UPPER_SNAKE_CASE - 缩进2 空格不用 Tab - 引号单引号JSX 属性用双引号 - 分号必须写 - 注释公共函数必须写 JSDoc复杂逻辑写行内注释 ## 目录约定 - src/app页面和路由 - src/components可复用组件 - src/lib工具函数和第三方封装 - src/types全局类型定义 - tests测试文件与被测文件同结构 ## 提交规范 - 格式type(scope): subject - type 取值feat / fix / docs / refactor / test / chore ## 禁止事项 - 禁止在组件里直接写 fetch统一走 src/lib/api.ts - 禁止使用 any必要时用 unknown 加类型守卫 - 禁止提交 console.log调试用 logger3.3 三份文档怎么配合使用PRD、TECH_DESIGN、AGENTS.md 不是孤立的。PRD 定义范围和验收标准TECH_DESIGN 定义实现路径和数据结构AGENTS.md 定义编码规矩。每次让 AI 写代码前你可以用一句话把三者串起来「请根据 PRD.md 的 3.1 功能、TECH_DESIGN.md 的 users 表结构、AGENTS.md 的代码规范实现用户注册接口。」这样 AI 的输入上下文是完整的输出质量会明显提升。如果你用的是支持项目级配置的 AI 编码工具可以把这三份文档的路径写进工具的配置文件里让它每次自动加载。下面是一个config.toml示例把模型调用统一走 TaoToken同时指定文档路径# config.toml [model] provider taotoken base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model_id claude-sonnet-4-20250514 [project] prd PRD.md tech_design TECH_DESIGN.md agents AGENTS.md [generation] temperature 0.3 max_tokens 8192这里base_url用https://taotoken.net/api不要加多余路径。model_id按你实际使用的模型填。temperature设低一点代码生成任务不需要太发散。配置好后AI 工具每次请求都会带上项目文档作为上下文生成结果会更贴合你的设计。4. 用 TaoToken 统一 Key 打通模型调用4.1 为什么需要统一 KeyVidocoding 流程里你可能会用到多个 AI 工具一个用来做需求分析一个用来写代码一个用来做代码审查。如果每个工具都单独配 Key管理起来很麻烦而且不同工具的计费和额度是分开的。用 TaoToken 统一 Key 的好处是一个 Key 走所有工具计费集中切换模型也方便。TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的接口大部分 AI 编码工具都能直接对接。4.2 获取 Key 并配置到项目第一步打开 TaoToken 控制台创建 API Key。地址是https://taotoken.net/console登录后在 API Keys 页面生成一个新 Key复制保存。注意 Key 只显示一次丢了要重新生成。第二步把 Key 写进项目配置。不要硬编码在代码里用环境变量。在项目根目录创建.env文件# .env TAOTOKEN_API_KEYsk-你的TaoToken密钥 TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELclaude-sonnet-4-20250514然后在.gitignore里加上.env避免 Key 被提交到仓库。如果你用的是 Node.js 项目可以用dotenv加载// src/lib/ai-client.js import OpenAI from openai; import dotenv/config; const client new OpenAI({ apiKey: process.env.TAOTOKEN_API_KEY, baseURL: process.env.TAOTOKEN_BASE_URL, }); export async function askAI(prompt) { const res await client.chat.completions.create({ model: process.env.TAOTOKEN_MODEL, messages: [{ role: user, content: prompt }], temperature: 0.3, }); return res.choices[0].message.content; }4.3 在 AI 编码工具里配置 TaoToken如果你用的是 Claude Code 这类命令行工具可以在项目里创建.claude/settings.json把模型请求指向 TaoToken{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Cline 这类 VS Code 插件在插件设置里找到 API Provider选 OpenAI CompatibleBase URL 填https://taotoken.net/apiAPI Key 填你的 TaoToken KeyModel ID 填claude-sonnet-4-20250514。保存后插件就会通过 TaoToken 调用模型。这里要提醒一点Base URL 只填到/api不要在后面加/v1或其他路径。有些工具会自动补全路径你多写了反而会 404。Model ID 要和你实际使用的模型一致写错了会报模型不存在。4.4 验证配置是否生效配置完成后用一条最简单的请求验证。在项目里跑curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 OK 两个字母}], max_tokens: 10 }如果返回的 JSON 里choices[0].message.content包含OK说明 Key 和 Base URL 都正确。如果返回 401检查 Key 是否复制完整如果返回 404检查 Base URL 是否多写了路径如果返回模型不存在检查 Model ID 拼写。这一步验证通过后再回到 AI 编码工具里测试能省很多排查时间。5. 从需求到代码的验证与常见报错排查5.1 一次完整的验证动作前面四步准备好后现在做一次从需求到代码的验证。假设 PRD 里有一个 P0 功能「用户注册」TECH_DESIGN 里定义了 users 表AGENTS.md 规定了代码规范。你可以这样给 AI 下指令请根据以下上下文实现用户注册功能 1. PRD.md 中 3.1 功能模块 A邮箱密码注册验收标准为邮箱格式校验、密码至少 8 位、重复邮箱返回 409 2. TECH_DESIGN.md 中 users 表结构 3. AGENTS.md 中代码规范TypeScript、camelCase、JSDoc 注释 输出要求 - 生成 src/app/api/register/route.ts - 生成 src/lib/validators.ts 中的邮箱和密码校验函数 - 生成对应的 Vitest 测试文件AI 返回代码后不要直接合并。先跑测试npm run test -- tests/register.test.ts测试通过后再手动验证接口curl -X POST http://localhost:3000/api/register \ -H Content-Type: application/json \ -d {email:testexample.com,password:12345678}预期返回 201 和用户 ID。再用同一个邮箱请求一次预期返回 409。如果两个都符合说明这个功能从需求到代码的链路是通的。接下来按同样方式做下一个 P0 功能每做完一个就验证一个不要攒着一起测。5.2 常见报错对照排查报错一401 Unauthorized{error:{message:Invalid API key,type:invalid_request_error}}原因通常是 Key 没配好。检查.env里的TAOTOKEN_API_KEY是否完整有没有多余空格。如果你用的是 Claude Code检查.claude/settings.json里的ANTHROPIC_API_KEY是否和 TaoToken 控制台生成的一致。还有一种情况是 Key 被撤销了去控制台重新生成一个。报错二local proxy failed / connection refusedError: connect ECONNREFUSED 127.0.0.1:8080这个报错说明工具在尝试走本地代理但代理没启动。检查你的环境变量里有没有HTTP_PROXY或HTTPS_PROXY如果有临时取消掉unset HTTP_PROXY unset HTTPS_PROXY然后重新请求。TaoToken 的 API 地址是直连的不需要额外代理配置。报错三reading choices 时 undefinedTypeError: Cannot read properties of undefined (reading choices)这个报错说明 API 返回的结构和你代码里解析的结构不一致。常见原因是 Base URL 写错了请求打到了别的端点返回的不是标准 OpenAI 格式。检查baseURL是否为https://taotoken.net/api不要加/v1。另外检查 Model ID 是否正确模型不存在时有些网关会返回非标准错误结构。报错四OAuth 相关错误Error: OAuth token expired如果你用的是 Claude Code 的 OAuth 登录方式而不是 API Key可能会遇到这个。解决办法是改用 API Key 方式在.claude/settings.json里配置ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL不要用 OAuth。TaoToken 走的是 API Key 鉴权不涉及 OAuth 流程。5.3 迭代阶段的注意事项核心功能跑通后进入迭代阶段。这时候不要一次性让 AI 重构整个项目而是按功能点逐个改。每次改之前先更新 PRD 或 TECH_DESIGN 里对应的描述再让 AI 按新描述改代码。改完跑测试测试通过再提交。提交信息按 AGENTS.md 里的规范写比如feat(auth): add password reset。如果 AI 生成的代码不符合 AGENTS.md 规范不要手动改而是把规范文件重新贴给它让它按规范重写。这样能保证规范始终生效。时间长了你会发现AI 的输出越来越稳定因为你的文档越来越完善上下文越来越清晰。这就是 Vidocoding 流程的复利效应前期投入的文档时间会在后期每次生成代码时省回来。6. 把流程固化成可复用的工作方式走到这里你已经有了 PRD 模板、TECH_DESIGN 结构、AGENTS.md 骨架以及 TaoToken 统一 Key 的配置方式。接下来要做的是把这套流程固化成习惯。我的做法是在项目根目录建一个docs/文件夹把三份文档放进去然后在 README 里写清楚每次开发前先读这三份文档。新项目直接复制这套结构改内容就行不用从零想。如果你经常做同类项目可以把 PRD 和 AGENTS.md 做成模板库按项目类型分类。比如 Web 应用一套、CLI 工具一套、数据处理脚本一套。下次开新项目选对应模板改改字段就能用。TaoToken 的 Key 可以跨项目复用配置一次所有项目共享。这样你的启动成本会越来越低。最后说一个实用技巧每次让 AI 生成代码前先让它复述一遍当前任务涉及的 PRD 条目、技术设计约束和 AGENTS.md 规范。如果复述正确再让它写代码如果复述有偏差先纠正理解再动手。这个习惯能挡掉大部分「AI 理解错需求」的问题。流程不是束缚是让 AI 的输出可控、可预期、可复用。把这套跑顺之后你会发现 Vidocoding 真正省下的不是打字时间而是返工时间。
设计模式)
