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:

# 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


**Expected:** A `CLAUDE.md` file exists in the project root with at minimum a project description, quick start commands, architecture overview, and conventions section.

**On failure:** If unsure what to include, start with just 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/`

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

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

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

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

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

## Author Information

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

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

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

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

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

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

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

Expected: Relevant skills and guides are referenced using @ paths, giving AI assistants access to detailed procedures for common tasks in the project.

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

## Quality Status

- R CMD check: 0 errors, 0 warnings, 1 note
- Test coverage: 85%
- Tests: 200+ passing
- Vignettes: 3 (rated 9/10)

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

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

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

putior (829 lines): Comprehensive CLAUDE.md with quality metrics, 20 accomplishments, MCP integration details, and development workflow
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

write-claude-md