---
name: write-claude-md
description: >
  AIコーディングアシスタントにプロジェクト固有の指示を提供する効果的な
  CLAUDE.mdファイルを作成する。構造、一般的なセクション、すべきこと・
  すべきでないパターン、MCPサーバーとエージェント定義との統合をカバー
  する。AIアシスタントを使用する新しいプロジェクトを始める場合、既存の
  プロジェクトでのAIの動作を改善する場合、プロジェクトの規約と制約を
  文書化する場合、またはMCPサーバーやエージェント定義をプロジェクト
  ワークフローに統合する場合に使用する。
locale: ja
source_locale: en
source_commit: 6f65f316
translator: claude-opus-4-6
translation_date: 2026-03-16
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の作成

AIアシスタントに効果的なプロジェクト固有のコンテキストを提供するCLAUDE.mdファイルを作成する。

## 使用タイミング

- AIアシスタントを使用する新しいプロジェクトを始める場合
- 既存のプロジェクトでのAIアシスタントの動作を改善する場合
- プロジェクトの規約、ワークフロー、制約を文書化する場合
- MCPサーバーやエージェント定義をプロジェクトに統合する場合

## 入力

- **必須**: プロジェクトタイプと技術スタック
- **必須**: 主要な規約と制約
- **任意**: MCPサーバーの設定
- **任意**: 著者と貢献者の情報
- **任意**: セキュリティと機密性の要件

## 手順

### ステップ1: 基本的な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` ファイルが存在し、最低限プロジェクトの説明、クイックスタートコマンド、アーキテクチャの概要、規約セクションが含まれている。

**失敗時：** 何を含めるか不明な場合は、最も重要な3つのコマンド（インストール、テスト、ビルド）を含むクイックスタートセクションだけで始める。プロジェクトの進化に合わせてファイルを段階的に拡張できる。

### ステップ2: 技術固有のセクションを追加する

**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`、または同等のファイルを調べて技術を特定し、対応するセクションを追加する。

### ステップ3: 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サーバーがまだ設定されていない場合、「Configured」ではなく「Available」として文書化し、セットアップ手順を記載する。認証情報には `your_token_here` などのプレースホルダー値を使用する。

### ステップ4: 著者情報を追加する

```markdown
## Author Information

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

**期待結果：** 著者情報セクションに名前、メールアドレス、ORCID（学術・研究プロジェクト）、GitHubユーザー名が含まれている。Rパッケージの場合、形式がDESCRIPTIONファイルの要件と一致している。

**失敗時：** 著者情報が機密または公開すべきでない場合、個人情報の代わりに組織名を使用するか、内部専用プロジェクトではセクション全体を省略する。

### ステップ5: セキュリティガイドラインを追加する

```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` に追加し、このセクションに記載する。

### ステップ6: スキルとガイドを参照する

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

**期待結果：** 関連するスキルとガイドが `@` パスを使用して参照されており、AIアシスタントがプロジェクトの一般的なタスクの詳細な手順にアクセスできる。

**失敗時：** 参照されているスキルやガイドが指定されたパスに存在しない場合、パスを確認するか参照を削除する。壊れた `@` 参照は価値を提供せず、アシスタントを混乱させる可能性がある。

### ステップ7: 品質とステータス情報を追加する

```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パッケージの場合、`.Rbuildignore` に `^CLAUDE\\.md$` を追加する

## 例

成功しているプロジェクトで観察されたパターン:

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に秘密情報がないか確認