🧹 技術調査 - AGENTS.md・CLAUDE.md 設定ファイルの設計臭6分類

調査対象: 論文 Configuration Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents (arXiv 2606.15828v1, 2026-06-14)
著者: Helio Victor F. dos Santos, Vitor Costa, João Eduardo Montandon, Luciana Lourdes Silva, Marco Túlio Valente
レプリケーションパッケージ: https://doi.org/10.5281/zenodo.20600327

この論文は、コーディングエージェント向け設定ファイル (AGENTS.md / CLAUDE.md) の品質問題を 6 種類の configuration smell (設定の設計臭) として体系化した研究です。本記事は提案された方法論の論理構造・概念モデル・実務への適用案をまとめます。コード例・プロンプト・CI ワークフローは「実装案/例」であり、論文が提示したコードそのものではありません。

概要

本論文は、AGENTS.md / CLAUDE.md の不適切な記述パターンを configuration smell と命名し、6 種類のカタログを定義した研究です。

研究は二段構成です。まず、グレー文献レビュー (ブログ・Hacker News 記事等 532,000 件から 14 件を精選) によって smell の種類を確定しました。次に、GitHub の star 上位 100 リポジトリに対するマイニングで prevalence (出現率) を測定しました。

結果として、調査対象 100 ファイルのうち 91 ファイル (91%) が 1 つ以上の smell を含むことが明らかになりました。これは設定ファイルの品質管理が現場でほぼ手つかずであることを示します。

本論文の位置づけは、Dockerfile・GitLab CI/CD などの構成ファイルへのコードスメル研究の系譜を、コーディングエージェントの設定ファイルへ初めて適用した点にあります。単なる記述的分析にとどまらず、規範的な品質基準 (何が悪いか・どう直すか) を提示しています。

関連研究との比較

先行研究は「何が書かれているか」または「効果があるか」を問いました。本論文は「何が問題か・どう直すか」という規範的問いを初めて提起し、smell カタログと自動検出手法を提供します。

特徴

• 6 種類の configuration smell カタログ: Lint Leakage / Context Bloat / Skill Leakage / Conflicting Instructions / Init Fossilization / Blind References の 6 分類を定義します。出現率は最頻の Lint Leakage (62%) から Blind References (16%) まで分布します。
• LLM ベース検出: 4 種類の smell を gemini-3.1-flash-lite (temperature=0) で自動検出し、第一著者が手動検証します。Lint Leakage は precision 93%、Blind References は 87% を達成しました。
• ルールベース検出: Context Bloat は LOC 200 行以上、Init Fossilization は作成後の commit 数 1 という閾値で機械的に判定します。
• 91% 有病率: 100 ファイル中 91 ファイルが少なくとも 1 つの smell を保有します。smell-free は 9 ファイルのみです。
• 共起分析: Conflicting Instructions が存在するファイルは Context Bloat も伴う確率が 81% (lift 1.76) です。設定問題は単独でなく複合的に発生する傾向があります。
• 実例つき remediation: 各 smell に悪例・良例のコード断片と修正ガイダンスを付与し、即実践可能な改善手順を提示します。
• PR 分析による具体例補強: 100 ファイルの commit (760 件) から PR (383 件) を辿り、関連 PR (17 件) のうち設定問題を議論する 2 件を具体例として利用します。検出結果全体の妥当性検証ではありません。

構造

本セクションでは、論文が提案する研究方法論を C4 モデルの 3 段階に読み替えて記述します。「システム」は smell 検出研究フレームワーク全体、「コンテナ」は方法論の主要コンポーネント、「コンポーネント」は検出パイプラインの内部構造を指します。

システムコンテキスト図

Configuration Smell 分析フレームワークを中心に、関与するアクターと外部システムを示します。

要素一覧

コンテナ図

フレームワークを構成する主要コンポーネントとデータの流れを示します。

グレー文献レビュー・カタログ

リポジトリマイニング

検出・検証・分析

コンポーネント図

検出パイプライン内部の 3 サブシステムと、各 smell との対応を示します。

LOC カウンター

LLM 検出器

Commit アナライザー

データ

論文が扱う概念をエンティティとしてモデル化します。

概念モデル

論文が操作する主要エンティティと所有・参照関係を示します。

概念モデル 説明

情報モデル

各エンティティの主要属性と多重度を示します。

ConfigurationFile

ConfigurationSmell

DetectionMethod

LeakedSkillCategory

CoOccurrenceRule

6 smell の一覧 (prevalence 降順)

共起ルール (論文 Table IV 全 6 件)

計 14 件のグレー文献を採用 (初期 532,000 件 → 上位 30 件 (最初の 3 ページ) を手動精査 → 16 件除外)。品質統制として 6 件は著名企業 (Anthropic, GitHub) 由来、8 件は経験豊富な著者、3 件は Hacker News 140+ upvote の文書が含まれます。

6 つの設定の設計臭

ここからは 6 分類を、定義・実例・改善 (Before/After) でまとめます。

構築方法: 検出環境の用意

本セクションのコード・プロンプト・スクリプトはすべて「実装案/例」です。論文 (arXiv 2606.15828) の方法論を実務に適用するための具体化であり、論文が提示したコードそのものではありません。論文由来の値 (200 行, temperature=0, gemini-3.1-flash-lite, commit=1) は出典を明示して使用します。

検出パラメータ一覧

Context Bloat 検出: 行数チェック

最も手軽なルールベース検出です。200 行以上であれば Context Bloat の疑いありと判定します。

#!/usr/bin/env bash
# context_bloat_check.sh - Context Bloat smell を行数で検出する実装案

THRESHOLD=200  # 論文の Context Bloat 節の閾値

for f in AGENTS.md CLAUDE.md .claude/agents/*.md; do
  [ -f "$f" ] || continue
  lines=$(wc -l < "$f")
  if [ "$lines" -ge "$THRESHOLD" ]; then
    echo "SMELL: Context Bloat  file=$f  lines=$lines  threshold=$THRESHOLD"
  else
    echo "OK: $f ($lines lines)"
  fi
done

論文の実例: javascript-obfuscator の CLAUDE.md は 1,477 行・27 セクションで、Key Features (難読化技法の解説) は README 向きの内容でした。

Init Fossilization 検出: commit 数チェック

設定ファイルの git commit 数が 1 のみである場合、/init 等で生成後に更新されていない疑いがあります。

#!/usr/bin/env bash
# init_fossilization_check.sh - Init Fossilization smell を commit 数で検出する実装案

for f in AGENTS.md CLAUDE.md; do
  [ -f "$f" ] || continue
  commit_count=$(git log --oneline --follow "$f" | wc -l)
  if [ "$commit_count" -eq 1 ]; then
    echo "SMELL: Init Fossilization  file=$f  commits=$commit_count"
    echo "  リポジトリ全体の commit 数: $(git rev-list --count HEAD)"
  else
    echo "OK: $f ($commit_count commits)"
  fi
done

論文の検証: Init Fossilization が検出されたリポジトリは活発に開発が続くプロジェクトであり、設定ファイルだけが放置されていることを確認しました。

LLM ベース検出: プロンプト実装案

論文は Lint Leakage / Skill Leakage / Blind References / Conflicting Instructions の 4 種類を gemini-3.1-flash-lite (temperature=0) で検出しました。論文が示すプロンプトテンプレートの構造は次のとおりです。

[役割付与] You are a senior software engineer.

[タスク定義] 設定ファイル (AGENTS.md) を渡すので、次の configuration smell が含まれるか検出してください。

[Smell 定義] <smell_name>: <smell の説明>

[ガイドライン / True & False Positive 例]  ← Blind References, Conflicting Instructions のみ追加

[出力フォーマット]
検出された場合: 該当行 (または矛盾の文脈を含む JSON) を返す。
検出されない場合: NO SMELL とだけ返す。

# Agents.md file
<ファイル本文>

以下は Lint Leakage 検出プロンプトの実装案です。検出精度を再現するには論文と同じモデル・温度を使用してください。

# lint_leakage_prompt.py - Lint Leakage 検出プロンプト実装案
LINT_LEAKAGE_PROMPT = """You are a senior software engineer.

I will provide an agent configuration file (AGENTS.md or CLAUDE.md).
Detect whether the file contains the following configuration smell.

Lint Leakage: The file contains rules already enforced by linters, formatters,
or static analysis tools (indentation, line length, import order, naming
conventions, docstring format). They are redundant because tools such as Ruff,
Black, Biome, or ESLint enforce them automatically.

If detected: return the exact lines that contain the redundant linting rules.
If not detected: return only: NO SMELL

# Agents.md file
{file_content}
"""

Blind References と Conflicting Instructions は、真陽性/偽陽性の例を付与した強化版プロンプトを使用します。

# conflicting_instructions_prompt.py - 強化版プロンプト実装案 (抜粋)
CONFLICTING_INSTRUCTIONS_PROMPT = """You are a senior software engineer.

Conflicting Instructions: two or more instructions contradict each other,
leading to ambiguous agent behavior (contradictory directory paths for the same
artifact, conflicting naming conventions, mutually exclusive workflow steps).

True positive: "Place components in packages/ui/components" AND
  "Create a new folder in packages/components for new components"
False positive: "snake_case for Python files" AND "camelCase for JavaScript"
  (different languages, no contradiction)

If detected: return a JSON object {"conflict": ..., "line_a": ..., "line_b": ...}
If not detected: return only: NO SMELL

# Agents.md file
{file_content}
"""

検出スクリプトの呼び出し例です。モデル名は実行時に利用可能な ID を確認してください。なお SDK は google-generativeai (旧 SDK) と google-genai (新 SDK) で API が異なるため、使用するパッケージのバージョンに合わせて記法を確認してください。

#!/usr/bin/env python3
# detect_smells.py - LLM ベース smell 検出を実行する実装案
# pip install google-generativeai
import google.generativeai as genai
import json, sys
from pathlib import Path

MODEL = "gemini-3.1-flash-lite"  # 論文の検出手法節で使用されたモデル
TEMPERATURE = 0  # 論文指定: 決定的出力

PROMPTS = {
    "lint_leakage": LINT_LEAKAGE_PROMPT,
    "conflicting_instructions": CONFLICTING_INSTRUCTIONS_PROMPT,
    # skill_leakage, blind_references も同様に定義する
}

def detect(file_path: str) -> dict:
    content = Path(file_path).read_text()
    model = genai.GenerativeModel(MODEL)
    results = {}
    for name, template in PROMPTS.items():
        prompt = template.format(file_content=content)
        resp = model.generate_content(
            prompt,
            generation_config=genai.GenerationConfig(temperature=TEMPERATURE),
        )
        results[name] = resp.text.strip()
    return results

if __name__ == "__main__":
    target = sys.argv[1] if len(sys.argv) > 1 else "CLAUDE.md"
    print(json.dumps(detect(target), ensure_ascii=False, indent=2))

利用方法: 検出結果を使った修正

検出結果の読み方

Lint Leakage の修正 (Before / After)

Before: AGENTS.md にコードスタイルルールを直書きしている例 (google/adk-python の実例に基づく)。

## Python Style Guide
- Use 2 spaces for indentation
- Maximum line length: 80 characters
- Use snake_case for functions and variables
- Use CamelCase for class names
- All public functions must have docstrings

After: フォーマット系は linter に委譲し、CLAUDE.md からは削除します。

# pyproject.toml (実装例)
[tool.ruff]
line-length = 80
indent-width = 2

[tool.ruff.lint]
select = ["E", "F", "I"]   # pycodestyle + pyflakes + isort

# .pre-commit-config.yaml (実装例)
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.0   # 実装時は最新版を確認すること
    hooks:
      - id: ruff
      - id: ruff-format

CLAUDE.md には linter で表現できないアーキテクチャ制約・ドメインルール・安全ポリシーのみを残します。論文によれば、実例 google/adk-python の Python Style Guide は後にメンテナーが別 skill ファイルへリファクタしており、smell の妥当性が実証されたとされています。

Skill Leakage の修正 (Before / After)

Before: AGENTS.md にタスク固有の手順を直書きしている例 (quickemu-project/quickemu の実例に基づく)。

## Adding a new OS to quickget
1. Add an entry to the os_info() case statement
2. Add a releases_<os>() function returning available versions
3. Add an editions_<os>() function if multiple editions exist
4. Add an arch_<os>() function if ARM64 is supported
5. Add the download URL construction logic

After: 専用の skill ファイルへ退避し、AGENTS.md にはファイルの存在と目的のみを記述します。

<!-- AGENTS.md 修正後 -->
## Skill Files
When adding a new OS to quickget, follow the procedure in
`docs/skills/add-new-os.md`.

Claude Code であれば .claude/skills/add-new-os/SKILL.md 構造で退避します。Skill Leakage が多い場合は論文 Table III のカテゴリ (Testing / Workflow / Scaffolding / Infrastructure / Architecture) を参考に分類します。

Context Bloat の修正方針

Before: 1 ファイルに 200 行超の内容が混在している状態 (javascript-obfuscator の実例: 1,477 行)。

After: 150〜200 行以内に収め、専門知識は別ファイルへ退避する方針です。

CLAUDE.md (目標: 150 行以内)
  - プロジェクト概要 (10 行)
  - ディレクトリ構成 (20 行)
  - 重要なアーキテクチャ制約 (30 行)
  - skill ファイルへの参照一覧 (10 行)

.claude/skills/obfuscation-options/SKILL.md
  - 難読化技法の詳細

docs/api-reference.md
  - API リファレンス全項目

分割の基準は、README 向けの機能説明・API 一覧・チュートリアルを CLAUDE.md に含めないことです。

Blind References の修正 (Before / After)

Before: パスや URL だけで目的を説明しない参照 (SuperClaude_Framework の実例に基づく)。

See `docs/plugin-reorg.md` for details.

After: 目的・スコープ・使う場面を付与します (browser-use の良い例を参考にした実装案)。

## 参照ドキュメント
`docs/plugin-reorg.md` — プラグインディレクトリの移行ガイド。
v5 以降の新規プラグインを追加する際、または既存プラグインのパスを変更する際に参照する。
移行前後のパス対応表と CI 設定の更新手順を含む。

論文が「良い例」として挙げる browser-use の参照スタイルは、URL に「何を提供し何を提供しないか・関連コードの場所」を併記する形式です。

Conflicting Instructions の修正 (Before / After)

Before: 同一成果物に対して 2 つの異なるパスを指定している状態 (inkline/inkline の実例に基づく)。

## Component Guidelines
Components should be placed in the `packages/ui/components` directory.

## How to create a new component
Create a new folder in `packages/components` with the name of the component.

After: 正規のパスを 1 つに統合し、他の記述を削除します。

## Component Structure
すべての新規コンポーネントは `packages/ui/components/<component-name>/` に配置する。
他のパス (`packages/components/` 等) は旧構造であり使用しない。

修正後は grep で旧パスの残存を確認します。

grep -rn "packages/components" CLAUDE.md AGENTS.md

運用

定期レビューのサイクル (Init Fossilization 対策)

論文は Init Fossilization を検出した 24 プロジェクトについて、活発に開発が続くプロジェクトでも設定ファイルの更新が放置されていることを確認しています。設定ファイルは作ったら終わりではなく、生きたドキュメントとして維持する必要があります。

論文が示す更新トリガー (4 条件):

• エージェントが同じミスを 2 回繰り返したとき
• コードレビューで設定のギャップが判明したとき
• 開発者が前セッションと同じ訂正を繰り返しているとき
• 新しいチームメンバーがオンボーディングで同じ context を必要とするとき

CI への smell 検出組み込み (実装案)

論文は自動検出ヒューリスティクスを提案していますが、CI/CD パイプラインへの組み込みは論文の対象外です。以下は論文の検出手法を PR チェックとして展開する実装案です。

# .github/workflows/agents-md-smell-check.yml (実装案)
name: AGENTS.md Smell Check

on:
  pull_request:
    paths:
      - 'AGENTS.md'
      - 'CLAUDE.md'
      - '.claude/**/*.md'

jobs:
  smell-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # git log に必要

      - name: Context Bloat check (deterministic)
        run: |
          for f in AGENTS.md CLAUDE.md; do
            [ -f "$f" ] || continue
            lines=$(wc -l < "$f")
            if [ "$lines" -ge 200 ]; then
              echo "::warning file=$f::Context Bloat の疑い ($lines 行 >= 200)"
            fi
          done

      - name: Init Fossilization check (deterministic)
        run: |
          for f in AGENTS.md CLAUDE.md; do
            [ -f "$f" ] || continue
            count=$(git log --oneline --follow "$f" | wc -l)
            if [ "$count" -le 1 ]; then
              echo "::warning file=$f::Init Fossilization の疑い (commit 数 = $count)"
            fi
          done

CI 組み込み時の注意点:

• LOC チェックと commit 数チェックは決定論的であり、自動 warn に使えます。
• LLM チェック (Lint Leakage・Skill Leakage・Blind References・Conflicting Instructions) は precision が 57〜93% であり、CI で自動 fail させると偽陽性が多発します。PR コメントへの情報出力にとどめ、マージ判断は人間が行う設計が現実的です。

共起の監視: 1 つ見つけたら他も疑う

論文のアソシエーションルール分析 (Table IV) と Upset 図 (Figure 13) は、smell が単独で発生するより複合して発生することを示しています。下表は両者を出所付きで併記します。

運用上の含意として、AGENTS.md で Lint Leakage を 1 件発見した場合、ファイル全体を Context Bloat・Skill Leakage の観点でも通読するとよいです。

ベストプラクティス

「詳しく書くほど良い」の否定

論文の中心的メッセージは、設定ファイルは小さく・的を絞って保つことです。「詳しく書くほど良い」という直感は誤りであり、行数が増えるほどトークン消費が増えて重要な指示が埋没します (Context Bloat)。

Anthropic は CLAUDE.md を 200 行未満に保つことを推奨しており、論文はこの 200 行を Context Bloat 閾値として採用しています (論文中の PR 例では 150〜200 行程度が望ましいとされます)。

skill ファイルへの分離 (Skill Leakage 対策)

論文が示す漏れた skill の種別 (Table III) と、分離先のファイル名の例です。

分離の判断基準は「この指示は全タスクに関係するか」です。NO なら skill ファイルへ退避します。Claude Code の .claude/skills/<name>/SKILL.md 構造はこのベストプラクティスの実践例です。AGENTS.md / CLAUDE.md は横断的コンテキスト (ブランドルール・安全ポリシー・ディレクトリ構造) に絞り、手順的な指示は skill ファイルに切り出します。6 smell のカタログを人間が管理するレビューチェックリストとして保持するのも一案です。

linter/formatter への委譲 (Lint Leakage 対策)

論文は「Biome・ESLint・Ruff などの linter/formatter はスタイルルールをより速く・安く・100% の一貫性で強制する」と指摘します。設定ファイルに linter が既にカバーするルールを書くことは、エージェントの注意資源を消費するだけです。

残すものは、linter が強制できないアーキテクチャ上の意思決定 (「このレイヤーは DB に直接触れない」等) です。

参照に文脈を付ける (Blind References 対策)

論文は「パスだけ書いてもエージェントは無視することが多い。なぜ・いつ読むべきかを伝えなければならない」と指摘します。文脈付き参照のチェックリストは次のとおりです。

• 参照先が何を提供するか (目的)
• 参照先が何を提供しないか (スコープ外)
• いつ・どのタスクで読むべきか
• 関連するコードの場所 (ある場合)

トラブルシューティング

反証・限界

論文の知見を実務に適用するとき、以下の限界を念頭に置く必要があります。

LLM 検出の precision ばらつき: 人手検証が前提

検出結果はすべて人手検証を前提として扱うべきです。特に Conflicting Instructions (precision 57%) は、自動検出の結果だけで「矛盾がある」と判断すると半数近くが偽陽性です。

なお論文は precision のみを報告し、recall (実際に smell があるファイルのうち検出できた割合) は計測していません。precision が高くても recall が低い場合は smell を見逃す可能性があり、スキャン結果が「クリーン」でも安全とは言い切れません。

閾値の恣意性

• 200 行閾値 (Context Bloat): Anthropic の推奨に基づく保守的な値です。プロジェクト規模・言語・チーム構成によっては適切な上限が異なる可能性があります。
• commit 数 1 (Init Fossilization): 保守的な閾値であり、2 件以上でも実質的に陳腐化している可能性を排除しません。

グレー文献レビューのバイアス

Google 検索の上位ページに依存しており、検索アルゴリズムや言語 (英語のみ) による選択バイアスがあります。非英語圏のベストプラクティスや、検索上位に出ない実務知見は捕捉されていません。

LLM 非決定性による再現性の問題

論文は temperature=0 で再現性を高めていますが、モデル更新で同じプロンプトの結果が変わる可能性があります。検出ツールを自製する場合は、使用モデルのバージョンを固定し、定期的に再検証する運用が必要です。

サンプルバイアス (star 上位 100 リポジトリ)

分析対象は GitHub star 上位の著名 OSS です。小規模・非公開・業務システムでの出現率や種別分布は異なる可能性があります。「91% が 1 つ以上の smell を持つ」という数値を自プロジェクトへ直接適用するのは慎重に行ってください。

まとめ

本論文は AGENTS.md / CLAUDE.md を「設計資産」として捉え、6 種類の設定の設計臭 (Lint Leakage / Context Bloat / Skill Leakage / Conflicting Instructions / Init Fossilization / Blind References) を定義し、star 上位 100 リポジトリの 91% が 1 つ以上の smell を抱えることを示しました。実務では「詳しく書くほど良い」を捨て、フォーマット系は linter へ、専門手順は skill ファイルへ切り出し、参照には文脈を付け、設定を生きたドキュメントとして定期レビューすることが要点です。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• 一次論文 (本フレームワーク)
  • Configuration Smells in AGENTS.md Files (HTML)
  • Configuration Smells in AGENTS.md Files (abstract)
  • レプリケーションパッケージ (Zenodo)
• 関連学術論文 (系譜)
  • Agent READMEs: An Empirical Study of Context Files for Agentic Coding (2511.12884)
  • On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents (2601.20404)
  • Decoding the Configuration of AI Coding Agents: Insights from Claude Code Projects (2511.09268)
  • Configuring Agentic AI Coding Tools: An Exploratory Study (2602.14690)
• 関連ツール・プラットフォーム公式
  • Ruff (Python linter/formatter)
  • Biome (JS/TS toolchain)
  • pre-commit
  • Claude Code documentation
• 実例リポジトリ
  • google/adk-python — Lint Leakage の実例
  • browser-use/browser-use — Blind References の良い例
  • quickemu-project/quickemu — Skill Leakage の実例
  • inkline/inkline — Conflicting Instructions の実例
  • javascript-obfuscator/javascript-obfuscator — Context Bloat の実例
  • SuperClaude-Org/SuperClaude_Framework — Blind References の悪い例