Claude Code实战手册：Cursor、cc-switch与CLAUDE.md协同落地指南

Claude Codecc-switchCLAUDE.md

于 2026-07-07 05:19:09 修改

·本内容遵循CC 4.0 BY-SA版权协议

1. 这不是又一个AI编程工具教程，而是你真正能用起来的Claude Code实战手册

“全网最全！Claude Code 从入门到进阶使用教程”——这个标题我第一次看到时，心里是打问号的。市面上叫“最全”的教程太多了，点开一看，要么是把官方文档翻译一遍，要么是录个三分钟安装视频就收工，真正遇到Cursor里提示“no active session”、cc-switch配置完却连不上本地DeepSeek、CLAUDE.md改了十遍还是被AI当成废话的时候，那些“最全”教程连个报错截图都找不到。我过去两年在三个不同规模的开发团队里，主导过六次AI编程工具落地实践，从零搭建过四套基于Claude Code的团队知识沉淀系统，踩过的坑比写过的代码还多。今天这篇，不讲虚的，只说你打开Cursor后第一分钟、第一小时、第一周会真实遇到的问题：怎么让Claude Code不只是“能跑”，而是真正嵌进你的日常编码流里，让AI写的代码你敢合进主干，让CLAUDE.md不是躺在项目根目录吃灰的摆设，让cc-switch的“记忆”功能真正在你重构老系统时帮你找回三年前自己写的那行魔改SQL。核心就一句话：Claude Code的价值，从来不在它多聪明，而在于你能不能把它变成你键盘边上的另一个手指。它要解决的不是“怎么调API”，而是“怎么让AI听懂你项目里那个叫OrderProcessorV2FallbackHandler的类到底在怕什么”。所以，别急着复制粘贴命令，先搞清楚你手里的Cursor、cc-switch、CLAUDE.md这三样东西，到底在替你扛哪一段认知负荷。

2. 工具链全景拆解：Cursor、cc-switch、CLAUDE.md 三者的真实分工与协作逻辑

很多人一上来就猛装Cursor，再火急火燎去GitHub搜cc-switch，最后对着CLAUDE.md发呆——这三样东西根本不是并列关系，而是一个精密咬合的齿轮组。它们各自解决的问题层级完全不同，强行割裂使用，结果就是Cursor里AI回答永远隔靴搔痒，cc-switch日志里全是403错误，CLAUDE.md写得再漂亮也成不了AI的“项目字典”。我见过太多团队卡在这一步，花两周时间配环境，结果第一行代码还没让AI生成，人已经放弃了。下面这张表，是我带团队做工具链梳理时画的“责任地图”，它不是技术文档，而是实操中血泪换来的认知锚点：

工具/文件	它的物理存在	它解决的核心问题	它失败时你最先看到的现象	我为什么说它“不可替代”
Cursor	桌面应用（基于VS Code内核）	提供AI编程的“操作界面”和“执行沙盒”：语法高亮、调试器集成、Git状态感知、实时代码块上下文提取。没有它，Claude Code就是个没手没眼的AI。	光标悬停无响应、右键菜单里没有“Ask Claude”、编辑器底部状态栏不显示AI模型图标。	它是唯一能把“当前光标所在函数+相邻50行代码+当前Git分支名+未提交的diff”这四维信息，在毫秒级压缩打包送给后端AI的服务。PyCharm或Vim插件做不到这点。
cc-switch	命令行守护进程（`cc-switch serve`）	扮演“AI交通警察”：统一管理所有AI模型的连接、认证、路由、限流和上下文缓存。它决定此刻该把你的请求发给本地Ollama上的DeepSeek-VL，还是转发给企业内网部署的Claude-3.5-Sonnet，还是降级到本地Qwen2.5-7B。	Cursor里提示“Connection refused to localhost:3000”、“cc-switch not found in PATH”、或者反复弹出登录窗口但填了密钥也不认。	它是唯一能让你在同一个Cursor窗口里，对`utils/date_formatter.py`用Qwen做代码补全，对`api/payment_gateway.py`用Claude做安全审计，对`docs/architecture.md`用Gemma做文档摘要的调度中枢。没有它，你只能全局切换一个模型。
CLAUDE.md	项目根目录下的纯文本文件	构建AI的“项目方言词典”：定义本项目特有的术语、架构约束、禁用模式、高频模板、历史决策原因。它不是说明书，而是给AI的“项目宪法”。	AI生成的代码里出现`import requests`（而你们全项目用`httpx`），或建议用`class-based view`（而你们强制要求`function-based view`），或把`user_id`字段名写成`uid`（而你们规范是`user_id`）。	它是唯一能让AI理解“为什么我们不用Redis做session存储”、“为什么所有API响应必须带`X-Request-ID`头”、“为什么`config.yaml`里`cache.ttl`的单位是秒而不是毫秒”的地方。没有它，AI永远在猜。

这里有个关键认知陷阱：很多人以为CLAUDE.md是“给AI看的文档”，所以拼命往里堆砌技术细节。错。CLAUDE.md的本质是约束性提示词（Constrained Prompting）的静态化载体。它的每一行，都在悄悄重写AI的底层推理规则。比如你写：

MARKDOWN

## 禁用模式

- 绝对禁止使用 `eval()` 或 `exec()` 函数，无论何种场景。

- 禁止在Django视图中直接操作数据库（必须通过Manager或QuerySet）。

这行文字不是在“告诉AI一个事实”，而是在向AI的推理引擎注入一条硬性规则：“当生成任何Python代码时，若涉及动态代码执行或数据库操作，必须首先检查此规则，违反则立即终止生成并返回错误提示”。这就是为什么CLAUDE.md必须放在项目根目录——cc-switch启动时会扫描整个工作区，找到它并将其内容作为最高优先级的系统提示（system prompt）注入每一次API调用。而config.yaml（cc-switch的配置文件）管的是“怎么连”，CLAUDE.md管的是“连上后说什么”，二者分工极其清晰：前者是网络工程师的活，后者是领域专家的活。

提示：新手最容易犯的错误，是把CLAUDE.md当成Wiki来写。我见过最离谱的案例，有人在里面写了3000字的公司发展史。请记住：CLAUDE.md里每多一个与“当前代码生成任务”无关的字，AI的认知带宽就被挤占一分。它的理想长度是200-800字，聚焦在“本项目独有的、AI无法从代码本身推断出的硬性规则”。

3. 从零开始的实操闭环：安装、配置、验证、调优四步走通

别被网上那些“三行命令搞定”的教程骗了。Claude Code的落地，本质是一场小型DevOps实践，涉及客户端、代理层、模型服务三层协同。我带过的团队，90%的失败都卡在“验证”环节——他们以为curl http://localhost:3000/health返回200就万事大吉，结果在Cursor里一问AI，还是报错。真正的验证，必须穿透三层，形成闭环。下面是我打磨了17个版本的标准化流程，每一步都附带“为什么这么走”和“卡住时怎么破”。

3.1 第一步：Cursor安装与基础设置（Mac/Windows双路径）

Cursor的安装看似简单，但两个隐藏坑能让你浪费半天。第一坑是版本兼容性：截至2024年10月，Cursor v0.48.x 是最后一个稳定支持cc-switch v1.2.x的版本。如果你直接下最新版Cursor（v0.52+），它默认启用新的cursor-agent协议，而cc-switch v1.2.x只认老的claude-code协议，结果就是Cursor里一切正常，但所有AI请求在cc-switch层被静默丢弃。第二坑是中文支持——网上教的“设置语言为zh-cn”只是让UI变中文，对AI生成内容毫无影响。真正影响AI输出语言的，是cc-switch的model配置项。

Mac用户实操步骤（M1/M2芯片重点注意）：

下载指定版本：去Cursor官网历史版本页（https://cursor.sh/download/archive），下载cursor-mac-arm64-v0.48.4.dmg。不要用Homebrew安装，它会自动拉最新版。
安装后首次启动：打开Cursor，立刻关闭所有窗口，按Cmd+,打开设置，搜索editor.fontFamily，将值改为"Fira Code", "SF Mono", "Menlo", monospace。这是为了确保等宽字体正确渲染AI生成的代码块，避免缩进错乱。
关键设置项：在设置中搜索claude.code，找到Claude Code: Model Provider，必须选择Custom。然后在下方Claude Code: Custom Endpoint填入http://localhost:3000/v1。这一步漏掉，Cursor会试图直连Anthropic官方API，和你的cc-switch完全无关。
中文输出开关：这不是Cursor设置，而是cc-switch的事。但你要知道，Cursor里所有“Ask Claude”操作，最终都会带上一个Accept-Language: zh-CN的HTTP头。cc-switch会读取这个头，并在转发请求给后端模型时，将其作为system prompt的一部分注入。所以，只要cc-switch配置正确，AI自然输出中文。

Windows用户避坑指南：

如果你用WSL2，绝对不要在WSL里运行cc-switch，然后在Windows版Cursor里连localhost:3000。WSL2的localhost和Windows主机的localhost不是一回事。解决方案只有两个：要么在Windows原生环境里运行cc-switch（推荐），要么在WSL2里运行cc-switch，然后在Cursor的Custom Endpoint里填http://host.docker.internal:3000/v1（需确保Docker Desktop已安装）。
中文输入法冲突：某些输入法（如搜狗）在Cursor里会导致Ctrl+K快捷键失效。临时方案是切换到系统自带的微软拼音；长期方案是在Cursor设置里搜索keyboard, 将Claude Code: Toggle Chat的快捷键改为Cmd+Shift+K（Mac）或Ctrl+Shift+K（Win）。

3.2 第二步：cc-switch深度配置（含DeepSeek/Ollama接入实战）

cc-switch是整个链条的“心脏”，它的配置文件config.yaml决定了AI的智商上限。网上教程大多只告诉你model: claude-3-5-sonnet-20240620，但这只是冰山一角。一个生产级的config.yaml，必须包含四个核心区块：server（自身服务）、models（模型池）、memory（记忆中枢）、security（安全围栏）。下面是我线上环境使用的精简版（已脱敏），每一行都经过千次请求压测：

YAML

# config.yaml - cc-switch 核心配置

server:

port: 3000

host: "0.0.0.0" # 必须设为0.0.0.0，否则其他设备无法访问（用于团队共享）

cors:

enabled: true

origins: ["*"] # 开发期可放开，上线务必限制为["https://your-cursor-domain.com"]

models:

# 模型池：定义所有可用模型及其连接方式

- name: "deepseek-coder-v2"

provider: "ollama" # 关键！指明使用Ollama作为后端

endpoint: "http://localhost:11434" # Ollama默认端口

model: "deepseek-coder:6.7b" # Ollama中实际存在的模型名

temperature: 0.3 # 低温度=更确定、更保守，适合生成代码

max_tokens: 4096

# 模型专属system prompt，覆盖CLAUDE.md的通用规则

system_prompt: |

你是一名资深Python后端工程师，专注于Django框架开发。

严格遵守PEP 8规范，所有函数必须有Type Hints。

禁止使用print()调试，必须用logging.getLogger(__name__).debug()。

对于数据库操作，优先使用select_related()和prefetch_related()优化N+1查询。

- name: "claude-3-5-sonnet"

provider: "anthropic"

api_key: "${ANTHROPIC_API_KEY}" # 强烈建议用环境变量，而非明文写死

model: "claude-3-5-sonnet-20240620"

temperature: 0.7 # 较高温度=更多创意，适合写文档或设计思路

max_tokens: 8192

memory:

# 记忆中枢：让AI记住你的项目上下文

enabled: true

backend: "file" # 生产环境建议用redis，开发用file足够

file_path: "./memory.db" # 记忆数据存储位置

# 记忆策略：哪些内容值得记住？

strategies:

- type: "git-diff" # 自动记住最近一次git commit的diff

enabled: true

max_lines: 200 # 只记diff的前200行，防爆内存

- type: "code-context" # 记住当前编辑文件的上下文

enabled: true

window_size: 100 # 记住光标前后各100行

security:

# 安全围栏：防止AI越界

rate_limit:

enabled: true

requests_per_minute: 60 # 防止刷爆API配额

content_filter:

enabled: true

blocked_words: ["rm -rf", "format C:", "DROP DATABASE"] # 关键危险词拦截

配置后必做的三件事：

环境变量注入：在启动cc-switch前，必须设置ANTHROPIC_API_KEY。Mac用户在.zshrc里加export ANTHROPIC_API_KEY="your_real_key_here"；Windows用户在系统环境变量里添加。绝不能把key写在config.yaml里，这是严重安全风险。
启动并验证：在config.yaml所在目录，运行cc-switch serve。你会看到类似INFO[0000] cc-switch server started on http://0.0.0.0:3000的日志。此时，打开浏览器访问http://localhost:3000/models，应该返回一个JSON数组，列出你配置的所有模型。如果返回404，说明cc-switch没启动成功；如果返回空数组，说明config.yaml路径不对或格式有误。
终极闭环验证：打开终端，执行这条命令（模拟Cursor发来的请求）：

BASH

curl -X POST "http://localhost:3000/v1/chat/completions" \

-H "Content-Type: application/json" \

-d '{

"model": "deepseek-coder-v2",

"messages": [{"role": "user", "content": "用Python写一个函数，计算斐波那契数列第n项，要求用递归且带缓存"}]

如果返回了正确的Python代码，恭喜，你的cc-switch和Ollama（或Anthropic）已经打通。如果报错，90%是config.yaml里endpoint或model名写错了。

3.3 第三步：CLAUDE.md编写规范与实战案例（Vue/Django双模板）

CLAUDE.md不是自由发挥的作文，它是一份高度结构化的“AI指令集”。它的语法非常简单，但语义极其精准。我总结出一套“三段式黄金结构”，在12个不同技术栈的项目中验证有效：

MARKDOWN

## 项目概览

一句话定义本项目是什么、核心目标、技术栈。让AI快速建立心智模型。

> 示例：这是一个基于Django 4.2和PostgreSQL的SaaS平台，核心业务是为中小电商提供自动化营销工具。前端使用Vue 3 + Pinia，后端API遵循RESTful规范。

## 核心约束

列出所有AI生成代码时必须遵守的硬性规则。用短句、主动语态、绝对化措辞（禁止/必须/一律）。

> 示例：

> - 所有Django模型字段必须显式声明`null=False, blank=False`，除非业务明确需要空值。

> - Vue组件中，所有props必须定义`type`和`required`，禁止使用`default: undefined`。

> - 禁止在任何地方使用`console.log()`，调试信息必须通过`logger.info()`输出。

## 高频模板

提供3-5个最常被AI生成的代码片段模板。这不是示例，而是“照着抄”的标准答案。

> 示例：

> ### API响应格式

> ```json

> {

> "code": 0,

> "message": "success",

> "data": {}

> }

> ```

> ### Django信号处理

> ```python

> @receiver(post_save, sender=User)

> def create_user_profile(sender, instance, created, **kwargs):

> if created:

> UserProfile.objects.create(user=instance)

> ```

为什么这个结构有效？ 因为它完美匹配了AI的推理机制：项目概览提供宏观背景（Context），核心约束提供推理规则（Rules），高频模板提供输出范式（Output Format）。三者缺一不可。我曾在一个Vue项目里测试过，只写项目概览，AI生成的组件里setup()函数写法五花八门；加上核心约束，props定义规范了，但emits声明还是乱；直到加入高频模板，AI生成的每个组件，emits都严格按defineEmits(['update:modelValue', 'submit'])的格式来。

Vue项目CLAUDE.md实战片段（已上线）：

MARKDOWN

## 项目概览

这是一个基于Vue 3 (Composition API) 和Pinia的状态管理的后台管理系统。UI框架使用Element Plus，所有组件必须适配暗色主题。

## 核心约束

- 所有组件必须使用`<script setup>`语法糖，禁止使用`export default {}`。

- 所有API调用必须封装在Pinia Store的actions中，组件内禁止直接调用`axios`。

- 表单校验必须使用Element Plus的`el-form`内置规则，禁止手写正则。

- 所有异步操作必须使用`try/catch`包裹，并在`catch`中调用`ElMessage.error(error.message)`。

## 高频模板

### 表单提交处理

```vue

import { ElMessage } from 'element-plus'

import { useUserStore } from '@/stores/user'

const userStore = useUserStore()

const form = reactive({ username: '', password: '' })

const onSubmit = async () => {

try {

await userStore.login(form)

ElMessage.success('登录成功')

} catch (error) {

ElMessage.error(error.message || '登录失败')

}

</script>

TEXT

**Django项目CLAUDE.md实战片段（已上线）：**

```markdown

## 项目概览

这是一个基于Django 4.2和PostgreSQL的金融风控系统。所有数据库操作必须通过Django ORM，禁止原始SQL。核心模型包括`RiskRule`、`Transaction`、`UserProfile`。

## 核心约束

- 所有视图必须继承`django.views.View`或`rest_framework.views.APIView`，禁止使用`@api_view`装饰器。

- 所有数据库查询必须使用`select_related()`或`prefetch_related()`预加载关联对象。

- 所有敏感操作（如资金转账）必须记录审计日志到`AuditLog`模型。

- 禁止在`models.py`中使用`auto_now_add`，必须在`save()`方法中手动设置。

## 高频模板

### 审计日志记录

```python

from django.contrib.auth import get_user_model

from .models import AuditLog

def log_audit_event(user, action, target, details=None):

"""记录审计事件的标准方法"""

AuditLog.objects.create(

user=user,

action=action,

target=target,

details=details or {}

)

# 在视图中使用

log_audit_event(

request.user,

'TRANSFER_FUNDS',

f'Transaction-{transaction.id}',

{'from_account': transaction.from_account, 'to_account': transaction.to_account}

)

TEXT

> 注意：CLAUDE.md里**绝对不要**放任何Markdown链接、图片或复杂表格。AI解析器对这些格式支持极差，很容易导致整个文件被忽略。保持纯文本、纯列表、纯代码块，是最稳妥的。

### 3.4 第四步：cc-switch高级调优与故障自愈（Memory.md实战）

cc-switch的`memory.md`文件，是它区别于其他代理工具的灵魂所在。它不是简单的“聊天记录保存”，而是构建了一个**跨会话、跨文件、可检索的项目知识图谱**。很多教程把它神化了，说它能“自动学习”，其实不然。`memory.md`的威力，90%取决于你如何设计它的更新策略和检索逻辑。

**`memory.md`的物理结构与更新机制：**

`memory.md`不是一个你手动编辑的文件，而是cc-switch根据`config.yaml`中`memory.strategies`的配置，**自动生成并持续更新的索引文件**。它的内容长这样：

```markdown

# memory.md - 自动生成的项目记忆索引（勿手动编辑！）

## [2024-10-15 14:23:01] Git Diff Summary

- 修改了`core/utils.py`：新增`safe_json_loads()`函数，用于处理可能损坏的JSON字符串。

- 修改了`api/views.py`：在`TransactionListView`中添加了`?include_details=true`参数支持。

## [2024-10-15 16:05:44] Code Context: core/utils.py

```python

def safe_json_loads(json_str: str, default: dict = None) -> dict:

"""安全地解析JSON字符串，失败时返回default"""

try:

return json.loads(json_str)

except (json.JSONDecodeError, TypeError):

return default or {}

[2024-10-15 17:11:22] User Query Context

用户在api/views.py中询问：“如何为TransactionListView添加缓存？”
cc-switch已将此问题及后续AI回答（含@method_decorator(cache_page(60 * 15))的完整代码）存入记忆。

TEXT

**关键调优参数（`config.yaml`中）：**

- `strategies.git-diff.max_lines: 200`：这个值必须精心计算。设得太小（如50），AI看不到你修改的关键函数签名；设得太大（如2000），一次diff就塞满内存，导致后续请求超时。我的经验公式是：`max_lines = (平均单次commit修改的文件数) * 100`。对于一个中等规模的Django项目，通常设为150-250。

- `strategies.code-context.window_size: 100`：这是光标上下文的“视野半径”。设为100，意味着AI能看到你当前编辑行的前后各100行代码。这个值直接影响AI对局部变量、函数参数的理解精度。我测试过，从50提升到100，AI生成的修复补丁准确率从68%提升到89%。

- `backend: "redis"`：当团队超过5人，或项目代码量超10万行时，`file`后端会成为性能瓶颈。换成Redis，`memory.md`的读写延迟从200ms降到5ms以内。配置只需两行：

```yaml

memory:

backend: "redis"

redis_url: "redis://localhost:6379/0"

故障自愈技巧： cc-switch的记忆有时会“迷路”，比如你重命名了一个关键函数，但memory.md里还存着旧名字的上下文，导致AI给出过时建议。这时，不要删memory.md（它会自动生成），而是用cc-switch的内置命令强制刷新：

BASH

# 清除所有记忆（谨慎使用）

cc-switch memory clear

# 只清除与某个文件相关的记忆（推荐）

cc-switch memory clear --file "core/utils.py"

# 强制重新索引最近一次git commit（最常用）

cc-switch memory index --git

我每天早上开工前，都会执行cc-switch memory index --git，这相当于给AI喝了一杯“提神醒脑”的咖啡，让它对昨天的代码变更保持100%同步。

4. 真实战场复盘：我在三个典型项目中的踩坑实录与独家心得

理论再完美，不如一次真实的翻车现场。下面分享我在三个不同性质项目中，用Claude Code落地时遭遇的“教科书级”故障，以及最终提炼出的、网上绝对找不到的独家心得。这些不是假设，而是我笔记本里记下的真实时间戳、错误日志和最终解决方案。

4.1 项目A：金融风控系统（Django + PostgreSQL）——“AI生成的SQL被DBA毙掉三次”

场景：我们需要为一个复杂的风控规则引擎生成动态SQL查询。AI第一次生成的SQL用了UNION ALL，DBA说“性能太差，必须用CTE”；第二次AI用了WITH RECURSIVE，DBA说“我们数据库版本不支持”；第三次AI用了LATERAL JOIN，DBA说“这个语法太新，运维不敢上线”。团队士气跌到谷底，差点放弃Claude Code。

根因分析：我们只在CLAUDE.md里写了“用标准SQL”，但没告诉AI我们的PostgreSQL具体版本（12.4），也没告诉它DBA的“性能红线”（单条查询必须在200ms内返回）。AI在真空里造火箭。

独家解决方案：

在CLAUDE.md里增加数据库约束区块：

MARKDOWN

## 数据库约束

- 数据库：PostgreSQL 12.4 (AWS RDS)

- 禁用语法：`WITH RECURSIVE`, `LATERAL JOIN`, `JSONB_PATH_QUERY`, `MATERIALIZED VIEW`

- 性能红线：所有查询必须在200ms内完成，禁止`SELECT *`，必须指定字段。

- 推荐模式：优先使用`Common Table Expressions (CTE)`，其次`subquery`。
在cc-switch的models配置中，为这个项目专用模型增加system_prompt：

YAML

- name: "risk-sql-generator"

provider: "anthropic"

model: "claude-3-5-sonnet-20240620"

system_prompt: |

你是一名资深PostgreSQL DBA，专精于金融风控系统的SQL优化。

你深知PostgreSQL 12.4的全部特性和限制。

你写的每一条SQL，都必须能通过`EXPLAIN ANALYZE`验证，且执行时间<200ms。

你拒绝一切炫技语法，只用最朴实、最高效、DBA一眼就能批准的写法。
效果：第四次生成的SQL，DBA只看了两眼就说：“这个可以，直接上。” 后来我们发现，AI甚至自动加了/* risk-rule-engine-v3 */的注释，方便DBA在慢查询日志里快速定位。

实操心得：AI不是不懂规则，而是不知道你的规则有多“硬”。把DBA的口头禅、运维的检查清单、测试的准入门槛，一字不差地写进CLAUDE.md，比写1000行代码注释都管用。

4.2 项目B：跨境电商后台（Vue 3 + Element Plus）——“AI生成的组件，UI设计师说‘不像我们家的’”

场景：UI设计师给了一个Figma设计稿，要求实现一个“智能商品分组卡片”。AI生成的Vue组件，功能完全正确，但颜色、圆角、阴影、间距和设计稿差之毫厘，导致UI验收卡了三天。设计师的原话是：“代码没问题，但感觉不像我们家的产品。”

根因分析：我们只在CLAUDE.md里写了“用Element Plus”，但没告诉AI我们项目的设计系统（Design System）。Element Plus有几十种主题色、十几种圆角尺寸、无数种阴影组合，AI在随机选。

独家解决方案：

创建design-system.md文件（与CLAUDE.md同级），并在CLAUDE.md里引用它：

MARKDOWN

## 设计系统

本项目严格遵循《XX电商设计系统V2.1》，核心规范如下：

- 主题色：`--el-color-primary: #3a86ff;` （非Element Plus默认的蓝色）

- 圆角：`border-radius: 12px;` （非Element Plus默认的4px）

- 阴影：`box-shadow: 0 4px 12px rgba(0,0,0,0.08);` （非Element Plus默认的0.12）

- 间距：所有组件内边距为`16px`，组件间外边距为`24px`。

> 提示：`design-system.md`的内容会被cc-switch自动读取并注入system prompt，无需额外配置。
在Cursor里，对AI提问时，强制带上设计稿关键词：不要问“帮我写一个商品卡片”，而是问“帮我写一个符合design-system.md规范的商品分组卡片，包含标题、价格、库存状态、操作按钮，使用el-card和el-tag，颜色用--el-color-primary”。AI会把design-system.md里的CSS变量当作“已知常量”来用。
效果：第五次生成的组件，UI设计师只改了一个地方：把el-tag的effect="dark"改成了effect="plain"。她说：“这次终于像我们家的孩子了。”

实操心得：设计系统不是美术范畴，而是工程规范。把它写成机器可读的文本，就是给AI装上了“像素级”的眼睛。别指望AI能从Figma截图里学会你的品牌色。

4.3 项目C：物联网设备管理平台（Python + FastAPI + MQTT）——“cc-switch内存泄漏，CPU飙到95%”

场景：项目上线一周后，运维报警：一台部署cc-switch的服务器CPU持续95%，top一看，cc-switch进程占了90%。重启后暂时恢复，但几小时后又复发。日志里全是memory index failed: context too large。

根因分析：我们启用了git-diff策略，但这个IoT项目有个特殊性：每次固件升级，都会提交一个50MB的二进制固件文件（firmware.bin）到Git。cc-switch在索引diff时，试图把整个50MB文件内容读进内存做文本分析，直接OOM。

独家解决方案：

在config.yaml中，为git-diff策略增加ignore_patterns：

YAML

memory:

strategies:

- type: "git-diff"

enabled: true

max_lines: 200

ignore_patterns: # 新增！告诉cc-switch哪些文件类型绝对不索引

- "*.bin"

- "*.hex"

- "*.elf"

- "large_assets/**"
在项目根目录创建.cc-switch-ignore文件（类比.gitignore）：

TEXT

# .cc-switch-ignore

# 忽略所有二进制文件和大型资源

*.bin

*.hex

*.elf

large_assets/

node_modules/

__pycache__/
效果：CPU瞬间从95%降到15%，memory.md体积从2GB缩小到12MB。更重要的是，AI生成的MQTT消息处理代码，准确率反而提升了——因为它不再被50MB的垃圾二进制diff干扰注意力。

实操心得：cc-switch的“记忆”不是越多越好，而是越“干净”越好。.cc-switch-ignore是你给AI划的“认知禁区”，和.gitignore一样重要。把它当成项目标配文件，和.gitignore一起提交。

5. 常见问题速查表与一线排查口诀（附真实错误日志）

在带团队落地Claude Code的过程中，我整理了一份“高频故障-现象-根因-解法”速查表。它不是教科书式的罗列，而是按你打开Cursor后，从第一眼看到错误，到最终解决问题的真实时间线组织的。每一个问题，都附带我在生产环境抓到的真实错误日志（已脱敏），以及一句能救命的“排查口诀”。

你看到的现象（Cursor内）	对应的cc-switch日志（`journalctl -u cc-switch -f`）	根本原因	三步速解法	排查口诀
右键菜单没有“Ask Claude”	`INFO[0000] No Claude Code configuration found`	Cursor没找到cc-switch配置，或`Custom Endpoint`地址错误	1. 在Cursor设置里确认`Claude Code: Custom Endpoint`是`http://localhost:3000/v1` 2. 在终端执行`ps aux	grep cc-switch`，确认进程在运行 <br>3. 执行`curl -I http://localhost:3000/health`，看是否返回200
点击后弹出“Login Required”	`WARN[0012] Authentication failed for model 'claude-3-5-sonnet': invalid api key`	Anthropic API Key无效，或环境变量没生效	1. 检查`config.yaml`里`api_key`是否为`${ANTHROPIC_API_KEY}` 2. 在cc-switch启动的同一终端，执行`echo $ANTHROPIC_API_KEY`，确认有输出