泡沫机械
96.43M · 2026-03-24
很多人开始用 Claude Code 时，第一反应都是优化 prompt。
但如果你已经在真实项目里用过一段时间，大概率会发现一个更棘手的问题：
不是 prompt 不够好，而是 Claude 每次进入项目时都像“重新认识你一次”。
你得反复解释这些东西：
这类信息如果一直靠会话里现讲，最终一定会出问题。上下文会越来越长，重要规则会被淹没，Claude 的行为也会越来越不稳定。
这也是我看完 shanraisshan/claude-code-best-practice 之后最强烈的一个感受：
如果你想把 Claude Code 用稳，最该先写好的不是一段万能 prompt，而是一份清晰、克制、长期有效的 CLAUDE.md。
但只写好 CLAUDE.md 还不够。
真正把 Claude Code 从“聊天工具”升级成“工程系统”，至少还要再补四层：
Commands：把高频任务固定成统一入口Subagents：把不同职责拆成独立角色Skills：把知识做成按需加载的模块.claude/settings.json：把权限、hooks 和行为边界固化到配置层这篇我不只讲 CLAUDE.md，而是顺着这个仓库，把这 5 个模块一起拆开。
CLAUDE.md 到底是什么可以把它理解成一句话：
它不是面向人的 README，也不是一次会话里的临时提示，而是项目级记忆入口。
这个仓库把 CLAUDE.md 放在非常核心的位置，原因很简单：
很多人以为“项目背景讲一次就够了”，但工程实践里真正稳定的方式，往往不是讲一次，而是把该记住的事情写成系统的一部分。
CLAUDE.md 比你想象中更重要因为它解决的是 Claude Code 最常见的三个失控点。
如果没有 CLAUDE.md，每次开新会话都要重新说：
这不仅浪费时间，还会让每次说明的口径都不完全一样。
很多团队会把重要约束写进一长串 prompt，比如：
问题是，这些规则一旦只存在于会话里，就很容易在长上下文里被稀释掉。
这是很多人容易忽略的一点。
Claude 不是“知道越多越好”，而是“越知道什么最重要越好”。
CLAUDE.md 的作用，本质上不是堆更多信息，而是帮 Claude 建立优先级。
CLAUDE.md 应该写什么根据这个仓库的最佳实践，CLAUDE.md 最适合放那些：
的信息。
最典型的内容包括下面几类。
Claude 第一次进项目时，最需要的是地图，而不是细节。
所以你应该先告诉它：
比如：
## Project
This is a monorepo with:
- `apps/web`: frontend app
- `apps/api`: backend service
- `packages/ui`: shared components
- `packages/config`: shared configs
这一段的意义不在于“介绍项目”，而在于让 Claude 后续读文件时能快速建立定位。
这是 CLAUDE.md 里非常实用的一部分。
你最好把下面这些命令明确写进去：
比如：
## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint`
这能直接减少 Claude 在命令选择上的猜测成本。
这部分最有价值。
不是把所有代码规范都搬进来，而是只写那些“如果不遵守，后果会明显变差”的规则。
比如：
如果规则只是“语法习惯”，优先交给 linter 或 formatter。
如果规则直接影响结构和行为，才适合写进 CLAUDE.md。
如果项目里已经有“标准答案”，一定要告诉 Claude 去哪里看。
比如：
这比抽象地说“请遵循现有风格”有效得多。
CLAUDE.md 通常长什么样这个仓库反复强调一件事：CLAUDE.md 一定要克制。
推荐长度大致控制在 150 到 200 行以内。原因不是为了好看，而是因为太长之后，Claude 对它的遵循度会明显下降。
下面这些内容，通常都不适合直接塞进 CLAUDE.md。
这是最典型的误用。
API 文档适合放在独立文档里，被引用；不适合整个内嵌进 CLAUDE.md。
除非某段代码是绝对关键模式，否则不要在这里贴很多实现细节。
因为 CLAUDE.md 最重要的是建立约束和路径，而不是充当知识库全文。
比如：
这些东西变化太快，不适合作为长期记忆。
这一点不用多说，永远不要写进去。
CLAUDE.md 和 README、Rules、Skills 到底怎么分工这是最容易混淆的地方。
我的理解是：
README 面向人CLAUDE.md 面向 Claude 的长期项目记忆Rules 面向路径或主题的局部约束Skills 面向按需加载的知识模块你可以用一个简单判断法：
CLAUDE.md这也是为什么这个仓库一直在强调“渐进式暴露知识”。
不是所有东西都该常驻上下文。
CLAUDE.md 应该怎么放这个仓库对 monorepo 的说明非常有价值，因为它把加载规律讲清楚了。
可以简单记成 3 句话：
CLAUDE.mdCLAUDE.md 按需懒加载这意味着非常适合这样设计：
CLAUDE.md写全局规则，比如：
CLAUDE.md写局部规则，比如：
这种分层的好处是：Claude 在前端目录工作时，不会被后端细节污染；在后端目录工作时，也不会一直带着前端上下文跑。
CLAUDE.md 模板如果你准备开始写第一版，可以直接从下面这个骨架开始。
# Project Overview
This project is a monorepo for X.
## Structure
- `apps/web`: frontend app
- `apps/api`: backend service
- `packages/ui`: shared components
## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`
## Conventions
- All API calls go through `lib/api.ts`
- Reuse components from `packages/ui` before creating new ones
- Follow route patterns in `apps/api/src/routes`
- Put tests next to implementation files
## Key References
- Frontend example: `apps/web/src/components/TodoList.tsx`
- API example: `apps/api/src/routes/todos.ts`
- Shared UI example: `packages/ui/src/Button.tsx`
## Do / Don't
- Do follow existing file patterns before introducing new abstractions
- Do run tests for changed modules
- Don't introduce new state management without checking existing patterns
这份模板的重点不是“完整”，而是“足够稳定、足够明确、足够短”。
CLAUDE.md 时，我建议你遵守 4 个原则如果一条信息过两周就会过期，它大概率不该进 CLAUDE.md。
不要把“可有可无的说明”塞进去。优先保留那些会直接影响判断和执行路径的内容。
“遵循现有风格”这种话帮助有限。
“参考 apps/web/src/components/TodoList.tsx 的模式”才是真正可执行的指令。
当你发现 CLAUDE.md 已经越来越长时，不要继续加。应该开始拆：
CLAUDE.md这才是长期可维护的结构。
CLAUDE.md 还不够，后面四层也得补上到这里你会发现，CLAUDE.md 解决的是“Claude 进入项目后先知道什么”。
但真实工程里还会继续遇到另外四个问题：
这四个问题，分别对应：
CommandsSubagentsSkills.claude/settings.json这也是这个仓库最值得继续往下拆的地方。
Commands 应该怎么设计如果说 CLAUDE.md 解决的是“Claude 先知道什么”，那 Commands 解决的就是：
哪些高频任务，应该从临时 prompt 升级成固定工作流入口。
这是非常常见的低效点。
比如下面这些事，你可能已经让 Claude 做了很多次：
但很多团队的做法还是：
这不仅浪费时间，也会导致执行口径越来越不一致。
Command 到底是什么按这个仓库的设计，Command 不是普通 prompt 别名，而是：
它通常放在 .claude/commands/*.md，用 Markdown 文件定义。
比较关键的字段包括：
namedescriptionmodelargument-hintallowed-toolscontextagenthooks从职责上看，command 最核心的价值不是“自己做完所有事”，而是“把正确的事按正确顺序串起来”。
Command 和 Subagent、Skill 的区别到底是什么这是最容易混淆的地方。
我的建议是直接记成一句话：
Command 负责流程入口Subagent 负责角色执行Skill 负责知识加载也就是说：
只要这个边界没分清，后面所有设计都会开始打架。
我觉得最典型的是下面这三类：
比如：
比如：
比如你不希望每个人都用不同 prompt 去做同一件事，那就应该抽成 command。
/weather-orchestrator 为什么是个好示例这个 command 很适合入门，因为它特别清楚地展示了编排职责。
它做的事情大致是：
Task / Agent 工具调用 weather-agentweather-svg-creator 生成 SVG 和 markdown 输出这里最值得学的不是天气本身，而是它的职责边界：
这正是一个好 command 的样子。
我很建议用一个很简单的标准：
同类 prompt 重复出现 3 次以上，就该考虑抽成 command。
因为这通常说明：
---
description: Review a pull request and summarize risks, regressions, and follow-up actions
model: sonnet
---
1. Ask the user for the PR link or changed files if not provided.
2. Inspect the changed files and identify behavioral risks.
3. Use the appropriate agent if the task needs specialized review.
4. Summarize findings in priority order.
Constraints:
- Focus on bugs, regressions, and missing tests.
- Do not rewrite unrelated code.
- Keep the final summary concise and actionable.
这类 command 最大的价值，不是省几行字，而是把工作流固化成团队资产。
我觉得最常见的是这 4 个：
如果一个 command 只是把原来临时 prompt 原封不动存起来，它的价值其实不大。
command 应该更多负责编排，而不是吞掉所有执行职责。
好的 command 通常很清楚：
这几层一旦混了，后面维护成本会非常高。
Subagents 应该怎么设计很多人一听到 agent，就会本能地多拆几个。
但真实情况通常是：agent 不是越多越好，职责越清晰越好。
常见问题基本就这几种：
这会导致一个很典型的问题：
你以为自己在做模块化，实际上只是在复制一堆职责不清的提示词。
Subagent 到底是什么按这个仓库的思路，Subagent 更像一句话：
它和 command、skill 的区别一定要分清：
Command 是流程入口Subagent 是执行角色Skill 是知识模块也就是说：
这个边界一旦清楚，Claude Code 的结构就会稳定很多。
我建议至少满足下面两个条件再拆：
典型适合拆 agent 的场景包括：
如果一个任务只是偶尔出现，或者没有稳定边界，那大概率还不值得拆 agent。
weather-agent 为什么写得干净它是一个很好的例子，因为它只做一件事：
weather-fetcher它没有做这些事：
这正是好的 subagent 该有的样子：边界小、职责清、输出明确。
这个仓库里的 subagent 配置里，有几个字段特别关键：
namedescriptiontoolsmodelpermissionModemaxTurnsskillsmemoryisolation如果只说最重要的几个，我会优先看这 5 个：
description这不是介绍文案，而是调用条件说明。
它应该告诉 Claude：
tools这是 agent 的能力边界。
经验上非常实用的一条是：
Read、Grep、GlobWrite、EditWebFetch、WebSearch不要因为省事就全部放开。工具越多，漂移空间越大。
permissionMode这个字段决定 agent 执行操作时的安全模式。
常见模式包括：
defaultacceptEditsdontAskbypassPermissionsplan如果你还在起步阶段，优先考虑：
acceptEditsplan直接上 bypassPermissions 风险很高，不建议当默认方案。
skills这里决定 agent 启动时预加载哪些知识。
这个设计很重要，因为它直接决定：
memory这个字段决定记忆范围：
userprojectlocal最实用的理解方式是：
userprojectlocal---
name: api-review-agent
description: Review backend API changes for route patterns, validation, and error handling
tools: Read, Grep, Glob, Edit, Write
model: sonnet
permissionMode: acceptEdits
maxTurns: 12
skills:
- backend-api-rules
memory: project
---
Review API-related changes only.
Focus on:
- route consistency
- validation
- error handling
- existing project patterns
Do not redesign unrelated modules.
Return a concise summary of findings and edits.
这个骨架里最重要的不是字段齐全，而是你能看出它的职责边界。
我觉得最常见的是这 4 个：
流程应该交给 command，执行交给 agent。两者一混，后面会越来越难维护。
“全能 agent” 听起来方便，但长期看最不稳定。
每多一个工具，就多一层不必要的自由度。
如果你自己都不知道这份知识应该存在用户级、项目级还是本地级，那 agent 的行为大概率也会混乱。
Skills 到底适合存什么内容如果说 CLAUDE.md 是长期记忆，Subagents 是角色，那么 Skills 就是按需加载的知识包。
这一层特别容易被写坏。
因为大家太容易把 skill 当成“能存很多内容的地方”。
于是结果往往是：
CLAUDE.md、rules 职责重叠这个仓库里最有价值的一点，是它强调了一个核心原则：
我更愿意把它理解成：
它适合做的事情，不是替代所有记忆，而是补充主上下文里不该常驻的知识。
按这个仓库的思路，比较适合放进 skill 的通常有 4 类：
比如：
不是那种死板到每一步都锁死的流程，而是有明确目标和约束的工作方式。
这类内容特别有价值，因为它正好是 Claude 默认知识里最容易缺的部分。
比如：
只要这些模板不是所有会话都必须带着，就很适合做成 skill。
这个判断更重要。
下面这些东西，通常不该放 skill：
这种内容应该放 CLAUDE.md，而不是 skill。
skill 最应该存的是“Claude 默认不知道，或者在这个项目里需要特殊处理”的东西。
skill 不应该承担临时通知板的职责。
如果它只是死板操作说明，没有知识结构，那往往更像脚本说明，而不是 skill。
weather-fetcher 和 weather-svg-creator这是理解 skill 设计最好的例子之一。
这两个 skill 虽然都属于同一个天气案例，但它们承担的是完全不同的职责：
weather-fetcher它更像领域知识。
它告诉 agent：
它适合作为 agent 预加载 skill。
weather-svg-creator它更像输出生成模块。
它负责：
它更适合作为被单独调用的 skill。
这两个 skill 一拆开，职责就非常清楚了：
user-invocable 和预加载 skill 怎么选这是 skill 设计里最容易忽略的点。
通常满足这些特征：
比如：
通常满足这些特征：
这时候就可以像这个仓库一样，把它设为 user-invocable: false。
---
name: backend-api-rules
description: Backend API review rules and implementation conventions
user-invocable: false
---
# Backend API Rules
Use this skill when reviewing or writing backend API handlers.
## Focus Areas
- route consistency
- request validation
- error handling
- response shape
## Gotchas
- Do not bypass the shared validation layer
- Reuse existing error helpers
- Follow the route patterns in `src/routes`
## Reference Files
- `src/routes/todos.ts`
- `src/lib/validation.ts`
这类模板比“塞一大堆说明”更有用，因为它本身就是围绕职责组织的。
如果只用一句话总结，我会这么说：
Skill 不是知识仓库，而是按需加载的知识模块。
一旦你按这个思路设计，skill 就不会再变成杂物间。
.claude/settings.json 应该怎么配如果前面三层解决的是“Claude 知道什么、谁来做什么”，那么 settings.json 解决的就是：
Claude 能做什么，以及它应该在什么边界里做。
这一层非常关键，因为很多团队真正缺的不是 prompt，而是行为边界。
因为他们只在会话里约束 Claude，却没有把这些约束沉淀成配置。
于是就会出现：
这就是为什么 .claude/settings.json 这么重要。
这个仓库把优先级讲得很清楚，从高到低大致是：
.claude/settings.local.json.claude/settings.json~/.claude/settings.json这套层级对团队特别重要，因为它允许你同时拥有：
最常见的实践就是：
.claude/settings.json.claude/settings.local.jsonpermissions 到底该怎么设计这是 settings.json 的核心。
最常见的三类规则是：
allowaskdeny很实用的一条设计原则是：
allow比如：
ask比如：
rmgitnpmcurl这个仓库就很强调：危险动作要显式收紧，而不是默认放开。
deny比如：
.env这能让安全边界真正落到配置里，而不是落在“希望 Claude 自己别碰”的幻想里。
settings.json 骨架{
"permissions": {
"allow": [
"Read(*)",
"Edit(*)",
"Write(*)",
"Agent(*)",
"mcp__*"
],
"ask": [
"Bash(git *)",
"Bash(rm *)",
"Bash(curl *)",
"Bash(npm *)"
],
"deny": [
"Read(.env)",
"Read(./secrets/**)"
],
"defaultMode": "acceptEdits"
}
}
真正的关键不是字段本身，而是你有没有把“什么能做、什么不能做、什么必须确认”说清楚。
这个仓库把 hooks 也放进了 settings 体系里，这是非常对的做法。
因为 hooks 本质上是生命周期自动化，比如：
SessionStartPreToolUsePostToolUsePreCompact你可以把它理解成：那些不想每次手动提醒 Claude 的动作，就应该考虑交给 hooks。
适合上 hooks 的事情包括：
但也别一开始就把 hooks 铺满。
最稳的策略永远是：先自动化确定性最高的动作。
env 和 auto-compaction 为什么也值得重视这个仓库提到一个很重要的点：上下文预算要前置管理。
其中一个实用配置就是：
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE它控制自动压缩上下文的触发阈值。
这件事很容易被忽略，但真实使用里非常重要。因为很多人不是不会用 Claude，而是总在上下文已经过载之后，才发现结果开始变差。
我认为这个仓库给出的思路非常稳：
放进 .claude/settings.json：
放进 .claude/settings.local.json：
这个分层很重要，因为它能避免“每个人都在自己电脑上养一套不同的 Claude”。
settings.json 的本质是什么如果说 CLAUDE.md 是长期记忆，Subagents 是角色边界，Skills 是知识模块，那 settings.json 的本质就是：
把 Claude 的行为边界从口头约束变成显式配置。
这是工程化里非常关键的一步。
如果把这个仓库真正有价值的内容压缩成 5 层，我会这么总结：
CLAUDE.md解决的是：
Commands解决的是：
Subagents解决的是：
Skills解决的是：
.claude/settings.json解决的是：
如果你现在的 Claude Code 使用状态是：
那最值得补的通常不是“更会问问题”，而是把这 4 层结构慢慢搭起来。
我的建议顺序仍然是：
CLAUDE.mdCommandsSubagentsSkills.claude/settings.json 固化行为边界当这 4 层开始协同之后，Claude Code 才会真正从“一个很好用的对话工具”变成“一个能长期协作的工程系统”。
