一句话

这页分析的是 awesome-claude-code 仓库里 22 份真实项目的 CLAUDE.md,看它们自然收敛出了哪些共同结构。

为什么做这份研究

自己第一次写 CLAUDE.md 时,最难的通常不是“写一句定义”,而是不知道该怎么组织结构。

看 22 份真实样本的价值在于:它比单一样板更可信,因为这些结构不是某个人拍脑袋定的,而是不同作者在不同项目里慢慢收敛出来的。

研究方法

本条目的做法是:

  1. 扫 22 份样本
  2. 观察它们的 section 组织方式
  3. 找出高频共同段落
  4. 再把这些段落归纳成可直接抄的骨架

需要保留的口径说明也在原页里:这页研究的是 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 个部分如下:

  1. 项目一句话是什么(约 22/22)
  2. 常用命令 / 脚本(约 22/22)
  3. 代码约定 / style(约 18/22)
  4. 目录结构导览(约 16/22)
  5. “不要做”清单(约 14/22)
  6. 架构 / 设计决策背景(约 12/22)
  7. 已知的坑 / 踩过的雷(约 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 .cursorrulesCursor 的对标机制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 / 文档