PHPプロジェクトで活用するCursor MDCファイルの最適設定ガイド

PHPでの開発現場で、コーディング規約やセキュリティ対策を徹底するためにCursorのcursor.rules（.mdcファイル）を活用するケースが増えています。CursorはAI搭載IDEとして、ユーザーが指定したルールを参照しながらコード補完やリファクタリングを行います。そのため、プロジェクト固有のベストプラクティスをまとめておくことで、バグ削減やコーディング規約の一元管理、AIと連携した効率的な開発を実現しやすくなります。

以下では、これまでの調査内容をもとに、実際の設定例や具体的なメリットについて詳しく解説します。

1. Cursor MDCファイル（`cursor.rules`）とは

Cursorの.mdcファイルは、AIエンジンに対して「どういったコーディング規約やセキュリティポリシーを順守するべきか」を伝える役割を持ちます。このファイルをプロジェクトに置いておくと、CursorのAIがコード補完時に設定内容を踏まえた提案を行い、一定のコーディング品質を保ったまま開発を進めることが可能です。

2. 推奨ルール例とその解説

2.1 PSR-12と厳格な型指定

PSR-12のコーディング規約を厳守
PHP-FIGが提唱するPSR-12によって、インデントやブレースの位置、命名規則（クラス名やメソッド名）などを統一できます。保守性や可読性が向上するため、チーム開発にも大きく寄与します。
declare(strict_types=1)の徹底
各PHPファイルの先頭にdeclare(strict_types=1);を入れておくと、型の不一致による予期せぬ不具合を早期発見しやすくなります。AIもこれを前提としたコード提案を行うため、型チェックを強化できます。
関数・メソッドの引数と戻り値の型宣言
PHP 7以降の型宣言を活用し、引数と戻り値に対して明示的に型を指定します。AIがコード補完を行う際にも型を考慮した提案が期待できます。

2.2 バグ削減のベストプラクティス

危険な関数の使用を制限
eval()、exec()、shell_exec()などの関数はセキュリティリスクが高いため、原則として禁止するか安全性を十分考慮した運用に限定します。
ユーザー入力の検証とサニタイズ
filter_input()やfilter_var()を使い、不正なデータや想定外の形式がプログラムのロジックに入り込まないようにすることが重要です。
エラーや例外ハンドリングの明確化
@演算子でエラーを隠すのではなく、しっかりと例外やエラーログを取得して原因を追える環境を整備します。
グローバル変数の乱用回避
依存性注入や引数受け渡しを意識し、グローバルスコープの変数を減らすことで副作用を最小化します。

2.3 AI（ChatGPT・Claudeなど）との連携最適化

APIキーの管理
外部AIサービスの鍵は環境変数（例：.envファイル）を利用し、ソースコードに直接書かないようにします。これにより、機密情報の漏えいリスクを低減できます。
SDKや公式ライブラリを推奨
可能な場合は公式クライアントやライブラリを利用し、接続やエラー時の再試行、レート制限をハンドリングしやすくします。
リトライ処理とログ
ネットワーク障害やHTTP 429の発生に備え、リトライ処理を組み込むとともに、やり取りした内容をログに残しておくと問題解決がスムーズになります。

2.4 安全なSQL接続の実装

PDOの活用とSQLインジェクション対策
PDOを用いてプリペアドステートメントを常に使用し、動的に生成した文字列を直接SQLに埋め込まないよう徹底します。
リソース管理とトランザクション
データベース接続を長時間開きっぱなしにしないようにし、必要に応じてトランザクションを適切に使用します。複数のテーブル更新などではCOMMITやROLLBACKの運用方針を明確にしておくと、データ整合性が保ちやすくなります。

2.5 プロジェクトごとのカスタムルール

アーキテクチャ概要の明示
プロジェクトの設計方針や使っているフレームワーク（例：Laravel、WordPressなど）をcursor.rules内で簡単に説明しておくと、AIがプロジェクトの文脈を理解しやすくなります。
複数のルールファイルに分割
共通のルールをまとめたbase.mdcと、機能ごとの.mdcを分けて管理することで、異なるモジュールやフェーズでのルールを柔軟に切り替えることが可能です。

3. 実際の`cursor.rules`ファイル例

# Coding Standards (PSR-12 and strict types)
- "Follow PSR-12 coding standards for all PHP code (consistent formatting and naming)."
- "Include declare(strict_types=1) at the top of every PHP file to enforce strict typing."
- "Use type hints for all function parameters and return types (PHP 7+ scalar and object types)."

# Bug Reduction Best Practices
- "Avoid using unsafe functions like eval(), exec(), or shell_exec(); use safer alternatives or none at all."
- "Always validate and sanitize user input (e.g., use filter_var or filter_input) to prevent unexpected behavior."
- "Enable error_reporting and handle exceptions; do not suppress errors with @, catch and log them instead."
- "Avoid global state; pass variables as parameters or use dependency injection to reduce side effects."

# AI Integration (ChatGPT/Claude)
- "Never hardcode API keys or secrets in code; use environment variables for OpenAI/Claude API keys."
- "Use official SDKs or APIs for AI integration and manage rate limits."
- "Implement error handling and retries for API calls (handle network failures and HTTP 429 rate limit responses)."
- "Log AI API interactions and responses for debugging and to monitor usage."

# Secure SQL Practices
- "Use PDO with prepared statements for all database queries to prevent SQL injection vulnerabilities."
- "Never directly embed user input in SQL queries; always use bound parameters or parameterized queries."
- "Close or reuse database connections properly to avoid resource leaks."
- "Use transactions for multi-step database operations to maintain data integrity."

# Project-Specific Custom Rules
- "Provide a high-level project overview and domain context here."
- "Specify any framework-specific conventions (e.g., Laravel, WordPress)."
- "Organize multiple .mdc files if needed."
- "Customize or override rules per project."

実際の運用では、このようなファイルを.cursor/rulesフォルダに配置し、共通ルールと個別ルールを組み合わせて使うことが推奨されています。AIがコードを補完する際に、ここで定義したポリシーや方針に基づいて提案が行われるので、コード品質のばらつきを抑えやすくなるでしょう。

4. まとめとメリット

コーディング規約の自動適用

PSR-12などをベースにルールを定義しておくと、チーム内のコードスタイルが自然に統一されます。

バグの早期発見と減少

危険な関数の使用制限やユーザー入力の検証を標準化することで、セキュリティインシデントやロジックエラーを未然に防ぎやすくなります。

AI連携における開発効率向上

APIキー管理やレート制限への対応方針を明確化することで、AIサービスとの連携がスムーズになります。さらにログに残す仕組みを整えれば、トラブルシュートも迅速です。

安全なSQL操作の標準化

PDOとプリペアドステートメントの利用をルール化することで、SQLインジェクション対策やリソース管理が統一されます。

プロジェクト固有の調整が容易

プロジェクト規模に合わせてルールファイルを複数に分割し、アーキテクチャの概要を記載することで、AIがプロジェクトの意図をくみ取ったサポートを提供しやすくなります。

総じて、PHP開発向けのCursor MDCファイルを整備しておくことは、開発スピードや品質を高めるうえで大いに役立つ取り組みといえます。チームの方針やフレームワーク特性に合わせてルールをカスタマイズし、バグ削減と生産性向上の両面を実現してください。

引用・参考文献

What is .cursorrule and How to Use It? – DEV Community
Comprehensive Laravel PHP Cursor Rules: Best Practices and Key Principles. rule by Ruchit Patel
Server Side Code Injection – PHP Code Injection | iothreat | Achieve SOC2 Compliance
Integrating Chatgpt Api With Php Frameworks | Restackio
How can I prevent SQL injection in PHP? | Sentry
Definitive Rules – Discussion – Cursor – Community Forum

本文章の一部にはAIによる生成が含まれています。