ai-docs

README

17 min read

ai-docs — AI活用ベストプラクティス

AI（LLM / エージェント）を使う際の実践知を、一次情報源から自分で読んでまとめた個人用の知識ベース。

情報源は Anthropic の Engineering ブログ、Claude Code ドキュメント、Claude Developer Platform ドキュメント。 ディレクトリ名をベンダー非依存にしてあるのは、将来 Anthropic 以外の知見を足しても名前が嘘にならないようにするため。

記述言語は日本語、technical term は英語のまま（context window, evals, harness など）。原典と照合しやすさを優先している。

原典からの引用は、英文をそのまま残したうえで、引用ブロック内の直下に訳を併記する。

> **The context window is a public good.** — [[agent-skills-best-practices]]
> **context window は公共財である。**

英文を訳に置き換えないのは、上と同じ理由（原典と照合できること）による。逆に訳を付けないと日本語資料として読めないため、両方を置く。 なお原典の英語タイトルは訳さない（frontmatter の title、SOURCES.md の記事一覧）。原典を検索・特定するための固有名なので、そのまま残す。

構成

ai-docs/
├── index.md       サイトのトップページ。読む順の入口
├── README.md      ← いま読んでいるファイル
├── PRINCIPLES.md  そのまま行動に移せる一文だけ38件。作業前に眺める用
├── QUOTES.md      原典のことばだけ57件。まずここを読むと全体像が通る
├── OVERVIEW.md    78本を1ページに。横断して初めて見えるものだけを置く
├── SOURCES.md     原典の台帳。何を読むべきか / どこまで取り込んだか
├── DECISIONS.md   運用ルールの根拠。結論だけでは理由が分からないものを置く
├── _TEMPLATE.md   sources/ を1本追加するときのひな形
├── sources/       原典1本 = 1ファイル。原典の主張だけを書く（78本）
├── topics/        複数原典を横断して統合した読み物（10本）
├── scripts/       freshness-check.sh
└── site/          静的サイトの構成（Quartz の設定とビルド手順）

トップレベル文書の使い分け:

何のためか
README.mdどう運用するか。 ルール、書き方、鮮度の確認手順
PRINCIPLES.md結局どう動けばいいか。 命令形・判断基準になる一文だけ38件
QUOTES.md原典が何と言っているか。 Anthropic 自身の言葉だけを57件、読む順に並べたもの
OVERVIEW.md何が分かっているか。 数字・判断の分岐点・原典どうしの食い違い
topics/テーマごとに結局どうすればいいか。 OVERVIEW を10テーマに深掘りしたもの
SOURCES.mdどこに何があるか。 原典の台帳と優先度
DECISIONS.mdなぜそう決めたか。 README のルールの根拠と、うまくいかなかった結果

sources/ と topics/ を分ける理由は2つ。

  1. 更新の局所化 — 原典が変わったとき、直す場所が sources/ の1ファイルに限定される。混ぜていると全文検索して探す羽目になる
  2. 出所の区別 — 1年後に読み返したとき、どこまでが Anthropic の主張で、どこからが自分の解釈かが分かる

DECISIONS.md に書くかの判断基準は「結論から理由が推測できるか」。 推測できるならここに一行書けば足りる。うまくいかなかった結果も書く（コミット履歴からは実質的に読み返せないため）。

読む順

まず全体像を掴むなら

  • QUOTES.md — **まずこれ。**原典のことばだけ57件。5分で「何が問題で、何が答えとされているか」が通る
  • PRINCIPLES.md — 作業を始める前と迷ったときに。行動に直結する38件だけ
  • OVERVIEW.md — 78本を1ページに圧縮したもの。制約 → 判断の早見表 → 数字 → モデル世代の落とし穴 → 原典どうしの矛盾の順。ここだけ読んでも実務は回る
  • 深掘りしたいテーマが決まったら topics/（10本）へ

AI活用全般をこれから学ぶなら

  1. sources/building-effective-agents.md — workflow と agent の区別。「最も単純な解から始めよ」
  2. sources/effective-context-engineering-for-ai-agents.md — context を「予算」として扱う考え方
  3. sources/writing-tools-for-agents.md — エージェントに渡すツールの設計
  4. sources/agent-skills-best-practices.md — エージェント向けドキュメントの書き方

Claude Code をうまく使いたいなら

  • sources/claude-code-best-practices.md 一本で足りる。ここが最も実務直結。

API でエージェントを組むなら

  1. sources/claude-prompting-best-practices.md — 全モデル共通の技法。公式の living reference
  2. sources/develop-tests.md — 成功基準と eval。prompting の前にこれ
  3. sources/manage-tool-context.md — ツール由来の context 圧迫への4つの対処と導入順
  4. sources/effort.md + sources/thinking.md — コストと知能のダイヤル

特定の疑問があるなら

SOURCES.md で該当領域の原典を探す（§1〜§4 はすべて取り込み済み）。 用語から引きたいときは sources/glossary.md の索引を使う。

原典を日本語で読む（よく使うもの）

Engineering ブログ（anthropic.com/engineering/*）は英語のみ。

よくある疑問への近道

疑問見る場所
サブエージェントはいつ使うべきかclaude-code-best-practices.md §7「調査には subagent」、effective-context-engineering...md「Sub-agent architectures」
context window が埋まってきたらどうするかclaude-code-best-practices.md §7「コンテキスト管理」、effective-context-engineering...md「Compaction」
CLAUDE.md に何を書くべきかclaude-code-best-practices.md §4（入れる/入れない対照表あり）
エージェントを作るべきか、単発の LLM 呼び出しで足りるかbuilding-effective-agents.md「エージェントを使うべきでないとき」
ツールの設計が悪いのか判断したいwriting-tools-for-agents.md「ツール設計 7原則」、define-tools.md「description は3〜4文以上」
Skill / hook / MCP / subagent のどれを使うかfeatures-overview.md（用途別の対照表と「いつ足すか」の引き金表）
~/.claude に置くか、リポジトリに置くかtopics/user-config.md（個人スコープでだけ起きること）
compaction で何が消えるのかcontext-window.md「compaction で何が生き残るか」の表
ツールが増えすぎて context を食うmanage-tool-context.md（4手法と導入順）、tool-search-tool.md
モデルを変えるか effort を変えるかchoosing-a-model.md、effort.md
prompt injection をどう防ぐかmitigate-jailbreaks.md（prompt 側）、secure-deployment.md（環境側）
eval が突破された / スコアが信用できないAI-resistant-technical-evaluations.md、infrastructure-noise.md、eval-awareness-browsecomp.md
他社/他チームは実際どう使っているかhow-anthropic-teams-use-claude-code.md（社内10チームの事例と tips）
コピペできるプロンプトが欲しいprompt-library.md（52件を SDLC フェーズ別に収録）

運用ルール

原典を1本追加する

  1. _TEMPLATE.md をコピーして sources/<slug>.md を作る
  2. WebFetch などで原典を実際に取得してから書く。記憶で書かない
  3. frontmatter の url にはリダイレクト後の実URLを、fetched には取得日を必ず入れる
  4. 引用した英文には訳を併記する（scripts/freshness-check.sh の 5 で検出できる）
  5. SOURCES.md の該当行を ⬜ → ✅ に更新する

書かないこと

  • 原典の全訳（要点と、そのまま使える具体例に絞る）
  • モデルバージョン固有のベンチマーク数値（すぐ古くなる。触れる場合は必ずモデル名を併記）
  • 時間依存の表現（「現在は」「最近」）。日付を書く

鮮度を確認する

./scripts/freshness-check.sh          # 月1回。理由は DECISIONS.md #6

URL の生存 / fetched の古さ / wikilink の解決 / 引用の訳漏れを一度に見る。

引用が原典と一致しているかは別のスクリプトで見る:

python3 scripts/audit.py

ルートと topics/ の全引用について、出典として示した sources/ に実在するかを照合する。 言い換えを引用ブロックに入れてしまう事故（DECISIONS.md #8）は、これでしか見つからない。 件数の整合・引用ゼロの sources/・陳腐化しやすい表現もあわせて見る。 whats-new の最新エントリだけは自動化していない（DECISIONS.md #2）ので、 スクリプトが促したら原典の最上部を目視で確認する。

サイトとして見る

bash site/build.sh --serve      # http://localhost:8321
bash site/build.sh              # ビルドのみ

Quartz でこのリポジトリを静的サイトにする。738本の [[wikilink]]（2026-08-17 時点）がそのまま解決し、backlink と日本語全文検索が付くのが採用理由。

隔離してビルドする（依存を信用しきれないとき）:

bash site/build-docker.sh      # 出力: ~/.cache/ai-docs-site

リポジトリを読み取り専用でマウントし、ホームディレクトリを渡さないので、~/.ssh などに到達できない。手順は build.sh と同じものを中で走らせる。

リポジトリには Quartz を入れていない。 site/build.sh が実行時に clone し、作業ディレクトリは既定で ~/.cache/ai-docs-quartz（node_modules 243MB）。ここを消しても再実行すれば同じ状態に戻る。

設定は基本デフォルトにしてある。 既定から変えているのは次の5つだけで、どれも機能を失わない。

変更理由
npm ci --ignore-scriptsインストール時の任意コード実行を止める。native binary は別パッケージで配られるので揃う
analytics: null既定は plausible。使わないので明示的に無効化
pageTitle: ai-docs既定の Quartz 5 が全ページのタイトルと OG に出てしまう
locale: ja-JP本文が日本語。既定は en-US
baseUrlOG画像・sitemap・RSS の絶対URLの土台。既定の localhost:8080 のまま公開すると全部壊れる

公開する（Cloudflare Pages）

公開先: https://ai-docs-5io.pages.dev

npx wrangler login    # 初回のみ。ブラウザが開く
bash site/build.sh
npx wrangler pages deploy ~/.cache/ai-docs-quartz/public --project-name=ai-docs

wrangler login はブラウザを開いて許可を待つ対話フローなので、エージェントに実行させると出力が返らず止まる。自分で叩くこと（Claude Code なら ! npx wrangler login）。認証済みかどうかは npx wrangler whoami で分かる。

手元でビルドしてから直接アップロードする方式にしている。Git 連携ではないので remote を必要とせず、何を公開するかを送信前に手元で確認できる。

送信されるのは public/ の中身だけで、git リポジトリは含まれない。 したがって commit author のメールアドレスやコミットメッセージは公開されない。ただし README.md 自身はサイトの一部として公開される（readme.html）ので、ここに手元固有のパスや個人的なメモを書かないこと。

baseUrl は公開先と一致していなければならない。 絶対URL（OG画像・sitemap・RSS）はビルド時に焼き込まれるので、アップロードし直すだけでは直らない。独自ドメインを足したときや公開先が変わったときは、site/quartz.config.yaml を直してビルドし直してから再アップロードする。

サブドメインはプロジェクト名から導けない。 ai-docs は既に他アカウントで使われていたため、Cloudflare が接尾辞を付けて ai-docs-5io.pages.dev を割り当てた（プロジェクト名自体は ai-docs のまま）。実際に割り当てられた値は npx wrangler pages project list で確認する。

public/CNAME が生成されるが、これは GitHub Pages 向けの成果物で Cloudflare Pages では参照されない。害はないので放置してよい。

詰まったときのメモ

  • Could not detect a directory containing static files: wrangler 4.123 以降、pages deploy は新しい Pages on Workers に委譲される。プロジェクトが存在しないとこのエラーになる（ディレクトリ指定は誤りではない）。初回だけ npx wrangler pages project create ai-docs --production-branch main で作り、--force を付けて旧 Pages に直接デプロイする。プロジェクト作成後は --force は不要。
  • 作業ツリーが dirty だと警告が出るが、アップロード内容には影響しない（--commit-dirty=true で黙る）。

Google Fonts・mermaid・cdnjs への preconnect は既定のまま。いずれも脆弱性ではなく、閲覧者の IP が Google と Cloudflare に渡るというプライバシー上の性質。気になったら site/quartz.config.yaml で切れる（ただし mermaid を切ると図が描けなくなる）。

site/quartz.config.yaml は消さないこと。 Quartz 本体の git に含まれない生成ファイルなので、ここで保持していないと clone し直した時点で設定（latex 無効化、_TEMPLATE.md 除外）が失われる。

Quartz の版はコミット SHA で固定している（site/build.sh の QUARTZ_REF）。タグ v5.0.0 は5ヶ月古く CLI も設定スキーマも違って動かない。上げるときは必ずローカルで通してから SHA を差し替える。

日本語版ドキュメントについて

読むのは日本語版でよい。 運用は次の4つ。

  • **frontmatter の url は英語版を正とする。**理由はカバレッジでも鮮度でもなく、翻訳で具体的なコマンド・フラグ・条件が落ちるから
  • url_ja を併記し、普段はそちらを読む
  • コマンドやフラグを実際に打つ前、および説明が腑に落ちないときは en を見る
  • Engineering ブログ（anthropic.com/engineering/*）に日本語版は存在しない（404 を確認済み）。選択の余地なし

根拠は DECISIONS.md 1（43ページの到達性テスト、本文突き合わせ、欠落の全8例）。当初想定していた「カバレッジが悪い」「翻訳が遅れる」はどちらも実測で否定された**ので、そこを疑い直す必要はない。

現状

  • sources/ 78本（2026-08-12 時点）。SOURCES.md に台帳化した原典はすべて取り込み済み
  • topics/ 10本執筆済み。78本中74本がいずれかの topic から参照されている（残り4本の除外理由は topics/README.md）
  • 今後の作業は「新規取り込み」ではなく鮮度の維持（SOURCES.md §5、scripts/freshness-check.sh）

グラフビュー

バックリンク