---

name: write-claude-md locale: caveman source_locale: en source_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-05-03" description: > Create effective CLAUDE.md file giving project-specific instructions to AI coding assistants. Covers structure, common sections, do/don't patterns, integration with MCP servers and agent definitions. Use when starting new project where AI assistants will be used, improving AI behavior on existing project, documenting project conventions and constraints, or integrating MCP servers or agent definitions into 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 CLAUDE.md file giving AI assistants effective project-specific context.

When Use

• Starting new project where AI assistants will be used
• Improving AI assistant behavior on existing project
• Documenting project conventions, workflows, constraints
• Integrating MCP servers or agent definitions into 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

Steps

Step 1: Create Basic CLAUDE.md

Place CLAUDE.md in 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

Got: CLAUDE.md file exists in project root with at minimum project description, quick start commands, architecture overview, conventions section.

If err: Unsure what to include? Start with just Quick Start section containing three most important commands (install, test, build). File can be expanded incrementally as 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/`

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

If err: Project uses unfamiliar stack? Inspect package.json, DESCRIPTION, Cargo.toml, or equivalent to identify technology. Add 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`

Got: Each configured MCP server has subsection documenting purpose, status (configured/available/not configured), command used to add. No actual tokens or secrets included.

If err: MCP servers not yet configured? Document 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

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

If err: Author information sensitive or should not be public? Use organization name instead of personal details, or omit 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`

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

If err: Unsure which files 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

Got: Relevant skills and guides referenced using @ paths. Gives AI assistants access to detailed procedures for common tasks in project.

If err: Referenced skills or guides don't exist at specified paths? Verify paths or remove references. Broken @ references provide no value. May confuse 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)

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

If err: Metrics not yet available (new project)? Add placeholder entries with "TBD". Update them as project matures. Do not fabricate numbers.

Check

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

Pitfalls

• Stale information: Update CLAUDE.md when project structure changes
• Too much detail: Keep 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, development workflow
2. Simple project (20 lines): Just quick start commands and key conventions

Scale CLAUDE.md to match project complexity.

See Also

• 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