---

name: write-claude-md locale: caveman-ultra source_locale: en source_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-05-03" 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

CLAUDE.md → AI assistants effective project-specific ctx.

Use When

• New project → AI used
• Improve AI behavior on existing
• Doc project conventions, workflows, constraints
• Integrate MCP servers|agent defs

In

• Required: Project type + tech stack
• Required: Key conventions + constraints
• Optional: MCP server configs
• Optional: Author + contributor info
• Optional: Security + confidentiality reqs

Do

Step 1: 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 in project root w/ min: project desc, quick start cmds, architecture, conventions.

If err: Unsure what to include → start w/ Quick Start only (3 most important: install, test, build). Expand incrementally.

Step 2: Tech-Specific Sections

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

Node.js/TS:

## 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: Tech-specific sections match actual stack — R pkg structure for R, Node.js details for web. Cmds + paths reference real layout.

If err: Unfamiliar stack → inspect package.json, DESCRIPTION, Cargo.toml, equivalent → ID tech + add corresponding section.

Step 3: MCP Server Info

## 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 MCP server: purpose, status (configured|available|not configured), cmd to add. No actual tokens|secrets.

If err: MCP not yet configured → doc as "Available" w/ setup instructions, not "Configured." Placeholder vals like your_token_here.

Step 4: Author Info

## Author Information

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

Got: Author section w/ name, email, ORCID (academic|research), GitHub. R pkgs match DESCRIPTION reqs.

If err: Author info sensitive|shouldn't be public → org name vs personal, or omit for internal-only.

Step 5: 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 never-commit files, placeholder conventions, confirms .gitignore covers sensitive.

If err: Unsure which sensitive → grep -rn "sk-\|ghp_\|password" . for exposed secrets. Real creds → .gitignore + mention here.

Step 6: Reference Skills + Guides

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

Got: Relevant skills + guides ref'd via @ paths → AI assistants get detailed procedures for common tasks.

If err: Ref'd skills|guides don't exist at paths → verify or remove. Broken @ refs no value, may confuse.

Step 7: Quality + Status

## 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 → current state, accurate nums for check, coverage, test count, doc status.

If err: Metrics not yet avail (new project) → placeholder "TBD" + update as matures. No fabricate.

Check

• CLAUDE.md in project root
• Quick start cmds accurate + work
• Architecture reflects actual structure
• No sensitive (tokens, passwords, private paths)
• MCP server configs current
• Ref'd files + paths exist

Traps

• Stale info: Update CLAUDE.md when project structure changes
• Too much detail: Concise. Link detailed guides vs duplicate
• Sensitive data: Never include actual tokens|creds. Placeholders.
• Conflicting instructions: CLAUDE.md doesn't contradict other config
• Missing from .Rbuildignore: R pkgs → add ^CLAUDE\\.md$ to .Rbuildignore

Examples

Pattern across successful projects:

1. putior (829 lines): Comprehensive CLAUDE.md w/ quality metrics, 20 accomplishments, MCP integration, dev workflow
2. Simple project (20 lines): Quick start + key conventions

Scale to match project complexity.

→

• create-r-package — CLAUDE.md as part of pkg setup
• configure-mcp-server — MCP config ref'd in CLAUDE.md
• security-audit-codebase — verify no secrets in CLAUDE.md