claude-md-writer

CLAUDE.md 编写器

一项用于创建和优化 CLAUDE.md 文件的技能，遵循 Anthropic 官方最佳实践。

黄金法则

对于每一行，都要问：“删除这行会导致 Claude 犯错吗？” 如果不会，就删掉。臃肿的 CLAUDE.md 会导致 Claude 忽略指令。

“将 CLAUDE.md 视为代码库中‘未写明的知识’”

快速工具

• /init - 根据项目结构生成初始 CLAUDE.md
• # 键 - 在会话期间动态添加指令

@import 语法

CLAUDE.md 可以导入其他文件：

See @README.md for overview and @package.json for commands.
Git workflow: @docs/git-instructions.md

参考文档

示例和验证清单请参阅：

• references/good-example.md - 结构良好的 CLAUDE.md 示例
• references/bad-example.md - 应避免的常见反模式
• references/checklist.md - 质量验证清单
• references/dead-weight-audit.md - 冗余内容审查（5 项精简指令的标准）

应包含与排除的内容

应包含	应排除
Claude 无法自行推断的 Bash 命令	Claude 阅读代码即可了解的内容
与默认设置不同的代码风格规则	通用语言规范
测试说明和首选测试运行器	详细的 API 文档（改为添加链接）
仓库规范（分支命名、PR）	经常变化的信息
项目特有的架构决策	长篇解释或教程
开发环境的特殊情况（环境变量）	逐文件说明
常见陷阱或不明显的行为	不言自明的做法

CLAUDE.md 与技能的区别

CLAUDE.md	技能
始终适用的广泛规则	仅在某些情况下相关的领域知识
代码风格和工作流	可重复使用的专用工作流
仓库规范	随上下文变化的信息
每次会话都会加载	按需加载

内容筛选

在向 CLAUDE.md 添加内容前，先评估：

如果内容是……	那么……
适用于所有任务的规则	添加到 CLAUDE.md
特定领域知识	建议创建技能
仅偶尔适用的工作流	建议创建技能
经常变化的信息	不要添加，改为链接到文档

如果用户想添加有条件的信息（“处理 X 时……”“对于 Y 类型的任务……”），建议单独创建一个技能。

使用模式

调用方式	行为
/claude-md-writer	完整流程：分析项目、编写或改进 CLAUDE.md
/claude-md-writer actualiza con la sesion	从当前会话中提取相关信息并添加到 CLAUDE.md
/claude-md-writer agrega regla: [descripcion]	按正确格式添加特定规则
/claude-md-writer revisa y optimiza	审核现有 CLAUDE.md，删除冗余内容并加强重点
/claude-md-writer audita	冗余内容审查：根据当前配置应用 5 项标准（参见 references/dead-weight-audit.md）
/claude-md-writer convierte a skill	找出适合转为技能的内容并将其提取出来

流程

步骤 1：分析项目

识别技术栈、项目结构和现有文档。

步骤 2：应用三个维度

维度	要回答的问题
WHAT	这是个什么项目？使用什么技术栈？结构如何？
WHY	项目为何存在？解决什么问题？
HOW	如何参与开发？有哪些命令和工作流？

第 3 步：遵循最佳实践编写

长度：控制在 200 行以内（理想长度约为 100 行）

结构（按顺序）：

1. 仓库概述（1 段）
2. 存在的意义（目的、用户）
3. 快速入门和命令（bash 命令及其说明）
4. 架构概述（关键模式）
5. 关键开发规则（突出强调）
6. 参考资料（指向详细文档的链接）

关键规则的强调方式：

- **CRITICAL**: [Never violate this]
- **IMPORTANT**: [Always do this]

渐进式披露：

• 使用文件引用，而不是代码片段
• 详细主题链接到外部文档
• 让 CLAUDE.md 专注于通用说明

第 4 步：使用检查清单验证

定稿前，按照 references/checklist.md 中的检查清单逐项检查。

模板

# CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

## Repository Overview

[One paragraph: what this project is, tech stack, main purpose]

## Why This Exists

[What problem it solves, who uses it, business context]

## Quick Start & Commands

\`\`\`bash
npm ci        # Install dependencies
npm start     # Start dev server
npm test      # Run tests
npm run build # Production build
\`\`\`

## Architecture Overview

[Key patterns, folder structure, main concepts - keep brief]

## Key Development Rules

- **CRITICAL**: [Most important rule that must never be violated]
- **IMPORTANT**: [Second most important rule]

## References

- `/docs/` - Detailed documentation
- `README.md` - Project readme

冗余内容审查

当用户要求审查其配置时，针对每条规则，应用 references/dead-weight-audit.md 中的 5 条标准：

1. 默认行为？ — Claude 无需说明就会做到
2. 冲突？ — 与配置中的其他规则相矛盾
3. 冗余？ — 已由其他规则或流程涵盖
4. 临时补丁？ — 为修复某个特定的不佳输出而添加
5. 含糊？ — 每次的解读都不同

预期输出：

• 要删除的内容及理由，每项一行
• 文件之间发现的冲突清单
• 删除冗余内容后的 CLAUDE.md 版本

审查后的流程： 删除 → 测试 3 项典型任务 → 仅重新添加导致问题的内容。

应避免的反模式

反模式	不足之处	推荐做法
代码片段	容易过时，浪费 token	使用 file:line 引用
样式规则	对确定性任务而言，LLM 效率低	配置代码检查工具
大杂烩	削弱指令的效用	控制在 200 行以内
没有强调	关键规则与次要规则同等重要	使用 CRITICAL/IMPORTANT
自动生成	忽略项目细节	手动编写
领域知识	增加每次会话的负担	移到技能中