Vince 发布了一份 Claude Code 工程化指南，核心命题：大多数用户知道 .claude/ 文件夹存在，但很少有人认真思考它的组织方式。
标准目录结构
your-project/
├── CLAUDE.md # 主项目指令
├── CLAUDE.local.md # 个人覆盖（不提交）
└── .claude/
├── settings.json # 控制层
├── settings.local.json # 本地覆盖
├── rules/ # 模块化指令
├── hooks/ # 自动化脚本
├── commands/ # 可复用提示词工作流
├── skills/ # 打包能力
└── agents/ # 专用子代理
两层分离：引导 vs 控制
CLAUDE.md：解释项目如何工作（栈、架构、关键命令、全局约定）
.claude/settings.json：控制 Claude 在项目中的操作方式（权限、hooks、项目级行为）
CLAUDE.local.md / .claude/settings.local.json：个人覆盖，不进 git 版本控制
一个负责引导，一个负责控制。
CLAUDE.md：全局指导
每次会话都需要的内容：
- 主要技术栈
- 高层架构
- 最重要的开发命令
- 广泛适用的代码约定
- 项目级警告或约束
rules/：专项指导
按领域或工作流拆分的规则：
.claude/
└── rules/
├── frontend.md
├── backend-api.md
├── testing.md
└── data-pipelines.md
什么时候拆分：
- CLAUDE.md 开始显得拥挤
- 不同仓库区域需要不同指导
- 不同人有不同标准
- 团队经常更新约定
- 想按路径限定指令作用域
hooks/：自动运行的脚本
不放在说明文档中，而是实际执行的自动化：
- 拦截危险操作（如 block-dangerous-commands.sh）
- 清理或验证输出（如 format-edits.sh）
- 强制执行工作流要求（如 run-tests-before-stop.sh）
commands/：可复用提示词工作流
不是自动运行的，而是按需调用的：
- review-pr.md
- write-tests.md
- summarize-changes.md
命名原则：write-tests.md 好过 test.md。动词开头，描述具体动作。
skills/：打包的完整能力
工作流有多个步骤、需要配套文档时使用：
.claude/
└── skills/
├── release-prep/
│ ├── SKILL.md
│ └── release-template.md
└── docs-audit/
├── SKILL.md
└── style-guide.md
commands/ vs skills/ 的区别：
- commands/ = 轻量可复用任务（一个文件就够了）
- skills/ = 更丰富的打包工作流（多个步骤 + 配套文档）
agents/：专用子代理
需要更聚焦的角色时使用：
.claude/
└── agents/
├── code-reviewer.md
├── security-auditor.md
└── docs-writer.md
每个 skill 解决一个重复出现的完整工作流，每个 agent 拥有一个专门角色。如果两个文件高度重叠，应该合并或简化。
项目级 vs 用户级
# 项目级（团队共享）
your-project/
├── CLAUDE.md
└── .claude/
├── settings.json
├── rules/
└── hooks/
# 用户级（个人偏好）
~/.claude/
├── CLAUDE.md
├── settings.json
├── skills/
├── agents/
└── projects/
判断标准：如果配置帮助整个团队更一致地工作 → 放项目级。如果主要反映一个人的工作流 → 放本地或全局设置。
本地覆盖文件（CLAUDE.local.md 和 .claude/settings.local.json）是很好的中间层，让人可以在不污染版本控制的情况下调整行为。
渐进式建设路线
不要一开始就填满所有文件夹。按需增加：
- 起步：CLAUDE.md + .claude/settings.json
- 指令膨胀：加 rules/
- 需要自动化：加 hooks/
- 提示词重复：加 commands/
- 工作流变深：加 skills/
- 需要专精角色：加 agents/
核心原则
最高效的 .claude/ 文件夹不是功能最丰富的，而是每个部分都有清晰用途的。好的结构应该能立即回答：
- 项目级指令在哪里？
- 个人覆盖在哪里？
- 自动化 guardrail 在哪里？
- 可复用工作流在哪里？
- 专用子代理在哪里？
核心 takeaway：Claude Code 的工程化不是一次性配置，而是随着项目成长渐进式建设的分层架构。rules/ 防止 CLAUDE.md 膨胀，hooks/ 把 guardrail 自动化，skills/ 把重复工作流打包——三层叠加后，Claude 从"需要不断纠正的助手"变成"了解项目上下文的协作者"。