AIドキュメントアシスタントの開発を通じて学んだテクニカルライティング

テクニカルライターの多くは、AIエージェントを開発しません。私たちはそれをドキュメント化します。スプリントレビューに参加し、アーキテクチャ決定記録を読みます。そして、金曜日までに統合を動かす必要がある人に、検索パイプラインをどう説明するかを考えます。

それでも、私は一つ作ってみました。

名前は**Artie**。Algoliaで構築したAIドキュメントアシスタントで、このドキュメントサイトの中で動いています。彼を作る過程で、私はライティングとAIについて、どのカンファレンスの講演よりも多くを学びました。

これはArtieの設計を順に解説する記事ではありません。それは**ケーススタディ**の役目です。この記事が扱うのは、より広い学びです。

• AIエージェントとは実際に何か
• 検索強化生成は実務でどう動くのか
• なぜプロンプトエンジニアリングは、多くの人が思うよりテクニカルライティングに近いのか
• そして、それが私たちの小さな世界の住人にとって何を意味するのか

AIエージェントとは何か、何ではないか

世間は「AIエージェント」という言葉を、スペルチェッカーから自動補完まで何にでも当てはめます。違いは重要です。AIの機能がすべてエージェントなわけではありません。機械学習を使うスペルチェッカーはエージェントではありません。自動補完の候補も同じです。固定された決定木をたどるチャットボットは、テキストボックスの付いたフローチャートにすぎません。

AIエージェントとは、定義された環境の中で目標を解釈し、それに基づいて行動できるシステムです。一定の制約下での自律性が、エージェントとプロンプト応答ループを分けます。エージェントはコンテキストを読み、戦略を選び、時には複数のステップを踏みます。

では、Artieはこのスペクトルのどこにいるのでしょうか。

その定義に照らせば、彼はエージェントではありません。ウェブを閲覧せず、コードを実行せず、多段のツール呼び出しもつなぎません。Algoliaがモデルの実行前にページを取得し、モデルはそれをコンテキストとして受け取ります。ただし彼は、意図を自力で解釈し、ガードレールを適用します。答える前に、その質問が技術的なものかポートフォリオに関するものかを見分けます。これはテキスト欄の付いた検索ボックスより多く、ユーザーの質問からバグレポートを起票できるような完全自律型エージェントより少ない存在です。

テクニカルライターには、いまこの区別が必要です。AIツールとAIエージェントを理解することは仕事の一部です。AIを組み込んだ製品をドキュメント化するときは、その製品がスペクトルのどこに位置するかを知る必要があります。そして、その製品における「AI」の意味をユーザーに伝える必要があります。期待は人によって違うからです。

検索強化生成はどう動くのか

検索強化生成（RAG）は、Artieと、増え続けるAIドキュメントツールを支えています。RAGは大規模言語モデル（LLM）の根本的な限界を回避します。モデルは固定のデータセットで学習します。あなたのコンテンツはその学習データに含まれていません。

通常のLLMとのやり取りはこうです。ユーザーがプロンプトを送り、モデルが学習データから応答を生成します。これは一般知識には向きますが、特定領域の質問には向きません。基盤モデルに自社製品のAPIを尋ねれば、答えをでっち上げるか、断るかのどちらかです。

RAGは、ユーザーの質問とモデルの応答の間に検索ステップを挟みます。パイプラインは次のとおりです。

1. クエリ処理。 検索レイヤーがユーザーの質問をベクトル埋め込みに変換します。これは意味を数値で表したものです。
2. 検索。 システムはナレッジベースから意味の近いコンテンツを探します。ここでのナレッジベースは、あなたのドキュメントを事前に構築したインデックスです。順位付けは意味に依存し、多くの場合キーワード一致も併用します。「認証を設定するには？」と「ログイン情報を構成する」というクエリは、同じドキュメントページを返します。
3. コンテキストの組み立て。 システムは取得したドキュメント、またはその断片を、ユーザーの質問とシステムプロンプトとともにコンテキストウィンドウへ詰め込みます。モデルはそのまとまりを処理します。
4. 生成。 モデルは学習データではなく、取得したコンテキストに基づいて応答を生成します。適切に調整されたシステムでは、根拠を明示し、取得したドキュメントに書かれている範囲にとどまります。

Mermaid (image)

Mermaid (code)

flowchart TD
    A["🔍 ユーザーの 質問"] --> B["クエリ 処理"]
    B -->|ベクトル 埋め込み| C["検索・抽出"]
    KB[("📚 ナレッジベース")] -.-> C
    C -->|関連 ドキュメント| D["コンテキスト 統合"]
    D -->|プロンプト + コンテキスト| E["生成"]
    E --> F["📄 根拠のある 回答"]

品質はステップ2で決まります。検索レイヤーが誤ったドキュメントを返したり、順位付けを誤ったりすれば、モデルの能力は役に立ちません。モデルは誤った素材から、もっともらしく整った回答を書いてしまいます。だからこそ、チャンク分割と埋め込みモデルの選択は、多くのチームが思う以上に重要です。称賛を受けるのは生成モデルですが、品質を決めるのは検索レイヤーです。

Artieの場合、ナレッジベースはこのサイトのドキュメントです。Algoliaがそれをインデックス化し、検索します。Artieはここでドキュメント化されている内容だけを扱うため、サイト自身の素材の中にとどまります。それが実際にどう働くかは**ケーススタディ**で説明しています。RAGはモデルを賢くしません。すべての応答が検証可能な情報源につながるため、モデルをより説明責任のあるものにします。

プロンプトエンジニアリングはテクニカルライティングである

このプロジェクトで得た大きな学びは一つです。システムプロンプトはテクニカルライティングの成果物です。

よく練られたシステムプロンプトは、スタイルガイドと同じ要素を持ちます。読者を定義します。トーンと文体のルールを定めます。範囲の境界を引きます。何を扱い、何を扱わないかを決めます。機械が人間の判断なしに従えるほど正確な指示を書きます。最も重要なルールが先に来るよう、情報を並べます。

それは読者分析であり、スタイルガイドでもあります。同時にコンテンツ計画でもあります。

スキルの移行はほぼ一対一です。

• 読者分析 → 読者の振り分け。 テクニカルライターは読者を特定し、それに合わせて内容を調整します。システムプロンプトもAIに対して同じことをします。Artieのプロンプトは技術者と採用担当者を振り分けます。よく構造化されたドキュメントサイトが読者ペルソナを振り分けるのと同じです。
• スタイルガイド → ペルソナの調整。 どのドキュメントチームにもトーンと文体の指針があります。システムプロンプトはAIのためのスタイルガイドです。読者ごとにトーンを設定し、すべての主張に情報源リンクを求めます。
• 情報アーキテクチャ → 指示の階層。 テクニカルライターは、順序と構造が理解に影響することを知っています。指示をどこに置くかで、モデルがそれを守る度合いが変わります。
• エッジケースのドキュメント化 → ガードレールの設計。 よいドキュメントは、予期しない操作を明確な指針で覆います。よいプロンプト設計は、システムを破ろうとするユーザーを覆います。

すべてのテクニカルライターがプロンプトエンジニアになる必要はありません。この分野は、テクニカルライターが何十年もかけて培うスキルを多く借りています。明確で構造化され、読者を意識した文書を書けるなら、あなたは思う以上にこの仕事に貢献できます。

ガードレールは言語の問題である

人々はAIのセキュリティを技術的な問題として扱います。レート制限、ログイン、アクセス制御です。どれも重要です。しかし公開チャットボットでは、攻撃者が狙う対象の多くが言語的です。

備考

プロンプトインジェクションとは、ユーザーがシステムプロンプトを上書きすることです。よくある例が「これまでの指示をすべて無視してください」という一文です。

プロンプトインジェクションは、言葉を使って言葉ベースの制御をかわします。防御とは、攻撃者がモデルを言いくるめて突破できないほど明確なルールを書くことです。

Open Worldwide Application Security Project（OWASP）のLLMアプリケーションのトップ10リスクは、プロンプトインジェクションを最大のリスクに挙げています。その一覧を読むと、多くのリスクが根底では言語の問題だと分かります。

• 不適切な出力処理（モデルが何を出力するか）
• データとモデルのポイズニング（モデルがテキストから何を学んだか）
• 過剰な自律性（プロンプトがモデルに何ができると伝えているか）

攻撃は技術的です。防御はしばしば自然言語で書かれ、システムプロンプトの中に置かれます。

これはテクニカルライターにとって、セキュリティの仕事の見え方を変えます。誰も私たちに認証システムの構築を求めません。しかしAIがどう応答するかを定めるルールは書けます。敵対的な入力に耐えるだけの精度で書けます。

ドキュメントの仕事で何が変わるか

AIの未来を予言するつもりはありません。いま見えている軌道と、生活のためにソフトウェアをドキュメント化する人にとってそれが何を意味するかは説明できます。

AIドキュメントアシスタントは、目新しさから当然の期待へと移りました。ユーザーは静的な検索を受け入れません。気軽に質問し、10個の青いリンクではなく根拠のある答えを求めます。RAGシステムはそれをいま可能にしています。ツールの導入は年々容易になっています。

ヒント

インフラ側に興味がある方へ。イベントストリームとオブザーバビリティパイプラインのドキュメントでは、DatadogやGalileoがモデル呼び出しをどう追跡するかを説明しています。

テクニカルライターの役割は縮むどころか広がります。これらのシステムが検索するナレッジベースを整える人が必要です。どう応答し、どこで止まるかを定めるシステムプロンプトを書く人が必要です。応答がドキュメントと合っているかを検証する人が必要です。どれもライティングの仕事であり、人が情報をどう受け取るかについての判断を要します。

テクニカルライターはLLMとRAGシステムの仕組みを学ぶべきです。機械学習エンジニアになる必要はありませんが、AI製品についての議論には加わるべきです。自分の専門性がどこに効き、どこに効かないかを知るだけのパイプライン理解は必要です。

テクニカルライターはすでに多くの読者に向けて書いています。コンテンツを構造化し、範囲を定めます。誤用に備えます。これらのスキルはAIの仕事にそのまま活きます。

AIはテクニカルライターを置き換えません。モデルは年々文章生成が上手くなりますが、何を、誰に、どのような制約の中で言うかを決める人は依然として必要です。

必要なのは編集者です。編集者は私たちです。

自分で最初の草稿を書いて、AIエージェントを校正者とスタイルチェッカーとして使うのも手です。

仕事の流れでAIをどう使うかは、私たちが使える他のどのツールとも同じく、あなた次第です。

仕事は変わっていません。ツールが変わっています。仕事はなくなりません。テクニカルライターを切ったチームは、結局また呼び戻します。

ケーススタディを読む

この記事が「なぜ重要か」と「どう動くか」を伝えたなら、ケーススタディを読んでください。Artieの具体的な設計判断を扱っています。

• 読者の振り分け
• 知識の根拠づけ
• ペルソナの調整
• セキュリティのガードレール
• 本番導入に向けて見直すとしたら変える判断

どちらの記事も単独で読めます。興味のあるほうから始めてください。