2026/3/26 5 min read

Claude Code の公式ベストプラクティスを試している

Claude Code を日常的に使っている。公式のベストプラクティスを読んで、自分の業務（dbt、BigQuery、Terraform あたり）で片っ端から試してみた。効いたものとそうでもなかったものがある。

skills が一番よかった

~/.claude/skills/{name}/SKILL.md にファイルを置くと、Claude Code がスキルとして認識する。description へキーワードを書いておけば、該当する話題が出たとき勝手に読み込まれる。

自分は dbt の命名規則、CI/CD のデプロイフロー、レイヤリング方針、BigQuery の運用ルールあたりを書いた。「dbt モデル追加したい」と言うだけで自社の手順が入った状態で返ってくる。毎回説明しなくていい。

公式のスキルオーサリングガイドに「Claude が元々知らないことだけ書け」とある。「BigQuery はカラム型ストアで…」みたいなことは書いても意味がない。ディレクトリ構成、自動生成スクリプトの存在、やってはいけないこと。そういう自社固有の話だけ書く。description は三人称の英語で、MUST activate when: をつけると発火しやすくなる。

CLAUDE.md は短いほうがいい

公式の表現を借りると「各行について『これを削除したら Claude が間違えるか？』と問う。No なら削除」。最初は何でも書いていたが、長くなるとルールが無視される。

今はこう分けている。

置き場所	中身
CLAUDE.md	コミット規約、レビュー方針、言語設定
skills	dbt パターン、BigQuery 運用、CI/CD フロー
hooks	lint、フォーマット

hooks は CLAUDE.md と違って無視されない。SQL を編集したら sqlfmt、.tf を編集したら terraform fmt が走るようにした。公式の言い方だと「CLAUDE.md は advisory、hooks は deterministic」。

/clear は地味に大事

dbt の作業をした後にそのまま Terraform の質問をすると、さっきのコンテキストが邪魔になる。公式が「kitchen sink session」と呼んでいるやつ。タスクが変わったら /clear。

検証手段を渡す

dbt モデルを書いたら make dbt-test、SQL なら sqlfluff lint。「作ったら検証しろ」を skills や CLAUDE.md に書いておけば勝手にやってくれる。hooks も併用すれば編集のたびに lint が走る。

サブエージェントは調査に使う

調査でファイルを大量に読むとメインのコンテキストが埋まる。サブエージェントに投げるとサマリーだけ返ってくる。リポジトリが複数ある場合は並列で調査できるので便利。skills に context: fork と agent: Explore を書いておくと、スラッシュコマンドでサブエージェントに投げられる。

そこそこ使えるもの

Plan Mode — 複数ファイルにまたがる変更のときだけ。単一ファイルの修正には要らない。

CLI ツール — gh、gcloud、bq を使わせると Web コンソールを開く回数が減る。BigQuery MCP サーバーも入れるとテーブルスキーマの確認がターミナルで済む。

エージェント定義 — ~/.claude/agents/*.md に7つ作った。ただしスキルと比べると毎回手動でスポーンしないといけないので、日常的に使うのはスキルのほう。エージェントは並列調査か大きめの委任に限る。

セッション名 — /rename でつけておくと claude --resume で探しやすい。

プラグイン — pyright-lsp で Python の型チェック、gopls-lsp で Go の補完。dbt プラグインはドキュメント参照とコマンド実行をサポートしてくれる。

あまり効かなかったもの

auto memory — 自動でメモリを書き出してくれる機能。データ基盤の構成は変更が多くて、古いメモリが残っていると変な前提で進むことがあった。今は手動で管理している。

エージェントの大量作成 — 7つ作って頻繁に使うのは2-3個。スキルのほうが勝手に発火するから楽。