1. 从 CLAUDE.md 到 MCP一次真实终端工作流的起点Claude-Code 是 Anthropic 推出的命令行 AI 编程工具它跑在你的终端里能读仓库、改文件、跑命令、调工具。CLAUDE.md 是它的项目记忆文件MCP 是它接入外部工具的标准协议Agent SDK 则是把这套 agent loop 搬进你自己程序的方式。这三样东西串起来就是一套能落地的 CLI 工作流。适合谁适合每天在终端里写代码、又想让 AI 真正参与工程流程的人而不是只想在网页里问两句的人。我自己的场景很典型一个 TypeScript 后端仓库加一个 Python 数据处理脚本目录日常要在两个终端之间切。以前每次开新会话都要重新解释“用 pnpm 不用 npm”“测试命令是 vitest 不是 jest”“别动 migrations 目录”说三遍就烦。后来把规则写进 CLAUDE.md再用 MCP 接上本地文件系统和数据库查询工具最后用 Agent SDK 写了个自动审查脚本才算把重复劳动压下去。这篇记录按三条主线走CLAUDE.md 项目记忆怎么写、MCP 服务怎么注册、Agent SDK 怎么调一次完整任务。每一步都给可复制的配置和命令你可以在自己终端里跑通同一套流程。中间会穿插我踩过的坑比如 401、local proxy failed、reading choices 这些报错怎么定位。先说清楚一个前提Claude-Code 本身是 CLI 工具模型调用需要配置 Base URL 和 Key。我这边用的是 TaoToken 的接入方式官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。下面所有配置都基于这个地址你换成自己的也能对照着改。2. CLAUDE.md 项目记忆模板与 /init 实操让 Claude-Code 记住构建命令和代码约定CLAUDE.md 是 Claude-Code 在每次会话开始时自动读取的项目记忆文件。它放在仓库根目录内容会被注入上下文跨会话长期生效。你可以把它理解成“给 AI 看的 README”但比 README 更偏工程约定构建命令、测试命令、目录结构、命名规范、禁止事项。最省事的起点是/init。在仓库根目录启动 Claude-Code 后输入/init它会扫描目录、识别技术栈、生成一份 CLAUDE.md 草稿。我实测下来/init对 Node 和 Python 混合仓库识别得还行但生成的命令经常是npm test这种默认值需要你手动改成项目真实命令。下面是我现在用的模板你可以直接复制改# 项目说明 这是一个 TypeScript Python 混合仓库。主服务在 src/数据处理脚本在 scripts/。 ## 代码规范 - TypeScript 使用函数式风格避免 class - 组件文件 PascalCase工具函数 camelCase - Python 脚本统一用 ruff 格式化行宽 100 - 提交信息用 conventional commits ## 常用命令 - pnpm dev - 启动开发服务器 - pnpm build - 构建生产版本 - pnpm test - 运行 vitest 测试 - pnpm lint - 运行 eslint ruff - python scripts/etl.py --dry-run - 数据管道空跑 ## 目录结构 - src/api/ - HTTP 路由层 - src/core/ - 业务逻辑 - src/db/ - 数据库访问migrations 只读 - scripts/ - 一次性数据处理脚本 ## 禁止事项 - 不要修改 src/db/migrations/ 下的文件 - 不要引入新的 ORM现有用 drizzle - 不要用 npm统一 pnpm写完之后日常维护靠两条路。一是手动编辑二是用#前缀把对话里的关键信息写回 CLAUDE.md。比如你发现 Claude 又用了 npm直接输入# 把“统一使用 pnpm”写入 CLAUDE.md它会追加进去。这个#引用还支持#config.yaml这种文件引用能把某个配置文件的内容同步进记忆。这里有个坑CLAUDE.md 不是越长越好。我一开始把整个 API 文档贴进去结果每次会话上下文占用很高/context一看记忆文件占了一大块。后来只留命令、约定、禁止事项三类控制在 80 行以内效果反而更稳。你可以用/context随时看上下文占用发现记忆文件挤爆了就精简。另一个实用技巧是引用。需要 Claude 精准看某个模块时输入src/core/让它只聚焦这个目录避免全仓库乱搜。配合!前缀跑命令比如! git status结果直接注入上下文比让 Claude 先解释再执行快得多。3. MCP 服务注册示例在 settings.json 里接入本地工具MCP 是 Model Context Protocol简单说就是让 Claude-Code 通过标准协议调用外部工具。你可以接本地文件系统、数据库、浏览器、内部 API。注册方式是在配置文件里写 MCP server 定义Claude-Code 启动时拉起这些服务。配置文件位置分两级项目级.claude/settings.json全局~/.claude/settings.json。项目级只对当前仓库生效全局对所有项目生效。我建议工具类配置放全局项目专属的放项目级。下面是一个可复制的 JSON 片段接两个 MCP server一个文件系统一个 SQLite 查询{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/projects/myapp ] }, sqlite: { command: uvx, args: [ mcp-server-sqlite, --db-path, /Users/yourname/projects/myapp/data/local.db ] } } }注意路径要写绝对路径相对路径在不同启动目录下会失效。npx和uvx分别对应 Node 和 Python 生态的 MCP server你按自己环境选。如果你同时管理多个 API 配置和多个 CLI 工具可以看看 CC Switch 这个桌面应用https://github.com/farion1231/cc-switch 。它提供可视化界面管理供应商配置一键切换内置 50 供应商预设还有统一的 MCP 和 Skills 管理。底层用 SQLite 和原子写入避免手动编辑配置文件写坏。我试过在多个项目间切 Base URL用它比手改 settings.json 稳。MCP 注册完用/mcp命令可以查看已连接的服务和可用工具。如果服务没起来/mcp会显示连接失败这时候去看终端日志通常是命令路径不对或者依赖没装。这里必须写全三件套Base URL、Key、Model ID。以 Claude-Code 的配置为例环境变量方式export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key export ANTHROPIC_MODELclaude-sonnet-4-20250514Model ID 要和你实际可用的模型对齐写错了会报 model not found。Key 在 https://taotoken.net/api-keys 生成注意不要提交到 git。MCP 的一个常见误区是把它当成“直连生产库”的通道。不要这么干。MCP server 应该指向本地开发库或者只读副本生产库查询走单独的只读账号和审计。我见过有人把生产连接串写进 MCP 配置结果 Claude 一个查询把慢 SQL 打上去影响线上。安全边界要自己划。4. 验证请求与 Agent SDK 调用跑通一次完整任务配置写完先做一次最小验证。启动 Claude-Code输入一个简单请求claude -p 读取 CLAUDE.md告诉我这个项目的测试命令是什么-p是 headless 模式非交互执行结果输出到 stdout。如果返回了pnpm test说明 CLAUDE.md 被正确读取Base URL 和 Key 也通了。接着验证 MCP。输入claude -p 用 filesystem 工具列出 src/core 下的文件如果 MCP 接好了它会调用 filesystem server 返回文件列表。没接好会提示工具不可用。然后上 Agent SDK。Agent SDK 是把 Claude-Code 的 agent loop、工具权限、上下文管理搬进你自己程序的方式。下面是一个 Node 示例跑一次“读 diff 并生成审查意见”的任务import { query } from anthropic-ai/claude-agent-sdk; const result await query({ prompt: 读取当前 git diff找出潜在的空指针风险输出 Markdown 报告, options: { cwd: /Users/yourname/projects/myapp, allowedTools: [Read, Bash, Grep], permissionMode: plan } }); for await (const message of result) { if (message.type assistant) { process.stdout.write(message.content); } }permissionMode: plan对应计划模式先给方案不改文件。allowedTools限制它能用的工具避免误操作。跑之前确保ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY已设置。一次完整任务的验证动作可以这样设计让 Agent SDK 读git diff用 Grep 找相关调用点输出一份审查报告到review.md。整个过程不修改源码只读加写报告。跑通后你会看到流式输出最后文件生成。如果要做长期编码或 Agent 任务可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan 。它适合持续性的编码场景比按次调用更省心。验证模型本身是否正常可以用模型对话页面 https://taotoken.net/chat 快速测一句确认 Key 和模型没问题再回到 CLI。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来。你大概率会碰到下面几个。401 Unauthorized。最常见。原因三种Key 没设置、Key 写错、Base URL 和 Key 不匹配。先echo $ANTHROPIC_API_KEY看有没有值再确认ANTHROPIC_BASE_URL是https://taotoken.net/api而不是别的。如果 Key 是从别处复制的注意有没有多余空格或换行。401 还会在 Key 过期时出现去 https://taotoken.net/api-keys 重新生成一个。local proxy failed。这个通常出现在你本地配了代理但代理没起来或者环境变量HTTP_PROXY/HTTPS_PROXY指向了一个不可用的地址。检查env | grep -i proxy把不需要的代理变量清掉。如果你在公司网络里确认网络策略允许访问 API 地址。reading choices 报错。这个多出现在响应解析阶段通常是返回体不是预期的 JSON 结构。原因可能是 Base URL 写成了带路径的地址比如多加了/v1导致请求打到了错误端点。确认 Base URL 就是https://taotoken.net/api不要自己拼路径。另一个原因是 Model ID 写错服务端返回了错误结构。OAuth 相关报错。Claude-Code 某些版本会走 OAuth 流程如果你用的是 API Key 方式确保没有残留的 OAuth token 干扰。检查~/.claude/下的凭证文件必要时清掉重新用 Key 登录。OAuth 报错信息里一般会带invalid_grant或token expired按提示重新授权或改用 Key。MCP server 启动失败。/mcp显示红色。先手动跑一遍配置里的 command比如npx -y modelcontextprotocol/server-filesystem /path看报什么错。常见是路径不存在、依赖没装、Node 版本太低。修好手动命令再回 Claude-Code 里试。上下文被挤爆导致模型健忘。用/context看占用如果记忆文件或历史对话占太多用/compact压缩或者/clear清空重来。CLAUDE.md 精简到 80 行以内能明显缓解。排查顺序建议先确认 Key 和 Base URL再确认 Model ID然后看 MCP 配置最后看上下文。大部分问题在前两步就能定位。6. 把工作流固定下来自定义命令、Hooks 与日常习惯配置跑通只是开始要让它变成日常得把重复动作固化。Claude-Code 支持自定义命令把常用提示词模板化。在.claude/commands/下放 Markdown 文件比如review.md读取当前 git diff按以下维度审查 1. 空指针和边界条件 2. 错误处理是否完整 3. 是否有硬编码密钥 输出 Markdown 报告到 review.md之后输入/review就能触发。团队共享的话把这个目录提交到仓库所有人复用同一套提示词。Hooks 用来在工具调用前后触发脚本做自动化守卫。比如在.claude/settings.json里配一个 PreToolUse hook拦截rm -rf这类危险命令{ hooks: { PreToolUse: [ { matcher: Bash, command: python .claude/hooks/guard.py } ] } }guard.py读 stdin 的命令内容发现危险模式就返回非零退出码Claude-Code 会阻止执行。这样你既享受自动化又有一道防线。日常习惯上我固定几条项目开始跑/init维护 CLAUDE.md复杂任务先切 Plan ModeShiftTab看方案方向不对连按两次Esc回退对话变长用/compact改完代码跑测试。CtrlR搜历史提示词CtrlS暂存没写完的提示词这两个在终端里很实用。最后说一个我踩过的坑不要用--dangerously-skip-permissions在日常仓库里跑。它跳过权限确认速度快但风险高。只在隔离容器或短生命周期环境里用。日常开发老老实实保留确认或者用 Plan Mode 先看方案。整套流程跑下来CLAUDE.md 管记忆MCP 管工具Agent SDK 管自动化三者各司其职。你不需要一次全上先把 CLAUDE.md 写好再加一个 MCP server最后用 SDK 包一层逐步推进比一次性配齐更稳。