はじめに

こんにちは、弱者エンジニア代表、橋田至です。

https://x.com/dall_develop

皆さんはClaude Code使っていますか？

Claude Codeとは、ターミナル上で動作するエージェント型コーディングツールです。

私自身、Claude Codeがリリースされてから毎日使用していますが、毎日生成能力の高さに驚いております。

そんなClaude Codeの性能をさらに引き出すものが、CLAUDE.mdという仕組みになっています。

CLAUDE.mdとは？

CLAUDE.mdはメモリ機能になります。

CLAUDE.mdを作成することで、Claude はこのファイルを継続的に参照し、プロジェクト固有の知識として学習することができます。

CLAUDE.mdには、

アーキテクチャ設計
コーディング規則
共通ワークフロー

などを設定すると、生成されるコードがより精度の高いものになります。

ちなみに、.cluade/にmdファイルを作成することでも同じようなメモリ機能を使うことができます。

CLAUDE.mdのベストプラクティス

CLAUDE.mdには何でも書けば良いというものではありません。

記載事項が多くなりすぎると、記載した内容を無視してしまう可能性が高まってしまうので、なるべく必要なことのみを端的に書くことが大切です。

そう考えるとトークン量を抑えるためにも、本当は英語で記述した方が良いですが、私は英語がそこまで得意ではないということもあり、拡張性や保守性も考えて日本語で記述しています。

一応anthropic社が出している公式のベストプラクティスがあるので、こちらを参考にして作成したら良いかなと考えています。

一応、こんな感じでclaudeを起動して

/init

を実行することで、Claude Codeがプロジェクトの設定を読み込んでCLAUDE.mdを自動生成してくれます。

私のマイCLAUDE.md

では私がどのようなCLAUDE.mdを設定しているのか公開いたします。

その前に、私が開発しているアプリの技術スタックを記載しておきます。

技術スタック, 構成

フレームワーク,ライブラリ

Expo
React Native
tamagui
react-native-maps
Hono
Prisma
tanstack query
zod

クラウドサービス

Cloudflare Worker
Cloudflare D1

リンター,フォーマッター

eslint
prettier

パッケージ管理

pnpm

テスティングツール

vitest

コードブロックなどもそのまま表示するため、そのままをこちらに貼り付けます。

以下は私のCLAUDE.md全文そのままです
markdownをそのまま表示させるため、ここではあえてコードブロックで全体を囲うということは行なっておりません。

Gotoshisha プロジェクト - Claude Code ガイド

プロジェクト概要

Gotoshishaは、位置情報共有機能を持つ SNS アプリケーションです。React Native + Expo でクロスプラットフォーム対応のフロントエンド、Cloudflare Workers + Hono のサーバーレスバックエンドで構築されています。

アプリ名: Gotoshisha (expo-react-native-maps-demo)
プロジェクトタイプ: モノレポ構成のフルスタックアプリケーション
主要機能: 位置情報共有、投稿・コメント・いいね機能、Auth0 認証

技術スタック

フロントエンド

フレームワーク: React Native 0.79.2 + Expo 53.0.9
言語: TypeScript 5.1.3
ルーティング: Expo Router 5.0.7
マップ: React Native Maps 1.20.1
認証: Auth0 (react-native-auth0 4.6.0 + expo-auth-session 6.1.5)
プラットフォーム: iOS / Android
ディープリンクスキーム: gotoshisha://

バックエンド

フレームワーク: Hono 4.6.3
ランタイム: Cloudflare Workers
データベース: Cloudflare D1 (SQLite)
ORM: Prisma 5.22.0 with @prisma/adapter-d1
バリデーション: Zod 3.23.8
デプロイ: Wrangler 3.86.1

開発・テスト環境

パッケージマネージャー: pnpm
テストフレームワーク: Vitest 3.1.4
リンター: ESLint 9.15.0 + TypeScript ESLint
CI/CD: GitHub Actions

プロジェクト構造

gotoshisha/
├── app/                          # フロントエンド（React Native + Expo）
│   ├── components/               # 再利用可能なコンポーネント
│   │   └── LoginButton.tsx      # Auth0ログインボタン
│   ├── contexts/                 # React Context
│   │   ├── AuthContext.tsx      # ネイティブ認証コンテキスト
│   │   └── AuthContext.web.tsx  # Web認証コンテキスト
│   ├── routes/                   # 画面コンポーネント
│   │   ├── home.tsx             # ホーム画面
│   │   ├── login.tsx            # ログイン画面
│   │   └── map.tsx              # マップ画面
│   ├── config/                   # 設定ファイル
│   │   └── auth0.ts             # Auth0設定
│   └── utils/                    # ユーティリティ
│       └── auth/                 # 認証関連ユーティリティ
│           ├── storage.ts        # クロスプラットフォームストレージ
│           ├── auth0Api.ts       # Auth0 API
│           ├── useAuth0.ts       # Auth0カスタムフック
│           └── *.test.ts         # テストファイル
├── backend/                      # バックエンド（Cloudflare Workers）
│   ├── src/                      # バックエンドソースコード
│   │   ├── index.ts             # メインエントリーポイント
│   │   ├── lib/                 # ライブラリ
│   │   └── types/               # 型定義
│   ├── prisma/                   # データベース
│   │   ├── schema.prisma        # Prismaスキーマ
│   │   └── dev.db               # 開発用SQLiteファイル
│   ├── migrations/               # マイグレーションファイル
│   ├── scripts/                  # ユーティリティスクリプト
│   │   └── seed.ts              # データベースシード
│   └── wrangler.toml            # Cloudflare Workers設定
├── assets/                       # 静的アセット
├── docs/                         # プロジェクトドキュメント
└── src/                          # 共通ユーティリティ

データベース設計

モデル構成

User: ユーザー情報（email, name, avatar）
Post: 投稿（title, content, 位置情報、画像）
Like: いいね機能
Comment: コメント機能
Tag/PostTag: タグシステム

環境別 DB 設定

開発: gotoshisha-db
ステージング: gotoshisha-db-staging
本番: gotoshisha-db-prod

開発ワークフロー

セットアップ

# 1. 依存関係インストール
pnpm install

# 2. バックエンドセットアップ
cd backend
pnpm install
pnpm db:generate

# 3. 環境変数設定（Auth0設定が必要）
cp .env.example .env

開発サーバー起動

# フロントエンド（ルートディレクトリから）
pnpm start              # Expo開発サーバー
pnpm ios               # iOS実行
pnpm android           # Android実行
pnpm start:clear       # キャッシュクリア付き起動

# バックエンド（backendディレクトリから）
cd backend
pnpm dev               # Wrangler開発サーバー（ローカル）

テスト実行

# フロントエンド
pnpm test              # ウォッチモード
pnpm test:run          # 単発実行
pnpm test:ui           # UI付きテスト

# バックエンド
cd backend
pnpm test:run          # テスト実行

コード品質チェック

# リンティング
pnpm lint              # ESLint実行
pnpm lint:fix          # 自動修正

# 型チェック
pnpm type-check        # TypeScript型チェック

データベース操作

cd backend

# Prisma操作
pnpm db:generate       # クライアント生成
pnpm db:push           # スキーマ同期（開発用）
pnpm db:migrate        # マイグレーション（本番用）
pnpm db:studio         # Prisma Studio（GUI）
pnpm db:seed           # シードデータ投入

認証システム

Auth0 設定

プロバイダー: Auth0
プラットフォーム別対応:
- ネイティブ: react-native-auth0
- Web: expo-auth-session + expo-crypto
セッション管理: expo-secure-store（ネイティブ）/ localStorage（Web）

テストガイドライン

フロントエンド

ファイル配置: app/utils/auth/*.test.ts
テスト対象: ユーティリティ関数、カスタムフック、純粋関数
環境: jsdom + vitest
日本語: テスト説明とコメントは日本語で記述

バックエンド

ファイル配置: backend/src/**/*.test.ts
テスト対象: API エンドポイント、データベース操作、ビジネスロジック
環境: Node.js + vitest

テスト実行環境

グローバル設定: vitest.config.ts（両方）
セットアップ: vitest.setup.ts（フロントエンド）
モック: React Native、Expo、Cloudflare Workers

デプロイメント

フロントエンド

# Web
pnpm build

# ネイティブ（要Expo Application Services）
eas build --platform ios
eas build --platform android

バックエンド

cd backend

# 本番デプロイ
pnpm deploy --env production

# ステージングデプロイ
pnpm deploy --env staging

重要な設定ファイル

フロントエンド

app.json: Expo アプリ設定
babel.config.js: Babel 設定（静的クラスブロック対応）
metro.config.js: Metro bundler 設定（テストファイル除外）
tsconfig.json: TypeScript 設定

バックエンド

wrangler.toml: Cloudflare Workers 設定
prisma/schema.prisma: データベーススキーマ
vitest.config.ts: テスト設定

トラブルシューティング

よくある問題

認証エラー: Auth0 のコールバック URL 設定を確認
バンドルエラー: Metro 設定でテストファイルが除外されているか確認
型エラー: Prisma クライアント生成（pnpm db:generate）を実行
D1 エラー: wrangler.toml の database_id 設定を確認

デバッグコマンド

# キャッシュクリア
pnpm start:clear

# 依存関係再インストール
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Expo診断
npx expo doctor

CI/CD

GitHub Actions で以下を自動実行：

TypeScript 型チェック
ESLint リンティング
Vitest ユニットテスト
ビルド検証

実行タイミング：

main/developブランチへのプッシュ
main/developブランチへのプルリクエスト

コントリビューション

機能ブランチを作成
コード品質チェックを通す（lint + type-check + test）
日本語でのコメント・テスト記述
プルリクエスト作成

コード生成規約

言語: TypeScript

コメント

各ファイルの冒頭には日本語のコメントで仕様を記述する。

出力例

/**
 * 2点間のユークリッド距離を計算する
 **/
type Point = { x: number; y: number };
export function distance(a: Point, b: Point): number {
  return Math.sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2);
}

テスト

各機能に対しては必ずユニットテストを実装(テストは Vitest を使用。describe/it 構文を使用。describe は日本語で記述)
コードを追加で修正したとき、pnpm run test がパスすることを常に確認する。

function add(a: number, b: number) {
  return a + b;
}
test("1+2=3", () => {
  expect(add(1, 2)).toBe(3);
});

vitest で実装と同じファイルにユニットテストを書く。
出力例

export function distance(a: Point, b: Point): number {...}
if (import.meta.vitest) {
  const {test, expect} = import.meta.vitest;
  test("ユークリッド距離を計算する", () => {
    const result = distance({x: 0, y: 0}, {x: 3, y: 4});
    expect(distance(result)).toBe(5)
  });
}

コードスタイル: ESLint + Prettier で統一
ドキュメント: 関数やコンポーネントには JSDoc コメントを必ず追加
規約: ハードコードは絶対にしないでください。環境変数や設定ファイルを使用して、柔軟に対応できるようにします。

参考リンク

CLAUDE.mdの中身について解説

せっかくなので、記載した内容の意味について解説します。

プロジェクト概要
- このプロジェクトの目的について解説
モノレポ開発のため、技術スタックに関してはフロントエンド、バックエンドに分けて記載
プロジェクト構造
- できるだけpackage by featureのディレクトリ構造に寄せています。レイヤー単位でのディレクトリ構成ではなく、機能単位でのディレクトリ構成にすることを意識しています。
セットアップ
- こちらはREADME代わりに記載
リンティング
- 機能追加、修正をするたびにlintを実行してもらうために記載
テストガイドライン
- こちらは非常に重要な記載だと考えています。Vibe Codingを行っていく場合は、テスト駆動開発との相性がとてもよく、私はコードの追加、修正が行われるたびにテストを書いてもらっています。Claudeに指示を出して完了するたびに必ずテストを実行させ、テストが通るまで試行錯誤を行なってもらうことで確実に動くコードを生成させることができます。
その他テストの書き方やコード規約などに関しては、mizchiさんの記事を参考にさせていただきました。

.claude/settings.jsonについて

Claude Codeは、権限プロンプトをバイパスするclaude --dangerously-skip-permissionsというコマンドがあります。

こちらで起動すればいちいちコマンドの許可をする必要はないですが、私はghも入れているので、万が一勝手にmainブランチにpushされてしまったりしたら困るので、許可するコマンドと拒否するコマンドを設定したいと思い、許可なしで実行してほしいコマンドは./claude/settings.jsonに記載しています。

.claude/settings.local.json

{
  "permissions": {
    "allow": [
      "Bash(npx expo prebuild:*)",
      "Bash(npx expo run:ios:*)",
      "Bash(npx expo start:*)",
      "Bash(node:*)",
      "Bash(rm:*)",
      "Bash(mkdir:*)",
      "Bash(grep:*)",
      "Bash(pnpm add:*)",
      "Bash(pnpm why:*)",
      "Bash(ls:*)",
      "Bash(pnpm test:*)",
      "Bash(pnpm type-check)",
      "Bash(pnpm install:*)",
      "Bash(pnpm run lint:*)",
      "Bash(pnpm run type-check:*)",
      "Bash(find:*)",
      "Bash(cp:*)",
      "Bash(mv:*)",
      "Bash(pnpm run:*)",
      "Bash(pnpm db:generate:*)",
      "Bash(chmod:*)",
      "Bash(pnpm db:seed-shisha:*)",
      "Bash(pnpm db:studio:*)",
      "Bash(./run-backend-test.sh:*)",
      "Bash(bash:*)",
      "Bash(npx prisma generate:*)",
      "Bash(zsh:*)",
      "Bash(npx vitest run:*)",
      "Bash(/usr/local/bin/node:*)",
      "Bash(/bin/rm:*)",
      "Bash(rg:*)",
      "Bash(pnpm dev:*)",
      "Bash(eas build:*)"
    ],
    "deny": [
        "Bash(git:*)",
    ]
  }
}

allowに設定しているコマンドは許可なしで実行され、denyに設定しているコマンドは実行されなくなります。

最後に

CLAUDE.mdを作成することで、よりClaude Codeの性能を引き出せるため、作成することをお勧めします。

Claude CodeでVibe Codingを効率的に進めるコツは、テスト駆動開発にあると私は考えています。

うまくClaude Codeにテストの追加、修正を実行させることで、確実に動くアプリを円滑に開発していくことができます。

この記事において、補足や間違い等あればコメントで指摘していただけると助かります。

皆様の開発人生に幸あれ！

参考

Discussion