基于MCP协议实现AI开发上下文永续：claude-code-bridge项目实战

1. 项目概述：一个为AI开发者设计的上下文永续工具

如果你和我一样，日常开发流程已经深度嵌入了像Claude这样的AI助手，那你肯定对“上下文丢失”这个痛点深有体会。我经常在Claude的桌面应用里花上二三十分钟，和它一起头脑风暴，敲定一个功能的技术架构、边界条件和实现优先级。这个过程充满了灵感的碰撞和严谨的推演，最终形成了一套清晰的行动纲领。但问题来了：当我心满意足地关掉Claude，打开我的主力代码编辑器Cursor，准备大干一场时，我发现Claude Code（Cursor内置的AI编程助手）对我刚才那半小时的“战略会议”一无所知。我又得从头解释一遍：“我们刚才决定用Next.js 14的App Router，数据库选PlanetScale，API层要加Redis缓存，并且用户头像上传功能要优先做……” 这种重复劳动不仅低效，更致命的是，它打断了“思考”到“执行”的无缝流状态，让宝贵的上下文在工具切换的缝隙中流失了。

claude-code-bridge这个项目，就是为了彻底解决这个问题而生的。它本质上是一个本地的MCP（Model Context Protocol）服务器，扮演着Claude桌面应用和你的代码项目之间的“智能书记官”。它的核心工作流异常简洁而有力：当你在Claude Mac应用里完成一次策略讨论后，它会自动将讨论中形成的技术决策和产品决策分别捕获，并写入到你项目中的两个特定文件里。随后，当你打开Cursor时，通过一个简单的规则文件，Claude Code会在会话伊始就读取这些文件，从而瞬间获得完整的项目上下文。这样一来，从“战略制定”到“战术执行”的链路被完全打通，上下文不再是易失的对话记忆，而是变成了可持久化、可累积、可传承的项目资产。

这个工具的目标用户非常明确：就是那些已经将Claude用于高阶思考（如系统设计、产品规划），同时使用Cursor和Claude Code进行实际编码构建的开发者。它不是为了炫技，而是为了解决一个真实、高频、影响开发体验和效率的具体问题。通过将AI对话中的决策“固化”到项目文件中，它实现了几个关键价值：消除上下文切换成本，让你无需在工具间重复解释；建立决策追溯机制，所有重要的技术选型和产品权衡都有据可查；实现知识复利，每一次策略会话的产出都成为下一次会话的输入，项目理解像滚雪球一样越来越深入。

2. 核心设计思路：双文件策略与自动化同步循环

claude-code-bridge的设计哲学充满了工程上的巧思，它没有试图去构建一个复杂无比的全能系统，而是用最精简的架构，解决了最核心的问题。整个设计的基石可以概括为“双文件驱动，自动化同步”。

2.1 双文件的职责分离：给AI的和给人的

项目要求在每个代码仓库的根目录创建两个Markdown文件：CLAUDE.md和docs/decisions.md。这绝非随意为之，而是深思熟虑后的职责分离。

CLAUDE.md：Claude Code的专属“记忆体”这个文件的服务对象首先是AI——具体来说是Cursor编辑器里的Claude Code。它的内容结构是高度格式化的，旨在为AI提供构建代码所需的全部技术上下文。通常，我会建议在里面包含以下几个部分：

• 愿景与使命：用一两句话阐明这个项目是做什么的，为谁服务的。这能帮助AI理解代码的最终目标，而不仅仅是实现细节。
• 当前技术栈：明确列出使用的语言、框架、库、数据库、部署平台等。例如，“前端：Next.js 14 (App Router), Tailwind CSS；后端：Node.js with Express, Prisma ORM；数据库：PostgreSQL on Supabase；缓存：Upstash Redis”。
• 代码规范：定义本项目非黑即白的代码规则。比如，“一律使用TypeScript并开启严格模式”、“组件必须为函数式并用React.memo包裹”、“API响应必须遵循统一的{ data, error }格式”。这些规则能极大提升AI生成代码的一致性和质量。
• 项目日志：这是文件的主体，也是claude-code-bridge自动写入的部分。所有在Claude对话中形成的技术决策都会以时间戳条目的形式追加在这里。例如，“[2024-05-27] 决定采用Server Actions替代独立的API路由，以简化数据获取并提升类型安全。”

docs/decisions.md：人类可读的“决策档案”这个文件存放在docs/目录下，其目标读者是项目组内的其他工程师、产品经理，乃至未来的维护者。它记录的是“为什么”而不是“是什么”。内容聚焦于产品逻辑、商业权衡和架构取舍。格式上，它通常是简单的、按时间倒序排列的条目，每个条目包含：决策内容、决策背景、考虑的备选方案及其被否决的理由、以及预期的结果。例如，“决策：用户首次登录后强制进入引导流程。原因：新用户留存数据显示，完成引导的用户7日留存率提升40%。考虑过的方案：1) 可跳过的引导（否决：跳失率高）；2) 渐进式提示（否决：不够突出）。”

这种分离的精妙之处在于，它尊重了不同“消费者”的信息需求。AI需要结构化、明确的技术指令来高效生成代码；人类则需要理解背后的逻辑和上下文来做出判断、进行评审或继承项目。把两者混在一起，只会让文件变得臃肿且目标不清。

2.2 自动化同步循环：让流程“隐形”

有了这两个文件，下一步就是如何自动地、准确地将Claude对话中的精华填充进去。claude-code-bridge通过实现一个MCP服务器，暴露了三个核心工具给Claude桌面应用：read_file,write_decisions,create_file。整个同步循环的自动化，就依赖于在Claude的“项目指令”中精心编写一套规则。

这个循环是这样的：

1. 策略会话：你在Claude Mac应用里，针对某个项目进行讨论。
2. 自动捕获：根据预设规则，在对话结束时（或达到某个触发条件），Claude会自动调用read_file工具，先读取项目中现有的CLAUDE.md，了解当前状态。
3. 智能写入：接着，Claude会判断是否需要写入。规则通常是：如果本次对话产生了新的技术结论，就调用write_decisions工具，将内容以标准格式追加到CLAUDE.md的“项目日志”部分；同时，如果有产品层面的决策，则追加到docs/decisions.md。如果发现现有的CLAUDE.md结构混乱或自相矛盾，它甚至可以调用create_file工具，直接重新生成一个整洁的新版本。
4. 无缝读取：当你切换到Cursor开始编码时，项目根目录下的.cursorrules文件会指示Claude Code：“在每次会话开始时，首先阅读CLAUDE.md”。于是，Claude Code一启动就拥有了全部最新的技术上下文。
5. 构建与迭代：你基于完整的上下文进行开发。下一次，当你再回到Claude讨论新问题时，它读取的CLAUDE.md和docs/decisions.md已经包含了上一次的决策记录，讨论可以直接在此基础上深化。

这个循环的关键在于“自动化”和“无感”。作为开发者，你不需要在对话后手动输入“请把刚才说的总结一下写到某某文件里”。整个同步过程由AI根据你预先设定的规则在后台静默完成。你只需要专注于思考和对话，而“记录”这件事，交给了这位不知疲倦的书记官。

3. 详细配置与实操要点

理解了核心设计后，我们来一步步拆解如何将这个工作流搭建起来。这个过程分为“机器级”的一次性设置和“项目级”的重复性配置。

3.1 一次性环境搭建：让MCP服务器跑起来

首先，你需要将claude-code-bridge这个“书记官”请到你的本地机器上安家。这部分的配置每个开发者只需要做一次。

步骤一：获取并构建项目打开终端，执行克隆和构建命令。这里有一个容易踩坑的点：项目是用TypeScript写的，所以npm run build这一步绝对不能省略。这个命令会将src/目录下的TypeScript源代码编译成dist/index.js这个JavaScript文件。Claude Mac应用最终启动MCP服务器时，执行的是这个编译后的JS文件，而不是TS源文件。如果你直接运行TS文件，会因为环境不兼容而失败。

git clone https://github.com/harshitleads/claude-code-bridge.git cd claude-code-bridge npm install npm run build # 确保看到dist目录被成功创建

步骤二：确认Node.js路径这是整个设置中最关键也最容易出错的一步。你需要告诉Claude Mac应用，用哪个Node.js解释器来运行我们刚刚编译好的服务器脚本。千万不要想当然地使用默认路径。

which node

在终端执行上述命令。在大多数使用Homebrew安装Node的Mac上，输出很可能是/opt/homebrew/bin/node。而系统自带的/usr/bin/node要么不存在，要么版本极旧，一定不要使用。请完整复制which node命令输出的路径。

步骤三：注册MCP服务器到Claude现在，我们需要让Claude Mac应用知道这个新“书记官”的存在。Claude的配置存放在一个固定的JSON文件中：~/Library/Application\ Support/Claude/claude_desktop_config.json

你可以用任何文本编辑器（如VSCode、Cursor、甚至nano）打开它。如果这是你第一次配置MCP服务器，这个文件可能不存在或内容为空，你可以直接创建一个。你需要添加一个mcpServers的配置块。

{ "mcpServers": { "claude-code-bridge": { "command": "/opt/homebrew/bin/node", // 替换为你的 which node 输出 "args": ["/absolute/path/to/claude-code-bridge/dist/index.js"] // 替换为你的绝对路径 } } }

• command：填入你第二步复制的Node.js路径。
• args：是一个数组，里面唯一的一项是你claude-code-bridge项目中dist/index.js文件的绝对路径。例如：/Users/yourname/Development/claude-code-bridge/dist/index.js。获取绝对路径的一个简单方法是在终端进入claude-code-bridge目录，然后执行pwd命令，再将结果与/dist/index.js拼接。

重要提示：修改完配置文件后，必须完全退出Claude Mac应用（使用Cmd+Q，而不是仅仅关闭窗口）并重新启动。然后，点击应用左上角的“Claude”菜单，进入“Settings”，再切换到“Connectors”标签页。你应该能看到claude-code-bridge被列出，状态是“LOCAL DEV”，并且下面显示了它提供的三个工具（read_file,write_decisions,create_file）。如果没看到，99%的原因是command或args里的路径写错了，请仔细检查。

3.2 项目级配置：为每个代码仓库启用上下文同步

机器级的设置完成后，对于每一个你希望启用此工作流的Git仓库，都需要进行如下配置。这个过程就像为项目开启一个专属的“决策记录仪”。

步骤四：创建核心文件在你的项目根目录，创建CLAUDE.md文件。我建议初始内容不要留空，至少把框架搭好，这样AI在首次追加内容时更有参照。一个丰富的模板能引导更高质量的记录。

## 愿景与使命 本项目是一个面向个人开发者的全栈知识管理平台，旨在通过AI辅助将碎片化信息转化为结构化、可关联的知识网络。 ## 当前技术栈 - **前端**: Next.js 14 (App Router), React 18, TypeScript, Tailwind CSS, shadcn/ui组件库 - **后端**: Next.js API Routes (App Router), 无独立后端服务器 - **数据库**: PostgreSQL on Supabase，使用Prisma ORM进行管理 - **认证**: Supabase Auth - **部署**: Vercel (前端)，Supabase (后端及数据库) - **AI集成**: 通过OpenAI API (GPT-4) 提供内容摘要与标签生成 ## 代码规范 1. **类型安全**: 必须使用TypeScript，并启用`strict: true`模式。 2. **组件设计**: 所有React组件必须为函数式组件，并使用`export default`导出。复杂组件需用`React.memo`包裹。 3. **数据获取**: 服务端使用`async/await`获取数据，客户端使用TanStack Query (React Query) 管理状态。 4. **API设计**: 所有API路由返回统一格式：`{ success: boolean, data?: any, error?: string }`。 5. **错误处理**: 必须使用try-catch块包裹可能失败的操作，并在前端友好地提示用户。 ## 项目日志 *技术决策将自动追加于此*

同时，在docs/目录下创建decisions.md文件。这个文件更侧重于产品叙事。

# 产品决策日志 本文件记录所有关键的产品功能、交互设计及业务逻辑决策，包括决策背景、权衡考量和拒绝的替代方案。此文件为只追加(Append-only)，永不修改历史记录。 ---

步骤五：配置Cursor的自动读取规则为了让Claude Code在Cursor里自动读取上下文，我们需要在项目根目录创建一个名为.cursorrules的文件。这个文件的内容是给Claude Code的指令。内容可以非常简单直接：

在开始任何新会话或处理任何用户请求之前，必须首先完整阅读并理解项目根目录下的CLAUDE.md文件。 该文件包含了本项目的愿景、技术栈、代码规范以及最新的技术决策日志。 你的所有代码建议和实现都必须严格遵循CLAUDE.md中的规定。

这个文件的作用是“强制”Claude Code在每次互动前加载上下文，确保它的建议始终与项目的最新决策保持一致。

步骤六：配置Claude的自动写入规则（最关键的一步）这是整个工作流自动化的“大脑”。你需要在Claude Mac应用里，为你正在工作的这个项目（或创建一个新项目）设置“项目指令”。请注意，这不是项目的“描述”字段，描述只是标题。你需要在项目设置里找到“Project instructions”或类似的文本框。

在这里，你需要粘贴一套详细的规则，告诉Claude在每次对话后应该如何行动。这套规则需要根据你的项目路径进行定制。以下是一个多项目管理的配置范例：

## 项目路径注册表 请根据对话中讨论的项目，使用以下绝对路径进行文件操作： 项目路径： - 知识管理平台 (knowledge-base): - CLAUDE.md: /Users/yourname/Projects/knowledge-base/CLAUDE.md - 决策文件: /Users/yourname/Projects/knowledge-base/docs/decisions.md - 实验性工具 (demo-tool): - CLAUDE.md: /Users/yourname/Projects/demo-tool/CLAUDE.md - 决策文件: /Users/yourname/Projects/demo-tool/docs/decisions.md ## 自动同步规则 在每次涉及技术或产品讨论的对话结束时，请自动执行以下操作： 1. **识别项目**：根据对话内容，确定当前讨论的是哪个项目（如“知识管理平台”）。 2. **读取现状**：使用`read_file`工具，读取该项目对应的CLAUDE.md文件的当前内容。 3. **决策与写入**： a. **技术决策**：如果本次对话得出了新的技术结论（如选用某个库、调整架构、定义API规范），则使用`write_decisions`工具，将结论以清晰、简洁的要点形式，追加到CLAUDE.md的“项目日志”部分。格式为：“[YYYY-MM-DD] 决策内容”。 b. **产品决策**：如果本次对话涉及产品功能、用户体验或业务逻辑的权衡，则使用`write_decisions`工具，将决策背景、最终选择和否决的替代方案，追加到该项目的docs/decisions.md文件。格式为：“## [YYYY-MM-DD] 决策主题\n内容...”。 c. **文件整理**：如果读取到的CLAUDE.md结构混乱、内容过时或自相矛盾，你可以使用`create_file`工具，直接根据当前对话的理解，重新生成一个结构清晰、内容准确的CLAUDE.md文件。 4. **精简原则**：如果对话纯属闲聊或未产生任何实质性决策，则无需执行任何写入操作。 5. **完全自动化**：请在不询问用户、不请求确认的情况下，自动完成上述所有步骤。

将上述示例中的路径替换成你电脑上的真实绝对路径。这套指令的精髓在于，它让Claude扮演了一个主动的、有判断力的助手。它不仅能自动追加内容，还能在发现文件混乱时主动整理，并且通过“项目路径注册表”支持你管理多个项目。

4. 实战应用与场景深化

配置完成后，这个工作流如何在实际开发中发挥作用呢？让我们通过几个具体场景来感受它的威力。

4.1 场景一：技术栈选型与架构讨论

假设你正在启动一个新项目，关于前端状态管理方案举棋不定。你在Claude Mac应用里开始了讨论：

• 你：“我们这个新的仪表盘项目，数据流比较复杂，有实时数据更新。在Zustand和TanStack Query之间该怎么选？”
• Claude：（经过一番利弊分析，对比了Zustand的轻量简洁和TanStack Query的服务器状态管理、缓存、后台更新等强大功能）“……考虑到仪表盘对实时性和缓存策略的高要求，建议采用TanStack Query作为服务器状态管理，同时搭配useContext或一个小型的Zustand store来处理纯粹的客户端UI状态（如侧边栏折叠）。这样组合能最大化开发效率和性能。”

对话结束。几秒钟后，claude-code-bridge自动工作。你的CLAUDE.md文件的“项目日志”部分会多出一行：

[2024-05-27] 前端状态管理方案确定：采用 TanStack Query (React Query) 管理所有服务器状态（数据获取、缓存、同步），同时使用一个轻量级的 Zustand store 来处理全局客户端UI状态（如主题、侧边栏）。理由：TanStack Query 对异步数据流的强大管理能力更适合本项目的实时仪表盘需求。

同时，docs/decisions.md可能会记录：

## 2024-05-27 状态管理库选型 **决策**：组合使用TanStack Query与Zustand。 **背景**：新仪表盘项目需要处理大量实时、关联的服务器数据，同时也有部分全局UI状态。 **权衡**： - **方案A（全量Zustand）**：轻量，学习曲线低，但对于缓存、后台更新、请求去重等需要手动实现，复杂度高。 - **方案B（全量TanStack Query）**：服务器状态管理能力一流，但处理纯客户端状态略显笨重。 - **选定方案（组合）**：用专业工具做专业事。TanStack Query负责服务器状态，Zustand负责客户端状态。牺牲了极致的简洁性，换来了更强大的功能和更清晰的关注点分离。 **预期**：提升数据流处理的可靠性和开发效率，初期学习成本稍高。

第二天，你打开Cursor开始写第一个数据获取Hook。Claude Code在会话开始时已经读到了CLAUDE.md里的决策。当你输入“创建一个获取用户列表的hook”时，它给出的建议会直接基于TanStack Query，而不是Redux或Zustand，并且会遵循你在“代码规范”里定义的API响应格式。

4.2 场景二：迭代开发中的上下文保持

项目进行到一半，你遇到一个性能问题：列表页在数据量大时渲染卡顿。你又找Claude商量。

• 你：“我们的用户列表页用了Array.map直接渲染500条项目，现在滚动很卡。有什么优化思路？”
• Claude：（在分析了CLAUDE.md中已知的技术栈后）“……考虑到我们用的是React和Next.js，建议：1. 立即引入react-virtualized或@tanstack/react-virtual实现虚拟滚动，只渲染可视区域内的行。2. 对列表项组件使用React.memo进行记忆化，避免不必要的重渲染。3. 检查TanStack Query的缓存策略，确保数据不会重复请求。”

对话结束。新的决策被追加到日志：

[2024-05-28] 性能优化决策：为长列表页面引入 `@tanstack/react-virtual` 实现虚拟滚动。所有列表项组件必须用 `React.memo` 包裹。检查并优化相关查询的 `staleTime` 与 `cacheTime` 配置。

一周后，另一位同事接手这个功能。他不需要找你询问历史，直接查看CLAUDE.md的日志和docs/decisions.md，就能立刻明白为什么这里用了虚拟滚动库，以及当初的性能瓶颈是什么。他甚至在Cursor里开始工作时，Claude Code也会基于这条日志，在他修改相关组件时提醒他“别忘了用React.memo”。

4.3 场景三：多项目并行管理

对于同时维护多个项目的开发者，claude-code-bridge的价值更大。你可以在Claude Mac应用里为每个项目都设置好对应的“项目指令”路径。当你和Claude讨论A项目时，它自动更新A项目的文件；切换到B项目对话，它又自动更新B项目的文件。你的大脑无需在不同项目的技术细节间强行切换和记忆，所有上下文都固化在各自的项目仓库里。.cursorrules文件也确保了，无论你打开哪个项目的代码，Claude Code读取的都是正确的、专属的CLAUDE.md。

5. 常见问题、排查与进阶技巧

即使配置再仔细，在实际使用中也可能遇到一些问题。以下是我在深度使用过程中总结的常见坑点和解决方案。

5.1 安装与连接问题排查表

5.2 进阶使用技巧与心得

1. 让CLAUDE.md“活”起来：不要只把它当成一个日志文件。你可以主动维护“当前技术栈”和“代码规范”部分。例如，当你升级了某个关键库（如Next.js从14升到15），手动更新技术栈部分。这样Claude Code在提供建议时，会基于最新的依赖版本，避免给出过时的API用法。

2. 决策条目的质量：自动追加的日志条目质量，取决于你与Claude对话的结论清晰度。在对话尾声，尝试用总结性的口吻说：“好的，那么我们本次的结论是：第一，…；第二，…”。Claude会基于这种清晰的结构生成更易读的日志。

3. .cursorrules的威力：这个文件不仅可以命令Claude Code读取CLAUDE.md。你还可以加入更多项目特定的指令，比如：“本项目的组件命名均采用PascalCase，工具函数采用camelCase”，“优先使用async/await而非.then链式调用”。这能进一步统一AI的代码输出风格。

4. docs/decisions.md的团队价值：这个文件是极好的团队沟通工具。在代码评审（PR）时，附上相关决策的链接，能让评审人快速理解代码背后的“为什么”，而不仅仅是看“是什么”。它为新成员提供了最快的历史上下文导入。

5. 处理“文件混乱”：如果你发现CLAUDE.md被自动追加得有些凌乱，可以在与Claude的对话中直接说：“请重新整理一下CLAUDE.md文件，保持‘愿景’、‘技术栈’、‘规范’、‘日志’的结构，并将日志按时间倒序排列。”根据你设定的规则，Claude可能会使用create_file工具直接生成一个整洁的新版本。这是一个非常强大的维护功能。

6. 安全与隐私考量：记住，CLAUDE.md和docs/decisions.md通常会被提交到Git仓库。绝对不要在Claude对话中提及并最终被写入这些文件的决策里，包含任何敏感信息，如API密钥、密码、内部服务器地址、未公开的商业逻辑细节等。养成好习惯，敏感信息永远只存在于环境变量或配置文件中。

这个工作流初看起来需要一些设置成本，但一旦跑通，它所带来的“上下文永续”体验是革命性的。它模糊了设计与开发、思考与执行之间的界限，让AI真正成为了一个拥有持久记忆和一致性的合作伙伴。你不再需要像一个中间人一样，在不同的工具间搬运信息。你可以更专注地思考，更流畅地构建。最终，你的项目仓库里留下的，不仅是一行行代码，还有一份伴随项目生长、记录每一个关键抉择的“数字航海日志”。