CLAUDE.md を書けばClaude Codeの出力品質が上がる。それはわかっている。でも、白紙の状態から書き始めるのは面倒だし、何を書けばいいのか迷う。
この記事では、用途別に10個のCLAUDE.mdテンプレートを用意した。コピペしてプロジェクトルートに置くだけで使える。自分のプロジェクトに合わせて固有名詞やパスを書き換えれば、それだけで実用レベルのCLAUDE.mdが完成する。
1. Next.js / React Webアプリ
App Routerベースの典型的なNext.jsプロジェクト向け。Server ComponentsとClient Componentsの判断基準を明示することで、Claudeが適切なレンダリング戦略を選べるようになる。
# CLAUDE.md
## Project
Next.js 15 app with App Router. TypeScript strict mode.
## Architecture
- Default to React Server Components. Add "use client" only when the component needs browser APIs, useState, or useEffect.
- Data fetching: use server actions or route handlers. Do not use getServerSideProps.
- Styling: Tailwind CSS. No CSS modules or styled-components.
- State management: React context for global state, useState/useReducer for local.
## Code Style
- Named exports only (no default exports except pages/layouts).
- File naming: kebab-case for files, PascalCase for components.
- Imports: group by external > internal > types, separated by blank line.
## Testing
- Vitest + React Testing Library for unit tests.
- Tests go in __tests__/ next to the source file.
- Test behavior, not implementation details.
## Key Paths
- src/app/ — routes and layouts
- src/components/ — shared UI components
- src/lib/ — utility functions and API clients2. Python データ分析 / ML
JupyterやPandasを使うデータ分析プロジェクト向け。型ヒントとdocstringのルールを入れておくと、Claudeが生成するコードの可読性が格段に上がる。
# CLAUDE.md
## Project
Python 3.11+ data analysis / ML project.
## Environment
- Package manager: uv (pyproject.toml). Do not use pip directly.
- Virtual env: .venv/ in project root.
- Run scripts with: uv run python <script>
## Code Style
- Type hints on all function signatures.
- Docstrings: Google style.
- Max line length: 88 (Black formatter).
- Imports: isort with black profile.
## Data Conventions
- Raw data in data/raw/ (read-only, never modify).
- Processed data in data/processed/.
- Use pathlib.Path, not os.path.
- Pandas: prefer method chaining. Avoid inplace=True.
## ML
- Experiment tracking: MLflow.
- Models saved to models/ with timestamp in filename.
- Always set random_state/seed for reproducibility.
- Log all hyperparameters before training.
## Notebooks
- Notebooks are for exploration only. Production code goes in src/.
- Clear all outputs before committing notebooks.3. REST APIバックエンド（FastAPI）
FastAPIでAPIサーバーを構築するプロジェクト向け。エンドポイントの設計規約とエラーハンドリングの方針を統一できる。
# CLAUDE.md
## Project
FastAPI REST API backend. Python 3.12.
## Architecture
- Router-based structure: each domain has its own router in app/routers/.
- Business logic in app/services/. Routers are thin — they validate input and call services.
- Database: SQLAlchemy 2.0 async with PostgreSQL.
- Migrations: Alembic. Always generate migration after model changes.
## API Conventions
- RESTful URL naming: plural nouns, no verbs (e.g., /users, /users/{id}).
- Response format: always return Pydantic models, never raw dicts.
- Error responses: raise HTTPException with appropriate status codes.
- Pagination: offset/limit pattern with total count in response.
## Auth
- JWT Bearer tokens. Auth dependency in app/deps/auth.py.
- Never hardcode secrets. Use environment variables via pydantic-settings.
## Testing
- pytest + httpx AsyncClient.
- Test files mirror source structure in tests/.
- Use factory_boy for test data.4. モバイルアプリ（React Native）
Expoベースのモバイルアプリ向け。プラットフォーム固有のコードとナビゲーション構造の指示があると、Claudeの出力精度が上がる。
# CLAUDE.md
## Project
React Native app with Expo (SDK 52). TypeScript strict.
## Architecture
- File-based routing with expo-router.
- Screens in app/ directory. Shared components in components/.
- API calls: TanStack Query. Mutations use optimistic updates.
- Local storage: expo-secure-store for secrets, MMKV for general data.
## Platform Handling
- Prefer cross-platform solutions. Use Platform.select() only when truly necessary.
- Test on both iOS and Android. Note platform differences in comments.
- Use SafeAreaView from react-native-safe-area-context.
## Styling
- StyleSheet.create for all styles. No inline styles.
- Design tokens in constants/theme.ts. Use theme values, not hardcoded colors/sizes.
## Testing
- Jest + React Native Testing Library.
- Mock native modules in jest.setup.ts.
- Snapshot tests for layout-critical screens only.5. DevOps / IaC
TerraformやCI/CDパイプラインを扱うインフラプロジェクト向け。セキュリティとステート管理の規約を明示しておくことが特に重要になる。
# CLAUDE.md
## Project
Infrastructure as Code with Terraform. AWS environment.
## Terraform
- Version: 1.8+. Required providers pinned in versions.tf.
- State: S3 backend with DynamoDB locking. Never use local state.
- Modules in modules/. Environments in environments/{dev,staging,prod}/.
- Naming: {project}-{env}-{resource} (e.g., myapp-prod-rds).
## Security Rules (CRITICAL)
- Never hardcode secrets, credentials, or API keys in .tf files.
- Sensitive variables: mark with sensitive = true.
- IAM: least privilege. No wildcard (*) actions in production policies.
- Security groups: no 0.0.0.0/0 ingress except for ALB port 443.
## CI/CD
- GitHub Actions. Workflows in .github/workflows/.
- Plan on PR, apply on merge to main.
- Always run terraform fmt and terraform validate before committing.
## Documentation
- Each module has a README.md with inputs/outputs table.
- Update docs when changing variable definitions.6. OSSライブラリ
npm / PyPIなどに公開するライブラリ向け。公開APIの後方互換性とドキュメントの整合性が特に重要なプロジェクトタイプ。
# CLAUDE.md
## Project
Open-source TypeScript library published to npm.
## Public API
- All public exports go through src/index.ts. No deep imports.
- Breaking changes require major version bump. Document in CHANGELOG.md.
- Deprecate before removing: mark with @deprecated JSDoc tag and keep for one major version.
## Code Style
- ESM only. No CommonJS.
- Zero runtime dependencies is a goal. Justify any new dependency.
- Generics: prefer readable names (TInput, TOutput) over single letters.
## Testing
- Vitest. 90%+ coverage target.
- Test public API behavior, not internal implementation.
- Include edge cases and error cases in every test file.
## Build
- tsup for bundling. Output: ESM + CJS + .d.ts.
- Check bundle size in CI. Alert if >10% increase.
## Documentation
- TSDoc comments on all public functions and types.
- README examples must compile and pass tests (tested via examples/ directory).7. モノレポ（Turborepo）
複数のパッケージを管理するモノレポ向け。パッケージ間の依存関係と共有設定のルールを定義しておくことで、Claudeがモノレポ構造を正しく理解できる。
# CLAUDE.md
## Project
Turborepo monorepo. pnpm workspace.
## Structure
- apps/ — deployable applications (web, api, admin)
- packages/ — shared libraries (ui, utils, config-*)
- Each package has its own package.json and tsconfig.json.
## Dependency Rules
- Shared packages: import via @repo/{package-name}.
- Internal packages use "workspace:*" version.
- External dependencies: install in the package that uses them, not root.
- Do not create circular dependencies between packages.
## Workflow
- Run tasks from root: pnpm turbo build, pnpm turbo test.
- New package: copy an existing package and modify. Do not create from scratch.
- Config packages (config-eslint, config-typescript) must not contain runtime code.
## CI
- Turborepo remote caching enabled. Do not disable.
- PRs must pass: turbo build + turbo lint + turbo test (affected packages only).8. ドキュメントサイト（Astro）
技術ドキュメントサイト向け。コンテンツの書式ルールとコンポーネントの使い分けを明示する。
# CLAUDE.md
## Project
Documentation site built with Astro + Starlight.
## Content
- Docs in src/content/docs/. Markdown or MDX.
- Frontmatter required: title, description, sidebar.order.
- Use sentence case for headings.
- Code blocks: always specify language. Use title prop for filenames.
## Writing Rules
- Active voice. Present tense.
- One concept per page. If a page exceeds 800 words, split it.
- Link to related pages using relative Markdown links.
- Do not use "simply", "just", or "easy" — what is easy for one reader may not be for another.
## Components
- Use Starlight built-in components (Tabs, Card, Aside) before creating custom ones.
- Custom components in src/components/. Import in MDX only.
## Build
- astro check must pass (zero errors, zero warnings).
- Run astro build locally before pushing to verify no broken links.9. Chrome拡張機能
Manifest V3ベースのChrome拡張向け。Content Script、Background Service Worker、Popupの責務分離を明示しておくと、Claudeが正しいコンテキストでコードを書ける。
# CLAUDE.md
## Project
Chrome extension with Manifest V3. TypeScript + Vite.
## Architecture
- src/background/ — Service worker. No DOM access. Handle events and alarms.
- src/content/ — Content scripts injected into web pages. Minimal footprint.
- src/popup/ — Extension popup UI (React).
- src/options/ — Options page (React).
## Messaging
- Use chrome.runtime.sendMessage for popup <-> background.
- Use chrome.tabs.sendMessage for background <-> content script.
- Define all message types in src/types/messages.ts.
## Permissions
- Request minimum permissions. Justify each permission in a comment in manifest.json.
- Prefer activeTab over broad host_permissions.
- Never request <all_urls> unless absolutely required.
## Storage
- chrome.storage.local for extension data.
- Always define storage keys as constants in src/constants/storage-keys.ts.
## Build & Test
- Vite for bundling. Output to dist/.
- Load unpacked from dist/ for development.
- Test background logic with Vitest (mock chrome API).10. CLIツール
Node.jsやRustで書くコマンドラインツール向け。UXの一貫性とエラーメッセージの品質がCLIツールの使い勝手を大きく左右する。
# CLAUDE.md
## Project
CLI tool built with Node.js + Commander.js. TypeScript.
## CLI Design
- Subcommand pattern: mycli <command> [options].
- All commands defined in src/commands/. One file per command.
- Flags: use --long-form as primary. Short flags (-v) for frequently used options only.
- Required args: positional. Optional args: flags.
## Output
- stdout for primary output (data, results). stderr for logs and progress.
- Support --json flag for machine-readable output.
- Use chalk for colored terminal output. Respect NO_COLOR env variable.
- Errors: print clear message + suggested fix. Exit with non-zero code.
## UX
- Show help text when no args given (do not error).
- Long operations: show spinner with ora.
- Destructive operations: confirm with interactive prompt unless --yes flag is passed.
## Testing
- Vitest. Test commands by invoking programmatically, not via shell.
- Test both success and error paths.
- Snapshot test help text output to catch unintended changes.カスタマイズのコツ
テンプレートをコピペした後、以下の3点を自分のプロジェクトに合わせて調整するだけで実用レベルになる。
パスとツール名を実際のものに差し替える。 テンプレートのディレクトリ構造やパッケージマネージャが自分のプロジェクトと違う場合は、最初に直す。ここがズレているとClaude Codeが間違ったファイルを探しに行く。
「やってほしくないこと」を追記する。 過去にClaude Codeが生成したコードで修正したパターンがあれば、それを「Do not ~」の形で書き足す。禁止事項はClaude Codeが最も忠実に守るルールのひとつだ。
育てながら使う。 CLAUDE.mdは一度書いて終わりではない。開発中に「また同じ修正をしている」と感じたら、そのルールをCLAUDE.mdに追加する。プロジェクトが進むほど精度が上がっていくのが、CLAUDE.mdの本来の使い方だ。
全テンプレートは The Prompt Shelf のギャラリーでも確認できる。実際のOSSプロジェクトで使われているCLAUDE.mdも掲載しているので、さらに具体的な書き方の参考にしてほしい。