这条目是什么
awesome-claude-code 社群仓库收录了 22 份真实项目的 CLAUDE.md（写在 CLAUDE.md 完全解读 里的”23 份”为口径估算，实测是 22 个）——横跨 IDE 插件、MCP 服务器、开发工具、学习教程、游戏模拟器等完全不同领域。
本条目做的事：把这 22 份横向交叉，找出”大家都有的段落”——这比单一样板（比如 CLAUDE.md 完全解读 给的”最小模板”）更有说服力，因为它来自不同领域不同作者的自然收敛。
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：AI-IntelliJ-Plugin, Cursor-Tools, JSBeeb, Pareto-Mac
- MCP 服务器：AWS-MCP-Server, Perplexity-MCP, claude-code-mcp-enhanced
- 知识/笔记：Basic-Memory, Note-Companion, Course-Builder
- AI/LLM 框架：LangGraphJS, Giselle, SPy, TPL, EDSL
- 数据/业务：SG-Cars-Trends-Backend, Lamoom-Python, Comm
- 游戏/模拟：JSBeeb, DroidconKotlin, Network-Chronicles
- 音乐/艺术：Guitar
22 份里共同出现的 7 个段落
按出现频次从高到低：
1. 项目一句话是什么（~22/22 全员有）
几乎每份 CLAUDE.md 第一段都是”这个项目是干什么的”。样本：
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 时没背景，一句话项目定位让它立刻进入状态。
2. 常用命令/脚本（~22/22 全员有）
几乎全员都有”Build / Test / Lint / Format”命令块。
Basic-Memory:
Install: make install or pip install -e ".[dev]" Run tests: uv run pytest -p pytest_mock -v or make test Single test: pytest tests/path/to/test_file.py::test_function_name Lint: make lint or ruff check . --fix Type check: make type-check or uv run pyright Format: make format or uv run ruff format . Run all code checks: make check
为什么重要：Claude 不知道你这个项目用什么工具链——pytest 还是 jest，make 还是 npm。写清命令 = 省掉 Claude 瞎猜。
3. 代码约定 / style（~18/22）
三类最常见：
- 命名（“类用 PascalCase，函数用 snake_case”）
- 文件组织（“tests/ 和 src/ 并列”）
- 禁止（“不要用 X 库 / 不要写 Y 风格”）
4. 目录结构导览（~16/22）
两种形式：
- 树状图 + 每个目录一句话
- 表格：路径 / 作用
5. “不要做”清单（~14/22）
高亮的：这一段往往决定 Claude 做事的下限，比”要做”段还重要。官方 best-practices-page.md 也强调这点。
样本里的”不要做”：
- “Never modify files outside the repository root”
- “Don’t use deprecated API X, use Y instead”
- “Never commit without running tests”
- “Don’t skip hooks with —no-verify”
6. 架构/设计决策背景（~12/22）
解释”这个代码为什么这样写”——让 Claude 改东西时不会破坏原本的设计意图。
样本：
LangGraphJS：“The framework separates graph definition from runtime… Do not mix these concerns.”
7. 已知的坑/踩过的雷（~8/22）
不全员有，但有的都是价值密度最高的段落。本质是 案例_Boris 怎么用 Claude Code 里 “Compounding Engineering”（tip 4）在单个 CLAUDE.md 里的体现——犯过的错写成规则。
从 22 样本可以抄的”骨架”
合成自以上 7 段的共同结构：
# [项目名] Project Guide
## Project Overview
[一句话说项目是什么 + 核心机制]
## CODEBASE DEVELOPMENT
### Build and Test Commands
- Install: ...
- Run tests: ...
- Lint: ...
- Format: ...
### Code Style
- Naming: ...
- File organization: ...
- **不要**（高亮）：...
### Architecture / Design Decisions
[为什么这样不那样 — 给改代码的 Claude 看]
### Directory Structure
(tree or table of folders)
### Known Pitfalls / Errata
- [踩过的坑 1]
- [踩过的坑 2]这个骨架和 CLAUDE.md 完全解读 给的”最小模板”非常接近——这不是巧合，是因为那个最小模板本来就是合成自类似样本。
22 份里比较少见的段落（值得参考）
7 个共同项之外，有些是”少数人做但想法很聪明”：
A. Permissions 预授权列表（样本里 3 个做）
在 CLAUDE.md 里直接写 “You can run these commands without asking: …”——实际上和 .claude/settings.json 的 permissions.allow 有重叠，但好处是文字说明让 Claude 更理解 why。
B. “When to ask me”段（样本里 4 个做）
比如 Comm 项目：
“Stop and ask before: (1) installing new dependencies; (2) changing the database schema; (3) modifying deployment configs.”
——不是”不能做”，是”做前先问”。细腻。
C. “模仿这个文件的风格”段（样本里 5 个做）
“When adding new commands, look at src/commands/hello.ts as the reference implementation.”
——把”代码风格”从抽象规则变成具体范本。Claude 模仿范本比遵守规则容易。
D. Meta：这份 CLAUDE.md 怎么维护（样本里 2 个做）
最罕见但最前沿：
“This CLAUDE.md is a living document. When you notice a pattern Claude keeps getting wrong, add it here. When a section becomes stale, remove it.”
——把 CLAUDE.md 本身当作项目的一部分来维护。呼应 案例_Boris 怎么用 Claude Code 的 “Compounding Engineering”。
陈彬视角
这是我见过最真实的 CLAUDE.md 研究素材——22 个不同领域不同作者的独立决策收敛出的共同结构，比任何”最佳实践模板”都可信。
对好朋友的建议：
起手阶段（第一版 CLAUDE.md）：前 4 段就够——项目一句话 + 常用命令 + 代码约定 + 不要做。别追求第一版完美，第一版的目的是”够用”。
演化阶段（用了两周后）：开始补架构决策段和已知坑段。这两段是”你开始被 Claude 犯同一种错折腾”之后自然写出来的。
成熟阶段（两三个月后）：考虑加 B（When to ask me）和 D（Meta 维护说明）段。这两段标志着你把 CLAUDE.md 当成活物在养，而不是一次性写完的文档。
一个提醒：别抄别人的 CLAUDE.md 当模板。抄结构没问题，抄具体内容没意义——别人写”不要用 lodash”对你不适用。CLAUDE.md 的价值密度在”你这个项目的特殊性”里，不在公共经验里。
关联
- 前置：CLAUDE.md 完全解读（规则和写法）
- 紧邻：案例_Boris 怎么用 Claude Code（Compounding Engineering）
- 紧邻：raw → wiki 知识沉淀机制（CLAUDE.md 里的”已知坑”段本质就是这个机制的微型版）
needs_sources（明确待补）
- 反面样本（写了 CLAUDE.md 但没用/反效果）
- 非 tech 领域（写作/教学/研究）的 CLAUDE.md
- 长期演化观察（同一个 CLAUDE.md 半年前 vs 现在对比）