1. 项目概述当Claude Code遇上长会话与多Agent协作最近在深度使用Claude Code进行一些复杂的代码重构和系统设计时我遇到了一个几乎所有深度用户都会碰到的天花板上下文窗口Context Window的极限。那个熟悉的错误提示api error: 400 this models maximum context length is...就像一堵墙提醒我单次会话的容量是有限的。更棘手的是当我想引入更多MCPModel Context Protocol服务器来增强Claude Code的能力比如连接数据库、调用外部API或者让多个Agent如代码分析Agent、文档生成Agent分工协作时整个提示词Prompt的设计逻辑就完全变了。这不再是一个简单的“问与答”而是一个需要精心设计的协作系统。核心矛盾在于有限的上下文窗口既要承载漫长的对话历史代码变更、讨论决策又要为多个专业Agent提供清晰的指令和上下文还要能灵活接入各种MCP工具。如果提示词写得不好轻则Agent理解偏差、各干各的重则直接触发上下文溢出对话中断前功尽弃。因此这个项目的核心就是解决在Claude Code的中长会话场景下如何设计提示词来高效地管理和协调多个Agent分工并充分利用MCP扩展能力。这不仅仅是写几句指令而是构建一套可持续、可扩展的交互协议。下面我将结合自己踩过的无数坑拆解其中的设计思路、实操要点和避坑指南。2. 核心理念与架构设计从单次对话到协作系统当我们从单次代码问答转向中长周期的项目协作时思维必须升级。你不能指望一个万能提示词从头用到尾而是需要建立一个分层、模块化、状态可维护的提示词体系。2.1 理解“中长会话”的独特挑战Claude Code的会话一旦开启其上下文就像一块不断写入的白板。对于中长会话例如持续数天、涉及多个功能模块开发的项目挑战主要来自三个方面上下文稀释与污染早期关于项目架构的讨论、已经解决的Bug记录、被废弃的代码片段都会占据宝贵的Token。随着会话进行模型需要从海量历史中精准定位当前任务的相关信息难度指数级上升。目标漂移会话开始时目标是“搭建用户认证模块”三天后可能已经在讨论“认证模块与支付系统的接口设计”。如果没有清晰的导航模型容易迷失在细节中忘记核心目标。工具MCP与代理Agent的集成复杂度每接入一个MCP服务器如tavily-mcp用于搜索brave-search-mcp作为备选或自定义的数据库查询MCP就等于为模型增加了一套“外设”。如何让模型知道在什么场景下调用哪个工具多个工具输出结果如何整合进对话流2.2 多Agent分工协作的范式转变“Agent分工”在这里不是指运行多个Claude实例而是在同一个Claude Code会话中通过提示词定义不同的“角色”或“职责模式”让模型在不同任务间切换身份。例如架构师Agent负责高层设计、技术选型。工程师Agent负责具体编码、实现细节。审查员Agent负责代码审查、寻找潜在问题。测试员Agent负责编写测试用例。传统的单角色提示词是“你是一个全栈开发助手”。而现在我们需要的是“根据当前任务阶段请你切换到‘架构师’模式评估以下方案...” 或者 “现在进入‘代码审查’模式请聚焦于代码风格和潜在性能问题...”这种模式切换的核心依赖于提示词对会话状态的显式管理和引导。2.3 系统架构设计提示词作为调度中枢基于以上挑战我设计的提示词系统架构通常包含以下几个层次系统级提示词一次性注入在会话最开始定义根本规则、可用MCP工具列表、Agent角色定义以及最重要的——状态记录和更新的协议。这部分要尽可能精炼但定义清晰。阶段导航提示词周期性使用在关键节点如一天开始、一个模块完成后使用用于总结上一阶段、明确下一阶段目标、清理无关上下文通过引导模型摘要化历史。任务执行提示词高频使用针对具体任务明确指定使用哪个Agent角色、调用哪个MCP工具、输入输出格式。状态同步与摘要提示词维护性使用定期要求模型对当前项目状态、关键决策、待办事项进行摘要并将这个摘要作为后续对话的“锚点”替代冗长的原始历史。这个架构的核心目标是将长会话“切片”成多个有状态的短会话并通过明确的协议将它们串联起来。3. 核心提示词模块拆解与编写实战理论说完我们来点实在的。下面我将拆解几个核心提示词模块并给出可直接复用的范例和编写逻辑。3.1 系统级初始化提示词这是对话的“宪法”必须在项目开始时清晰设定。它不应该包含具体的项目细节而是定义协作的规则。范例与解析# 项目协作协议 v1.2 ## 核心原则 1. **状态驱动**本对话将维护一个“项目状态”对象。在任何任务开始前我会先同步或询问状态。 2. **角色扮演**我将通过指令如[角色架构师]来指定你的当前职责。请严格遵循该角色的知识范围和关注点。 3. **工具调用**已安装并配置以下MCP服务器供你调用 * search-web: 用于通用网络搜索Tavily。 * search-code: 用于在特定代码仓库中搜索可选。 * sql-query: 用于查询项目数据库需我提供凭证。 * doc-generator: 根据代码生成API文档。 * diagram-tool: 生成架构图或流程图。 调用工具时请清晰说明原因和所需参数。 4. **上下文管理**当对话历史过长时我会提示“**请摘要当前进度**”。你的摘要应包含核心目标、已完成模块、当前阻塞、下一步计划。此摘要将替代部分历史。 ## 角色定义 * **架构师**关注技术选型、系统边界、数据流、非功能性需求性能、安全、扩展性。避免深入具体语法。 * **工程师**关注代码实现、API设计、具体库的使用、错误处理、单元测试。提供可运行的代码片段。 * **审查员**关注代码风格一致性、潜在Bug、性能瓶颈、安全漏洞、是否符合既定架构。不提供新实现只评述。 * **测试员**关注测试用例的覆盖率、边界条件、模拟数据、测试框架的使用。 ## 输出格式约定 * 代码块必须指定语言。 * 关键决策点请用 **决策** ...格式记录。 * 待办事项请用- [ ] 列表管理。 * 调用工具请求格式[工具调用工具名] 请求描述 参数JSON格式。 请确认你已理解本协议。我们的第一个任务是初始化项目状态。编写要点与心得版本号加上v1.2很有用当你想调整协议时可以明确指出版本升级避免混淆。工具列表动态更新如果你中途新增了MCP服务器一定要在对话中正式“更新协议”让模型重新确认可用工具集。角色定义要具体避免“专家”、“助手”这种泛称。用“关注...避免...”的句式明确边界防止角色越界。例如明确告诉“审查员”不提供新实现可以避免它在你要求审查时自作主张重写代码。格式约定是金科玉律统一的格式如决策块、TODO列表能让信息结构化便于后期从历史中快速检索关键信息也是对抗上下文稀释的有效手段。3.2 状态维护与导航提示词这是保证长会话不迷失的关键。状态维护不是模型的自动行为需要你主动通过提示词来引导。范例1每日站会式同步**[状态同步2024-05-17 晨会]** **当前项目状态摘要由你更新** 项目名称电商平台用户服务重构 核心目标将单体中的用户模块拆分为独立微服务包含登录、注册、资料管理。 昨日完成 1. 使用Spring Boot搭建了项目基础骨架。 2. 实现了User实体、Repository层和基础的Service层。 3. 通过sql-query工具确认了旧数据库表结构。 当前阻塞 1. 新旧系统数据迁移策略未最终确定。 2. JWT令牌与现有网关的集成细节需要确认。 今日计划 1. [优先级高] 确定数据迁移方案双写一次性迁移。 2. [优先级中] 实现JWT生成与验证的过滤器。 3. [优先级低] 编写第一个API端点用户查询的控制器。 **请根据以上对话历史更新并确认上述状态摘要。确认后我们将首先处理[优先级高]的任务。**范例2阶段切换与上下文清理**[阶段切换从“基础搭建”进入“业务逻辑实现”]** 上一个阶段“项目基础搭建”已结束主要产出为Spring Boot项目初始化、Maven依赖配置、数据库连接池设置、基础包结构。 现在我们将进入“业务逻辑实现”阶段。本阶段的核心是完成用户注册、登录的核心流程。 **为了聚焦新阶段请执行以下操作** 1. 将上一阶段的最终产出如关键配置代码、目录结构浓缩为一个不超过300字的简要描述。 2. 基于此简要描述和上述阶段目标遗忘上一阶段的具体讨论过程如关于某个依赖版本的争论。 3. 你的知识背景应调整为我们已经有一个配置好的Spring Boot Web项目现在需要开始写业务代码。 请确认阶段切换完成并请求下一步指令。实操心得定时触发养成习惯在每天开始工作、每次解决一个重大阻塞后主动进行状态同步。这相当于给对话设置了“存档点”。引导模型摘要指令要明确。“请摘要”比“我们说到哪了”更有效。要求它输出结构化的摘要你之后可以直接引用这个摘要而不是翻几百行历史。主动“遗忘”明确告诉模型可以“遗忘”讨论过程只记住结论和产出。这是人工管理上下文的最直接方式能有效节省Token。状态对象化高级用法是将状态维护成一个可操作的JSON对象。你可以要求模型“将当前状态输出为一个JSON包含goal,completed,blockers,nextSteps字段。” 下次同步时直接提供这个JSON让它更新。这使状态机器可读、可编程。3.3 多Agent角色调度提示词当需要切换模型“人格”以执行特定任务时提示词必须清晰、有强制性。范例1调用架构师Agent进行设计评审[角色架构师] [背景切换当前处于“业务逻辑实现”阶段正在处理用户登录流程。我们计划使用Spring Security JWT。] **任务技术方案评审** 现有工程师Agent提出了一个初步方案 java // 简化的JWT过滤器方案 public class JwtFilter extends OncePerRequestFilter { Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws ... { // 从Header取Token // 用硬编码的Secret验证并解析 // 将用户信息存入SecurityContext } }以及一个简单的UserDetailsService实现。请以架构师视角评审这个方案与项目既定的“与API网关集成”的目标是否一致是否存在重复认证硬编码Secret的安全性如何配置管理方案是什么这个过滤器的性能考量如Token解析开销和扩展性如何支持多密钥或密钥轮转是否需要考虑防重放攻击等安全机制请聚焦于架构层面问题暂不深入代码优化。**范例2调用审查员Agent进行代码审查**[角色审查员] [上下文这是工程师Agent刚刚实现的用户注册Service方法。]任务代码审查审查以下代码重点关注代码风格是否符合项目约定的命名、格式。潜在Bug空指针、事务边界、异常处理。性能与安全密码存储、输入验证、数据库查询效率。是否符合架构是否遵循分层架构职责是否清晰。Service public class UserServiceImpl implements UserService { Autowired private UserRepository userRepo; Autowired private PasswordEncoder encoder; public User register(UserRegistrationDto dto) { if(userRepo.findByUsername(dto.getUsername()) ! null) { throw new UsernameExistsException(); } User user new User(); user.setUsername(dto.getUsername()); user.setPassword(encoder.encode(dto.getPassword())); // 注意这里 user.setEmail(dto.getEmail()); return userRepo.save(user); } }请逐项列出发现的问题和建议。**调度技巧** * **[角色XXX]作为强制开关**把这个标签放在请求的最开头非常醒目能有效重置模型的“思维焦点”。 * **提供明确的评审清单**告诉审查员“关注什么”可以避免它跑偏去讨论业务逻辑设计。清单就是它的工作指引。 * **背景切换**[背景切换...]是一个快速同步上下文的小技巧比复述一大段历史高效得多。它告诉模型“请基于这个新背景思考而不是之前的所有对话。” ### 3.4 MCP工具集成与调用提示词 让模型学会在合适的时候调用合适的工具需要你在提示词中做好“工具教育”和“调用示范”。 **范例引导模型使用搜索工具解决具体问题**[角色工程师] 我们正在实现JWT密钥的管理。架构师建议不从代码硬编码而是从外部配置或环境变量读取。但我对Spring Boot中如何安全地管理JWT密钥的最佳实践不太确定。请执行以下步骤分析需求我们需要一个方案能在application.yml或环境变量中配置密钥并在运行时注入到JWT工具类中同时考虑生产环境的密钥轮换。知识缺口我不确定Spring Boot对此是否有官方推荐方式以及如何与jjwt库结合。工具调用请使用search-web工具搜索以下关键词组合首选关键词Spring Boot JWT secret configuration best practices external备选关键词jjwt Value environment variable Spring Security限制请优先查找近两年2022年后的Stack Overflow或官方博客如Baeldung, Spring.io内容。整合建议基于搜索结果提供一个简洁的方案概述并给出关键配置代码片段示例。请开始第一步分析并在需要时调用工具。**编写逻辑与注意事项** * **不要假设模型会主动用工具**你必须明确指令它去用。更好的方式是在系统协议里就约定“遇到不确定的知识应优先考虑调用搜索工具”。 * **教它如何搜索**模型不一定知道用什么关键词最有效。你可以示范告诉它“首选关键词”、“备选关键词”、“来源限制”。这能大幅提高搜索结果的可用性。 * **工具调用结果的处理**要指示模型如何汇报结果。例如“请摘要搜索结果的三个主要观点并引用来源。” 避免它直接把一大段网页HTML扔进对话那会瞬间污染上下文。 * **错误处理**在提示词中可以加入“如果search-web工具调用失败或结果不理想请告知我我们可以尝试调整关键词或切换至brave-search-mcp。” ## 4. 中长会话提示词的生命周期管理 有了这些模块如何在实际项目中串联使用以下是一个典型的工作流展示了提示词如何随时间演变和协作。 ### 4.1 项目启动阶段奠基与协议确认 1. **输入系统级初始化提示词**建立协作基础规则。 2. 进行简短的**项目目标对齐**对话并用状态同步提示词产出第一版项目状态摘要。 3. **确认所有MCP连接正常**可以通过一个小任务测试工具调用如“请用search-web查一下‘Spring Boot 3的最新特性’”。 ### 4.2 日常开发循环导航、执行、同步 这是一个循环往复的过程构成了日常工作的主干[每日开始] - [状态同步提示词] - [明确当日首要任务] - [进入特定Agent角色执行任务] - [遇到问题调用MCP工具] - [完成任务产出代码/文档] - [微型状态同步记录完成项] - [切换至下一个任务/角色] - ... - [每日结束进行完整状态同步与摘要]**关键点**在每个任务边界和角色切换处都使用明确的提示词进行“上下文重置”确保思维聚焦。 ### 4.3 关键决策点存档与转向 当遇到技术选型、方案评审等重大决策时 1. 使用[角色架构师]提示词发起深度讨论。 2. 将讨论中的核心论点和最终**决策**用约定的格式 **决策** ...明确记录下来。 3. 在后续的状态同步中**重点引用这些决策记录**而不是讨论过程。这相当于创建了项目的“决策日志”价值极高。 ### 4.4 会话维护与“重启”策略 即使有良好的状态管理会话最终仍可能逼近上下文极限。此时需要“软重启” 1. 发起一个**终极摘要请求**“请为当前项目生成一份全面的摘要报告包括项目概述、架构图文字描述、已完成的所有模块清单、所有重要决策列表、当前状态、剩余工作清单、以及遇到的已知问题。” 2. 将这个摘要报告复制出来。 3. **开启一个新的Claude Code会话**。 4. 在新会话中首先粘贴**系统级初始化提示词**可能需要根据项目进展微调。 5. 接着粘贴上一会话的**终极摘要报告**并附言“这是之前项目的完整状态。我们在此基础上继续。当前首要任务是[从摘要中的‘下一步计划’里选一项]”。 6. 这样你就在新会话中继承了几乎所有关键上下文而舍弃了庞杂的过程性对话。Token用量重置但项目记忆得以保留。 ## 5. 常见陷阱、排查技巧与高级策略 在实际操作中你会遇到各种问题。下面是一些实录的坑和解决方案。 ### 5.1 常见问题速查表 | 问题现象 | 可能原因 | 排查与解决思路 | | :--- | :--- | :--- | | 模型忽略角色指令回答泛泛 | 1. 角色定义不够具体边界模糊。br2. 提示词中角色指令位置不突出。br3. 上下文历史过长早期指令被稀释。 | 1. 强化角色定义使用“作为XX你应关注A避免讨论B”句式。br2. 将[角色XXX]置于请求最前单独成行。br3. 执行状态同步摘要历史刷新上下文。 | | 频繁触发 context length 错误 | 1. 会话历史确实已满。br2. MCP工具返回了过长的内容如整页网页。br3. 模型生成了过于冗长的回答。 | 1. 执行“会话维护与重启策略”。br2. 在工具调用提示词中要求模型“摘要结果只提取关键信息”。br3. 在请求中明确要求“回答请尽量简洁聚焦要点”。 | | 模型不主动调用MCP工具 | 1. 系统提示词中工具描述不清晰。br2. 模型不确定何时该调用工具。br3. 工具调用格式复杂。 | 1. 在系统提示词中列举工具并附上简单用例。br2. 在任务提示词中明确指示“若需要XX信息请调用YY工具”。br3. 简化调用格式或提供调用模板。 | | 多个Agent间工作记忆断裂 | 1. 切换角色时没有提供足够的背景。br2. 状态同步不及时不同角色对项目进度认知不一致。 | 1. 使用[背景切换...]快速同步上下文。br2. 在任何角色执行任务前先同步一次精简版项目状态“基于我们已完成的A现在要做B”。 | | 决策点记录混乱后期遗忘 | 1. 没有统一的决策记录格式。br2. 决策散落在长篇对话中。 | 1. 强制使用 **决策**格式。br2. 定期使用提示词“请梳理本次对话以来所有标记为**决策**的内容列表输出。” | ### 5.2 高级策略实现动态上下文窗口 对于超长周期项目可以尝试更精细的策略 **“三段式”上下文管理** 1. **活跃上下文**最近几次的问答关于当前正在进行的任务。保持完整。 2. **摘要上下文**项目的状态摘要、决策日志、架构图。定期更新始终保留。 3. **归档上下文**过去已完成的模块的详细讨论。将其移出主会话必要时通过搜索工具如本地的代码向量库MCP按需检索。 在提示词中可以这样实现“关于‘用户认证模块’的详细设计讨论已于三天前结束并归档。当前活跃上下文仅包含‘订单模块’的相关讨论。如需回顾认证模块细节请提示我我可使用code-search工具查找当时的决策记录。” ### 5.3 提示词版本化与迭代 你的系统级提示词不是一成不变的。随着项目推进和团队协作习惯的形成你应该迭代它。 * **建立提示词库**将好的任务提示词、角色提示词保存为模板。 * **A/B测试**对于同一类任务如代码审查尝试两种不同风格的提示词看哪个效果更好。 * **收集反馈**观察模型在哪些指令下执行得更好哪些指令它容易误解。反过来优化你的提示词。 最终你会发现管理Claude Code的长会话和多Agent协作其本质是**通过精心设计的提示词将一个生成式AI模型编程成一个具有状态管理、角色调度和工具调用能力的可预测系统**。这个过程本身就是最硬核的提示词工程。 Claude Code长会话多Agent协作：提示词工程与MCP工具集成实战
1. 项目概述当Claude Code遇上长会话与多Agent协作最近在深度使用Claude Code进行一些复杂的代码重构和系统设计时我遇到了一个几乎所有深度用户都会碰到的天花板上下文窗口Context Window的极限。那个熟悉的错误提示api error: 400 this models maximum context length is...就像一堵墙提醒我单次会话的容量是有限的。更棘手的是当我想引入更多MCPModel Context Protocol服务器来增强Claude Code的能力比如连接数据库、调用外部API或者让多个Agent如代码分析Agent、文档生成Agent分工协作时整个提示词Prompt的设计逻辑就完全变了。这不再是一个简单的“问与答”而是一个需要精心设计的协作系统。核心矛盾在于有限的上下文窗口既要承载漫长的对话历史代码变更、讨论决策又要为多个专业Agent提供清晰的指令和上下文还要能灵活接入各种MCP工具。如果提示词写得不好轻则Agent理解偏差、各干各的重则直接触发上下文溢出对话中断前功尽弃。因此这个项目的核心就是解决在Claude Code的中长会话场景下如何设计提示词来高效地管理和协调多个Agent分工并充分利用MCP扩展能力。这不仅仅是写几句指令而是构建一套可持续、可扩展的交互协议。下面我将结合自己踩过的无数坑拆解其中的设计思路、实操要点和避坑指南。2. 核心理念与架构设计从单次对话到协作系统当我们从单次代码问答转向中长周期的项目协作时思维必须升级。你不能指望一个万能提示词从头用到尾而是需要建立一个分层、模块化、状态可维护的提示词体系。2.1 理解“中长会话”的独特挑战Claude Code的会话一旦开启其上下文就像一块不断写入的白板。对于中长会话例如持续数天、涉及多个功能模块开发的项目挑战主要来自三个方面上下文稀释与污染早期关于项目架构的讨论、已经解决的Bug记录、被废弃的代码片段都会占据宝贵的Token。随着会话进行模型需要从海量历史中精准定位当前任务的相关信息难度指数级上升。目标漂移会话开始时目标是“搭建用户认证模块”三天后可能已经在讨论“认证模块与支付系统的接口设计”。如果没有清晰的导航模型容易迷失在细节中忘记核心目标。工具MCP与代理Agent的集成复杂度每接入一个MCP服务器如tavily-mcp用于搜索brave-search-mcp作为备选或自定义的数据库查询MCP就等于为模型增加了一套“外设”。如何让模型知道在什么场景下调用哪个工具多个工具输出结果如何整合进对话流2.2 多Agent分工协作的范式转变“Agent分工”在这里不是指运行多个Claude实例而是在同一个Claude Code会话中通过提示词定义不同的“角色”或“职责模式”让模型在不同任务间切换身份。例如架构师Agent负责高层设计、技术选型。工程师Agent负责具体编码、实现细节。审查员Agent负责代码审查、寻找潜在问题。测试员Agent负责编写测试用例。传统的单角色提示词是“你是一个全栈开发助手”。而现在我们需要的是“根据当前任务阶段请你切换到‘架构师’模式评估以下方案...” 或者 “现在进入‘代码审查’模式请聚焦于代码风格和潜在性能问题...”这种模式切换的核心依赖于提示词对会话状态的显式管理和引导。2.3 系统架构设计提示词作为调度中枢基于以上挑战我设计的提示词系统架构通常包含以下几个层次系统级提示词一次性注入在会话最开始定义根本规则、可用MCP工具列表、Agent角色定义以及最重要的——状态记录和更新的协议。这部分要尽可能精炼但定义清晰。阶段导航提示词周期性使用在关键节点如一天开始、一个模块完成后使用用于总结上一阶段、明确下一阶段目标、清理无关上下文通过引导模型摘要化历史。任务执行提示词高频使用针对具体任务明确指定使用哪个Agent角色、调用哪个MCP工具、输入输出格式。状态同步与摘要提示词维护性使用定期要求模型对当前项目状态、关键决策、待办事项进行摘要并将这个摘要作为后续对话的“锚点”替代冗长的原始历史。这个架构的核心目标是将长会话“切片”成多个有状态的短会话并通过明确的协议将它们串联起来。3. 核心提示词模块拆解与编写实战理论说完我们来点实在的。下面我将拆解几个核心提示词模块并给出可直接复用的范例和编写逻辑。3.1 系统级初始化提示词这是对话的“宪法”必须在项目开始时清晰设定。它不应该包含具体的项目细节而是定义协作的规则。范例与解析# 项目协作协议 v1.2 ## 核心原则 1. **状态驱动**本对话将维护一个“项目状态”对象。在任何任务开始前我会先同步或询问状态。 2. **角色扮演**我将通过指令如[角色架构师]来指定你的当前职责。请严格遵循该角色的知识范围和关注点。 3. **工具调用**已安装并配置以下MCP服务器供你调用 * search-web: 用于通用网络搜索Tavily。 * search-code: 用于在特定代码仓库中搜索可选。 * sql-query: 用于查询项目数据库需我提供凭证。 * doc-generator: 根据代码生成API文档。 * diagram-tool: 生成架构图或流程图。 调用工具时请清晰说明原因和所需参数。 4. **上下文管理**当对话历史过长时我会提示“**请摘要当前进度**”。你的摘要应包含核心目标、已完成模块、当前阻塞、下一步计划。此摘要将替代部分历史。 ## 角色定义 * **架构师**关注技术选型、系统边界、数据流、非功能性需求性能、安全、扩展性。避免深入具体语法。 * **工程师**关注代码实现、API设计、具体库的使用、错误处理、单元测试。提供可运行的代码片段。 * **审查员**关注代码风格一致性、潜在Bug、性能瓶颈、安全漏洞、是否符合既定架构。不提供新实现只评述。 * **测试员**关注测试用例的覆盖率、边界条件、模拟数据、测试框架的使用。 ## 输出格式约定 * 代码块必须指定语言。 * 关键决策点请用 **决策** ...格式记录。 * 待办事项请用- [ ] 列表管理。 * 调用工具请求格式[工具调用工具名] 请求描述 参数JSON格式。 请确认你已理解本协议。我们的第一个任务是初始化项目状态。编写要点与心得版本号加上v1.2很有用当你想调整协议时可以明确指出版本升级避免混淆。工具列表动态更新如果你中途新增了MCP服务器一定要在对话中正式“更新协议”让模型重新确认可用工具集。角色定义要具体避免“专家”、“助手”这种泛称。用“关注...避免...”的句式明确边界防止角色越界。例如明确告诉“审查员”不提供新实现可以避免它在你要求审查时自作主张重写代码。格式约定是金科玉律统一的格式如决策块、TODO列表能让信息结构化便于后期从历史中快速检索关键信息也是对抗上下文稀释的有效手段。3.2 状态维护与导航提示词这是保证长会话不迷失的关键。状态维护不是模型的自动行为需要你主动通过提示词来引导。范例1每日站会式同步**[状态同步2024-05-17 晨会]** **当前项目状态摘要由你更新** 项目名称电商平台用户服务重构 核心目标将单体中的用户模块拆分为独立微服务包含登录、注册、资料管理。 昨日完成 1. 使用Spring Boot搭建了项目基础骨架。 2. 实现了User实体、Repository层和基础的Service层。 3. 通过sql-query工具确认了旧数据库表结构。 当前阻塞 1. 新旧系统数据迁移策略未最终确定。 2. JWT令牌与现有网关的集成细节需要确认。 今日计划 1. [优先级高] 确定数据迁移方案双写一次性迁移。 2. [优先级中] 实现JWT生成与验证的过滤器。 3. [优先级低] 编写第一个API端点用户查询的控制器。 **请根据以上对话历史更新并确认上述状态摘要。确认后我们将首先处理[优先级高]的任务。**范例2阶段切换与上下文清理**[阶段切换从“基础搭建”进入“业务逻辑实现”]** 上一个阶段“项目基础搭建”已结束主要产出为Spring Boot项目初始化、Maven依赖配置、数据库连接池设置、基础包结构。 现在我们将进入“业务逻辑实现”阶段。本阶段的核心是完成用户注册、登录的核心流程。 **为了聚焦新阶段请执行以下操作** 1. 将上一阶段的最终产出如关键配置代码、目录结构浓缩为一个不超过300字的简要描述。 2. 基于此简要描述和上述阶段目标遗忘上一阶段的具体讨论过程如关于某个依赖版本的争论。 3. 你的知识背景应调整为我们已经有一个配置好的Spring Boot Web项目现在需要开始写业务代码。 请确认阶段切换完成并请求下一步指令。实操心得定时触发养成习惯在每天开始工作、每次解决一个重大阻塞后主动进行状态同步。这相当于给对话设置了“存档点”。引导模型摘要指令要明确。“请摘要”比“我们说到哪了”更有效。要求它输出结构化的摘要你之后可以直接引用这个摘要而不是翻几百行历史。主动“遗忘”明确告诉模型可以“遗忘”讨论过程只记住结论和产出。这是人工管理上下文的最直接方式能有效节省Token。状态对象化高级用法是将状态维护成一个可操作的JSON对象。你可以要求模型“将当前状态输出为一个JSON包含goal,completed,blockers,nextSteps字段。” 下次同步时直接提供这个JSON让它更新。这使状态机器可读、可编程。3.3 多Agent角色调度提示词当需要切换模型“人格”以执行特定任务时提示词必须清晰、有强制性。范例1调用架构师Agent进行设计评审[角色架构师] [背景切换当前处于“业务逻辑实现”阶段正在处理用户登录流程。我们计划使用Spring Security JWT。] **任务技术方案评审** 现有工程师Agent提出了一个初步方案 java // 简化的JWT过滤器方案 public class JwtFilter extends OncePerRequestFilter { Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws ... { // 从Header取Token // 用硬编码的Secret验证并解析 // 将用户信息存入SecurityContext } }以及一个简单的UserDetailsService实现。请以架构师视角评审这个方案与项目既定的“与API网关集成”的目标是否一致是否存在重复认证硬编码Secret的安全性如何配置管理方案是什么这个过滤器的性能考量如Token解析开销和扩展性如何支持多密钥或密钥轮转是否需要考虑防重放攻击等安全机制请聚焦于架构层面问题暂不深入代码优化。**范例2调用审查员Agent进行代码审查**[角色审查员] [上下文这是工程师Agent刚刚实现的用户注册Service方法。]任务代码审查审查以下代码重点关注代码风格是否符合项目约定的命名、格式。潜在Bug空指针、事务边界、异常处理。性能与安全密码存储、输入验证、数据库查询效率。是否符合架构是否遵循分层架构职责是否清晰。Service public class UserServiceImpl implements UserService { Autowired private UserRepository userRepo; Autowired private PasswordEncoder encoder; public User register(UserRegistrationDto dto) { if(userRepo.findByUsername(dto.getUsername()) ! null) { throw new UsernameExistsException(); } User user new User(); user.setUsername(dto.getUsername()); user.setPassword(encoder.encode(dto.getPassword())); // 注意这里 user.setEmail(dto.getEmail()); return userRepo.save(user); } }请逐项列出发现的问题和建议。**调度技巧** * **[角色XXX]作为强制开关**把这个标签放在请求的最开头非常醒目能有效重置模型的“思维焦点”。 * **提供明确的评审清单**告诉审查员“关注什么”可以避免它跑偏去讨论业务逻辑设计。清单就是它的工作指引。 * **背景切换**[背景切换...]是一个快速同步上下文的小技巧比复述一大段历史高效得多。它告诉模型“请基于这个新背景思考而不是之前的所有对话。” ### 3.4 MCP工具集成与调用提示词 让模型学会在合适的时候调用合适的工具需要你在提示词中做好“工具教育”和“调用示范”。 **范例引导模型使用搜索工具解决具体问题**[角色工程师] 我们正在实现JWT密钥的管理。架构师建议不从代码硬编码而是从外部配置或环境变量读取。但我对Spring Boot中如何安全地管理JWT密钥的最佳实践不太确定。请执行以下步骤分析需求我们需要一个方案能在application.yml或环境变量中配置密钥并在运行时注入到JWT工具类中同时考虑生产环境的密钥轮换。知识缺口我不确定Spring Boot对此是否有官方推荐方式以及如何与jjwt库结合。工具调用请使用search-web工具搜索以下关键词组合首选关键词Spring Boot JWT secret configuration best practices external备选关键词jjwt Value environment variable Spring Security限制请优先查找近两年2022年后的Stack Overflow或官方博客如Baeldung, Spring.io内容。整合建议基于搜索结果提供一个简洁的方案概述并给出关键配置代码片段示例。请开始第一步分析并在需要时调用工具。**编写逻辑与注意事项** * **不要假设模型会主动用工具**你必须明确指令它去用。更好的方式是在系统协议里就约定“遇到不确定的知识应优先考虑调用搜索工具”。 * **教它如何搜索**模型不一定知道用什么关键词最有效。你可以示范告诉它“首选关键词”、“备选关键词”、“来源限制”。这能大幅提高搜索结果的可用性。 * **工具调用结果的处理**要指示模型如何汇报结果。例如“请摘要搜索结果的三个主要观点并引用来源。” 避免它直接把一大段网页HTML扔进对话那会瞬间污染上下文。 * **错误处理**在提示词中可以加入“如果search-web工具调用失败或结果不理想请告知我我们可以尝试调整关键词或切换至brave-search-mcp。” ## 4. 中长会话提示词的生命周期管理 有了这些模块如何在实际项目中串联使用以下是一个典型的工作流展示了提示词如何随时间演变和协作。 ### 4.1 项目启动阶段奠基与协议确认 1. **输入系统级初始化提示词**建立协作基础规则。 2. 进行简短的**项目目标对齐**对话并用状态同步提示词产出第一版项目状态摘要。 3. **确认所有MCP连接正常**可以通过一个小任务测试工具调用如“请用search-web查一下‘Spring Boot 3的最新特性’”。 ### 4.2 日常开发循环导航、执行、同步 这是一个循环往复的过程构成了日常工作的主干[每日开始] - [状态同步提示词] - [明确当日首要任务] - [进入特定Agent角色执行任务] - [遇到问题调用MCP工具] - [完成任务产出代码/文档] - [微型状态同步记录完成项] - [切换至下一个任务/角色] - ... - [每日结束进行完整状态同步与摘要]**关键点**在每个任务边界和角色切换处都使用明确的提示词进行“上下文重置”确保思维聚焦。 ### 4.3 关键决策点存档与转向 当遇到技术选型、方案评审等重大决策时 1. 使用[角色架构师]提示词发起深度讨论。 2. 将讨论中的核心论点和最终**决策**用约定的格式 **决策** ...明确记录下来。 3. 在后续的状态同步中**重点引用这些决策记录**而不是讨论过程。这相当于创建了项目的“决策日志”价值极高。 ### 4.4 会话维护与“重启”策略 即使有良好的状态管理会话最终仍可能逼近上下文极限。此时需要“软重启” 1. 发起一个**终极摘要请求**“请为当前项目生成一份全面的摘要报告包括项目概述、架构图文字描述、已完成的所有模块清单、所有重要决策列表、当前状态、剩余工作清单、以及遇到的已知问题。” 2. 将这个摘要报告复制出来。 3. **开启一个新的Claude Code会话**。 4. 在新会话中首先粘贴**系统级初始化提示词**可能需要根据项目进展微调。 5. 接着粘贴上一会话的**终极摘要报告**并附言“这是之前项目的完整状态。我们在此基础上继续。当前首要任务是[从摘要中的‘下一步计划’里选一项]”。 6. 这样你就在新会话中继承了几乎所有关键上下文而舍弃了庞杂的过程性对话。Token用量重置但项目记忆得以保留。 ## 5. 常见陷阱、排查技巧与高级策略 在实际操作中你会遇到各种问题。下面是一些实录的坑和解决方案。 ### 5.1 常见问题速查表 | 问题现象 | 可能原因 | 排查与解决思路 | | :--- | :--- | :--- | | 模型忽略角色指令回答泛泛 | 1. 角色定义不够具体边界模糊。br2. 提示词中角色指令位置不突出。br3. 上下文历史过长早期指令被稀释。 | 1. 强化角色定义使用“作为XX你应关注A避免讨论B”句式。br2. 将[角色XXX]置于请求最前单独成行。br3. 执行状态同步摘要历史刷新上下文。 | | 频繁触发 context length 错误 | 1. 会话历史确实已满。br2. MCP工具返回了过长的内容如整页网页。br3. 模型生成了过于冗长的回答。 | 1. 执行“会话维护与重启策略”。br2. 在工具调用提示词中要求模型“摘要结果只提取关键信息”。br3. 在请求中明确要求“回答请尽量简洁聚焦要点”。 | | 模型不主动调用MCP工具 | 1. 系统提示词中工具描述不清晰。br2. 模型不确定何时该调用工具。br3. 工具调用格式复杂。 | 1. 在系统提示词中列举工具并附上简单用例。br2. 在任务提示词中明确指示“若需要XX信息请调用YY工具”。br3. 简化调用格式或提供调用模板。 | | 多个Agent间工作记忆断裂 | 1. 切换角色时没有提供足够的背景。br2. 状态同步不及时不同角色对项目进度认知不一致。 | 1. 使用[背景切换...]快速同步上下文。br2. 在任何角色执行任务前先同步一次精简版项目状态“基于我们已完成的A现在要做B”。 | | 决策点记录混乱后期遗忘 | 1. 没有统一的决策记录格式。br2. 决策散落在长篇对话中。 | 1. 强制使用 **决策**格式。br2. 定期使用提示词“请梳理本次对话以来所有标记为**决策**的内容列表输出。” | ### 5.2 高级策略实现动态上下文窗口 对于超长周期项目可以尝试更精细的策略 **“三段式”上下文管理** 1. **活跃上下文**最近几次的问答关于当前正在进行的任务。保持完整。 2. **摘要上下文**项目的状态摘要、决策日志、架构图。定期更新始终保留。 3. **归档上下文**过去已完成的模块的详细讨论。将其移出主会话必要时通过搜索工具如本地的代码向量库MCP按需检索。 在提示词中可以这样实现“关于‘用户认证模块’的详细设计讨论已于三天前结束并归档。当前活跃上下文仅包含‘订单模块’的相关讨论。如需回顾认证模块细节请提示我我可使用code-search工具查找当时的决策记录。” ### 5.3 提示词版本化与迭代 你的系统级提示词不是一成不变的。随着项目推进和团队协作习惯的形成你应该迭代它。 * **建立提示词库**将好的任务提示词、角色提示词保存为模板。 * **A/B测试**对于同一类任务如代码审查尝试两种不同风格的提示词看哪个效果更好。 * **收集反馈**观察模型在哪些指令下执行得更好哪些指令它容易误解。反过来优化你的提示词。 最终你会发现管理Claude Code的长会话和多Agent协作其本质是**通过精心设计的提示词将一个生成式AI模型编程成一个具有状态管理、角色调度和工具调用能力的可预测系统**。这个过程本身就是最硬核的提示词工程。