Cursor/Claude Codeの修正精度を劇的に上げる「llms.txt」活用術

「Cursorに修正を頼んだら、意図しない古いライブラリを使われた」「Claude Codeがプロジェクトの全体構造を理解しておらず、ファイル間の依存関係を破壊してしまった」
AIエディタを使っているエンジニアなら誰しも直面するコンテキスト未共有によるハルシネーション（幻覚）問題。ここで有効なのが、llms.txt やMarkdownドキュメントを「外部コンテキストの入口」として扱う発想です。

1. AIエディタが陥る「文脈の欠如」という罠

CursorやGitHub Copilotなどには「Codebase Indexing（コードのインデックス化）」機能がありますが、AIはコードの文字列を解析しているだけであり、「あなたが今、何の課題を解決するために、どのドキュメント（公式仕様や要件定義）に依存しているか」までは自動で理解できません。

そこで、プロジェクトのルートディレクトリに要件定義やアーキテクチャのガイドラインをまとめたMarkdown文書を置き、AIエディタに参照させる「Context Injection」という手法が広く使われています。当サイトでは、その1形式として llms-full.txt という大きめの補助ファイルを紹介しています。

2. Cursor のルールファイルと `llms.txt` の最強の組み合わせ

Cursorには、ディレクトリごとにAIの振る舞いを定義できるルールファイル機能があります。
これと llms.txt（または llms-full.txt のような補助ドキュメント）を組み合わせることで、社内ルールと参照先ドキュメントをAIに一貫して渡しやすくすることが可能です。

⚠️ 2025年以降のCursorは `.cursor/rules/` に移行
従来の .cursorrules（ルートの単一ファイル）は非推奨となり、現在は .cursor/rules/ ディレクトリ配下に複数のMarkdownファイル（.mdc拡張子）を配置する新形式が標準です。用途別（コーディング規約・ライブラリ仕様・外部ドキュメント参照等）に分割して管理できるようになりました。

---
description: 外部ライブラリの公式ドキュメント参照ルール
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: true
---

# External Documentation Rules

You are an expert full-stack developer.
Before writing or modifying any code for this project, you MUST read the following document to understand our internal architecture and UI rules:
@docs/llms-full.txt

When updating routing logic, read the local summary in docs/external/nextjs.md first.

When implementing Stripe payments, read the local summary in docs/external/stripe.md first.

Do NOT use older patterns (Pages Router, etc.). Adhere strictly to the rules defined above.

🔥 ポイント：alwaysApply: true の使い方
新形式の .mdc ファイルでは、フロントマターの alwaysApply: true を指定することでファイル種別に関わらず全チャットで強制適用できます。globs で対象ファイルを絞れば、TypeScriptファイル編集時のみ参照させるといった細かい制御も可能です。

📌 ここでの注意点
Cursor公式で確認できるのは .cursor/rules/ によるルール適用です。llms.txt をURLで直接読ませる運用は便利ですが、記事執筆時点では「Cursorの標準仕様」と断定するより、チームの運用パターンとして紹介するのが安全です。

3. Claude Code (CLI) での活用法と CLAUDE.md

Anthropicが公開したターミナル用AIエージェント「Claude Code」は、CLAUDE.md による継続的なプロジェクト文脈の付与が非常に強力です。

CLIに外部ドキュメントURLを明示して渡す運用は実務上有効ですが、Claude Codeが一般的なWebサイトの llms.txt を標準仕様として自動解釈するとまでは言い切れません。ここでは「URLやローカルMarkdownを明示的に参照させると精度が上がる」という運用ノウハウとして捉えてください。

CLAUDE.md：プロジェクト専用の「永続コンテキスト」

Claude Codeには、プロジェクト設定ファイルとして CLAUDE.md があります。プロジェクトルートに配置すると、Claude Code がそのディレクトリで起動するたびに自動読み込みされ、毎回コンテキストを説明し直す手間がなくなります。

# Project: My SaaS App

## Architecture
- Framework: Next.js 16 App Router (NOT Pages Router)
- DB: Supabase (PostgreSQL)
- Auth: Supabase Auth

## Next.js 16 Key Patterns (Breaking Changes from v14/v15)
- `params` and `searchParams` in pages are now a Promise:
  Use `const { slug } = await params`, NOT `const { slug } = params`
- Route segment configs (`export const dynamic`, `export const revalidate`) are deprecated.
  Use `'use cache'` directive + `cacheLife()` for caching instead.
- For instant client-side navigation, export `unstable_instant` from the route.
- All pages are dynamic by default. No need for `dynamic = 'force-dynamic'`.

## Important Rules
- Always use TypeScript strict mode
- Use Server Components by default; Client Components only when necessary
- Never use `any` type
- Do NOT use deprecated `getServerSideProps` or `getStaticProps` (Pages Router only)

## Key Documentation
Always refer to these before writing code:
- Internal API spec: @docs/llms-full.txt
- Next.js 16 summary: @docs/external/nextjs.md
- Supabase summary: @docs/external/supabase.md

💡 CLAUDE.md と llms.txt の組み合わせがベストプラクティス
CLAUDE.md に「参照すべきローカル資料や外部ドキュメントの要約」を明記することで、Claude Code は起動直後から正しいコンテキストを持ち、ゼロから説明する必要がなくなります。llms.txt はその入口の1つとして使えます。

4. 他のAIエディタでの対応状況

llms.txt を活用したコンテキスト注入の考え方は、Cursor・Claude Code 以外のAIエディタでも応用できます。ただし、各ツールでの正式サポート範囲は異なるため、「標準機能」と「運用ノウハウ」を分けて考える必要があります。

5. 自分のOSSやプロダクトにも「AIの目」を用意しよう

もしあなたが公開しているライブラリやWebサービスがあるなら、/llms.txt や読みやすいMarkdownドキュメントを整備する価値は高いです。エンジニアがAIツールにURLを渡すとき、入口が整理されているだけで情報取得の精度が上がるからです。
ただし、2026年4月13日時点では「必須要件」と断言するより、将来性の高いDevRel施策として位置づけるのが正確です。