Back to Details

claude-md-architect

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CLAUDE.md Architect Skill

CLAUDE.md 架构师技能

Generate and optimize CLAUDE.md files for software projects by analyzing codebase context and applying Anthropic engineering best practices. Creates concise, maintainable project instructions that maximize Claude Code effectiveness while minimizing token consumption.
通过分析代码库上下文并应用Anthropic工程最佳实践，为软件项目生成并优化CLAUDE.md文件。创建简洁、可维护的项目说明，在最大程度提升Claude Code效果的同时减少Token消耗。

Core Principles

核心原则

  1. Conciseness over Completeness: Treat CLAUDE.md like frequently-used prompts, not exhaustive documentation
  2. Evidence-Based Context: Analyze actual codebase before making recommendations
  3. Incremental Refinement: Start minimal, iterate based on effectiveness
  4. Token Efficiency: Every line should earn its presence in the context window
  5. Human-Readable Structure: Use clear organization with XML tags for parsing
  1. 简洁优先于完整：将CLAUDE.md视为常用提示词，而非详尽文档
  2. 基于证据的上下文：提出建议前先分析实际代码库
  3. 增量优化：从最简版本开始，根据效果逐步迭代
  4. Token效率：每一行内容都要在上下文窗口中体现价值
  5. 易读结构：使用清晰的组织方式，搭配XML标签便于解析

When to Use This Skill

适用场景

Activate when user requests:
  • "init CLAUDE.md" or "create project instructions"
  • "optimize" or "improve" existing CLAUDE.md
  • "setup Claude for my project"
  • Project-specific instructions for Claude Code
  • Starting work on a new project that needs documentation
  • Existing CLAUDE.md is outdated or ineffective
当用户提出以下需求时激活此技能：
  • "初始化CLAUDE.md" 或 "创建项目说明"
  • "优化" 或 "改进" 现有CLAUDE.md
  • "为我的项目配置Claude"
  • 针对Claude Code的项目专属指令
  • 启动需要文档的新项目
  • 现有CLAUDE.md已过时或效果不佳

Quick Decision Tree

快速决策树

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
用户请求
    │
    ├─→ "init" 或 "create" → 初始化新的CLAUDE.md
    │   └─→ 参考：@refs/initialization-workflow.md
    │
    ├─→ "optimize" 或 "improve" → 优化现有CLAUDE.md
    │   └─→ 参考：@refs/optimization-patterns.md
    │
    └─→ "integrate" 或 "setup MCP/slash commands" → 集成配置
        └─→ 参考：@refs/integration-strategies.md

Workflow Overview

工作流概述

Initialize New CLAUDE.md

初始化新的CLAUDE.md

Quick Steps:
  1. Discover - Analyze codebase (language, framework, structure, tests)
  2. Extract - Identify code style, commands, patterns
  3. Generate - Select template, customize for project
  4. Validate - Verify commands, check token count
  5. Present - Show output with explanation
Detailed Instructions: @refs/initialization-workflow.md
快速步骤：
  1. 发现 - 分析代码库（语言、框架、结构、测试）
  2. 提取 - 识别代码风格、命令、模式
  3. 生成 - 选择模板，针对项目定制
  4. 验证 - 验证命令正确性，检查Token数量
  5. 交付 - 展示输出内容并附带说明
详细说明： @refs/initialization-workflow.md

Optimize Existing CLAUDE.md

优化现有CLAUDE.md

Quick Steps:
  1. Analyze - Evaluate token efficiency, accuracy, relevance
  2. Identify - Find redundancy, outdated info, generic fluff
  3. Refactor - Apply token reduction, restructure, improve clarity
  4. Test - Verify 40%+ token reduction, retain critical info
  5. Present - Show before/after with metrics
Detailed Instructions: @refs/optimization-patterns.md
快速步骤：
  1. 分析 - 评估Token效率、准确性、相关性
  2. 定位问题 - 找出冗余内容、过时信息、通用套话
  3. 重构 - 应用Token缩减、结构调整、提升清晰度
  4. 测试 - 验证Token缩减40%以上，同时保留关键信息
  5. 交付 - 展示前后对比及指标数据
详细说明： @refs/optimization-patterns.md

Token Reduction Quick Reference

Token缩减参考示例

Before (Verbose)

优化前（冗长版）

markdown
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.
markdown
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.

After (Concise)

优化后（简洁版）

markdown
undefined
markdown
undefined

Testing Requirements

测试要求

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

**Result:** 70% token reduction, same information
  • 新增功能需编写测试（Jest框架，覆盖率>80%）
  • 单元测试：针对
    src/lib/
    中的独立函数
  • 集成测试：使用Supertest测试API端点

**结果：** Token使用量减少70%，信息完整度不变

Template Selection Guide

模板选择指南

Project TypeKey IndicatorsTemplate Focus
Web AppReact/Vue/Angular, frontend buildUI components, responsive design, routing
Backend APIExpress/FastAPI, database, authRESTful conventions, validation, security
CLI ToolCommander/Click, stdioCommands, user experience, file operations
LibraryPackage exports, no app logicAPI design, versioning, backward compatibility
MonorepoWorkspaces, multiple packagesCross-package changes, workspace commands
项目类型关键指标模板重点
Web应用React/Vue/Angular、前端构建UI组件、响应式设计、路由
后端APIExpress/FastAPI、数据库、认证RESTful规范、校验、安全
CLI工具Commander/Click、标准输入输出命令、用户体验、文件操作
类库包导出、无应用逻辑API设计、版本管理、向后兼容
单体仓库工作区、多包管理跨包变更、工作区命令

Quality Checklist

质量检查清单

Before presenting CLAUDE.md:
  • ✓ File is <400 lines (prefer <250)
  • ✓ Commands verified against package.json/Makefile
  • ✓ Patterns match actual codebase conventions
  • ✓ No redundant info already in README
  • ✓ Context loading is selective, not exhaustive
  • ✓ Structure uses clear sections with headers
  • ✓ Examples are concrete, not generic
  • ✓ Security/testing requirements reflect actual needs
交付CLAUDE.md前需确认：
  • ✓ 文件行数<400（优先<250）
  • ✓ 命令已与package.json/Makefile验证
  • ✓ 模式匹配代码库实际约定
  • ✓ 无已在README中存在的冗余信息
  • ✓ 上下文加载为选择性加载，而非全盘加载
  • ✓ 结构清晰，使用标题划分章节
  • ✓ 示例具体，而非通用描述
  • ✓ 安全/测试要求符合实际需求

Token Budget Guidelines

Token预算指南

Project ComplexityTarget Token Count
Simple (single-purpose tool)100-200 tokens
Medium (standard web app)200-400 tokens
Complex (multi-service platform)400-800 tokens
Maximum (exception only)1000 tokens
If approaching max, split into:
  • .claude/CLAUDE.md
    (essentials)
  • .claude/ARCHITECTURE.md
    (reference, not auto-loaded)
  • .claude/commands/*.md
    (workflows as slash commands)
项目复杂度目标Token数量
简单（单一用途工具）100-200 Token
中等（标准Web应用）200-400 Token
复杂（多服务平台）400-800 Token
最大值（仅特殊情况）1000 Token
若接近最大值，可拆分为以下文件：
  • .claude/CLAUDE.md
    （核心内容）
  • .claude/ARCHITECTURE.md
    （参考文档，不自动加载）
  • .claude/commands/*.md
    （作为斜杠命令的工作流）

Content Priority

内容优先级

Keep (High Value)

保留（高价值）

  • Project-specific commands and scripts
  • Code style conventions unique to this project
  • File organization patterns
  • Testing requirements and strategies
  • Security constraints
  • Performance considerations
  • 项目专属命令和脚本
  • 项目特有的代码风格约定
  • 文件组织模式
  • 测试要求和策略
  • 安全约束
  • 性能考量

Remove (Low Value)

删除（低价值）

  • Generic software engineering advice
  • Information already in README
  • Obvious best practices (DRY, SOLID, etc.)
  • Detailed framework explanations (use context7)
  • Step-by-step tutorials (link to docs)
  • 通用软件工程建议
  • 已在README中存在的信息
  • 显而易见的最佳实践（DRY、SOLID等）
  • 详细框架说明（使用context7获取）
  • 分步教程（链接至官方文档）

Context Loading Strategy

上下文加载策略

Use @-syntax ONLY for:

仅在以下场景使用@语法：

  • Small, universally relevant files (<100 lines)
  • Configuration affecting all changes (tsconfig, .eslintrc)
  • Core type definitions used everywhere
  • 小型、通用相关文件（<100行）
  • 影响所有变更的配置文件（tsconfig、.eslintrc）
  • 全局使用的核心类型定义

Use On-Demand Loading:

使用按需加载：

markdown
When working on authentication:
  @src/lib/auth.ts
  @src/middleware/authenticate.ts
markdown
处理认证相关内容时：
  @src/lib/auth.ts
  @src/middleware/authenticate.ts

Avoid:

避免：

  • Loading entire directories with @src/**
  • Adding large files that aren't always needed
  • Injecting documentation that duplicates official sources
  • 使用@src/**加载整个目录
  • 添加并非始终需要的大文件
  • 注入与官方文档重复的内容

Integration with Global CLAUDE.md

与全局CLAUDE.md的集成

User has ~/.claude/CLAUDE.md (global):
  • Universal principles (SOLID, DRY, YAGNI)
  • MCP tool documentation
  • Preferred communication style
Project CLAUDE.md should:
  • Focus exclusively on project-specific guidance
  • Avoid duplicating MCP tool usage (already global)
  • Add project-specific MCP tool applications only
Example header:
markdown
undefined
用户拥有~/.claude/CLAUDE.md（全局配置）：
  • 通用原则（SOLID、DRY、YAGNI）
  • MCP工具文档
  • 偏好的沟通风格
项目级CLAUDE.md应：
  • 仅聚焦项目专属指导
  • 避免重复MCP工具使用说明（已在全局配置中）
  • 仅添加项目专属的MCP工具应用场景
示例头部：
markdown
undefined

MyProject - Development Guide

MyProject - 开发指南

Note: General software engineering principles are in your global CLAUDE.md. This guide focuses on project-specific patterns and requirements.
undefined
注意：通用软件工程原则请查看全局CLAUDE.md。 本指南仅聚焦项目专属模式与要求。
undefined

MCP Tool Configuration

MCP工具配置

Detect opportunities:

识别配置机会：

  • React/Vue/Angular imports → Suggest context7 for official docs
  • UI component requests → Suggest magic MCP for patterns
  • E2E test files → Suggest Playwright MCP for browser automation
  • React/Vue/Angular导入 → 推荐使用context7获取官方文档
  • UI组件请求 → 推荐使用magic MCP生成组件模式
  • E2E测试文件 → 推荐使用Playwright MCP进行浏览器自动化

Add to CLAUDE.md:

添加至CLAUDE.md：

markdown
undefined
markdown
undefined

MCP Tools Configuration

MCP工具配置

context7 (Official Documentation)

context7（官方文档）

Use for React hooks, Next.js routing, Prisma schema
用于React hooks、Next.js路由、Prisma schema相关内容

magic (UI Component Generation)

magic（UI组件生成）

Use for new components, accessibility improvements
用于新增组件、无障碍优化

Playwright (E2E Testing)

Playwright（E2E测试）

Use for user flows, visual regression, accessibility audits

**Detailed Integration Guide:** @refs/integration-strategies.md
用于用户流程、视觉回归测试、无障碍审计

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

Output Format

输出格式

When Generating New CLAUDE.md

生成新CLAUDE.md时

  1. Display generated content in code block
  2. Explain customizations based on analysis
  3. Highlight key decisions
  4. Suggest optional additions
  5. Provide save location and next steps
  1. 在代码块中展示生成内容
  2. 说明基于分析的定制点
  3. 突出关键决策
  4. 建议可选补充内容
  5. 提供保存位置及后续步骤

When Optimizing Existing CLAUDE.md

优化现有CLAUDE.md时

  1. Summarize issues found
  2. Show before/after comparison for key sections
  3. Present optimized full version
  4. Quantify improvements (token savings %)
  5. Suggest iteration approach
Detailed Templates: @refs/output-templates.md
  1. 总结发现的问题
  2. 展示关键部分的前后对比
  3. 呈现完整优化版本
  4. 量化改进效果（Token节省百分比）
  5. 建议迭代方向
详细模板： @refs/output-templates.md

Common Mistakes to Avoid

常见错误规避

ProblemSolution
Over-DocumentationDocument project-specific decisions only
Stale InformationVerify against current package.json, files
Redundant ContextLink to README, add only unique patterns
Token WasteOn-demand context by functional area
Generic FluffSpecific patterns: "Use Zod validation, Prisma transactions"
问题解决方案
过度文档化仅记录项目专属决策
信息过时与当前package.json、文件验证一致
上下文冗余链接至README，仅添加独特模式
Token浪费按功能区域按需加载上下文
通用套话使用具体模式：如"使用Zod校验、Prisma事务"

Success Metrics

成功指标

Effective CLAUDE.md

高效CLAUDE.md

  • Claude requires fewer clarifying questions
  • Code matches project conventions on first try
  • Commands work without errors
  • User rarely provides missing context manually
  • Claude需要的澄清问题更少
  • 生成代码首次即可匹配项目约定
  • 命令执行无错误
  • 用户无需手动重复提供缺失上下文

Ineffective CLAUDE.md

低效CLAUDE.md

  • Claude frequently asks "what framework?"
  • Generated code doesn't match existing style
  • User repeatedly provides same context files
  • CLAUDE.md contains info never referenced
  • Claude频繁询问"使用什么框架？"
  • 生成代码与现有风格不符
  • 用户反复提供相同上下文文件
  • CLAUDE.md包含从未被引用的信息

Philosophy

设计理念

Remember:
  • CLAUDE.md is a living document, not permanent documentation
  • Start minimal, add based on actual friction points
  • Remove guidance that doesn't improve Claude's output
  • Measure effectiveness: fewer questions = better CLAUDE.md
When in doubt:
  • Prefer concise over comprehensive
  • Prefer specific over generic
  • Prefer examples over explanations
  • Prefer on-demand over auto-loading
请记住：
  • CLAUDE.md是动态文档，而非永久文档
  • 从最简版本开始，根据实际痛点逐步添加内容
  • 删除无法提升Claude输出效果的指导
  • 效果衡量标准：问题越少 = CLAUDE.md质量越高
存疑时遵循：
  • 优先简洁而非全面
  • 优先具体而非通用
  • 优先示例而非解释
  • 优先按需加载而非自动加载

Reference Files

参考文件

  • @refs/initialization-workflow.md - Complete guide for creating new CLAUDE.md files from scratch
  • @refs/optimization-patterns.md - Techniques for reducing tokens and improving effectiveness
  • @refs/integration-strategies.md - Integration with global config, MCP tools, slash commands
  • @refs/output-templates.md - Standard formats for presenting results to users
Quick Start: When user requests CLAUDE.md creation/optimization, follow the decision tree above and consult relevant reference files for detailed instructions.
  • @refs/initialization-workflow.md - 从零创建CLAUDE.md的完整指南
  • @refs/optimization-patterns.md - 缩减Token与提升效果的技巧
  • @refs/integration-strategies.md - 与全局配置、MCP工具、斜杠命令的集成指南
  • @refs/output-templates.md - 向用户交付结果的标准格式
快速启动： 当用户请求CLAUDE.md创建/优化时，遵循上述决策树并参考相关文件获取详细说明。