Write Claude Md

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

````markdown
# 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**:

````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/TS**:

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

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

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

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

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

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

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