AIコーディング前にリポジトリを自動点検するOSSを作った ― Codex / Copilot / Cursor対応

はじめに

AIにコードを書いてもらう前に、そのリポジトリの設定や指示が本当に大丈夫か確認したい。

そんな用途向けに、codex-workspace-bootstrap (cwb) というOSSを作りました。

ひと言でいうと、

AIコーディングを始める前の「リポジトリ健康診断」

をするためのツールです。

この記事では、

• 何をチェックできるのか
• どんな問題を検出できるのか
• どうやって使うのか
• なぜ作ったのか

を順番に紹介します。

GitHub:

何ができるのか

最近は、1つのリポジトリで複数のAIコーディングツールを使うことが増えています。

たとえば、

• Codex
• GitHub Copilot
• Cursor
• Cline
• Continue
• Claude Code
• Gemini CLI

などです。

便利な一方で、それぞれのAI向け設定が少しずつ食い違っていくことがあります。

例えばこんな問題

1. 実際はpnpmなのに、AIにはnpmを使うよう書いてある

たとえばリポジトリ側では、

{
  "packageManager": "pnpm@10"
}

となっているのに、AI向けの指示ファイルでは、

npm test

と書いてあるケースです。

この状態だと、AIが間違ったコマンドを実行しようとする可能性があります。

cwb は、こうした package managerの不一致 を検出します。

2. AIに書いてあるコマンドが存在しない

たとえば、

npm run test:unit

と書いてあるのに、実際の package.json に test:unit が存在しないケースです。

これも自動でチェックできます。

3. AIごとに指示が食い違っている

例えば、

AGENTS.md
→ pnpm test

Copilot instructions
→ npm test

Cursor rules
→ pnpm run test:unit

のように、複数のAI向け設定がバラバラになることがあります。

cwb は、同じ適用範囲の指示を比較して、矛盾しそうな部分を検出します。

誤検知を増やさないために、適用範囲が違うルールを無理に比較しないようにしています。

4. ネストされたAI向け設定にも対応

大きなリポジトリでは、

AGENTS.md
services/api/AGENTS.md
services/payments/AGENTS.override.md

のように、ディレクトリごとに指示が分かれていることがあります。

またCursorでは、

backend/.cursor/rules/
frontend/.cursor/rules/

のように、サブディレクトリ側にルールが置かれることもあります。

cwb は、こうしたネストされた設定も検出します。

5. Gitに入れたくない危険そうなファイルも確認

.env や秘密情報を含みやすい名前のファイルがGitで追跡されていないかも確認します。

ただし、この機能は軽量チェックです。

GitleaksやTrivyのような本格的なセキュリティスキャナの代替ではありません。

ファイル内容を勝手に表示することもしません。

使い方

Python 3.10以上があれば使えます。

インストール:

pip install codex-workspace-bootstrap

実行:

cwb preflight .

これだけです。

結果は3段階

実行すると、リポジトリの状態を次の3段階で表示します。

• READY
• NEEDS ATTENTION
• BLOCKED

READY

基本的な設定やAI向け指示が揃っていて、重大な問題が見つからなかった状態です。

NEEDS ATTENTION

使えないわけではないものの、

• AI向け指示が不足している
• コマンドの食い違いがある
• 設定の確認が必要

といった状態です。

BLOCKED

AIに作業させる前に確認した方がよい重大な問題がある状態です。

CIでも使える

GitHub Actionsなどで、

cwb preflight . --fail-on-integrity

と実行できます。

AI向け設定に矛盾や不整合が見つかった場合、CIを失敗させることができます。

つまり、

AI向け設定の壊れたPRをマージ前に止める

という使い方もできます。

JSON / Markdown / SARIFにも対応

自動化向けにレポートも出力できます。

cwb preflight . --json preflight.json

cwb preflight . --markdown preflight.md

cwb preflight . --sarif preflight.sarif

SARIFはGitHub Code Scanningへの連携にも使えます。

自動修正は慎重に

修正候補を確認したい場合は、

cwb fix .

を実行します。

これはデフォルトではプレビューのみです。

実際に安全な変更だけ適用する場合は、

cwb fix . --apply

を使います。

既存のAI向け指示に矛盾がある場合でも、勝手に書き換えないようにしています。

なぜ作ったのか

CodexやCopilot、CursorのようなAIコーディングツールは、コードを書く能力がどんどん高くなっています。

ただし、AIが優秀になっても、

• リポジトリの設定
• テストコマンド
• package manager
• AIごとの指示ファイル

が壊れていれば、AIはその壊れた前提に従って作業してしまいます。

そこで、

AIにコードを触らせる前に、まずリポジトリ側を点検する

ためのツールとして cwb を作りました。

AIそのものを置き換えるツールではありません。

Codex / Copilot / Cursorなどを使う前段階の preflight layer という位置付けです。

ローカル中心で動作

基本的なチェックはローカルで動作します。

AI向け指示ファイルからコマンドを読み取ることはありますが、そのコマンドを勝手に実行することはありません。

リポジトリ内容を外部AIサービスへ送信することも、コア機能では行いません。

対応しているAI向け設定

現在は主に次の形式を検出します。

• Codex / AGENTS.md
• GitHub Copilot instructions
• Cursor rules
• Cline rules
• Continue rules
• Claude Code
• Gemini CLI

今後も実際のリポジトリを見ながら、誤検知を増やさない形で改善していく予定です。

GitHub

MITライセンスで公開しています。

実際のリポジトリで、

• こんな設定を検出できなかった
• 誤検知した
• monorepoで変な挙動になった
• こういうAI向け設定にも対応してほしい

といったケースがあれば、Issueで教えてもらえると助かります。

特に今は、機能を増やすことよりも 実リポジトリでの精度改善 を優先しています。