Claude Code 用到第二阶段，最容易卡在这八个问题

大家已经不太问「Claude Code 是什么」「MCP 怎么安装」这种入门题，更多是下面这种让人抓头发的问题，Skill 明明装了，为什么不触发；MCP 明明注册了，为什么 Claude Code 偏不用；代码图谱接上了，结果它照着旧地图改代码；PDF Token 省下来了，图表却答错了。

这才是 AI 编程真正开始进阶的信号。

047 那一辑，我回答的是「怎么把 Claude Code 用起来」。这一辑回答的是「已经用了，为什么还是不顺」。我把 061、062、066、067、071、072、073 几篇文章里反复出现的追问合并成 8 个问题，不假装逐字引用某一位读者，直接给结论和排障路径。

先看速查表。

1. Skill 装好了，为什么 Claude Code 完全不触发

这个问题最容易把锅甩给模型。

你在~/.claude/skills里放了一个文件夹，里面也有SKILL.md，然后对 Claude Code 说「帮我按这个 Skill 做」，它却像没听见一样。你再把 Skill 内容复制进对话，事情立刻又能跑起来。

这通常不是 Skill 内容不够长，而是三层链路只通了一层。

第一层是发现，Claude Code 能不能在当前会话的 Skill 搜索范围里看到它。第二层是路由，description有没有把「什么时候应该使用我」说清楚。第三层是执行，Skill 里面的路径、命令和工具是不是当前环境真的存在。

很多人只检查了第一层。看见目录在，就以为完成了安装。

一个能被正确路由的最小SKILL.md，至少要把触发场景写具体。

--- name: service-review description: Use when reviewing a backend service change, especially when the task touches database writes, retries, permissions, or idempotency. Do not use for simple formatting changes. --- # Service Review 先读取改动范围和相关测试，再按数据一致性、重试、权限、可观测性四项检查。

「帮我做代码审查」太宽了，模型不知道什么时候该选它。写成「检查后端服务的数据库写入、重试、权限和幂等性」就不一样了，触发条件、任务边界和不适用场景都有了。

排障顺序也别反过来。先在对话里显式调用一次，确认 Skill 本体能执行；再看description是否具体；最后才去怀疑模型能力。如果显式调用也失败，问题在路径或执行层，不在路由层。

Skill 不触发时，先查链路，不要先改 Prompt。

反例是把description写成一段产品宣传词，再在正文里塞 500 行流程。模型连「什么时候选我」都没看懂，后面写再多也只是躺在硬盘里的愿望。

2. Skill 放全局还是项目里，为什么越装越乱

061 那篇里有个问题我很认同，skills.sh的可编辑副本和 plugin 的只读订阅能不能混用。我的判断很简单，能混不是重点，同一个 Skill 到底谁是唯一真源才是重点。

我把 Skill 分三类。

个人习惯放全局，换项目也成立。项目规则放项目里，离开这个仓库就不该继续生效。团队能力要有版本管理，不能靠每个人电脑里一个手工复制的文件夹维持。

最危险的组合是，同名service-review同时出现在用户级目录、项目级目录和 plugin 里。你以为自己改的是这一份，Claude Code 实际读到的可能是另一份。等它表现异常时，排查半天，最后发现不是模型变了，是电脑里有三个「同事」抢着发言。

skills.sh适合你想改造内容、保留本地控制权的场景。plugin 适合你只想订阅、跟着上游更新的场景。两者选一个作为权威来源，另一个最多用于临时试验，试完就删掉。

这也是为什么我不建议把所有 Skill 都塞进全局目录。全局目录很方便，但它会把项目 A 的工作流带进项目 B。项目越来越多之后，Agent 不是更聪明，而是背着一只装满旧规则的口袋。

🗳️投票，你最常遇到哪种 Claude Code 卡点

• Skill 装了不触发
• MCP 注册了不调用
• Token 消耗压不住
• 能执行，但总是改错地方

3. CLAUDE.md、Skill、system prompt，到底该把什么放在哪里

这三个东西最容易被写成一锅粥。

我给它们各自安排一句话。

system prompt 管全局行为，CLAUDE.md 管项目事实，Skill 管可复用流程。

system prompt 更像驾驶规则，告诉 Agent 怎么使用工具、怎么拆任务、什么时候需要确认。它不应该塞进某个项目的数据库表名。CLAUDE.md更像项目入职手册，说明项目用什么技术栈、测试怎么跑、哪些目录不能碰。Skill 是操作手册，说明遇到某类任务时，应该按什么顺序完成检查、修改和验证。

举个后端项目的例子。

「不要在没有测试的情况下修改生产配置」是全局安全约束，适合放在 system prompt 或稳定的全局规则里。「这个项目用 Gradle，单测命令是./gradlew test，订单状态由OrderStateMachine管理」是项目事实，适合写进CLAUDE.md。「做数据库迁移时先生成方案，再检查回滚脚本，最后执行迁移测试」是工作流，适合做成 Skill。

把三类内容混在一起，会出现两种坏结果。项目事实被全局规则污染，换个仓库仍然带着旧表名。工作流被写进CLAUDE.md，每次对话都加载一遍，但你只是偶尔做数据库迁移，Token 和注意力都被白白占用。

Claude Code 四层上下文职责，system prompt、CLAUDE.md、Skill 和当前对话的分工

Claude Code 四层上下文职责，system prompt、CLAUDE.md、Skill 和当前对话的分工

判断放哪里，有个很实用的问题，你把这句话复制到另一个项目，还成立吗。成立，优先考虑全局规则。不成立，放项目上下文。只有做某类任务才需要，放 Skill。只对当前这一轮有效，直接写进当前对话。

规则不是越集中越好，职责清楚才是省 Token。

4.--append-system-prompt能不能当万能增强包

不能。

062 那篇拆过 system prompt 之后，很多人第一反应是，把所有「绝对不能错」的规则都追加进去。这个思路只对了一半。

--append-system-prompt适合给一轮任务加稳定的全局边界，比如本次会话只允许修改src/，禁止执行发布命令，任何删除动作必须先停下来确认。它不适合拿来替代项目文档、Skill 流程和测试。

如果你的 CLI 版本支持这个参数，可以先用帮助信息确认，再按会话启动。

复制

claude --help | grep -E -- '--(append-)?system-prompt' claude --append-system-prompt "$(cat .claude/guardrails.md)"

这里有两个坑。

第一个坑，--system-prompt和--append-system-prompt不是一回事。前者是替换默认系统提示词，后者是在默认提示词后追加。你只是想补一条边界，却把底层工具使用策略一起覆盖了，模型行为变得奇怪，不一定是它变笨了，可能是你把方向盘拆了。

第二个坑，把互相冲突的约束全塞进去。比如一边要求「先规划再修改」，一边又要求「收到任务后立即改文件」；一边要求「任何命令都要确认」，一边又想完全无人值守。模型最后只能在冲突里随机取舍。

我更建议只追加三类内容，安全边界、当前会话的权限范围、必须遵守的输出格式。项目知识写CLAUDE.md，复杂流程写 Skill，临时任务边界写当前 Prompt。

system prompt 是护栏，不是外挂。护栏越多，车不一定跑得越稳。

5. MCP 明明注册了，Claude Code 为什么就是不用

MCP 能启动，不代表 Claude Code 会调用它。

这是三个问题。

第一，服务器有没有真正启动。命令路径错、运行时版本不对、环境变量没有传进去，都会让它停在注册表里。第二，工具描述是否写清楚。工具名叫search，描述只写「搜索内容」，模型不知道什么时候该优先用它。第三，当前任务有没有给出调用理由。你让 Agent「分析项目」，它可能认为直接读文件就够了；你明确要求「先用代码图谱查询调用链，再打开命中的源文件」，路由结果就会不同。

我自己排 MCP，先把它拆成四个动作。

claude mcp list cat .mcp.json command -v node node --version

第一条看有没有注册，第二条看项目级配置，后两条看运行时。不同版本的 CLI 命令可能略有变化，最终以claude --help为准。不要一上来就重装 MCP，那是把未知问题换成更大的未知问题。

工具描述也要写「什么时候用」，不能只写「我能做什么」。比如sense_graph不要只写「查询代码图谱」，而要写「当任务涉及调用链、影响面、死代码或符号关系时，优先使用本工具；返回结果后仍需打开源文件和测试确认」。

这句「仍需回源确认」很关键。MCP 返回的是证据线索，不是最终答案。代码图谱、知识库、搜索服务都一样。

MCP 不调用的四步排障流程，从注册检查到任务路由

MCP 不调用的四步排障流程，从注册检查到任务路由

反例是给 Agent 接 20 个 MCP，然后期待它自动选得像一个经验丰富的架构师。工具越多，选择空间越大，描述越模糊，误路由越频繁。先接少量高价值工具，把描述和回归场景写清楚，再逐步增加。

6. 一套 Skill 能不能同时给 Claude Code、Codex 和 Cursor 用

能复用，但不能幻想「复制过去就完全一样」。

最适合复用的是 Skill 的知识和流程，比如审查清单、领域术语、验收步骤、示例输入输出。最不适合直接复用的是宿主绑定，工具名称、配置目录、权限语法、调用命令和子 Agent 机制。

我会把 Skill 拆成两层。

核心层只写任务方法，先收集什么信息，按哪些风险检查，什么条件算完成。适配层再写 Claude Code 的 MCP 名称、Codex 的调用方式、Cursor 的规则路径。核心层可以放在一个普通仓库里，适配层各自只有几十行。

071 那篇里两个 PPT Skill 的经验也是一样，支持多个 Agent，不等于所有 Agent 的运行体验一致。Claude Code 可能最顺手，Codex 可能更适合脚本化，Cursor 更靠近编辑器上下文。你真正要迁移的是能力边界，不是目录结构。

最常见的失败方式，是把 Claude Code 专用的CLAUDE.md、MCP 工具名和权限配置原封不动塞给另一个 Agent，然后得出「这个 Skill 不兼容」的结论。不是 Skill 不兼容，是适配层没有拆出来。

7. 代码图谱接上以后过期了，Agent 按旧地图改错怎么办

代码图谱最容易被误解成「代码真相」。其实它更像数据库索引。

索引快，但它永远有一个前提，索引和源数据同步。文件刚改完，图谱还没增量更新；分支切换了，索引仍然指向上一条分支；生成目录被扫描进去了，图谱里出现了根本不该参与分析的符号。这几种情况都会让 Agent 得到一个看起来很专业、其实已经过期的答案。

所以我给代码图谱定了三条规矩。

第一，先查更新时间和当前分支，再相信关系查询。第二，图谱只负责缩小范围，命中的文件必须回源读。第三，涉及写操作、数据库迁移和权限改动时，至少再看一遍测试和调用方，不能只凭图谱的影响面结论动手。

073 那篇实测里，sense 的工具调用从 19 次降到 10 次，Token 从 228K 降到 156K。这说明地图能减少 Agent 的盲翻，但不代表它可以替代源代码。省下来的调用次数，应该拿去做验证，不是拿去省略验证。

小项目也不要为了追热点强行上图谱。仓库只有几个模块，人工读目录比维护索引更快。真正值得接入的，是跨模块调用多、领域边界复杂、同名符号很多、Agent 经常反复翻源码的仓库。

代码图谱是导航，不是目的地。导航过期时，回到源代码才是最短路径。

8. PDF 检索省了 Token，为什么图表问题反而答错

这是 072 那篇最容易被忽略的边界。

Token Saver 这类方案用文本抽取、关键词检索和语义检索，把大 PDF 变成与问题最相关的几段文本。文字问题非常适合这条路径，章节编号、条款原文、定义、接口参数，都能少搬很多上下文。

但图表不是文字。

一张架构图里，箭头方向、颜色分组、节点位置可能比旁边的说明更重要。文本抽取只能拿到几个节点名称，拿不到「这个箭头从哪里指向哪里」。你让文本 RAG 回答图表，它只能根据残缺信息补全，答错不是偶然，是输入通道已经丢了视觉信息。

所以 PDF 问答要先分流。

072 里提到的 92% 到 99% 节省，是特定文档、特定问题和特定基准线下的结果，不是「所有 PDF 都能省 99%」。如果你的任务主要看图、看财报、看扫描版合同，优先保证信息完整，别为了一个漂亮的节省率把视觉通道关了。

省 Token 的前提，是没有省掉答案需要的证据。

一条命令，把四层排障先跑一遍

如果你不想每次靠记忆排查，可以在项目里放一个只读检查脚本。它不修改配置，只告诉你当前环境到底有哪些层。

#!/usr/bin/env bash set -u project_dir="$(pwd)" echo "project: ${project_dir}" for path in "${HOME}/.claude/skills" "${project_dir}/.claude/skills"; do if [ -d "${path}" ]; then echo "skill-dir: ${path}" find "${path}" -maxdepth 2 -name SKILL.md -print else echo "skill-dir-missing: ${path}" fi done for config in "${HOME}/.claude.json" "${project_dir}/.mcp.json" "${project_dir}/.claude/settings.json"; do if [ -f "${config}" ]; then echo "config: ${config}" else echo "config-missing: ${config}" fi done if command -v claude >/dev/null 2>&1; then echo "claude: $(claude --version 2>/dev/null || true)" claude mcp list 2>&1 || true else echo "claude: not-found" fi

保存成scripts/claude-code-doctor.sh后执行。

chmod +x scripts/claude-code-doctor.sh ./scripts/claude-code-doctor.sh

它不能判断 Skill 的 description 写得好不好，也不能替你决定工具该不该调用，但能先把「目录不存在」「配置文件不在」「CLI 不在 PATH」「MCP 列表为空」这些低级问题筛出来。脚本显示一切正常，Agent 仍然不触发时，再回到任务描述和工具 description 查路由。

常见问题

Q，Skill 是不是越多越好。

不是。Skill 的价值是减少重复决策，不是往上下文里堆目录。先保留与你当前项目和任务稳定相关的少数 Skill，能明确说出触发条件、输入和验收方式，再考虑增加。

Q，Skill 明确写了「必须调用 MCP」，为什么还是不用。

「必须」不是路由证据。把调用时机、工具能解决什么、调用后要怎么验证写进 tool description，并在任务里点名第一步先查什么。必要时先显式调用一次，确认工具链路通了，再测试自动路由。

Q，代码图谱能不能替代CLAUDE.md。

不能。图谱回答结构关系，CLAUDE.md说明项目约定。一个告诉 Agent 谁调用谁，一个告诉 Agent 哪些目录能改、测试怎么跑，职责不同。

Q，PDF 是不是都应该接 Token Saver。

不是。反复追问长文本时值得接，图表密集、扫描件为主或需要保留版式时，先用原生多模态。工具要按问题类型选，不要按标题里的节省率选。

Q，只有 Claude Code 才能用这些 Skill 吗。

不一定。只要另一个 Agent 支持相近的 Skill 文件规范，就能复用核心流程。但配置路径、工具名称、权限机制和调用习惯要做适配，不能把宿主专用配置整包复制。

我的判断

Claude Code 用到第二阶段，拼的已经不是「谁会背更多命令」，而是谁能把上下文、工具和验证拆成几层，各自只做该做的事。

Skill 不触发，先查路由；MCP 不调用，先查描述；代码图谱给出结论，回源确认；PDF 检索省下 Token，先确认有没有把图表证据一起省掉。把这四句话记住，很多看起来像模型抽风的问题，最后都会落回工程边界。

我不太相信「再装一个 Skill 就会变聪明」这类说法。真正稳定的 AI 编程工作流，通常不是工具越多越强，而是每个工具的职责越窄、证据链越完整。下篇我打算把.mcp.json的项目级和用户级配置、环境变量注入、团队共享模板单独拆出来，想看哪一块，评论区留个关键词。

公众号主页顺手点个星标，后面这类 Claude Code 排障文不容易在信息流里沉下去。身边有人正被 Skill 和 MCP 配置折磨，直接把这篇甩给他，比一句「你再试试」有用。

最后

我们整理出这套 AI 大模型 突围资料包：

✅ 从零到一的 AI 学习路径图
✅ 大模型调优实战手册（附医疗/金融等大厂真实案例）
✅ 百度/阿里专家闭门录播课
✅ 大模型当下最新行业报告
✅ 真实大厂面试真题
✅ 2025 最新岗位需求图谱

所有资料 ⚡️ ，朋友们如果有需要 《 AI大模型 入门+进阶学习资源包》，下方扫码获取~

资料展示

下面是我整理的AI大模型学习资料和工具包预览，适合收藏后按主题逐步学习。

需要这份AI大模型资料清单的话，在评论区回复「清单」即可；我会根据大家的问题继续补充对应的实战内容。