Write Claude Md

---
name: write-claude-md
description: >
  创建有效的 CLAUDE.md 文件，为 AI 编程助手提供项目专属指令。涵盖结构设计、
  常用章节、规范与禁忌模式，以及与 MCP 服务器和智能体定义的集成。适用于新项目
  引入 AI 助手、优化现有项目的 AI 行为、记录项目约定与限制，或将 MCP 服务器
  或智能体定义集成到项目工作流中。
locale: zh-CN
source_locale: en
source_commit: 6f65f316
translator: claude-opus-4-6
translation_date: 2026-03-16
license: MIT
allowed-tools: Read Write Edit Bash Grep Glob
metadata:
  author: Philipp Thoss
  version: "1.0"
  domain: general
  complexity: basic
  language: multi
  tags: claude-md, ai-assistant, project-config, documentation
---

# 编写 CLAUDE.md

创建 CLAUDE.md 文件，为 AI 助手提供有效的项目专属上下文。

## 适用场景

- 新项目中引入 AI 助手
- 改善 AI 助手在现有项目中的表现
- 记录项目约定、工作流程和限制条件
- 将 MCP 服务器或智能体定义集成到项目中

## 输入

- **必需**：项目类型和技术栈
- **必需**：关键约定和限制
- **可选**：MCP 服务器配置
- **可选**：作者和贡献者信息
- **可选**：安全与保密要求

## 步骤

### 第 1 步：创建基础 CLAUDE.md

将 `CLAUDE.md` 放在项目根目录：

````markdown
# Project Name

Brief description of what this project is and its purpose.

## Quick Start

Essential commands for working on this project:

```bash
# Install dependencies
npm install  # or renv::restore() for R

# Run tests
npm test     # or devtools::test() for R

# Build
npm run build  # or devtools::check() for R
```

## Architecture

Key architectural decisions and patterns used in this project.

## Conventions

- Always use descriptive variable names
- Follow [language-specific style guide]
- Write tests for all new functionality
````

**预期结果：** 项目根目录存在 `CLAUDE.md` 文件，至少包含项目描述、快速启动命令、架构概述和约定规范章节。

**失败处理：** 若不确定写什么，先从只包含三条最重要命令（安装、测试、构建）的 Quick Start 章节开始。随着项目发展可逐步扩充。

### 第 2 步：添加技术栈专属章节

**R 包项目**：

````markdown
## Development Workflow

```r
devtools::load_all()    # Load for development
devtools::document()    # Regenerate docs
devtools::test()        # Run tests
devtools::check()       # Full package check
```

## Package Structure

- `R/` - Source code (one function per file)
- `tests/testthat/` - Tests mirror R/ structure
- `vignettes/` - Long-form documentation
- `man/` - Generated by roxygen2 (do not edit manually)

## Critical Files (Do Not Delete)

- `.Rprofile` - Session configuration
- `.Renviron` - Environment variables (git-ignored)
- `renv.lock` - Locked dependencies
````

**Node.js/TypeScript 项目**：

```markdown
## Stack

- Next.js 15 with App Router
- TypeScript strict mode
- Tailwind CSS for styling
- Vercel for deployment

## Conventions

- Use `@/` import alias for src/ directory
- Server Components by default, `"use client"` only when needed
- API routes in `src/app/api/`
```

**预期结果：** 添加了与项目实际技术栈匹配的专属章节——R 包项目对应 R 包结构，Web 项目对应 Node.js 技术栈详情。命令和路径引用真实的项目布局。

**失败处理：** 若项目使用不熟悉的技术栈，查看 `package.json`、`DESCRIPTION`、`Cargo.toml` 或同类文件来识别技术栈，并添加对应章节。

### 第 3 步：添加 MCP 服务器信息

```markdown
## Available MCP Servers

### r-mcptools (R Integration)
- **Purpose**: Connect to R/RStudio sessions
- **Status**: Configured
- **Configuration**: `claude mcp add r-mcptools stdio "Rscript.exe" -- -e "mcptools::mcp_server()"`

### hf-mcp-server (Hugging Face)
- **Purpose**: AI/ML model and dataset access
- **Status**: Configured
- **Configuration**: `claude mcp add hf-mcp-server -e HF_TOKEN=token -- mcp-remote https://huggingface.co/mcp`
```

**预期结果：** 每个已配置的 MCP 服务器都有子章节，记录其用途、状态（已配置/可用/未配置）以及添加命令。不包含实际 token 或密钥。

**失败处理：** 若 MCP 服务器尚未配置，将其记录为"可用"并附上配置说明，而非"已配置"。凭据使用占位符，如 `your_token_here`。

### 第 4 步：添加作者信息

```markdown
## Author Information

### Standard Package Authorship
- **Name**: Author Name
- **Email**: author@example.com
- **ORCID**: 0000-0000-0000-0000
- **GitHub**: username
```

**预期结果：** 作者信息章节包含姓名、邮箱、ORCID（学术/研究项目）和 GitHub 用户名。R 包格式与 DESCRIPTION 文件要求一致。

**失败处理：** 若作者信息属于敏感信息或不宜公开，改用组织名称，或对仅供内部使用的项目省略该章节。

### 第 5 步：添加安全指南

```markdown
## Security & Confidentiality

- Never commit `.Renviron`, `.env`, or files containing tokens
- Use placeholder values in documentation: `YOUR_TOKEN_HERE`
- Environment variables for all secrets
- Git-ignored: `.Renviron`, `.env`, `credentials.json`
```

**预期结果：** 安全章节列出绝不能提交的文件、文档中占位符的约定规范，并确认 `.gitignore` 覆盖所有敏感文件。

**失败处理：** 若不确定哪些文件敏感，执行 `grep -rn "sk-\|ghp_\|password" .` 扫描泄露的密钥。包含真实凭据的文件应添加到 `.gitignore` 并在此章节中注明。

### 第 6 步：引用技能和指南

```markdown
## Development Best Practices References
@agent-almanac/skills/write-testthat-tests/SKILL.md
@agent-almanac/skills/submit-to-cran/SKILL.md
```

**预期结果：** 使用 `@` 路径引用相关技能和指南，使 AI 助手能访问项目常见任务的详细操作规程。

**失败处理：** 若引用的技能或指南在指定路径不存在，验证路径或删除该引用。失效的 `@` 引用没有任何价值，反而可能造成混淆。

### 第 7 步：添加质量和状态信息

```markdown
## Quality Status

- R CMD check: 0 errors, 0 warnings, 1 note
- Test coverage: 85%
- Tests: 200+ passing
- Vignettes: 3 (rated 9/10)
```

**预期结果：** 质量指标章节反映项目当前实际状态，包括检查结果、测试覆盖率、测试数量和文档状态的准确数字。

**失败处理：** 若指标尚无（新项目），添加标注"TBD"的占位条目，随项目成熟逐步更新。切勿编造数字。

## 验证清单

- [ ] CLAUDE.md 位于项目根目录
- [ ] 快速启动命令准确且可正常运行
- [ ] 架构章节反映实际项目结构
- [ ] 不含敏感信息（token、密码、私人路径）
- [ ] MCP 服务器配置为最新状态
- [ ] 引用的文件和路径均存在

## 常见问题

- **信息过期**：项目结构变更时更新 CLAUDE.md
- **内容过多**：保持简洁，通过链接指向详细指南，而非重复内容
- **敏感数据**：切勿包含真实 token 或凭据，使用占位符
- **指令冲突**：确保 CLAUDE.md 不与其他配置文件相矛盾
- **未添加到 `.Rbuildignore`**：R 包项目需在 `.Rbuildignore` 中添加 `^CLAUDE\\.md$`

## 示例

成功项目中观察到的模式：

1. **putior**（829 行）：包含质量指标、20 项成就、MCP 集成详情和开发工作流的完整 CLAUDE.md
2. **简单项目**（20 行）：仅包含快速启动命令和关键约定

根据项目复杂度调整 CLAUDE.md 的规模。

## 相关技能

- `create-r-package` - 作为包创建流程的一部分编写 CLAUDE.md
- `configure-mcp-server` - CLAUDE.md 中引用的 MCP 配置
- `security-audit-codebase` - 验证 CLAUDE.md 中无密钥泄露