一句话
这页分析的是 awesome-claude-code 仓库里 22 份真实项目的 CLAUDE.md，看它们自然收敛出了哪些共同结构。
为什么做这份研究
自己第一次写 CLAUDE.md 时，最难的通常不是“写一句定义”，而是不知道该怎么组织结构。
看 22 份真实样本的价值在于：它比单一样板更可信，因为这些结构不是某个人拍脑袋定的，而是不同作者在不同项目里慢慢收敛出来的。
研究方法
本条目的做法是：
- 扫 22 份样本
- 观察它们的 section 组织方式
- 找出高频共同段落
- 再把这些段落归纳成可直接抄的骨架
需要保留的口径说明也在原页里：这页研究的是 22 份真实样本；另一些条目里出现的“23 份”是更粗的估算说法。
22 个样本名单
来源目录：raw/2026-04-18/claude-code-best-practices/community/awesome-claude-code/resources/claude.md-files/
样本包括：
AI-IntelliJ-Plugin / AVS-Vibe-Developer-Guide / AWS-MCP-Server / Basic-Memory / Comm / Course-Builder / Cursor-Tools / DroidconKotlin / EDSL / Giselle / Guitar / JSBeeb / Lamoom-Python / LangGraphJS / Network-Chronicles / Note-Companion / Pareto-Mac / Perplexity-MCP / SG-Cars-Trends-Backend / SPy / TPL / claude-code-mcp-enhanced
领域分布覆盖：
- 开发工具 / IDE
- MCP 服务器
- 知识 / 笔记
- AI / LLM 框架
- 数据 / 业务
- 游戏 / 模拟
- 音乐 / 艺术
22 份样本里共同出现的结构
原页里出现频率最高的 7 个部分如下：
- 项目一句话是什么（约 22/22）
- 常用命令 / 脚本（约 22/22）
- 代码约定 / style（约 18/22）
- 目录结构导览（约 16/22）
- “不要做”清单（约 14/22）
- 架构 / 设计决策背景（约 12/22）
- 已知的坑 / 踩过的雷（约 8/22）
原页给过的两个样本说明很有代表性：
Basic-Memory：“Basic Memory is a local-first knowledge management system built on the Model Context Protocol (MCP)…”
Perplexity-MCP：“Perplexity MCP is a Model Context Protocol server that connects…”
这说明“项目一句话是什么”几乎是全员都有的开头，因为 Claude 读 CLAUDE.md 时默认没有背景。
必有 / 常有 / 可选
按这 22 份样本的频率，大致可以分成三层：
- 必有：项目一句话、常用命令
- 常有：代码约定、目录结构、“不要做”清单
- 可选：架构 / 设计决策背景、已知坑 / 踩过的雷、Permissions 预授权、When to ask me、参考实现、Meta 维护说明
如果你只是起第一版，抄到“必有 + 常有”通常就已经够用。
可直接抄的骨架
原页合成出来的骨架如下：
# [项目名] Project Guide
## Project Overview
[一句话说项目是什么 + 核心机制]
## CODEBASE DEVELOPMENT
### Build and Test Commands
- Install: ...
- Run tests: ...
- Lint: ...
- Format: ...
### Code Style
- Naming: ...
- File organization: ...
- 不要做：...
### Architecture / Design Decisions
[为什么这样不那样]
### Directory Structure
[tree or table]
### Known Pitfalls / Errata
- [踩过的坑 1]
- [踩过的坑 2]场景上，这个骨架的用途很直接：新项目照着抄，15 分钟就能写出第一版 CLAUDE.md。
常见误解 / 反例
- 误解一：所有
CLAUDE.md都一个样。不是，差异很大，只是骨架有共性。 - 误解二：越长越专业。不是，质量和长度不是一回事。
- 反例：把 22 份样本里出现过的 section 全都塞进自己的文件，
CLAUDE.md很快会膨胀成 5000 字说明书，启动负担和维护成本一起上来。
陈彬视角
这是我见过最真实的 CLAUDE.md 研究素材——22 个不同领域不同作者的独立决策收敛出的共同结构，比任何”最佳实践模板”都可信。
对好朋友的建议：
起手阶段：前 4 段就够——项目一句话 + 常用命令 + 代码约定 + 不要做。
演化阶段：开始补架构决策段和已知坑段。
成熟阶段：再考虑加 “When to ask me” 和 Meta 维护说明。
一个提醒：别抄别人的 CLAUDE.md 当模板。抄结构没问题，抄具体内容没意义。
与其他术语的关系
[[CLAUDE.md]]：主条目讲术语本身，这页讲真实样本的实证归纳。[[MD-based System]]：CLAUDE.md是 MD-based 的说明书层，这页提供了它的现实写法证据。[[Harness]]：这些样本共同展示了 harness 的说明书层通常怎么写。[[04-系统/03-案例/Boris 怎么用 Claude Code]]：这里的“已知坑写成规则”与 Boris 的做法相呼应。[[04-系统/02-机制/MD-based System 陈彬使用论]]：可继续看更强的 markdown-first 主张。
延伸阅读 / 官方链接
🎬 3 个场景（读者最可能用到的情境）
场景 1 · 新项目抄骨架 15 分钟出第一版
创业团队开新仓库，谁都不知道 CLAUDE.md 怎么写。照这页的 “必有 + 常有”（项目一句话、常用命令、代码约定、目录结构、不要做清单）抄 4-5 段，15 分钟就能交付可用的第一版。
场景 2 · 团队对齐样板
一个公司有 8 个项目，每个 CLAUDE.md 写法差异大，换人协作成本高。把本页的 5 段骨架定成团队内部样板，每个项目至少对齐这 5 段，其他自由发挥。
场景 3 · 从 README 迁移到 CLAUDE.md
老项目只有一份 README（面向人类），没有 CLAUDE.md（面向 AI）。按本页对照：README 里”这是什么”→ 项目一句话、“怎么跑”→ 常用命令、“怎么贡献”→ 代码约定。几段对应迁过去就是第一版 CLAUDE.md。
⚖️ 和最像的邻居比
| 术语 | 本质区别 | 适用边界 |
|---|---|---|
| 本页（22 份共同结构） | 实证归纳的 5 段骨架 | 起草第一版时的参考模板 |
| README | 面向人类贡献者的文档 | 开源社交入口、不是 AI 优先 |
| CLAUDE.md（术语本体） | 面向 AI 的项目说明书 | 长期规则、每次 session 加载 |
| Cursor .cursorrules | Cursor 的对标机制 | Cursor 用户的等价物 |
🚫 反例（不该这么用）
反例 1 · 模板化成固定 5 段不结合项目
强行把每个项目的 CLAUDE.md 都凑成标准 5 段，即使某段在你项目里没实际内容。结果是”常用命令”段写了 3 条伪命令，代码约定写了”遵循最佳实践”这种空话。正确做法：骨架是提醒你”别漏”，但每段必须由项目实际内容驱动，没有就省掉。
反例 2 · 把 22 份样本的 section 全堆进自己的文件
“既然这些 section 都出现过，我全要”。5000 字膨胀版 CLAUDE.md，启动负担和维护成本一起上。正确做法：起手只写”必有 + 常有”7 段以内，等踩坑和迭代后再按需补”可选”段。
❓ 常见误解
- 误解 1：“22 份是完整答案” → 实际：这是 awesome-claude-code 一个社区仓库的样本快照，代表”常见共识”，不是”最优解”，更不是权威模板。
- 误解 2：“抄别人的
CLAUDE.md当模板” → 实际：抄结构没问题，抄具体内容（命令/约定/踩坑）没意义——那是别人项目的细节。 - 误解 3：“共同结构 = 最佳实践” → 实际：共同只说明”大家都写了”，不代表”这是最有价值的段”；有些项目的”踩过的雷”段只有 8/22，但对长期维护可能比”目录结构”更关键。
🧬 历史坐标（最早谁提 · 本质 · 分型 · git）
最早谁提
本页的样本来源是 hesreallyhim/awesome-claude-code——2024 年在 Claude Code 发布后出现的社区汇编仓库，收集 CLAUDE.md、slash command、agent 编排等资源。本页的”22 份共同结构”是对该仓库 resources/claude.md-files/ 目录的一次归纳性梳理。
本质（一句话 · 20 字内）
23 份样本收敛出的 5 段共同骨架。
分型 / 演化（2-4 行主线）
- 初代：单项目自写 CLAUDE.md（风格各异）
- 2024 awesome-claude-code 出现 → 社区开始横向参照
- 2025-2026 共同结构收敛：项目一句话 + 常用命令 + 代码约定 + 目录导览 + 不要做清单
- 分叉：简洁派（前 4 段）vs 手册派（再加架构决策 / 已知坑 / When to ask me）
代表 git / 文档
- awesome-claude-code · hesreallyhim · 本页样本源（含 22 份 CLAUDE.md）
- Claude Code 最佳实践官方页 · Anthropic · 官方侧的 CLAUDE.md 建议
- LLM Wiki gist · Karpathy 2026-04 · 把 CLAUDE.md 范式提到”LLM 知识所有权”高度