AIエージェントの設定はどこに置くべきか — チーム共有と個人設定の使い分け

エージェントの設定でつまずく人の多くは、書いた内容ではなく、書いた場所で失敗しています。自分の環境では動くのに同僚の環境では動かない。同僚の設定が勝手に自分に適用される。設定したはずのルールが効かない。いずれも中身の問題ではなく、そのファイルが誰に届くかの問題です。

指示ファイルに何を書くかは次の章で扱います。この章はその手前、どのファイルに書くかの話です。

設定には階層がある

Claude Codeを例に取ると、設定ファイルは5つの階層に分かれています。上にあるものほど強く、同じキーが複数の場所にあれば上位が勝ちます。

見落とされやすいのが 3が4より強いという点です。プロジェクト個人の設定は、チームで共有しているプロジェクト設定を上書きします。チームのファイルがモデルAを指定していても、自分のローカル設定でモデルBにすれば、自分のセッションだけが変わります。コミットせずに個人の例外を作れる、という設計です。

置き場所は「自分だけか、全員か」と「このプロジェクトだけか、すべてか」の2つの軸で決まります。

Gitに入れるもの、入れないもの

分岐はここで決まります。

プロジェクト共有設定はコミットします。 公式ドキュメントも、リポジトリをクローンした全員が同じ権限・フック・テレメトリ・プラグインの設定を得られるようコミットすることを勧めています。チームで揃えたいものは、ここに置いて初めて揃います。

プロジェクト個人設定はコミットしません。 ここが少し親切な設計になっていて、Claude Codeがこのファイルを初めて書き込むとき、グローバルのGit除外設定に自動で追加します。以後どのリポジトリでもコミットに混ざりません。

「今後は聞かない」が保存される場所

日々の運用で、この階層に最も影響するのが権限プロンプトです。コマンドの実行許可を求められたときに「はい、今後は聞かない」を選ぶと、その許可ルールはプロジェクト個人設定に保存されます。

つまり、意識して設定を書かなくても、使っているうちにローカル設定は勝手に育ちます。そして育ったものは自分にしか効きません。チームで揃えたい許可があるなら、育ったローカル設定から共有設定へ引っ越す作業が要ります。

もう1つ、場所に関する細かいが実害のある挙動があります。この許可ルールの保存先は、サブディレクトリやワークツリーで起動した場合でもリポジトリのルートになります。一方、共有設定は起動したフォルダからしか読まれません。サブディレクトリで起動すると、リポジトリルートにコミットされている共有設定が読み込まれないまま作業することになります。

共有設定を効かせたいなら、リポジトリのルートで起動します。

上書きされるものと、合成されるもの

すべてのキーが「上位が勝つ」わけではありません。公式ドキュメントは、リストは上書きではなく合成されると説明しています。

許可ルールが合成されるということは、どのスコープに足しても許可は増えるということです。だからこそ、権限設計の章で扱ったとおり、禁止側が強く設計されています。禁止はどのスコープに書かれていても、他のスコープの許可を打ち消します。

そして管理設定は最上位で、コマンドライン引数でも上書きできません。組織として絶対に守らせたいものは、ここに置くことで初めて保証になります。

効かないときは、まずスコープを疑う

設定が効かないときに中身を書き直し続けるのは、最も時間を溶かすパターンです。順序としては読み込まれているかの確認が先です。

1. どのファイルが読み込まれているかを確認する
2. 読み込まれていなければ、置き場所と起動ディレクトリを疑う
3. 読み込まれているのに効かないなら、上位のスコープで上書きされていないかを見る
4. 禁止ルールに引っかかっていないかを見る

多くのツールが、現在読み込まれている設定や指示ファイルを一覧表示する手段を持っています。Claude Codeなら /config で設定を確認でき、読み込み済みのファイルは /context で確認できます。

よくあるハマりどころ

サブディレクトリで起動する。 前述のとおり、共有設定が読まれません。モノレポで特定のパッケージだけ触りたいときにやりがちです。

手で作ったローカル設定をコミットする。 自動除外はツールが作ったファイルにしか働きません。

個人の好みをチーム共有ファイルに書く。 「日本語で返答して」「自分の好きなモデル」といった設定は、共有ファイルに書くとチーム全員に配られます。個人の好みは、ユーザー設定かプロジェクト個人設定に置きます。

組織の設定を上書きしようとする。 管理設定はコマンドライン引数でも上書きできません。効かないのではなく、そう設計されています。

育ったローカル設定を放置する。 便利に使っているうちに、自分の環境だけが特別に快適になり、チームには何も共有されていない状態になります。

ちゃんと使うためのポイント

• 設定は階層構造。同じキーは上位が勝つが、リストは合成される
• プロジェクト個人設定は、プロジェクト共有設定より強い。個人の例外はコミットせずに作れる
• 共有したいものはコミットする。個人のものはコミットしない。手作りファイルは自動除外されない
• 「今後は聞かない」はプロジェクト個人設定に溜まる。チームに要るものは共有設定へ引っ越す
• 共有設定を読ませるにはリポジトリのルートで起動する
• 効かないときは中身を直す前に、読み込まれているかを確認する

次の章では、この置き場所の上で、実際に指示ファイルへ何を書くかを扱います。同じ内容でも、置き場所と中身の両方が揃って初めて機能します。

参考リンク

• Claude Code settings（公式） — 5階層の優先順位、Git除外の挙動、リストの合成規則
• Configure permissions（Claude Code 公式） — 許可ルールがスコープをまたいでどう評価されるか
• Rules（Cursor 公式） — プロジェクト / ユーザー / チームという同種のスコープ分け