enhance-docs

enhance-docs

読みやすさ、構成、RAG 最適化の観点からドキュメントを分析します。

引数の解析

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');
const aiMode = args.includes('--ai');

ドキュメントの場所

種類	場所	目的
ユーザードキュメント	docs/*.md、README.md	人間が読みやすいガイド
エージェントドキュメント	agent-docs/*.md	AI 向けのリファレンス資料
プロジェクトメモリ	CLAUDE.md、AGENTS.md	AI のコンテキスト／指示

最適化モード

AI 専用モード（--ai）

エージェントドキュメントと RAG に最適化されたドキュメント向けです。

• トークンを積極的に削減
• 情報を高密度にまとめる
• 検索に適した自己完結型のセクション
• 最適なチャンク境界

両方モード（--both、デフォルト）

ユーザー向けドキュメントを対象にします。

• 読みやすさと AI への適合性のバランスを取る
• 人間と検索システムの両方にわかりやすい構成

ワークフロー

1. 検出 - すべての .md ファイルを見つけます
2. 解析 - 構成と内容を抽出します
3. チェック - モードに基づいてパターンを確認します
4. レポート - Markdown 形式の出力を生成します
5. 修正 - --fix が指定されている場合、自動修正を適用します

検出パターン

1. リンクの検証（高）

• 壊れたアンカーリンク（[text](#missing-anchor)）
• 存在しないファイルへのリンク
• 不正なリンク構文

2. 構成の検証（高）

見出しの階層：

• 階層を飛ばさない（H1 の次が H2 なしで H3 になるなど）
• ドキュメントごとに H1 は 1 つ
• コードブロックに言語タグを付ける

位置を考慮したコンテンツ（「中間で見失う」ことに関する研究に基づく）：

• 重要な情報はドキュメントの冒頭または末尾に配置
• 補足情報は中間に配置
• 中間のセクションに埋もれた重要なコンテンツを検出

推奨される構成：

1. Overview/Purpose (START - high attention)
2. Quick Start / TL;DR
3. Detailed Content
4. Reference / API
5. Summary / Key Points (END - high attention)

3. トークン効率（高 - AI モード）

トークン数の推定： characters / 4 または words * 1.3

不要な表現：

• 「このドキュメントでは……」
• 「ご覧のとおり……」
• 「見ていきましょう……」
• 「重要なのは……ということです」

冗長な表現：

冗長	簡潔
"in order to"	"to"
"due to the fact that"	"because"
"has the ability to"	"can"
"at this point in time"	"now"
"for the purpose of"	"for"
"in the event that"	"if"

目標： プロジェクトメモリファイルは約 1500 トークン。リファレンスドキュメントは柔軟に設定します。

4. RAG 最適化（中 - AI モード）

チャンクサイズのガイドライン：

サイズ	問題
>1000 トークン	長すぎるため、サブトピックに分割します
<50 トークン	短すぎるため、関連する内容と統合します
200-500 トークン	検索に最適

意味上の境界：

• 1 セクションにつき 1 つのトピック
• 自己完結型のセクション（セクション冒頭で「それ」「これ」を避ける）
• 内容を説明する明確なセクションタイトル

コンテキストアンカー：

# Bad - ambiguous start
## Configuration
It requires several settings...

# Good - self-contained
## Configuration
The plugin configuration requires several settings...

5. 情報密度（中 - AI モード）

文章より表を優先します：

# Bad - verbose
The function accepts a path parameter which is required,
a limit parameter which defaults to 10, and an optional
format parameter.

# Good - dense
| Param | Required | Default | Description |
|-------|----------|---------|-------------|
| path | Yes | - | File path |
| limit | No | 10 | Max results |
| format | No | json | Output format |

順序のある項目は段落よりリストを優先します。

例、コマンド、設定にはコードブロックを使用します。

6. 相互参照の品質（中）

• 内部リンクには相対パスを使用します
• 外部リンクは安定したものを使用します（コミットハッシュは避けます）
• 参照セクションでは、正規の情報源を示します

7. バランスに関する提案（中 - 両方モード）

• 長いコンテンツ（見出しがないまま 500 語を超えるもの）にセクション見出しがない
• 重要な情報がドキュメントの後半に埋もれている
• 長いドキュメントに TL;DR または要約がない

自動修正

問題	修正
見出しの不統一	H1 → H3 を H1 → H2 に変更
冗長な表現	簡潔な表現に置き換え
コードの言語指定がない	内容の検出に基づいて追加

出力形式

## Documentation Analysis: {name}

**File**: {path}
**Mode**: {AI-only | Both}
**Tokens**: ~{count}

| Certainty | Count |
|-----------|-------|
| HIGH | {n} |
| MEDIUM | {n} |

### Link Issues
| Line | Issue | Fix | Certainty |

### Structure Issues
| Line | Issue | Fix | Certainty |

### Efficiency Issues [AI mode]
| Line | Issue | Fix | Certainty |

### RAG Issues [AI mode]
| Line | Issue | Fix | Certainty |

パターンの統計

カテゴリ	パターン数	モード	確度
リンク	3	共通	高
構成	4	共通	高
トークン効率	3	AI	高
RAG 最適化	3	AI	中
情報密度	2	AI	中
相互参照	2	共通	中
バランス	3	両方	中
合計	20	-	-

### 冗長な表現 ```markdown In order to configure the plugin, you need to... ``` ```markdown To configure the plugin... ``` ### RAG チャンキング ```markdown ## Installation [2000+ tokens of mixed content covering install, config, and usage] ``` ```markdown ## Installation [400 tokens - installation only]

Configuration

[300 tokens - config only]

Usage

[400 tokens - usage only]

</good_example>

### 位置を意識したコンテンツ
<bad_example>
```markdown
## Introduction
[Long background...]

## History
[More context...]

## Critical Setup Steps
[Important info buried in middle]

</bad_example> <good_example>

## Quick Start (Critical)
[Important setup steps at START]

## Background
[Supporting context in middle]

## Reference
[Details...]

## Key Reminders
[Critical points repeated at END]

</good_example>

表と文章の比較

<bad_example>

The API accepts three parameters. The first is `query` which is required.
The second is `limit` which defaults to 10. The third is `format`.

</bad_example> <good_example>

| Param | Required | Default |
|-------|----------|---------|
| query | Yes | - |
| limit | No | 10 |
| format | No | json |

</good_example>

参考資料

• agent-docs/CONTEXT-OPTIMIZATION-REFERENCE.md - トークン予算、位置認識、チャンキング
• agent-docs/PROMPT-ENGINEERING-REFERENCE.md - 構造、情報密度

制約

• 確実性の高い問題のみを自動修正する
• 元のトーンとスタイルを維持する
• AI 最適化と人間の可読性のバランスを取る（デフォルトモード）
• コンテンツを削除せず、再構成または要約のみを行う