LLMs.txtファイルの更新

リポジトリのルートに存在する llms.txt ファイルを更新して、ドキュメント、仕様、またはリポジトリ構造の変更を反映します。このファイルは、大規模言語モデル(LLM)に対して、リポジトリの目的と仕様を理解するための関連コンテンツの場所を示す高レベルなガイダンスを提供します。

主要なディレクティブ

既存の llms.txt ファイルを更新して、llms.txt仕様への準拠を維持しながら、現在のリポジトリ構造とコンテンツを反映させます。このファイルはLLM消費のために最適化されたままでありながら、人間にとって読みやすい状態を保つ必要があります。

分析および計画フェーズ

llms.txt ファイルを更新する前に、徹底的な分析を完了する必要があります。

ステップ1: 現在のファイルと仕様のレビュー

• 既存の llms.txt ファイルを読み、現在の構造を理解する
• https://llmstxt.org/ の公式仕様をレビューして、継続的な準拠を確認する
• リポジトリの変更に基づいて更新が必要な領域を特定する

ステップ2: リポジトリ構造分析

• 適切なツールを使用して現在のリポジトリ構造を調査する
• 現在の構造を既存の llms.txt に記載されている内容と比較する
• 含めるべき新しいディレクトリ、ファイル、またはドキュメントを特定する
• 更新が必要な削除または再配置されたファイルに注意する

ステップ3: コンテンツ発見と変更検出

• 新しいREADMEファイルとその場所を特定する
• 新しいドキュメントファイル(/docs/、/spec/ などの .md ファイル)を見つける
• 新しい仕様ファイルとその目的を特定する
• 新しい設定ファイルとその関連性を発見する
• 新しいサンプルファイルとコードサンプルを見つける
• 既存のドキュメント構造への変更を特定する

ステップ4: 更新計画の作成

分析に基づいて、以下を含む構造化されたプランを作成します:

• 精度を維持するために必要な変更
• llms.txt に追加される新しいファイル
• 削除または更新が必要な廃止された参照
• 明確さを維持するための組織的改善

実装要件

フォーマット準拠

更新された llms.txt ファイルは、仕様に従ってこの正確な構造を維持する必要があります:

1. H1ヘッダー: リポジトリ/プロジェクト名の単一行(必須)
2. ブロッククォート概要: ブロッククォート形式での簡潔な説明(オプションだが推奨)
3. 追加の詳細: コンテキストのための見出しのないゼロ個以上のマークダウンセクション
4. ファイルリストセクション: マークダウンリストのリンクを含むゼロ個以上のH2セクション

コンテンツ要件

必須要素

• プロジェクト名: H1として明確で説明的なタイトル
• 概要: リポジトリの目的を説明する簡潔なブロッククォート
• 主要ファイル: カテゴリー別に整理された必須ファイル(H2セクション)

ファイルリンク形式

各ファイルリンクは次の形式に従う必要があります: [descriptive-name](relative-url): optional description

セクション構成

ファイルを次のような論理的なH2セクションに整理します:

• Documentation: コアドキュメンテーションファイル
• Specifications: 技術仕様と要件
• Examples: サンプルコードと使用例
• Configuration: セットアップと設定ファイル
• Optional: 補助的なファイル(特別な意味 - より短いコンテキストではスキップできます)

コンテンツガイドライン

言語とスタイル

• 簡潔で明確で曖昧さのない言語を使用する
• 説明のない専門用語を避ける
• 人間とLLMの両方の読者に向けて書く
• 説明において具体的で情報的である

ファイル選択基準

以下のファイルを含めます:

• リポジトリの目的と範囲を説明するもの
• 重要な技術ドキュメントを提供するもの
• 使用例とパターンを示すもの
• インターフェースと仕様を定義するもの
• セットアップと設定の指示を含むもの

以下のファイルを除外します:

• 純粋な実装の詳細であるもの
• 重複した情報を含むもの
• ビルドアーティファクトまたは生成されたコンテンツであるもの
• プロジェクトを理解するのに関連しないもの

実行ステップ

ステップ1: 現在の状態分析

1. 既存の llms.txt ファイルを徹底的に読む
2. 現在のリポジトリ構造を完全に調査する
3. 既存のファイル参照を実際のリポジトリコンテンツと比較する
4. 廃止された、不足している、または不正確な参照を特定する
5. 現在のファイルの構造上の問題に注意する

ステップ2: コンテンツ計画

1. 主要な目的ステートメントが更新を必要とするかどうかを判断する
2. 必要に応じて概要ブロッククォートを確認および更新する
3. 新しいファイルとディレクトリの追加を計画する
4. 廃止または移動されたコンテンツの削除を計画する
5. より明確にするための必要に応じてセクションを再編成する

ステップ3: ファイル更新

1. リポジトリルートの既存の llms.txt ファイルを更新する
2. 正確なフォーマット仕様への準拠を維持する
3. 適切な説明とともに新しいファイル参照を追加する
4. 廃止された参照を削除または更新する
5. すべてのリンクが有効な相対パスであることを確認する

ステップ4: 検証

1. https://llmstxt.org/ 仕様への継続的な準拠を確認する
2. すべてのリンクが有効でアクセス可能であることを確認する
3. ファイルがLLMナビゲーションツールとして依然として有効に機能することを確認する
4. ファイルが引き続き人間と機械の両方で読みやすいことを確認する

品質保証

フォーマット検証

• ✅ プロジェクト名を持つH1ヘッダー
• ✅ ブロッククォート概要(含まれている場合)
• ✅ ファイルリスト用のH2セクション
• ✅ 適切なマークダウンリンク形式
• ✅ 破損または無効なリンクなし
• ✅ 全体を通じた一貫したフォーマット

コンテンツ検証

• ✅ 明確で曖昧さのない言語
• ✅ 必須ファイルの包括的なカバレッジ
• ✅ コンテンツの論理的組織
• ✅ 適切なファイルの説明
• ✅ LLMナビゲーションツールとして有効に機能する

仕様準拠

• ✅ https://llmstxt.org/ フォーマットに正確に従う
• ✅ 必須のマークダウン構造を使用する
• ✅ 適切にオプションセクションを実装する
• ✅ リポジトリルート(/llms.txt)にファイルが位置する

更新戦略

追加プロセス

新しいコンテンツを追加する場合:

1. 新しいファイルに適切なセクションを特定する
2. リンクのために明確で説明的な名前を作成する
3. 簡潔であるが情報的な説明を書く
4. セクション内でアルファベット順または論理順を維持する
5. 新しいコンテンツ種別に対して新しいセクションが必要かどうかを検討する

削除プロセス

廃止されたコンテンツを削除する場合:

1. ファイルが実際に削除または再配置されていることを確認する
2. 削除するのではなく再配置されたファイルを更新する必要があるかを確認する
3. セクションが空になった場合は削除する
4. 必要に応じてクロスリファレンスを更新する

再編成プロセス

コンテンツを再構築する場合:

1. 一般から特定への論理的フローを維持する
2. 重要なドキュメンテーションをプライマリセクションに保つ
3. 必要に応じて補助的コンテンツを「Optional」セクションに移動する
4. 新しい組織がLLMナビゲーションを改善することを確認する

llms.txt の構造例:

# [Repository Name]

> [Concise description of the repository's purpose and scope]

[Optional additional context paragraphs without headings]

## Documentation

- [Main README](README.md): Primary project documentation and getting started guide
- [Contributing Guide](CONTRIBUTING.md): Guidelines for contributing to the project
- [Code of Conduct](CODE_OF_CONDUCT.md): Community guidelines and expectations

## Specifications

- [Technical Specification](spec/technical-spec.md): Detailed technical requirements and constraints
- [API Specification](spec/api-spec.md): Interface definitions and data contracts

## Examples

- [Basic Example](examples/basic-usage.md): Simple usage demonstration
- [Advanced Example](examples/advanced-usage.md): Complex implementation patterns

## Configuration

- [Setup Guide](docs/setup.md): Installation and configuration instructions
- [Deployment Guide](docs/deployment.md): Production deployment guidelines

## Optional

- [Architecture Documentation](docs/architecture.md): Detailed system architecture
- [Design Decisions](docs/decisions.md): Historical design decision records

成功基準

更新された llms.txt ファイルは以下を行うべきです:

1. 現在のリポジトリ構造とコンテンツを正確に反映する
2. llms.txt仕様への準拠を維持する
3. 重要なドキュメンテーションへの明確なナビゲーションを提供する
4. 廃止または不正確な参照を削除する
5. 新しい重要なファイルとドキュメンテーションを含める
6. LLM消費のための論理的組織を維持する
7. 全体を通じて明確で曖昧さのない言語を使用する
8. 人間と機械の両方の読者に対して引き続き効果的に機能する