読み取り専用のエージェント指示書でドキュメントのリンク切れを監査する

開始前に必要なもの

これは手動で実行および検証する監査です。Cueは音声入力と、指定された素材に対する任意のAgentサポートを提供します。Cueがインストールされているからといって、エージェントがリポジトリを読み取ったり、イントラネットを開いたり、サイトをクロールしたり、ファイルを編集したりできるわけではありません。

開始する前に、以下のすべてを準備してください:

• Cueがインストールされ、Dictationが動作していること。マイクへのアクセス権、および使用しているプラットフォームでCueが要求する入力やアクセシビリティの権限を確認してください。外部の記事などで読んだキーの組み合わせではなく、CueのSettingsに表示されているショートカットを使用してください。Dictationのチュートリアルでは、本ガイドが前提としているフォーカス、録音状態、挿入の確認事項を扱っています。
• 編集可能な下書きノート。シェルプロンプトや自動公開されるドキュメントではなく、一時的な入力フィールドから始めてください。どこかに送信する前に、指示書を必ず確認してください。
• 削除可能なフォルダ。以下の演習では7つの小さなファイルを作成します。破棄しても問題のない場所に配置してください。誤って git add . を実行してコミットしてしまわないよう、実際の リポジトリ内には作成しないでください。
• 普段使用しているターミナル、または行番号が表示されるテキストエディタ。すべてのファイルは手動で検査できます。シェルの実行は必須ではありません。
• ご自身で接続したエージェント。インストールされているCueのAgentセレクターには、Cue、Claude、Codex、Geminiが表示される場合があります。リストに表示されていることは、接続されていること、サインインしていること、権限があること、またはディスクを読み取れることと同じではありません。レポートが実際のファイル読み取りに基づいていると想定する前に、ご自身の環境でこれらを確認してください。
• 機密情報が対象に含まれていないこと。認証情報、トークン、プライベートURL、顧客ドキュメントは含めないでください。この演習は完全に架空のものであるため、そうした情報なしで練習できます。

エージェントではなく、あなた自身が決めるべき事項が1つあります。それは「何をもってリンク切れとみなすか」です。アンカーの欠落、到達不能な外部サイト、大文字小文字の不一致、コードサンプル内のリンクなどをプロジェクトの欠陥とみなすかどうかを、監査の前に決定してください。その定義がなければ、誰も対処できないリストが生成されてしまいます。

演習: Orchid Notes ドキュメントテスト環境

Orchid Notesは、この演習のために作成された架空のノートアプリです。以下のファイルは練習用の素材であり、Cueのドキュメントでも実際のプロジェクトでもありません。外部アドレスには予約済みの .invalid サフィックスを使用しています。これはネットワークサンドボックスではないため、これらのアドレスを取得（fetch）しないでください。また、監査中はネットワークアクセスを無効のままにしてください。検証していないステータスを割り当てるのではなく、「未チェック（unchecked）」として報告させてください。

link-audit-fixture という名前のフォルダを作成し、その中に以下の7つのファイルを配置します。仕込まれた欠陥のいくつかはディレクトリ構造に依存しているため、パスは表示されているとおりに正確に維持してください。

index.md

# Orchid Notes documentation

Orchid Notes is a fictional note-taking app used only for this exercise.

- [Getting started](./getting-started.md)
- [Install guide](./guides/install.md)
- [Troubleshooting](./guides/troubleshooting.md)
- [API reference](./reference/api.md)
- [Uninstall guide](./guides/uninstall.md)
- [Release notes](./CHANGELOG.md)
- [Support mailbox](mailto:support@example.invalid)

![Architecture diagram](./assets/architecture.png)

getting-started.md — 12行目から14行目はリンク構文を示すコードブロックであり、読者がたどれるリンクではない点に注意してください:

# Getting started

Read the [install guide](./guides/Install.md) first, then open the
[API reference](./reference/api.md).

For offline setup, see [offline mode](./guides/install.md#offline-mode).

The legacy handbook lives at https://example.invalid/orchid/legacy-handbook.

Downloads are named like this in our release template:

```markdown
[Download the installer](./dist/orchid-1.2.3.dmg)
```

See [release notes]() for the full history.

CHANGELOG.md

# Release notes

## 1.2.0
Adds the sync panel. See [sync settings](./reference/api.md#sync-settings).

## 1.1.0
Fixes the export bug described in [troubleshooting](./guides/troubleshooting.md).

## 1.0.0
First release. The old notes format is documented in
[the legacy handbook](./guides/uninstall.md).

guides/install.md

# Install

## Requirements

## Desktop install

Return to the [documentation home](../index.md) or continue to the
[API reference](../reference/api.md).

If the installer fails, read [troubleshooting](./troubleshooting.md).

guides/troubleshooting.md

# Troubleshooting

## Export produces an empty file

Check the [install requirements](./install.md#requirements).

## Sync never finishes

See the [sync notes](../reference/api.md#sync-settings) and the
[status page](https://example.invalid/orchid/status).

Still stuck? Open the [support checklist](../support/checklist.md).

reference/api.md

# API reference

## Sync settings

## Export endpoint

Back to [home](../index.md).

assets/diagram.png — 任意の内容でプレースホルダーファイルを作成します。ファイル名が重要であり、内容は関係ありません。1行のテキストで十分です。

実行前に想定されるリンク切れリストを作成する

これは、この演習を行う価値を高める重要なステップです。まず模範解答を作成し、その上でレポートの内容を確認します。レポートを先に見ると、無意識のうちにそれに同調してしまいます。

仕込まれた欠陥 — 7か所、6つの異なるターゲット:

おとり項目 — リンク切れリストに含まれてはならない6項目:

D-2 と K-6 は、レポートの典型的な2つの失敗を浮き彫りにします。両方の元の場所を保持せずに D-1 と D-2 を統合してしまったレポートは、レビューすべきファイルを見落としています。また、K-6 をリンク切れとして挙げたレポートは、推測を行ったか、承認していないリクエストを実行してしまったかのいずれかです。

指示書をディクテーションしてルートを選択する

1. テスト用フォルダを作成し、想定リストを別の場所に保存します。エージェントのコンテキストに模範解答を貼り付けないでください。目的はエージェントをテストすることであり、答えが含まれた指示書では何の検証にもなりません。
2. 空白の下書きノートを開き、そのテキストフィールドにフォーカスします。Cue Settings のショートカットを使って Dictation を開始し、話し始める前に録音状態を確認してください。
3. 監査の目的と適用範囲を声に出して指示します。例えば次のように伝えます。「Audit the markdown files in this folder for links that point at files or headings that do not exist. Report file, line and exact target for each one. Do not fetch any external address. Do not edit any file. List anything you did not check separately.（このフォルダ内のマークダウンファイルを監査し、存在しないファイルや見出しを指しているリンクを検出してください。それぞれについてファイル名、行番号、正確なターゲットを報告してください。外部アドレスは取得しないでください。ファイルは一切編集しないでください。確認しなかった項目は別リストに記載してください。）」 設定した操作で停止し、処理を待ってから、挿入されたテキストを確認します。
4. テキストを送信する前に文字起こしを修正してください。パス、拡張子、大文字、そして否定の「not」などの単語は、明示的に校正する必要があります。これらが1つ変わるだけでタスクの内容が変わってしまうためです。link-audit-fixture や ./guides/install.md などの文字列は、ディクテーションするよりも元のソースからコピーしてください。識別子が勝手に変換されてしまう場合は、「正確な技術用語のディクテーション」を参照してください。
5. 3つのルートから1つを選択し、自分がどのルートを使用しているかを把握してください。これらに互換性はありません。 普段使っているエージェントへのディクテーション: ターミナルまたはエディタでコーディングエージェントの入力欄にフォーカスし、確認済みの指示書をディクテーションまたは貼り付けます。Cueはテキストを提供するだけであり、何を読み取れるかはエージェント自身の権限によって決まります。 Cue内で外部エージェントを選択: インストールされているCueでClaude、Codex、GeminiがAgentとして選択できる場合は、まずそのルートの接続、サインイン、プロジェクト、権限を確認してください。ターミナルのカレントディレクトリや過去の会話が引き継がれていると思い込まないでください。 Cue独自のAgentを選択したモデルで使用: Cueのモデルセレクターはモデルを選択するためのものです。ファイルアクセス、シェルアクセス、ネットワークアクセスを付与するものではなく、外部エージェントを接続するものでもありません。エージェントがフォルダを読み取れるか確信が持てない場合は、後述の4つ目のフォールバックルートを採用してください。
6. 手動フォールバック: 6つのMarkdownファイルをご自身で開き、機密情報を含まない内容をファイル名および行番号とともにエージェントに貼り付けます。エージェントは提供されたテキストをレビューできますが、貼り付けられた内容だけからディスクの実態を検証することはできません。この場合のレポートには、ファイルシステム監査ではなく「テキストレビュー」と明記してください。
7. テスト環境の記憶ではなく、作成しておいた想定リストとレポートを照合して読みます。仕込んだ欠陥が検出されたか見落とされたか、余計な指摘が事実に基づいているか捏造であるかを1つずつマークします。
8. 作業が完了したらテスト環境を削除するか、次に評価するエージェントやモデルのためのリグレッションテスト演習として意図的に保持しておきます。

読み取り専用の監査指示書をコピーする

ブラケットで囲まれた項目を置き換えてください。実際のタスクではプレースホルダーを残したままにせず、実行を成功させるために勝手にスコープを広げないでください。

Task: Audit documentation links. Read-only. Do not edit, create, move or delete any file.
Scope: [absolute path to link-audit-fixture], markdown files only, no subdirectories outside it.
Definition of broken, for this audit:
- a relative link or image whose target file does not exist
- a link to a heading anchor that does not exist in the target file
- a link with an empty target
- a target whose spelling differs from the file on disk, including capitalisation
Out of scope, list separately and do not call broken:
- external http and https addresses. Do not request them. Approved list: [none]
- mailto and tel links
- links that appear inside fenced code blocks, which are examples, not links
For every finding return: file path, line number, the exact link target as written,
which of the four categories above it falls into, and the evidence you used.
If you did not open a file, say so. If you inferred rather than checked, say so.
List every link you could not classify in an "unchecked" section with the reason.
Do not propose edits yet. Do not run any command that writes. Do not fetch anything.
Report only. Wait for my next instruction.

「approved list: [none]（承認リスト: なし）」という行は意図的なものです。この演習には、架空の外部アドレスを取得する理由がありません。実際の外部リンクを後で監査する場合は、個別に承認されたリストと、ネットワークアクセスがそのリストに制限されたツールが必要です。読み取り専用のリクエストであっても、アドレスを開示してしまったり、プライベートな環境、認証が必要な環境、またはレート制限のあるシステムに到達してしまったりする可能性があります。読み取り専用＝オフラインではありません。この演習をパスさせるためだけに、エージェントに認証情報を渡すようなことは決してしないでください。

レポートをただ読むだけでなく採点する

具体例（合成例であり、実際のエージェント実行結果ではありません）: あるレポートが D-1、D-2、D-3、D-6、D-7 を検出し、K-5 にもフラグを立て、K-6 を未チェックに分類したとします。この場合、仕込まれた欠陥を5件検出し、D-4 と D-5 を見落とし、K-5 という1件の誤検出（フォールスポジティブ）を生じさせています。今回のオフラインスコープにおいて、K-6 を未チェックのままにしたのは正しい判断です。単に「監査完了」と受け入れるのではなく、これら3つの分類をご自身のレビューに反映させてください。

エージェントのレポートと模範解答を用意し、一度に通しで照合します。ご自身で以下の3つの項目を判定します:

次に、監査前にエージェントの書き込み可能スコープ外に保存しておいたベースラインと、実際のファイルを比較します。ファイル一覧とコンテンツのハッシュ値を比較してください。リポジトリの場合は、該当する場合、追跡対象外や無視されたファイルを含めて git status と git diff を確認します。Gitのステータスに変更がないことや、タイムスタンプが更新されていないことだけでは、一時的な書き込みがなかったことや、データが読み取られて送信されていないことの証明にはなりません。これらの確認は最終的なファイル状態を検証するだけです。読み取り専用やオフラインの制約を徹底するにはツールの実行権限の制御が必要であり、呼び出し履歴はそれを裏付ける証拠となります。エージェントが「変更は行いませんでした」と述べたとしても、それ自体は何の変更も行われなかった証拠にはなりません。

確認できた項目は件数としてカウントしてください（仕組んだ7つのうち何件が指摘され、余計な主張が何件捏造されたか）。スコア、パーセンテージ、精度などの数値に変換しないでください。架空の1つのフォルダにある7つの欠陥だけではそうした指標を裏付けることはできず、根拠のない数字だけが一人歩きしてしまう危険があります。

D-4 や D-5 を見落としたレポートであっても、無駄ではありません。そのエージェントの対応範囲を把握できたことになります。採点の目的は、その特定のルートにある特定のエージェントが実際にどのカテゴリを検査できるのかを把握し、自分自身で追加確認すべき項目を明確にすることです。

制限事項

• これはMarkdownファイルのフォルダを監査するものです。レンダリングされたサイトの状態、リダイレクト、テンプレートによって生成されたリンク、HTML属性内のリンク、ビルド時に組み立てられるリンクの状態を検証するものではありません。これらを検証するにはクローラーと別の権限が必要です。
• 設計上、外部リンクは一切チェックしません。架空の .invalid アドレスは未チェックのままとなります。予約済みのサフィックスが付いているからといって、ツールがネットワークリクエストを行わなかったことの証明にはなりません。実際の外部リンクの監査には、承認されたスコープを別途設定する必要があります。
• 問題なく完了したからといって、ドキュメントが正しいとは限りません。リンクが間違ったページを解決している場合もありますし、ページが存在していても内容が古い場合もあります。リンクの存在確認は検証コストが最も低い項目に過ぎず、最も重要な項目というわけではありません。
• テキスト検索はMarkdownパーサーではありません。単純な文字列検索では、コードブロック内の例をリンク切れとして報告したり、生のURLや参照形式のリンクを見落としたりする可能性があります。一致した内容を欠陥として扱う前に、ドキュメントレンダラーの仕様を確認してください。
• ファイルシステムの動作は環境によって異なります。D-4 のファイル存在チェックは、ローカルのファイルシステムが大文字と小文字を区別するかどうかに依存します。同じ監査でも、MacとLinuxのCIランナーでは結果が正当に異なる場合があります。
• ここでは組み込みのリンクチェッカーの検証は行っていません。これは監査の指示書を音声で取得し、エージェントに依頼する範囲を制限するための方法であり、Cueの全機能を網羅したものではありません。特定のエージェントがフォルダを読み取れるかどうかは、インストールされているバージョンで確認してください。
• 1つのテスト環境はあくまで1つのサンプルです。ここでの採点結果が良好であっても、大規模な実際のリポジトリ、別のモデル、あるいは別のルートでの動作を保証するものではありません。

ステップで問題が発生した場合のリカバリ

Cue自体の問題については、プラットフォーム、Cueのバージョン、モード、および機密情報を伏せた実例を添えて「Cueサポートに問い合わせる」をご利用ください。プライベートなドキュメント、リポジトリの内容、トークンなどは送信しないでください。

スケールアップ前に答えておくべき質問

なぜ実際のドキュメントで最初に実行せず、意図的に欠陥を仕込むのですか？ 見慣れないドキュメントでは、「何も検出されなかった」の裏に「何もチェックしていなかった」という事実が隠れている可能性があります。テスト環境を用意することで、実行前に正解を把握できます。実際のリポジトリでは、別途カバレッジの確認が必要です。

一度採点した後も、テスト環境を保持しておくべきですか？ 維持コストは低く、モデル、エージェント、またはルートを変更した際に役立ちます。公開対象のリポジトリの外で保管し、模範解答も同じ場所に置いて内容が乖離しないようにしてください。

エージェントにリンク切れの修正を直接依頼してもよいですか？ 修正は、独自のレビューを伴う個別の承認タスクであり、これらの欠陥のほとんどには複数の正しい修正方法があります。例えば uninstall.md の場合、不足しているページを作成する、リンクを削除する、別の場所を指定するなど、さまざまな選択肢があり、これは編集上の判断事項です。まずは監査を採点し、次に修正案を提示させ、適用はご自身で行ってください。

どのモデルを使用すべきですか？ モデル名だけでなく、そのルートが実際に何を読み取れるかから検討してください。ファイルアクセス権のないモデルは、その制限を開示すべきです。しかし、一度も開いていないファイルについて、もっともらしいレポートを作成してしまう可能性もあります。この演習は、そうした問題を発見するのに役立ちます。正直に「未チェック」と報告するモデルは、監査を完了できていないものの、結果を捏造してもいません。

情報源と関連ワークフロー

上記のテスト環境、その欠陥、およびエージェントの動作例は演習用の素材です。本ガイドのいかなる部分も、Cueまたは特定のエージェントの定量的な成果を主張するものではありません。この公開バージョンでは、実行可能なリンクチェッカースクリプトではなく、手動での検証演習を採用しています。インストールされているCueのバージョン、画面に表示されるコントロール、およびエージェントの権限が、ここに記載された内容よりも優先されます。

• Cue Dictationチュートリアル: フォーカス、録音状態、挿入の確認。
• Cue Voice Agentチュートリアル: 明示的なコンテキスト指定とアクション前のレビュー。
• コーディングエージェントとCueの連携: ツールへのディクテーション、外部エージェントの選択、Cueのエージェントを選択したモデルで使用する場合の違い。
• Codexを使用したコード変更のレビュー: ドキュメントツリーではなくdiffに適用される同様の根拠確認ルール。
• 正確な技術用語のディクテーション: パス、バージョン、識別子を正確に維持する方法。
• 選択したコンテキストを完了タスクに変換する: 監査によって実際に対処すべき作業が特定された後の進め方。