---

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 放在项目根目录：

# 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 包项目：

## 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 项目：

## 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 服务器信息

## 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 步：添加作者信息

## Author Information

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

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

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

第 5 步：添加安全指南

## 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 步：引用技能和指南

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

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

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

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

## 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 中无密钥泄露