claude-md-generator

CLAUDE.md 生成器

阅读代码库。编写一份 CLAUDE.md，准确告知 Claude 所需的信息，不多不少。

---

关键规则： 优秀的 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，则运行审计模式。

# Discover ALL CLAUDE.md locations
find . -name "CLAUDE.md" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null
ls ~/.claude/CLAUDE.md 2>/dev/null && echo "Global CLAUDE.md found"
ls .claude.local.md 2>/dev/null && echo ".claude.local.md found"

如果找到多个 CLAUDE.md 文件：列出这些文件。询问：“在 [locations] 中找到 CLAUDE.md。要更新所有文件，还是只更新 [root]？”

---

步骤 2：审计模式（如果是 create/update，则跳至步骤 3）

为找到的每个 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 Audit Report

| File | Score | Grade | Top Issues |
|------|-------|-------|-----------|
| ./CLAUDE.md | 72 | B | Missing gotchas section, test command outdated |
| ./packages/api/CLAUDE.md | 45 | D | No commands, 340 lines (too long), stale arch notes |

**Overall: B (72/100)**

Issues found:
- ./packages/api/CLAUDE.md: 340 lines: well over the 100-line target
- ./packages/api/CLAUDE.md: Test command references `jest` but package.json uses `vitest`
- ./CLAUDE.md: No Gotchas section: most valuable section is missing

报告后，询问：“要我修复其中任何文件吗？（全部／仅根目录／指定文件）”

如果用户回答是，则对其要求修复的每个文件继续执行步骤 3。

---

步骤 3：扫描项目结构

# Project type and package manager
ls package.json yarn.lock pnpm-lock.yaml bun.lockb requirements.txt pyproject.toml Cargo.toml go.mod 2>/dev/null

# Top-level directory structure
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 scripts
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

找出以下确切命令：构建、测试（全部）、测试（单个文件／名称）、开发服务器、lint／类型检查。记录运行这些命令所需的环境变量。

---

步骤 5：查找代码风格和注意事项

# Import aliases (most commonly missed)
python3 -c "
import json, sys
try:
    d = json.load(open('tsconfig.json'))
    paths = d.get('compilerOptions', {}).get('paths', {})
    if paths: print('Import aliases:', json.dumps(paths, indent=2))
except: pass
" 2>/dev/null

# Environment variables required
cat .env.example 2>/dev/null | grep -v "^#" | grep -v "^$" | head -20

# Auto-generated files (must not be edited)
find . -path "*/node_modules" -prune -o -name "*.ts" -print \
  | xargs grep -l "DO NOT EDIT\|@generated\|Generated by" 2>/dev/null | head -5

# Test setup requirements
cat jest.config.js jest.config.ts vitest.config.ts 2>/dev/null | head -30

# Database/migration setup
ls migrations/ prisma/ drizzle/ db/ 2>/dev/null

注意事项包括（仅包含以下内容，其他一律跳过）：

• 自动生成的文件（不得编辑）
• 测试运行前必须设置的环境变量
• 非默认的导入别名映射
• 需要正在运行的服务才能执行的测试命令
• 已知的有意设计的特殊行为（变通方案，而非 Bug）

---

步骤 6：使用 Gemini 生成 CLAUDE.md 草稿

汇总所有发现并生成草稿：

cat > /tmp/claude-md-request.json << 'ENDJSON'
{
  "system_instruction": {
    "parts": [{
      "text": "Write a CLAUDE.md file for a software project. Rules: (1) Under 100 lines total. (2) Only include what Claude cannot derive from reading the code. (3) No inline code examples: use file.ts:42 references instead. (4) Sections: Commands, Code Style (only non-defaults), Testing (only if setup needed), Gotchas (required: what trips people up). Skip any section that has nothing non-obvious to say. (5) All commands in code blocks. (6) Preferred order: short Project Overview (1-2 sentences, only if non-obvious), Commands, Architecture (only non-obvious structure), Code Style, Testing, Gotchas. (7) Do not use em dashes. (8) Output only the CLAUDE.md content, no commentary."
    }]
  },
  "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.

将所引用的文件写入 docs/ai-context/，其中包含无法纳入 100 行限制的详细信息。

---

步骤 7：自检

展示草稿前，请检查：

• 少于 100 行（计数：echo "$CONTENT" | wc -l）
• 没有内联代码示例（只能使用 file.ts:42 形式的引用或 shell 命令）
• 所有命令都在代码块中，且可直接运行
• 存在注意事项部分，且至少包含一条实际内容
• 没有只陈述文件中显而易见信息的部分
• 没有 em dash
• 没有营销用语或填充短语（“本项目使用 React……”）
• 如果存在导入别名，则已记录
• 如果存在自动生成的文件，则已标注“不得编辑”

如果任何一项检查未通过，请先修改，再展示。

---

步骤 8：展示草稿并等待批准

未经用户批准，绝不写入文件。

在代码块中展示草稿：

## Draft CLAUDE.md ([N] lines)

[full draft content here]

---
Write this to CLAUDE.md? (yes / edit first / cancel)

如果用户回答 yes：写入文件，然后确认： “已写入 CLAUDE.md（[N] 行）。包含的部分：[## 标题列表]。”

如果用户回答 edit first：应用其修改，然后重新展示草稿。

如果用户回答 cancel：停止。

---

不应包含的内容

• 语言／框架版本（“这是一个 TypeScript 项目”）
• 框架的工作原理（Claude 已经了解 React、FastAPI 等）
• 所有依赖项的列表
• 代码检查工具已强制执行的风格规则（缩进大小、引号风格）
• 与 README.md 重复的内容
• 行内代码示例或多行代码片段
• 对使用相同技术栈的任何项目都相同的内容