書 CLAUDE.md

立 CLAUDE.md 文，予 AI 助手以項目特脈絡。

用時

• 始新項目而將用 AI 助手
• 改善現項目中 AI 之行
• 錄項目之約、流、限
• 整合 MCP 服或臣定於項目

入

• 必要：項目類與技術棧
• 必要：要約與限
• 可選：MCP 服之設
• 可選：作者與貢者信
• 可選：安與密之要

法

第一步：立基 CLAUDE.md

置 CLAUDE.md 於項目根：

# 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` 文存於項目根，至少含項目述、速始命、架構覽、約段。

敗則：不確含何者，唯始 Quick Start 段含三要命（裝、試、建）。文可隨項目演而漸擴。

### 第二步：加技術特段

**為 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 包結構、web 項目用 Node.js 棧詳等。命與徑指實項目布。

敗則：項目用陌棧者，察 package.json、DESCRIPTION、Cargo.toml、或等以辨技術而加應段。

第三步：加 MCP 服信

## 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 服未設者，錄為「Available」附設囑而非「Configured」。憑值用 your_token_here 之代。

第四步：加作者信

## Author Information

### Standard Package Authorship
- **Name**: Author Name
- **Email**: [email protected]
- **ORCID**: 0000-0000-0000-0000
- **GitHub**: username

得：作者信段含名、郵、ORCID（學/研項目）、GitHub 名。R 包者，式合 DESCRIPTION 文之要。

敗則：作者信為密或不宜公者，用組名代個詳，或於內項目全略此段。

第五步：加安囑

## 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 並述於此段。

第六步：引術與指南

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

得：相關術與指南以 @ 徑引，予 AI 助手詳法應項目常任。

敗則：引之術或指南於指徑不存者，驗其徑或去其引。斷 @ 引無益且或亂助手。

第七步：加質與狀信

## 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 含質指、二十成就、MCP 整詳、開流
2. 簡項目（20 行）：唯速始命與要約

CLAUDE.md 之模配項目複度。

參

• create-r-package - CLAUDE.md 為包設之部
• configure-mcp-server - CLAUDE.md 中所引之 MCP 設
• security-audit-codebase - 驗 CLAUDE.md 無密