write-claude-md
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
- 最近更新
- 2026-05-19
- Stars
- ★ 10
- Forks
- 2
01 前言 Front Matter
- name
- write-claude-md
- locale
- caveman-lite
- license
- MIT
- metadata
- { "tags": "claude-md, ai-assistant, project-config, documentation", "author": "Philipp Thoss", "domain": "general", "version": "1.0", "language": "multi", "complexity": "basic" }
- translator
- Julius Brussee homage — caveman
- 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.
- allowed-tools
- Read Write Edit Bash Grep Glob
- source_commit
- 82c77053
- source_locale
- en
- translation_date
- 2026-05-03
03 SKILL.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:
# 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/ structurevignettes/- Long-form documentationman/- 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
## 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
## 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
## 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
## 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
## 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:
- 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
04 同仓库更多 Skills
zarr-python
Chunked N-D arrays for cloud storage. Compressed arrays, parallel I/O, S3/GCS integration, NumPy/Dask/Xarray compatible, for large-scale scientific computing pipelines.
youtube-downloader
Download and process YouTube content for research. Use when: downloading competitor videos for analysis; extracting audio for podcasts; getting transcripts for content repurposing; archiving webinars; research content curation
yc-pitch-deck
Create a compelling startup pitch deck that follows the structure proven to raise billions from top investors. Master the YC and Sequoia formats that get founders funded. Use when: **Fundraising** to create investor pitch decks; **YC application** to structure your narrative; **Demo Day prep** to craft your 2-minute pitch; **Angel investors** to communicate your opportunity; **Partnership pitches** to structure compelling asks
x-twitter-scraper
Use when the user needs X (Twitter) data or confirmation-gated X actions through Xquik: tweet search, user lookup, follower extraction, media download, monitoring, webhooks, MCP, SDKs, posting, likes, DMs, and profile updates. Requires a Xquik API key. Never ask for X login material.
write-vignette
Create R package vignettes using R Markdown or Quarto. Covers vignette setup, YAML configuration, code chunk options, building and testing, and CRAN requirements for vignettes. Use when adding a Getting Started tutorial, documenting complex workflows spanning multiple functions, creating domain-specific guides, or when CRAN submission requires user-facing documentation beyond function help pages.
write-validation-documentation
Write IQ/OQ/PQ validation documentation for computerized systems in regulated environments. Covers protocols, reports, test scripts, deviation handling, and approval workflows. Use when validating R or other software for regulated use, preparing for a regulatory audit, documenting qualification of computing environments, or creating and updating validation protocols and reports for new or re-qualified systems.