Claude Codeに保守しやすいコードを書いてもらうための事前準備やガードレール

Claude Codeを使いはじめて、いろいろ試してるけど、
なかなかいい感じのコードを書いてくれないな〜と思い、
いろいろ調べてみたときの備忘録(*´ω｀*)

えいや、でコード生成してくれるけど、
あとで自分で変更したり、保守したりするときに大変なので、
自分がいいとおもう感じに生成してほしかったりする。。

ドキュメントとサンプルコード大事...

事前準備やガードレール一覧

このあたりを用意しておくと、よさそうな感覚

プロジェクトに関するドキュメント(メモリ/コンテキスト: CLAUDE.md)
lint/format/自動テストの設定＆実行コマンド
サンプルコード or テンプレートリポジトリ

このあたりは任意、あるとより安心・便利

ドキュメント大事・カードレール大事

なにも情報・制約ないと、自由に書けてしまう

新しいメンバが入ってきたときと一緒で、
このプロジェクトのルールや方針をちゃんと教えないといけない
(可能な限り解空間を絞る/解空間の定義をLLMに与える)

使ってるFW/開発方針/ディレクトリ構成などなど

たくさんのコードを書いてくれてるけど、チェックが大変なので、
チェックとかも自動化しておくと便利、ないとつらい

format/lint/testなどなど

ドキュメント読んだだけだと、どう書けばいいかわからないので、
マネしやすいよう、サンプルコードや参考となる実例があるといい

「〇〇をしてないけない」みたいな禁止が苦手っぽいので、
「APIキーをコミットしない」、「mainに直プッシュしない」とかは、
git-secretsなど使い、プロジェクト外で制限するほうが安心

1. メモリ/コンテキスト(`CLAUDE.md`)

Claude CodeだとCLAUDE.md。公式ガイドやこの記事が参考になる

公式ガイドに書いてあるのはこのあたり

よく使うbashコマンド
コアのファイルやユーティリティ関数
コーディング規約
テスト手順
リポジトリ関連のルール (例: ブランチの命名規則、merge or rebaseどっちをつかうか)
開発環境のセットアップ (例: npm iなど)
プロジェクト特有の予期しない動作や警告(例: エラーメッセージやデバッグ方法など)
ワークフロー(例: 必ずlintやtestが通ること、など)

公式ガイドの小さな例はこんな感じ

# Bash commands
- npm run build: プロジェクトのビルド
- npm run typecheck: タイプチェッカーの実行

# Code style
- CommonJS (require) ではなく、ES モジュール (import/export) 構文を使用する
- 可能な場合はインポートを分解する（例：import { foo } from 'bar'）

# Workflow
- 一連のコード変更が終わったら必ず型チェックを行ってください
- パフォーマンスのために、テストスイート全体ではなく、単一のテストを実行することを優先します。

このあたりも整理し、記載しておくとよい

アーキテクチャ: DDD/Clean Architecture/MVVM/MVP/MVC...
フォルダ構成: Layer-first/Feature-first/package by feature/Feature-Sliced Design...
技術スタック: 利用するライブラリ＋そのURL。FW/多言語/テストライブラリ...
テスト方針: UT/IT/E2Eの観点や方針、手順などなど...
共通基盤周り: 認証や例外処理などのコードの場所や使い方などなど...

強調レベルの使い分け

ref: Claude Code の CLAUDE.mdは設定した方がいい - じゃあ、おうちで学べる

特定のキーワードをつけておくと、強調できるようになるっぽい

# NEVER（絶対禁止）：絶対にやってほしくないこと
NEVER: パスワードやAPIキーをハードコーディングしない

# YOU MUST（必須事項）：必ずやってほしいこと
YOU MUST: すべての公開APIにドキュメントを記載

# IMPORTANT（重要事項）：考慮してほしいこと。判断はAIに委ねる
IMPORTANT: パフォーマンスへの影響を考慮

`CLAUDE.md`の階層化

monorepoなど、複数の言語やアプリを利用している場合、
いろんな情報が混ざってしまう。。

ので、子ディレクトリにもCLAUDE.mdに配置して、
コンテキストを階層化しておくとよいかんじ

./
  web/
    CLAUDE.md ... Web用
  server/
    CLAUDE.md ... サーバ用
  CLAUDE.md   ... 全体用

こうしておくと、

rootで起動し、webを操作時、web/CLAUDE.mdを見てくれる(子の参照)
webで起動すると、./CLAUDE.md(親の参照)

という感じで、必要なときに参照してくれるっぽい

`CLAUDE.md`を育てる

一度で完璧なのを作るのは大変だし、
都度ルールが変わっていくので、
適宜見直したり、追加したりして育てていくのが前提

レビューして指摘したあとに、
二度と間違えないように、 @CLAUDE.md に追記して
とか頼むと、よしなに追記してくれる

2. lint/format/自動テスト

こんな感じで、全部コマンド一つで実行できるようにしておくと便利

npm run build        # プロジェクトのビルド
npm run lint         # lintの実行
npm run format       # formatの実行
npm run check-format # formatのチェック
npm run test         # テストの実行

Flutterとかだと、markdownのフォーマットとかを考えたりとメンドなので、
Makefileやシェルスクリプトを用意して、対象を全部実行できるようにしておくとよい

このあたりの設定自体も、Claude Codeにお願いしちゃってもよいかも

これらを整備しておいて、lint/format/testが通ることを
ワークフローなどに指定しておけば、いい感じのコードになるまでがんばってくれる

手動でコード書くときとコマンド実行したときとで差があるとこまるので、
VSCode上のフォーマットと一致するようにsettings.jsonを設定しておく

lintやformatルールも育てる

CLAUDE.mdと同様に、lintやformatルールも育てる対象

レビューで指摘したりしたら、ルール自体を追加して、
何度も指摘しなくていいようにできる

ルールの作成自体も、Claude Codeにお願いしちゃえばよい

3. サンプルコード or テンプレートリポジトリ

真似できるサンプルがあると、出てくるコードがいい感じになるので、
なるべく用意しておくと便利

画面/UIコンポーネント/Repositoryなどなど

markdownにサンプルコードを書いてもいいけど、
実例があるとよりよいので、1機能作っておくとかもいいかも

lint/test/formatの設定も何度もやるのは大変だったり、
使い回せるので、テンプレートリポジトリを用意しておくと立ち上がりが早くなる

アーキテクチャ/フォルダ構成/例外ハンドリング周りは、
いろいろあるので、整えておいてあると、捗る

その他のガードレール

CLAUDMD.mdなどに禁止事項として書いておくだけだと守られないこともあるので、
LLMがそもそも操作できないようにしておく仕組み集

git-secrets
- パスワードやその他の機密情報をGitリポジトリへのコミットを防いでくれるツール
- インストールしておくと、git commit時にリジェクトされる
Git Hooks(pre-commits) / Husky
- コミット時点でチェック/制限
- mainへの直プッシュや規約にあってないコミットメッセージを防げる
- 参考: githookで直push/直commitを禁止にするなど - くらげになりたい。
DevContainer: コンテナ上で動作させ、隔離する
- コンテナ上で動かすので、ファイルアクセスが制限できる
- 参考: VSCodeのDevContainer入門＆Claude Codeのリファレンス実装を見てみる - くらげになりたい。

おまけに、並列でタスクを実行させたいときに便利なやつ

Git Worktree
- フォルダ単位でブランチ。並列動作させるときに便利
- .evnなどを.gitignoreにはいっているものをコピペしないと動かなくなるので注意

おまけのおまけ

Claud DesktopでCLAUD.mdを作ってもらったときのサンプル

ultrathink: flutter+melos+fvmを使ったスマホアプリを考えています
どんなCLAUD.mdを作成するとよいですか。最高のパフォーマンスを引き出すフルサンプルを教えて

Claude Opus 4で生成してもらったCLAUD.mdのサンプル(Flutter+Melos+FVM)

以上!! ちょっとは仲良くなれてきた気がする...(*´ω｀*)