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

- Skill: `pjt222/write-claude-md-7` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pjt222/write-claude-md-7`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/write-claude-md-7/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: pjt222 (https://skillmd.com/u/pjt222)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pjt222/write-claude-md-7

---


# 撰寫 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` 文件,至少含專案描述、快速開始命令、架構概述與慣例段。

**失敗時：** 若不確含何,先寫含三個最重要命令之 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 套件結構、網頁專案用 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 伺服器尚未配置,記錄為「Available」並附設置指示,而非「Configured」。任何憑證用 `your_token_here` 之占位值。

### 步驟四：加作者資訊

```markdown
## Author Information

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

**預期：** 作者資訊段含姓名、email、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 行）：含品質指標、20 項成就、MCP 整合細節與開發工作流之全面 CLAUDE.md
2. **簡單專案**（20 行）：僅含快速開始命令與關鍵慣例

依專案複雜度調整 CLAUDE.md 之規模。

## 相關技能

- `create-r-package` — CLAUDE.md 作為套件設置之一部分
- `configure-mcp-server` — CLAUDE.md 中引用之 MCP 配置
- `security-audit-codebase` — 驗證 CLAUDE.md 中無機密