AIコーディングをする際、AIに事前にルールを定義しておくことができます。
その際に使用するのが「.md」の拡張子のファイルです。
本記事には、あまり聞きなれない「.md」ファイルについて書いています。
.mdってなに？「文章を書くためのファイル」
.mdは「マークダウン(Markdown)」というファイル形式です。中身はただの文字。Wordのように装飾ボタンを押す代わりに、記号を使って見た目を表現します。
たとえば、
- 行の先頭に
#を書くと「見出し」になる - 文字を
**で囲むと「太字」になる - 行の先頭に
-を書くと「箇条書き」になる
これだけのシンプルなルールです。
なぜわざわざMarkdownを使うのか
Wordは便利ですが、「見た目の情報」がファイルの中にぎっしり詰まっています。
一方Markdownは中身がただの文字だけなので、
- 軽い(ファイルサイズが小さい)
- どんなパソコンでも開ける
- 人間が読んでもわかる
- コンピューターやAIが読み取りやすい
という特徴があります。最後の点が大事で、AIに何かを読ませたいときにとても都合がいいのです。
メモ帳でも書ける
.mdファイルは特別なソフトがなくても、Windowsのメモ帳やMacのテキストエディットで書けます。ファイルを保存するときに、名前をmemo.mdのように.mdで終わらせるだけです。
対応ソフトで開くと「きれいに表示」される
メモ帳で開くと記号がそのまま見えますが、Markdown対応ソフト(たとえばGitHub、Notion、Obsidianなど)で開くと、#が大きな見出しに、**が太字に、自動で変換されて表示されます。同じファイルでも、見るソフトによって「ソースコード状態」と「きれいに整形された状態」を切り替えられるイメージです。
どんなときに使われるか
プログラマーが説明書を書くとき、ブログ記事を書くとき、メモを取るとき、そして最近ではAIに指示やルールを書いておくときにもよく使われます。
AIに対するルールやガイドラインをMarkdown(.md)ファイルで定義する。
Markdown(.md)ファイルで定義する手法は、ここ数年で急速に広まりました。プレーンテキストでありながら見出しやリストで構造化でき、人間にもAIにも読みやすいことが理由です。代表的なものを整理して紹介します。
ツールごとの代表的なファイル
CLAUDE.md(Claude Code) AnthropicのコーディングエージェントであるClaude Codeが、プロジェクトのルートやサブディレクトリに置かれたCLAUDE.mdを自動的に読み込みます。プロジェクト固有のビルドコマンド、コーディング規約、アーキテクチャの概要、「やってはいけないこと」などを書いておくと、Claudeがそれを踏まえて作業します。~/.claude/CLAUDE.mdに置けばユーザー全体のグローバル設定として効きます。
AGENTS.md OpenAIのCodex CLIをはじめ、Cursor、Aider、Jules、Amp など複数のエージェントツールが共通でサポートしようとしている「業界標準」を目指したフォーマットです。中身はCLAUDE.mdと似たもので、ツール非依存に書けるのが利点です。
.cursor/rules/*.mdc(Cursor) Cursorは旧来の単一ファイル.cursorrulesから、.cursor/rules/ディレクトリ配下に複数の.mdc(Markdown + YAMLフロントマター)を置く方式に移行しました。フロントマターでルールの適用範囲(対象ファイルのglob、常時適用か手動呼び出しかなど)を指定できます。
.windsurfrules / .windsurf/rules/(Windsurf) Codeium Windsurfも同様の仕組みを持ちます。
.github/copilot-instructions.md(GitHub Copilot) リポジトリ内に置くとCopilot Chatが自動で参照します。
CONVENTIONS.md(Aider) Aiderでは--read CONVENTIONS.mdで明示的に読み込ませる慣習があります。
SKILL.md(Anthropic Skills) Claudeが特定のタスク(Word文書作成、PDF処理など)を行う際に読み込む手順書です。YAMLフロントマターにnameとdescriptionを書き、本文に手順やベストプラクティスを記述します。ファイル名は必ずSKILL.mdで固定です。
中身に書く典型的な内容
技術スタックと使用ライブラリのバージョン、ビルド・テスト・デプロイのコマンド、命名規則やフォーマッタの設定、ディレクトリ構成と各モジュールの責務、外部APIや認証情報の扱い方、コミットメッセージやPRのスタイル、「触れてはいけないファイル」「禁止パターン」、過去にハマった落とし穴とその回避策、といったところが定番です。
書き方のコツ
第一に、具体的で短く。「きれいなコードを書け」のような抽象論はAIにはほぼ効きません。「fetchではなくsrc/lib/http.tsのapiClientを使う」のように、行動レベルで指示します。
第二に、理由を添える。「なぜそうするか」を一文足すと、想定外の状況でもAIが趣旨を汲んで判断できます。
第三に、例を入れる。Good例とBad例を並べると精度が大きく上がります。
第四に、階層化する。プロジェクト全体に効く一般則と、特定サブシステムだけのルールは別ファイルに分けるとメンテしやすく、トークン消費も抑えられます。CursorやClaude Codeはサブディレクトリのルールファイルを自動で見つけてくれます。
第五に、更新を前提に書く。これらは「育てる」ドキュメントです。AIが間違えるたびに該当ルールを追記していくと、徐々にプロジェクト固有の知見が蓄積されます。
注意点
ルールファイルは毎回コンテキストに読み込まれるため、長くなりすぎるとトークン消費が増え、本来の指示が薄まります。500〜1500行を超えるようなら分割を検討してください。また、機密情報(APIキー、本番URL、社内固有名詞でセンシティブなもの)を書き込んでGitHubに公開してしまう事故が起きやすいので、.gitignoreでの扱いも最初に決めておくと安全です。