⚡

CLAUDE.md编写技能Skill claude-md-authoring

这个技能用于创建和审查CLAUDE.md配置文件，优化Claude Code的使用。它应用HumanLayer指南，包括指令预算管理、WHAT/WHY/HOW框架和渐进披露，识别并避免反模式如将AI用作代码检查器。关键词：CLAUDE.md, 配置编写, Claude Code, 指令预算, 渐进披露, 开发指南, 反模式识别。

架构设计 0 次安装 0 次浏览 更新于 3/9/2026

name: claude-md-authoring description: 创建和审查Claude Code的CLAUDE.md配置文件。应用HumanLayer指南，包括指令预算（约50用户级，约100项目级）、WHAT/WHY/HOW框架和渐进披露。识别反模式，如将Claude用作风格规则的代码检查器。

CLAUDE.md 编写

快速入门

  1. 确定范围：用户级（~/.claude/）还是项目级（.claude/）？
  2. 应用WHAT/WHY/HOW框架（仅项目级）
  3. 保持指令在预算内：用户级约50，项目级约100
  4. 切勿将Claude用作代码检查器：风格规则属于工具，而非CLAUDE.md
  5. 在最终确定前使用质量检查清单验证

核心原则

“模型对您的代码库的唯一了解就是您输入的令牌。”

CLAUDE.md是上下文传递的最高杠杆点。每条指令都在争夺有限的注意力。仅包含Claude无法推断且必须普遍应用的内容。

范围决策

用户级（~/.claude/CLAUDE.md）

适用于所有项目。仅包括：

  • 个人工作风格偏好
  • 关系动态（反驳、诚实、沟通）
  • 通用哲学（YAGNI、根本原因调试）
  • 主动性边界

切勿包括：

  • 项目特定命令（构建、测试、代码检查）
  • 技术栈详情
  • 因项目而异的风格规则
  • 不一定存在的工具/框架引用

项目级（.claude/CLAUDE.md）

适用于一个项目。使用WHAT/WHY/HOW框架：

WHAT（2-5行）

  • 项目目的一句话
  • 主要语言/框架
  • 关键目录及其用途

WHY（可选，2-3行）

  • 非显而易见的架构决策
  • 影响实现选择的约束

HOW（3-7行）

  • 基本命令：构建、测试、代码检查、运行
  • 任何项目特定工作流
  • 查找更多文档的位置

指令预算

LLM可靠遵循约150-200条指令。Claude Code的系统提示使用约50，留下有限预算。

范围 目标 最大值
用户级 ~30-40 60
项目级 ~50-80 120
组合 ~80-120 150

计数指令：每个可操作指令计为一条指令。

  • “切勿跳过测试” = 1条指令
  • “对新文件使用TypeScript” = 1条指令
  • 一个5项列表 = 5条指令

反模式：将Claude用作代码检查器

❌ 切勿依赖Claude进行风格执行：

  • 带有具体示例的命名约定
  • 注释格式化规则
  • 空格/缩进要求
  • 文件头要求（ABOUTME、版权）

✓ 使用确定性工具代替：

  • ESLint/Biome用于JavaScript/TypeScript风格
  • Black/Ruff用于Python格式化
  • 预提交钩子用于文件头
  • Claude Code钩子运行格式化器

为何重要：LLM不一致地遵循风格规则。代码检查器确定性失败；Claude静默且不可预测地失败。

例外：高层哲学是可接受的：

  • ✓ “名称应描述目的，而非实现细节”
  • ❌ “切勿使用像ZodValidator或MCPWrapper这样的名称”

渐进披露

对于复杂指导，不要将所有内容嵌入CLAUDE.md。

模式：引用外部文档，让Claude决定相关性。

## 参考文档
- 代码约定：参见`docs/conventions.md`
- API模式：参见`docs/api-design.md`
- 测试哲学：参见`docs/testing.md`

当任务涉及相关领域时阅读这些。

好处：

  • 保持CLAUDE.md专注
  • Claude仅在相关时阅读文档
  • 更容易维护分离的关注点

结构模板

用户级

[开场人设/哲学 - 1-2行]

## 协作方式
[关系动态、沟通偏好]

## 主动性
[何时继续 vs. 暂停确认]

## 开发哲学
[通用原则：YAGNI、调试方法等]

## 护栏
[版本控制、测试原则 - 保持简洁]

项目级

## 项目概述
[WHAT：目的、栈、结构]

## 开发
[HOW：构建、测试、代码检查命令]

## 架构
[WHY：关键决策、约束 - 如果非显而易见]

## 约定
[如果需要，简要指向详细文档]

质量检查清单

在最终确定前，验证：

通用适用性

  • [ ] 每条指令适用于每个会话（用户级）或项目中的每个任务（项目级）
  • [ ] 用户级配置中没有项目特定命令
  • [ ] 没有可能不存在的工具引用

指令经济性

  • [ ] 在指令预算内（计数它们）
  • [ ] 没有与Claude Code内置行为的冗余
  • [ ] 示例已修剪或移至参考文档

无LLM作为代码检查器

  • [ ] 无具体命名约定示例
  • [ ] 无注释格式化规则
  • [ ] 无文件头要求
  • [ ] 风格指导限于哲学，非具体细节

渐进披露

  • [ ] 复杂主题引用外部文档
  • [ ] 主文件在100行内（用户）或150行内（项目）
  • [ ] 示例在参考文件中，非内联

清晰度

  • [ ] 一致的标题层次结构
  • [ ] 无冲突指令
  • [ ] 可操作指令，非模糊指导

常见陷阱

  1. 过度具体化：包括所有偏好而非通用关键点
  2. 风格执行：Claude不一致遵循的详细命名/评论规则
  3. 过时命令：构建/测试命令与实际工具脱节
  4. 自动生成：使用/init而非手工制作
  5. 工具假设：引用不一定可用的MCP服务器或工具
  6. 冲突规则：“匹配周围风格” + “切勿使用X模式”
  7. 指令膨胀：每次挫折后添加规则而非修复根本原因

何时跳过此技能

  • 快速一次性项目（仅使用默认值）
  • 已有良好维护CLAUDE.md的项目
  • 当团队已有既定模式时

示例：前后对比

之前（有问题的用户级）：

## 命名
切勿使用像ZodValidator、MCPWrapper、JSONParser...这样的名称
[20多行具体示例]

## 注释
所有文件必须以ABOUTME:头开始...

之后（改进的用户级）：

## 代码风格
名称应描述目的，而非实现细节。
使用项目代码检查器进行格式化；不要依赖手动执行。

为何更好：哲学胜过具体细节。代码检查器确定性处理执行。

集成

编写CLAUDE.md后：

  • 用户级：符号链接到~/.claude/CLAUDE.md或直接放置
  • 项目级：提交到仓库根目录的.claude/CLAUDE.md
  • 验证：启动新的Claude Code会话并观察指令是否被遵循