为什么现在值得写
上周三晚上十一点，我正对着一个支付网关的遗留代码做重构。咖啡已经续到第三杯，Claude Code 的光标在终端里一闪一闪。我敲下'帮我把这个回调逻辑抽离成独立模块'，心里盘算着大概二十分钟能收工。
这段代码，怕是要被接管了
结果 Claude 回了我一句：'这个项目用的是 CommonJS 还是 ES Modules？测试框架是 Jest 还是 Mocha？错误处理是抛异常还是返回 error code？'
异常直接甩脸上了
那一瞬间，我血压直接拉满。这已经是这个月第十次了，每次会话它都像刚出厂的空白人设，我得把项目的规矩、坑点、架构决策像教实习生一样重新讲一遍。明明上一次会话才说过，它怎么就记不住？
第十次回答同一个问题
直到我在 Hacker News 上刷到那篇《Anatomy of the .claude/ folder》，才意识到自己一直在犯一个低级错误：我忽略了项目根目录下那个不起眼的 .claude 文件夹。
这玩意儿不是缓存，不是日志，而是 Claude Code 的'长期记忆区'和'操作系统'。
现在值得写，是因为很多人跟我一样，把 Claude 当成了随叫随到的临时工，用完即弃。但实际上，只要配置好这个文件夹，它就能变成懂规矩、有记忆、能自动跑流程的合伙人。
这不是什么未来学，而是现在就能落地的生产力差距。
两套目录，两套人格
项目级 vs 全局级：谁该进 Git？
很多人一看到 .claude 就以为只有一个地方，其实 Claude Code 维护了两套平行的目录结构。一套在项目根目录，叫项目级配置；一套在你的用户主目录 ~/.claude/，叫全局级配置。
这两套目录就像公司的'员工手册'和你的'私人笔记'。
项目级配置，包括 CLAUDE.md、settings.json、rules/、commands/ 这些，是团队共识。比如项目用什么构建命令、有哪些架构红线、哪些坑不能踩。
这些东西应该提交到 Git 仓库，让团队里每个人——包括每个人手里的 Claude——都遵守同一套规矩。
全局级配置，比如 ~/.claude/CLAUDE.md 和 ~/.claude/settings.json，是你个人的偏好。
比如你喜欢用简洁的 commit message，或者你习惯让 Claude 在执行某些命令前先问你一声。这些不该进 Git，否则就是在把你的个人习惯强加给全组人。
最关键的是 CLAUDE.local.md 和 settings.local.json 这两个带 local 后缀的文件。它们是给你自己用的'覆盖层'。
比如项目规定测试必须跑全量，但你本地调试时想只跑单文件，就可以在 settings.local.json 里覆盖掉那个规则。
记得把它们加进 .gitignore，别把个人覆盖推到远程仓库。
CLAUDE.md：给 AI 看的 README
写什么：构建命令、架构决策、隐形坑
CLAUDE.md 是整个 .claude 体系里最重要的文件，没有之一。Claude Code 在每次会话开始时，会把它加载到系统提示里，相当于给 AI 发了一份'入职指南'。
写什么？写那些 AI 不看代码就猜不到、看了代码也容易猜错的东西。
第一，构建、测试、lint 命令。
别让 AI 每次都猜你是用 npm run dev 还是 pnpm start，直接写死：'启动开发服务器用 pnpm dev，测试用 pnpm test:unit，lint 用 pnpm lint:fix'。
第二，关键架构决策。
比如'所有 API 响应必须走统一的 ResponseWrapper'，或者'数据库事务只在 Service 层开启，Controller 层禁止直接操作事务'。
这些是团队的'宪法'，不写下来，AI 就会按它训练数据里的'大众写法'来，然后被你的架构师在 Code Review 里打回。
第三，非显而易见的坑。比如'支付模块的浮点数计算必须用 decimal.js，禁止直接用 JavaScript 的 Number'，或者'用户模块的密码字段在日志里必须脱敏'。
这些坑，AI 不踩一遍是不知道疼的，但你可以在它踩之前就立块牌子。
不写什么：别把它当垃圾桶
很多人一听说这文件重要，就把所有能想到的都往里塞。项目背景、技术选型理由、甚至还有竞品分析。这是把 CLAUDE.md 当成产品文档了。
记住，CLAUDE.md 是给 AI 看的'指令集'，不是给人看的'说明书'。
别写属于 linter 或 formatter 配置的内容。比如'缩进用 2 空格'、'字符串用单引号'，这些写在 .eslintrc 和 .prettierrc 里就好，AI 会自己读。
别写可以链接的完整文档。比如'Redis 的分布式锁实现原理'，给个文档链接就行，AI 会自己去看。把原理塞进 CLAUDE.md，只会撑爆上下文窗口。
别写解释理论的长段落。AI 不需要你教它什么是 RESTful，它需要的是'本项目所有接口必须返回 200，错误信息放 body 里的 code 字段'这种具体指令。
⚠️ 踩坑提醒：200 行红线
这里有个硬指标：CLAUDE.md 最好控制在 200 行以内。
这不是我拍脑袋定的，而是 Claude Code 的实际表现决定的。文件太长，会吃掉大量上下文 token，导致留给实际代码分析的窗口变小。
更麻烦的是，指令一多，Claude 的'指令遵守度'反而会下降——它开始挑着听，或者干脆忽略后面的内容。
就像你给实习生讲了半小时注意事项，他最后记住的可能只有'中午食堂有红烧肉'。
如果你的规矩确实多，200 行装不下，那就拆。把通用的规矩留在 CLAUDE.md，把特定模块的规矩拆到 rules/ 目录下。
从工具人到合伙人：自动化配置拆解
rules/：按路径加载的'局部记忆'
rules/ 目录是用来放'模块化指令'的。每个文件专注一个领域，而且可以指定'作用域'。
比如，你有个 security-rules.md，内容是关于安全编码的规范。你可以在文件头加一段配置：
---
paths:
- "src/handlers/**/*.ts"
- "src/middleware/**/*.ts"
---
这样，只有当 Claude 在处理 src/handlers/ 或 src/middleware/ 下的文件时，才会加载这套安全规则。其他时候，这些规则处于'休眠'状态，不占上下文。
这就像给 AI 配了一副'变色眼镜'，走到不同的区域，自动切换不同的滤镜。
commands/：你的专属斜杠指令
commands/ 目录里放的是自定义的斜杠命令。
比如你建一个 review.md，里面写好代码审查的提示词，之后在会话里输入 /project:review，Claude 就会自动执行这套审查流程。
更有意思的是，你可以在命令里嵌入 shell 命令的输出。比如在 review.md 里写：
请审查以下文件的变更：
!`git diff --name-only main...HEAD`
那个 ! 开头的语法，会让 Claude 先在后台跑一遍 git diff，把结果塞进提示词里，再开始审查。你不用自己复制粘贴文件列表，它自己会去查。
skills/：自动触发的隐形工作流
skills/ 和 commands/ 的区别，就像'主动服务'和'被动响应'。
命令是你不叫它不动。技能是它看着对话内容，觉得'这事儿我熟'，就自己跳出来帮忙。
每个技能是一个目录，里面至少有一个 SKILL.md，写清楚'什么情况下触发'以及'触发后干什么'。
比如你定义一个 security-review 技能，当 Claude 检测到你正在写认证相关的代码时，它会自动加载安全审查的流程，在后台跑一遍，然后把建议贴出来。
这才是真正的'懂你'——不用你开口，它就知道什么时候该干什么。
agents/：受限的专项特工
有些任务太复杂，不适合让主 Claude 实例干所有事。这时候可以定义 agents/，也就是'子代理'。
比如定义一个 code-reviewer.md，在文件头写明：
---
description: 专门做代码审查的子代理
model: claude-sonnet-4-20250514
tools:
- Read
- Grep
- Glob
---
这个子代理只能用 Read、Grep、Glob 三个工具，不能写文件，不能跑 Bash 命令。它的职责就是'只看不改'，做纯粹的审查工作。
这种'最小权限原则'的隔离，不仅安全，还能让每个代理更专注。术业有专攻，AI 也一样。
安全带与红按钮：权限控制
allow、deny 与中间地带
settings.json 是 Claude Code 的'权限控制中心'。里面有三个关键列表：allow、deny 和默认的'中间地带'。
allow 列表里的操作，Claude 可以不经确认直接执行。比如 Bash(npm run *)、Bash(git *)、Read、Write 这些高频且安全的操作。
deny 列表里的操作，Claude 完全禁止执行。比如 Bash(rm -rf *)、Bash(curl *)，还有对 .env 文件的 Read 操作。这些是红线，碰都别让它碰。
中间地带，就是既不在 allow 也不在 deny 里的操作。Claude 会先停下来，问你'我要执行 XXX，可以吗？'。你确认后，它才会继续。
⚠️ 踩坑提醒：别给 AI 开 rm -rf 权限
我知道，每次确认都很烦，尤其是你正沉浸在心流里的时候。但千万别为了省事，把 rm -rf 加进 allow 列表。
AI 不像人，它没有'直觉'。它可能为了清理一个临时目录，顺手把整个项目删了——因为它判断那个目录'看起来像临时的'。这种事，Hacker News 上已经有人踩过坑了。
权限配置是给 AI 系的安全带，也是给自己买的保险。麻烦一点，总比半夜两点在服务器机房里哭要好。
写在最后
.claude 文件夹，本质上是我们在做'上下文工程'。提示词工程教 AI 怎么说话，上下文工程教 AI 怎么记住规矩、怎么自动干活、怎么在边界内操作。
很多人抱怨 AI 编程助手'不够智能'，其实很多时候，是我们没给它足够的'上下文环境'。就像你招了个名校毕业的实习生，却不给他看文档、不告诉他规矩、不给他配电脑权限，最后怪他干不好活——这不太公平。
把 .claude 配置好，AI 才能从'临时工'变成'合伙人'。这个文件夹，就是你们之间的'合作协议'。
你的 .claude 文件夹里都放了什么？有没有什么独门的配置技巧？欢迎在评论区晒出来，让大家抄抄作业。
参考文献
Anatomy of the .claude/ folder - Hacker News 热门讨论
Claude Code 官方文档 - Configuration 部分
如果你想继续追更，欢迎在公众号 计算机魔术师 找到我。后续的新稿、精选合集和阶段性复盘，会优先在那里做串联。
