别再裸奔用 Claude Code 了：高手都在先做这套配置

· 2026-06-25 · # X文章收藏

很多人用 Claude Code，第一天都很兴奋。

打开项目。
输入一句：

帮我修一下这个 bug。

然后 Claude 开始读文件、改代码、跑命令。

看起来像一个真正的工程师。

但用几天之后，问题就来了：

它有时候会过度设计。
它会忘记你们项目的约定。
它会改着改着偏离原需求。
它会说“完成了”，但测试其实没跑。
它会在上下文快满的时候变得越来越飘。
它会把本来简单的改动做成一套复杂架构。

这时候很多人第一反应是：

是不是我的提示词写得不够好？

但真正用得好的人，思路完全不同。

他们不是每次都临时写一个更长的 prompt。

他们是在任务开始之前，先给 Claude Code 搭好一套工作环境。

换句话说：

新手在写提示词。
高手在搭系统。

Claude Code 不应该被当成聊天框。

它更像一个刚加入项目的新同事。

如果你不给它项目背景、代码规范、测试方式、提交习惯、禁止事项和验收标准，它当然只能靠猜。

所以这篇文章不是讲“神级提示词”。

而是手把手教你搭一套真正能长期复用的 Claude Code 配置：

一个不臃肿的 CLAUDE.md
一组可复用的 Skills / slash commands
一个专门负责审查的 reviewer 子代理
一套 rules 文件，把规则按场景拆开
一个 permissions / hooks 安全兜底
一个上下文快满时的重启流程
照着配完，你会明显感觉到：

Claude Code 不再像一个临时外包。

而更像一个知道项目规矩的协作者。

一、先建立正确认知：Claude Code 不是“更聪明的聊天框”

大多数人用 Claude Code 的方式是这样的：

帮我实现登录功能
帮我修这个报错
帮我优化这个页面
帮我写单元测试

这当然能用。

但问题是，每一次都是“临时对话”。

你每次都要重新告诉它：

项目是什么
技术栈是什么
用 npm 还是 pnpm
测试怎么跑
哪些文件不能碰
提交格式是什么
什么时候算完成
不要过度封装
不要改无关文件
如果你不写，它就猜。
如果你每次都写，你就累。
如果你写得太长，它又可能忽略重点。

所以更好的方式是：

把稳定不变的规则，写进项目结构里。
把重复执行的流程，做成命令。
把必须遵守的限制，交给 permissions 和 hooks。
把审查工作，交给另一个独立角色。

这样 Claude Code 才不是“听你一句话干活”。

而是在一套明确的工程规则里干活。

二、先建这套目录结构

在你的项目根目录下，建议先整理成这样：

your-project/
├── CLAUDE.md
├── CLAUDE.local.md
├── .claude/
│ ├── settings.json
│ ├── settings.local.json
│ ├── rules/
│ │ ├── code-style.md
│ │ ├── testing.md
│ │ ├── security.md
│ │ └── frontend.md
│ ├── skills/
│ │ ├── pr/
│ │ │ └── SKILL.md
│ │ ├── diff-review/
│ │ │ └── SKILL.md
│ │ ├── test/
│ │ │ └── SKILL.md
│ │ └── handoff/
│ │ └── SKILL.md
│ ├── agents/
│ │ └── reviewer.md
│ └── session-notes/
│ └── README.md

简单解释一下：

CLAUDE.md：项目级总说明，团队可以一起维护，建议提交到 Git。
CLAUDE.local.md：你自己的私人偏好，比如本机环境、个人习惯，不建议提交。
.claude/rules/：更细的规则，比如测试规范、前端规范、安全规范。
.claude/skills/：可复用工作流，比如 /pr、/diff-review、/handoff。
.claude/agents/：子代理，比如只负责审查、不负责改代码的 reviewer。
.claude/settings.json：权限、hooks、环境变量等配置。
.claude/session-notes/：上下文快满时，用来保存进度和交接记录。

如果你之前用的是 .claude/commands/，也不是不能用。

但新项目更建议优先使用 .claude/skills/。

因为 Skills 更适合做成长期可复用的工作流，可以放说明、规则、脚本、模板和辅助文件。

你不需要一开始就把所有东西写满。

先搭骨架，再逐步补充。

Claude Code 的配置不要追求“大而全”。

真正好用的配置，一定是：

短
清楚
可维护
能复用

三、先写一个不超过 200 行的 CLAUDE.md

很多人第一个错误，就是把 CLAUDE.md 写成项目百科全书。

写 400 行、800 行，甚至上千行。
把架构、接口、目录、业务背景、代码风格、部署流程全部塞进去。

这看起来很认真，实际很容易适得其反。

因为 CLAUDE.md 是 Claude 每次进入项目都要读的长期上下文。

你放进去的每一行，都会占用注意力。

越长，越容易把真正重要的规则淹没。

我的建议是：

CLAUDE.md 只放“每次都必须知道”的东西。

可以直接用这个模板：

CLAUDE.md

Project

这是一个用 Next.js + TypeScript 构建的 Web 项目。

主要入口在 src/app，组件在 src/components，业务逻辑在 src/lib。

请优先阅读相邻文件，遵循现有模式，不要重新发明一套架构。

Tech Stack

Framework: Next.js
Language: TypeScript
Package manager: pnpm
Styling: Tailwind CSS
Test: Vitest / Playwright

Core Rules

Use the simplest approach that works.
Match existing patterns before creating new abstractions.
Do not introduce a new library unless there is a clear reason.
Do not rename public APIs unless explicitly asked.
Do not modify unrelated files.
Do not silently skip tests.
Before saying the task is done, explain what was changed and how it was verified.

Commands

Install: pnpm install
Dev: pnpm dev
Lint: pnpm lint
Typecheck: pnpm typecheck
Test: pnpm test
E2E: pnpm e2e

Workflow

When working on a task:

First inspect the relevant files.
Then write a short plan.
Make the smallest safe change.
Run the relevant checks.
Summarize the diff.
Mention any risks or follow-up work.

Git Rules

Never push directly to main.
Use a feature branch.
Commit only after tests or checks pass.
Commit message format: type(scope): summary

Context Management

When context usage gets high:

Write current plan, progress, changed files, open questions, and next steps to .claude/session-notes/YYYY-MM-DD-task.md.
Ask the user to run /clear.
Start the next session by reading that handoff file.

这里面最重要的一句是：

Use the simplest approach that works.

中文意思就是：

用能解决问题的最简单方案。

这句话非常关键。

因为 AI 写代码很容易“炫技”：

简单需求给你抽象三层。
一个按钮状态给你设计状态机。
一个接口请求给你封装通用框架。
一个页面改动给你重构半个项目。

你必须明确告诉它：

先匹配已有模式。
先做最小改动。
不要提前抽象。
不要为了看起来高级而重构。

Claude Code 不是不能写复杂代码。

而是它需要知道：

什么时候不该复杂。

四、把细规则拆到 .claude/rules/

CLAUDE.md 只放总规则。

更细的规则，不要全部塞进去。

比如：

前端组件规则
API 设计规则
测试规则
安全规则
文档规则
数据库迁移规则
这些可以放到 .claude/rules/ 里。

例如：

.claude/rules/
├── frontend.md
├── api.md
├── testing.md
└── security.md

示例 1：前端规则

新建：

.claude/rules/frontend.md

内容：

Frontend Rules

Prefer small components over large component files.
Use existing design tokens and Tailwind patterns.
Do not introduce a new UI library.
Keep accessibility in mind: labels, aria attributes, keyboard navigation.
Before creating a new component, check whether a similar component already exists.
Avoid unnecessary client components. Use server components by default unless interactivity is required.

这类规则适合放“写代码时应该怎么做”。

示例 2：测试规则

新建：

.claude/rules/testing.md

内容：

Testing Rules

Add or update tests for behavior changes.
Prefer focused tests over broad snapshot tests.
If a test cannot be added, explain why.
Run the most relevant test first.
Do not claim a task is complete without mentioning test status.

示例 3：安全规则

新建：

.claude/rules/security.md

内容：

Security Rules

Never read or print secrets from .env, .env.local, credential files, or private keys.
Never commit secrets.
Validate all external input.
Do not disable auth, rate limits, or permission checks unless explicitly requested.
For destructive operations, stop and ask for confirmation.

注意：

这类规则能提高 Claude 的行为稳定性，但它不是完整沙箱。

如果是“绝对不能做”的事，不要只写在规则里。

要放到 permissions 里。

如果涉及真实密钥、生产数据、客户数据，最好再配合：

dev container
sandbox
只读副本
测试环境
人工确认发布动作
记住：

自然语言规则适合指导行为。
安全边界必须用配置兜底。

五、把重复操作做成 Skills

很多人每天都在重复输入同样的话：

帮我检查这个 PR，看看有没有问题
帮我跑测试、lint，然后总结改动
帮我根据当前 diff 写 PR 描述
帮我整理上下文，准备开新会话

这类重复流程，不应该每次手写。

应该做成 Skill。

比如你创建：

.claude/skills/pr/SKILL.md

内容：

name: pr
description: Prepare a clean PR from the current branch
disable-model-invocation: true
allowed-tools:
- Read
- Grep
- Glob
- Bash(git status)
- Bash(git diff)
- Bash(git diff )
- Bash(pnpm lint)
- Bash(pnpm typecheck)
- Bash(pnpm test)
- Bash(pnpm test )
model: sonnet

Prepare this branch for a clean pull request.

Steps:

Inspect current git status.
Review the diff against the base branch.
Run lint.
Run typecheck.
Run relevant tests.
If anything fails, stop and report the failure clearly.
Summarize changes grouped by file.
Write a concise PR title.
Write a PR description with:
- What changed
- Why it changed
- How it was tested
- Risks
Do not push directly to main.

以后你只需要输入：

/pr

Claude 就会按固定流程走。

这就是 Skill 的价值：

把“临时提示词”变成“团队流程”。

这里有一个关键点：

不要随手写：

allowed-tools: Read, Grep, Glob, Bash

尤其不要裸写 Bash。

更稳的方式是只放你允许它执行的具体命令：

Bash(git status)
Bash(git diff *)
Bash(pnpm lint)
Bash(pnpm typecheck)
Bash(pnpm test *)

因为 allowed-tools 不是“只允许这些工具”。

它更像是“这些工具在这个 Skill 里可以更顺畅地使用”。

如果你想明确禁止编辑，就要配合：

disallowed-tools:

Edit
Write
MultiEdit

所以，安全配置要保守一点。

能写具体命令，就不要给裸 Bash。

六、做一个 /diff-review：只审查，不改代码

不要把这个命令叫 /review。

因为 Claude Code 自己也有 review 相关的内置命令。

为了避免混淆，建议你叫：

/diff-review

创建：

.claude/skills/diff-review/SKILL.md

内容：

name: diff-review
description: Review current local diff without editing files
disable-model-invocation: true
allowed-tools:
- Read
- Grep
- Glob
- Bash(git status)
- Bash(git diff)
- Bash(git diff *)
- Bash(git diff –name-only)
disallowed-tools:
- Edit
- Write
- MultiEdit
model: sonnet

Review the current local diff.

Rules:

Do not edit files.
Compare the diff against the original task.
Check correctness, missing requirements, risky assumptions, and test coverage.
Ignore pure style preferences unless they affect maintainability or correctness.
Return findings in this format:

Blocking issues
Non-blocking concerns
Missing tests
Suggested next step

If the diff looks good, say so clearly.

这个 Skill 的作用很明确：

只看 diff
只找问题
不动文件
不重构
不顺手优化

你可以在每次重要改动之后运行：

/diff-review

让 Claude 对照原始任务看一遍当前改动有没有跑偏。

七、做一个 /test：专门跑检查

创建：

.claude/skills/test/SKILL.md

内容：

name: test
description: Run relevant checks for the current change
disable-model-invocation: true
allowed-tools:
- Read
- Grep
- Glob
- Bash(git status)
- Bash(git diff)
- Bash(git diff –name-only)
- Bash(pnpm lint)
- Bash(pnpm typecheck)
- Bash(pnpm test)
- Bash(pnpm test *)
model: sonnet

Run the most relevant checks for the current change.

Steps:

Inspect changed files.
Decide which tests are relevant.
Run lint if available.
Run typecheck if available.
Run focused tests first.
If focused tests pass and the change is broad, suggest whether full tests are needed.
Summarize results clearly.

Always report:

Commands run
Passed checks
Failed checks
Checks not run
Remaining risk

这条命令能解决一个很常见的问题：

Claude 经常会说：

实现好了。

但它没有告诉你：

跑了什么
什么通过了
什么没跑
为什么没跑
还剩什么风险
所以你要把“验收”变成固定流程。

不要相信一句“应该没问题”。

要看检查结果。

八、做一个 /handoff：上下文快满时保存交接

很多长任务最后崩掉，不是 Claude 不会写代码。

而是上下文太长之后，它开始忘记早期约束。

与其等它自动压缩，不如主动交接。

创建：

.claude/skills/handoff/SKILL.md

内容：

name: handoff
description: Save current progress before clearing context
disable-model-invocation: true
allowed-tools:
- Read
- Grep
- Glob
- Bash(git status)
- Bash(git diff)
- Bash(git diff –name-only)
- Write
model: sonnet

Create a handoff note in .claude/session-notes/.

Include:

Original user request
Current plan
Files changed
Commands run
Test results
Decisions made
Open questions
Risks
Next recommended action

After writing the note, tell the user to run /clear.

In the next session, start by reading the handoff file before continuing.

用的时候输入：

/handoff

它会生成类似这样的文件：

.claude/session-notes/2026-06-25-auth-refactor.md

内容结构可以是：

Handoff: Auth Refactor

Original Request

用户要求修复登录失败后空白页的问题，并补充测试。

Current Status

已定位问题在 src/lib/auth.ts 的错误处理逻辑。
已修改登录失败时的返回值。
前端页面已增加错误提示。

Files Changed

src/lib/auth.ts
src/app/login/page.tsx
src/lib/auth.test.ts

Commands Run

pnpm lint
pnpm test src/lib/auth.test.ts

Test Results

Focused tests passed.
Full test suite not yet run.

Decisions Made

保留现有 auth 结构，不引入新状态管理库。
只做最小修复，不重构登录模块。

Open Questions

是否需要补 Playwright E2E 测试？

Risks

完整测试套件还没跑。
登录失败场景已覆盖，但第三方 OAuth 流程还没验证。

Next Step

运行完整测试套件。
然后让 reviewer 审查当前 diff。

然后执行：

/clear

新会话开始时输入：

Read .claude/session-notes/2026-06-25-auth-refactor.md and continue from there.

这样比盲目依赖自动压缩更稳。

因为你明确控制了什么信息被保留下来。

不会把关键约束交给自动总结来决定。

九、配置 reviewer 子代理：让“写代码的人”和“审代码的人”分开

这是很多人忽略的一步。

你让同一个 Claude：

先写代码，
再审查自己写的代码。

效果往往一般。

因为它会天然倾向于相信自己的实现。
它会解释自己为什么这么写。
它会漏掉自己一开始就理解错的地方。

更好的方式是：

创建一个只负责审查、不负责修改的 reviewer。

新建：

.claude/agents/reviewer.md

内容：

name: reviewer
description: Reviews a diff against the plan. Finds correctness gaps. Never edits files.
tools: Read, Grep, Glob
model: sonnet

You are a strict but practical code reviewer.

You review code you did not write.

Your job is not to make the code prettier.
Your job is to find gaps against the stated task.

Review process:

Read the original task or plan.
Read the current diff or changed files.
Check whether every requirement is implemented.
Check whether behavior changes are tested.
Check whether the solution introduces unnecessary complexity.
Check whether unrelated files were modified.
Check whether the implementation matches existing project patterns.

Important:

Do not edit files.
Do not run shell commands.
Do not nitpick style unless it affects correctness.
Do not invent hypothetical edge cases.
Focus on correctness, missing requirements, regressions, and test coverage.
If the work is sound, say so directly.

Output format:

Verdict

Pass / Needs changes

Blocking issues

List only issues that must be fixed.

Missing tests

List missing tests if any.

Notes

Short practical notes only.

用的时候可以这样说：

Use the reviewer subagent to review the current diff against the original task.
Do not edit files.
Only report correctness issues, missing requirements, and missing tests.

或者在 Claude Code 里用 @reviewer 指定这个子代理。

这套“编写者 / 审阅者”模式，比让 Claude 自己检查自己更稳。

尤其适合这些场景：

改登录鉴权
改支付流程
改数据库迁移
改权限判断
改线上 bug
大范围重构
PR 合并前检查
记住一句话：

写代码和审代码，最好不要是同一个脑子。

哪怕都是 Claude，也要拆成两个角色。

十、用 settings 和 permissions 做安全边界

CLAUDE.md 和 rules 是行为指导。

但它们不是绝对保险。

比如你写：

不要读取 .env
不要直接 push main
不要运行危险命令

Claude 大多数时候会遵守。

但只要是自然语言规则，就有被忽略、误解、冲突的可能。

所以真正危险的限制，要交给配置层。

新建或编辑：

.claude/settings.json

可以先放一个保守版本：

{
“permissions”: {
“deny”: [
“Read(/.env)”,
“Read(/.env.)”,
“Read(**/.pem)”,
“Read(/*.key)”,
“Read(/secrets/)”,
“Read(/private/**)”,
“Bash(rm -rf *)”,
“Bash(rm -fr *)”,
“Bash(git push origin main)”,
“Bash(git push origin master)”
],
“ask”: [
“Bash(git push *)”,
“Bash(npm publish *)”,
“Bash(pnpm publish *)”,
“Bash(docker compose down *)”,
“Bash(kubectl *)”,
“Bash(terraform apply *)”
],
“allow”: [
“Bash(git status)”,
“Bash(git diff)”,
“Bash(git diff *)”,
“Bash(pnpm lint)”,
“Bash(pnpm typecheck)”,
“Bash(pnpm test)”,
“Bash(pnpm test *)”
]
}
}

这类配置的思路很简单：

常规读取：允许
常规测试：允许
发布、推送、删除、基础设施操作：必须询问
secrets、私钥、敏感目录：禁止
直接 push main：禁止
但这里要注意：

permissions 是 Claude Code 层面的安全边界，不是完整沙箱。

如果你让 Bash 跑一个脚本，而脚本内部自己读取文件，权限规则未必能替你挡住所有风险。

所以真正敏感的项目，不要只靠 Claude Code 配置。

更稳的做法是：

在测试副本里操作
不把真实 .env 放进工作区
用 dev container 隔离环境
生产密钥不落地
发布动作必须人工确认
高风险操作必须走 CI/CD
一句话：

CLAUDE.md 负责告诉它该怎么做。
permissions 负责第一道安全边界。
真正高风险的事，还要靠环境隔离。

十一、hooks 只做辅助，不要当安全系统

如果你经常忘记 Claude 是否在等你确认，可以加一个通知 hook。

例如 macOS：

{
“hooks”: {
“Notification”: [
{
“matcher”: “”,
“hooks”: [
{
“type”: “command”,
“command”: “osascript -e ‘display notification "Claude Code needs your attention" with title "Claude Code"‘“
}
]
}
]
}
}

Windows 和 Linux 可以换成对应的通知命令。

更实用的 hook 是：

Claude 每次改完文件之后，自动格式化。

例如：

{
“hooks”: {
“PostToolUse”: [
{
“matcher”: “Edit|Write”,
“hooks”: [
{
“type”: “command”,
“command”: “file=$(jq -r ‘.tool_input.file_path // empty’); if [ -n "$file" ]; then pnpm prettier –write "$file"; fi”
}
]
}
]
}
}

但 hooks 不要一上来配太激进。

先从这几类开始：

通知
格式化
日志记录
简单安全提醒
自动跑轻量检查
不要一上来就让 hooks 自动提交、自动发布、自动迁移数据库。

hooks 的原则是：

让重复动作自动化
不要让危险动作自动化

尤其要记住：

hooks 适合辅助流程。
permissions 才适合做权限边界。
生产级安全要靠环境隔离。

十二、加一个 .gitignore，别把本地隐私提交上去

很多教程会漏掉这一步。

你既然建了本地配置，就要想清楚哪些东西能提交，哪些不能提交。

建议在 .gitignore 里加：

CLAUDE.local.md
.claude/settings.local.json
.claude/session-notes/

为什么？

CLAUDE.local.md 可能有你的本机路径、个人偏好。
settings.local.json 可能有你自己的权限设置。
session-notes/ 可能有内部任务、客户信息、bug 细节、业务路径。

如果是团队协作，可以提交这些：

CLAUDE.md
.claude/settings.json
.claude/rules/
.claude/skills/
.claude/agents/

但本地配置和交接记录，默认不要提交。

除非你明确知道里面没有敏感信息。

十三、上下文快满时，不要硬撑

Claude Code 长任务最容易翻车的地方，不是开始。

而是中后段。

一开始它很清楚：

项目读过了。
计划写好了。
文件也改了。
测试也跑了一部分。

然后上下文越来越长。

你继续追问：

再顺手改一下这个。
再帮我优化一下。
再把测试补一下。
再看一下刚才的问题。

这时它开始变得不稳定：

忘记原需求
重复解释
修改无关文件
把已经确定的方案推翻
测试没跑却说完成
对旧错误产生错误记忆
所以不要等它崩。

我建议在 CLAUDE.md 里明确写一条：

Context Management

When context usage gets high or the task becomes long:

Stop making new changes.
Write a handoff note to .claude/session-notes/.
Include original request, current status, changed files, commands run, test results, risks, and next steps.
Ask the user to run /clear.
In the new session, read the handoff note first before continuing.

你也可以直接运行：

/handoff

然后：

/clear

新会话读 handoff 文件继续。

这一步会救你很多次。

十四、给中文用户的一套 30 分钟配置流程

如果你不想研究太多，直接照这个顺序做。

第 1 步：初始化 Claude Code

在项目根目录运行：

claude

进入后先执行：

/init

让 Claude 帮你生成一个初始版 CLAUDE.md。

但不要直接相信它生成的版本。

你要手动删掉废话，只保留：

项目是什么
技术栈是什么
常用命令是什么
最重要的代码约定
完成任务前必须做什么
哪些事不能做
目标是：

控制在 200 行以内

第 2 步：精简 CLAUDE.md

问自己一个问题：

如果删掉这一行，Claude 会更容易犯错吗？

如果答案是否定的，就删。

不要写这种废话：

请写高质量代码
请保持代码整洁
请遵循最佳实践
请认真思考

这些太空了。

要写具体规则：

Use pnpm, not npm.
Run pnpm typecheck before saying TypeScript changes are complete.
Do not introduce new dependencies without explaining why.
Check neighboring files before creating a new pattern.

规则越具体，越容易执行。

第 3 步：创建 4 个最常用 Skills

先创建这四个：

.claude/skills/pr/SKILL.md
.claude/skills/diff-review/SKILL.md
.claude/skills/test/SKILL.md
.claude/skills/handoff/SKILL.md

分别负责：

/pr：准备合并前检查
/diff-review：审查当前本地 diff
/test：跑相关检查
/handoff：保存上下文交接
不要一开始做十几个 Skill。

先把最高频的流程固化。

第 4 步：创建 reviewer 子代理

创建：

.claude/agents/reviewer.md

记住核心原则：

reviewer 只审查，不改代码。
reviewer 只找正确性问题，不挑风格毛病。
reviewer 必须对照原始任务和当前 diff。

这能显著减少“自己写、自己夸、自己放行”的问题。

第 5 步：加最小安全配置

先在 .claude/settings.json 里禁止三类事：

读取 secrets
直接 push main
执行高风险删除或发布命令
示例：

{
“permissions”: {
“deny”: [
“Read(/.env)”,
“Read(/.env.)”,
“Read(**/.pem)”,
“Read(**/*.key)”,
“Bash(rm -rf *)”,
“Bash(git push origin main)”
],
“ask”: [
“Bash(git push *)”,
“Bash(npm publish *)”,
“Bash(pnpm publish *)”
],
“allow”: [
“Bash(git status)”,
“Bash(git diff *)”,
“Bash(pnpm lint)”,
“Bash(pnpm typecheck)”,
“Bash(pnpm test *)”
]
}
}

先保守一点。

等你熟悉后，再逐步放开常用安全命令。

第 6 步：跑一次真实任务

不要用 demo 测试。

直接找一个真实小任务：

修复一个小 bug
补一个测试
改一个页面文案
重构一个小函数

流程这样走：

让 Claude 先读相关文件，不要立刻改。
让 Claude 写 plan。
确认 plan。
让 Claude 实现。
运行 /test。
运行 @reviewer 审查 diff。
运行 /pr 生成 PR 描述。

你会马上感受到差别。

之前是：

你一直提醒 Claude 不要跑偏。

现在是：

系统本身在约束 Claude 不要跑偏。

十五、几个内置命令也要知道

除了你自己做的 Skills，Claude Code 还有一些内置命令很有用。

建议记住这些：

/init
初始化 CLAUDE.md

/permissions
查看和管理权限规则

/hooks
查看或配置 hooks

/agents
管理 subagents

/context
查看当前上下文占用

/compact
压缩当前上下文

/clear
开启新会话

/code-review
审查当前 diff

/security-review
做安全审查

/rewind
回到之前的检查点

/reload-skills
重新加载 Skills / commands

你不需要一开始全都用。

但至少要知道：

/init
/permissions
/agents
/context
/clear
/reload-skills

这几个会经常用到。

十六、最常见的 6 个坑

坑 1：CLAUDE.md 写太长

很多人觉得越详细越好。

错。

CLAUDE.md 不是说明书。

它是“每次都要加载的行为准则”。

越长，越容易稀释重点。

建议：

100 行以内很好
200 行以内可接受
超过 300 行就该拆
超过 500 行基本是在制造噪音

坑 2：把硬规则写成软提示

比如：

不要读取 .env
不要 push main
不要运行 rm -rf

只写在 CLAUDE.md 里是不够的。

这些应该放到：

.claude/settings.json

用 permissions 做第一道安全边界。

自然语言规则适合指导行为。

安全边界必须用配置兜底。

坑 3：让 Claude 一边写一边审

同一个上下文里，Claude 很容易为自己的实现找理由。

所以要拆：

main Claude：负责实现
reviewer：负责审查
permissions：负责权限边界
hooks：负责流程辅助
tests：负责最终验证
不要让一个角色包办所有判断。

坑 4：一上来就让它改代码

更好的开场不是：

帮我修这个 bug

而是：

先阅读相关文件，解释问题可能在哪里，不要修改代码。
然后给我一个最小修改计划。

先探索。
再计划。
再执行。

这比直接开改稳很多。

坑 5：上下文快爆了还继续聊

长任务一定要学会中途交接。

当你发现 Claude 开始重复、跑偏、忘记前文、答非所问，就该停了。

不要继续硬撑。

运行：

/handoff

然后：

/clear

新会话读 handoff 文件继续。

这一步会救你很多次。

坑 6：没有让 Claude 跑真实检查

“看起来没问题”不等于完成。
“我已经修改好了”不等于完成。
“逻辑应该是对的”不等于完成。

你要让它明确说：

跑了什么命令
哪些通过了
哪些没跑
为什么没跑
还剩什么风险
所以 CLAUDE.md 里一定要写：

Before saying a task is done, report what checks were run and their results.

十七、最终推荐配置：普通开发者够用版

如果你只想抄一套最小可用配置，就用这个。

必备文件

CLAUDE.md
.gitignore
.claude/settings.json
.claude/skills/pr/SKILL.md
.claude/skills/diff-review/SKILL.md
.claude/skills/test/SKILL.md
.claude/skills/handoff/SKILL.md
.claude/agents/reviewer.md
.claude/rules/testing.md
.claude/rules/security.md

本地忽略文件

CLAUDE.local.md
.claude/settings.local.json
.claude/session-notes/

必备规则

先读代码，再写计划。
优先最小改动。
匹配现有模式。
不引入无必要依赖。
不修改无关文件。
不读取 secrets。
不直接 push main。
完成前必须说明检查结果。
长任务必须 handoff 后 clear。
重要改动必须 reviewer 审查。

日常工作流

普通小改动：

让 Claude 读文件
→ 写 plan
→ 实现
→ /test
→ 总结

重要改动：

读文件
→ 写 plan
→ 实现
→ /test
→ @reviewer
→ /diff-review
→ /pr

长任务：

读文件
→ 分阶段计划
→ 每阶段检查
→ /handoff
→ /clear
→ 继续

结尾

Claude Code 真正厉害的地方，不是它能不能听懂一句 prompt。

而是你能不能把它放进一套稳定的工程系统里。

新手问：

我该怎么写提示词，才能让 Claude 一次做对？

高手问：

我该怎么配置项目，让 Claude 每次都不容易做错？

这就是差别。

提示词解决的是一次对话。

配置解决的是长期协作。

如果你只是偶尔让 Claude Code 改一小段代码，随便聊也能用。

但如果你想让它真的接手项目里的重复工作：

修 bug。
写测试。
做 PR。
审代码。
整理上下文。
长期协作。

那就别再裸奔了。

先搭结构，再写任务。

Claude Code 的上限，不只取决于模型有多强。

也取决于你给它的工作环境有多清楚。

来源：@Vincent_AINotes · 原文链接

别再裸奔用 Claude Code 了：高手都在先做这套配置

一、先建立正确认知：Claude Code 不是“更聪明的聊天框”

二、先建这套目录结构

三、先写一个不超过 200 行的 CLAUDE.md

CLAUDE.md

Project

Tech Stack

Core Rules

Commands

Workflow

Git Rules

Context Management

四、把细规则拆到 .claude/rules/

Frontend Rules

Testing Rules

Security Rules

五、把重复操作做成 Skills

name: prdescription: Prepare a clean PR from the current branchdisable-model-invocation: trueallowed-tools: - Read - Grep - Glob - Bash(git status) - Bash(git diff) - Bash(git diff *) - Bash(pnpm lint) - Bash(pnpm typecheck) - Bash(pnpm test) - Bash(pnpm test *)model: sonnet

六、做一个 /diff-review：只审查，不改代码

name: diff-reviewdescription: Review current local diff without editing filesdisable-model-invocation: trueallowed-tools: - Read - Grep - Glob - Bash(git status) - Bash(git diff) - Bash(git diff *) - Bash(git diff –name-only)disallowed-tools: - Edit - Write - MultiEditmodel: sonnet

七、做一个 /test：专门跑检查

name: testdescription: Run relevant checks for the current changedisable-model-invocation: trueallowed-tools: - Read - Grep - Glob - Bash(git status) - Bash(git diff) - Bash(git diff –name-only) - Bash(pnpm lint) - Bash(pnpm typecheck) - Bash(pnpm test) - Bash(pnpm test *)model: sonnet

八、做一个 /handoff：上下文快满时保存交接

name: handoffdescription: Save current progress before clearing contextdisable-model-invocation: trueallowed-tools: - Read - Grep - Glob - Bash(git status) - Bash(git diff) - Bash(git diff –name-only) - Writemodel: sonnet

Handoff: Auth Refactor

Original Request

Current Status

Files Changed

Commands Run

Test Results

Decisions Made

Open Questions

Risks

Next Step

九、配置 reviewer 子代理：让“写代码的人”和“审代码的人”分开

name: reviewerdescription: Reviews a diff against the plan. Finds correctness gaps. Never edits files.tools: Read, Grep, Globmodel: sonnet

Verdict

Blocking issues

Missing tests

Notes

十、用 settings 和 permissions 做安全边界

十一、hooks 只做辅助，不要当安全系统

十二、加一个 .gitignore，别把本地隐私提交上去

十三、上下文快满时，不要硬撑

Context Management

十四、给中文用户的一套 30 分钟配置流程

十五、几个内置命令也要知道

十六、最常见的 6 个坑

十七、最终推荐配置：普通开发者够用版

结尾

name: pr
description: Prepare a clean PR from the current branch
disable-model-invocation: true
allowed-tools:
- Read
- Grep
- Glob
- Bash(git status)
- Bash(git diff)
- Bash(git diff )
- Bash(pnpm lint)
- Bash(pnpm typecheck)
- Bash(pnpm test)
- Bash(pnpm test )
model: sonnet

name: diff-review
description: Review current local diff without editing files
disable-model-invocation: true
allowed-tools:
- Read
- Grep
- Glob
- Bash(git status)
- Bash(git diff)
- Bash(git diff *)
- Bash(git diff –name-only)
disallowed-tools:
- Edit
- Write
- MultiEdit
model: sonnet

name: test
description: Run relevant checks for the current change
disable-model-invocation: true
allowed-tools:
- Read
- Grep
- Glob
- Bash(git status)
- Bash(git diff)
- Bash(git diff –name-only)
- Bash(pnpm lint)
- Bash(pnpm typecheck)
- Bash(pnpm test)
- Bash(pnpm test *)
model: sonnet

name: handoff
description: Save current progress before clearing context
disable-model-invocation: true
allowed-tools:
- Read
- Grep
- Glob
- Bash(git status)
- Bash(git diff)
- Bash(git diff –name-only)
- Write
model: sonnet

name: reviewer
description: Reviews a diff against the plan. Finds correctness gaps. Never edits files.
tools: Read, Grep, Glob
model: sonnet