はじめに
こんにちは、弱者エンジニア代表、橋田至です。
皆さんは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を起動して
を実行することで、Claude Codeがプロジェクトの設定を読み込んでCLAUDE.mdを自動生成してくれます。
私のマイCLAUDE.md
では私がどのようなCLAUDE.mdを設定しているのか公開いたします。
その前に、私が開発しているアプリの技術スタックを記載しておきます。
技術スタック, 構成
フレームワーク,ライブラリ
- Expo
- React Native
- tamagui
- react-native-maps
- Hono
- Prisma
- tanstack query
- zod
クラウドサービス
- Cloudflare Worker
- Cloudflare D1
リンター,フォーマッター
パッケージ管理
テスティングツール
コードブロックなどもそのまま表示するため、そのままをこちらに貼り付けます。
以下は私のCLAUDE.md全文そのままです
markdownをそのまま表示させるため、ここではあえてコードブロックで全体を囲うということは行なっておりません。
プロジェクト概要
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
開発ワークフロー
セットアップ
pnpm install
cd backend
pnpm install
pnpm db:generate
cp .env.example .env
開発サーバー起動
pnpm start
pnpm ios
pnpm android
pnpm start:clear
cd backend
pnpm dev
テスト実行
pnpm test
pnpm test:run
pnpm test:ui
cd backend
pnpm test:run
コード品質チェック
pnpm lint
pnpm lint:fix
pnpm type-check
データベース操作
cd backend
pnpm db:generate
pnpm db:push
pnpm db:migrate
pnpm db:studio
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
デプロイメント
フロントエンド
pnpm build
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
npx expo doctor
CI/CD
GitHub Actions で以下を自動実行：
- TypeScript 型チェック
- ESLint リンティング
- Vitest ユニットテスト
- ビルド検証
実行タイミング：
-
main/developブランチへのプッシュ -
main/developブランチへのプルリクエスト
コントリビューション
- 機能ブランチを作成
- コード品質チェックを通す（lint + type-check + test）
- 日本語でのコメント・テスト記述
- プルリクエスト作成
コード生成規約
コメント
- 各ファイルの冒頭には日本語のコメントで仕様を記述する。
出力例
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にテストの追加、修正を実行させることで、確実に動くアプリを円滑に開発していくことができます。
この記事において、補足や間違い等あればコメントで指摘していただけると助かります。
皆様の開発人生に幸あれ！
参考
Views: 0
