CLAUDE.md 文件增强器

这个技能为 Claude Code 项目提供全面的 CLAUDE.md 文件生成和增强服务。它分析现有文件，验证最佳实践，并生成针对您的项目类型、技术栈和团队规模定制化的指南。

功能

🆕 交互式初始化：智能工作流程，探索您的代码库，检测项目类型和技术栈，请求确认，然后创建定制化的 CLAUDE.md 文件
✨ 100% 原生格式合规：所有生成的文件遵循官方 Claude Code 格式，包括项目结构图、设置说明、架构部分和文件结构解释（匹配 /update-claude-md 命令）
分析现有文件：扫描并评估当前 CLAUDE.md 文件的结构、完整性和质量
验证最佳实践：根据 Anthropic 指南检查（文件长度、必需部分、格式化标准）
生成新文件：为新项目从头开始创建完整的 CLAUDE.md 文件
增强现有文件：添加缺失的部分，改善结构，并更新至最新的最佳实践
模块化架构：支持子目录中的上下文特定 CLAUDE.md 文件（backend/、frontend/、docs/）
技术栈定制：为特定技术（TypeScript、Python、Go、React、Vue 等）定制指南
团队规模适应：根据团队规模（单人、小型 <10、中型 10+、大型 50+）调整复杂性
模板选择：根据项目复杂性和开发阶段选择合适的模板

输入要求

分析和增强

提供现有 CLAUDE.md 文件内容或文件路径：

{
  "mode": "enhance",
  "file_path": "CLAUDE.md",
  "content": "[现有 CLAUDE.md 内容]",
  "project_context": {
    "type": "web_app",
    "tech_stack": ["typescript", "react", "node", "postgresql"],
    "team_size": "small",
    "phase": "mvp"
  }
}

新文件生成

提供项目上下文：

{
  "mode": "create",
  "project_context": {
    "type": "api",
    "tech_stack": ["python", "fastapi", "postgresql", "docker"],
    "team_size": "medium",
    "phase": "production",
    "workflows": ["tdd", "cicd", "documentation_first"]
  },
  "modular": true,
  "subdirectories": ["backend", "database", "docs"]
}

上下文参数

type: 项目类型（web_app、api、fullstack、cli、library、mobile、desktop）
tech_stack: 技术栈数组（例如，["typescript", "react", "node"]）
team_size: solo、small（<10）、medium（10-50）、large（50+）
phase: 开发阶段（prototype、mvp、production、enterprise）
workflows: 关键工作流程（tdd、cicd、documentation_first、agile 等）

输出格式

分析报告

{
  "analysis": {
    "file_size": 450,
    "line_count": 320,
    "sections_found": [
      "快速导航",
      "核心原则",
      "技术栈",
      "工作流程说明"
    ],
    "missing_sections": [
      "测试要求",
      "错误处理模式"
    ],
    "issues": [
      {
        "type": "length_warning",
        "severity": "medium",
        "message": "文件超过推荐的 300 行（320 行）"
      },
      {
        "type": "missing_section",
        "severity": "low",
        "message": "考虑添加 '测试要求' 部分"
      }
    ],
    "quality_score": 75,
    "recommendations": [
      "拆分为模块化文件（backend/CLAUDE.md、frontend/CLAUDE.md）",
      "添加测试要求部分",
      "将根文件减少到 <150 行"
    ]
  }
}

生成内容

完整的 CLAUDE.md 文件内容或要添加的特定部分：

# CLAUDE.md

此文件为 Claude Code 在处理本项目时提供指导。

## 快速导航

- [后端指南](backend/CLAUDE.md)
- [前端指南](frontend/CLAUDE.md)
- [数据库操作](database/CLAUDE.md)
- [CI/CD 工作流程](.github/CLAUDE.md)

## 核心原则

1. **测试驱动开发**：在实现之前编写测试
2. **类型安全优先**：在整个项目中使用 TypeScript 严格模式
3. **组件组合**：偏好小型、可复用的组件
4. **错误处理**：始终使用适当的日志记录处理错误
5. **文档更新**：保持文档与代码变更同步

[... 根据模板添加的额外部分 ...]

如何使用

示例 1：为新项目初始化 CLAUDE.md（交互式）

嘿 Claude—我刚刚添加了 "claude-md-enhancer" 技能。我还没有 CLAUDE.md 文件。你能帮我为这个项目创建一个吗？

会发生什么：

Claude 检查 CLAUDE.md 是否存在（不存在）
Claude 使用内置命令探索你的代码库
Claude 分析：项目类型、技术栈、团队规模、工作流程
Claude 显示发现并请求确认
你确认设置
Claude 创建定制化的 CLAUDE.md 文件（s）
Claude 增强最佳实践

交互流程：

✋ 用户必须在创建前确认
🔍 对发现的内容完全可见
⚙️ 在继续前调整设置的选项

示例 2：分析现有 CLAUDE.md

嘿 Claude—我刚刚添加了 "claude-md-enhancer" 技能。你能分析我当前的 CLAUDE.md 文件并告诉我缺少什么或可以改进的地方吗？

示例 2：为 TypeScript 项目生成新 CLAUDE.md

嘿 Claude—我刚刚添加了 "claude-md-enhancer" 技能。你能为我的 TypeScript React 项目创建一个 CLAUDE.md 文件吗？我们有 5 名开发人员。我们使用 PostgreSQL、Docker 并遵循 TDD 实践。

示例 3：增强现有文件

嘿 Claude—我刚刚添加了 "claude-md-enhancer" 技能。你能通过添加缺失的部分和改善结构来增强我现有的 CLAUDE.md 文件吗？这是我当前的文件：[粘贴内容]

示例 4：生成模块化架构

嘿 Claude—我刚刚添加了 "claude-md-enhancer" 技能。你能为我的全栈项目创建一个模块化的 CLAUDE.md 设置吗？我需要分别为后端（Python/FastAPI）、前端（React）和数据库（PostgreSQL）的文件。

初始化工作流程（新项目）

当项目根目录中不存在 CLAUDE.md 时，此技能提供智能初始化工作流程：

工作流程步骤

步骤 1：检测

技能检查项目根目录中是否存在 CLAUDE.md
如果未找到，则开始初始化工作流程

步骤 2：代码库探索

使用 Claude Code 的内置 explore 命令
分析项目结构、文件和目录
检查配置文件（package.json、requirements.txt、go.mod 等）
查看现有文档

步骤 3：智能分析

项目类型检测：web_app、api、fullstack、cli、library、mobile、desktop
技术栈检测：TypeScript、Python、React、FastAPI、PostgreSQL、Docker 等
团队规模估计：基于项目复杂性（单人、小型、中型、大型）
开发阶段：prototype、mvp、production、enterprise
工作流程检测：TDD、CI/CD、documentation-first、agile
结构推荐：单文件 vs. 模块化架构

步骤 4：用户确认 ✋

以清晰格式显示所有发现
显示推荐的 CLAUDE.md 结构
请求用户确认或调整设置
用户必须明确批准 才能继续

步骤 5：文件创建

根据确认的设置生成定制化的 CLAUDE.md
如果推荐，则创建模块化文件（backend/、frontend/ 等）
应用技术特定的最佳实践

步骤 6：增强

验证生成的内容
添加质量改进
确保完整性

步骤 7：总结

显示创建了哪些文件
提供后续步骤
立即准备使用

交互示例

用户："我需要这个项目的 CLAUDE.md"

Claude："我将首先探索你的代码库以了解项目。
        [使用内置命令探索]

        根据我的探索，以下是我发现的：

        项目类型：全栈应用
        技术栈：TypeScript、React、Node.js、PostgreSQL、Docker
        团队规模：小型（2-9 名开发人员）
        开发阶段：MVP
        工作流程：TDD、CI/CD

        推荐结构：模块化架构
        - 根 CLAUDE.md（导航中心）
        - backend/CLAUDE.md（API 指南）
        - frontend/CLAUDE.md（React 指南）

        你想让我创建这些文件吗？"

用户："是的，请继续"

Claude："正在创建定制化的 CLAUDE.md 文件...
        ✅ 创建了 CLAUDE.md（100 行）
        ✅ 创建了 backend/CLAUDE.md（150 行）
        ✅ 创建了 frontend/CLAUDE.md（175 行）

        你的项目已准备好进行 AI 辅助开发！"

脚本

workflow.py

管理新项目的交互式初始化工作流程。

关键功能：

check_claude_md_exists() - 检测 CLAUDE.md 是否存在
generate_exploration_prompt() - 引导 Claude 探索代码库
analyze_discoveries() - 分析探索结果
generate_confirmation_prompt() - 创建用户确认提示
get_workflow_steps() - 获取完整的工作流程步骤

analyzer.py

分析现有 CLAUDE.md 文件以识别结构、部分和质量问题。

关键功能：

analyze_file() - 解析并分析 CLAUDE.md 结构
detect_sections() - 识别存在和缺失的部分
calculate_quality_score() - 评分文件质量（0-100）
generate_recommendations() - 提供可操作的改进建议

validator.py

根据最佳实践和 Anthropic 指南验证 CLAUDE.md 文件。

关键功能：

validate_length() - 检查文件长度（如果 >300 行则警告）
validate_structure() - 验证必需部分是否存在
validate_formatting() - 检查 markdown 格式化质量
validate_completeness() - 确保包含关键信息

generator.py

基于模板生成新的 CLAUDE.md 内容或缺失的部分。

关键功能：

generate_root_file() - 创建主 CLAUDE.md 协调器
generate_context_file() - 创建上下文特定文件（后端、前端等）
generate_section() - 生成单个部分（技术栈、工作流程等）
merge_with_existing() - 将新部分添加到现有文件中

template_selector.py

根据项目上下文选择合适的模板。

关键功能：

select_template() - 根据项目类型和团队规模选择模板
customize_template() - 根据技术栈调整模板
determine_complexity() - 计算适当的细节级别
recommend_modular_structure() - 建议子目录组织

最佳实践

临界验证规则 ⚠️

“在声明完成之前，始终将输出与官方示例进行对比验证。”

在最终确定任何 CLAUDE.md 生成之前：

将输出与 /update-claude-md 命令格式进行对比
检查官方 Claude Code 文档以获取必需的部分
验证所有原生格式部分是否存在（概述、项目结构、文件结构、设置和安装、架构等）
与 examples/ 文件夹中的参考示例进行交叉检查

对于新项目

从最小模板（50-100 行）开始，根据需要增长
对于有 >3 个主要组件的项目，使用模块化架构
立即包含技术栈参考
在团队规模超过 5 人之前添加工作流程说明

增强

修改前先分析 - 首先了解当前结构
保留自定义内容 - 只增强，不替换
更改后验证 - 确保改进不会破坏现有模式
与 Claude Code 测试 - 验证指南按预期工作

通用指南

保持根文件简洁 - 最多 150 行，用作导航中心
使用上下文特定文件 - backend/CLAUDE.md、frontend/CLAUDE.md 等。
避免重复 - 每个指南应该只出现一次
链接到外部文档 - 不要复制官方文档
定期更新 - 每季度审查指南或当技术栈变化时

限制

技术限制

需要有效的项目上下文以进行准确的模板选择
技术栈检测基于关键字，可能需要手动细化
模块文件生成假设标准目录结构

范围边界

专注于 CLAUDE.md 结构，而不是项目特定的业务逻辑
最佳实践建议是通用的，可能需要行业特定的定制
验证是基于指南的，不是强制的（未经批准，没有自动修复）

何时不使用

对于非 Claude AI 工具（这是 Claude Code 特定的）
对于不使用 Claude Code 或类似 AI 助手的项目
当你需要高度专业化的领域指南（法律、医疗合规）

模板类别

按规模

最小（50 行） - 单人开发者、原型、黑客松
核心（100-150 行） - 小型团队、MVP、标准项目
详细（200-300 行） - 大型团队、生产系统、企业

按项目类型

Web 应用 - 前端重点（React、Vue、Angular）
API - 后端服务（REST、GraphQL、微服务）
全栈 - 集成前端 + 后端
CLI - 命令行工具和实用程序
库 - 可重用的包和框架
移动 - React Native、Flutter、原生 iOS/Android

按技术栈

TypeScript/Node - 现代 JavaScript 生态系统
Python - Django、FastAPI、Flask
Go - Gin、Echo、原生服务
Java/Kotlin - Spring Boot、企业 Java
Ruby - Rails、Sinatra

质量指标

文件质量评分（0-100）

根据以下因素计算：

长度适当性（25 分） - 不太短或太长
部分完整性（25 分） - 必需部分存在
格式化质量（20 分） - 适当的 markdown 结构
内容特异性（15 分） - 针对项目，不通用
模块化组织（15 分） - 在适当时使用子目录文件

建议优先级

关键 - 缺少必需部分，文件过长（>400 行）
高 - 缺少重要部分，格式化问题
中 - 可以添加可选部分，小改进
低 - 锦上添花的增强，风格建议

高级功能

模块化架构支持

自动生成上下文特定文件：

project-root/
├── CLAUDE.md                 # 根协调器（100-150 行）
├── backend/
│   └── CLAUDE.md            # 后端特定（150-200 行）
├── frontend/
│   └── CLAUDE.md            # 前端特定（150-200 行）
├── database/
│   └── CLAUDE.md            # 数据库操作（100-150 行）
└── .github/
    └── CLAUDE.md            # CI/CD 工作流程（100-150 行）

技术栈检测

自动从以下文件中检测技术：

package.json（Node.js/TypeScript）
requirements.txt 或 pyproject.toml（Python）
go.mod（Go）
Cargo.toml（Rust）
pom.xml 或 build.gradle（Java）

团队规模适应

调整细节级别：

单人：最小指南，注重效率
小型（<10）：核心指南，工作流程基础
中型（10-50）：详细指南，团队协调
大型（50+）：全面指南，流程执行

参考资料

Anthropic Claude Code 文档：https://docs.claude.com/en/docs/claude-code
CLAUDE.md 最佳实践：基于社区模式和 Anthropic 指导
示例 CLAUDE.md 文件：查看 examples/ 文件夹，了解涵盖不同项目类型和团队规模的 6 个参考实现

版本

版本：1.0.0 最后更新：2025 年 11 月兼容：Claude Code 2.0+、Claude Apps、Claude API

记住：目标是使 Claude 更高效、更具上下文感知能力，而不是创建官僚作风。从简单开始，根据实际使用迭代，并在可能的情况下自动化质量检查。