1. 独立开发者用 markdown 驱动 Claude Code 跑 monorepo 的真实困境
一个独立开发者，用一份 markdown 驱动 Claude Code，20 天跑通 9 个包的 monorepo 工程，这件事听起来像标题党，但拆开看每一步都是可复制的工程动作。核心检索词先摆出来：markdown 是唯一事实源，Claude Code 是执行器，monorepo 是交付形态，SDD（Spec-Driven Development，规范驱动开发）是把三者粘起来的方法论。适合谁？适合一个人维护多包仓库、被 AI 上下文遗忘折磨过、想让 AI 写代码但不敢让它乱写的人。
我踩过的坑很典型：早上和 AI 敲定了一个包依赖方向，下午新开会话改 bug，AI 完全不记得早上的决策，反手给你加了一个反向依赖，构建直接循环。这不是模型不行，是工作流没有沉淀。独立开发者用 AI 写代码，死法基本就两种——上下文遗忘和决策无沉淀。9 个包的 monorepo 把这两个问题放大 9 倍，因为包与包之间的依赖图、构建顺序、发布边界，任何一处漂移都会在 CI 里炸出来。
所以这篇不讲虚的，直接给可复制的CLAUDE.md、spec 目录结构、TaoToken 统一 Key 的 Base URL 配置片段，以及逐包验证构建与依赖图的检查动作。目标是把 20 天的节奏拆成一个你能直接套用的工程模板。你不需要 9 个包，3 个包也能用同一套骨架。
先说清楚 monorepo 的包划分，后面所有配置都围绕它。我用的是 pnpm workspace，9 个包分成三层：底层 3 个纯 TS 工具包（@app/core、@app/schema、@app/utils），中间 3 个领域包（@app/design、@app/render、@app/agent），顶层 3 个交付包（@app/cli、@app/desktop、@app/mcp）。依赖方向严格单向：交付层依赖领域层，领域层依赖工具层，禁止反向。这条规则不写进 markdown，AI 三天就能给你破坏掉。
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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api （这个不加 UTM）。
前置准备分三件事：拿到 Key、确认 Base URL、把 Model ID 对齐。这三件套缺一不可，后面所有配置片段都围绕它们。
第一步，去控制台创建 API Key。入口是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，选一个你打算长期用的模型，把它的 Model ID 记下来。Claude Code 的配置里 Model ID 必须和网关支持的名称完全一致，写错会直接 404 或者reading choices报错。
如果你用的是 Claude Code 的 coding plan 模式，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，这里可以看套餐和额度说明。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的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 B：PROGRESS 置 []，按 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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和madge：
pnpm why @app/core npx madge --circular packages/madge --circular会扫出循环依赖。9 个包的仓库里，循环依赖一旦出现，构建顺序就乱了。我实测下来，最容易出循环的地方是领域层和交付层之间——AI 为了让某个功能跑通，会偷偷让@app/agent反向引用@app/cli里的工具函数。发现循环后不要直接删代码，先回到 spec 看依赖方向定义，改 spec 再改代码。
逐包验证的检查清单：
| 检查项 | 命令 | 通过标准 |
|---|---|---|
| 单包构建 | pnpm --filter <pkg> build | 无 TS 报错 |
| 全量构建 | pnpm -r build | 9 个包全绿 |
| 循环依赖 | 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，可以看额度方案。接入细节翻文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。Key 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。验证模型先用模型对话 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
最后一个实操技巧：每个 sprint 结束时，让 Claude Code 把MEMORY.md的最近 20 条索引重新整理一遍，去重、合并同类项。这个动作花不了几分钟，但能让下一个 sprint 的上下文加载保持在几千 token 以内，不会被历史决策挤爆。9 个包跑下来，MEMORY.md索引始终控制在 20 条滚动窗口，这是 20 天节奏不崩的关键。
