Claude Code使用指南：GitHub霸榜项目开发实战

# CLAUDE.md：一个让AI编程效率翻倍的配置文件 编者按：很多开发者在使用Claude Code时都会遇到一个典型问题——每次对话都像第一次见面。你需要反复交代项目背景、技术栈、代码规范，甚至哪些方案已经试过却行不通。如果这些信息没有固定下来，AI就只能靠猜测工作，结果往往是改了不该改的文件、重构了不需要动的代码，甚至推荐完全不合适的技术方案。 今天要介绍的CLAUDE.md，本质上就是一份写给Claude Code的“使用说明书”。你只需要把它放在项目根目录，Claude每次启动时就会自动读取。它能提前告诉AI：应该如何思考问题、怎么写代码、什么时候必须询问确认、哪些操作绝对不能擅自执行、项目使用什么技术栈，以及过去做过哪些重要决策。 简单来说，CLAUDE.md的作用很明确：减少重复解释，限制模型越界，让AI编程变得更稳定、更可控。 如果你正在使用Claude Code，建议先从Andrej Karpathy总结的4条核心规则开始：不清楚就先问、先做最简单方案、不碰无关代码、明确说明不确定性。把这四条写进CLAUDE.md，再根据项目实际情况逐步补充，你会发现使用体验明显改善。 ## 大多数开发者都忽略的关键设置 每次打开Claude Code，它都像一张白纸。 它不知道你的技术栈，不了解你的代码规范，不清楚项目背景，更不记得你之前尝试过什么、明确拒绝过什么。于是它只能猜测——而一旦开始猜测，就可能重构你没有要求修改的代码，推荐会破坏现有架构的框架，未经确认就删除文件，甚至推翻你之前已经做出的技术决策。 CLAUDE.md就是一个放在项目根目录下的纯文本文件。Claude Code会在每次会话开始时自动读取它。 一次设置，永久生效，不必反复解释。更重要的是，它能修复三类代价高昂的错误。 ### 默认设置：每周375美元，只是在重复解释 普通开发者每天大约要花30分钟向Claude重复解释上下文。 技术栈、编码规范、项目背景、已经尝试过的方法——除非你把这些信息一次性写下来，并让Claude每次自动读取，否则它们不会在不同会话之间保留。 如果按开发者时薪150美元计算： - 每天30分钟，就是75美元 - 每周就是375美元 - 如果是5人团队，每周就是1875美元的隐性成本  以下7条规则，应该放在CLAUDE.md文件的最前面： **去掉客套话** 回答时不要用“好问题”“当然可以”“没问题”或类似铺垫开头。直接给出答案，不要寒暄，不要复述问题。 **根据任务匹配回答长度** 回答长度应与任务复杂度匹配。简单问题直接、简短回答；复杂任务给出完整、详细说明。不要用复述问题或重复结论的结束语来填充篇幅。 **行动前先给方案** 在开始任何重要任务前，先给出2–3种可行路径，等待选择后再继续执行。 **不确定就承认不确定** 如果对任何事实、数据、日期或技术信息不确定，请在引用前明确说明。不要用看似合理的信息填补知识空白。拿不准时，直接说不确定。 **明确身份与知识边界** 关于我：[你的姓名] / 角色：[你的角色] / 背景：[专业领域]。 我擅长：[你熟悉的内容]。 我还在学习：[知识缺口]。 请根据这些信息调整每次回答的深度。不要过度解释我已经知道的内容，也不要跳过我需要的背景。 **当前项目上下文** 我正在做：[项目名称] / 目标：[具体结果] / 受众：[谁会使用] / 技术栈背景：[相关约束] / 需要避免：[列表]。 请将这些上下文应用到每一个任务中。如果某项需求与上下文不匹配，请在执行前指出。 **锁定表达风格** 我的写作风格是：[描述你的表达风格]。 句子长度：[偏好]。 我常用的词：[示例]。 我绝不会用的词：[示例]。 格式：[散文式或结构化]。 当你代表我写任何内容时，都必须严格匹配这一风格，不要默认使用你自己的表达模式。 **时间成本明细** - 每天重复解释上下文的时间：30分钟 - 按开发者时薪150美元计算：75美元/天 - 每周：每位开发者375美元 - 5人团队：每周1875美元 - CLAUDE.md设置时间：总计45分钟 **重要提醒**：不要从零开始写CLAUDE.md。先使用下面这个提示词，再编辑输出结果： “基于我告诉过你的关于我自己、我的项目，以及我希望如何工作的内容，请为我写一份完整的CLAUDE.md文件。内容包括：我是谁、我的技术背景、我的沟通偏好，以及每次会话都应遵守的默认行为。要求具体、纯文本、500词以内。” ## 行为约束：那些未经授权的“每小时150美元”改动 想象一下这个场景：你让Claude修复一个函数。 结果它重构了三个文件，重命名了变量，重新组织了imports，还改写了你花时间写好的注释——而这一切都没有经过你的确认。 审查并回滚这些不必要的改动，可能要花1小时，也就是150美元。如果每周发生三次，就是450美元。对5人团队来说，每周就是2250美元，全都浪费在清理没人授权的变更上。  以下7条规则，应该放进CLAUDE.md的行为约束部分： **严格控制范围** 只修改与当前任务直接相关的文件、函数和代码行。不要重构、重命名、重组、重新格式化，或“优化”任何没有明确要求修改的内容。 如果发现其他地方值得修复，请在最后用备注说明。不要直接修改，永远不要。 **重大变更前先询问** 在对已经创建的内容做出重大修改前——包括重写章节、删除段落、重构结构、改变语气等——必须先停下来，准确说明准备改什么，以及为什么改。等待确认后再继续。 **破坏性操作前必须确认** 在删除任何文件、覆盖已有代码、删除数据库记录，或移除依赖前，必须停下来，列出具体会影响哪些内容，并要求明确确认。只有在当前消息中说“是”，才能继续。 “你之前提到过”不等于确认。 **生产环境操作必须强制暂停** 以下操作必须获得当前会话中的明确确认，没有例外： - 部署或推送到任何环境 - 运行迁移或数据库结构变更 - 发送任何外部API调用 - 执行任何带有不可逆副作用的命令 必须在当前消息中明确说“是”。 **始终展示修改内容** 完成任何编码任务后，结尾必须包括： - 修改的文件：列出所有动过的文件 - 修改内容：每个文件用一句话说明 - 有意未修改的文件 - 后续需要处理的事项 **未经确认不得代我行动** 未经在当前消息中的明确确认，不得代表我发送、发布、分享或安排任何内容。包括邮件、日历邀请、文档共享，或任何发生在当前对话之外的操作。必须在当前消息中明确说“是”。 **写代码前先思考** 对于涉及架构决策、复杂问题调试，或非简单功能开发的任务，先一步步梳理问题，再写代码。展示推理过程，指出不确定之处，然后再执行。 **成本统计** - 每周回滚不必要范围变更：150美元 - 每周手动diff检查：75美元 - 每位开发者行为相关浪费：225美元/周 - 5人团队：1125美元/周 - CLAUDE.md行为部分设置时间：30分钟 ## 记忆与技术栈：让Claude Code真正可靠的设置 Claude会在不同会话之间忘记一切。 你做过的每个决定，失败过的每种方案，六个月前为什么选择Prisma而不是Drizzle，以及某个约束为什么来自特定客户需求——它都会忘记。然后，它会重新提出你早就排除过的方案。 这一部分相当于为Claude提供当前最接近“真实记忆”的机制，同时锁定技术栈，避免它继续推荐会破坏现有架构的工具。  **MEMORY.md决策日志** 在项目中维护一个名为MEMORY.md的文件。每当做出重要决定后，都新增一条记录： - 决定了什么 - 为什么这样决定 - 排除了什么，为什么排除 每次会话开始时，先读取MEMORY.md。未经提醒，不得与已记录的决定相冲突。 **会话结束总结** 当说“session end”“wrapping up”或“let's stop here”时，请向MEMORY.md写入一份会话总结，包括： - 本次处理了什么 - 已完成什么 - 仍在进行什么 - 做出了哪些决定 - 下次会话的优先事项 **ERRORS.md失败日志** 维护一个名为ERRORS.md的文件。当某个方案尝试超过两次仍未成功时，记录下来： - 什么没有奏效 - 最后什么方案奏效 - 下次需要注意什么 在为类似任务提出方案前，先检查ERRORS.md。 **永久事实清单** 以下事实对本项目始终成立，并必须无例外地应用到每次会话： [你的永久约束、架构决策和规则] 如果某个任务与这些事实冲突，请在执行前指出。 **锁定技术栈** 本项目的技术栈如下，始终使用这些工具。除非明确要求，否则不要推荐替代方案： - 语言：[如TypeScript] - 框架：[如Next.js 14] - 包管理器：[如pnpm] - 数据库：[如PostgreSQL with Prisma] - 测试：[如Vitest] - 样式：[如Tailwind CSS] 如果某个工具看起来不合适，可以指出。但除非明确说明，否则必须使用已定义的技术栈。 **困难决策启用扩展思考** 对于涉及系统架构、性能权衡、数据库设计，或长期技术决策的问题，请使用扩展思考模式。 一步步分析问题，提出可能没有考虑到的取舍，指出在规模扩大后可能不成立的假设，然后给出建议。 **那4条走红的规则** Karpathy总结出了4种会让Claude Code失败的行为。一位开发者将其提炼成下面4行规则。编码准确率因此从65%提升到了94%。 1. **先问，不要假设**。如果有任何不清楚的地方，在写下第一行代码前先问。不要对意图、架构或需求做无声假设。 2. **先做最简单的方案**。永远先实现能工作的最简单方案。不要加入未被明确要求的抽象层或灵活性。 3. **不要触碰无关代码**。如果某个文件或函数与当前任务没有直接关系，不要修改它。即便认为它可以被优化，也不要动。 4. **明确标出不确定性**。如果对某个方案或技术细节没有把握，请在继续前说明。没有确定性却表现得很自信，比承认知识缺口造成的损害更大。 **成本统计** - 每周因遗忘决策和错误建议造成的恢复成本：每位开发者300美元 - 错误技术栈推荐和不兼容工具：每周75美元 - 每位开发者记忆相关浪费：375美元/周 - 5人团队：1875美元/周 - MEMORY.md + ERRORS.md + 技术栈设置时间：20分钟 ## 结论：算一笔明白账 完整成本账如下： - 每周重复解释上下文：375美元 - 每周回滚未授权改动：225美元 - 每周处理被遗忘决策带来的问题：375美元 - 每位开发者每周总浪费：975美元 如果是5人开发团队：每周4875美元。一年就是253,500美元。 而CLAUDE.md的设置总共只需要2小时。 仅Karpathy的4条规则，就让编码准确率从65%提升到94%。 一个纯文本文件，21条规则，两小时工作量。 完成这项设置的开发者，实际上是在使用一个更可靠的Claude：它能记住决策，控制任务范围，在破坏性操作前请求确认，也不会推荐会破坏现有架构的框架。 而还没有设置的人，每周仍在花975美元重复解释自己。 **最后建议**：先从Karpathy的4条规则开始。只需要这4条。现在就把它们粘贴到项目根目录下一个名为CLAUDE.md的新文件里，只要2分钟。之后每周再根据发现的缺口逐步补充。 在它被信息流淹没前，先收藏起来。如果你觉得有用，也可以分享给真正需要它的人。