ai-feier/init-claude-md

init-claude-md Skill

概述

此 skill 用于在项目根目录生成 CLAUDE.md 入口文件和 .claude/ 最小骨架，建立面向 Claude Code 的项目指令体系。

核心设计原则：

• CLAUDE.md 是指令入口，不是百科全书：~100 行的指令文件，指向详细文档
• 指令分层：CLAUDE.md 定义核心指令，详细规范放在 .claude/rules/ 中
• 渐进式披露：从最小骨架开始，规则随项目复杂度按需创建
• 自动加载：Claude Code 自动读取 CLAUDE.md 和 .claude/rules/ 下的规则文件

使用方式

在项目中执行：

/init-claude-md

工作流程

1. 检查项目根目录是否已存在 CLAUDE.md
2. 如果存在 → 提示用户选择覆盖或跳过
3. 如果不存在 → 写入 CLAUDE.md 模板 + 创建最小 .claude/ 骨架
4. 显示成功消息，提示用户填写 [待填写] 占位内容

---

CLAUDE.md 模板

# CLAUDE.md

> 此文件是 Claude Code 在本项目的**指令入口**，保持精简（<100 行）。
> 原则：指令，不是百科全书。Claude Code 会自动读取此文件。

## 指令加载方式

Claude Code 自动加载以下内容：

CLAUDE.md # 项目级指令（本文件） .claude/rules/ # 规则文件目录 ├─ common/ # 通用规则（跨项目共享） └─ local/ # 本地规则（项目特定）

从 `.claude/rules/local/` 加载项目特定规则。

## 项目概述

[项目维护者在此描述项目目的和核心功能]

## 技术栈

[项目维护者在此列出主要技术栈]

## 项目结构

[项目维护者在此描述关键目录和模块]

## 构建命令

[项目维护者在此添加构建、测试、部署命令]

## 编码规范

[项目维护者在此添加技术栈相关规范]

## 规则治理

### 规则文件约定
- **规则目录**：`.claude/rules/local/` 存放项目特定规则
- **命名规范**：`{类别}.md`，如 `coding-style.md`、`testing.md`
- **规则粒度**：每个规则文件专注一个主题，不超过 100 行

### 渐进式规则策略
- 项目初期只维护 `CLAUDE.md`
- 需要新规则时：创建规则文件 → 在 CLAUDE.md 中引用
- 规则文件应按需创建，避免空文件占位

## 注意事项

[项目维护者在此添加项目特定的注意事项和约束]

---

初始生成的最小骨架

执行此 skill 时，只生成以下最小结构：

CLAUDE.md
.claude/
└── rules/
    └── local/
        └── .gitkeep

.claude/rules/local/.gitkeep：占位文件，确保目录被 git 跟踪。

---

渐进式扩展规范

新建规则文件时的步骤

1. 在 .claude/rules/local/ 目录创建规则文件
2. 使用下方模板编写规则
3. 在 CLAUDE.md 的"编码规范"章节中引用该规则

规则文件模板

# [规则名称]

> 一句话描述本规则的用途。

## 核心规则

1. **[规则1]**：[具体描述]
2. **[规则2]**：[具体描述]

## 示例

### 正确示例

[代码示例]

### 错误示例

[代码示例]

## 适用范围

[描述本规则适用的文件、目录或场景]

规则文件写作规则

• 专注单一主题：每个文件只描述一类规则
• 提供示例：正确/错误示例对比，便于理解
• 明确适用范围：说明规则适用的场景
• 保持精简：每个规则文件不超过 100 行

---

实现细节

写入顺序

1. 写入 CLAUDE.md
2. 创建 .claude/rules/local/ 目录
3. 写入 .claude/rules/local/.gitkeep（空文件）

文件保护

• 已存在的文件不覆盖（CLAUDE.md 除外，由用户决定）
• 创建完成后，输出需要人工填写的 [待填写] 位置列表

错误处理

• 捕获文件写入异常，显示友好错误消息
• 确保操作原子性：全部成功或全部回滚

---

与 AGENTS.md 的对比

| 特性 | CLAUDE.md | AGENTS.md | |------|-----------|-----------| | 目标工具 | Claude Code | AI Agent (通用) | | 文件位置 | 项目根目录 | 项目根目录 | | 配套目录 | .claude/rules/ | docs/ | | 主要内容 | 项目指令和规范 | 文档导航入口 | | 规则文件 | .claude/rules/local/*.md | docs/**/*.md | | 触发方式 | Claude Code 自动读取 | Agent 主动检索 | | 设计原则 | 指令分层、渐进披露 | 目录导航、渐进披露 |

---

示例输出

执行成功后显示：

✓ CLAUDE.md 已创建
✓ .claude/rules/local/ 目录已创建

请填写以下占位内容：
- 项目概述
- 技术栈
- 项目结构
- 构建命令
- 编码规范
- 注意事项

提示：CLAUDE.md 会被 Claude Code 自动读取，保持精简（<100 行）。
详细规则可放在 .claude/rules/local/ 目录下。