AIが迷う職場では、AIコーディングも迷う
AIコーディングエージェントは、かなり大きなプロジェクトでもコードを読み、必要なファイルを探し、修正案を作れるようになっています。
ただし、ここで誤解しやすいのは「賢いモデルを使えば、どんな現場でも同じように成果が出る」という見方です。実際には、AIが働く作業環境の整え方によって、出力の安定性は大きく変わります。
ファイル名が曖昧で、古い仕様書が残り、テストコマンドも人によって違い、秘密情報の置き場所も決まっていない。こうした状態では、人間の新入社員も迷います。AIも同じです。
Claude Codeの公式ブログでも、大規模コードベースで成果を出すには、モデル単体ではなく、周辺の設定や運用を含めた「harness」が重要だと説明されています。harnessとは、指示ファイル、hooks、skills、plugins、MCP、LSP、subagentsなど、AIが作業するための環境一式だと捉えると分かりやすいです。
中小企業でAIコーディングを導入する場合も、最初から大企業向けの複雑な仕組みを作る必要はありません。まずは、AIが迷わず、安全に、検証しながら動ける最低限の作業環境を作ることが先です。
「全部読ませる」より「探しやすくする」
AIエージェントは、プロジェクト内のファイルを探索し、必要な情報を読みながら作業します。Claude Codeのドキュメントでは、コードベースを読み、ファイルを編集し、コマンドを実行し、開発ツールと連携できるAIコーディングツールとして説明されています。
ここで大切なのは、すべての情報を最初から詰め込まないことです。長いルール、古い資料、大量のログを常に読ませると、AIの作業文脈が膨らみ、重要な指示が埋もれます。
人間でも、初日に全社規程、全議事録、全マニュアルを渡されても動けません。最初に必要なのは、全体地図と、今やる作業に関係するローカルルールです。
そのため、AI向けの情報は次のように分けると扱いやすくなります。
- 全体方針: 事業方針、禁止事項、主要コマンド、レビュー方針
- 領域別ルール: 管理画面、API、ブログ、データベース、テストなど
- 手順化された作業: レビュー、リリース、調査、ドキュメント作成
- 強制したい制約: 削除禁止、秘密情報の読み取り禁止、危険コマンドの確認
- 外部接続: タスク管理、ログ、社内ドキュメント、CRMなど
Optiensでいえば、AGENTS.md のような全体方針は「会社の憲法」に近いものです。一方で、ブログ作成、管理画面改修、Supabase作業、AI診断レポート作成には、それぞれ別の手順や注意点があります。全部を1つの巨大な指示ファイルに入れるより、領域別に分けた方がAIにも人間にも読みやすくなります。
中小企業がまず整えるべき5つのこと
1. プロジェクトの地図を作る
最初に必要なのは、AIが「どこを見ればよいか」を判断するための地図です。
例えば、次のような短い一覧で十分です。
src/pages/: 公開ページと管理画面src/content/blog/: ブログ記事executive/: 事業計画、調査メモ、ファクトチェック記録scripts/: 検証、同期、生成系スクリプトsupabase/: Edge Functionsやデータベース関連
この地図があるだけで、AIは当てずっぽうでファイルを開く回数を減らせます。大事なのは、完璧なドキュメントを作ることではなく、AIが最初に読む目次を置くことです。
2. 指示ファイルは短く、階層化する
Claude Codeでは CLAUDE.md がプロジェクトの指示ファイルとして扱われます。公式ドキュメントでは、CLAUDE.md は各セッション開始時に読み込まれる文脈であり、具体的で簡潔な指示の方が安定しやすいと説明されています。
一方、このリポジトリのようにCodexや他のAIエージェントも使う場合は、AGENTS.md を正本にし、Claude Code向けには CLAUDE.md から読み込ませる設計も考えられます。重要なのは、同じルールを複数箇所に手作業で重複させないことです。
全体ルールには、次のような内容だけを置くのが現実的です。
- 事業方針と禁止事項
- 主要な技術スタック
- 必ず守る検証コマンド
- 触ってはいけないファイルや情報
- コミット・pushのルール
細かい実装手順や特定領域の注意点は、別ファイルやスキルに分けます。
3. AIに読ませないものを決める
AIに読ませる情報を増やすことと同じくらい、読ませない情報を決めることも重要です。
生成済みファイル、ビルド成果物、巨大なログ、外部ライブラリ、古いバックアップ、秘密情報をAIが探索対象に含めると、作業が遅くなるだけでなく、誤った判断や情報漏洩リスクにつながります。
中小企業では、まず次を確認してください。
.envやAPIキーがリポジトリに残っていないか- 顧客情報を含むCSVやExcelが作業ディレクトリに置かれていないか
- 生成物やログをAIが毎回読みに行っていないか
- 古い仕様書と新しい仕様書が同じ場所に混在していないか
- 削除・送信・外部通信に関する許可ルールが決まっているか
AI導入の前に、作業場を片付ける。これは地味ですが、かなり効きます。
4. テストとレビューの担当範囲を決める
AIはテストを実行できますが、「どのテストを走らせるべきか」はプロジェクトごとに違います。
小さな修正のたびに全テストを走らせると時間がかかり、出力ログも膨らみます。逆に、必要な確認を飛ばすと、動いたように見えるだけの変更が混ざります。
そこで、領域ごとに次を決めておきます。
- ブログ記事変更時に実行するチェック
- 管理画面変更時に実行するビルド
- API変更時に確認するテスト
- DB変更時に確認するマイグレーション
- 本番反映前に人間が見るポイント
Optiensの公開コンテンツなら、ファクトチェック、サービス範囲チェック、ビルド確認が重要です。AIが自動で進める部分と、人間が最終判断する部分を分けておくと、速さと安全性を両立しやすくなります。
5. 運用責任者を決める
AIコーディング環境は、作って終わりではありません。
モデルの性能、ツールの仕様、社内の運用ルールは変わります。以前は必要だった細かい指示が、次のモデルでは不要になることもあります。逆に、新しい機能が増えたことで、禁止事項や確認手順を追加すべき場合もあります。
そのため、AIコーディング環境には責任者が必要です。
大企業ならDeveloper Experienceや情報システム部門が担うかもしれません。中小企業なら、まず1人で構いません。その人が、指示ファイル、権限設定、社内スキル、禁止ファイル、レビュー手順を見直す役割を持ちます。
見直し頻度は、業務量やツール変更の速さによります。少なくとも、主要モデルやエージェント機能が大きく変わったタイミングでは、ルールを読み返した方がよいです。
プロンプト改善だけでは限界がある
AIコーディングで失敗したとき、多くの人はプロンプトを直そうとします。もちろん指示の出し方は大事です。
しかし、毎回プロンプトで説明しなければならないことは、本来は作業環境に埋め込むべきです。
- 毎回説明する会社ルール → 指示ファイルへ
- 毎回やるレビュー手順 → スキルやチェックリストへ
- 毎回止めたい危険操作 → 権限設定やhooksへ
- 毎回探す社内情報 → ドキュメント地図やMCP連携へ
- 毎回迷うテスト → 領域別コマンドへ
プロンプトは、その場の依頼を書く場所です。会社のルールや安全基準を毎回チャットに書く運用は、属人化しやすく、抜け漏れも起きます。
AIを社内導入するなら、プロンプト術より先に、AIが働く作業環境を整える。この順番が大事です。
Optiensとしての見方
中小企業がAIコーディングを導入するとき、最初から高度なマルチエージェント環境や独自MCPを作る必要はありません。
まずは、次の小さな整備から始めるのが現実的です。
- プロジェクト地図を1枚作る
- AI向けの全体ルールを短くまとめる
- 機密情報と生成物を探索対象から外す
- よく使う検証コマンドを明記する
- AIの変更を人間が見るレビュー観点を決める
- 1人の責任者が月次でルールを見直す
これだけでも、AIはかなり働きやすくなります。
AIコーディングの本質は、単に「コードを書かせる」ことではありません。AIが迷わず動ける仕事場を作り、人間が判断すべきところを残し、改善し続けることです。
AI活用をどこから始めるべきか迷っている場合は、まず AI活用診断簡易版（無料） で、既存業務のどこがAIパッケージ化しやすいかをご確認ください。より具体的に整理したい場合は、詳細版AI活用診断（¥5,500税込・MTGなし） で、AIパッケージ適合性、構成案、優先順位、費用前提を整理してお届けします。