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

```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 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**: [email protected]
- **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