1. 项目缘起为什么我们需要一个“优雅”的CR助手在团队协作开发中Code Review代码审查简称CR是保证代码质量、促进知识共享的关键环节。然而传统的CR流程常常伴随着一些“痛点”开发者提交PRPull Request后需要等待同事抽空审查沟通可能异步且低效审查者面对复杂的变更集有时难以快速抓住核心逻辑和潜在风险而一些基础的代码风格、命名规范问题又常常在反复的“这个变量名可以改一下”、“这里加个空行”的评论中被提及消耗了双方不少精力。我所在的团队也长期受此困扰。直到我开始接触Claude和其衍生的开发工具一个想法逐渐成型能否利用AI的能力构建一个智能的、自动化的CR助手它不仅能自动检查代码风格和常见缺陷更能理解业务上下文对代码逻辑、架构设计甚至安全漏洞提出有深度的建议。这不仅仅是另一个静态代码分析工具如SonarQube而是一个能“对话”、能“理解”、能融入我们日常开发流程的智能伙伴。最近Anthropic推出的Claude Desktop及其背后的Claude Code技术栈特别是其支持MCPModel Context Protocol协议的能力让我看到了将想法落地的绝佳机会。Claude Code并非一个单一工具它更像是一个以Claude AI模型为核心通过MCP协议连接各种外部工具和数据的智能体Agent开发环境。我们可以基于此定制一个专属于我们团队的CR Agent。这个项目的目标就是从零开始利用Claude Code搭建一个“优雅”的CR助手。这里的“优雅”不仅指其代码和架构的简洁更指其用户体验它应该无缝集成到开发工作流中比如通过GitHub Actions或GitLab CI提供精准、有建设性的评审意见并以清晰、友好的方式呈现最终目标是提升CR效率让开发者更专注于创造性的逻辑构建而非格式纠错。2. 技术栈深度解析Claude Code、MCP与AI Agent在动手之前我们必须先厘清核心概念。这些术语在社区里很热但理解其内在联系和在我们项目中的角色至关重要。2.1 Claude Code不只是个代码编辑器很多人会把Claude Code和Cursor、VSCode等AI编程助手混淆。简单来说Claude Code是Anthropic官方推出的深度集成Claude系列模型如Claude 3.5 Sonnet的本地开发环境。它的“优雅”之处在于其原生设计哲学本地优先与隐私所有代码、上下文都在你的本地机器上处理敏感代码无需上传至第三方服务器这对企业开发至关重要。强大的上下文处理它能智能地读取你整个项目目录的文件构建丰富的上下文使Claude的理解更加准确。MCP协议的核心载体这是Claude Code最强大的特性之一。它内置了对MCP协议的支持意味着它可以成为一个“大脑”去协调和调用各种外部“工具”MCP Server。在我们的CR助手项目中Claude Code将扮演智能体Agent的运行时环境。我们将在这里编写Agent的核心逻辑并配置它去连接我们需要的各种MCP工具。2.2 MCP协议让AI拥有“手”和“眼睛”MCPModel Context Protocol是一个开放协议你可以把它想象成AI模型的“USB接口”标准。它的核心思想是解耦大语言模型LLM擅长理解和生成但不擅长直接操作文件系统、查询数据库或调用API。MCP协议定义了一套标准让LLM如Claude可以通过声明式的描述发现、调用由独立“服务器”MCP Server提供的各种工具Tools。一个MCP Server就是一个提供特定能力的后台服务。例如filesystem-mcp让AI可以读写本地文件。sqlite-mcp让AI可以操作SQLite数据库。brave-search-mcp或tavily-mcp为AI提供联网搜索能力。github-mcp让AI可以访问GitHub API读取仓库信息、PR、Issue等。对于我们的CR助手MCP协议是能力扩展的基石。我们需要让Agent能获取Git仓库的差异diff能读取项目文件甚至能调用代码分析工具如基于AST的检查器。这些都将通过集成相应的MCP Server来实现。2.3 AI Agent从被动应答到主动工作流一个简单的AI聊天机器人是你问它答。而一个AI Agent则具备更高的自主性。它可以根据一个目标例如“审查这个PR”自行规划步骤拆解任务调用合适的工具通过MCP处理中间结果并最终达成目标。我们的CR助手本质上就是一个专为Code Review场景设计的AI Agent。它的工作流可以规划为触发监听Git仓库的PR创建或更新事件。感知通过github-mcp获取PR的元信息、差异文件列表和具体代码变更diff。分析调用Claude模型结合整个项目的上下文通过Claude Code的文件读取能力以及代码变更进行分析。分析维度包括代码风格、逻辑错误、潜在bug、性能问题、安全漏洞、架构一致性等。执行在分析过程中可能需要调用更多工具。例如调用一个专门的code-linter-mcp假设我们构建一个进行静态检查或者调用search-mcp去查询某个API的最佳实践文档。决策与输出综合所有分析结果生成结构化的评审评论并通过github-mcp将评论提交到对应的PR代码行上。这个Agent将运行在Claude Code环境中利用其MCP客户端能力形成一个完整的自动化闭环。3. 从零搭建环境准备与基础框架搭建理论清晰后我们开始动手。第一步是准备好我们的“工作台”。3.1 安装与配置Claude Code目前Claude Code主要通过Claude Desktop应用来体验和开发。你需要前往Anthropic官网下载对应操作系统的Claude Desktop。安装过程很简单但有几个关键点需要注意系统要求确保你的系统满足要求特别是关于虚拟化支持的部分。如果你在安装或运行时遇到类似“Virtual Machine Platform not available”的错误通常需要在BIOS/UEFI设置中开启CPU的虚拟化支持如Intel VT-x或AMD-V并在Windows的“启用或关闭Windows功能”中开启“虚拟机平台”和“Windows虚拟机监控程序平台”。登录与模型安装后你需要登录Anthropic账户。目前根据网络信息新用户注册可能受限“not available to new users right now”你可能需要等待开放或使用已有账户。登录后在设置中确保你可以使用Claude 3.5 Sonnet或更高版本模型这些模型在代码理解上表现更佳。开发者模式Claude Desktop默认面向普通用户。要将其作为Agent开发环境我们需要用到其“开发者”特性。这通常涉及使用命令行启动特定配置或者等待Anthropic发布更直接的Claude Code SDK。目前社区通常通过配置Claude Desktop来加载本地MCP Server进行开发。一个常见的启动命令示例如下在终端中执行# 假设你的MCP服务器配置定义在一个叫 claude_desktop_config.json 的文件中 CLAUDE_CONFIG_PATH/path/to/your/claude_desktop_config.json /Applications/Claude.app/Contents/MacOS/Claude这个配置文件的核心就是定义Claude Desktop要连接的MCP Server。3.2 创建你的第一个MCP Server我们的CR助手Agent需要能力我们就从创建一个最简单的MCP Server开始让它具备“说话”输出日志的能力。我们将使用官方推荐的JavaScript/TypeScript SDKmodelcontextprotocol/sdk。首先初始化一个Node.js项目mkdir cr-assistant-mcp-server cd cr-assistant-mcp-server npm init -y npm install modelcontextprotocol/sdk然后创建一个server.js文件import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; // 1. 创建一个MCP服务器实例并声明其能力 const server new Server( { name: cr-assistant-server, version: 0.1.0, }, { capabilities: { // 这里声明服务器提供哪些能力例如工具Tools、提示词模板Prompts等 tools: {}, }, } ); // 2. 定义一个简单的工具记录审查日志 server.setRequestHandler(tools/call, async (request) { if (request.params.name log_review) { const message request.params.arguments?.message || No message provided; console.log([CR Assistant Log]: ${message}); return { content: [ { type: text, text: 已成功记录日志: ${message}, }, ], }; } throw new Error(Unknown tool: ${request.params.name}); }); // 3. 启动服务器使用标准输入输出作为传输层这是与Claude Desktop通信的标准方式 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(CR Assistant MCP Server running on stdio); } main().catch((error) { console.error(Server error:, error); process.exit(1); });这个服务器目前只提供了一个叫log_review的工具它接收一个消息参数并将其打印到控制台。接下来我们需要让Claude Desktop知道这个服务器。3.3 配置Claude Desktop连接MCP Server在Claude Desktop的配置目录下通常位于~/.config/Claude/或%APPDATA%\Claude\创建或编辑mcp-servers.json文件。这个文件告诉Claude Desktop有哪些可用的MCP Server。{ mcpServers: { cr-assistant: { command: node, args: [/absolute/path/to/your/cr-assistant-mcp-server/server.js], env: { NODE_ENV: development } } } }配置完成后重启Claude Desktop。如果配置成功你在Claude的输入框里或许就能看到它已经识别出新的工具具体UI交互可能随版本变化。更可靠的方式是通过Claude的“开发者工具”或相关菜单查看已连接的MCP服务。至此我们已经建立了一个最基础的“管道”Claude Code通过Claude Desktop可以调用我们自定义的MCP Server中的工具了。虽然这个工具只是打日志但它验证了整个MCP链路是通的。这是构建复杂Agent的第一步。4. 核心能力构建让CR助手“看得见”代码变更一个只会打日志的助手毫无用处。接下来我们要赋予它核心能力获取并理解Git代码变更。4.1 集成Git与GitHub MCP Server我们不需要自己从头实现Git操作社区已经有优秀的MCP Server项目。例如github-mcp-server或更通用的git-mcp-server。我们可以直接集成它们。以使用现有的github-mcp-server为例。首先你可能需要找到一个可靠的实现例如来自modelcontextprotocol官方或社区仓库的示例。假设我们找到了一个它可以通过环境变量配置GitHub Personal Access Token (PAT)并提供get_pull_request_diff这样的工具。我们的做法是要么直接运行这个第三方Server并将其添加到Claude Desktop的mcp-servers.json配置中更好的方式是将其功能集成到我们自己的cr-assistant-mcp-server中这样我们可以进行定制化。我们修改自己的server.js引入octokit/rest这样的GitHub SDK并添加一个工具import { Octokit } from octokit/rest; // 初始化OctokitToken应从环境变量安全读取 const octokit new Octokit({ auth: process.env.GITHUB_PAT, }); // ... 在server.setRequestHandler中增加新的工具处理 ... if (request.params.name get_pr_diff) { const { owner, repo, pull_number } request.params.arguments; if (!owner || !repo || !pull_number) { throw new Error(Missing required arguments: owner, repo, pull_number); } try { const { data: diffData } await octokit.rest.pulls.get({ owner, repo, pull_number, mediaType: { format: diff, }, }); // diffData 是一个包含diff文本的字符串 return { content: [ { type: text, text: 成功获取PR #${pull_number}的差异。\n差异内容如下\n${diffData}, }, ], }; } catch (error) { console.error(Failed to fetch PR diff:, error); return { content: [ { type: text, text: 获取PR差异失败: ${error.message}, }, ], isError: true, }; } }同时我们需要更新服务器的能力声明capabilities.tools添加这个新工具的描述包括其名称、描述和参数schema这样Claude才能知道如何调用它。注意处理GitHub API时务必注意Token的权限管理。创建的PAT需要至少具备读取仓库内容repo的权限。永远不要将Token硬编码在代码中必须通过环境变量或安全的配置管理系统传入。4.2 设计Agent的审查工作流现在我们的Server有了获取PR Diff的能力。接下来我们需要在Claude Code中设计Agent的思维链Chain of Thought。这不是写一个简单的脚本而是引导Claude按照我们的规划去执行一系列步骤。我们可以在Claude Code中创建一个新的对话或笔记作为Agent的“指令集”System Prompt。这个指令集需要非常详细你是一个专业的Code Review助手。当用户要求你审查一个GitHub PR时请严格按照以下步骤执行 1. **确认信息**向用户询问或确认PR的关键信息包括仓库所有者owner、仓库名repo和PR编号pull_number。 2. **获取变更**调用 get_pr_diff 工具获取该PR的详细代码差异。 3. **初步分析**阅读diff理解本次变更的范围、修改的文件以及大致的意图。 4. **获取上下文**为了更准确地审查你需要了解相关文件的完整内容。对于diff中涉及修改的每个文件调用 read_file 工具我们需要另一个MCP Server或扩展当前Server来提供文件读取能力来获取其当前内容或变更前后的内容如果工具支持。 5. **深度审查**基于完整的代码上下文和变更内容进行多维度分析 a. **功能性**变更是否实现了PR描述中的需求逻辑是否正确 b. **代码质量**命名是否清晰函数是否过于冗长有无重复代码 c. **安全性**有无潜在的安全漏洞如SQL注入、XSS d. **性能**有无可能引起性能退化的改动如循环内的重复计算、N1查询 e. **可测试性**是否添加或更新了相应的测试 f. **一致性**是否符合项目的代码风格和架构约定 6. **生成报告**将审查发现的问题归类如【阻塞项】、【建议】、【表扬】并为每个问题指明具体的文件、行号以及清晰的修改建议。 7. **记录与输出**调用 log_review 工具记录本次审查概要。最后将完整的审查报告以清晰的Markdown格式输出给用户。 请记住你的目标是提供建设性、具体的反馈帮助开发者提升代码质量。这个指令集定义了Agent的骨架。当你在Claude Code中给出这个指令并告诉它“请审查仓库myorg/myrepo下的PR #123”它就会开始尝试调用你提供的工具一步步执行。你可能会发现Claude在调用工具时参数传递或结果解析上需要更精确的引导这需要反复调试和优化你的指令以及工具接口的设计。5. 进阶优化从基础审查到智能体协作基础框架跑通后我们可以追求更“优雅”和强大。5.1 集成专业代码分析工具让Claude去做所有的代码风格和静态检查是低效的。我们应该集成专业的工具让AI做它擅长的高级抽象分析而让专业工具做它们擅长的模式匹配。我们可以创建或集成一个linter-mcp-server。这个Server内部封装了对ESLintJavaScript、PylintPython、CheckstyleJava等工具的命令行调用。它提供一个run_lint工具接收文件路径或代码片段返回结构化的lint结果。然后在我们的审查工作流中在第5步“深度审查”之前或之后加入一个步骤“调用run_lint工具对变更文件进行静态检查并将结果纳入考量”。这样Agent就能结合精准的规则检查来自linter和深度的逻辑理解来自Claude给出更全面的报告。5.2 实现自动化触发与评论目前我们的Agent需要手动在Claude Code中触发。要实现真正的自动化我们需要将其部署为一个持续运行的服务并通过GitHub Webhook或GitHub Actions来触发。方案一基于GitHub Actions将我们的cr-assistant-mcp-server以及核心的Agent指令脚本打包。创建一个GitHub Actions工作流文件.github/workflows/cr-assistant.yml。在工作流中配置在pull_request事件触发时运行。在Action的Job中安装Node.js环境启动我们的MCP Server然后运行一个Node.js脚本。这个脚本的核心作用是“模拟”Claude Code的环境它需要能够与MCP Server通信并执行一个“硬编码”的、包含上述审查工作流的Claude调用这可能需要使用Anthropic的API SDK如anthropic-ai/sdk直接调用Claude模型并模拟工具调用流程。脚本获取Claude生成的审查报告后使用GitHub Token通过GitHub API将评论提交到PR中。方案二部署为常驻服务将整个系统MCP Server Agent逻辑部署到一台服务器或云函数上。在GitHub仓库设置中配置一个Webhook指向我们服务的API端点。当PR事件发生时GitHub会发送Payload到我们的服务。我们的服务处理Payload启动审查流程最后通过GitHub API提交评论。方案一更简单直接利用GitHub的生态系统方案二更灵活可以管理更复杂的状态和上下文。对于初创项目从GitHub Actions开始是更佳选择。5.3 上下文管理与成本优化Claude模型有上下文窗口限制例如200K tokens。一个大型PR的diff加上多个文件的完整内容很容易超出限制。因此我们的Agent需要具备“上下文管理”的智慧智能摘要在获取文件内容后可以先让Claude对每个文件生成一个简短摘要例如“这个文件是用户认证模块的主控制器包含login、logout、register三个主要函数”而不是将全部原始代码塞入上下文。优先级加载优先加载与变更行直接相关的文件如被修改的文件对于间接相关的依赖文件仅在Claude认为有必要深入分析时才按需加载。分阶段审查对于非常大的PR可以设计Agent将其按模块或目录拆分成多个子任务进行分批审查。此外每次调用Claude API都有成本。我们需要在工具调用设计上追求高效避免无意义的来回对话。例如将“获取diff”、“读取文件A”、“读取文件B”等多个工具调用请求尽可能合并到一次Claude对话中完成而不是每个操作都发起一次新的、昂贵的模型调用。6. 避坑指南与实战心得在搭建和调试这个CR助手的过程中我踩过不少坑这里分享一些关键的经验教训。6.1 MCP Server开发的常见陷阱工具描述必须精确在capabilities.tools中定义工具时inputSchema必须严格按照JSON Schema格式准确描述参数。一个常见的错误是参数类型定义错误比如应该是string却写成了integer这会导致Claude在调用时传参失败而你从日志里可能只看到一个模糊的错误。错误处理与响应格式MCP协议要求工具调用响应必须遵循特定格式。即使工具执行出错你也必须返回一个格式正确的响应并将isError设为true同时在content中提供错误信息。如果Server直接抛出未捕获的异常整个连接可能会中断。stdio传输的阻塞问题MCP Server使用标准输入输出与客户端通信。这意味着你的Server必须是异步的、事件驱动的不能有长时间的同步阻塞操作。例如在一个工具处理函数中执行一个耗时很长的同步计算会阻塞后续所有请求。务必使用异步I/O或将耗时任务放到Worker线程中。6.2 Claude指令设计的艺术明确工具调用边界在给Claude的指令中要清晰地告诉它“什么时候该调用工具”。例如“当你需要知道PR的具体修改时请调用get_pr_diff工具并提供owner、repo、pull_number参数”。过于模糊的指令会导致Claude犹豫不决或错误调用。结构化输出引导如果你希望Claude输出一个结构化的报告比如Markdown表格最好在指令中给出一个明确的示例模板。这比单纯说“请用Markdown格式输出”要有效得多。处理模型的“臆想”有时Claude可能会“幻想”出一些不存在的工具或参数。你需要在指令开头就明确列出所有可用的工具及其精确用法并强调“仅可使用以下工具”。6.3 集成到CI/CD时的权限与网络问题GitHub Token权限在GitHub Actions中运行时使用的GITHUB_TOKEN默认权限是有限的。你需要确保它在仓库设置中拥有“内容读写”contents: write权限才能发布PR评论。对于访问私有仓库或其他组织仓库可能需要配置更精细的Personal Access Token或GitHub App。网络出口与API访问如果你的Runner在防火墙后或者Anthropic API被限制访问会导致整个流程失败。确保你的运行环境可以稳定访问api.anthropic.com以及GitHub API。超时与重试代码审查可能很耗时特别是对于大PR。GitHub Actions有默认的超时限制6小时单个Job也有时间限制。你的脚本需要设置合理的超时和重试机制并考虑将超长PR的审查拆分成多个Job。6.4 效果评估与迭代第一个版本的效果可能不尽如人意。它可能会漏报一些重要问题或者对某些代码变更产生误报尤其是涉及复杂业务逻辑时。不要期望一蹴而就。建立一个迭代机制收集反馈在团队内部小范围试用让开发者对AI生成的评论进行“评价”有用/无用或直接修改。分析案例定期查看哪些评论被采纳了哪些被忽略了。分析漏报和误报的案例。优化指令与工具根据分析结果不断细化你的System Prompt。例如如果发现Agent经常误判性能问题可以在指令中增加更具体的性能审查指南或者集成一个专门的性能模式检测工具。设定边界明确告诉团队这个助手的能力范围。它擅长发现代码异味、潜在bug模式和基础规范问题但对于深层的架构决策和复杂的业务逻辑正确性仍然需要人类专家把关。它应该是一个“初级审查员”或“辅助员”而不是最终决策者。搭建这样一个CR助手的过程本身就是一个对AI Agent、MCP协议以及软件工程实践深入理解的过程。它不会完全取代人工审查但能极大地消除审查中的枯燥劳动让人类开发者可以聚焦于那些真正需要创造力和深度思考的部分。当你看到它第一次自动在团队的PR下留下一条精准、有用的评论时那种成就感正是驱动我们不断探索技术边界的乐趣所在。