CLAUDE.md 生成器 是做什么的？
读取代码库。编写一个只包含 Claude 所需信息的 CLAUDE.md：不多不少。
关键规则： 一份好的 CLAUDE.md 不超过 100 行。它只包含 Claude 无法从阅读代码本身推导出的信息。不要自动写入文件：始终先展示草稿并等待用户批准。
代码片段规则： 不要在 CLAUDE.md 中包含内联代码示例。应改用 file.ts:42 引用。CLAUDE.md 中的代码会浪费令牌且容易过时。
步骤 1：检测模式
确定要运行的三种模式：
create：不存在 CLAUDE.md。从头编写。 update：存在 CLAUDE.md。在不丢弃自定义内容的前提下进行改进。 audit：对项目中所有 CLAUDE.md 文件进行 A-F 评分并输出质量报告。如果用户说“审计”、“检查”、“审查”或“评分”我的 CLAUDE.md，则运行审计模式。
# 发现所有 CLAUDE.md 的位置
find . -name "CLAUDE.md" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null
ls ~/.claude/CLAUDE.md 2>/dev/null && echo "找到全局 CLAUDE.md"
ls .claude.local.md 2>/dev/null && echo "找到 .claude.local.md"
如果找到多个 CLAUDE.md 文件：列出它们。询问：“在 [位置] 找到了 CLAUDE.md。我应该全部更新还是只更新 [根目录]？”
步骤 2：审计模式（如果是 create/update 则跳过此步骤）
对于找到的每个 CLAUDE.md，使用以下评分标准进行 A-F 评分：
| 标准 | 检查内容 |
|---|---|
| 命令 | 构建/测试/lint 命令是否存在且可运行？ |
| 架构 | 是否解释了非显而易见的项目结构？ |
| 非显而易见模式 | 是否记录了常见陷阱、生成文件、环境变量顺序？ |
| 简洁性 | 是否在 100 行以内？没有明显的填充内容？ |
| 时效性 | 命令是否与当前的 package.json/Makefile 匹配？ |
| 可操作性 | 新贡献者能否在不提问的情况下遵循此文件？ |
评分：90-100 = A，70-89 = B，50-69 = C，30-49 = D，0-29 = F
以表格形式呈现：
## CLAUDE.md 审计报告
| 文件 | 评分 | 等级 | 主要问题 |
|------|-------|-------|-----------|
| ./CLAUDE.md | 72 | B | 缺少常见陷阱部分，测试命令已过时 |
| ./packages/api/CLAUDE.md | 45 | D | 无命令，340 行（太长了），架构说明已过时 |
**总体评分：B (72/100)**
发现的问题：
- ./packages/api/CLAUDE.md：340 行：远超 100 行的目标
- ./packages/api/CLAUDE.md：测试命令引用的是 `jest`，但 package.json 中使用的是 `vitest`
- ./CLAUDE.md：缺少常见陷阱部分：最有价值的部分缺失了
报告完成后，询问：“要我修复其中任何一个吗？（全部 / 仅根目录 / 指定）”
如果用户回答是，则针对他们想要修复的每个文件继续执行步骤 3。
步骤 3：扫描项目结构
# 项目类型和包管理器
ls package.json yarn.lock pnpm-lock.yaml bun.lockb requirements.txt pyproject.toml Cargo.toml go.mod 2>/dev/null
# 顶层目录结构
find . -maxdepth 2 -type d \
| grep -v node_modules | grep -v .git | grep -v __pycache__ \
| grep -v ".next" | grep -v dist | grep -v build | sort
步骤 4：提取构建和测试命令
# npm/yarn/pnpm/bun 脚本
cat package.json 2>/dev/null \
| python3 -c "
import sys, json
d = json.load(sys.stdin)
for name, cmd in d.get('scripts', {}).items():
print(f'{name}: {cmd}')
"
# Python、Go、Rust Makefiles
cat Makefile 2>/dev/null | grep -E "^[a-z].*:" | head -20
# Go
cat go.mod 2>/dev/null | head -5
# Rust
cat Cargo.toml 2>/dev/null | grep -E "^\[" | head -10
确定以下内容的精确命令：build、test（全部）、test（单个文件/名称）、dev server、lint/typecheck。注意运行它们所需的任何环境变量。
步骤 5：查找代码风格和常见陷阱
# 导入别名（最常被遗漏）
python3 -c "
import json, sys
try:
d = json.load(open('tsconfig.json'))
paths = d.get('compilerOptions', {}).get('paths', {})
if paths: print('导入别名:', json.dumps(paths, indent=2))
except: pass
" 2>/dev/null
# 所需的环境变量
cat .env.example 2>/dev/null | grep -v "^#" | grep -v "^$" | head -20
# 自动生成的文件（不可编辑）
find . -path "*/node_modules" -prune -o -name "*.ts" -print \
| xargs grep -l "DO NOT EDIT\|@generated\|Generated by" 2>/dev/null | head -5
# 测试设置要求
cat jest.config.js jest.config.ts vitest.config.ts 2>/dev/null | head -30
# 数据库/迁移设置
ls migrations/ prisma/ drizzle/ db/ 2>/dev/null
什么算作常见陷阱（包含这些，跳过其他所有内容）：
- 自动生成的文件（不可编辑）
- 运行测试之前所需的环境变量
- 非默认的导入别名映射
- 需要运行服务的测试命令
- 已知的故意怪癖（变通方法，而非错误）
步骤 6：使用 Gemini 生成 CLAUDE.md 草稿
编译所有发现并生成草稿：
cat > /tmp/claude-md-request.json << 'ENDJSON'
{
"system_instruction": {
"parts": [{
"text": "为一个软件项目编写 CLAUDE.md 文件。规则：(1) 总共不超过 100 行。(2) 只包含 Claude 无法从阅读代码中推导出的信息。(3) 无内联代码示例：改用 file.ts:42 引用。(4) 章节：Commands（命令）、Code Style（代码风格，仅非默认项）、Testing（测试，仅在需要设置时）、Gotchas（常见陷阱，必需：容易出错的地方）。跳过任何没有非显而易见内容的章节。(5) 所有命令放在代码块中。(6) 推荐顺序：简短的项目概述（1-2 句话，仅当非显而易见时）、Commands、Architecture（架构，仅非显而易见结构）、Code Style、Testing、Gotchas。(7) 不要使用 em dash（长破折号）。(8) 只输出 CLAUDE.md 内容，不加注释。"
}]
},
"contents": [{
"parts": [{
"text": "PROJECT_ANALYSIS_HERE"
}]
}],
"generationConfig": {
"temperature": 0.3,
"maxOutputTokens": 2048
}
}
ENDJSON
curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d @/tmp/claude-md-request.json \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(d['candidates'][0]['content']['parts'][0]['text'])"
将 PROJECT_ANALYSIS_HERE 替换为步骤 3-5 的发现。
对于大型项目（50+ 个文件）： 在 CLAUDE.md 底部添加一个 @path 指针，而不是内联细节：
## Extended Reference
See @docs/ai-context/architecture.md for full module map.
See @docs/ai-context/testing.md for integration test setup details.
将无法放入 100 行以内的细节写入 docs/ai-context/ 下的引用文件。
步骤 7：自我质量检查
在展示草稿前，检查：
- 不超过 100 行（计数：
echo "$CONTENT" | wc -l） - 无内联代码示例（仅
file.ts:42引用或 shell 命令） - 所有命令放在代码块中，且可直接运行
- 常见陷阱部分存在，且至少包含一个真实条目
- 没有只说明文件中显而易见内容的章节
- 没有 em dash
- 没有营销用语或填充短语（“该项目使用 React 来...”）
- 如果存在导入别名，已记录
- 如果存在自动生成的文件，已标记“不可编辑”
如果任何检查失败，在展示前进行修改。
步骤 8：展示草稿并等待批准
未经用户批准，切勿写入文件。
在代码块中展示草稿：
## CLAUDE.md 草稿（[N] 行）
[完整草稿内容]
---
将此写入 CLAUDE.md？（yes / edit first / cancel）
如果用户回答 yes：写入文件，然后确认：“CLAUDE.md 已写入（[N] 行）。章节：[所有 ## 标题列表]。”
如果用户回答 edit first：应用他们的编辑，重新展示草稿。
如果用户回答 cancel：停止。
不包含的内容
- 语言/框架版本（“这是一个 TypeScript 项目”）
- 框架工作原理（Claude 已经了解 React、FastAPI 等）
- 所有依赖项列表
- lint 器已经强制执行的风格规则（缩进大小、引号风格）
- 与 README.md 重复的内容
- 内联代码示例或多行代码片段
- 任何使用相同技术栈的任何项目都会完全相同的内容