基于Scratchpad的Cursor AI协作规则：提升Claude 3.5编码效率

1. 项目概述从 Devin 启发到个人 Cursor 规则定制如果你和我一样日常重度依赖 Cursor 进行编码并且对 Claude Sonnet 3.5 的潜力充满好奇那么你很可能也经历过这样的时刻面对一个复杂的重构任务或一段难以理解的遗留代码你希望 AI 助手能像一个真正的搭档有条不紊地和你一起思考、拆解而不是仅仅给出一个最终答案。这正是我最初被devin.cursorrules这个项目吸引的原因。它试图将 Devin那个传说中的 AI 软件工程师的工作流引入 Cursor通过一套精心设计的规则.cursorrules文件来引导 AI 进行更结构化、更接近人类工程师的思考。然而在实际将这套规则应用到我的日常工作流中时我发现了一个有趣的矛盾理论上更详细、更长的提示词Prompt应该能提供更明确的指令引导 AI 产生更高质量的输出。但实践下来尤其是在使用 Claude Sonnet 3.5 这类模型时情况并非总是如此。我经历了一个从“全盘照搬”到“精简实用”的转变过程。最终我创建了自己的.cursorrules分支版本核心目标只有一个在有限的上下文窗口内最大化 AI 助手的协作效率和思考深度。这个项目Huguet57/.cursorrules就是我这场“提示词工程”实验的结晶它剥离了原版中我认为当前并非必需的复杂“工具”调用部分而全力聚焦于一个真正改变游戏规则的功能——Scratchpad草稿纸。2. 核心思路解析为什么“更少”反而意味着“更多”在深入我的具体实现之前有必要先拆解一下我做出这些设计决策背后的逻辑。这不仅仅是关于删减了几行代码而是关于如何与大型语言模型LLM进行高效协作的底层思考。2.1 上下文窗口看不见的硬性天花板首先我们必须正视一个所有 LLM 使用者都无法回避的限制上下文窗口Context Window。你可以把它想象成 AI 的“工作记忆”或“短期记忆区”。当我们与 Claude 对话时我们输入的提示词、AI 之前的回复、当前编辑的文件内容甚至整个对话历史都会占用这个窗口。一旦总长度超过窗口限制最早的信息就会被“遗忘”。原版的devin.cursorrules是一个雄心勃勃的、功能完整的“智能体”框架。它定义了角色、目标、工作流程并预设了 AI 可以调用的一系列“工具”比如运行命令、读写文件等。这套规则本身就已经是一篇非常长的“说明书”。当我们在 Cursor 中激活它并试图让它处理一个本身就有几百行代码的文件时上下文窗口的压力会急剧增加。我的关键发现是当提示词过长逼近或挤占模型处理当前任务如理解代码、生成新代码所需的核心上下文空间时AI 的表现会显著下降。它可能会开始忽略你指令中的关键部分或者无法连贯地运用你设定的复杂流程。这就是为什么我反复尝试强制 AI 使用原版长提示词中的 Scratchpad 功能时它常常“失灵”的根本原因——不是它不想用而是它可能已经“记不住”或者无法在拥挤的上下文中有效执行那套复杂指令了。2.2 Scratchpad结构化思考的强制脚手架那么为什么在众多功能中我唯独保留了 Scratchpad并视其为“天才之作”Scratchpad 的本质是强制 AI 进行逐步推理Chain-of-Thought并将其外部化、可视化。在没有 Scratchpad 的普通对话中AI 的思考过程是黑箱的它直接给出结论。这带来了几个问题难以纠偏如果结论错了你很难知道它是在哪一步推理上出了问题。无法协作你无法在 AI 的“思考中途”插入自己的见解或进行引导。信任缺失一个凭空出现的答案即使正确也让人心里没底。Scratchpad 通过在 AI 的回复中开辟一个专门的、格式化的区域要求 AI 必须在这里先写下它的思考过程、计划、待办事项、遇到的问题然后再输出最终的代码或答案。这个过程带来了巨大的好处提升输出质量被迫放慢速度、梳理思路通常会减少“想当然”的错误。增强可控性你可以随时审查 Scratchpad 中的内容如果发现思路跑偏可以在它执行错误操作前进行干预或纠正。教育价值对于学习编程的人来说观察 AI 如何拆解问题、设计解决方案本身就是极佳的学习材料。留存思考记录Scratchpad 的内容会保留在对话历史中当未来需要回顾或修改时你能清晰地看到当初的决策依据。因此我的核心思路变得非常清晰在有限的上下文预算内将最多的“算力”和“注意力”分配给最能提升协作质量和结果可靠性的功能——即 Scratchpad 所代表的显式推理过程。砍掉其他功能不是否定它们的价值而是为了在当前的技术约束下确保核心价值的完美实现。2.3 工具集的取舍面向未来的简洁性原版规则中的“工具”调用如run_command,read_file等其设计愿景是让 AI 能够自主执行一些操作更像一个自动化的智能体。这是一个非常前沿和强大的概念。然而在我的实际使用中主要聚焦于代码编写、重构和解释我发现信任与安全边界我目前更倾向于保持“人在回路中”的模式。由我本人来审核 AI 的建议然后亲手执行命令或修改文件这让我对系统的变更拥有完全的控制权避免了自动化可能带来的意外风险。复杂度与稳定性工具调用机制增加了提示词的复杂度和与 Cursor 环境交互的不确定性。在追求稳定、可预测的日常协作体验时简化这一部分可以减少很多潜在的“怪癖”或失效场景。聚焦当前需求对于大多数日常开发任务调试、写函数、写文档、代码审查一个能和我进行清晰、结构化“讨论”的 AI 伙伴比一个全自动的执行者更有用、也更高效。所以我的版本选择暂时舍弃了工具集。这使我的.cursorrules文件变得非常精简和专注就像一个为“结对编程”场景量身定制的轻量级协议。它不追求全自动而是追求高信噪比的深度协作。3. 我的 .cursorrules 文件详解与配置下面我将完整展示并逐行解析我目前正在使用的.cursorrules文件。这个文件通常放置在项目根目录或用户全局配置目录下Cursor 会在会话中自动读取并应用其中的规则。# Huguet‘s Simplified Cursor Rules for Claude 3.5 Sonnet # Focus: Enhanced Collaboration via Scratchpad ## Core Identity Communication Style - You are an expert software engineer paired with me (the human). - Our interaction is a **collaborative session**. Think out loud. - **Always** use the Scratchpad section to structure your thoughts before answering. - Be concise but thorough in reasoning. No fluff. - Admit uncertainties and ask clarifying questions early. ## Primary Directive: The Scratchpad Workflow 1. **For EVERY response that involves problem-solving, planning, or code generation, YOU MUST start your response with the following exact Scratchpad section:** ### Scratchpad **Goal:** [Clearly state the immediate goal based on my request] **Thoughts Plan:** - [Step 1: Break down the problem or request] - [Step 2: Analyze existing code/context if any] - [Step 3: Outline potential approaches and choose one] - [Step 4: Note any uncertainties or questions for me] **Next Actions:** - [List the concrete actions you will take in this response, e.g., Write the function calculateTotal, Explain the bug in three points] 2. After the Scratchpad, provide the final answer, code, or explanation under a ### Final Output or ### Code heading. 3. If the task is trivial (e.g., explain this single line), you may use a shortened scratchpad, but the structure must be present. ## Interaction Principles - **Ask before acting on ambiguity:** If my request is vague, use the Scratchpad to list interpretations and ask me to pick one. - **Prefer incremental delivery:** For large tasks, propose a step-by-step plan in the Scratchpad, get my approval, then execute step 1. Well iterate. - **Link to context:** When referring to code, mention file names and line numbers if possible. - **No hallucinations:** If you dont know, say so in the Scratchpad. Do not invent APIs or library behaviors. ## Response Formatting - Use clear markdown headings (###, ####) to separate Scratchpad, Final Output, and different parts of the answer. - Write code blocks with proper language tagging. - Keep the Scratchpad visually distinct from the final output.3.1 规则文件逐模块解读1. 核心身份与沟通风格这一部分设定了 AI 的基本角色和互动基调。“专家软件工程师”确立了专业性“协作会话”强调了平等伙伴关系而非主仆。“大声思考”和“必须使用 Scratchpad”是核心指令直接对应了我想要的可视化推理过程。“简洁而彻底”和“尽早承认不确定性”则是为了优化交流效率避免兜圈子和自信的胡言乱语。2. 首要指令Scratchpad 工作流这是整个文件的心脏。它用非常明确的、格式化的指令规定了 AI每一次进行问题解决、计划或代码生成时必须遵循的输出结构。强制性使用“YOU MUST”这样强烈的字眼减少模型的犹豫或忽略的可能性。结构化将思考过程分解为“目标”、“思考与计划”、“下一步行动”三个板块。这引导 AI 进行逻辑递进Goal确保 AI 正确理解你的意图。Thoughts Plan强制进行问题拆解、现状分析和方案设计。Next Actions明确本次回复的具体产出管理你和 AI 双方的预期。灵活性也允许对于极其简单的任务使用简化的 Scratchpad在严格性和流畅性之间取得平衡。3. 交互原则这部分定义了在 Scratchpad 框架下的具体协作礼仪。处理模糊性当需求不明确时要求 AI 在 Scratchpad 中列出几种可能的解读并让你选择。这避免了它猜错方向白费功夫。增量交付对于大任务鼓励“计划-批准-执行”的小步快跑循环。这让你始终保持控制权并能及时调整方向。上下文关联要求提及文件名和行号这在处理多文件项目时至关重要能快速定位。杜绝幻觉明确禁止编造信息鼓励诚实表达“不知道”。这是建立可靠协作关系的基石。4. 响应格式规定了 Markdown 的使用确保回复的清晰度和可读性。将 Scratchpad 与最终输出用标题明显区分开使得对话记录一目了然。3.2 如何在 Cursor 中应用此规则创建规则文件在你的项目根目录下创建一个名为.cursorrules的文件注意开头的点。粘贴内容将上述规则内容完整复制到该文件中。激活规则在 Cursor 中打开该项目。通常Cursor 会自动检测并应用根目录下的.cursorrules。你可以在 Cursor 的聊天界面看到提示表明规则已加载。选择模型在 Cursor 的设置或聊天模型选择器中确保你使用的是Claude 3.5 Sonnet。这套规则是针对该模型的交互特性优化的。开始对话现在当你向 Cursor 的 AI 提问或发出指令时它应该会遵循规则首先在### Scratchpad标题下输出它的思考过程。注意.cursorrules是项目级的。你也可以在 Cursor 的全局设置中指定一个全局规则文件路径这样所有项目都会默认使用。但对于不同性质的项目你可能需要微调规则因此项目级规则文件提供了更大的灵活性。4. 实战效果对比与场景示例理论说得再多不如看看实际效果。下面我将通过几个典型的编程场景对比使用我的精简规则和普通无规则对话的差异。4.1 场景一编写一个复杂的工具函数用户请求“帮我写一个 Python 函数用来解析混合了中文、英文和数字的字符串并按照不同的类型进行分块返回。例如输入‘Hello世界123abc’输出[(en, Hello), (zh, 世界), (num, 123), (en, abc)]。”普通对话无规则的典型回复import re def parse_mixed_string(s): pattern r([a-zA-Z])|([\u4e00-\u9fff])|(\d) matches re.finditer(pattern, s) result [] for match in matches: if match.group(1): result.append((en, match.group(1))) elif match.group(2): result.append((zh, match.group(2))) elif match.group(3): result.append((num, match.group(3))) return result print(parse_mixed_string(Hello世界123abc))回复可能直接给出代码附带少量解释但思考过程是缺失的。使用.cursorrules后的回复### Scratchpad **Goal:** Create a Python function to parse a mixed Chinese/English/numeric string and return chunked tuples with type labels. **Thoughts Plan:** - Step 1: Understand the requirement. We need to segment the string by language/type, not just split. The example shows contiguous blocks of the same type. - Step 2: Choose an approach. Regular expressions are suitable. We need a pattern that matches consecutive Latin letters, consecutive Chinese characters (Unicode range), and consecutive digits. - Step 3: Design the regex. We can use re.finditer with a pattern containing capture groups for each type. The order of groups matters. Well use ([a-zA-Z])|([\u4e00-\u9fff])|(\d). - Step 4: Implementation details. We need to iterate over matches, determine which group matched, and assign the correct label. - Step 5: Edge cases to consider: empty string, string with other characters (e.g., punctuation), overlapping patterns (shouldnt happen with this design). - Step 6: Ask for clarification? The requirement seems clear. No need for now. **Next Actions:** - Write the function parse_mixed_string with the described logic. - Include a simple test example in the code block. ### Code python import re def parse_mixed_string(s: str) - list[tuple[str, str]]: Parses a string containing mixed Chinese, English, and numeric characters. Returns a list of tuples where each tuple is (type, substring). Type can be en, zh, or num. # Regex pattern: English letters | Chinese characters | Digits pattern r([a-zA-Z])|([\u4e00-\u9fff])|(\d) result [] for match in re.finditer(pattern, s): # Check which capture group matched (1: en, 2: zh, 3: num) if match.group(1): result.append((en, match.group(1))) elif match.group(2): result.append((zh, match.group(2))) elif match.group(3): result.append((num, match.group(3))) return result # Example usage if __name__ __main__: test_str Hello世界123abc print(parse_mixed_string(test_str)) # Expected output: [(en, Hello), (zh, 世界), (num, 123), (en, abc)]对比分析过程透明化Scratchpad 清晰展示了 AI 从理解目标、选择方案正则表达式、设计模式、考虑边界条件到最终决定实施的完整思维链。如果我对正则表达式范围有疑问例如是否包含全角字母我可以立即在它执行前提出。质量提升因为有计划步骤最终代码包含了类型注解、详细的文档字符串和一个if __name__ “__main__”测试块。这些在普通对话中可能被省略。便于纠偏如果我发现它的计划Step 3中使用的 Unicode 范围不准确我可以在它写出代码前纠正“中文范围考虑一下扩展区用[\u4e00-\u9fff\u3400-\u4dbf\U00020000-\U0002a6df]更全面。” 这实现了真正的“结对编程”。4.2 场景二重构一段冗长的代码用户请求“看看下面这个函数太长了帮我重构一下提高可读性。” 附上一段几十行的、嵌套很深的处理函数。普通对话的回复可能会直接给出一个重构后的版本并简要说明“我提取了几个辅助函数”、“使用了更清晰的变量名”。但你不知道它判断“长”的标准是什么提取函数的边界是如何划定的有没有考虑性能影响。使用.cursorrules后的回复### Scratchpad **Goal:** Refactor the provided long function for better readability and maintainability. **Thoughts Plan:** - Step 1: Analyze the existing function. It appears to do three distinct things: 1) validate input, 2) process data through a series of transformations, 3) format and output the result. These are tightly coupled. - Step 2: Identify refactoring strategies. - Extract validation logic into a separate validate_input function. - The core transformation loop is complex but sequential. Can it be broken into _transform_step_a, _transform_step_b? - The formatting logic at the end is also a candidate for extraction (_format_result). - Step 3: Consider trade-offs. Creating too many small functions might make the flow harder to follow. Aim for a balance where each function has a single, clear responsibility. - Step 4: Check for state mutations. The original function modifies an input parameter. We should decide if we want to keep that side effect or make it pure. - Step 5: Need clarification? Yes. Regarding the side effect on the config parameter: Should the refactored version modify it in place, or should we work on a copy and return a new config? **Next Actions:** - Ask the user about the side effect handling. - After clarification, proceed to write the refactored version, showing the main function and the extracted helper functions. ### Question for You I notice the original function modifies the config dictionary in place. For better predictability, would you prefer the refactored version to: 1. Continue modifying config in place (side effect)? 2. Work on a copy of config and return the modified version (pure function)?对比分析决策过程可见Scratchpad 展示了 AI 是如何分析代码、识别职责、规划重构策略的。你看到了它的“设计思路”。主动发起关键讨论它识别出了一个重要的设计决策点副作用处理并在执行重构之前主动提出来询问你的偏好。这避免了它按照自己的假设重构后结果不符合你的预期。协作感极强这不再是“你命令它执行”而是“我们一起分析共同决策”。Scratchpad 成为了我们共享的设计白板。4.3 场景三解释一段复杂的算法或错误当遇到一段难以理解的算法或一个晦涩的错误信息时Scratchpad 会引导 AI 进行逐步拆解而不是直接抛出一大段解释。使用.cursorrules后的回复结构示例### Scratchpad **Goal:** Explain the ‘Maximum call stack size exceeded’ error in the provided React component. **Thoughts Plan:** - Step 1: Reproduce the error mentally. The error indicates recursion or an infinite loop in rendering/updates. - Step 2: Analyze the component code. Look for useEffect dependencies that change on every render, setState calls inside render with no condition, or recursive function calls. - Step 3: Found a useEffect that sets state based on a prop, and that state is used in a dependency array of another useEffect that sets the same state again. This creates a loop. - Step 4: Formulate the explanation: 1) Describe the error meaning, 2) Pinpoint the exact code lines causing the loop, 3) Explain the loop cycle step-by-step, 4) Provide the fix principle. **Next Actions:** - Provide a step-by-step explanation of the infinite update loop. - Show the problematic code snippet with annotations. - Suggest a corrected version. ### Final Output: Error Explanation Fix **1. What the error means:** ... **2. The root cause in your code:** ... **3. The infinite loop cycle:** ... **4. How to fix it:** ...这种结构化的解释比一段笼统的文字要容易理解得多因为它模拟了专家调试时的逻辑过程。5. 常见问题、局限性与调优心得即使有了这套精简的规则在实际使用中你仍然可能会遇到一些挑战。以下是我在实践中总结的一些常见问题和应对策略。5.1 为什么 AI 有时还是会忽略 Scratchpad这是最可能遇到的问题。即使规则写得再明确LLM 也并非百分之百可靠。原因和解决方案如下上下文过长这是首要原因。如果你的对话历史已经很长或者你一次性粘贴了巨量的代码模型可能没有足够的“注意力”分配到规则指令上。对策开启一个新的聊天会话Fresh Chat。这是最有效的方法。新会话的上下文是干净的规则指令会得到最高优先级的处理。对策在复杂任务开始时可以温和地提醒“请记住使用 Scratchpad 来规划你的思路。”指令冲突或模糊如果你的请求非常简短且直白如“将这里的变量名从a改成amount”模型可能会判断这不需要复杂思考从而跳过 Scratchpad。对策对于你希望无论如何都进行结构化思考的任务可以在请求中明确强调“请使用 Scratchpad 来分析并执行这个重构。”对策接受这种“智能跳过”。我的规则中也允许对琐碎任务使用简化 Scratchpad这本身是流畅性的一种体现。模型本身的“固执”或随机性LLM 具有概率性偶尔会出现不遵循指令的情况。对策使用“重试”/“Regenerate”功能。通常重新生成一次回复模型就会正确遵守规则。5.2 如何针对不同项目微调规则.cursorrules的魅力在于它的可定制性。你可以为不同的项目类型创建不同的规则文件。前端项目可以加入对组件设计、状态管理、API 调用规范的强调。## Frontend Specifics - When proposing UI components, consider accessibility (ARIA labels) and responsive design. - Prefer functional components with hooks over class components. - For state, evaluate if it can be local (useState), lifted up, or needs a global manager.数据科学项目可以强调数据验证、可视化规范和可复现性。## Data Science Specifics - Always include data shape checks and handling of missing values in your plans. - When suggesting visualizations, recommend libraries (e.g., matplotlib, seaborn, plotly) and justify the choice. - Comment on the computational complexity of proposed algorithms.团队协作项目可以加入代码风格和提交规范的提醒。## Team Conventions - Follow PEP 8 (Python) / Airbnb Style Guide (JS) for code style. - Write descriptive commit messages in the imperative mood. - Tag TODO comments with username if a specific person should handle it.将项目特定的规则放在通用规则后面它们会共同作用让 AI 助手更贴合你的项目上下文。5.3 Scratchpad 是否拖慢了交互速度这是一个合理的担忧。从“输入问题”到“得到最终答案”中间多了一个思考步骤的输出理论上时间会变长。实际体验对于中小型任务这个延迟非常轻微多几秒钟但带来的收益更高的代码质量、更少的返工、更好的理解是巨大的。对于微型任务正如规则所说你可以允许其使用简化格式或者对于极其简单的请求如语法更正可以接受它直接给出答案。这需要你和 AI 之间形成一种默契。“慢就是快”在复杂的开发任务中前期多花 30 秒进行规划可能避免后面 30 分钟的调试和重写。Scratchpad 强制进行的这种“设计先行”的 discipline从整体效率上看是提升的。5.4 与 Claude 3.5 Sonnet 的特性结合我选择 Claude 3.5 Sonnet 并非偶然。这个模型在遵循复杂指令、进行长链条推理以及代码生成质量上表现尤为出色。我的精简规则正是为了最大化发挥它的这些长处强大的指令跟随Sonnet 能很好地理解并坚持 Scratchpad 的格式要求。出色的推理能力Scratchpad 为它的推理能力提供了一个完美的输出框架让你能“看到”它的思考。高质量的代码生成结构化的思考自然导向更健壮、更可读的代码。5.5 一个重要的心态转变从“问答”到“协作”使用这套.cursorrules最大的收获可能不是某个具体的技术技巧而是一种与 AI 互动心态的转变。你不再仅仅是提问者和评判者而是成为了一个设计评审员、一个思路共鸣板、一个合作者。Scratchpad 就是我们的共享工作区。当你开始习惯阅读它的“Thoughts Plan”并在此基础上提出“你有没有考虑过……”或者“我更喜欢第二种方案因为……”时你就在进行真正的结对编程。这种体验远比简单地复制粘贴一段生成的代码要丰富和有益得多。它迫使你也进行更深入的思考从而形成一个积极的学习和创造循环。