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

核心原则

Conciseness over Completeness: Treat CLAUDE.md like frequently-used prompts, not exhaustive documentation
Evidence-Based Context: Analyze actual codebase before making recommendations
Incremental Refinement: Start minimal, iterate based on effectiveness
Token Efficiency: Every line should earn its presence in the context window
Human-Readable Structure: Use clear organization with XML tags for parsing

简洁优先于完整：将CLAUDE.md视为常用提示词，而非详尽文档
基于证据的上下文：提出建议前先分析实际代码库
增量优化：从最简版本开始，根据效果逐步迭代
Token效率：每一行内容都要在上下文窗口中体现价值
易读结构：使用清晰的组织方式，搭配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:

Discover - Analyze codebase (language, framework, structure, tests)
Extract - Identify code style, commands, patterns
Generate - Select template, customize for project
Validate - Verify commands, check token count
Present - Show output with explanation

Detailed Instructions: @refs/initialization-workflow.md

快速步骤：

发现 - 分析代码库（语言、框架、结构、测试）
提取 - 识别代码风格、命令、模式
生成 - 选择模板，针对项目定制
验证 - 验证命令正确性，检查Token数量
交付 - 展示输出内容并附带说明

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

Optimize Existing CLAUDE.md

优化现有CLAUDE.md

Quick Steps:

Analyze - Evaluate token efficiency, accuracy, relevance
Identify - Find redundancy, outdated info, generic fluff
Refactor - Apply token reduction, restructure, improve clarity
Test - Verify 40%+ token reduction, retain critical info
Present - Show before/after with metrics

Detailed Instructions: @refs/optimization-patterns.md

快速步骤：

分析 - 评估Token效率、准确性、相关性
定位问题 - 找出冗余内容、过时信息、通用套话
重构 - 应用Token缩减、结构调整、提升清晰度
测试 - 验证Token缩减40%以上，同时保留关键信息
交付 - 展示前后对比及指标数据

详细说明： @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 Type	Key Indicators	Template Focus
Web App	React/Vue/Angular, frontend build	UI components, responsive design, routing
Backend API	Express/FastAPI, database, auth	RESTful conventions, validation, security
CLI Tool	Commander/Click, stdio	Commands, user experience, file operations
Library	Package exports, no app logic	API design, versioning, backward compatibility
Monorepo	Workspaces, multiple packages	Cross-package changes, workspace commands

项目类型	关键指标	模板重点
Web应用	React/Vue/Angular、前端构建	UI组件、响应式设计、路由
后端API	Express/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 Complexity	Target 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时

Display generated content in code block
Explain customizations based on analysis
Highlight key decisions
Suggest optional additions
Provide save location and next steps

在代码块中展示生成内容
说明基于分析的定制点
突出关键决策
建议可选补充内容
提供保存位置及后续步骤

When Optimizing Existing CLAUDE.md

优化现有CLAUDE.md时

Summarize issues found
Show before/after comparison for key sections
Present optimized full version
Quantify improvements (token savings %)
Suggest iteration approach

Detailed Templates: @refs/output-templates.md

总结发现的问题
展示关键部分的前后对比
呈现完整优化版本
量化改进效果（Token节省百分比）
建议迭代方向

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

Common Mistakes to Avoid

常见错误规避

Problem	Solution
Over-Documentation	Document project-specific decisions only
Stale Information	Verify against current package.json, files
Redundant Context	Link to README, add only unique patterns
Token Waste	On-demand context by functional area
Generic Fluff	Specific 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创建/优化时，遵循上述决策树并参考相关文件获取详细说明。