Claude Code 项目结构怎么搭才不乱：1 个 CLAUDE.md + 1 个 settings.json 起步，其他文件夹按需再加，11 月 2 日实测版

最好的 Claude Code 项目结构其实很小：根目录放一个 CLAUDE.md，再加一个 .claude/settings.json 管权限，剩下的 rules、skills、subagents 文件夹都等真正有需要时再加。共享的文件提交进 git，个人的文件不要进版本库。这篇是 AI Parabellum 在 11 月 2 日用 Claude Code v2.1.316 在 macOS 上实测的指南，对照 Anthropic 官方文档一个个验证过。

先记住一张分工表：CLAUDE.md 是每个会话都加载的指令，写构建测试命令和新人猜不到的规则，控制在 200 行以内；CLAUDE.local.md 放你自己的私人备注，记得加进 .gitignore；settings.json 里放权限、钩子和环境变量，共享的提交、个人的用 settings.local.json；.claude/rules/*.md 可以按路径限定生效范围；skills/<名字>/SKILL.md 是用 /名字 调用的可复用提示词；.claude/agents/*.md 定义子代理；.mcp.json 是团队共享的 MCP 服务器。最关键的一条分界线：CLAUDE.md 里的只是一句请求，模型大概率会照做但不保证；而 settings.json 里的 deny 规则和钩子是 Claude Code 强制执行的，绝不能破的规矩一定要放这边。

搭好之后用 /memory 验证：它会列出当前加载的全部指令文件，确认 CLAUDE.md、导入的 README 和本地文件都在；没有文件时在 Claude Code 里跑 /init 可以生成一份 starter，再慢慢删；/doctor 还会建议你删掉代码里已经能看出来的废话。常见坑有四个：CLAUDE.md 写成大杂烩、把 CLAUDE.local.md 或 settings.local.json 提交了、第一天就把官方示例树全抄过来、以及还在等 /agents 向导——v2.1.316 里它已经没了，子代理直接写 .claude/agents/ 下的文件。想先抄一份现成的模板，可以看站内这篇 CLAUDE.md 模板照着抄；还在纠结 AGENTS.md 和 CLAUDE.md 选哪个，先看 AGENTS.md 和 CLAUDE.md 只能二选一？实测对比。官方文档见 原文教程。

来源：AI Parabellum，原文：https://aiparabellum.com/claude-code-project-structure-best-practices/