⚡

CLAUDE.md创作Skill claude-md-authoring

用于创建和审查CLAUDE.md配置文件，优化Claude Code的使用，包括指令预算管理、WHAT/WHY/HOW框架应用，避免反模式如使用Claude作为linter，支持渐进式披露。关键词：CLAUDE.md, 配置文件, Claude Code, 指令预算, 渐进式披露, 反模式

AI应用 0 次安装 0 次浏览 更新于 3/9/2026

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

CLAUDE.md 创作

快速入门

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

核心原则

“模型对你的代码库唯一知道的就是你输入的令牌。”

CLAUDE.md是上下文转移的最高杠杆点。每个指令都竞争有限的注意力。只包括Claude无法推断且必须普遍应用的内容。

范围决策

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

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

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

切勿包括：

  • 项目特定命令（构建、测试、lint）
  • 技术栈细节
  • 因项目而异的样式规则
  • 不一定存在的工具/框架引用

项目级（.claude/CLAUDE.md）

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

WHAT（2-5行）

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

WHY（可选，2-3行）

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

HOW（3-7行）

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

指令预算

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

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

计算指令: 每个可操作指令计为一条指令。

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

反模式：Claude作为Linter

❌ 切勿依赖Claude进行样式强制：

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

✓ 使用确定性工具代替：

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

为什么重要: LLM不一致地遵循样式规则。Linter确定性地失败；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：构建、测试、lint命令]

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

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

质量检查清单

最终确定前，验证：

普遍适用性

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

指令经济性

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

无LLM作为Linter

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

渐进式披露

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

清晰度

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

常见陷阱

  1. 过度指定: 包括每个偏好而非普遍关键的内容
  2. 样式强制: 详细命名/注释规则，Claude不一致地遵循
  3. 过时命令: 构建/测试命令与实际工具脱节
  4. 自动生成: 使用/init而非手工制作
  5. 工具假设: 引用MCP服务器或不一定可用的工具
  6. 冲突规则: “匹配周围样式” + “切勿使用X模式”
  7. 指令膨胀: 每次挫折后添加规则而非修复根本原因

何时跳过此技能

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

示例：前后对比

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

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

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

之后（改进的用户级）:

## 代码样式
名称应描述目的，而非实现细节。
使用项目linter进行格式化；不要依赖手动强制。

为什么更好: 哲学胜过具体细节。Linter确定性地处理强制。

集成

创作CLAUDE.md后：

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