CLAUDE_CODE_PERFORCE_MODE（クロードコード・パーフォースモード）

Perforceでバージョン管理しているチームでClaude Codeを使う人向け

Perforceで管理されたプロジェクトでClaude Codeにファイルを直してもらうと、たまに変な事故が起きます。Claude は「直しました」と返すのに、Perforce 側にはその変更がまるで載っていない、という現象です。原因は Perforce が同期したファイルを読み取り専用のまま置く仕組みにあります。CLAUDE_CODE_PERFORCE_MODE は、この事故をブロックして気づかせるための起動時設定です。

値に 1 を入れておくと、Claude が読み取り専用のファイルを書き換えようとした瞬間に処理を止めて、「先に p4 edit しなさい」とヒントを返してくれます。Git でやっているチームには関係ない、Perforce 専用の安全装置です。

噛み砕くと

新しい職場で、共有の棚にある書類を思い浮かべてください。Perforce の世界では、棚から取り出した書類は最初みんな「閲覧専用・書き込み禁止」のシールが貼られています。中身を読むのは自由ですが、勝手にボールペンで書き込むのはルール違反です。

書き込みたいときは、まず受付に「この書類、今から私が編集します」と申告する。これが p4 edit です。申告して初めてシールが剥がれ、書き換えてよい状態になります。

Claude Code は放っておくとこのシールを無視して書き込もうとします。CLAUDE_CODE_PERFORCE_MODE を 1 にしておくと、Claude が「シール貼ったままの書類だ。先に受付へ」と気づいて手を止めてくれる。それだけの設定です。地味だけど効きます。

大事な前提：これはPerforceを使っているチーム専用

この設定は Perforce で同期したファイルが読み取り専用になる、という Perforce 固有のクセに対応するためのものです。Git でファイルを管理しているなら、ファイルは普通に書き換えられる状態なので、この設定は何の意味も持ちません。

つまり「Claude の暴走を防ぐ汎用ストッパー」ではなく、Perforce を使うゲーム開発や映像制作の現場に刺さる、ピンポイントな安全装置だと思ってください。

「Perforceで管理しているゲーム開発」を例に、実際の手順を見る

ここからは、Perforce でソースを管理しているゲーム開発のプロジェクトで、Claude にC++のファイルを1つ直してもらう流れを追います。設定する前と後で何が変わるかを見ていきます。

ステップ1: まず公式の説明を確認する

公式の変更履歴（changelog）には、v2.1.98 で追加された設定としてこう書かれています。

Added CLAUDE_CODE_PERFORCE_MODE env var: when set, Edit/Write/NotebookEdit fail on read-only files with a p4 edit hint instead of silently overwriting them

訳すと「CLAUDE_CODE_PERFORCE_MODE を設定すると、Edit / Write / NotebookEdit の各ツールが読み取り専用ファイルに対して失敗し、黙って上書きする代わりに p4 edit のヒントを返す」。短い1行に挙動が全部詰まっています。

ステップ2: 設定する前の挙動を確認する

まだ何も設定していない状態を考えます。Perforce から同期したばかりの PlayerController.cpp は読み取り専用です。この状態で Claude に「この当たり判定のバグを直して」と頼みます。

あなた: PlayerController.cpp の当たり判定のバグを直して

Claude は Edit ツールでファイルを書き換え、「直しました」と返してきます。ところがこの変更、Perforce には1ミリも反映されていません。ローカルのファイルだけが書き換わって、チームの誰とも共有されない宙ぶらりんの状態になります。これが一番こわいパターンです。

ステップ3: 設定を入れる

そこで CLAUDE_CODE_PERFORCE_MODE に 1 を入れます。入れ方は2つあります。1つはターミナルで毎回宣言する方法。

$ export CLAUDE_CODE_PERFORCE_MODE=1

もう1つは、設定ファイル settings.json の env の中に書いて常に効かせる方法です。チームで使うならこちらが楽です。

{
  "env": {
    "CLAUDE_CODE_PERFORCE_MODE": "1"
  }
}

ステップ4: 設定後にもう一度頼む

設定を入れた状態で、また PlayerController.cpp の修正を頼みます。ファイルはまだ読み取り専用のままです。

あなた: PlayerController.cpp の当たり判定のバグを直して

今度は Claude が Edit ツールを使った瞬間に処理が失敗します。そして「このファイルは読み取り専用です。先に p4 edit してください」というヒントが返ってきます。ローカルだけ書き換わる事故が、ここで止まります。

ステップ5: 初心者がやりがちな勘違い

ここで多いのが「設定を入れたんだから、Claude が p4 edit も自動でやってくれるんでしょ？」という期待です。これは外れます。この設定がやるのは「止めて教える」ところまで。p4 edit を打つのは自分の役目です。

$ p4 edit PlayerController.cpp

このコマンドで読み取り専用が外れ、Perforce にも「このファイルを編集中」として登録されます。あくまで自動化ではなく、見落としを防ぐためのストッパーだと割り切ってください。

ステップ6: 編集して提出まで進める

p4 edit を打ったあと、もう一度 Claude に同じ修正を頼めば、今度は普通に書き換わります。あとは中身を確認して Perforce に提出すれば、変更がちゃんとチームに共有されます。最初に止めてもらえたおかげで「直したのに反映されてない」という落とし穴を踏まずに済みます。

つまり CLAUDE_CODE_PERFORCE_MODE は何をしてくれるのか

• やってくれる: 読み取り専用ファイルへの書き換えを止めて、「先に p4 edit せよ」と教える。ローカルだけ書き換わる事故を防ぐ
• やってくれない: p4 edit の自動実行。止めるだけで、編集可能にする操作は自分でやる
• 意味が薄い場面: Git でファイルを管理しているプロジェクト。ファイルが読み取り専用にならないので、この設定はそもそも発動しない

使いどころ3シナリオ（具体題材で再現）

シナリオ1: Perforce管理のゲームプロジェクトに新メンバーが入ったとき

Unreal Engine 製のゲームを Perforce で管理しているチームに、新しい人が加わったとします。その人が Perforce のルールに慣れる前に Claude にコードを直させると、p4 edit を忘れたままローカルだけ書き換わる事故を起こしがちです。settings.json にこの設定を入れておけば、忘れていても Claude が手前で止めて教えてくれる。新人教育の保険として効きます。

シナリオ2: 大量のファイルをまとめてClaudeに直させるとき

たとえば命名規則を変えるために、50個のソースファイルを一気に Claude に修正させる場面。手作業だと「どれを p4 edit したか」を見失います。この設定があれば、p4 edit していないファイルだけがエラーで止まるので、漏れていたファイルがその場で炙り出されます。全部書き換わってから「あのファイル提出できてない」と気づくより、はるかに安全です。

シナリオ3: 映像制作でアセットの設定ファイルを触るとき

ゲームに限らず、映像やアニメの制作現場でも Perforce はよく使われます。シーンの設定ファイルを Claude に調整させるようなとき、読み取り専用のまま書き換える事故は同じように起きます。この設定を入れておけば、媒体がコードでなくても同じストッパーが働きます。

初心者が踏みやすい落とし穴

• Gitユーザーには無関係。これは Perforce 専用の設定です。Git で管理しているならファイルは読み取り専用にならないので、設定しても何も起きません。
• p4 edit を自動でやってくれると思い込む。この設定は止めて教えるだけ。編集できる状態にするには自分で p4 edit を打つ必要があります。
• Perforce以外の理由で読み取り専用になったファイルも止まる。判定の根拠は「ファイルに書き込み許可があるか」だけです。Perforce と関係なく読み取り専用にしてあるファイルでも、同じようにブロックされます。
• 値を 1 以外にしても期待通りに動くとは限らない。公式は「設定したとき」に有効になると書いています。素直に 1 を入れるのが無難です。
• ターミナルでの export は画面を閉じると消える。常に効かせたいなら settings.json の env に書く方を選んでください。
• v2.1.98より前のバージョンでは存在しない。この設定は v2.1.98 で追加されました。古いバージョンを使っていると設定しても無視されます。
• 止まったのを「バグ」だと勘違いして設定を外す。エラーで止まるのは正常動作です。外す前に p4 edit を試してください。

書き方

settings.json の env に "CLAUDE_CODE_PERFORCE_MODE": "1" を書く（またはターミナルで export CLAUDE_CODE_PERFORCE_MODE=1）

やってみるとこうなる

入力

{
  "env": {
    "CLAUDE_CODE_PERFORCE_MODE": "1"
  }
}

出力例

読み取り専用のままのファイルをClaudeが書き換えようとすると、Edit/Write/NotebookEditが失敗し「このファイルは読み取り専用です。先に p4 edit してください」というヒントが返る。p4 edit でファイルを編集用に開いてから頼み直すと、今度は普通に書き換わる。

関連項目

• settings.json（セッティングス・ジェイソン）
• CLAUDE.md
• Edit（エディット）
• Write（ライト）
• /notebook-edit（準備中）

公式ドキュメント

https://code.claude.com/docs/en/changelog