今回やること
この記事では、曖昧な CLAUDE.md を、AIが実行しやすい具体的な指示に改善します。
CLAUDE.mdは、AIに気持ちを伝える文章ではなく、作業ルールを具体的に渡すファイルです。
前提条件
CLAUDE.mdがある、またはこれから作る- プロジェクトのテスト・ビルドコマンドがわかる
- チームや個人の禁止事項を整理できる
Step 1: 悪い例を見る
次のような CLAUDE.md は曖昧です。
# ルール
- いい感じに実装する
- きれいなコードにする
- テストも適切にやる
- セキュリティに気をつける
方向性はわかりますが、AIが何をすればよいか判断しにくいです。
Step 2: 技術スタックを書く
## 技術スタック
- Runtime: Node.js
- Framework: Astro
- Language: TypeScript
- Package manager: npm
使っている技術を短く書きます。バージョンが重要なら明記します。
Step 3: コマンドを書く
## よく使うコマンド
- 開発サーバー: `npm run dev`
- ビルド: `npm run build`
- 型チェック: `npm run typecheck`
AIに「テストして」と言うより、実行すべきコマンドを明記します。
Step 4: 作業ルールを書く
## 作業ルール
- 変更前に関連ファイルを読む
- 大きな変更では先に計画を出す
- 既存の設計や命名に合わせる
- 関係ないリファクタを混ぜない
- 変更後に必要な検証コマンドを実行する
AIが迷いやすい点を先に書きます。
Step 5: 禁止事項を書く
## 禁止事項
- APIキー、秘密鍵、個人情報をログや記事に出さない
- 本番DBを直接変更しない
- `git reset --hard` のような破壊的操作を勝手に実行しない
- ユーザーの未コミット変更を勝手に戻さない
禁止事項は、事故防止のために明確にします。
Step 6: 出力形式を書く
レビューや報告の形式も指定できます。
## 報告形式
作業完了時は、次を短く報告する。
- 変更したファイル
- 実行した検証
- 残っている懸念
改善後の例
# Project Instructions
## 技術スタック
- Runtime: Node.js
- Framework: Astro
- Language: TypeScript
- Package manager: npm
## よく使うコマンド
- Build: `npm run build`
- Type check: `npm run typecheck`
## 作業ルール
- 変更前に関連ファイルを読む
- 大きな変更では先に計画を出す
- 既存の設計と命名に合わせる
- 関係ないリファクタを混ぜない
## 禁止事項
- 秘密情報を出力しない
- 破壊的なGit操作を勝手に実行しない
- 本番環境を直接変更しない
よくあるエラー
| エラー | よくある原因 | 確認すること |
|---|---|---|
| AIが守らない | 指示が曖昧 | 具体的な行動にする |
| コンテキストを圧迫する | 長く書きすぎ | 常時必要なものだけ残す |
| 古いコマンドを実行する | 更新されていない | package.jsonと照合する |
| 矛盾する | 複数の指示が競合 | 定期的に整理する |
まとめ
CLAUDE.md は、AIに毎回渡す作業ルールです。技術スタック、実行コマンド、作業ルール、禁止事項、報告形式を短く具体的に書きます。曖昧な表現を減らし、AIが確認可能な行動に落とし込むことが重要です。
参考リソース
← 一覧に戻るPR
PR
