基本的な使い方とCLAUDE.md
重要キーワード (4 語)
CLAUDE.md
(プロジェクトメモリ)
— Claude Code が毎セッション自動で読む Markdown ファイル
@-mention
(アットメンション)
— @ で始まるファイル/ディレクトリ補完
TodoList
(タスクリスト)
— Claude Code が複雑な作業を分解して管理する内部リスト
Statusline
(ステータスライン)
— ターミナル下部に表示される現在状態のバー
基本的な使い方
$ cd my-project
$ claude
> このリポジトリのバグを調べて、原因を特定し、修正案を出して
Claude Code の典型的な思考プロセス:
1. ファイル一覧を見る (ls, Glob)
2. 重要なファイルを読む (CLAUDE.md, README, package.json/requirements.txt)
3. 仮説を立て、コードを追う (Grep, Read)
4. 計画を提示 (Plan Mode の場合は実行前に承認待ち)
5. 修正を適用 → 検証 (テスト実行・lint)
6. 完了報告
TodoList で大きなタスクを分解
複数ステップのタスクは Claude が自動で TODO を作って進捗管理します。
[✓] 1. 既存のミドルウェア構成を調査
[~] 2. Flask-Limiter を requirements.txt に追加
[ ] 3. ミドルウェアを app/__init__.py に組み込み
[ ] 4. ログイン経路にデコレータを適用
[ ] 5. テスト追加
[ ] 6. テスト実行
途中で割り込んで指示を変更することも可能 (Esc で停止 → 追加プロンプト)。
ファイル参照: @
> @src/server.py を要約して
> @src/ ディレクトリ全体の構造を説明して
> @docs/ARCHITECTURE.md @src/main.py の整合性をチェックして
@ でファイル/ディレクトリ補完。複数指定 OK。@ を使うと「今ここを見てほしい」が明確に伝わるので、雑にプロンプトを書くより精度が上がる。
画像の貼り付け
スクショを直接ペースト (Ctrl+V / Cmd+V / WSL は別途) すると 画像入力として認識。
実用例: - 🐛 UI バグ再現: 見た目のバグスクショ → 「この崩れを直して」 - 📊 図表理解: アーキテクチャ図 → 「これに沿って実装して」 - 📝 手書きメモ: ホワイトボード写真 → 「これをコード化して」
コマンド出力の取り込み: !
> ! npm test
> ! git log --oneline -20
! プレフィックスでシェル実行 → 出力をプロンプトに含める。
!は Claude にツールを使わせるのではなく、ユーザー側でコマンドを打つショートカット。CI ログを貼り付けたい時などに便利。
複数行入力 (Multi-line)
> \
複数行のプロンプトを書きたいとき
\ で行末を継続できます。
または トリプルバッククォートで囲んでもOK:
> ```
\
複数行モード
### 割り込み・停止
- `Esc`: 進行中のタスクを停止 (一番使う)
- `Ctrl+C` 1 回: 入力欄クリア
- `Ctrl+C` 2 回: セッション終了
- `/clear`: コンテキスト完全リセット
---
## CLAUDE.md (プロジェクトメモリ) — Claude Code を継続的に良くする要
リポジトリのルートに `CLAUDE.md` を置くと、**毎回 Claude のコンテキストに自動で読み込まれます**。
これが Claude Code を「使う度にチームの常識を学ぶ」存在にする最重要ファイル。
### 実例: 中規模 Flask プロジェクトの CLAUDE.md
```markdown
# my-flask-app
## このプロジェクトについて
- **言語**: Python 3.11
- **フレームワーク**: Flask 3.0 + SQLAlchemy 2.0
- **DB**: PostgreSQL (本番) / SQLite (テスト)
- **デプロイ**: Docker + GitHub Actions → AWS ECS
## ディレクトリ構成
- `app/` ... アプリ本体
- `routes/` ... API エンドポイント (Blueprint 分割)
- `models/` ... SQLAlchemy モデル
- `services/` ... ビジネスロジック (routes が薄く、ここが厚い)
- `tests/` ... pytest
- `migrations/` ... Alembic — **手動編集禁止**
## コード規約
- snake_case for functions/variables, PascalCase for classes
- 公開関数には型ヒント必須
- 例外を握りつぶさない (再 raise か `logger.exception` で記録)
- 環境変数は `app/config.py` で 1 箇所管理 (ベタ書き禁止)
## ローカル開発
\`\`\`bash
docker-compose up -d db
poetry install
poetry run flask db upgrade
poetry run flask run --debug
\`\`\`
## テスト・Lint
- `poetry run pytest -q`
- `poetry run ruff check .`
- `poetry run mypy app/`
- **PR を出す前に 3 つすべて緑にする**
## 触ってはいけないファイル
- `migrations/versions/*.py` (`alembic revision` で生成、手書き禁止)
- `.github/workflows/*.yml` (運用と相談してから)
- `app/legacy/` (廃止予定、変更しない)
## ドメイン用語
- **Tenant**: 法人顧客の単位
- **Workspace**: Tenant 内の作業空間
- **Invitation**: 未承諾の Workspace 招待
## 注意
- `git push --force` は禁止 (CI が拒否)
- 本番 DB への直接クエリ禁止 (代わりに `app/scripts/dryrun_*.py` を使用)
階層構造 (3 層)
| 場所 | スコープ | 用途 |
|---|---|---|
~/.claude/CLAUDE.md |
グローバル (全プロジェクト) | 個人の好み (口調・テスト言語など) |
<repo>/CLAUDE.md |
プロジェクト (チーム共有) | リポジトリ固有の規約 |
<repo>/<subdir>/CLAUDE.md |
サブディレクトリ | サブパッケージ固有 (例: frontend/CLAUDE.md) |
すべての階層が読み込まれ、近い階層が優先。モノレポでは frontend / backend に個別の CLAUDE.md を置くのが定番。
/init で雛形生成
/init
を実行すると、Claude が現在のリポジトリを解析して CLAUDE.md のドラフトを生成。 そのまま使わず、人手で「ドメイン特有の落とし穴」を必ず追記する のが鉄則。
CLAUDE.md に書くべきこと / 書かないこと
✅ 書く: - ビルド・テスト・lint・型チェック・dev サーバー起動コマンド - DB スキーマ・マイグレーション運用ルール - コード規約 (LLM が守れる粒度の具体例つきが理想) - 「触ってはいけない」ファイル/ディレクトリ - ドメイン用語の定義 - デプロイ手順の概要 (詳細は別ドキュメントに) - アーキテクチャ判断の前提 (例: なぜ Redis を使ってるか)
❌ 書かない: - 機密 (API キー・パスワード・本番 URL) - 一時的な状態 (作業中の TODO は別ファイルに) - 巨大なドキュメント (1000 行を超えるなら別ファイル + 参照に) - 個人名 (チームに変動があるとき特に)
よくあるアンチパターン
- 🚫 CLAUDE.md にコードをまるごとコピペ → 古くなって嘘になる。代わりにファイルパスで指定 (
@app/models/user.py を参照) - 🚫 「優しく書いてください」のような曖昧指示 → 具体的に (「コメントは関数あたり 1 行以内」)
- 🚫 TOC / 目次が肥大 → 検索しないので不要
統計を見る
/cost で現在のセッションのトークン消費・概算費用が見られます。
長時間セッションで context window を超えそうな時は要チェック (詳細は ch5-l5)。