一个独立开发者，用一份 markdown 驱动 Claude Code，20 天跑通 9 个包的 monorepo 工程：TaoToken 统一 Key 接入实录

1. 独立开发者用 markdown 驱动 Claude Code 跑 monorepo 的真实困境一个独立开发者用一份 markdown 驱动 Claude Code20 天跑通 9 个包的 monorepo 工程这件事听起来像标题党但拆开看每一步都是可复制的工程动作。核心检索词先摆出来markdown 是唯一事实源Claude Code 是执行器monorepo 是交付形态SDDSpec-Driven Development规范驱动开发是把三者粘起来的方法论。适合谁适合一个人维护多包仓库、被 AI 上下文遗忘折磨过、想让 AI 写代码但不敢让它乱写的人。我踩过的坑很典型早上和 AI 敲定了一个包依赖方向下午新开会话改 bugAI 完全不记得早上的决策反手给你加了一个反向依赖构建直接循环。这不是模型不行是工作流没有沉淀。独立开发者用 AI 写代码死法基本就两种——上下文遗忘和决策无沉淀。9 个包的 monorepo 把这两个问题放大 9 倍因为包与包之间的依赖图、构建顺序、发布边界任何一处漂移都会在 CI 里炸出来。所以这篇不讲虚的直接给可复制的CLAUDE.md、spec 目录结构、TaoToken 统一 Key 的 Base URL 配置片段以及逐包验证构建与依赖图的检查动作。目标是把 20 天的节奏拆成一个你能直接套用的工程模板。你不需要 9 个包3 个包也能用同一套骨架。先说清楚 monorepo 的包划分后面所有配置都围绕它。我用的是 pnpm workspace9 个包分成三层底层 3 个纯 TS 工具包app/core、app/schema、app/utils中间 3 个领域包app/design、app/render、app/agent顶层 3 个交付包app/cli、app/desktop、app/mcp。依赖方向严格单向交付层依赖领域层领域层依赖工具层禁止反向。这条规则不写进 markdownAI 三天就能给你破坏掉。SDD 在这里的定义很具体把每个工程决策——WHY、WHAT、HOW、验收标准、边界条件、约束——写成结构化 markdown作为 AI 写代码的唯一真理来源。给人看的规范可以模糊给 AI 看的规范必须可执行、可验证、可追溯否则 AI 会用幻觉填满你留的空白。验收标准必须写成 Given/When/Then不能写系统正常工作因为 AI 看到模糊标准会自动脑补一段它觉得应该正常的代码。20 天的节奏大致是第 1-2 天搭骨架和写CLAUDE.md第 3-6 天跑底层 3 个包第 7-12 天跑领域 3 个包第 13-17 天跑交付 3 个包第 18-20 天做依赖图校验和发布闭环。每个包都走同一套 Phase A→D 流程下面会展开。2. TaoToken 统一 Key 接入 Claude Code 的前置准备Claude Code 默认走 Anthropic 官方端点但独立开发者经常需要在多个模型之间切换或者团队里多人共用一套额度。TaoToken 在这里的角色是统一 Key 网关一个 Base URL、一个 Key背后可以路由到不同模型。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 这个不加 UTM。前置准备分三件事拿到 Key、确认 Base URL、把 Model ID 对齐。这三件套缺一不可后面所有配置片段都围绕它们。第一步去控制台创建 API Key。入口是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 登录后在 API Keys 页面新建一个 Key复制出来形如sk-xxxxxxxx。这个 Key 只显示一次丢了就重建。如果你要长期跑 coding agent建议单独建一个 Key 专门给 Claude Code 用方便按项目隔离额度。第二步确认 Base URL。Claude Code 走的是 Anthropic 兼容协议所以 Base URL 填https://taotoken.net/api不要带末尾斜杠。注意这里和官网首页是两个地址配置里只写 API 端点。第三步确认 Model ID。在模型对话页面可以先试跑一下入口是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 选一个你打算长期用的模型把它的 Model ID 记下来。Claude Code 的配置里 Model ID 必须和网关支持的名称完全一致写错会直接 404 或者reading choices报错。如果你用的是 Claude Code 的 coding plan 模式入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 这里可以看套餐和额度说明。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到协议细节先翻文档。这里要强调一个原则TaoToken 是统一 Key 网关不是编辑器替代品也不是灰色中转。它的作用是让你在 Claude Code、Cline、Codex 这些工具之间共用一套凭证和额度减少多工具切换时的配置成本。所有配置都走官方 API 端点不涉及任何网络层的东西。前置准备做完你应该手上有三样东西一个sk-开头的 Key、https://taotoken.net/api这个 Base URL、一个确认可用的 Model ID。下面进入可复制配置。3. 可复制的 CLAUDE.md 与 TaoToken Base URL 配置片段这一节是全文最硬的部分所有片段都能直接抄。先给 Claude Code 的环境变量配置再给CLAUDE.md骨架最后给 spec 目录结构。Claude Code 读取配置的方式有两种环境变量和 settings 文件。环境变量最直接在 shell 里 export 即可export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key export ANTHROPIC_MODEL你的ModelID如果你不想每次开终端都 export写进~/.claude/settings.json。这个文件是 Claude Code 的全局配置路径和原文一致{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: 你的ModelID } }注意 JSON 里不能有注释Key 和 Model ID 都要替换成你自己的。Base URL 末尾不要加斜杠加了会拼出//v1/messages这种路径部分网关会 404。接下来是CLAUDE.md放在 monorepo 根目录。这份文件是 Claude Code 每次启动都会读的项目级指令相当于给 AI 的项目宪法。骨架如下# 项目宪法 ## 唯一事实源 - 任务进度PROGRESS.md - 任务规范specs/feature.md - 跨任务经验MEMORY.md memory/category/*.md - 冲突时以 specs/ 为准代码不是真理来源。 ## 包结构pnpm workspace - packages/core, packages/schema, packages/utils工具层 - packages/design, packages/render, packages/agent领域层 - packages/cli, packages/desktop, packages/mcp交付层 ## 依赖方向硬约束 - 交付层 - 领域层 - 工具层禁止反向。 - 新增跨层依赖前必须先更新 specs/ 并说明理由。 ## 禁止依赖 - LangChain / LangGraph - Electron - Jest统一用 vitest - Vercel AI SDK - Ink CLI ## 执行流程Phase A-D禁止跳步 - Phase A读 PROGRESS.md 找下一个 [ ] 任务读对应 spec扫 MEMORY.md 最近 20 条。 - Phase BPROGRESS 置 []按 spec 实现spec 有缺陷先改 spec。 - Phase C输出需求驱动的验证清单PROGRESS 置 [⏸]停下等人工测试。 - Phase D人工回复测试通过后三向同步PROGRESS/spec/memory。 ## 验收标准写法 - 必须 Given/When/Then禁止系统正常工作这类模糊描述。这份CLAUDE.md的关键在禁止依赖和依赖方向两段。AI 默认会抓最热门的方案你不写死边界它就会反复给你引荐 LangChain。每一条禁止项背后都是踩过的坑不是拍脑袋。spec 目录结构长这样specs/ sprint-01-core.md sprint-02-schema.md sprint-03-utils.md sprint-04-design.md ... memory/ decisions/ pitfalls/ conventions/ PROGRESS.md MEMORY.md CLAUDE.md每个 spec 文件用统一模板节选## 目标WHY 一句话解决什么问题对谁有价值。 ## 功能描述WHAT ### 用户故事 - 作为 [角色]我想 [操作]以便 [价值]。 ### 验收标准Given/When/Then - Given: [前置] / When: [操作] / Then: [预期结果] ### 边界条件 - [条件][处理方式] ## 技术方案HOW ### 文件变更计划 | 操作 | 路径 | 说明 | | --- | --- | --- | ## 任务分解TASKS - [ ] T-1.1 ...PROGRESS.md只写状态不写实现细节## Sprint 01 - core - [x] T-1.1 初始化包结构 - [] T-1.2 实现核心类型 - [ ] T-1.3 单元测试MEMORY.md是索引详情放memory/category/*.md。每个任务结束时 AI 必须问自己这次有没有新决策/新坑/新约定有就 draft 进去。这条强制动作是整个方法论里杠杆最高的一条它把经验沉淀从靠自觉变成流程必经。如果你用 Cline 或者 Codex配置逻辑一样只是文件位置不同。Cline 的 MCP 配置里同样要写全三件套Base URL、Key、Model ID。Codex 的auth.json也是这三个字段。CC Switch 这类工具切换配置时确保三件套一起切只切 Key 不切 Base URL 是最常见的翻车点。4. 逐包验证构建与依赖图的检查动作配置写完不算完9 个包的 monorepo 必须逐包验证否则依赖图漂移你根本发现不了。这一节给具体命令和检查动作。先验证 Claude Code 能不能正常请求。最直接的方式是跑一次模型对话入口 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 确认 Key 和 Model ID 可用。然后在项目里让 Claude Code 执行一个只读任务比如读 PROGRESS.md 告诉我下一个待办任务如果它能正确读取并回答说明 Base URL 和 Key 都通了。接着逐包构建。pnpm workspace 下用过滤命令pnpm -r --filter app/core build pnpm -r --filter app/schema build pnpm -r --filter app/utils build底层三个包必须先过因为它们被上层依赖。构建失败先看 TypeScript 报错再看包之间的类型引用路径。monorepo 里最常见的构建错误是Cannot find module app/core原因是tsconfig.json的 paths 没配或者 package.json 的 exports 字段缺失。依赖图检查用pnpm why和madgepnpm why app/core npx madge --circular packages/madge --circular会扫出循环依赖。9 个包的仓库里循环依赖一旦出现构建顺序就乱了。我实测下来最容易出循环的地方是领域层和交付层之间——AI 为了让某个功能跑通会偷偷让app/agent反向引用app/cli里的工具函数。发现循环后不要直接删代码先回到 spec 看依赖方向定义改 spec 再改代码。逐包验证的检查清单检查项命令通过标准单包构建pnpm --filter pkg build无 TS 报错全量构建pnpm -r build9 个包全绿循环依赖npx madge --circular packages/无输出类型检查pnpm -r typecheck无 error单元测试pnpm -r test全通过每个包构建通过后让 Claude Code 走 Phase C输出需求驱动的验证清单。注意是需求驱动不是读实现反推。AI 写完代码后如果让它自己写测试它会读自己的实现然后写出这段代码确实按它写的方式运行的测试听起来对实际没用。正确姿势是闭眼想用户拿到这个功能会怎么用、会踩哪些边界、错误怎么恢复先列清单再对照实现查漏。Phase D 的三向同步必须人工触发。AI 不能自己宣布任务完成必须你手动测试通过、回复测试通过四个字才进入同步。这条规则把人在环中从口号变成流程红线。9 个包 20 天能跑通靠的就是这条红线——每个包交付前都有人工验证卡点不会出现AI 说完成了但其实没验证的情况。依赖图还有一个隐性检查发布边界。9 个包里哪些要发 npm、哪些是内部包必须在 spec 里写清楚。内部包的package.json加private: true防止误发布。发布前用pnpm publish --dry-run预演一遍确认产物和依赖声明都对。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth配置和验证过程中会撞到几类固定报错逐个拆。401 Unauthorized。最常见原因是 Key 没生效或者 Base URL 写错。先检查ANTHROPIC_API_KEY是不是sk-开头且没有多余空格再检查ANTHROPIC_BASE_URL是不是https://taotoken.net/api且末尾无斜杠。如果环境变量和 settings.json 同时存在环境变量优先级更高可能你改了 settings 但环境变量还是旧的。用echo $ANTHROPIC_BASE_URL确认实际生效值。还有一种情况是 Key 被删了或者额度耗尽去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 重新建一个。local proxy failed。这个报错通常出现在工具尝试走本地代理但代理没起来的时候。检查你的 shell 里有没有残留的HTTP_PROXY/HTTPS_PROXY环境变量有就 unset 掉。Claude Code 直连 API 端点即可不需要任何本地代理层。如果你装了 CC Switch 之类的配置切换工具确认它没有注入额外的代理配置。reading choices 报错。这个一般出现在响应体解析阶段根因是 Model ID 写错或者网关返回了非预期格式。先确认ANTHROPIC_MODEL和网关支持的模型名完全一致大小写敏感。如果 Model ID 对但还是报错去模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 用同一个 Key 试跑能跑通说明是 Claude Code 侧配置问题跑不通说明是 Key 或模型权限问题。OAuth 相关报错。Claude Code 某些版本会尝试 OAuth 流程如果你用的是 API Key 模式需要在配置里明确禁用 OAuth。检查 settings.json 里有没有冲突的认证字段只保留ANTHROPIC_API_KEY。如果工具提示你登录 Anthropic 账号说明它没读到你的 API Key 配置回到上一节确认三件套是否写全。排查顺序建议固定成先echo三个环境变量确认值再用 curl 直接打 API 端点确认 Key 有效最后才怀疑工具配置。curl 验证命令curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:你的ModelID,max_tokens:16,messages:[{role:user,content:ping}]}返回正常 JSON 说明网关侧没问题报错就往工具配置查。这个二分法能省掉大量瞎猜时间。还有一个 monorepo 特有的报错Cannot find module在单包构建时出现但全量构建正常。原因是单包构建时 workspace 依赖没被 link先跑一次pnpm install再单独构建。如果还不行检查该包的tsconfig.json有没有继承根配置的 paths。6. 把 20 天节奏固化成可复用模板回到最初的问题独立开发者用一份 markdown 驱动 Claude Code 跑通 9 包 monorepo可复用的到底是什么。不是那 9 个包的具体代码而是三样东西——CLAUDE.md里的硬约束、spec 目录的三源同步结构、Phase A→D 的执行流程。这三样换任何项目都能套。具体动作把本文第 3 节的CLAUDE.md骨架抄进你的仓库根目录把禁止依赖清单换成你自己踩过的坑把包结构换成你的实际分层。然后建specs/、memory/、PROGRESS.md、MEMORY.md四个位置第一个 sprint 只做一个包跑通 Phase A→D 全流程再铺开。20 天跑 9 个包的前提是流程已经顺了不是一上来就并行。长期跑 coding agent 的话Coding Plan 入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以看额度方案。接入细节翻文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。验证模型先用模型对话 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后一个实操技巧每个 sprint 结束时让 Claude Code 把MEMORY.md的最近 20 条索引重新整理一遍去重、合并同类项。这个动作花不了几分钟但能让下一个 sprint 的上下文加载保持在几千 token 以内不会被历史决策挤爆。9 个包跑下来MEMORY.md索引始终控制在 20 条滚动窗口这是 20 天节奏不崩的关键。