以下の内容はhttps://tech-blog.cluster.mu/entry/2025/07/17より取得しました。

社内のAIコーディング導入を加速するため前提知識をまとめたガイドラインを書いた

組織開発

こんにちは、クラスター株式会社でサーバーサイドをメインに開発しているid:shiba_yu36です。

クラスター株式会社は2025/07から開発チームのエンジニア希望者にClaude Maxを配り、Claude CodeなどによるAIコーディングをどんどん取り入れる決定をしました。しかしAIコーディングをいきなり行おうとしても、AIやエージェントによるコーディングの前提知識が足りず、使いこなせない・AIコーディングは使えないと判断を下してしまう可能性があります。

そこで導入を加速するため、前提となる知識をまとめたAIコーディングガイドラインを書き、Claude Max導入直後に開発チームへ展開することにしました。今回はこのガイドライン内容をそのまま共有しようと思います。

AIコーディングの導入の参考になれば嬉しいです。また、間違っている部分もあると思うので識者の方は指摘してもらえると助かります（なんなら指摘たくさんもらえたら改善できて嬉しい）。

では早速AIコーディングガイドラインを公開します。なおクラスターではモノレポを使った開発をしているため、その前提のドキュメントとなっています。

AIコーディングを活用する上での前提知識

  • まずAIコーディングの前提が日々進化してるので、ガイドラインもすぐに陳腐化する可能性があることを認識しておく
  • コーディングエージェントとしてはClaude Codeが設定なしで良い動きをする & Claude Opus 4モデルコーディング性能が非常に高いため話題になっている
    • そのため、多めに設定が必要なコーディングエージェント & コーディング性能低めのモデルを使うと、逆にAIコーディングの限界を見誤るので注意
  • Claude Code + Opus 4で知識がやたら多く処理スピードが異常に速い経験3~4年目エンジニアくらいの活躍をする。ただし、AIが得意な領域を任せる、作業スコープを限定する、渡すプロンプトを工夫することで性能が飛躍的に向上しうる
  • 現在のAIコーディングでは、安全面の対策をした上でコーディングエージェントの自律性を上げ、完了条件に向けて自動で動けるように整えることが大切

AIが得意な領域、苦手な領域

（今後のAIの進化によって不得意なものが普通にできる可能性もあるので色々試してみて欲しい）

経験3〜4年目のエンジニア、かつGitHubやWeb上に出やすい知識は無限にあり、調査や実装スピードが人の10倍ほどあると考えると、得意不得意がイメージしやすい。

  • 得意
    • 大量のコードから調査を行う
      • 例：このコード配下で、hogeテーブルのfugaフィールドのデータ更新をしている部分はどこ？
    • 明確なエラーメッセージからバグ修正を行う
      • 例：sentryのエラーを自動で読みにいって、調査・設計・修正まで行う
    • 内部品質は無視して動くプロトタイプ、PoCを作らせる
    • 領域を絞った上での実装やテスト
      • 例：全体設計と実装ステップまでは自分でやった上で、1ステップずつ実装させる
    • いろんなパターンで複数の実装を行う
  • 不得意
    • 指示通りではなく、目的を捉え直して良い設計を提案する
    • 巨大なコードベースでアーキテクチャを俯瞰して適切な設計を行う
    • 専門性が非常に高く、Web上にも情報が現れにくい問題
    • 何の参考コードもない状態で 0 -> 1実装をさせる

またプログラミング言語によっても得意不得意がある。

安全面の対策をし、自律的に動く環境を整えることが大切

コーディングエージェントはデフォルトではコマンド実行などいろんなことに許可を求めるように動く。自律的に動くような整備をしなければ、コーディングエージェント側から確認依頼が高頻度で来てしまい、効率が上がらない。そのため安全面の対策をした上で自律的に動ける環境を整えると良い。

  • 安全面の対策
    • シークレットキーや個人情報など、送ってはならないものを読み込まないように設定
    • rm -rfなど、絶対に呼び出したくないコマンドを自動で呼び出さないようにする
    • 隔離したコンテナ内で動かす工夫をしている人もいる
  • 自律的に動く環境
    • 自動で使っても問題ないものにデフォルト許可を与える
    • テストやlintなど、AIが誤りを素早く検知できる環境
    • エラーログやコンソールへのアクセス
    • ブラウザなど動作確認環境へのアクセス
    • Sentryなど外部ツールとの自動連携
  • タスクの完了条件を明示して、そこに収束させるような指示を行う
    • 「〜というテストが通ったら実装完了とみなす」「ブラウザで〜ができるようになったら実装完了とみなす」という完了条件を明示すると自律的に動いてくれやすい
      • TDDとも相性が良い
    • 間違った方向に進んでいることが分かったら早めに軌道修正する

Claude Codeの設定

公式ドキュメントがよく出来ているので、前提として「はじめに」の「概要」〜「一般的なワークフロー」まで読んでおくと良い。その上で有用に考える部分をピックアップして説明する。

自分用のCLAUDE.md

~/.claude/CLAUDE.md に自分用のCLAUDE.mdを配置できる。自分の好みの設定を配置すると良い。逆にプロジェクトで全員で使いたいものはプロジェクト単位のCLAUDE.mdに書きましょう。

例

# User-specific formatting preferences

## Conversation Guidelines
- 常に日本語で会話する

## Bashコマンド
- rmはインタラクティブにする設定をしているため、削除するときはrm -fを使うこと

セキュリティを最低限担保した上で自律性を上げる設定

Claude Codeのセキュリティに書かれているとおり、許可ベースのアーキテクチャ、親ディレクトリは見ないなど、Claude Codeがセキュリティをある程度担保している。しかし全てに許可を求められると自律性が損なわれる。安全と考えたツールは自動実行させる設定をすると良い。

~/.claude/settings.json

~/.claude/settings.jsonに自動実行させたいツール、絶対に許可しないツールを設定できる。

{
  // ここで設定している以外のものは都度ユーザーに確認を求める
  "permissions": {
    // ユーザーに許可を求めず自動で実行するツール群
    "allow": [
      "Bash(rg:*)", // rgやgit grepは.gitignoreを考慮して検索してくれる
      "Bash(git grep:*)",
      "Bash(go test:*)",
      "Bash(ls:*)",
      "Bash(find:*)",
      "Bash(head:*)",
      "Bash(tail:*)",
      "Bash(cat:*)",
      "Bash(gh pr view:*)",
      "Bash(gh pr diff:*)",
      "Read(*)" // 全ファイル基本読み込み可
    ],
    // 絶対に実行させないツール群
    "deny": [
      "Bash(sudo:*)",
      "Bash(git reset:*)",
      "Bash(git rebase:*)",
      "Read(.env*)", // .env系はセキュリティ情報が入ることが多いので読み込ませない
      "Read(id_rsa)", // 秘密鍵系
      "Read(id_ed25519)"
    ]
  }
}

他にもプロジェクト配下で自動実行して良いコマンドも設定できる。Claude Codeでツール実行を求める時に「今後は自動実行して良い」という選択肢が出るので、安全と思ったら適宜設定する（ただし、この場合はプロジェクト配下の設定ファイルに記録されるので、よく使うコマンドは~/.claude/settings.json側に記載しておく）。

See Also

MCP

MCPを設定することで、他ツールとの連携力を上げ、自律性を高めることができる。たとえば

  • Sentry MCPを使って、AIがエラーを参照できるように
  • Playwright MCPを使って、AIがブラウザを自動操作し動作確認をできるように

しかしMCPはセキュリティリスクもあるので、できる限り公式提供やセキュリティに問題がないものを選ぶようにすること。

MCPサーバーの設定スコープには3種類あり、必要に応じてプロジェクト共用・個人用で設定を行うとよい

  • local: プロジェクトごとの個人用設定（~/.claude.jsonに保存される）
  • project: プロジェクトで共通利用するサーバーの設定（プロジェクト直下の.mcp.jsonに保存される）
  • user: すべてのプロジェクトで利用できる個人用設定（~/.claude.jsonに保存される）
通知設定

自律性を上げるとはズレるが、Claude Codeがこちらに確認を求めているときに通知することで、裏側で実行させやすくなる。 セットアップ > 通知設定

上記設定を行っても、IDE連携をしたターミナル上ではBellが鳴らない場合があるので、その場合は別途IDE側の設定を追加で行う。

プロジェクト用のCLAUDE.mdを育てる

プロジェクトごとに適切なCLAUDE.mdを配置してメモリ管理することでClaude Codeにそのプロジェクトの前提知識を教えられる。そのレポジトリの親ディレクトリを再帰的に辿ってCLAUDE.mdを参照したり、子ディレクトリを操作するときはその内部のCLAUDE.mdを参照したりするため、同一レポジトリ内でもプロジェクトごとに特化したCLAUDE.mdを用意すると良い。

CLAUDE.mdの適切な書き方については一般的なプロンプトエンジニアリングが参考になる。たとえば

  • 曖昧な指示ではなく明示的な指示を行う
  • 何をしないかではなく、何をすべきかを伝える

See Also

プロジェクトのCLAUDE.mdに書く内容の指針

CLAUDE.mdに特定の時にしか使わないような指示も含めて大量の内容を入れると、大事な指示に従いにくくなってしまう（と予想している）。そこで次のような指針にすると良いだろう。

  • Claude Codeがコードを読む・コードを書く時に必ず従って欲しい内容はCLAUDE.mdに直接書く、もしくは別ドキュメントに書いて@インポートで読み込むようにする
    • @インポートはCLAUDE.mdに書いておくと勝手に展開して必ず読み込む機能。人間も読みやすいようにREADME.mdに書いて参照するなどの活用ができる
  • 特定の状況でのみ必要な内容は別ドキュメントに記載する
    • CLAUDE.mdに書くとしてもpath記載に留め、@インポートしない
    • もしくはチャット上で必要な時に@で読み込む
  • ワークフローとして定義できるものならスラッシュコマンド化を検討する

Claude Code Tips

  • Claude Codeへの指示もプロンプトエンジニアリングの一種なので、プロンプトエンジニアリングの基礎を学んでおく
  • Shift+Tabを使って、通常モード・auto-accept edits・plan modeを切り替えられる
    • 通常モードはファイル編集に許可を求める
    • auto-accept editsはファイル編集を自動で行う
    • plan modeは実装計画のみ行い、ファイル編集をしない。plan modeで方針壁打ちした後、auto-accept editsで一気に実装というやり方を取ると便利
    • 参考: アイデンティティとアクセス管理 - Anthropic
  • claude --continue / claude --resumeを使うと過去のチャットに復帰できる
  • ultrathinkというワードを追加すると、より思考に時間をかけさせることができる
  • 画像を貼り付けることも可能。ドラッグ&ドロップ、スクショからのCtrl+vのコピペに対応
  • コンテキストが増えすぎるとめちゃくちゃなことをしやすくなる。適切なタイミングで/clearでコンテキストを消すと良い
  • 汎用的になってしまったワードでは、より限定すると効くことがある
    • リファクタリングして => マーティン・ファウラーが推奨するリファクタリングをして

まとめ

今回は、社内で用意したAIコーディングガイドラインの内容を公開しました。AIコーディングは情報の流速が速く、前提知識を理解するまで時間がかかるので、このようなドキュメントによって導入が加速すると良いなと思っています。

ツッコミどころがあればぜひコメントもください！



以上の内容はhttps://tech-blog.cluster.mu/entry/2025/07/17より取得しました。
このページはhttp://font.textar.tv/のウェブフォントを使用してます
不具合報告/要望等はこちらへお願いします。
モバイルやる夫Viewer Ver0.14