Agent-almanac write-claude-md

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/zh-CN/skills/write-claude-md" ~/.claude/skills/pjt222-agent-almanac-write-claude-md-01abd6 && rm -rf "$T"

manifest: i18n/zh-CN/skills/write-claude-md/SKILL.md

source content

编写 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 包项目**：

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

## 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$
```

示例

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

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

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