コンテキスト監査

コンテキスト監査 は何をしますか？

この規約を採用したリポジトリは、小さな永続ファイル群を維持することで、エージェントがセッションごとに同じことを再導出しないようにします。プロジェクトの規約（AGENTS.md）、既に決定済みでその理由（memory.md）、コードベースのおおまかな構成（.agent/graph.md）です。このスキルは、それらのファイルが存在し、最新であるかを、それらに依存する前、または手動でリポジトリをスキャンする前にチェックします。

トリガーフレーズ

セッション開始 / 信頼性チェック

• 「このリポジトリについて説明して」
• 「このプロジェクトについて知ってることは？」
• 「AGENTS.md / memory.md は信頼していい？」
• 「コンテキストファイルは最新？」
• 「コンテキストをチェック」 / 「コンテキスト監査」

陳腐化

• 「AGENTS.md は古い？」 / 「memory.md は古い？」
• 「前回の同期からどのくらいコミットがある？」
• 「エージェントファイルは最新？」
• 「コンテキストが古くなっていないかチェック」

トークンコスト

• 「コンテキストファイルでどのくらい節約できる？」
• 「トークン節約額」 / 「コンテキストコスト」
• 「トークン節約のベンチマーク」
• 「ベースライン vs キュレーショントークン」

セットアップ / オンボーディング

• 「AGENTS.md をスキャフォールド」 / 「コンテキストを初期化」
• 「ctx-audit をインストール」 / 「コンテキストフックを設定」
• 「AIコンテキストをセットアップ」 / 「このプロジェクトはAI対応？」

CI / 自動化

• 「ctx-audit をCIに追加」
• 「pre-pushフックを追加」
• 「CIでコンテキストの鮮度を強制」

アーキテクチャ

• 「アーキテクチャマップはある？」
• 「graph.md を生成」 / 「graphify を実行」

実行方法

ctx-audit の推奨実行方法：

npx ctx-audit

あるいは、スキルとしてインストールされている場合：

node <path-to-this-skill-folder>/../scripts/audit.mjs

フラグ：

• --json — 機械可読な出力（結果をプログラム的に処理する場合に使用）。
• --strict — 欠落または古いファイルがある場合、終了コード1を返す。
• --ci — --strict --json のエイリアス。
• --help — 使用方法を表示して終了。

サブコマンド

# AGENTS.md + memory.md をスキャフォールド（対話形式、リポジトリルートに直接ファイルを書き込み）
npx ctx-audit init

# ワンコマンドインストール：スキルを ~/.claude/skills/ にコピーし、CLAUDE.md に登録
npx ctx-audit install

# Gitフック：プッシュごとに --strict 監査を実行
npx ctx-audit hook install
npx ctx-audit hook status
npx ctx-audit hook uninstall

# プロジェクト CLAUDE.md：エージェント用の指示ブロックを追加
npx ctx-audit claude install
npx ctx-audit claude uninstall

# トークン節約レポート（焦点を絞った共有可能な形式）
npx ctx-audit benchmark

エージェント判断テーブル

ステータス	意味	アクション
FRESH	前回の同期からのコミット数が陳腐化閾値の半分未満	ファイルを信頼 — 生のソースをスキャンする代わりに読む
STALE?	閾値に近づいている（陳腐化の可能性あり）	軽度の注意 — 依存する前に重要な主張をスポットチェック
STALE!	閾値を超えており、失敗とみなす	主張は未検証として扱う；実際のコードと照らし合わせてスポットチェック；セッション後に更新
STALE	大幅に遅れており、失敗とみなす	STALE! と同様だがより緊急；セッション後すぐに更新
MISSING（必須）	ファイルが存在しない	npx ctx-audit init を実行；規約が整っているとみなして進めない
absent（オプション）	オプションファイルがない	許容可能；graph.md を生成するために /graphify の実行を検討
over budget	トークン数が maxTokens を超過	ファイルが肥大化している — トリミングする；読むことで節約以上のコストがかかる可能性あり
dead reference	ファイル内のバッククォートパスまたは dir/file.ext がディスク上に存在しない	参照を更新；ファイルは古い構造を文書化している
SHA bumped	last_synced_commit が更新されたが、本文は変更なし	ファイルが実際に最近の変更を反映しているか確認；機械的な更新の可能性あり

結果の解釈

• MISSING（必須ファイル）：規約が整っているとみなして進めない。 スターターファイルをスキャフォールドする（npx ctx-audit init を実行）ことを提案し、 ファイルなしで作業したり、古い「すべて手動で探索する」アプローチを黙って行わないようにする。
• FRESH：ファイルは最新。生のソースをスキャンする代わりに読む。
• STALE?（陳腐化の可能性あり）：閾値に近づいている。重要な主張をスポットチェック。
• STALE!（ほぼ確実に陳腐化）：その主張は未検証として扱う。重要な主張は実際のコードと照らし合わせてスポットチェックし、セッション後にファイルとその last_synced_commit を更新する。
• STALE：大幅に遅れている。STALE! と同様の扱いだが、より緊急。
• トークン数は約3.5文字/トークンのヒューリスティックに基づく — 方向性としては有用だが、正確ではない。ファイルが「予算超過」とフラグされた場合、読むことで節約するはずだったコストがかかり始めるほど肥大化している；トリミングを提案する。
• デッド参照警告：コンテキストファイルに記述されたパスがディスク上に存在しない。ファイルが古い構造を参照していることを示す。

動作例

セッション開始時の基本的な監査：

npx ctx-audit

CIゲート（コンテキストが古い場合にビルドを失敗させる）：

# .github/workflows/ctx-audit.yml
- name: コンテキストの鮮度を監査
  run: npx ctx-audit --strict

プログラム利用のためのJSON出力：

npx ctx-audit --json | jq '.checks[] | {file, stalenessLevel, stale}'

ワンコマンドオンボーディング：

npx ctx-audit install        # スキルをコピー、CLAUDE.md に登録
npx ctx-audit hook install   # pre-pushガードを追加
npx ctx-audit claude install # プロジェクト CLAUDE.md に注意書きを追加
npx ctx-audit init           # AGENTS.md + memory.md をスキャフォールド

特定のサブシステムの陳腐化のみをチェック（frontmatter経由）：

---
last_synced_commit: abc1234
watches: src/auth/**, src/api/**
---

このファイルの場合、src/auth/ または src/api/ に影響するコミットのみが陳腐化のカウント対象となる。

トークン節約のベンチマーク：

npx ctx-audit benchmark

設定

リポジトリルートに .ctx-audit.json を配置して動作をカスタマイズ：

{
  "files": [{ "id": "...", "file": "...", "label": "...", "maxTokens": N, "required": true }],
  "sourceDirs": ["src", "packages/core"],
  "staleThreshold": 10,
  "baselineFileCap": 300
}

フロントマター

各コンテキストファイルはフロントマターで始める必要があります：

---
last_synced_commit: <git sha>
watches: src/auth/**, src/api/**
---

watches フィールド（オプション）は、すべてのソースディレクトリではなく、指定されたパスに影響するコミットのみに陳腐化チェックを限定します。

必須ファイルがない場合 — スキャフォールドする

npx ctx-audit init を実行してテンプレートを生成します。TTYではリポジトリルートに直接ファイルを書き込み、パイプ時はstdoutに出力します。レガシーな --init フラグも後方互換エイリアスとしてサポートされています。

AGENTS.md — 安定したプロジェクト規約：ビルド/テスト/リンタコマンド、ファイルレイアウトルール、エージェントが絶対にやってはいけないこと。頻繁に変更されるべきではありません。

memory.md — 現在のコードの再記述ではなく、実行中の決定ログ。各エントリ：試みたこと、決定したこと、その理由、状況が変わった場合に再検討すべきこと。履歴を書き換えずに追記してください。

.agent/graph.md（オプションですが、リポジトリが大きくなったら推奨） — 主要モジュールごとに1段落で、その責務と通信相手を説明します。ファイル内容や網羅的なツリーではなく、エージェントがすべてを再読しなくてもナビゲートできる程度の情報で十分です。 ヒント：手動で書く代わりに、/graphify を実行してコードベースから自動生成することもできます。

これらのファイルをスキャフォールドまたは更新した後は、last_synced_commit を現在のHEADに更新して、次の監査ですぐに古いとフラグされないようにしてください。