Anatomy of the .claude folder .claude 文件夹的结构解析
A complete guide to CLAUDE.md, custom commands, skills, agents, and permissions, and how to set them up properly. 关于 CLAUDE.md、自定义命令、技能、代理和权限的完整指南，以及如何正确设置它们。
Most Claude Code users treat the .claude folder like a black box. They know it exists. They’ve seen it appear in their project root. But they’ve never opened it, let alone understood what every file inside it does.大多数 Claude Code 用户都将 `.claude` 文件夹视作一个黑箱。他们知道它的存在，也见过它出现在项目根目录中，但从未打开过它，更别提理解其中每个文件的作用了。
That’s a missed opportunity. 这可是一个错失良机。
The .claude folder is the control center for how Claude behaves in your project. It holds your instructions, your custom commands, your permission rules, and even Claude’s memory across sessions. Once you understand what lives where and why, you can configure Claude Code to behave exactly the way your team needs it to.`.claude` 文件夹是 Claude 在项目中行为表现的控制中心。它承载着你的指令、自定义命令、权限规则，甚至包括 Claude 跨会话的记忆。一旦你明白了每个文件的位置和用途，就能对 Claude Code 进行配置，使其完全按照团队的需求来运行。
This guide walks through the entire anatomy of the folder, from the files you’ll use daily to the ones you’ll set once and forget. 本指南将带你剖析该文件夹的完整结构，从你将日常使用的文件，到那些只需设置一次便可长久不用再管的文件。
Two folders, not one 两个文件夹，而非一个
Before diving in, one thing worth knowing upfront: there are actually two .claude directories, not one. 在深入之前，有一点值得提前了解：实际上有两个 .claude 目录，而非只有一个。
The first lives inside your project and the second lives in your home directory: 第一个位于你的项目内，第二个则位于你的主目录中：
The project-level folder holds team configuration. You commit it to git. Everyone on the team gets the same rules, the same custom commands, the same permission policies.项目级文件夹存放团队配置。你需要将其提交到 Git 中。团队中的每个人都遵循相同的规则、使用相同的自定义命令、执行相同的权限策略。
The global ~/.claude/ folder holds your personal preferences and machine-local state like session history and auto-memory.全局的 ~/.claude/ 文件夹保存了你的个人偏好设置和本地机器状态，例如会话历史和自动记忆。
CLAUDE.md: Claude’s instruction manual CLAUDE.md：Claude 的指令手册
This is the most important file in the entire system. When you start a Claude Code session, the first thing it reads is CLAUDE.md. It loads it straight into the system prompt and keeps it in mind for the entire conversation.这是整个系统中最重要的文件。当你启动一个 Claude Code 会话时，它首先读取的就是 CLAUDE.md。该文件会直接加载到系统提示中，并在整个对话期间持续生效。
Simply put: **whatever you write in CLAUDE.md, Claude will follow.**简而言之：你在 CLAUDE.md 中写的任何内容，Claude 都会遵循。
If you tell Claude to always write tests before implementation, it will. If you say “never use console.log for error handling, always use the custom logger module,” it will respect that every time. 如果你告诉Claude始终在实现之前编写测试，它会照做。如果你说”永远不要用console.log处理错误，始终使用自定义日志模块”，它每次都会遵守这个要求。
A CLAUDE.md at your project root is the most common setup. But you can also have one in ~/.claude/CLAUDE.md for global preferences that apply across all projects, and even one inside subdirectories for folder-specific rules. Claude reads all of them and combines them.在项目根目录放置CLAUDE.md是最常见的设置。但你也可以在~/.claude/CLAUDE.md中设置一个全局偏好文件，适用于所有项目，甚至可以在子目录中为特定文件夹设置规则。Claude会读取所有配置文件并将它们合并。
What actually belongs in CLAUDE.md CLAUDE.md实际上应该包含什么
Most people either write too much or too little. Here’s what works. 大多数人要么写太多，要么写太少。以下是行之有效的内容。
Write: 编写：
- Build, test, and lint commands (npm run test, make build, etc.) 构建、测试和代码检查命令（npm run test、make build 等）
- Key architectural decisions (“we use a monorepo with Turborepo”) 关键架构决策（“我们采用 Turborepo 进行单仓库管理”）
- Non-obvious gotchas (“TypeScript strict mode is on, unused variables are errors”) 不易察觉的注意事项（“TypeScript 严格模式已开启，未使用的变量会报错”）
- Import conventions, naming patterns, error handling styles 导入惯例、命名模式、错误处理风格
- File and folder structure for the main modules 主要模块的文件和文件夹结构
Don’t write: 不要编写：
- Anything that belongs in a linter or formatter config 任何属于 linter 或 formatter 配置的内容
- Full documentation you can already link to 您现在就可以链接到的完整文档
- Long paragraphs explaining theory 解释理论的长段落
Keep CLAUDE.md under 200 lines. Files longer than that start eating too much context, and Claude’s instruction adherence actually drops. 保持 CLAUDE.md 文件在200行以内。超过这个长度的文件会占用过多上下文，而 Claude 的指令遵循能力实际上会下降。
Here’s a minimal but effective example: 以下是一个精简但有效的示例：
# Project: Acme API
## Commands
npm run dev # Start dev server
npm run test # Run tests (Jest)
npm run lint # ESLint + Prettier check
npm run build # Production build
## Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- All handlers live in src/handlers/
- Shared types in src/types/
## Conventions
- Use zod for request validation in every handler
- Return shape is always { data, error }
- Never expose stack traces to the client
- Use the logger module, not console.log
## Watch out for
- Tests use a real local DB, not mocks. Run \`npm run db:test:reset\` first
- Strict TypeScript: no unused imports, everThat’s ~20 lines. It gives Claude everything it needs to work productively in this codebase without constant clarification. 大约20行代码。这足以让Claude在代码库中高效工作，而无需反复澄清问题。
CLAUDE.local.md for personal overrides CLAUDE.local.md：用于个人偏好覆盖
Sometimes you have a preference that’s specific to you, not the whole team. Maybe you prefer a different test runner, or you want Claude to always open files using a specific pattern. 有时你会有属于自己的特定偏好，而不是整个团队的共同习惯。也许是喜欢不同的测试运行工具，或是希望Claude始终按特定模式打开文件。
Create CLAUDE.local.md in your project root. Claude reads it alongside the main CLAUDE.md, and it’s automatically gitignored so your personal tweaks never land in the repo. 在你的项目根目录下创建 CLAUDE.local.md。Claude 会将其与主 CLAUDE.md 一并读取，且该文件会自动被 gitignore 忽略，这样你的个人调整就不会进入代码库。
The rules/ folder: modular instructions that scale rules/ 文件夹：可扩展的模块化指令
CLAUDE.md works great for a single project. But once your team grows, you end up with a 300-line CLAUDE.md that nobody maintains and everyone ignores. 对于单个项目来说，CLAUDE.md 效果很好。但当你的团队壮大后，终会出现一份长达 300 行的 CLAUDE.md，无人维护，也无人理会。
The rules/ folder solves that. 而 rules/ 文件夹正是解决这一问题的方案。
Every markdown file inside .claude/rules/ gets loaded alongside your CLAUDE.md automatically. Instead of one giant file, you split instructions by concern:.claude/rules/ 中的每个 Markdown 文件都会与你的 CLAUDE.md 自动同时加载。你不再需要维护一个巨型文件，而是按关注点拆分解构指令：
.claude/rules/
├── code-style.md
├── testing.md
├── api-conventions.md
└── security.mdEach file stays focused and easy to update. The team member who owns API conventions edits api-conventions.md. The person who owns testing standards edits testing.md. Nobody stomps on each other. 每个文件都保持焦点明确、易于更新。负责 API 规范的团队成员编辑 api-conventions.md，负责测试标准的成员编辑 testing.md——大家互不干扰。
The real power comes from path-scoped rules. Add a YAML frontmatter block to a rule file and it only activates when Claude is working with matching files:真正的威力来自路径作用域规则。为规则文件添加 YAML 前置元数据块后，只有当 Claude 处理匹配的文件时该规则才会激活。
---
paths:
- "src/api/**/*.ts"
- "src/handlers/**/*.ts"
---
# API Design Rules
- All handlers return { data, error } shape
- Use zod for request body validation
- Never expose internal error details to clientsClaude won’t load this file when it’s editing a React component. It only loads when it’s working inside src/api/ or src/handlers/. Rules without a paths field load unconditionally, every session. 当 Claude 在编辑 React 组件时，不会加载此文件。它仅在 `src/api/` 或 `src/handlers/` 目录内工作时才会加载。未指定 `paths` 字段的规则会在每次会话中无条件加载。
This is the right pattern once your CLAUDE.md starts feeling crowded. 当你的 `CLAUDE.md` 开始显得拥挤时，这是正确的模式。
The hooks system: deterministic control over Claude’s behavior 钩子系统：对 Claude 行为的确定性控制
CLAUDE.md instructions are good. But they’re suggestions. Claude follows them most of the time, not all of the time. You can’t rely on a language model to always run your linter, never execute a dangerous command, or consistently notify you when it’s done. CLAUDE.md 指令虽然不错，但它们只是建议。Claude 大多数时候会遵循这些指令，但并非总是如此。你不能指望语言模型总是运行你的代码检查工具、永远不执行危险命令，或者始终在任务完成时通知你。
Hooks make these behaviors deterministic. They’re event handlers that fire automatically at specific points in Claude’s workflow. Your shell script runs every time, no exceptions. 钩子让这些行为变得确定可靠。它们是事件处理程序，会在 Claude 工作流程的特定节点自动触发。你的 shell 脚本每次都会执行，无一例外。
All hook configuration lives in settings.json under a hooks key. Claude Code snapshots the config at session start, receives a JSON payload on stdin when an event fires, and uses exit codes to decide what happens next. The critical thing to know: exit code 2 is the only code that blocks execution. Exit 0 means success. Exit 1 means error but non-blocking. Exit 2 means stop everything and send your stderr to Claude for self-correction. Using exit 1 for security hooks is the most common mistake. It logs an error and does nothing. 所有钩子配置都存放在 `settings.json` 文件的 `hooks` 键下。Claude Code 会在会话启动时对配置进行快照，事件触发时通过标准输入接收 JSON 数据，并根据退出码决定后续操作。关键信息是：退出码 2 是唯一会阻止执行的代码。退出 0 表示成功。退出 1 表示错误，但不会阻塞。退出 2 表示停止一切操作，并将你的标准错误输出发送给 Claude 进行自我修正。最常见的错误是在安全钩子中使用退出码 1，这只会记录一个错误，却什么也不会阻止。
.claude/
├── settings.json # hooks config lives here, under the "hooks" key
└── hooks/ # your hook scripts (convention, not required)
├── bash-firewall.sh # PreToolUse: blocks dangerous commands
├── auto-format.sh # PostToolUse: runs formatter on edited files
└── enforce-tests.sh # Stop: ensures tests pass before finishingThe events you’ll use most: PreToolUse (fires before any tool runs, your security gate), PostToolUse (fires after a tool succeeds, for formatters and linters), Stop (fires when Claude finishes, for quality gates like “tests must pass”), UserPromptSubmit (fires when you press enter, for prompt validation), Notification (for desktop alerts), and SessionStart/SessionEnd (for context injection and cleanup). For tool events, a matcher regex field narrows which tools trigger the hook. “Write|Edit|MultiEdit” targets file changes. “Bash” targets shell commands. Omitting it matches everything.你最常使用的事件有：PreToolUse（在任何工具运行前触发，是你的安全门禁）、PostToolUse（在工具成功执行后触发，用于格式化工具和代码检查工具）、Stop（在Claude完成工作时触发，用于质量门禁，如”测试必须通过”）、UserPromptSubmit（在你按下回车时触发，用于提示词验证）、Notification（用于桌面通知），以及SessionStart/SessionEnd（用于上下文注入和清理）。对于工具事件，一个匹配器正则表达式字段可以缩小触发钩子的工具范围。“Write|Edit|MultiEdit”针对文件修改。“Bash”针对Shell命令。省略该字段则匹配所有事件。
Here’s what a typical hooks config looks like. This auto-formats every file Claude touches and blocks dangerous bash commands: 以下是一个典型的钩子配置示例。它能自动格式化Claude处理的所有文件，并拦截危险的bash命令：
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null"
}
]
}
],
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bash-firewall.sh" }
]
}
]
}
}The bash firewall script reads the command from stdin, checks it against dangerous patterns like rm -rf /, git push —force main, and DROP TABLE, and exits with code 2 to block anything that matches. 这个bash防火墙脚本从标准输入读取命令，检查是否包含`rm -rf /`、`git push —force main`、`DROP TABLE`等危险模式，若匹配则退出代码2进行拦截。
Stop hooks are equally powerful. A script that runs npm test and exits with code 2 on failure will prevent Claude from declaring “done” until the suite is green. One gotcha: always check the stop_hook_active flag in the JSON payload. Without it, the hook blocks Claude, Claude retries, the hook blocks again, and you get an infinite loop. Let Claude stop on the second attempt. 停止钩子同样强大。如果脚本运行 `npm test` 并在失败时返回退出码 2，Claude 在测试套件全部通过前就不会宣布任务完成。需要注意一点：始终检查 JSON 数据中的 `stop_hook_active` 标志。若不检查，钩子会阻止 Claude，Claude 重试，钩子再次阻止，导致无限循环。让 Claude 在第二次尝试时停止。
For desktop notifications, a Notification hook with osascript (macOS) or notify-send (Linux) wired up in /.claude/settings.json works across all projects. 对于桌面通知，在 `/.claude/settings.json` 中配置好使用 `osascript`（macOS）或 `notify-send`（Linux）的通知钩子后，即可跨所有项目生效。
A few things to watch out for. Hooks don’t hot-reload mid-session. PostToolUse can’t undo anything since the tool already ran, so use PreToolUse if you need to prevent an action. Hooks fire recursively for subagent actions too. And hooks execute with your full user permissions and no sandboxing, so always quote shell variables, validate JSON input, and use absolute paths for script references. 有几点需要注意。钩子在会话期间不会热重载。`PostToolUse` 无法撤销任何操作，因为工具已经执行完毕，如需阻止某个操作请使用 `PreToolUse`。钩子也会递归触发子代理的操作。此外，钩子以你的完整用户权限执行且不经过沙箱，因此务必对 shell 变量加引号、验证 JSON 输入、使用脚本的绝对路径。
The skills/ folder: reusable workflows on demand `skills/` 文件夹：按需调用的可复用工作流
Skills are workflows that Claude can invoke on its own, based on the context, when the task matches the skill’s description. Skills watch the conversation and act when the moment is right.技能是指Claude在遇到与技能描述匹配的任务时，可根据上下文自主调用的工作流程。技能会监控对话进程，在合适的时机采取行动。
Each skill lives in its own subdirectory with a SKILL.md file: 每个技能都存放在独立的子目录中，并包含一个SKILL.md文件：
.claude/skills/
├── security-review/
│ ├── SKILL.md
│ └── DETAILED_GUIDE.md
└── deploy/
├── SKILL.md
└── templates/
└── release-notes.mdThe SKILL.md uses YAML frontmatter to describe when to use it: SKILL.md通过YAML前置元数据描述技能的适用场景：
---
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.When you say “review this PR for security issues,” Claude reads the description, recognizes it matches, and invokes the skill automatically. You can also call it explicitly with /security-review.当您说“审核此 PR 的安全问题”时，Claude 会读取描述内容，识别出匹配项，并自动调用该技能。您也可以使用 /security-review 显式调用它。
The key difference from commands: skills can bundle supporting files alongside them. The @DETAILED_GUIDE.md reference above pulls in a detailed document that lives right next to SKILL.md. Commands are single files. Skills are packages.与命令的关键区别在于：技能可以附带支持文件。上述 @DETAILED_GUIDE.md 引用会拉取一个与 SKILL.md 同目录的详细文档。命令是单个文件，而技能是文件包。
Personal skills go in ~/.claude/skills/ and are available across all your projects.个人技能存放在 ~/.claude/skills/ 中，并可在您所有项目中调用。
The agents/ folder: specialized subagent personas agents/ 文件夹：专业子代理角色
When a task is complex enough to benefit from a dedicated specialist, you can define a subagent persona in .claude/agents/. Each agent is a markdown file with its own system prompt, tool access, and model preference: 当任务复杂到需要专业分工时，你可以在 .claude/agents/ 文件中定义子代理角色。每个代理都是一个 markdown 文件，包含独立的系统提示、工具权限和模型偏好：
.claude/agents/
├── code-reviewer.md
└── security-auditor.mdHere’s what a code-reviewer.md looks like: 以下是一个 code-reviewer.md 文件示例：
---
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 scaleWhen Claude needs a code review done, it spawns this agent in its own isolated context window. The agent does its work, compresses the findings, and reports back. Your main session doesn’t get cluttered with thousands of tokens of intermediate exploration. 当 Claude 需要进行代码审查时，它会在独立的上下文窗口中创建这个代理。该代理完成工作后，会压缩发现并报告结果。您的主会话不会因包含数千个中间探索的标记而变得杂乱。
The tools field restricts what the agent can do. A security auditor only needs Read, Grep, and Glob. It has no business writing files. That restriction is intentional and worth being explicit about. 工具字段限制了代理可以执行的操作。安全审计员只需要 Read、Grep 和 Glob 功能，无需写入文件。这种限制是刻意的，值得明确说明。
The model field lets you use a cheaper, faster model for focused tasks. Haiku handles most read-only exploration well. Save Sonnet and Opus for the work that actually needs them. 模型字段允许您为特定任务使用更便宜、更快速的模型。Haiku 能很好地处理大多数只读探索任务。将 Sonnet 和 Opus 留给真正需要它们的任务使用。
Personal agents go in ~/.claude/agents/ and are available across all projects.个人代理存放在 ~/.claude/agents/ 目录下，并可在所有项目中跨项目使用。
settings.json: permissions and project config settings.json：权限与项目配置
The settings.json file inside .claude/ controls what Claude is and isn’t allowed to do. This is also where your hooks live and it’s where you define which tools Claude can run, which files it can read, and whether it needs to ask before running certain commands.位于 .claude/ 内部的 settings.json 文件用于控制 Claude 允许和禁止执行的操作。同时，这也是存放钩子函数的地方，你可以在此定义 Claude 可运行的工具、可读取的文件，以及执行某些命令前是否需要征求许可。
The complete file looks like this: 完整文件内容如下：
{
"$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.*)"
]
}
}Here’s what each part does. 以下是每个部分的作用：
The $schema line enables autocomplete and inline validation in VS Code or Cursor. Always include it.$schema 这一行可以在 VS Code 或 Cursor 中启用自动补全和内联验证。请始终保留它。
The allow list contains commands that run without Claude asking for confirmation. For most projects, a good allow list covers:允许列表包含那些无需 Claude 请求确认即可运行的命令。对于大多数项目来说，一个完善的允许列表应涵盖：
- Bash(npm run *) or Bash(make *) so Claude can run your scripts freely Bash(npm run *) 或 Bash(make *) 可让 Claude 自由运行你的脚本
- Bash(git *) for read-only git commands Bash(git *) 用于只读的 git 命令
- Read, Write, Edit, Glob, Grep for file operations Read（读取）、Write（写入）、Edit（编辑）、Glob（文件匹配）、Grep（搜索）用于文件操作
The deny list contains commands that are blocked entirely, no matter what. A sensible deny list blocks:拒绝列表中的命令无论何种情况都被完全禁止。合理的拒绝列表会屏蔽：
- Destructive shell commands like rm -rf 破坏性 shell 命令（如 rm -rf）
- Direct network commands like curl 直接网络命令（如 curl）
- Sensitive files like .env and anything in secrets/ 敏感文件（如 .env 及 secrets/ 目录下的所有内容）
If something isn’t in either list, Claude asks before proceeding. That middle ground is intentional. It gives you a safety net without having to anticipate every possible command upfront.如果某操作不在上述任一列表中，Claude 会在执行前询问确认。这种中间地带的设置是经过深思熟虑的——它为你提供了安全防护，同时无需预先设想所有可能的命令。
settings.local.json for personal overrides settings.local.json 用于个人覆盖配置
Same idea as CLAUDE.local.md. Create .claude/settings.local.json for permission changes you don’t want committed. It’s auto-gitignored.与 CLAUDE.local.md 思路相同。创建 .claude/settings.local.json 文件，用于存放你不想提交的权限变更设置。该文件会自动被 .gitignore 忽略。
The global ~/.claude/ folder 全局 ~/.claude/ 文件夹
You don’t interact with this folder often, but it’s useful to know what’s in it. 虽然不常与这个文件夹交互，但了解其内容还是很有用的。
~/.claude/CLAUDE.md loads into every Claude Code session, across all your projects. Good place for your personal coding principles, preferred style, or anything you want Claude to remember regardless of which repo you’re in.~/.claude/CLAUDE.md 会加载到每个 Claude Code 会话中，并应用于你的所有项目。适合存放你的个人编码原则、偏好风格，或者任何你希望 Claude 无论身处哪个仓库都能记住的内容。
~/.claude/projects/ stores session transcripts and auto-memory per project. Claude Code automatically saves notes to itself as it works: commands it discovers, patterns it observes, architecture insights. These persist across sessions. You can browse and edit them with /memory.~/.claude/projects/ 用于存储每个项目的会话记录和自动记忆。Claude Code 会在工作时自动保存笔记：包括它发现的命令、观察到的模式、架构洞见等。这些记忆会跨会话持续存在。你可以通过 /memory 命令浏览和编辑它们。
~/.claude/commands/ and ~/.claude/skills/ hold personal commands and skills available across all projects.~/.claude/commands/ 和 ~/.claude/skills/ 存放了可在所有项目中使用的个人命令和技能。
You generally don’t need to manually manage these. But knowing they exist is handy when Claude seems to “remember” something you never told it, or when you want to wipe a project’s auto-memory and start fresh. 通常你不需要手动管理这些文件。但当 Claude 似乎”记得”你从未告诉过它的信息时，或者你想清除某个项目的自动记忆重新开始时，了解这些文件的存在就会派上用场。
The full picture 整体概览
Here’s how everything comes together: 以下是各个部分如何协同运作的全貌：
your-project/
├── CLAUDE.md # Team instructions (committed)
├── CLAUDE.local.md # Your personal overrides (gitignored)
│
└── .claude/
├── settings.json # Permissions, hooks, config (committed)
├── settings.local.json # Personal permission overrides (gitignored)
│
├── hooks/ # Hook scripts referenced by settings.json
│ ├── bash-firewall.sh # PreToolUse: block dangerous commands
│ ├── auto-format.sh # PostToolUse: format files after edits
│ └── enforce-tests.sh # Stop: ensure tests pass before finishing
│
├── rules/ # Modular instruction files
│ ├── code-style.md
│ ├── testing.md
│ └── api-conventions.md
│
├── skills/ # Auto-invoked workflows
│ ├── security-review/
│ │ └── SKILL.md
│ └── deploy/
│ └── SKILL.md
│
└── agents/ # Specialized subagent personas
├── code-reviewer.md
└── security-auditor.md
~/.claude/
├── CLAUDE.md # Your global instructions
├── settings.json # Your global settings + hooks
├── skills/ # Your personal skills (all projects)
├── agents/ # Your personal agents (all projects)
└── projects/ # Session history + auto-memoryA practical setup to get started 一个可供上手实践的实用配置方案
If you’re starting from scratch, here’s a progression that works well. 如果从零开始，这个渐进方案效果不错。
Step 1. Run /init inside Claude Code. It generates a starter CLAUDE.md by reading your project. Edit it down to the essentials.步骤1：在Claude Code中运行 /init。它会读取你的项目并生成初始 CLAUDE.md 文件。将其精简至核心内容。
Step 2. Add .claude/settings.json with allow/deny rules appropriate for your stack. At minimum, allow your run commands and deny .env reads.步骤2：添加 .claude/settings.json，并根据你的技术栈设置允许/拒绝规则。至少需允许运行命令并拒绝读取 .env 文件。
Step 3. Create one or two commands for the workflows you do most. Code review and issue fixing are good starting points.步骤3：为你最常使用的工作流程创建一至两个命令。代码审查和问题修复是不错的起点。
Step 4. As your project grows and your CLAUDE.md gets crowded, start splitting instructions into .claude/rules/ files. Scope them by path where it makes sense.第4步：随着项目规模扩大，当你的`CLAUDE.md`文件变得臃肿时，开始将指令拆解到`.claude/rules/`文件夹中。根据实际路径进行范围限定。
Step 5. Add a /.claude/CLAUDE.md with your personal preferences. This might be something like “always write types before implementations” or “prefer functional patterns over class-based.”第5步：创建`/.claude/CLAUDE.md`文件，添加你的个人偏好设置。例如可以写上”总是先写类型再写实现”或”优先使用函数式模式而非基于类的方式”。
That’s genuinely all you need for 95% of projects. Skills and agents come in when you have recurring complex workflows worth packaging up. 对于95%的项目而言，这些真的就是你需要的一切。当你拥有值得打包封装的、重复出现的复杂工作流程时，才需要用到技能和智能体。
The key insight 关键在于
The .claude folder is really a protocol for telling Claude who you are, what your project does, and what rules it should follow. The more clearly you define that, the less time you spend correcting Claude and the more time it spends doing useful work..claude 文件夹本质上是一套协议，用于告诉 Claude 你是谁、你的项目做什么、以及它应遵循什么规则。你定义得越清晰，花在纠正 Claude 上的时间就越少，而它花在有用工作上的时间就越多。
CLAUDE.md is your highest-leverage file. Get that right first. Everything else is optimization.CLAUDE.md 是你杠杆率最高的文件。先把这份文件做对，其他一切都只是优化。
Start small, refine as you go, and treat it like any other piece of infrastructure in your project: something that pays dividends every day once it’s set up properly. 从小处着手，逐步完善，把它当作项目中任何其他基础设施来对待：一旦正确设置，它每天都会带来回报。
That’s a wrap! 这就是今天的全部内容！
If you enjoyed reading this. 如果你喜欢阅读这篇文章。
Find me → @akshay_pachaar ✔️找到我 → @akshay_pachaar ✔️
Every day, I share tutorials and insights on AI, Machine Learning and vibe coding best practices. 每天，我都会分享关于人工智能、机器学习以及“氛围编程”最佳实践的教程和见解。