mcpField
C
claude-md-authoring

claude-md-authoring

github.com/ratacatAgent 工作流5850 次安装37 周前更新
代码仓库

关于 claude-md-authoring

用于编写精简实用的 CLAUDE.md 指令的 Skill，支持用户级和项目级配置。它指导 Claude Code 用户组织上下文、控制指令数量并检查常见问题。

主要功能

  1. 01区分用户级与项目级范围
  2. 02WHAT/WHY/HOW 结构
  3. 03指令预算建议
  4. 04代码检查与风格规则建议
  5. 05质量核对清单

适用场景

  1. 01起草项目 CLAUDE.md
  2. 02区分个人与项目指引
  3. 03检查指令是否冗余

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ratacat/claude-skills --skill claude-md-authoring

安装后在 Claude Code 中输入/claude-md-authoring确认已加载。

详细介绍

CLAUDE.md 编写

快速入门

  1. 确定范围：用户级（~/.claude/）还是项目级（.claude/）？
  2. 应用 WHAT/WHY/HOW 框架（仅限项目级）
  3. 将指令控制在预算内：用户级约 50 条，项目级约 100 条
  4. 绝不把 Claude 当作代码检查工具：风格规则应交由工具处理，而不是写在 CLAUDE.md 中
  5. 定稿前使用质量检查清单进行验证

核心原则

“模型对你的代码库唯一了解的内容，就是你输入给它的 token。”

CLAUDE.md 是传递上下文最具杠杆效应的途径。每条指令都会占用有限的注意力。只写入 Claude 无法推断且必须始终遵循的内容。

范围选择

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

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

  • 个人工作风格偏好
  • 协作关系偏好（提出异议、诚实沟通、交流方式）
  • 通用理念（YAGNI、根因调试）
  • 主动性的边界

绝不包括：

  • 项目专属命令（构建、测试、代码检查）
  • 技术栈详情
  • 因项目而异的风格规则
  • 并非所有项目都会使用的工具或框架
项目级（.claude/CLAUDE.md）

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

WHAT（2-5 行）

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

WHY（可选，2-3 行）

  • 不易理解的架构决策
  • 会影响实现选择的约束

HOW（3-7 行）

  • 必要命令：构建、测试、代码检查、运行
  • 项目专属工作流
  • 更多文档的位置

指令预算

大模型通常能可靠遵循约 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
  • 使用 Pre-commit 钩子处理文件头
  • 使用 Claude Code Hooks 运行格式化工具

为何重要：大模型遵循风格规则的表现不一致。代码检查工具会确定性地报错；Claude 则可能悄无声息地以不可预测的方式出错。

例外：高层理念可以接受：

  • ✓ “名称应描述用途，而非实现方式”
  • ❌ “绝不使用 ZodValidator 或 MCPWrapper 这样的名称”

渐进式披露

对于复杂的指导，不要把所有内容都写进 CLAUDE.md。

模式：引用外部文档，让 Claude 自行判断相关性。

## Reference Documentation
- Code conventions: See `docs/conventions.md`
- API patterns: See `docs/api-design.md`
- Testing philosophy: See `docs/testing.md`

Read these when the task involves the relevant area.

好处：

  • 让 CLAUDE.md 保持简洁聚焦
  • Claude 只在相关时才阅读文档
  • 更容易分别维护不同关注点

结构模板

用户级
[Opening persona/philosophy - 1-2 lines]

## Working Together
[Relationship dynamics, communication preferences]

## Proactiveness
[When to proceed vs. pause for confirmation]

## Development Philosophy
[Universal principles: YAGNI, debugging approach, etc.]

## Guardrails
[Version control, testing principles - kept brief]
项目级
## Project Overview
[WHAT: Purpose, stack, structure]

## Development
[HOW: Build, test, lint commands]

## Architecture
[WHY: Key decisions, constraints - if non-obvious]

## Conventions
[Brief pointers to detailed docs if needed]

质量检查清单

定稿前，请确认：

普遍适用性
  • 每条指令都适用于每次会话（用户级），或项目中的每项任务（项目级）
  • 用户级配置中没有项目专属命令
  • 没有可能不存在的工具引用
指令精简
  • 未超出指令预算（请计数）
  • 没有重复 Claude Code 的内置行为
  • 精简示例，或将其移至参考文档
不把大模型当作代码检查工具
  • 没有具体的命名约定示例
  • 没有注释格式规则
  • 没有文件头要求
  • 风格指导仅限理念，不涉及具体规范
渐进式披露
  • 复杂主题引用外部文档
  • 主文件少于 100 行（用户级）或 150 行（项目级）
  • 示例放在参考文件中，而非内联
清晰度
  • 标题层级一致
  • 没有相互冲突的指令
  • 指令可执行，而非含糊的指导

常见陷阱

  1. 过度详述：罗列每项偏好，而非只保留普遍关键的偏好
  2. 强制风格：详细规定命名和注释规则，但 Claude 执行得并不一致
  3. 过时命令：构建／测试命令与实际工具链不符
  4. 自动生成：使用 /init，而不是手动编写
  5. 工具假设：引用并非始终可用的 MCP 服务或工具
  6. 规则冲突：「遵循周围风格」与「绝不使用 X 模式」
  7. 指令膨胀：每次遇到问题就添加规则，而不是解决根本原因

何时跳过此技能

  • 临时小项目（使用默认设置即可）
  • 已有维护良好的 CLAUDE.md 的项目
  • 团队已经形成既定模式时

示例：改进前后

改进前（有问题的用户级配置）：

## Naming
NEVER use names like ZodValidator, MCPWrapper, JSONParser...
[20 more lines of specific examples]

## Comments
All files MUST start with ABOUTME: header...

改进后（经过改进的用户级配置）：

## Code Style
Names should describe purpose, not implementation details.
Use project linters for formatting; don't rely on manual enforcement.

为何更好：强调理念，而非具体细节。由 Linter 确定性地执行规则。

集成

编写 CLAUDE.md 后：

  • 用户级：创建符号链接指向 ~/.claude/CLAUDE.md，或直接放置在该路径
  • 项目级：提交到仓库根目录下的 .claude/CLAUDE.md
  • 验证：启动新的 Claude Code 会话，观察是否遵循这些指令

评论

支持 Markdown