aif-reference

リファレンスの作成

外部ソースから構造化されたナレッジリファレンスを作成し、設定済みのリファレンスディレクトリに保存して、ほかの AI Factory スキルから後で再利用できるようにします。

ステップ 0：設定の読み込み

最初に行うこと： .ai-factory/config.yaml が存在する場合は読み込み、以下を確認します。

• パス： paths.references と paths.rules_file
• 言語： プロンプトと要約には language.ui、生成するリファレンス成果物には language.artifacts、リファレンス内の人が読む技術用語には language.technical_terms

config.yaml が存在しない場合は、次のデフォルト値を使用します。

• references/: .ai-factory/references/
• RULES.md: .ai-factory/RULES.md
• ui_language: en
• artifact_language: en
• technical_terms_policy: keep

解決後の言語値：

• ui_language = language.ui || "en"
• artifact_language = language.artifacts || language.ui || "en"
• technical_terms_policy = language.technical_terms || "keep"

technical_terms_policy が keep、translate、mixed のいずれでもない場合は、keep として扱います。english などの従来の値も keep として扱います。

すべての AskUserQuestion プロンプト、進捗状況の更新、要約、次の手順の案内は、必ず ui_language で記述してください。

生成するリファレンスファイルとリファレンスの INDEX.md は、必ず artifact_language で記述してください。

テンプレートと例は構造を定めるものであり、英語の出力を固定するものではありません。artifact_language が en 以外の場合は、保存前に、人が読む見出し、ラベル、要約、概念の説明、ベストプラクティスの文章、落とし穴、インデックスの説明を翻訳してください。引用元の文章、ソースタイトル、URL、ローカルパス、コード例、API シグネチャ、コマンド名、設定キー、パッケージ名、バージョン文字列、生のエラー、リンク先は変更せずに保持してください。それ以外の、人が読む技術用語には technical_terms_policy を適用してください。

プロジェクトのコンテキスト

.ai-factory/skill-context/aif-reference/SKILL.md を読み込んでください - ファイルが存在する場合は必須です。

このファイルには、パッチ、コードベースの規約、技術スタックの分析をもとに /aif-evolve が蓄積した、プロジェクト固有のルールが記載されています。これらのルールは現在のプロジェクトに合わせたものです。

skill-context のルールの適用方法：

• このスキルの一般的な指示に対するプロジェクトレベルの上書きルールとして扱います。
• skill-context のルールが、この SKILL.md に記載された一般的なルールと競合する場合は、skill-context のルールを優先します。
• 競合しない場合は、両方を適用します。
• 重要： skill-context のルールは、生成するリファレンスファイルを含め、このスキルのすべての出力に適用されます。skill-context のルールに「リファレンスには必ず X を含める」とある場合は、必ず従ってください。

遵守の確認： 出力成果物を生成した後は、すべての skill-context のルールに照らして確認してください。ルールに違反している場合は、ユーザーに提示する前に出力を修正してください。

使用する場面

• AI が、学習データに含まれていない、または一部しか把握していないドキュメントを必要としている場合
• 特定のドキュメント、仕様、内部ファイルに基づく、根拠のある回答を得たい場合
• /aif-plan、/aif-implement、/aif-explore、/aif-grounded で再利用できるドメインコンテキストが必要な場合
• その場限りの会話コンテキストではなく、永続的なナレッジ成果物が必要な場合

引数の判定

Check $ARGUMENTS:
- Contains "--update"        -> Update Mode: refresh existing reference
- Contains URLs (http/https) -> URL Mode: fetch and process web sources
- Contains file paths        -> File Mode: process local documents
- "list"                     -> List existing references
- "show <name>"              -> Show reference content
- "delete <name>"            -> Delete a reference (with confirmation)
- Empty                      -> Interactive mode

ワークフロー

ステップ 0.1：セットアップ

解決済みのリファレンスディレクトリが存在することを確認します。

mkdir -p <resolved references dir>

重複を避けるため、既存のリファレンスを確認します。

ls <resolved references dir>

--name <ref-name> が指定されている場合は、それをリファレンス名として使用します。 --update が指定されている場合は、新しいリファレンスを作成する代わりに、既存のリファレンスを検索して更新します。

ステップ 1：情報源を収集する

URL の場合：

URL ごとに、以下を行います。

1. WebFetch を使ってページを取得し、以下を抽出します。
   • 主なトピックと目的
   • 主要な概念、用語、定義
   • コード例とパターン
   • API メソッド、パラメーター、戻り値の型、シグネチャ
   • デフォルト値を含む設定オプション
   • ベストプラクティスと推奨事項
   • エラー処理とエッジケース
   • バージョン情報と互換性に関する注意事項
   • 重要なサブページへのリンク
2. 重要なサブページが参照されている場合は、それらも取得します（ソース URL ごとに追加で最大 8 ページ）。
3. 明らかな不足が残る場合は、不足を補うために対象を絞った WebSearch クエリを 1～2 件実行します。

ローカルファイルの場合：

1. Read で各ファイルを読み込みます。
2. ファイルが他のローカルファイルを参照している場合は、それらも読み込みます（インクルードは最大 5 階層）。
3. 形式（markdown、HTML、JSON、YAML、プレーンテキスト）を判定し、それに応じて内容を抽出します。

対話モードの場合：

ユーザーに以下を尋ねます。

1. このリファレンスで取り上げるトピックやテクノロジーは何ですか？
2. URL やローカルファイルはありますか？それとも検索しますか？
3. ユースケースで特に重要な点は何ですか？

ステップ 2：リファレンスをまとめる

収集した資料を、構造化されたリファレンス文書にまとめます。

リファレンスファイルの形式：

保存する前に、この構造を artifact_language で記述します。以下の見出しは標準の構造ラベルであり、英語表記に固定されているわけではありません。

# <Topic> Reference

> Source: <list of source URLs or file paths>
> Created: YYYY-MM-DD
> Updated: YYYY-MM-DD

## Overview

<1-3 paragraph summary>

## Core Concepts

<Concept 1>: <clear explanation>
<Concept 2>: <clear explanation>

## API / Interface

<Only if applicable. Preserve exact signatures and types from source docs.>

## Usage Patterns

<Practical code examples organized by use case.>

## Configuration

<Options, defaults, valid values. Table format preferred.>

## Best Practices

<Numbered list with reasoning>

## Common Pitfalls

<What goes wrong and how to avoid it>

## Version Notes

<Only if relevant. Breaking changes, migration notes, deprecations.>

品質ルール：

• 創作しない — 実際に見つかった内容のみを含めます
• コードを原文どおりに保持 — ドキュメントの例は正確なままにします
• 学術的な内容より実用性を重視 — すぐに参照して役立つ内容を優先します
• 簡潔に — 1 行あたりの有用な情報を最大限にします
• シグネチャを完全に記載 — API には全パラメーター、型、戻り値を含めます
• 出典を明記 — 必ずソース URL またはパスを含めます

ステップ 3：名前を付けて保存する

命名規則：

• トピックから名前を決めます：react-hooks.md、fastapi-endpoints.md、docker-compose.md
• 小文字、ハイフン、.md を使用します
• --name が指定されている場合は、その名前を使用します（拡張子がない場合は .md を追加）
• reference.md のような汎用的な名前は避けます

保存先： <resolved references dir>/<name>.md

ステップ 4：インデックスに登録する

<resolved references dir>/INDEX.md が存在するか確認します。存在しない場合は作成し、存在する場合は更新します。

人が読みやすい見出し、トピックの説明、ソースの概要を artifact_language で記述します。ファイル名、リンク、URL、日付は変更しません。

# References Index

Available knowledge references for AI agents.

| Reference | Topic | Sources | Updated |
|-----------|-------|---------|---------|
| [react-hooks](react-hooks.md) | React Hooks API and patterns | react.dev | 2026-03-20 |
| [docker-compose](docker-compose.md) | Docker Compose configuration | docs.docker.com | 2026-03-20 |

ステップ 5：結果を報告する

ユーザーに以下を示します。

• リファレンス名とパス
• サイズ（行数）
• 含まれるセクション
• 使用したソース URL またはファイルパス
• 後続の AI Factory ワークフローでの使い方

更新モード（--update）

--update が指定されている場合：

1. --name または一致するソースを使って、既存のリファレンスを見つけます
2. ヘッダーに記載されたソースを再取得します
3. 新しい資料と既存の内容を比較し、変更があったセクションのみを更新します
4. Created: は保持し、Updated: を更新します
5. 変更内容を報告します

一覧表示／表示／削除

• /aif-reference list — <resolved references dir>/INDEX.md を読み込んで表示するか、ディレクトリ内のファイルを一覧表示します
• /aif-reference show <name> — リファレンスの内容を読み込んで表示します（.md は省略可能）
• /aif-reference delete <name> — 確認を求めてからファイルを削除し、INDEX.md を更新します

他のスキルとの連携

解決済みの references ディレクトリにあるリファレンスは、すべての AI Factory スキルから利用できます。

• /aif-plan と /aif-implement は、ドメインのコンテキストを把握するためにリファレンスを読み込めます
• /aif-grounded は、根拠となる情報源として利用できます
• /aif-explore は、調査中に参照できます

特定のリファレンスをスキルが認識できるようにするには、解決済みの RULES.md ファイルにそのリファレンスを記載します。

## References
- For <topic> details, see `<resolved references dir>/<name>.md`

アーティファクトの所有権

• 主な所有権： 解決済みの参照ディレクトリ（デフォルト：.ai-factory/references/）
• 共有所有権： 解決済みの参照インデックスファイル（そのディレクトリ内のINDEX.md）
• 読み取り専用： その他すべての.ai-factory/ファイル
• 設定ポリシー： 設定を考慮します。保存先にはpaths.referencesを使用し、保存済みの参照を他のスキルに示す際はpaths.rules_fileを使用します。プロンプトと要約にはlanguage.uiを、生成する参照アーティファクトにはlanguage.artifactsを、人が読む用語ポリシーにはlanguage.technical_termsを使用します。

ガードレール

• 参照の最大サイズ： 参照ごとに1000行未満を目安にします。それを超える場合は、複数のファイルに分割し、解決済みの参照ディレクトリ内にINDEX.mdを含むディレクトリを作成します
• 重複禁止： 新しい参照を作成する前に、既存の参照を確認します
• 古いデータの禁止： 参照を更新できるよう、必ずソースを含めます
• 意見の禁止： 参照には個人的な好みではなく、ソースの内容を反映します
• アクセス権の尊重： URLで認証が必要な場合や読み込みに失敗した場合は、推測せずにその旨を報告します