name: claudemd-maintainer description: 用于维护和改进CLAUDE.md文件的上下文感知指导。在编辑CLAUDE.md、讨论AI助手文档结构或优化项目指令时使用。

CLAUDE.md 维护者（智能路由）

目的

为维护和改进CLAUDE.md文件提供上下文感知指导。帮助确保文件保持有效、简洁，并遵循LLM指令文件的最佳实践。

自动激活时机

编辑或讨论CLAUDE.md时
关键词：claude.md, 项目指令, claude入门, 上下文文件
讨论AI助手的文档结构时

🚨 关键规则

保持在300行以下 - 研究表明LLM能可靠处理约150-200条指令；行数增加性能下降
切勿自动生成 - 手动编写每行内容；自动生成内容常含噪声
仅包含通用适用性 - 移除任务特定或范围狭窄的指导
文件引用优于代码片段 - 代码嵌入易过时；路径保持准确

📊 有效的CLAUDE.md原则

包含内容（什么、为什么、如何）

类别	包含	避免
技术栈	技术、架构概述	详尽依赖列表
关键规则	必须遵循的行为（合并）	跨章节重复的规则
快速命令	基本构建/运行命令	完整命令参考
文件引用	详细指南的路径	可能过时的嵌入代码
常见错误	记录的实际失败	假设性警告

排除内容

代码风格指南 → 使用代码格式化工具（如SwiftFormat、ESLint等）
详尽命令参考 → 指向工具文档
任务特定指令 → 放入技能或单独文档
代码片段 → 使用file:line引用代替

🎯 渐进式披露模式

级别1：CLAUDE.md（理想100-150行，最大300行）
├─ 关键规则（必须遵循的行为）
├─ 快速入门（仅基本命令）
├─ 高级架构
└─ 指向级别2和3

级别2：技能（.claude/skills/）
├─ 领域特定快速参考
├─ 决策树和工作流
└─ “→ 路由到”综合文档

级别3：专业指南
├─ 完整技术文档
├─ 完整示例和边缘案例
└─ 故障排除指南

📋 快速审核清单

审核CLAUDE.md时：

[ ] 行数低于300？（使用wc -l CLAUDE.md）
[ ] 无重复规则？（搜索重复概念）
[ ] 最小化代码片段？（用文件路径引用替换）
[ ] 移除狭窄范围项？（移至技能）
[ ] 关键规则合并？（单一权威位置）
[ ] 文件引用最新？（路径仍有效）
[ ] 记录常见错误？（实际失败，非假设）

🔄 优化工作流

减少行数

查找重复项：搜索重复概念

# 查找潜在重复
grep -n "NEVER" CLAUDE.md | head -20

合并规则：将所有关键规则移至一个章节

用引用替换代码：

# ❌ 之前（占用10+行）
### 排版
```swift
AnytypeText("标题", style: .uxTitle1Semibold)
AnytypeText("正文", style: .bodyRegular)

✅ 之后（1行）

排版 → path/to/TYPOGRAPHY_MAPPING.md

将狭窄指导移至技能：如果适用于不到20%的任务，则为技能

添加新指导

添加前询问：

这适用于大多数任务吗？（如果否 → 技能或专业文档）
有现有指导吗？（如果是 → 合并，勿重复）
代码格式化工具能强制执行吗？（如果是 → 使用工具）
此代码示例会很快过时吗？（如果是 → 使用文件引用）

⚠️ 常见错误

累积热修复

# ❌ 错误 - 添加一次性规则
### 特别说明（2025-01-15）
执行Y时始终检查X...

# ✅ 正确 - 添加至适当技能或移除

重复规则

# ❌ 错误 - 同一规则在3处
## 关键规则：切勿添加AI签名
## 预提交：无AI签名
## PR格式：无“Generated with Claude”

# ✅ 正确 - 单一合并规则
## 关键规则
2. **切勿在任何地方添加AI签名** - 无Co-Authored-By，无表情签名

嵌入易过时代码

# ❌ 错误 - 代码将过时
```swift
Image(asset: .X32.qrCode)  // 如果资产名称变更？

✅ 正确 - 文件引用保持准确

图标 → Modules/Assets/.../ImageAsset.swift:45


## 📚 研究与最佳实践

**来源**：基于行业实践和LLM行为研究

### 主要发现
- LLM能可靠处理约150-200条指令
- 指令增加性能下降
- 无关上下文可能被完全忽略（Claude添加“此上下文可能相关或不相关”）
- 文档中代码片段成为维护负担
- 渐进式披露减少上下文开销

### 推荐指标
| 指标 | 目标 | 最大值 |
|--------|--------|-----|
| 总行数 | 100-150 | 300 |
| 代码块 | 2-4 | 6 |
| 关键规则 | 3-5 | 10 |
| 章节 | 6-8 | 12 |

## 🔗 相关

- `.claude/skills/README.md` - 技能系统概述
- `.claude/skills/skills-manager/SKILL.md` - 管理技能系统
- 渐进式披露架构文档

---

**导航**：此技能帮助维护CLAUDE.md质量。对于技能系统管理，参见`skills-manager`。对于添加新技能，参见`.claude/skills/README.md`。