ctxlint

ctxlint

ワンクリックでローカルの Yaw MCP 設定に追加でき、すべての Yaw Terminal セッションで利用できます。手動でインストールする場合は、以下をご覧ください。

AI エージェントのコンテキストファイル、MCP サーバー設定、セッションデータを実際のコードベースと照合してリントします。 コンテキストのリント、MCP 設定のリント、セッション監査に対応しています。16 種類の AI ツール、8 種類の MCP クライアント、プロジェクト間の整合性チェック、自動修正をサポートします。CLI、CI ステップ、コミット前フック、MCP サーバーとして利用できます。

あなたの CLAUDE.md はエージェントに嘘をついています。.mcp.json には API キーがハードコードされています。ctxlint は両方を検出します。

ctxlint を使う理由

AI コーディングツールには、CLAUDE.md、.cursorrules、AGENTS.md、.mcp.json などのコンテキストファイルが付属しています。これらのファイルは、あなたとエージェントとの間で最も重要なインターフェースです。何を構築するか、どのようにテストするか、必要なものがどこにあるかをエージェントに伝えます。

しかし、コンテキストファイルはすぐに古くなります。ファイル名を変更したり、ビルドスクリプトを変更したり、Jest から Vitest に切り替えたりしても、CLAUDE.md には古い情報が残ったままです。エージェントは古い指示に忠実に従い、失敗します。結局、マークダウンファイルの 12 行目にある誤ったパスが原因だとわかるまで、10 分もデバッグすることになります。

コンテキストファイルが 5 つ、MCP 設定が 3 つあるチームで、さらに先週ビルドシステムに手を加えた人が 2 人いるとしましょう。既存の解決策がないまま、深刻な問題が発生します。

ctxlint は、この問題に特化して作られたリンターです。コンテキストファイルを読み込み、実際のコードベースと照合して、エージェントが気づく前に食い違いを検出します。

• 起動が高速 — ランタイム依存関係がゼロの、単一の自己完結型バンドルとして提供されます。npx が約 400 KB の tarball をダウンロードし、すぐに起動します
• 実際の問題を検出 — 壊れたパス、誤ったコマンド、古い参照、ファイル間の矛盾を検出します
• 賢い提案 — Git のリネームを検出し、あいまい検索で適切なパスを提案します
• 自動修正 — --fix を使うと、Git の履歴に基づいて壊れたパスを自動的に書き換えます
• トークンを考慮 — ファイルがコンテキストウィンドウをどのくらい消費するかを表示し、重複した内容にフラグを付けます
• あらゆる AI ツールに対応 — Claude Code、Cursor、Copilot、Windsurf、Gemini、Cline、Aider など、さらに 9 種類をサポートします
• 複数の出力形式 — テキスト、JSON、SARIF（GitHub Code Scanning）に対応します
• MCP サーバー — IDE／エージェントとの連携用に、自動承認向けのツールアノテーションを備えた 7 つのツールを提供します
• 監視モード — --watch を使うと、コンテキストファイルの変更時に自動で再リントします

インストール

インストールせずに直接実行します。

npx -y @yawlabs/ctxlint@latest

プロジェクトへのインストール（チームにおすすめ）

npm install -D @yawlabs/ctxlint
# or
pnpm add -D @yawlabs/ctxlint

次に、package.json のスクリプトに追加します。

{
  "scripts": {
    "lint:ctx": "ctxlint --strict"
  }
}

グローバルインストール

npm install -g @yawlabs/ctxlint

プロジェクトごとに設定せず、すべてのプロジェクトで ctxlint を使いたい場合に便利です。

チェック対象

チェック項目	検出内容
壊れたパス	コンテキスト内のファイル参照のうち、プロジェクト内に存在しないもの
誤ったコマンド	package.json のスクリプトや Makefile のターゲットと一致しないビルド／テストコマンド、およびビルドで宣言されていない Gradle プロジェクトパスや Maven の -pl モジュール
古いコンテキスト	最近のコード変更後に更新されていないコンテキストファイル
トークンの浪費	セッションごとにファイルが消費するコンテキストウィンドウの量
冗長な内容	エージェントがすでに推測できる内容（例：package.json に react があるのに「React を使用しています」と記載）
矛盾	コンテキストファイル間で指示が食い違っているもの（例：一方では「Jest を使用」、もう一方では「Vitest を使用」）
フロントマター	Cursor の .mdc、Copilot の指示、Windsurf のルールにおける無効または欠落した YAML フロントマター
CI カバレッジ	どのコンテキストファイルにも記載されていない .github/workflows/ 内のリリース／デプロイのワークフロー
CI のシークレット	CI ワークフローで使用されるシークレット（${{ secrets.X }}）のうち、コンテキストファイルに記載されていないもの
インラインのシークレット	コンテキストファイルに貼り付けられた実際のシークレット — 秘密鍵ヘッダー、AWS／GitHub／Anthropic／OpenAI／npm／Slack／Google／Stripe のトークン形式。メッセージにシークレットそのものが表示されることはありません（6 文字の伏せ字付きプレフィックスのみ）
無効なフック	存在しなくなったスクリプトを参照している .claude/settings.json の PreToolUse フック／権限エントリ（無効なゲートは何もせずに処理されます）。デフォルトではプロジェクトの .claude/settings.json[.local] をスキャンします。ユーザーのグローバルな ~/.claude/settings.json もスキャンするには --hooks-global を渡します
不足しているシークレット	兄弟リポジトリには設定されているが、現在のプロジェクトには存在しない GitHub シークレット
設定の乖離	正規の設定ファイル（CI、tsconfig など）が兄弟プロジェクト間で異なっている状態
不足しているワークフロー	2 つ以上の兄弟リポジトリには存在するが、ここには存在しない GitHub Actions ワークフロー
古いメモリ	存在しなくなったパスを参照する Claude Code のメモリエントリ
重複したメモリ	プロジェクト間で内容がほぼ重複しているメモリ（内容の重複率が 60% 超）
ループ検出	エージェントがループに陥っている状態 — セッション履歴内でコマンドや周期的なパターンが繰り返されているもの
メモリの超過	MEMORY.md が Claude Code のセッション読み込み上限である 200 行／25KB を超えている状態 — 上限を超えたエントリはエージェントから見えません
共有一時パス	エージェントが書き込み、後で読み戻す固定の一時パス（例：/tmp/pkg.bak）— 同時進行中の別セッションが、その間に上書きする可能性があります
未検証のゲート	lint／型チェック／テスト／ビルドの実行でエラーが発生した、または何も出力されなかったにもかかわらず、その後エージェントの文章が成功したと主張している状態
デフォルトブランチへの編集	コミットやブランチ切り替えを挟まずに main／master 上で 10 個以上のファイルが編集された状態
解決できない SHA	このリポジトリで解決できないコミット SHA を参照するメモリ
大量読み込み	4,000 トークン以上のファイル全体の読み込み、および後続のターンでキャッシュ済みコンテキストとして再送されるトークン数の推定（情報レベルのベースライン）

サポート対象のコンテキストファイル

ファイル	ツール
CLAUDE.md、CLAUDE.local.md、.claude/rules/*.md	Claude Code
AGENTS.md、AGENT.md、AGENTS.override.md	AAIF / Multi-agent standard
.cursorrules、.cursor/rules/*.md、.cursor/rules/*.mdc、.cursor/rules/*/RULE.md	Cursor
.github/copilot-instructions.md、.github/instructions/*.md、.github/git-commit-instructions.md	GitHub Copilot
.windsurfrules、.windsurf/rules/*.md	Windsurf
GEMINI.md	Gemini CLI
.clinerules	Cline
.aiderules	Aider
.aide/rules/*.md	Aide / Codestory
.amazonq/rules/*.md	Amazon Q Developer
.goose/instructions.md、.goosehints	Goose by Block
.junie/guidelines.md、.junie/AGENTS.md	JetBrains Junie
.aiassistant/rules/*.md	JetBrains AI Assistant
.continuerules、.continue/rules/*.md	Continue
.rules	Zed
replit.md	Replit

MCP サーバー設定のリント

ctxlint は、MCP サーバーの設定ファイル（AI クライアントに接続するツールを指定する JSON 設定ファイル）もリントします。これらもコンテキストインターフェースの一種であり、エージェントができることを左右します。

# Lint context files + MCP configs
npx @yawlabs/ctxlint@latest --mcp

# Lint only MCP configs
npx @yawlabs/ctxlint@latest --mcp-only

# Include global/user-level configs (Claude Desktop, Cursor, Windsurf, etc.)
npx @yawlabs/ctxlint@latest --mcp-global

スキャン対象の MCP 設定ファイル

ファイル	クライアント
.mcp.json	Claude Code（汎用プロジェクト設定）
.cursor/mcp.json	Cursor
.vscode/mcp.json	VS Code / GitHub Copilot
.amazonq/mcp.json	Amazon Q Developer
.continue/mcpServers/*.json	Continue

--mcp-global を指定すると、Claude Desktop、Cursor、Windsurf、Amazon Q のグローバル設定ファイルもスキャンします。

MCP 設定チェックで検出できること

チェック	検出内容
スキーマ	無効な JSON、誤ったルートキー（servers と mcpServers の違い）、必須フィールドの不足
セキュリティ	Git で追跡されている設定ファイル内のハードコードされた API キーと Bearer トークン
コマンド	Windows で npx 用の cmd /c ラッパーがないこと、引数内の無効なファイルパス
非推奨	SSE トランスポートの使用（2025 年 3 月に非推奨。Streamable HTTP を使用してください）
環境変数	クライアントに適さない環境変数の構文（${VAR}、${env:VAR}、${{ secrets.VAR }} の違い）
URL	不正な URL、プロジェクト設定内の localhost、パス要素の不足
一貫性	クライアント設定間で同じサーバーの設定が異なること
冗長性	無効化されたサーバー、複数のスコープにある同一の設定

MCP 設定の出力例

MCP Configs
  .mcp.json
    ✗ mcp-security    Server "api": hardcoded Bearer token in a git-tracked file
    ✗ mcp-deprecated  Server "old-svc": SSE transport is deprecated — use "http"
    ✓ mcp-schema
    ✓ mcp-commands
  .cursor/mcp.json
    ✗ mcp-env  Server "api": Cursor uses ${env:VAR}, not ${VAR}
    ✓ mcp-schema
  .vscode/mcp.json
    ✗ mcp-schema  .vscode/mcp.json must use "servers" as root key, not "mcpServers"

Cross-file
    ⚠ Server "api" is configured differently in .mcp.json and .cursor/mcp.json
    ℹ Server "db" is in .mcp.json but missing from .cursor/mcp.json

Summary: 3 errors, 2 warnings, 1 info

MCP 設定リンティング仕様

MCP 設定のリンティングルール、クライアント間の設定状況、および機械可読なルールカタログをまとめた完全な仕様を、オープン仕様として公開しています。

• MCP_CONFIG_LINT_SPEC.md — 完全な lint ルール一式（ルール数は仕様ファミリーの表を参照）、クライアント／形式の完全なリファレンス、実装ガイダンスを掲載しています。ツールに依存しないため、どのリンターでも実装できます。
• mcp-config-lint-rules.json — AI エージェント、CI システム、その他のツールでプログラムから利用できる機械可読なルールカタログです。

セッションのリンティング

ctxlint は AI エージェントのセッションデータ（履歴ファイルやメモリー項目）を監査し、プロジェクト間の一貫性を確認できます。セッションチェックでは、現在のプロジェクトを同階層のリポジトリと比較して、設定のずれや不足を検出します。

# Lint context files + session data
npx @yawlabs/ctxlint@latest --session

# Lint only session data
npx @yawlabs/ctxlint@latest --session-only

セッションチェックは、プロジェクトディレクトリ外のファイル（ホームディレクトリ内のエージェント履歴、親ディレクトリ内の同階層リポジトリ）にアクセスするため、オプトインです。

スキャン対象のセッションファイル

エージェント	履歴	メモリー
Claude Code	~/.claude/history.jsonl	~/.claude/projects/*/memory/*.md
Codex CLI	~/.codex/history.jsonl	—

エージェントが実行した操作（実行したコマンド、書き込みまたは読み取りを行ったファイル）をシグナルとするチェックでは、現在のプロジェクトにある Claude Code のセッショントランスクリプト ~/.claude/projects/<encoded-project>/*.jsonl も読み取ります。対象は直近 5 件に制限されます。

セッションチェックで検出できること

チェック	検出内容
シークレットの不足	gh secret set が 2 つ以上の兄弟リポジトリで実行されている一方、このリポジトリでは実行されていない
設定の乖離	共有設定ファイル（CI ワークフロー、tsconfig、.prettierrc など）で、行の重複率が 20〜90％。関連性はあるものの、乖離し始めているほど異なっている
ワークフローの不足	2 つ以上の兄弟リポジトリにある GitHub Actions ワークフローが、このプロジェクトにはない
古いメモリ	すでに存在しないファイルパスを参照するメモリエントリ
重複したメモリ	プロジェクト間でほぼ重複しているメモリエントリ（重複率 60％超）
ループ検出	エージェントがループに陥っている状態 — 同一コマンドが 3 回以上連続する、または A、B、A、B のような循環パターン
メモリインデックスの超過	MEMORY.md が Claude Code のドキュメントに記載されたセッション読み込み上限（200 行／25KB）を超えており、上限を超えたエントリがエージェントから見えない
共有一時パス	エージェントが書き込み、後で読み返す固定の一時パス（例：/tmp/pkg.bak） — その間に別のセッションが上書きする可能性があります
未検証のゲート	lint／typecheck／test／build がエラーになった、または何も出力しなかった後、エージェントの文章が成功したと主張している
デフォルトブランチでの編集	main／master で 10 個以上のファイルが編集され、その間にコミットもブランチの切り替えもない
解決できない SHA	メモリに記載されたコミット SHA をこのリポジトリで解決できない
大量の読み取り	トークン数が 4,000 以上のファイル全体の読み取りと、後続のターンでキャッシュ済みコンテキストとして再送されるトークン数の推定（情報レベルの基準値）

セッション lint 仕様

• AGENT_SESSION_LINT_SPEC.md — lint ルール一式（仕様ファミリー表に記載されたルール数）、8 つのエージェントにまたがるエージェントセッションデータの全体像、兄弟の検出戦略、実装ガイダンス。
• agent-session-lint-rules.json — 機械可読なルールカタログ。

出力例

ctxlint v0.28.0

Scanning /Users/you/my-app...

Found 2 context files (1,847 tokens total)
  CLAUDE.md (1,203 tokens, 42 lines)
  AGENTS.md -> CLAUDE.md (symlink)

CLAUDE.md
  ✗ Line 12: src/auth/middleware.ts does not exist
    → Did you mean src/middleware/auth.ts? (renamed 14 days ago)
  ✗ Line 8: "pnpm test" — script "test" not found in package.json
  ⚠ Last updated 47 days ago. src/routes/ has 8 commits since.
  ⚠ testing framework conflict: "Vitest" in CLAUDE.md vs "Jest" in AGENTS.md
  ℹ Line 3: "Express" is in package.json dependencies — agent can infer this

Summary: 2 errors, 2 warnings, 1 info
  Token usage: 1,203 tokens per agent session
  Estimated waste: ~55 tokens (redundant content)

オプション

Usage: ctxlint [options] [command] [path]

Arguments:
  path                 Project directory to scan (default: ".")

Options:
  --strict                  Exit code 1 on any warning or error (for CI)
  --checks <list>           Comma-separated checks to run (see below)
  --ignore <list>           Comma-separated checks to skip
  --fix                     Auto-fix broken paths using git history and fuzzy matching
  --fix-dry-run             Preview --fix changes without writing
  --yes                     Skip interactive confirmation prompts (required for --fix in TTY)
  --follow-symlinks         Allow --fix to write through symlinks (default: skip)
  --format <fmt>            Output format: text, json, or sarif (default: text)
  --tokens                  Show token breakdown per file
  --verbose                 Show passing checks too
  --quiet                   Suppress all output except errors (exit code only)
  --config <path>           Path to config file (default: .ctxlintrc in project root)
  --depth <n>               Max subdirectory depth to scan (default: 2)
  --mcp                     Enable MCP config linting alongside context file checks
  --mcp-only                Run only MCP config checks, skip context file checks
  --mcp-global              Also scan user/global MCP config files (implies --mcp)
  --session                 Enable session audit checks (cross-project consistency)
  --session-only            Run only session checks, skip context and MCP checks
  --skills                  Run agent-skill checks (~/.claude/skills + ~/.claude/agents)
  --skills-only             Run only agent-skill checks, skip everything else
  --hooks-global            Also scan the user-global ~/.claude/settings.json in the
                            dead-hook check (default scans project .claude/ only)
  --mcp-server              Start the MCP server (alias: `serve` subcommand)
  --lsp                     Start in LSP server mode (JSON-RPC over stdio for editor integration)
  --no-ignore-file          Disable .ctxlintignore suppression (see all findings)
  --watch                   Re-lint on context file changes
  -V, --version             Output the version number
  -h, --help                Display help

Commands:
  init                 Set up a git pre-commit hook
  serve                Start the MCP server (same as --mcp-server)

利用可能なチェック： paths、commands、staleness、tokens、tier-tokens、redundancy、contradictions、frontmatter、ci-coverage、ci-secrets、content-secrets、hook-coverage、mcp-schema、mcp-security、mcp-commands、mcp-deprecated、mcp-env、mcp-urls、mcp-consistency、mcp-redundancy、session-missing-secret、session-diverged-file、session-missing-workflow、session-stale-memory、session-duplicate-memory、session-loop-detection、session-memory-index-overflow、session-shared-temp-path、session-unverified-gate-claimed-clean、session-default-branch-accumulation、session-unresolvable-sha、session-large-read、skill-frontmatter、skill-broken-ref、skill-trigger-collision、skill-orphaned、skill-dead-tool-restriction

mcp-* チェック名を渡すと、--mcp が指定されたものとみなされます。session-* チェック名を渡すと、--session が指定されたものとみなされます。skill-* チェック名を渡すと、--skills が指定されたものとみなされます。

ウォッチモード

npx @yawlabs/ctxlint@latest --watch

コンテキストファイル、MCP 設定、または package.json に変更があると、自動的に再 lint します。コードと並行してコンテキストファイルを編集する開発時に便利です。

CI での使用

- name: Lint context files
  run: npx @yawlabs/ctxlint@latest --strict

終了コード

コード	意味
0	成功 — 問題がない、または問題が厳格モードのしきい値を下回っている
1	厳格モードで少なくとも 1 件のエラーまたは警告が検出された（--strict が設定されている）
2	設定エラー、無効な CLI オプション、または内部エラー

非厳格モードでは、ctxlint は常に 0 で終了します。デフォルトではレポートツールとして動作します。CI で適用を強制するには、--strict を渡してください。

GitHub Action

- name: Lint context files
  uses: yawlabs/ctxlint-action@v1

または、オプションを指定する場合：

- name: Lint context files
  uses: yawlabs/ctxlint-action@v1
  with:
    args: '--strict --mcp'

SARIF 出力（GitHub Code Scanning）

- name: Lint context files
  run: npx @yawlabs/ctxlint@latest --format sarif > ctxlint.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: ctxlint.sarif

自動修正

npx @yawlabs/ctxlint@latest --fix

壊れたパスが git で名前変更されている場合、またはプロジェクト内に一致するパスがある場合、--fix はコンテキストファイルを自動的に書き換えます。

コミット前フック

組み込み

npx @yawlabs/ctxlint@latest init

各コミットの前に ctxlint --strict を実行する git コミット前フックを設定します。

pre-commit フレームワーク

.pre-commit-config.yaml に追加します：

repos:
  - repo: https://github.com/yawlabs/ctxlint
    rev: v0.28.0
    hooks:
      - id: ctxlint

設定ファイル

プロジェクトのルートに .ctxlintrc または .ctxlintrc.json を作成します：

{
  "checks": ["paths", "commands", "tokens", "contradictions", "frontmatter"],
  "ignore": ["redundancy"],
  "ignoreRules": [
    { "check": "paths", "match": "^docs/archive/", "reason": "archived docs cite removed files" }
  ],
  "strict": true,
  "tokenThresholds": {
    "info": 500,
    "warning": 2000,
    "error": 5000,
    "aggregate": 4000,
    "tierBreakdown": 1000,
    "tierAggregate": 4000
  },
  "contextFiles": ["CONVENTIONS.md", "docs/ai-rules.md"],
  "exclude": ["fixtures/**", "examples/**"]
}

contextFiles 配列を使うと、組み込みのリストにカスタムファイルパターンを追加してスキャンできます。CONVENTIONS.md のようなプロジェクト固有のコンテキストファイルに便利です。

exclude 配列はその対となるもので、スキャン対象から完全に除外するコンテキストファイルの glob を指定します。テスト用フィクスチャ、サンプルプロジェクト、ベンダー提供のテンプレートなど、このプロジェクトのエージェントコンテキストではないファイルに使用します。

exclude はファイルを除外します。一方、ignore／ignoreRules／.ctxlintignore は検出結果を抑制します。この違いは、ファイル間チェックで重要です。contradictions と redundancy/duplicate-content は検出されたファイル群を比較し、どのファイル単位の glob にも一致しないリテラルパス (project) を対象として報告します。lint 対象にするつもりのなかった 2 つのファイル間の矛盾を抑制する唯一の方法は、ファイル自体を除外することです。実際のコンテキストファイルでノイズとなる検出結果が 1 件ある場合は .ctxlintignore を使用し、そのファイルを対象に含めるべきでない場合は exclude を使用してください。

設定リファレンス

フィールド	型	デフォルト	意味
checks	string[]	すべてのチェック	実行するチェックです。チェック名には paths、commands、tokens、tier-tokens、redundancy、contradictions、frontmatter、staleness、ci-coverage、ci-secrets、content-secrets、hook-coverage のほか、任意の mcp-* / session-* / skill-* が含まれます。
ignore	string[]	[]	スキップするチェックです。checks の評価後に適用されます。
ignoreRules	object[]	[]	検出結果ごとの抑制設定で、ignore より詳細に指定できます。各ルールは一致した検出結果だけを除外し、最初に一致したルールが適用されます。一度も適用されないルールと reason がないルールは、テキストレポートと JSON の _meta.ignoreReport に表示されます。
ignoreRules[].check	string	必須	ルールを適用するチェックを、正確な名前（paths、session-stale-memory など）で指定します。
ignoreRules[].match	string	なし	検出結果のメッセージに対して評価する正規表現です。match と pathPattern のどちらも指定しないルールは、そのチェックのすべての検出結果を除外します。両方を指定した場合は、両方に一致する必要があります。
ignoreRules[].pathPattern	string	なし	検出結果に記載された各パスに対して評価する正規表現です。すべてのパスが一致した場合にのみルールが適用されます。session-stale-memory にのみ適用されます。それ以外のチェックではルールは適用されず、設定の読み込み時に警告が表示されます。
ignoreRules[].reason	string	なし	検出結果を抑制する理由です。省略可能ですが、指定しない場合は確認用にレポートへ表示されます。
strict	boolean	false	警告またはエラーが1つでもある場合、ゼロ以外の終了コードで終了します。
tokenThresholds	object	下記を参照	ファイルごと、および複数ファイルをまたぐトークンしきい値です。
tokenThresholds.info	number	1000	tokens/info のファイルごとの情報しきい値です。
tokenThresholds.warning	number	3000	tokens/large のファイルごとの警告しきい値です。
tokenThresholds.error	number	8000	tokens/excessive のファイルごとのエラーしきい値です。
tokenThresholds.aggregate	number	5000	tokens/aggregate の複数ファイル合計しきい値です。
tokenThresholds.tierBreakdown	number	1000	tier-tokens/section-breakdown の常時読み込みファイルしきい値です。
tokenThresholds.tierAggregate	number	4000	tier-tokens/aggregate の常時読み込みファイル合計しきい値です。
contextFiles	string[]	[]	組み込みリストと併せてスキャンする追加の glob パターンです。
exclude	string[]	[]	スキャン対象から完全に除外するコンテキストファイルの glob です。各ファイルのプロジェクト相対パスに対して照合します。除外ファイルは検出結果を抑制するのではなく、スキャン対象から取り除くため、ファイル間チェックでも参照されません。
mcp	boolean	false	MCP 設定チェックをデフォルトで有効にします（--mcp と同じです）。
mcpOnly	boolean	false	MCP 設定チェックのみを実行し、コンテキストファイルのチェックをスキップします（--mcp-only と同じです）。
mcpGlobal	boolean	false	ユーザー／グローバル MCP 設定もスキャンします（--mcp-global と同じです）。
session	boolean	false	セッション監査チェックを有効にします（プロジェクト間の整合性を確認します）。--session と同じです。
sessionOnly	boolean	false	セッションチェックのみを実行し、コンテキストと MCP のチェックをスキップします（--session-only と同じです）。
skills	boolean	false	エージェントスキルチェックを有効にします（~/.claude/skills と ~/.claude/agents）。--skills と同じです。
skillsOnly	boolean	false	エージェントスキルチェックのみを実行し、その他すべてをスキップします（--skills-only と同じです）。
hooksGlobal	boolean	false	デッドフックチェックで、ユーザーのグローバル設定 ~/.claude/settings.json もスキャンします（--hooks-global と同じです）。
設定ファイルの解決順序：プロジェクトルートの .ctxlintrc → .ctxlintrc.json。別の場所を指定するには --config <path> を使用します。CLI フラグは設定フィールドより優先されます。

CLI フラグは設定ファイルの設定より優先されます。カスタムの場所から設定を読み込むには --config <path> を使用します。

Ignore ファイル（.ctxlintignore）

プロジェクトルートに .ctxlintignore ファイルを置くと、.ctxlintrc を変更せずに検出結果を抑制できます。各行は 1 つのルールで、checkName [fileGlob] [# reason] の形式です。

# Blank lines and lines starting with # are skipped.
paths                    # every paths finding, in every file
tokens CLAUDE.md         # tokens findings in CLAUDE.md only
redundancy .claude/**    # redundancy findings in files under .claude/

• checkName は、Options の Available checks リストにある名前（paths、tokens、mcp-security など）であり、ルール ID ではありません。チェック名以外の名前も拒否されませんが、ルールに一致しないため、発火しなかったルールとして報告されます。
• fileGlob は省略可能です。指定しない場合、ルールはすべてのファイルに適用されます。指定した場合、パスが一致するファイル内の検出結果にのみ適用されます。パスは ctxlint が出力するプロジェクト相対パスで、すべてのプラットフォームでスラッシュが使われ、ドットファイルも含まれます。contradictions と redundancy/duplicate-content によるファイル横断の検出結果は、パス (project) に対して報告されます。この場合は、そのリテラルに一致させます（contradictions (project)）。
• # reason の前にはスペースが必要です。paths#legacy の場合、トークン全体がチェック名として読み込まれます。読み込まれるのは最初の 2 つのトークンのみのため、ここではメッセージ正規表現を指定できません。代わりに ignoreRules を使用してください。
• glob 付きのルールはファイル内の順序で先に適用され、その後、glob なしのルールと ignoreRules が適用されます。検出結果は、最初に一致したルールによって除外されます。
• 除外された件数、何も除外しなかったルール、理由のないルールは、ignoreRules と同じ「Ignore rules」レポートに一覧表示されます。
• --no-ignore-file を指定すると、その実行ではファイルがスキップされます。ignoreRules は引き続き適用されます。--watch では、ファイルが変更されると再度 lint が実行されます。

MCP サーバーとして使う

ctxlint には、7 つのツール（ctxlint_audit、ctxlint_mcp_audit、ctxlint_session_audit、ctxlint_skill_audit、ctxlint_validate_path、ctxlint_token_report、ctxlint_fix）を公開する MCP サーバーが付属しています。読み取り専用のツールはすべてアノテーションを宣言しているため、MCP クライアントは確認ダイアログを省略できます。

serve サブコマンド（または互換性維持のために残されている同等の --mcp-server フラグ）で起動します。

npx -y @yawlabs/ctxlint@latest serve

Claude Code で使う

claude mcp add ctxlint -- npx -y @yawlabs/ctxlint@latest serve

.mcp.json を使う（Claude Code のプロジェクト設定、Cursor、Windsurf）

プロジェクトルートに .mcp.json を作成します。

macOS / Linux / WSL：

{
  "mcpServers": {
    "ctxlint": {
      "command": "npx",
      "args": ["-y", "@yawlabs/ctxlint@latest", "serve"]
    }
  }
}

Windows：

{
  "mcpServers": {
    "ctxlint": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@yawlabs/ctxlint@latest", "serve"]
    }
  }
}

ヒント： このファイルにはシークレットが含まれていないため、安全にコミットできます。

VS Code / GitHub Copilot で使う

.vscode/mcp.json に追加します。

{
  "servers": {
    "ctxlint": {
      "command": "npx",
      "args": ["-y", "@yawlabs/ctxlint@latest", "serve"]
    }
  }
}

Claude Desktop で使う

Claude Desktop の設定（claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "ctxlint": {
      "command": "npx",
      "args": ["-y", "@yawlabs/ctxlint@latest", "serve"]
    }
  }
}

JSON 出力

npx @yawlabs/ctxlint@latest --format json

すべてのファイルの結果、問題、概要を含む構造化 JSON を返します。インテグレーションやダッシュボードの構築に便利です。

仕様

ctxlint は、AI エージェントのインターフェースをリントするための4つのオープン仕様のリファレンス実装です。これらの仕様は特定のツールに依存しないため、どのリンター、IDE 拡張機能、CI システムでも実装できます。

仕様	対象
AI Context File Linting Spec	16のクライアントでコンテキストファイル（CLAUDE.md、.cursorrules、AGENTS.md など）を検証する43のルールです。ファイル形式、フロントマターのスキーマ、パス／コマンドの検証、古さ、トークン予算、重複、矛盾を対象とします。
MCP Config Linting Spec	8つのクライアントで MCP サーバー設定（.mcp.json、.cursor/mcp.json、.vscode/mcp.json など）を検証する29のルールです。スキーマ検証、ハードコードされたシークレット、環境変数の構文、非推奨のトランスポート、ファイル間の整合性を対象とします。
Agent Session Linting Spec	8つのエージェントでエージェントのセッションデータ（履歴、メモリ）を監査する13のルールです。プロジェクト間のシークレットの整合性、設定のドリフト、古くなったメモリ、ループ検出を対象とします。
Agent Skill Linting Spec	~/.claude 配下にある Claude Code のスキル（SKILL.md）とエージェント（.md）の定義を監査する5つのルールです。フロントマターの有無、壊れた参照、トリガーフレーズの衝突、孤立したスキル、使用されていないツール制限を対象とします。（v1、実験的）

すべての仕様には、プログラムから利用できる機械可読なルールカタログが含まれています。

• context-lint-rules.json — コンテキストファイルのルールと、サポートされる16の形式の定義
• mcp-config-lint-rules.json — MCP 設定のルールと、8つのクライアントの定義
• agent-session-lint-rules.json — セッションのリントルールと、8つのエージェントデータソースの定義
• agent-skill-lint-rules.json — エージェントスキルのリントルール（~/.claude/skills、~/.claude/agents）

Yaw Labs のその他のプロジェクト

• Yaw — AI ネイティブなターミナル

ライセンス

MIT