---

name: write-claude-md description: > Create an effective CLAUDE.md file that provides project-specific instructions to AI coding assistants. Covers structure, common sections, do/don't patterns, and integration with MCP servers and agent definitions. Use when starting a new project where AI assistants will be used, improving AI behavior on an existing project, documenting project conventions and constraints, or integrating MCP servers or agent definitions into a project workflow. 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

Write CLAUDE.md

Create a CLAUDE.md file that gives AI assistants effective project-specific context.

When to Use

• Starting a new project where AI assistants will be used
• Improving AI assistant behavior on an existing project
• Documenting project conventions, workflows, and constraints
• Integrating MCP servers or agent definitions into a project

Inputs

• Required: Project type and technology stack
• Required: Key conventions and constraints
• Optional: MCP server configurations
• Optional: Author and contributor information
• Optional: Security and confidentiality requirements

Procedure

Step 1: Create Basic CLAUDE.md

Place CLAUDE.md in the project root:

# 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

Expected: A CLAUDE.md file exists in the project root with at minimum a project description, quick start commands, architecture overview, and conventions section.

On failure: If unsure what to include, start with just the Quick Start section containing the three most important commands (install, test, build). The file can be expanded incrementally as the project evolves.

Step 2: Add Technology-Specific Sections

For R packages:

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

For 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/`

Expected: Technology-specific sections are added that match the project's actual stack — R package structure for R projects, Node.js stack details for web projects, etc. Commands and paths reference the real project layout.

On failure: If the project uses an unfamiliar stack, inspect package.json, DESCRIPTION, Cargo.toml, or equivalent to identify the technology and add the corresponding section.

Step 3: Add MCP Server Information

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

Expected: Each configured MCP server has a subsection documenting its purpose, status (configured/available/not configured), and the command used to add it. No actual tokens or secrets are included.

On failure: If MCP servers are not yet configured, document them as "Available" with setup instructions rather than "Configured." Use placeholder values like your_token_here for any credentials.

Step 4: Add Author Information

## Author Information

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

Expected: Author information section includes name, email, ORCID (for academic/research projects), and GitHub username. For R packages, the format matches DESCRIPTION file requirements.

On failure: If author information is sensitive or should not be public, use the organization name instead of personal details, or omit the section entirely for internal-only projects.

Step 5: Add Security Guidelines

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

Expected: Security section lists files that must never be committed, placeholder conventions for documentation, and confirms that .gitignore covers all sensitive files.

On failure: If unsure which files are sensitive, run grep -rn "sk-\|ghp_\|password" . to scan for exposed secrets. Any file containing real credentials should be added to .gitignore and mentioned in this section.

Step 6: Reference Skills and Guides

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

Expected: Relevant skills and guides are referenced using @ paths, giving AI assistants access to detailed procedures for common tasks in the project.

On failure: If the referenced skills or guides do not exist at the specified paths, verify the paths or remove the references. Broken @ references provide no value and may confuse the assistant.

Step 7: Add Quality and Status Information

## Quality Status

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

Expected: Quality metrics section reflects the current state of the project with accurate numbers for check results, test coverage, test count, and documentation status.

On failure: If metrics are not yet available (new project), add placeholder entries with "TBD" and update them as the project matures. Do not fabricate numbers.

Validation

• CLAUDE.md is in project root
• Quick start commands are accurate and work
• Architecture section reflects actual project structure
• No sensitive information (tokens, passwords, private paths)
• MCP server configurations are current
• Referenced files and paths exist

Common Pitfalls

• Stale information: Update CLAUDE.md when project structure changes
• Too much detail: Keep it concise. Link to detailed guides rather than duplicating content.
• Sensitive data: Never include actual tokens or credentials. Use placeholders.
• Conflicting instructions: Ensure CLAUDE.md doesn't contradict other config files
• Missing from .Rbuildignore: For R packages, add ^CLAUDE\\.md$ to .Rbuildignore

Examples

Pattern observed across successful projects:

1. putior (829 lines): Comprehensive CLAUDE.md with quality metrics, 20 accomplishments, MCP integration details, and development workflow
2. Simple project (20 lines): Just quick start commands and key conventions

Scale the CLAUDE.md to match project complexity.

Related Skills

• create-r-package - CLAUDE.md as part of package setup
• configure-mcp-server - MCP configuration referenced in CLAUDE.md
• security-audit-codebase - verify no secrets in CLAUDE.md