.claude/文件夹剖析

.claude/文件夹剖析 .claude/文件夹剖析 Modified March 23 Code block Markdown Copy 4. Performance concerns Give specific, actionable feedback per file. 现在在Claude Code中运行/project:review，它会在Claude看到提示之前自动将真实的git差异注入到提示中。!反引号语法用于运行shell命令并嵌入输出。这就是这些命令真正有用的原因，而不仅仅是保存的文本。 向命令传递参数 使用$ARGUMENTS 在命令名后传递文本： Code block Markdown Copy description: Investigate and fix a GitHub issue argument hint: [issue number] Look at issue $ARGUMENTS in this repo. ! Understand the bug, trace it to the root cause, fix it, and write a test that would have caught it. 运行 /project:fix issue 234 会将问题 234 的内容直接输入到提示中。 个人命令与项目命令 .claude/commands/ 中的项目命令会被提交并与团队共享。如果希望命令不受项目限制、在所有场景中生效，请将其放置在 /.claude/commands/ 目录下，这类命令会以 /用户:命令名称 的形式展示。 实用的个人命令示例：每日站会辅助命令、按照自定义规范生成提交信息的命令、快速安全扫描命令。 skills/文件夹：按需使用的可复用工作流 你现在已经了解命令是如何工作的了。技能在表面上看起来很相似，但触发机制却有着根本的不同。在深入探讨之前，先来看看它们的区别： 技能是Claude可以自行调用的工作流程，当任务与技能描述匹配时，无需你输入斜杠命令。命令等待你的操作，而技能则会观察对话，并在时机合适时采取行动。 每个技能都存放在其自己的子目录中，并配有一个SKILL.md文件： Code block Markdown Copy .claude/skills/ ├── security review/ │ ├── SKILL.md │ └── DETAILED GUIDE.md └── deploy/ ├── SKILL.md └── templates/ └── release notes.md SKILL.md 使用 YAML 前置元数据来描述何时使用它： Code block Markdown Copy name: security review description: Comprehensive security audit. Use when reviewing code for vulnerabilities, before deployments, or when the user mentions security. allowed tools: Read, Grep, Glob Analyze the codebase for security vulnerabilities: 1. SQL injection and XSS risks 2. Exposed credentials or secrets 3. Insecure configurations 4. Authentication and authorization gaps Report findings with severity ratings and specific remediation steps. Reference @DETAILED GUIDE.md for our security standards. 当你说出“检查此合并请求的安全问题”时，Claude 会读取描述、识别匹配项，并自动调用相关技能。你也可以通过 /security review 手动调用该技能。 它与命令的核心区别在于：技能可以附带配套文件。上文引用的 @DETAILED GUIDE..md 文件，就是与 SKILL.md 放在同一目录下的详细文档。命令是单个文件，而技能是程序包。 个人技能存放在 /.claude/skills/ 目录中，可适用于你的所有项目。 agents/文件夹：专门的子agent角色 当一项任务足够复杂，需要专业专家来处理时，你可以在.claude/agents/中定义一个子代理角色。每个代理都是一个markdown文件，有自己的系统提示、工具访问权限和模型偏好： Code block Plain Text Copy .claude/agents/ ├── code reviewer.md └── security auditor.md 以下是 code reviewer.md 文件的样子： Code block Markdown Copy name: code reviewer description: Expert code reviewer. Use PROACTIVELY when reviewing PRs, checking for bugs, or validating implementations before merging. model: sonnet tools: Read, Grep, Glob You are a senior code reviewer with a focus on correctness and maintainability. When reviewing code: Flag bugs, not just style issues Suggest specific fixes, not vague improvements Check for edge cases and error handling gaps Note performance concerns only when they matter at scale 当Claude需要进行代码审查时，它会在自己独立的上下文窗口中生成这个代理。代理完成工作，压缩审查结果，并反馈报告。你的主会话不会被数千个中间探索的令牌弄得杂乱无章。 工具字段用于限制智能代理可执行的操作。安全审计工具仅需要读取、文本搜索和文件匹配功能，无需具备文件写入权限。该限制为刻意设置，且有必要进行明确说明。 模型字段支持为专项任务选用成本更低、响应更快的模型。Haiku 模型能够很好地完成大多数只读查询探索工作，可将 Sonnet 和 Opus 模型留待刚需场景使用。 个人代理存放在 /.claude/agents/目录下，可在所有项目中使用。 settings.json：权限和项目配置 .claude/ 目录下的 settings.json 文件控制着 Claude 被允许和不被允许做的事情。在这个文件中，你可以定义 Claude 可以运行哪些工具、可以读取哪些文件，以及在运行某些命令之前是否需要询问。 完整的文件看起来是这样的： Code block JSON Copy { "$schema": "https://json.schemastore.org/claude code settings.json", "permissions": { "allow": [ "Bash(npm run )", "Bash(git status)", "Bash(git diff )", "Read", "Write", "Edit" ], "deny": [ "Bash(rm rf )", "Bash(curl )", "Read(./.env)", "Read(./.env. )" ] } } 下面介绍每个部分的作用。 $schema行可以在VS Code或Cursor中启用自动补全和内联验证。请务必包含它。 允许列表包含无需Claude确认即可运行的命令。对于大多数项目而言，合适的允许列表应涵盖： • Bash(npm run ) 或 Bash(make )，以便Claude可以自由运行你的脚本 • Bash(git )，用于只读的Git相关命令 • 读取、写入、编辑、全局匹配、文本搜索等文件操作权限 禁止列表包含无论何种情况都完全禁止运行的命令。合理的禁止列表会拦截： • rm rf 等具有破坏性的终端命令 • curl 等直连网络的命令 • .env 文件以及 secrets/ 目录下的所有敏感文件 未列入以上任一列表的操作，Claude 在执行前都会发起确认。这种折中设计是刻意为之的。它为你提供了安全保障，同时无需预先预判所有可能出现的命令。 用于个人自定义配置的 settings.local.json 文件 与CLAUDE.local.md的思路相同。创建.claude/settings.local.json，用于存放你不想提交的权限更改。它会自动被Git忽略。 全局的 /.claude/文件夹 你不常与这个文件夹互动，但了解其中的内容很有用。 /.claude/CLAUDE.md会在所有项目的每个Claude Code会话中加载。这是存放你个人编码原则、偏好风格或任何你希望Claude无论在哪个仓库都能记住的内容的好地方。 /.claude/projects/ 存储每个项目的会话记录和自动记忆。Claude Code 在运行时会自动将发现的命令、观察到的模式、架构见解等笔记保存到自身中。这些内容会在会话间持久保存。你可以使用 /memory 浏览和编辑它们。 /.claude/commands/ 和 /.claude/skills/ 目录存放着可在所有项目中使用的个人命令和技能。 一般来说，你不需要手动管理这些内容。但当Claude似乎“记得”你从未告诉过它的事情，或者当你想清除某个项目的自动记忆并重新开始时，了解它们的存在会很有用。 全貌 以下是所有环节如何整合在一起的： Code block Plain Text Copy $ARGUMENTS @DETAILED GUIDE 现在在Claude Code中运行/project:review，它会在Claude看到提示之前自动将真实的git差异注入到提示中。!反引号语法用于运行shell命令并嵌入输出。这就是这些命令真正有用的原因，而不仅仅是保存的文本。 向命令传递参数 使用$ARGUMENTS 在命令名后传递文本： $ARGUMENTS 运行 /project:fix issue 234 会将问题 234 的内容直接输入到提示中。 个人命令与项目命令 .claude/commands/ 中的项目命令会被提交并与团队共享。如果希望命令不受项目限制、在所有场景中生效，请将其放置在 /.claude/commands/ 目录下，这类命令会以 /用户:命令名称 的形式展示。 实用的个人命令示例：每日站会辅助命令、按照自定义规范生成提交信息的命令、快速安全扫描命令。 skills/文件夹：按需使用的可复用工作流 你现在已经了解命令是如何工作的了。技能在表面上看起来很相似，但触发机制却有着根本的不同。在深入探讨之前，先来看看它们的区别： 技能是Claude可以自行调用的工作流程，当任务与技能描述匹配时，无需你输入斜杠命令。命令等待你的操作，而技能则会观察对话，并在时机合适时采取行动。 每个技能都存放在其自己的子目录中，并配有一个SKILL.md文件： SKILL.md 使用 YAML 前置元数据来描述何时使用它： 当你说出“检查此合并请求的安全问题”时，Claude 会读取描述、识别匹配项，并自动调用相关技能。你也可以通过 /security review 手动调用该技能。 它与命令的核心区别在于：技能可以附带配套文件。上文引用的 @DETAILED GUIDE..md 文件，就是与 SKILL.md 放在同一目录下的详细文档。命令是单个文件，而技能是程序包。 @DETAILED GUIDE 个人技能存放在 /.claude/skills/ 目录中，可适用于你的所有项目。 agents/文件夹：专门的子agent角色 当一项任务足够复杂，需要专业专家来处理时，你可以在.claude/agents/中定义一个子代理角色。每个代理都是一个markdown文件，有自己的系统提示、工具访问权限和模型偏好： 以下是 code reviewer.md 文件的样子： 当Claude需要进行代码审查时，它会在自己独立的上下文窗口中生成这个代理。代理完成工作，压缩审查结果，并反馈报告。你的主会话不会被数千个中间探索的令牌弄得杂乱无章。 工具字段用于限制智能代理可执行的操作。安全审计工具仅需要读取、文本搜索和文件匹配功能，无需具备文件写入权限。该限制为刻意设置，且有必要进行明确说明。 模型字段支持为专项任务选用成本更低、响应更快的模型。Haiku 模型能够很好地完成大多数只读查询探索工作，可将 Sonnet 和 Opus 模型留待刚需场景使用。 个人代理存放在 /.claude/agents/目录下，可在所有项目中使用。 settings.json：权限和项目配置 .claude/ 目录下的 settings.json 文件控制着 Claude 被允许和不被允许做的事情。在这个文件中，你可以定义 Claude 可以运行哪些工具、可以读取哪些文件，以及在运行某些命令之前是否需要询问。 完整的文件看起来是这样的： 下面介绍每个部分的作用。 $schema行可以在VS Code或Cursor中启用自动补全和内联验证。请务必包含它。 允许列表包含无需Claude确认即可运行的命令。对于大多数项目而言，合适的允许列表应涵盖： • Bash(npm run ) 或 Bash(make )，以便Claude可以自由运行你的脚本 • Bash(git )，用于只读的Git相关命令 • 读取、写入、编辑、全局匹配、文本搜索等文件操作权限 禁止列表包含无论何种情况都完全禁止运行的命令。合理的禁止列表会拦截： • rm rf 等具有破坏性的终端命令 • curl 等直连网络的命令 • .env 文件以及 secrets/ 目录下的所有敏感文件 未列入以上任一列表的操作，Claude 在执行前都会发起确认。这种折中设计是刻意为之的。它为你提供了安全保障，同时无需预先预判所有可能出现的命令。 用于个人自定义配置的 settings.local.json 文件 与CLAUDE.local.md的思路相同。创建.claude/settings.local.json，用于存放你不想提交的权限更改。它会自动被Git忽略。 全局的 /.claude/文件夹 你不常与这个文件夹互动，但了解其中的内容很有用。 /.claude/CLAUDE.md会在所有项目的每个Claude Code会话中加载。这是存放你个人编码原则、偏好风格或任何你希望Claude无论在哪个仓库都能记住的内容的好地方。 /.claude/projects/ 存储每个项目的会话记录和自动记忆。Claude Code 在运行时会自动将发现的命令、观察到的模式、架构见解等笔记保存到自身中。这些内容会在会话间持久保存。你可以使用 /memory 浏览和编辑它们。 /.claude/commands/ 和 /.claude/skills/ 目录存放着可在所有项目中使用的个人命令和技能。 一般来说，你不需要手动管理这些内容。但当Claude似乎“记得”你从未告诉过它的事情，或者当你想清除某个项目的自动记忆并重新开始时，了解它们的存在会很有用。 全貌 以下是所有环节如何整合在一起的： 一个实用的入门设置 如果你要从头开始，这里有一个行之有效的步骤。 步骤1. 在Claude Code中运行 /init。它会通过读取你的项目生成一个初始的CLAUDE.md文件。将其编辑精简至要点。 步骤2. 添加.claude/settings.json 文件，并根据你的技术栈添加合适的允许/拒绝规则。至少要允许运行命令，拒绝读取.env 文件。 步骤3.为你最常执行的工作流程创建一两个命令。代码审查和问题修复是不错的起点。 步骤4. 随着项目的发展，CLAUDE.md文件变得拥挤时，开始将指令拆分为.claude/rules/文件。在合理的情况下，按路径对其进行范围界定。 步骤5. 添加一个 /.claude/CLAUDE.md 文件，其中包含你的个人偏好。这可能是类似 “总是在实现之前编写类型” 或 “更喜欢函数式模式而非基于类的模式” 这样的内容。 实际上，这就是95%的项目所需的全部内容。当你有值得打包的重复性复杂工作流程时，技能和代理就会派上用场。 关键见解 .claude文件夹实际上是一种协议，用于告知Claude你是谁、你的项目是做什么的，以及它应该遵循哪些规则。你对这些内容定义得越清晰，花在纠正Claude上的时间就越少，它花在做有用工作上的时间就越多。 CLAUDE.md是你最关键的文件。先把它处理好。其他一切都是优化。 从小处着手，边做边完善，把它当作项目中的其他基础设施一样对待：一旦设置得当，它每天都会带来回报。 收工啦！ 如果你喜欢阅读这篇文章。 Find me → @akshay pachaar✔️ @akshay pachaar 每天，我都会分享关于AI、机器学习和vibe coding最佳实践的教程和见解。 🔗 原文链接： https://x.com/akshay pachaar/status... https://x.com/akshay pachaar/status... 关于CLAUDE.md、自定义命令、技能、Agent与权限的完整指南，以及正确的配置方法。 大多数Claude Code用户都将.claude文件夹视为一个黑盒。他们知道这个文件夹存在，也见过它出现在项目根目录中，但从未打开过，更不了解里面每个文件的作用。 这其实错失了很多机会。 .claude文件夹是控制Claude在项目中运行行为的核心中枢。其中存放着你的指令、自定义命令、权限规则，还有Claude在各会话中留存的记忆。只要弄清楚各类文件的存放位置和用途，你就能按照团队需求，量身配置Claude Code的运行模式。 本指南将全面解析该文件夹的完整结构，涵盖日常常用文件以及只需一次配置、后续无需打理的文件。 两个文件夹，不是一个 在深入探讨之前，有一点值得提前了解：实际上有两个.claude目录，而不是一个。 第一个位于你的项目内部，第二个位于你的主目录中： 项目级文件夹保存团队配置。你将其提交到git。团队中的每个人都能获得相同的规则、相同的自定义命令和相同的权限策略。 全局的 /.claude/文件夹保存着你的个人偏好和机器本地状态，如会话历史和自动记忆。 CLAUDE.md：Claude的使用手册 这是整个系统中最重要的文件。当你启动Claude Code会话时，它读取的第一个文件就是CLAUDE.md。它会直接将其加载到系统提示中，并在整个对话过程中牢记于心。 简单来说：无论你在CLAUDE.md中写什么，Claude都会遵循。 如果你告诉Claude在实现之前总是先编写测试，它就会这么做。如果你说“永远不要使用console.log进行错误处理，始终使用自定义日志记录器模块”，它每次都会照做。 在项目根目录下的CLAUDE.md是最常见的设置。但你也可以在 /.claude/CLAUDE.md中设置一个用于全局偏好设置，这些设置将适用于所有项目，甚至可以在子目录中设置一个用于特定文件夹规则的CLAUDE.md。Claude会读取所有这些文件并将它们合并。 CLAUDE.md中实际应包含哪些内容 大多数人要么写得太多，要么写得太少。以下是行之有效的方法。 要写： • 构建、测试和代码检查命令（npm run test、make build等） • 关键架构决策（“我们使用带有 Turborepo 的单仓库”） • 非显而易见的陷阱（“TypeScript严格模式已开启，未使用的变量会被视为错误”） • 导入约定、命名模式、错误处理风格 • 主要模块的文件和文件夹结构 不要写: • 任何属于代码检查器或格式化器配置的内容 • 你已经可以链接到的完整文档 • 解释理论的长段落 保持CLAUDE.md文件行数不超过200行。超过这个长度的文件会占用过多上下文，Claude遵循指令的能力实际上会下降。 以下是一个简洁但有效的示例： 这大约20行内容，足以让Claude掌握所有所需信息，从而在该代码库中高效开展工作，无需反复进行信息确认。 用于个人自定义设置的 CLAUDE.local.md 文件 有时你会有只适用于自己、而非整个团队的个人偏好。比如，你偏爱其他的测试运行工具，或是希望Claude始终按照特定规则打开文件。 在项目根目录中创建 CLAUDE.local.md 文件。Claude 会连同主文件 CLAUDE.md 一并读取该文件，且该文件会被自动纳入Git忽略列表，确保你的个人设置不会提交到代码仓库中。 rules/文件夹：可扩展的模块化指令 CLAUDE.md 适用于单个项目。但随着团队规模扩大，你的 CLAUDE.md 文件会变成 300 行的大文件，无人维护，也没人查看。 rules/ 文件夹可以解决这个问题。 .claude/rules/ 目录下的所有 Markdown 文件都会与你的 CLAUDE.md 一同自动加载。你无需使用一个庞大的文件，而是可以按照业务范畴拆分指令： 每个文件内容专一，易于更新。负责API规范的团队成员编辑 ，负责测试标准的人员编辑 ，彼此互不干扰。 其核心优势在于路径限定规则。在规则文件中添加一段YAML前置元数据，该规则便仅在Claude处理匹配文件时生效： Claude 在编辑 React 组件时不会加载该文件，仅在处理 src/api/ 或 src/handlers/ 目录下的文件时才会加载。未配置路径字段的规则会在每次会话中无条件加载。 当你的 CLAUDE.md 文件内容变得繁杂时，这种划分方式就是理想的处理方案。 commands/ 文件夹：用于存放自定义斜杠命令 开箱即用，Claude Code 有内置的斜杠命令，如 /help 和 /compact。commands/ 文件夹允许你添加自己的命令。 你放入.claude/commands/ 文件夹的每个 Markdown 文件都会变成一个斜杠命令。 名为 review.md 的文件创建 /project:review 。名为 fix issue.md 的文件创建 /project:fix issue 。文件名即命令名。 这里有一个简单的例子。创建.claude/commands/review.md 文件：