Write Claude Md

---
name: write-claude-md
locale: wenyan-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
---

# 書 CLAUDE.md

立 CLAUDE.md 予 AI 助手有效案境。

## 用

- 始用 AI 助手之新案→用
- 改現案 AI 為→用
- 錄案規、流、約→用
- 納 MCP 器或客定於案→用

## 入

- **必**：案型與技棧
- **必**：關規與約
- **可**：MCP 器配
- **可**：作者與貢者
- **可**：安與密要

## 行

### 一：建基 CLAUDE.md

置 `CLAUDE.md` 於案根：

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

得：`CLAUDE.md` 存於案根，至少含案述、速啟命、構覽、規節。

敗：不確何納→始於僅速啟節含三要命（裝、試、建）。案演中漸擴。

### 二：加技節

**R 包**：

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

得：技節合案實棧——R 案 R 包構、網案 Node.js 棧。命與路指真案布。

敗：案用未識棧→察 `package.json`、`DESCRIPTION`、`Cargo.toml` 或同等以辨技、加應節。

### 三：加 MCP 器信

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

得：每配 MCP 器有副節錄目、態（已配/可用/未配）、加之命。無真令或密。

敗：MCP 器未配→錄為「可用」附建指、非「已配」。憑證用佔位如 `your_token_here`。

### 四：加作者信

```markdown
## Author Information

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

得：作者信節含名、信箱、ORCID（學/研案）、GitHub 用名。R 包式合 DESCRIPTION 要。

敗：作者信敏或不公→用機構名代個、或內案略此節。

### 五：加安指

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

得：安節列永不可提之檔、文佔位規、確 `.gitignore` 蓋諸敏檔。

敗：不確何敏→`grep -rn "sk-\|ghp_\|password" .` 掃露密。任含真憑檔加 `.gitignore` 並述此節。

### 六：參技與指

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

得：關技與指以 `@` 路參，予 AI 助手案中常任之詳程。

敗：所參技或指於指路不存→驗路或移參。壞 `@` 參無價或惑助手。

### 七：加質與態信

```markdown
## Quality Status

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

得：質指節映案今態附察果、覆、計、文之準數。

敗：指未備（新案）→佔位「TBD」、案熟後更。勿造數。

## 驗

- [ ] CLAUDE.md 於案根
- [ ] 速啟命準且行
- [ ] 構節映實案構
- [ ] 無敏（令、密、私路）
- [ ] MCP 器配為今
- [ ] 所參檔與路存

## 忌

- **舊信**：案構變時更 CLAUDE.md
- **過詳**：簡。鏈詳指、勿復容
- **敏數**：永勿納真令或憑。用佔位
- **衝指**：確 CLAUDE.md 不違其他配檔
- **缺於 `.Rbuildignore`**：R 包加 `^CLAUDE\\.md$` 於 `.Rbuildignore`

## 例

成案中觀式：

1. **putior**（829 行）：詳 CLAUDE.md 含質指、20 成、MCP 整詳、開發流
2. **簡案**（20 行）：僅速啟命與關規

CLAUDE.md 度合案複。

## 參

- `create-r-package` - CLAUDE.md 為包設之部
- `configure-mcp-server` - CLAUDE.md 中參 MCP 配
- `security-audit-codebase` - 驗 CLAUDE.md 中無密