AI導入ガイド

素のLLMは確率的生成器である

LLMは「次に来る可能性が最も高いトークンを連続して選ぶ」という操作の繰り返しで動いている。入力テキストを数値ベクトルに変換し、学習済みの重みを通じて確率分布を計算し、そこからサンプリングする。検索でも計算でも記憶の呼び出しでもない。

実務では外部資料・SSOT・ツール・人間レビューが加わる

現実のAI活用では、素のLLMに加えて複数の補強機構が動作する。検索拡張（RAG）によって一次ソースの文書を文脈に注入したり、ツール呼び出しでリアルタイムのデータを取得したりする。それでも最終的な品質は人間のレビューと承認に依存する。

もっともらしさと正しさは別である

失敗例

AIに「我が社の昨年の売上を教えて」と尋ね、
返ってきた数値をそのまま報告資料に記載した。

実際は学習データにその情報が含まれておらず、
もっともらしい数値が生成されていた。

AIには「このCSV（実績データ添付）を
分析して傾向を要約して」と依頼する。

AIが使う数値は自分で提供したもの。
要約の論理はレビューで確認する。

良い運用

判断基準

文脈は有限である

LLMが一度に処理できるテキストの量には上限（コンテキストウィンドウ）がある。Anthropicの表現を借りれば「LLMにはアテンションバジェットがある」。会話履歴・指示・参照ファイル・システムプロンプト、すべてがこの有限な空間を共有している。

長すぎるとノイズが増える

コンテキストが長くなるほど、AIは全体に均等に注目できなくなる傾向がある。重要な指示が文脈の途中に埋もれると、それが参照されにくくなる現象（context rot）が実務上問題になる。これは機構の詳細より「長い文脈では精度が落ちやすい」という現象として理解しておけば十分である。

添付します：
- 過去3年分のすべての会議議事録
- 全部門の予算データ（未整理）
- 関係するかもしれないメール200通
- 過去の類似案件資料

これを参考に提案書を書いてください。

目的：Q3の営業提案書（A4・2枚）
参照：今期の製品仕様書（添付）
制約：競合他社の名指し禁止
対象：製造業・中規模企業の調達担当

上記だけを根拠に構成案を出してください。

重要なのは「何を足すか」より「何を残すか」

Anthropicが「文脈エンジニアリング」と呼ぶ考え方の核心は、「LLM推論中に最適なトークンの集合をキュレーションし維持するための戦略」にある。「追加する」ではなく「最適化する」という発想の転換が必要だ。

失敗例

ある担当者がドキュメント整理をAIに依頼した。「参考になるかもしれない」と判断した100ファイルを一括で貼り付けた結果、AIは重要な制約条件（ファイル末尾に記載）を参照できず、不適切な分類を大量に出力した。確認に要した時間は生成時間の10倍になった。

良い運用

判断基準

指示の6要素

Good/Bad比較 — なぜBadが失敗するのか

Badな指示では、AIが「空白」を確率的に補完する。学習データの中の「似た文脈でよく来るパターン」で埋めるため、意図と外れた出力が生成される。

売上データを分析して

Q3の月次売上（添付CSV）を分析し、
経営会議向けに3点の改善提案を
箇条書きで出してください。
金額は百万円単位、小数点1桁。

競合との違いをまとめて

競合製品Xとの機能比較表を作成してください。
制約：競合名は「他社製品A」と匿名化。
自社優位点は3点以内。根拠のない主張は禁止。

このメールに返信して

以下のメール（引用）に返信文を書いてください。
形式：ビジネス敬語、200字以内、
件名含む。謝罪は入れない。
---
（メール本文）

この企画書を改善して

添付の企画書を改善してください。
優先順位：1）論理構成の明確さ
2）実行可能性の具体性
3）読みやすさ
現在の文章は保持し、追記で改善点を示す形式で。

うちの商品の特徴を説明して

以下の製品仕様（添付）をもとに、
初めての顧客向けの特徴説明を書いてください。
専門用語は使わず、利用シーン3例を含む。
（製品仕様書の抜粋）

失敗例

ある担当者が「契約書のリスクを洗い出して」とだけ指示した。AIは「よくある契約書レビューのパターン」で確率的補完を行い、その会社特有の業法規制リスクを見落とした汎用的なチェックリストを返した。依頼者はそれをそのまま使い、後から弁護士に指摘を受けた。

判断基準

指示を送る前に次の問いを確認する。「AIがこの指示の空白部分を何で埋めるか」を想像できるなら、その空白は明示すべき箇所だ。

AIは加速装置である

AIはドラフト作成・構造化・パターン認識・要約といった反復的作業を劇的に速くする。しかし速さは正確さを保証しない。「速く間違える」リスクを理解した上で使う必要がある。特に、確定した正解が必要な場面・間違いの影響が大きい場面・一次ソースで検証しにくい場面では、人間の判断をAIに置き換えてはならない。

ユースケース分類

3軸判断表

以下の3軸でタスクを評価する。「高・高・低」の組み合わせは人間が主体で対応すべき領域だ。

失敗例

ある担当者がAIに「競合調査をして」と依頼し、返ってきた競合情報をそのまま営業資料に使った。AIが生成した「競合の製品価格」はカットオフ以前の情報であり、現在の実際の価格と乖離していた。顧客提案の場で指摘を受け、信頼を損ねた。

良い運用

判断基準

タスクを前にして次の問いを立てる。「このタスクでAIが間違えた場合、どのフローで検出できるか」が答えられないなら、AIを主体で使うべきではない。

流暢な出力ほど危険である理由

人間は流暢で自信に満ちた文章を読むと、批判的思考が緩む傾向がある。AIの出力は構造的に流暢になるよう最適化されているため、誤った内容であっても自信を持って語られる。これは「ハルシネーション」が「明らかな間違い」として出てくるのではなく、「もっともらしい誤り」として出てくる理由でもある。

生成コストより検証コストの方が本質

AIを使えば生成コストは劇的に下がる。しかし検証コストは下がらない。むしろ「大量に・速く・流暢に」生成できるようになったことで、検証しきれずに誤りが通過するリスクが上がる。AI活用のROIは「生成が速くなった」ではなく「検証が追いついているか」で測るべきだ。

生成: 10分 → AIで2分（80%削減）
検証: 省略（「AIだから大丈夫」）
結果: エラーが本番環境に流入
コスト: 修正に元の10倍の時間

生成: 10分 → AIで2分（80%削減）
検証: 3分（定型チェックリスト）
合計: 5分（従来比50%削減）
品質: 保持または向上

数値・ロジック・コードで何をどう確認するか

責任3層モデル

AI活用における責任は次の3層に分かれる。最終的な品質責任は必ず人間が負う。

失敗例

ある担当者がAIに財務サマリーを作成させ、「AIが出したから正しいはず」という認識でそのまま経営会議に提出した。数値の単位（百万円と億円）が混在していたが、流暢な文体のため読み飛ばされた。会議の途中で指摘を受け、再集計に一週間かかった。

良い運用

判断基準

結論

CLAUDE.mdはプロジェクトの憲法であり、セッションをまたいで常に有効な原則だけを記述する。コマンド一覧、制約、言語設定はここに置く。一方、チャートパターンやデプロイ手順のような「必要なときに参照する手順」はskillsへ、セキュリティチェックやログ出力のような「実行のたびに動く検査」はhooksへ分離する。この三分割が機能することで、CLAUDE.mdは軽量かつ確実に読まれる文書になる。

失敗例

# CLAUDE.md（肥大化版）
コマンド: uv run pytest -x
デプロイ手順: wrangler pages deploy ...
チャート実装: floating bars [[start,end]]...
セキュリティ: rm -rf を検知したらブロック
ログ: tool_logger.py を呼べ
言語: 日本語出力

# CLAUDE.md（憲法版）
## コマンド
uv run pytest -x   # テスト
uv run ruff check  # Lint

## 制約
- Bash: > /dev/null 2>&1
- Cloudflare: 25MB制限

## 言語
日本語出力。変数名は英語。

良い運用 — 三分表

スコープは三階層で管理する。グローバル設定（~/.claude/）はモデル選択・認証のみ。プロジェクト設定（project/.claude/）はhooks・permissions・skills。サブプロジェクト（projects/X/）はそのプロジェクト固有の制約を上書きする。完全分離ではなく、共通文脈と局所文脈の階層化が目的だ。

判断基準

「これはセッションをまたいで常に守るべきか？」と問え。YESならCLAUDE.md。「必要なときだけ参照するか？」ならskills。「コード実行のたびに自動で走らせるか？」ならhooks。この問いを省略すると、肥大化したCLAUDE.mdが生まれ、AIは大量のノイズの中から本当の制約を見つけられなくなる。ハーネスなしにはAIは暴走する。

結論

Anthropicはコンテキストウィンドウが拡張するにつれてAIの性能が劣化する現象を「文脈腐敗（context rot）」と呼ぶ。長いセッションには過去の失敗、撤回された指示、関係のない情報が蓄積し、AIは新しい指示よりも古いノイズに引きずられる。これを防ぐのが文脈衛生だ。

失敗例

A機能の実装が終わったあと、/clearを打たずにB機能の指示を出した。AIはAの実装で採用したアーキテクチャをBにも適用しようとし、要件が異なるにもかかわらず同じパターンで実装した。古い文脈が新しい判断を汚染した典型例だ。

良い運用 — 判断テーブル

LangChainのコンテキストエンジニアリングでは、文脈操作をWrite（追加）・Select（選択）・Compress（圧縮）・Isolate（分離）の4操作として整理している。/compactはCompressに、/clearはIsolateに対応する操作として理解できる。これは「理解のレンズ」として有効だが、Claude Codeの3コマンドと直接1対1で対応するわけではない点に注意する。

判断基準

「前のタスクの情報は今のタスクに役立つか？」と問え。役立たないなら /clear。役立つが量が多いなら /compact。セッションを続けながらAIの現在地を知りたいなら /context。この判断を怠ることがAIの迷走の主因になる。文脈は設計するものだ。

結論

Plan Modeとはコードを書く前にAIに計画を出力させる運用パターンだ。Anthropicはエージェントの長期実行において「一度に一機能ずつ作業する」ことを推奨している。Plan Modeはこの原則を実践するための整流器として機能する。計画段階で矛盾・見落とし・依存関係の問題を発見することで、実装後の大規模な手戻りを防ぐ。

当チームの運用規律として、3ステップ以上にわたる実装は必ずPlan Modeを経由する。この「3ステップ以上」はチームが決めた閾値であり、一般的な正解ではない。ただし実際には、1ファイルの小修正を除くほぼすべての実装がこの基準に該当する。

失敗例

「ダッシュボードにYTD累積チャートを追加して」

→ AIが即座にコードを書き始める
→ データ構造の前提が違った
→ 既存チャートのレイアウトを壊した
→ 全面書き直し

「ダッシュボードにYTD累積チャートを追加する。
まず実装計画だけ出力して。コードはまだ書かない」

→ AIが計画を出力
→ データ構造・影響範囲を確認
→ 合意後に実装開始
→ 一発で通る

良い運用 — Plan → Implement → Verify

Planフェーズでは計画と受入基準の両方を合意する。「何を作るか」だけでなく「何をもって完了とするか」を先に決めることで、Verifyフェーズの判断が機械的になる。Anthropicの推奨する増分実行（incremental execution）とも整合する。

判断基準

「この実装は1ファイルの単純な修正か？」という問いから始める。NOであればPlan Modeを使う。当チームでは3ステップ以上を基準としているが、本質は「実装後の手戻りコストが計画のコストを上回る可能性があるか」だ。複数ファイル・データ構造変更・UI変更が重なるときは必ずPlanを先に出力させる。

結論

hooksはClaude Codeがツールを呼び出す前後に自動実行されるスクリプトだ。自然言語で「危険なコマンドは実行しないで」と書いても、長いセッションの中でその制約が無視されることがある。hooksはその問題を解決する。実行タイミングで機械的に検査・記録することで、AIの挙動を構造的に制御する。ハーネスなしにはAIは暴走する — これがhooksの存在理由だ。

失敗例

CLAUDE.mdに「rm -rfは使わないこと」と書いていたが、AIが生成したクリーンアップスクリプトにそのコマンドが含まれていた。自然言語の制約はAIのトークン予測から「忘れられる」。PreToolUseがあればその瞬間にブロックされていた。

良い運用 — Hook ライフサイクル

コード例 — PreToolUse（危険コマンド検知）

# PreToolUse: 危険パターン検知
import json, sys

DANGEROUS = ["rm -rf", "DROP TABLE", "force push"]
data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "")

if any(p in command for p in DANGEROUS):
    print(json.dumps({"decision": "block", "reason": "危険コマンド検知"}))

import json, sys

DANGEROUS_PATTERNS = [
    "rm -rf",
    "DROP TABLE",
    "DROP DATABASE",
    "force push",
    "--force",
    "git push -f",
]

def main():
    data = json.load(sys.stdin)
    tool_name = data.get("tool_name", "")
    tool_input = data.get("tool_input", {})
    command = tool_input.get("command", "")

    if tool_name == "Bash":
        for pattern in DANGEROUS_PATTERNS:
            if pattern in command:
                result = {
                    "decision": "block",
                    "reason": f"危険コマンド検知: {pattern}"
                }
                print(json.dumps(result))
                return

if __name__ == "__main__":
    main()

コード例 — PostToolUse（ツール使用ログ）

# PostToolUse: ツール使用をJSONLログに記録
from datetime import datetime
LOG_PATH = ".claude/logs/tool-usage.jsonl"

data = json.load(sys.stdin)
tool_name = data.get("tool_name", "")
file_path = data.get("tool_input", {}).get("file_path", "")

entry = {"ts": datetime.now().isoformat(), "tool": tool_name, "file": file_path}
with open(LOG_PATH, "a") as f:
    f.write(json.dumps(entry) + "\n")

{
  "hooks": {
    "PreToolUse": [
      {"command": "python .claude/hooks/security.py"}
    ],
    "PostToolUse": [
      {"command": "python .claude/hooks/tool_logger.py"}
    ]
  }
}

判断基準

「これをCLAUDE.mdに書いても守られなかったことがあるか？」と問え。YESならhooksに移す。安全制約・強制ログ・外部APIへの二重呼び出し防止など、人間の監視なしに毎回確実に実行されなければならないものはすべてhooksの候補だ。hookは軽量なPythonスクリプトで足り、複雑なロジックは不要だ。

結論 — 5レイヤーの分業

skillsはmarkdownファイルであり、AIが「必要なときに」参照する手順書だ。チャートの実装パターン、デプロイ規則、KPI定義など、常時メモリに置く必要はないが確実に正確であるべき知識を置く。agentsはサブエージェントとして特定の役割を持つ。Anthropicが推奨するtwo-agent pattern（例: impl-agentとreviewer）はお互いの盲点を補完する。

失敗例

skillsを作らずにすべての手順をCLAUDE.mdに書いたプロジェクトでは、CLAUDE.mdが6000トークンを超えた。AIはその冒頭にある「言語設定」すら参照できなくなり、英語で出力し始めた。必要時手順を常設ファイルに置いたことが、本来守るべき原則を見えなくした。

良い運用 — FP&Aダッシュボード生成パイプライン

判断基準

5レイヤーのうちどれが欠けているかを確認する。CLAUDE.mdだけあってhooksがないなら、制約は自然言語のお願いに依存している。skillsがなくてCLAUDE.mdが肥大化しているなら、必要時手順を移す。agentsがなくて1つのプロンプトに実装・レビュー・テストを混在させているなら、役割分担を設計する。ハーネスなしにはAIは暴走する — この原則は5レイヤーすべてを貫く核心だ。

環境サマリー

ディレクトリ構成 — 5レイヤーの物理配置

24 Skills — カテゴリ別一覧

全スキルは自動起動。description の "Use when..." でAIが文脈に応じて自動参照する。CLAUDE.mdに書くには多すぎる知識を、必要な瞬間にだけロードする仕組み。

Hooks — 4つの機械的検査

S9で解説したhooksの実装。「お願い」では漏れる検査を、イベント駆動で100%実行する。

5 Agents — 役割分担

Anthropicの two-agent pattern を拡張。メインはOpus、サブエージェントはSonnet/Haikuでトークンコスト最適化。

7 Projects — モノレポ内の独立ダッシュボード群

CLAUDE.md — 常設原則の実物

S6で「何を書くか・何を書かないか」を設計すると述べた。実際のCLAUDE.mdは以下の構造で、約40行に収まっている。

永続記憶 — Auto Memory

セッションを超えて蓄積されるファイルベースの記憶システム。MEMORY.md（インデックス）+ 個別の記憶ファイルで構成。

教訓 — 失敗から学ぶ自動フィードバック

session_start hookが毎セッション冒頭で直近の教訓をロードする。過去の失敗をAIが繰り返さないための仕組み。

まとめ