write-claude-md

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

```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:** A `CLAUDE.md` file exists in the project root with at minimum a project description, quick start commands, architecture overview, and conventions section.

**If fail:** If unsure what to include, start with 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**:

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

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

**Got:** 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.

**If fail:** 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

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

**If fail:** 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

```markdown
## 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), and GitHub username. For R packages, the format matches DESCRIPTION file requirements.

**If fail:** 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

```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 files that must never be committed, placeholder conventions for documentation, and confirms that `.gitignore` covers all sensitive files.

**If fail:** 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

```markdown
## 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 are referenced using `@` paths, giving AI assistants access to detailed procedures for common tasks in the project.

**If fail:** 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

```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 section reflects the current state of the project with accurate numbers for check results, test coverage, test count, and documentation status.

**If fail:** 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

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