claude-md-architect

CLAUDE.md 架构技能

通过分析代码库上下文并应用 Anthropic 工程最佳实践，为软件项目生成并优化 CLAUDE.md 文件。创建简洁、易维护的项目说明，在最大限度发挥 Claude Code 效能的同时，尽量减少令牌消耗。

核心原则

1. 精简优先于面面俱到：将 CLAUDE.md 视为常用提示词，而非详尽文档
2. 基于证据的上下文：提出建议前，先分析实际代码库
3. 渐进式改进：从最简版本开始，根据效果迭代
4. 令牌效率：上下文窗口中的每一行都应物有所值
5. 便于阅读的结构：使用清晰的组织结构和 XML 标签，便于解析

何时使用此技能

在用户提出以下请求时启用：

• “init CLAUDE.md”或“创建项目说明”
• “优化”或“改进”现有 CLAUDE.md
• “为我的项目配置 Claude”
• 为 Claude Code 编写项目专属说明
• 开始处理需要文档的新项目
• 现有 CLAUDE.md 已过时或效果不佳

快速决策树

User Request
    │
    ├─→ "init" or "create" → Initialize New CLAUDE.md
    │   └─→ Follow: @refs/initialization-workflow.md
    │
    ├─→ "optimize" or "improve" → Optimize Existing CLAUDE.md
    │   └─→ Follow: @refs/optimization-patterns.md
    │
    └─→ "integrate" or "setup MCP/slash commands" → Integration
        └─→ Follow: @refs/integration-strategies.md

工作流概览

初始化新的 CLAUDE.md

快速步骤：

1. 探索——分析代码库（语言、框架、结构、测试）
2. 提取——识别代码风格、命令和模式
3. 生成——选择模板并按项目定制
4. 验证——验证命令并检查令牌数
5. 呈现——展示结果并说明理由

详细说明： @refs/initialization-workflow.md

优化现有 CLAUDE.md

快速步骤：

1. 分析——评估令牌效率、准确性和相关性
2. 识别——找出冗余、过时信息和泛泛内容
3. 重构——精简令牌、调整结构并提升清晰度
4. 测试——确认令牌减少 40% 以上，同时保留关键信息
5. 呈现——展示优化前后的内容及指标

详细说明： @refs/optimization-patterns.md

令牌精简快速参考

精简前（冗长）

When you are implementing new features in this codebase, it's very important that you always make sure to write comprehensive tests for all the functionality you add. We use Jest as our testing framework, and we expect all new code to have at least 80% code coverage.

精简后（简洁）

### Testing Requirements
- New features require tests (Jest, >80% coverage)
- Unit tests: Individual functions in `src/lib/`
- Integration tests: API endpoints with Supertest

结果： 令牌减少 70%，信息不变

模板选择指南

项目类型	关键指标	模板重点
Web 应用	React/Vue/Angular、前端构建	UI 组件、响应式设计、路由
后端 API	Express/FastAPI、数据库、身份验证	RESTful 约定、验证、安全
CLI 工具	Commander/Click、标准输入输出	命令、用户体验、文件操作
库	包导出、无应用逻辑	API 设计、版本控制、向后兼容
单体仓库	工作区、多个包	跨包更改、工作区命令

质量检查清单

呈现 CLAUDE.md 前：

• ✓ 文件少于 400 行（最好少于 250 行）
• ✓ 已根据 package.json/Makefile 验证命令
• ✓ 模式符合代码库的实际约定
• ✓ 未重复 README 中已有的信息
• ✓ 选择性加载上下文，而非加载全部内容
• ✓ 使用清晰的标题划分章节
• ✓ 示例具体，不流于泛泛
• ✓ 安全和测试要求符合实际需求

令牌预算指南

项目复杂度	目标令牌数
简单（单一用途工具）	100-200 个令牌
中等（标准 Web 应用）	200-400 个令牌
复杂（多服务平台）	400-800 个令牌
最大值（仅限例外情况）	1000 个令牌

如果接近最大值，可拆分为：

• .claude/CLAUDE.md（核心内容）
• .claude/ARCHITECTURE.md（参考资料，不会自动加载）
• .claude/commands/*.md（以斜杠命令形式提供的工作流）

内容优先级

保留（高价值）

• 项目专属命令和脚本
• 此项目特有的代码风格约定
• 文件组织模式
• 测试要求和策略
• 安全约束
• 性能注意事项

删除（价值低）

• 通用软件工程建议
• README 中已有的信息
• 显而易见的最佳实践（DRY、SOLID 等）
• 详细的框架说明（使用 context7）
• 分步教程（链接到文档）

上下文加载策略

仅在以下情况下使用 @ 语法：

• 小型且普遍适用的文件（<100 行）
• 影响所有更改的配置（tsconfig、.eslintrc）
• 在各处使用的核心类型定义

按需加载：

When working on authentication:
  @src/lib/auth.ts
  @src/middleware/authenticate.ts

避免：

• 使用 @src/** 加载整个目录
• 添加并非始终需要的大型文件
• 注入与官方来源重复的文档

与全局 CLAUDE.md 集成

用户有 ~/.claude/CLAUDE.md（全局配置）：

• 通用原则（SOLID、DRY、YAGNI）
• MCP 工具文档
• 偏好的沟通风格

项目 CLAUDE.md 应该：

• 仅关注项目专属的指导
• 避免重复 MCP 工具用法（全局配置中已有）
• 仅添加项目特定的 MCP 工具应用

示例标题：

# MyProject - Development Guide

> Note: General software engineering principles are in your global CLAUDE.md.
> This guide focuses on project-specific patterns and requirements.

MCP 工具配置

识别使用机会：

• 导入 React/Vue/Angular → 建议使用 context7 查阅官方文档
• UI 组件请求 → 建议使用 magic MCP 获取模式
• E2E 测试文件 → 建议使用 Playwright MCP 进行浏览器自动化

添加到 CLAUDE.md：

## MCP Tools Configuration

### context7 (Official Documentation)
Use for React hooks, Next.js routing, Prisma schema

### magic (UI Component Generation)
Use for new components, accessibility improvements

### Playwright (E2E Testing)
Use for user flows, visual regression, accessibility audits

详细集成指南： @refs/integration-strategies.md

输出格式

生成新的 CLAUDE.md 时

1. 在代码块中显示生成的内容
2. 说明基于分析所做的自定义
3. 突出关键决策
4. 建议可选的补充内容
5. 提供保存位置和后续步骤

优化现有 CLAUDE.md 时

1. 总结发现的问题
2. 展示关键章节的优化前后对比
3. 提供优化后的完整版本
4. 量化改进幅度（节省的 token 百分比）
5. 建议迭代方式

详细模板： @refs/output-templates.md

应避免的常见错误

问题	解决方案
文档过多	仅记录项目特定的决策
信息过时	对照当前的 package.json 和文件进行验证
上下文冗余	链接到 README，仅添加独有模式
Token 浪费	按功能领域按需加载上下文
泛泛而谈	使用具体模式：“使用 Zod 验证、Prisma 事务”

成功指标

有效的 CLAUDE.md

• Claude 需要提出更少的澄清问题
• 代码首次生成就符合项目规范
• 命令运行无误
• 用户很少需要手动补充缺失的上下文

无效的 CLAUDE.md

• Claude 经常询问“使用什么框架？”
• 生成的代码与现有风格不一致
• 用户反复提供相同的上下文文件
• CLAUDE.md 包含从未被引用的信息

理念

请记住：

• CLAUDE.md 是一份持续更新的文档，而非永久性文档
• 从精简开始，根据实际阻碍逐步添加
• 删除无法改善 Claude 输出的指导
• 衡量效果：问题越少 = CLAUDE.md 越好

如有疑问：

• 宁可简洁，不要面面俱到
• 宁可具体，不要泛泛而谈
• 宁可提供示例，不要进行解释
• 宁可按需加载，不要自动加载

参考文件

• @refs/initialization-workflow.md - 从头创建新的 CLAUDE.md 文件的完整指南
• @refs/optimization-patterns.md - 减少 token 并提升效果的技巧
• @refs/integration-strategies.md - 与全局配置、MCP 工具和斜杠命令集成
• @refs/output-templates.md - 向用户展示结果的标准格式

---

快速入门： 用户请求创建或优化 CLAUDE.md 时，请遵循上述决策树，并查阅相关参考文件获取详细说明。