原理と思想 — 本質理解
LLM の動作原理を理解し、業務で安全に活用するための判断軸を身につける
S1. 生成AIの正体 — 流暢なる無知
LLM（Large Language Model＝大規模言語モデル）は「それっぽいことを言う装置」である。流暢さと正確さは別物だ
実務での意味：流暢な出力は信頼の根拠にならない。特に数値・固有名詞・法的事実は必ず一次ソースで検証すること。
今日から何を変えるべきか：AI の出力を「叩き台」として扱い、SSOT（Single Source of Truth＝信頼できる唯一の情報源）照合・ボトムアップ検証・レビュー・承認のフローに組み込む。
まず直感で掴む — 家族の「次の一言」が読める感覚
長く一緒に暮らしている家族やパートナーが、次に何を言うか — なんとなくわかる、という体験はないだろうか。「この話題が出たら、きっとこう返すだろう」「この表情のときは、あの言葉が来る」。根拠を説明しろと言われると困るが、膨大なやりとりの蓄積から無意識に予測している。
LLM の正体は、まさにこれだ。インターネット上の膨大なテキストを「やりとりの蓄積」として学習し、「この文脈の次には、こういう言葉が来る可能性が高い」を超高速で計算している。家族の一言を予測するのと本質的に同じ操作を、数十億のパラメータで、あらゆる話題に対してやっているだけだ。
仕組みを知る — 確率的なトークン選択の繰り返し
技術的に言えば、LLM は入力テキストを数値ベクトルに変換し、学習済みの重みを通じて確率分布を計算し、そこからサンプリングする。検索でも計算でも記憶の呼び出しでもない。「次に来る可能性が最も高いトークンを選ぶ」操作を、出力が完了するまで繰り返しているだけだ。
LLM 生成フロー
タイピングアニメーション — 生成のしくみを体感する
なぜ危険か — ボトムアップの論理が存在しない
この仕組みの本質的な危うさは、出力の裏に明確なロジックの積み上げがないことにある。
たとえば「日本の SaaS 市場規模は？」と聞くと、それらしい数字がレポートの体裁で返ってくる。だが、その数字は一次ソースを辿り、定義を確認し、積み上げ計算で検算した結果ではない。膨大なテキストの中で「この文脈のあとにはこのくらいの数字が来やすい」というパターンから導いた、もっともらしい回答にすぎない。家族の次の一言を当てるのと同じ操作で、市場調査をしているふりをしている。
AIに「我が社の昨年の売上を教えて」と尋ね、 返ってきた数値をそのまま報告資料に記載した。 実際は学習データにその情報が含まれておらず、 もっともらしい数値が生成されていた。
AIには「このCSV（実績データ添付）を 分析して傾向を要約して」と依頼する。 AIが使う数値は自分で提供したもの。 要約の論理はレビューで確認する。
どう制御するか — ハーネスで論理を外付けする
ソースを辿るか、積み上げて検算するか、数字を鵜呑みにするか — それを決めるのは AI ではなく、ユーザーが設計するハーネス（制御の仕組み）だ。素の LLM に補強機構を外付けすることで、初めて実務に使える品質になる。
現実の AI 活用では、RAG（Retrieval-Augmented Generation＝検索拡張生成）で一次ソースの文書を文脈に注入したり、ツール呼び出しでリアルタイムのデータを取得したりする。それでも最終的な品質は人間のレビューと承認に依存する。
SSOT 照合
数値・定義・固有名詞は必ずシステム・オブ・レコードと突き合わせる。AI の出力値をそのまま使わない。
ボトムアップ検証
合計と内訳が一致するか確認する。上から見て「それっぽい」ではなく、下から積み上げて正しいかを問う。
レビューと承認
生成物は必ずドメイン知識を持つ人間が確認する。流暢さを信頼の根拠にしない。
叩き台として使う
AI の出力を「完成品」ではなく「叩き台」として扱う。修正する前提で受け取る。
一次ソースで検証する
数値・固有名詞・法的事実は必ず一次ソース（SSOT）と突き合わせる。
ドメイン知識でレビューする
出力の論理・前提・結論を専門知識で評価する。「流暢かどうか」ではなく「正しいかどうか」を問う。
承認フローに組み込む
AI 生成物は必ず人間の承認を経てから使用する。自動承認はしない。
判断基準 — 何を任せ、何を確認するか
| 問い | AI に任せてよい | 人間が必ず確認する |
|---|---|---|
| 数値の正確性 | 傾向・パターンの指摘 | 具体的な数値そのもの |
| 事実の正確性 | 一般的な知識の整理 | 固有名詞・日付・法律 |
| 論理の整合性 | 構造の提案・要約 | 前提の正しさ・結論の妥当性 |
| 最新情報 | 学習カットオフ以前の知識 | リアルタイム・組織内情報 |
Stochastic Parrot 問題 — "the underlying mechanism is still probabilistic pattern matching, not genuine reasoning or semantic grounding"
The Stochastic Parrot Problem and Why It Still Matters in AI System Design
S2. 文脈という有限資源
文脈は盛るものではなく設計するもの — 何を入れるかより何を残すか
実務での意味：「とにかく全部渡す」は逆効果になる。関連するものだけを精選し、必要な情報だけを提供することが品質を上げる。
今日から何を変えるべきか：プロンプトに情報を「盛る」発想をやめ、「何を残すか」を設計する発想に切り替える。
文脈は有限である
LLMが一度に処理できるテキストの量には上限（コンテキストウィンドウ）がある。Anthropicの表現を借りれば「LLMにはアテンションバジェットがある」。会話履歴・指示・参照ファイル・システムプロンプト、すべてがこの有限な空間を共有している。
コンテキストウィンドウの構成イメージ
長すぎるとノイズが増える
コンテキストが長くなるほど、AIは全体に均等に注目できなくなる傾向がある。重要な指示が文脈の途中に埋もれると、それが参照されにくくなる現象（context rot）が実務上問題になる。これは機構の詳細より「長い文脈では精度が落ちやすい」という現象として理解しておけば十分である。
添付します： - 過去3年分のすべての会議議事録 - 全部門の予算データ（未整理） - 関係するかもしれないメール200通 - 過去の類似案件資料 これを参考に提案書を書いてください。
目的：Q3の営業提案書（A4・2枚） 参照：今期の製品仕様書（添付） 制約：競合他社の名指し禁止 対象：製造業・中規模企業の調達担当 上記だけを根拠に構成案を出してください。
重要なのは「何を足すか」より「何を残すか」
Anthropicが「文脈エンジニアリング」と呼ぶ考え方の核心は、「LLM推論中に最適なトークンの集合をキュレーションし維持するための戦略」にある。「追加する」ではなく「最適化する」という発想の転換が必要だ。
補足: Transformerのアテンション機構とコンテキスト長の関係
Transformerモデルはアテンション機構により、入力全体の任意の位置に注目できる設計になっている。計算量はトークン数の二乗（n²）に比例するため、長い入力ほど計算負荷が増大する。
実装上、この計算量を抑えるための様々な近似手法が導入されているが、「長くなるほどすべての位置に均等に注目できなくなる」という傾向は残る。これがcontext rotとして知られる精度低下現象の背景にある。
断言できるのは「現象として精度が落ちやすい」こと。機構の内部動作の詳細は実装ごとに異なる。
補足: 文脈エンジニアリングとプロンプトエンジニアリングの違い
プロンプトエンジニアリングが「入力テキストの書き方」を最適化するのに対し、文脈エンジニアリングはより広い概念だ。何をシステムプロンプトに入れるか、どの資料を参照させるか、会話履歴をどの時点で切り捨てるか、といった設計全体を対象にする。
「良いプロンプトを書く」だけでなく、「AIが正しく動くために必要な情報の全体をどう設計するか」が問われている。
失敗例
ある担当者がドキュメント整理をAIに依頼した。「参考になるかもしれない」と判断した100ファイルを一括で貼り付けた結果、AIは重要な制約条件（ファイル末尾に記載）を参照できず、不適切な分類を大量に出力した。確認に要した時間は生成時間の10倍になった。
良い運用
目的を先に宣言する
最初に「何のための文脈か」を明示する。AIも人間も、目的が明確なほど不要な情報を除外しやすい。
資料は抜粋で渡す
全文でなく、関連する箇所のみを切り出して渡す。「ここに答えがある」という部分だけを提供する。
会話は適度に切る
長い会話セッションは途中でリセットする。蓄積された古い文脈が精度を下げる前に、新しいセッションで始める。
判断基準
| 状況 | 対処法 |
|---|---|
| 「念のため全部渡したい」と思ったとき | 一歩止まって、本当に必要な情報だけに絞る |
| AIの回答が途中からズレ始めたとき | セッションをリセットして指示を再設計する |
| 重要な制約を必ず守らせたいとき | 文脈の冒頭・末尾どちらかに明記する |
| 長い資料を参照させたいとき | 該当箇所を抜粋し、「この部分を参照してください」と明示する |
Anthropic文脈エンジニアリング — "the set of strategies for curating and maintaining the optimal set of tokens during LLM inference" / "LLMs have an attention budget"
Effective Context Engineering for AI Agents — Anthropic Engineering
S3. AIへの指示は「依頼」ではなく「設計」
指示の質が出力の質を決める — 6要素で設計する
実務での意味：「わかってくれるはず」が通じない。目的・条件・制約・入力・出力形式・評価観点の6要素を明示することで再現性が上がる。
今日から何を変えるべきか：指示を書いたら「この6要素のうち何が欠けているか」をチェックリストで確認してから送る。
指示の6要素
目的 — なぜやるのか
何のためのタスクかを最初に述べる。「営業提案書を書く」ではなく「製造業の調達担当を説得するための提案書を書く」と目的まで伝える。
条件 — どんな状況か
読者・業界・前提知識・役割などの文脈情報。「あなたはFP&Aアナリストです」という役割設定も条件の一部。
制約 — やってはいけないこと
「競合名を出さない」「専門用語は使わない」「3点以内に絞る」など。制約がないとAIは何でも足す方向に動く。
入力 — 参照する素材
AIに使わせたいデータ・文書・定義を具体的に提供する。「なんとなく知っているはず」は通用しない。
出力形式 — どんな形で返すか
箇条書き/散文、文字数、単位、言語、構成要素を指定する。Anthropicが「例は千の言葉に値する」と言うように、具体例を1つ示すと格段に精度が上がる。
評価観点 — 何をもって「良い」とするか
「簡潔さ・論理的整合性・実行可能性の順で優先」など、評価基準を示す。AIは明示されない基準は勝手に補完する。
Good/Bad比較 — なぜBadが失敗するのか
Badな指示では、AIが「空白」を確率的に補完する。学習データの中の「似た文脈でよく来るパターン」で埋めるため、意図と外れた出力が生成される。
売上データを分析して
Q3の月次売上（添付CSV）を分析し、 経営会議向けに3点の改善提案を 箇条書きで出してください。 金額は百万円単位、小数点1桁。
競合との違いをまとめて
競合製品Xとの機能比較表を作成してください。 制約：競合名は「他社製品A」と匿名化。 自社優位点は3点以内。根拠のない主張は禁止。
このメールに返信して
以下のメール（引用）に返信文を書いてください。 形式：ビジネス敬語、200字以内、 件名含む。謝罪は入れない。 --- （メール本文）
この企画書を改善して
添付の企画書を改善してください。 優先順位：1）論理構成の明確さ 2）実行可能性の具体性 3）読みやすさ 現在の文章は保持し、追記で改善点を示す形式で。
うちの商品の特徴を説明して
以下の製品仕様（添付）をもとに、 初めての顧客向けの特徴説明を書いてください。 専門用語は使わず、利用シーン3例を含む。 （製品仕様書の抜粋）
失敗例
ある担当者が「契約書のリスクを洗い出して」とだけ指示した。AIは「よくある契約書レビューのパターン」で確率的補完を行い、その会社特有の業法規制リスクを見落とした汎用的なチェックリストを返した。依頼者はそれをそのまま使い、後から弁護士に指摘を受けた。
判断基準
指示を送る前に次の問いを確認する。「AIがこの指示の空白部分を何で埋めるか」を想像できるなら、その空白は明示すべき箇所だ。
| 要素 | 欠けていると何が起こるか | 対処 |
|---|---|---|
| 目的 | 汎用的・当たり障りない出力になる | 「なぜやるか」を1文で先頭に書く |
| 条件 | 想定と異なる読者・立場で書かれる | 役割・業界・専門レベルを明示 |
| 制約 | 不要な情報が大量に足される | 「〜しない」を明記する |
| 入力 | 学習データの一般論で補完される | 参照させる資料を直接貼る |
| 出力形式 | 形式が毎回変わり再利用できない | 例を1つ示すか構造を明記する |
| 評価観点 | AIの評価基準で最適化される | 何を優先するかを順序立てて伝える |
Anthropic — "For an LLM, examples are the 'pictures' worth a thousand words"
Effective Context Engineering for AI Agents — Anthropic Engineering
S4. 実務での適用判断 — 加速装置の使いどころ
AIは万能ではない。向き・不向きを見極めて使う
実務での意味：タスクの特性（確定性・影響範囲・検証しやすさ）を3軸で評価し、AIを使うかどうかを判断する。
今日から何を変えるべきか：「AIで何でもできる」という発想を捨て、「このタスクの3軸はどうか」を毎回考える習慣をつける。
AIは加速装置である
AIはドラフト作成・構造化・パターン認識・要約といった反復的作業を劇的に速くする。しかし速さは正確さを保証しない。「速く間違える」リスクを理解した上で使う必要がある。特に、確定した正解が必要な場面・間違いの影響が大きい場面・一次ソースで検証しにくい場面では、人間の判断をAIに置き換えてはならない。
ユースケース分類
叩き台・ドラフト作成
企画書・メール・報告書の初稿。人間が内容を確認・修正することが前提であれば速度向上効果が高い。
要約・構造化
長い会議議事録の要点整理、散逸した情報の構造化。AIが出した構造を人間がレビューする前提で使う。
コードの叩き台
ルーティン処理・テンプレート的なコードの初稿生成。動作確認・テストは人間が行う。
データ分析の補助
パターン指摘・仮説生成には使える。数値の正確性は必ずSSOTと突き合わせる。AIが示した数値を直接使わない。
法律・会計の判断
ドラフトや論点整理には使えるが、最終判断は必ず専門家が行う。AIの出力を根拠に意思決定しない。
最新情報の取得
学習カットオフ以降の情報はない。最新の市場動向・法改正・競合情報はAIに依存せず一次ソースを確認する。
3軸判断表
以下の3軸でタスクを評価する。「高・高・低」の組み合わせは人間が主体で対応すべき領域だ。
| 判断軸 | AIが向いている（低） | 人間が必要（高） |
|---|---|---|
| 確定性が必要か 正解が一つに決まるか | 幅のある回答でよい（方針案、構成案） | 正確な数値・法的判断・固有の事実 |
| 間違いの影響が大きいか 誤りのコストはどうか | 影響小（内部メモ、叩き台） | 影響大（顧客提出物・法的文書・財務数値） |
| 一次ソースで検証しやすいか 出力を後から確認できるか | 検証しやすい（数値はCSVで確認可能等） | 検証しにくい（専門知識が必要・SSOTが存在しない） |
失敗例
ある担当者がAIに「競合調査をして」と依頼し、返ってきた競合情報をそのまま営業資料に使った。AIが生成した「競合の製品価格」はカットオフ以前の情報であり、現在の実際の価格と乖離していた。顧客提案の場で指摘を受け、信頼を損ねた。
良い運用
スピードと精度を分離する
「速く叩き台を作る」フェーズと「正確性を確認する」フェーズを意識的に分ける。両方を同時にAIに任せない。
失敗コストを先に見積もる
このタスクでAIが間違えたら何が起こるかを先に考える。コストが高い場面では検証コストも予算に入れる。
「加速」と「代替」を区別する
「AIが書いたから確認しなくてよい」ではなく「AIが書いたから速く確認できる」という使い方が正しい。
判断基準
タスクを前にして次の問いを立てる。「このタスクでAIが間違えた場合、どのフローで検出できるか」が答えられないなら、AIを主体で使うべきではない。
S1「生成AIの正体」で解説したハルシネーションの構造的原因、S5「なぜレビューと検証は省略できないか」の検証フロー設計と合わせて読むこと。
判断軸の詳細設計については Anthropic Engineering — Effective Context Engineering も参照。
S5. なぜレビューと検証は省略できないか
流暢な出力ほど危険である — 検証は生成コストより本質だ
実務での意味：検証コストを生成後に削減しようとすると失敗する。検証の手順と責任を先に設計することが品質の源泉である。
今日から何を変えるべきか：AI活用のフローに「誰が何を検証するか」を明示的に設計し、省略不可の工程として組み込む。
流暢な出力ほど危険である理由
人間は流暢で自信に満ちた文章を読むと、批判的思考が緩む傾向がある。AIの出力は構造的に流暢になるよう最適化されているため、誤った内容であっても自信を持って語られる。これは「ハルシネーション」が「明らかな間違い」として出てくるのではなく、「もっともらしい誤り」として出てくる理由でもある。
生成コストより検証コストの方が本質
AIを使えば生成コストは劇的に下がる。しかし検証コストは下がらない。むしろ「大量に・速く・流暢に」生成できるようになったことで、検証しきれずに誤りが通過するリスクが上がる。AI活用のROIは「生成が速くなった」ではなく「検証が追いついているか」で測るべきだ。
生成: 10分 → AIで2分（80%削減） 検証: 省略（「AIだから大丈夫」） 結果: エラーが本番環境に流入 コスト: 修正に元の10倍の時間
生成: 10分 → AIで2分（80%削減） 検証: 3分（定型チェックリスト） 合計: 5分（従来比50%削減） 品質: 保持または向上
数値・ロジック・コードで何をどう確認するか
ボトムアップで積み上げる
合計と内訳が一致するか。単位は正しいか。オーダーが合っているか（百万と億の混同など）。SSOTの対応する値と突き合わせる。
前提と結論を分離する
AIが使っている前提が正しいか。結論は前提から論理的に導けるか。「もっともらしい言い方」で繋いでいないか。
テストを先に書く
AIが生成したコードは「動くように見える」ことが多い。エッジケース・境界値・異常系を意識したテストを人間が書き、通過を確認する。
責任3層モデル
AI活用における責任は次の3層に分かれる。最終的な品質責任は必ず人間が負う。
層1 — AIの出力（生成）
確率的補完の結果。流暢さは保証されるが正確さは保証されない。ここで品質を担保しようとしてはいけない。
層2 — 担当者のレビュー（検証）
ドメイン知識を持つ担当者が数値・ロジック・事実を確認する。SSOT照合・ボトムアップ検証・チェックリストを使う。
層3 — 責任者の承認（品質保証）
業務上の影響を理解した責任者が最終承認する。AIが生成したからという理由で承認フローを短縮しない。
失敗例
ある担当者がAIに財務サマリーを作成させ、「AIが出したから正しいはず」という認識でそのまま経営会議に提出した。数値の単位（百万円と億円）が混在していたが、流暢な文体のため読み飛ばされた。会議の途中で指摘を受け、再集計に一週間かかった。
良い運用
検証手順を先に設計する
AIを使う前に「何を、誰が、どう確認するか」を決める。後から「なんとなく確認する」では漏れが出る。
チェックリストを定型化する
数値確認・ロジック確認・事実確認のチェックリストを作り、毎回同じ手順で確認する。判断を属人化しない。
「流暢さ」を信頼の根拠にしない
読みやすい・論理的に見える・自信がある、はいずれも確認を省略する理由にならない。むしろ流暢なほど注意深く読む。
リスクに応じて承認レベルを変える
影響が小さいものは担当者確認で十分。影響が大きいものは責任者承認を必須とする。一律の判断をしない。
判断基準
| 確認対象 | 確認方法 | 省略できない条件 |
|---|---|---|
| 数値 | SSOTと突き合わせ、ボトムアップ積み上げ確認 | 外部提出・意思決定に使う場合は常に必須 |
| ロジック | 前提の明示・前提→結論の論理確認 | 相手を説得する目的で使う場合は必須 |
| コード | テスト実行・エッジケース確認 | 本番環境に適用する場合は必須 |
| 事実 | 一次ソース（公式文書・データベース）確認 | 固有名詞・日付・法令は常に必須 |
| 引用・出典 | 原文の直接確認 | 引用として使う場合は常に必須 |
補足: なぜ「ハルシネーションを防ぐ」より「検証フローを設計する」の方が有効か
ハルシネーションは確率的生成の構造的な帰結であり、プロンプトの工夫で完全に防ぐことはできない。発生頻度を下げることはできるが、ゼロにはならない。
そのため「ハルシネーションを防ぐ」という問いの立て方より、「ハルシネーションが発生しても検出できるフローを設計する」という問いの方が実務的に有効だ。誤りが通過しないシステムを作ることが目標であり、誤りが発生しないシステムを作ることは現時点では不可能だ。
Stochastic Parrot問題 — "Validate outputs rather than trusting fluency. Add controls when stakes are high."
The Stochastic Parrot Problem and Why It Still Matters in AI System Design
Claude Code 運用設計 — 制御の設計思想
ハーネスとは、AIを自律的な問題解決者としてではなく、アーキテクチャの制約が成果を形作る構成要素として扱う設計思想。
S6. Claude Code とは何か — チャットAIとの根本的な違い
AIがターミナルを直接操作する。これが意味することを理解する
実務での意味：コピペが不要になる代わりに、AIの行動を制御する「ハーネス」の設計が不可欠になる。
今日から何を変えるべきか：AIを「相談相手」ではなく「操縦すべき実行者」として捉え直し、この第二編で制御の仕組みを学ぶ。
Claude の全体像 — アプリとコードの2形態
「Claude」は Anthropic 社が開発した LLM（第一編参照）。ユーザーとの接点は大きく2つの形態がある。
| 形態 | 提供形態 | できること | できないこと |
|---|---|---|---|
| Claude App claude.ai / モバイル |
Webブラウザ チャットUI |
対話・要約・翻訳・壁打ち ファイルアップロード（PDF等） サンドボックス内コード実行 Artifacts（ファイル生成・DL） |
あなたのPCのファイル操作 Git操作 任意のコマンド実行 セッション間の状態保持 |
| Claude Code ターミナル CLI |
ターミナル AIが直接操作 |
あなたのPCのファイル読み書き Git操作・PR作成・デプロイ 任意のシェルコマンド実行 サブエージェント並列処理 MCP連携（外部API・DB） |
GUIでの対話的操作 ブラウザ内完結の作業 |
Claude App も単なるチャットではない — サンドボックス内でコードを実行し、ファイルを生成してダウンロードさせることもできる。しかし、操作対象はすべて隔離された仮想環境内に限られる。あなたのプロジェクトフォルダには一切触れない。
Claude Code は違う。あなたのターミナルに直接アクセスし、実際のファイルシステム上で操作する。この違いが、以下のパラダイムシフトを生む。
パラダイムシフト — コピペから直接操作へ
従来のAI活用（ChatGPT / Gemini 等）
質問を入力
回答を生成
回答をコピー待ち
ファイルに貼付待ち
テスト実行待ち
エラー修正待ち
再度AIに質問待ち
Claude Code — 一気通貫
指示を出す
ファイル生成
テスト実行
エラー修正
再テスト
コミット
デプロイ
AIがターミナルにアクセスできるということは、パソコンでできることのほぼすべてをAIが実行できるということだ。ファイルの読み書き、コードの実行、Git操作、外部APIの呼び出し、データベースへのクエリ — すべてAIが直接行う。
従来のフローで人間が担っていたコピペ → 貼付 → テスト → 修正 → 再質問のループが丸ごと消える。人間は「何をしたいか」を伝えるだけ。実行のすべてをAIが引き受ける。
→ だからこそ「ハーネス」が必要だ。自由度が上がった分、制御しなければ暴走する。
他のAIツールとの位置づけ
| ツール | 形態 | ターミナル直接操作 | 特徴 |
|---|---|---|---|
| ChatGPT / Gemini | チャットUI | ✕ | 汎用対話。結果は人間がコピペ |
| Cursor / Windsurf | IDE統合 | △（IDE内のみ） | エディタ内でのコード補完・編集 |
| Claude Code | ターミナルCLI | ◎ | OS全体を操作。ファイル・Git・API・DB |
| GitHub Copilot CLI | ターミナルCLI | ○ | コマンド提案中心 |
Claude Code の特異性は、ターミナルへのフルアクセス＋長時間タスクの自律実行＋サブエージェント並列処理にある。IDE に閉じないことで、DevOps・データパイプライン・デプロイまで一貫して扱える。
急速な深化 — 2025年12月からの進化
Oct
Claude Code 初期リリース
ターミナルからのAIコーディングが現実に。ファイル操作・Git・テスト実行を自律的に行うエージェントの誕生。
Dec
Anthropic「Effective harnesses for long-running agents」公開
ハーネス設計思想の体系化。「AIを制御する構造」が、プロンプトエンジニアリングの次のフロンティアとして定義された。
Jan
「Effective context engineering for AI agents」公開
コンテキストウィンドウの最適化が中心課題に。限られたトークン枠にどの情報を入れるかが成果を左右するという認識が広まる。
Feb-
Hooks / Skills / Sub-agents の成熟
5レイヤー構成（CLAUDE.md → Skills → Hooks → Sub-agents → Memory）が実用水準に到達。個人の「制御体系」が組織的ノウハウへ昇華。
2025年末から2026年初にかけて、AIコーディングツールの世界は急速に変化している。重要なのは個別のツール名ではなく、「AIがターミナルを通じてパソコンを直接操作する」というパラダイムが定着したことだ。このガイドで学ぶ設計原則 — ハーネス、コンテキスト管理、検証フロー — は、ツールが変わっても適用できる普遍的な考え方だ。
この力を安全に活用するために — まず CLAUDE.md の設計から始めよう。
S7. CLAUDE.md — プロジェクトの憲法
何を書くか・何を書かないかを設計する
実務での意味: 書きすぎたCLAUDE.mdはノイズになり、AIが本当に守るべき制約を見失う。
今日から: 既存のCLAUDE.mdを「常設 / 必要時 / 実行時」の三列で仕分けし、不要な行を他へ移す。
結論
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.md | 常設原則 — 常に有効 | コマンド、言語設定、外部API制約 |
| skills/ | 必要時手順 — 参照型 | chart-patterns.md、deploy-rules.md |
| hooks/ | 実行時検査 — 自動起動 | security.py、tool_logger.py |
スコープは三階層で管理する。グローバル設定（~/.claude/）はモデル選択・認証のみ。プロジェクト設定（project/.claude/）はhooks・permissions・skills。サブプロジェクト（projects/X/）はそのプロジェクト固有の制約を上書きする。完全分離ではなく、共通文脈と局所文脈の階層化が目的だ。
- ~/.claude/ # グローバル: model, credentials
- settings.json
- .credentials.json
- project/.claude/ # プロジェクト: CLAUDE.md, hooks, skills
- CLAUDE.md # 常設原則
- hooks/
- security.py
- tool_logger.py
- skills/
- chart-patterns.md
- deploy-rules.md
- projects/X/ # サブプロジェクト: 局所上書き
- CLAUDE.md
判断基準
「これはセッションをまたいで常に守るべきか？」と問え。YESならCLAUDE.md。「必要なときだけ参照するか？」ならskills。「コード実行のたびに自動で走らせるか？」ならhooks。この問いを省略すると、肥大化したCLAUDE.mdが生まれ、AIは大量のノイズの中から本当の制約を見つけられなくなる。ハーネスなしにはAIは暴走する。
S8. 文脈衛生 — /clear, /compact, /context
文脈の蓄積をコントロールする3つのコマンド
実務での意味: 古い文脈が蓄積すると「文脈腐敗」が起き、AIの出力品質が低下する。
今日から: タスク完了後は反射的に /clear を打ち、新しいタスクを汚染なしで始める習慣をつける。
結論
Anthropicはコンテキストウィンドウが拡張するにつれてAIの性能が劣化する現象を「文脈腐敗（context rot）」と呼ぶ。長いセッションには過去の失敗、撤回された指示、関係のない情報が蓄積し、AIは新しい指示よりも古いノイズに引きずられる。これを防ぐのが文脈衛生だ。
セッションフローとコマンドの使いどころ
失敗例
A機能の実装が終わったあと、/clearを打たずにB機能の指示を出した。AIはAの実装で採用したアーキテクチャをBにも適用しようとし、要件が異なるにもかかわらず同じパターンで実装した。古い文脈が新しい判断を汚染した典型例だ。
良い運用 — 判断テーブル
| 状況 | 使うコマンド | 理由 |
|---|---|---|
| 別件・別タスクに移る | /clear | 文脈を完全リセット。汚染を断つ |
| 同じ作業を続けるが冗長になった | /compact | 重要部分を保ちつつトークン削減 |
| 今どの文脈にいるか確認したい | /context | AIが何を「覚えているか」を把握 |
| 長時間のセッション中に迷走を感じる | /compact → /context | 圧縮後に現状を確認して再整理 |
LangChainのコンテキストエンジニアリングでは、文脈操作をWrite（追加）・Select（選択）・Compress（圧縮）・Isolate（分離）の4操作として整理している。/compactはCompressに、/clearはIsolateに対応する操作として理解できる。これは「理解のレンズ」として有効だが、Claude Codeの3コマンドと直接1対1で対応するわけではない点に注意する。
判断基準
「前のタスクの情報は今のタスクに役立つか？」と問え。役立たないなら /clear。役立つが量が多いなら /compact。セッションを続けながらAIの現在地を知りたいなら /context。この判断を怠ることがAIの迷走の主因になる。文脈は設計するものだ。
S9. Plan Mode — 思考の整流器
いきなり書かせないための、実行前の構造化ステップ
実務での意味: 計画なしで書き始めると、後半で矛盾が露呈して全面書き直しになる。
今日から: 複数ファイルにまたがる変更や新機能追加には、最初の指示に「まず計画だけ出力して」を付ける。
結論
Plan Modeとはコードを書く前にAIに計画を出力させる運用パターンだ。Anthropicはエージェントの長期実行において「一度に一機能ずつ作業する」ことを推奨している。Plan Modeはこの原則を実践するための整流器として機能する。計画段階で矛盾・見落とし・依存関係の問題を発見することで、実装後の大規模な手戻りを防ぐ。
当チームの運用規律として、3ステップ以上にわたる実装は必ずPlan Modeを経由する。この「3ステップ以上」はチームが決めた閾値であり、一般的な正解ではない。ただし実際には、1ファイルの小修正を除くほぼすべての実装がこの基準に該当する。
失敗例
「ダッシュボードにYTD累積チャートを追加して」 → AIが即座にコードを書き始める → データ構造の前提が違った → 既存チャートのレイアウトを壊した → 全面書き直し
「ダッシュボードにYTD累積チャートを追加する。 まず実装計画だけ出力して。コードはまだ書かない」 → AIが計画を出力 → データ構造・影響範囲を確認 → 合意後に実装開始 → 一発で通る
良い運用 — Plan → Implement → Verify
ワークフロー: Plan Mode の3フェーズ
Planフェーズでは計画と受入基準の両方を合意する。「何を作るか」だけでなく「何をもって完了とするか」を先に決めることで、Verifyフェーズの判断が機械的になる。Anthropicの推奨する増分実行（incremental execution）とも整合する。
判断基準
「この実装は1ファイルの単純な修正か？」という問いから始める。NOであればPlan Modeを使う。当チームでは3ステップ以上を基準としているが、本質は「実装後の手戻りコストが計画のコストを上回る可能性があるか」だ。複数ファイル・データ構造変更・UI変更が重なるときは必ずPlanを先に出力させる。
S10. Hooks — 実行タイミングで機械的に差し込む
自然言語のお願いは抜ける。だから機械的に差し込む。
実務での意味: AIへの自然言語の制約は常に有効ではない。コード実行で強制する仕組みが必要だ。
今日から: 絶対に避けたいコマンドパターンを1つ特定し、PreToolUseのDangerousリストに追加する。
結論
hooksはClaude Codeがツールを呼び出す前後に自動実行されるスクリプトだ。自然言語で「危険なコマンドは実行しないで」と書いても、長いセッションの中でその制約が無視されることがある。hooksはその問題を解決する。実行タイミングで機械的に検査・記録することで、AIの挙動を構造的に制御する。ハーネスなしにはAIは暴走する — これがhooksの存在理由だ。
失敗例
CLAUDE.mdに「rm -rfは使わないこと」と書いていたが、AIが生成したクリーンアップスクリプトにそのコマンドが含まれていた。自然言語の制約はAIのトークン予測から「忘れられる」。PreToolUseがあればその瞬間にブロックされていた。
良い運用 — Hook ライフサイクル
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": "危険コマンド検知"}))
security.py — 全コード
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")
settings.json — Hook 登録設定
{
"hooks": {
"PreToolUse": [
{"command": "python .claude/hooks/security.py"}
],
"PostToolUse": [
{"command": "python .claude/hooks/tool_logger.py"}
]
}
}
判断基準
「これをCLAUDE.mdに書いても守られなかったことがあるか？」と問え。YESならhooksに移す。安全制約・強制ログ・外部APIへの二重呼び出し防止など、人間の監視なしに毎回確実に実行されなければならないものはすべてhooksの候補だ。hookは軽量なPythonスクリプトで足り、複雑なロジックは不要だ。
S11. Skills・Agents・パイプライン — 全体設計
5つの制御レバーを統合して安定した自律実行を設計する
実務での意味: どれか一つが欠けると、残りの仕組みがその穴を補おうとして肥大化し、全体が崩れる。
今日から: 現在のプロジェクト構成を5レイヤーに照らし合わせ、「どのレイヤーが空白か」を確認する。
結論 — 5レイヤーの分業
| レイヤー | 担当 | 例 | 節 |
|---|---|---|---|
| CLAUDE.md | 常設原則 | コマンド、制約、言語設定 | S6 |
| skills | 必要時手順 | chart-patterns、deploy-rules | — |
| Plan Mode | 事前整理 | 実装計画、受入基準 | S8 |
| hooks | 実行時検査 | security.py、tool_logger.py | S9 |
| agents | 役割分担 | impl-agent、reviewer、tester | — |
skillsはmarkdownファイルであり、AIが「必要なときに」参照する手順書だ。チャートの実装パターン、デプロイ規則、KPI定義など、常時メモリに置く必要はないが確実に正確であるべき知識を置く。agentsはサブエージェントとして特定の役割を持つ。Anthropicが推奨するtwo-agent pattern（例: impl-agentとreviewer）はお互いの盲点を補完する。
Skills とは何か — なぜ必要で、なぜ効くのか
Claude Code の Skills は、CLAUDE.md には書ききれない専門知識を、必要な瞬間にだけコンテキストウィンドウに注入する仕組みだ。
なぜ CLAUDE.md だけでは足りないのか
| アプローチ | 問題 | 結果 |
|---|---|---|
| 全部 CLAUDE.md に書く | 6000+ トークンで原則が埋もれる | 言語設定すら無視される |
| 外部ドキュメントを毎回手動で貼る | ユーザー負担大・貼り忘れ | 一貫性が保てない |
| Skills（自動起動） | 必要時のみロード。CLAUDE.md はコンパクト | 原則が常に見える + 専門知識も使える |
コンテキスト埋め込みの仕組み
Skills の起動には3つのモードがある。AIの判断で自動的にコンテキストへ注入される。
自動起動（description トリガー）
各スキルの description に "Use when..." を書く。AIはユーザーの発言・作業内容からマッチするスキルを自動で読み込む。例: チャート実装中 → chart-patterns が自動ロード。
明示起動（スラッシュコマンド）
/plan /verify /debug のように、ユーザーがコマンドとして明示的に呼び出す。手順が厳密に定義された作業向き。
サブエージェント委譲
スキル内で agent: impl-agent を指定すると、専用のサブエージェントにタスクを委譲。メインのコンテキストを汚さず、並列実行も可能。
Skills のメリット（実測値）
CLAUDE.md をコンパクトに維持
24スキル分の知識を外出し → CLAUDE.md は約40行。原則が常にAIの視界に入る。
ドメイン知識の正確性
Chart.js のバグパターン、DAXの罠、KPI計算式など、「曖昧に覚えている」ではなく「正確な手順書」として参照される。
新人AI問題の解消
セッションが切れるたびにAIは記憶を失う。Skills があれば、新セッションでも同じ品質で作業できる。「引き継ぎ書」が常に最新。
チーム間の一貫性
複数のサブエージェントが同じスキルを参照するため、impl-agent も reviewer も同じルールで動く。人間のコードレビュー負荷が減る。
スキルファイルの構造
各スキルは .claude/skills/ に1ファイル = 1スキルで配置。frontmatter で起動条件を宣言する。
失敗例
skillsを作らずにすべての手順をCLAUDE.mdに書いたプロジェクトでは、CLAUDE.mdが6000トークンを超えた。AIはその冒頭にある「言語設定」すら参照できなくなり、英語で出力し始めた。必要時手順を常設ファイルに置いたことが、本来守るべき原則を見えなくした。
良い運用 — FP&Aダッシュボード生成パイプライン
FP&Aダッシュボード生成のデータフロー。各ステップは独立したPythonモジュールが担当する。
データ取得 — fetcher群
Fabric / BQ → Python fetcher → parquet/jsonl キャッシュ
データ整形 — preparers
KPI計算・セグメント集計・YTD累積処理
HTML生成 — html_generator
Chart.js テンプレートへのデータ注入・セクション結合
デプロイ — Cloudflare Pages
wrangler pages deploy → funnel-dashboard.pages.dev/
Anthropicが推奨するtwo-agent patternを拡張した5エージェント構成。
| エージェント | 役割 | 主な責務 |
|---|---|---|
| impl-agent | 実装担当 | 機能コード・ユニットテスト |
| reviewer | コードレビュー | 設計・セキュリティ・可読性 |
| tester | テスト設計 | 統合テスト・E2E・カバレッジ |
| debugger | デバッグ | エラー原因特定・修正提案 |
| verifier | 検証 | 数値整合・KPI検証・不変条件 |
各エージェントは .claude/agents/ 配下のmarkdownで定義される。役割の境界を明確にすることで、impl-agentがテスト設計の責務まで負わないよう制約する。これもハーネスの一形態だ。
デプロイはskills/deploy-rules.mdに手順を置き、AIが参照して実行する。
判断基準
5レイヤーのうちどれが欠けているかを確認する。CLAUDE.mdだけあってhooksがないなら、制約は自然言語のお願いに依存している。skillsがなくてCLAUDE.mdが肥大化しているなら、必要時手順を移す。agentsがなくて1つのプロンプトに実装・レビュー・テストを混在させているなら、役割分担を設計する。ハーネスなしにはAIは暴走する — この原則は5レイヤーすべてを貫く核心だ。
実践ショーケース — FP&A Master 環境の全体像
第一編・第二編の原則を適用した実際のClaude Code環境。24スキル・5エージェント・4フック・7プロジェクトが連動する
S12. 実環境の全体像 — ハーネスの実装例
SaaS FP&Aモノレポで稼働中の構成をそのまま公開する
環境サマリー
ディレクトリ構成 — 5レイヤーの物理配置
24 Skills — 各タグをクリックして中身を見る
全スキルは自動起動。description の "Use when..." でAIが文脈に応じて自動参照する。CLAUDE.mdに書くには多すぎる知識を、必要な瞬間にだけロードする仕組み。
👉 下のタグをクリックすると、そのスキルの詳細パネルが展開されます。まずは「plan」をクリックしてみてください。
/plan — 計画フェーズ
新機能開始、アーキテクチャ設計、3+ステップのタスク分解、または "plan" "設計" "計画" と発言した時
| 項目 | 内容 |
|---|---|
| 問題文 | 何を解決するか（1文） |
| 対象 | ファイル/モジュール/機能 |
| 制約 | 技術制約、時間制約、互換性要件 |
| 完了条件 | DoD（受入基準） |
1. 調査: 対象コードの現状把握
2. 3点リスクチェック: 符号(Sign) / NULL・空値 / 境界条件
3. 分割: タスクを独立した単位に分解
4. 委譲判断: 2ファイル以上 or 独立タスク複数 → Task委譲
5. 順序: 依存関係を考慮した実装順序
6. 検証: 各ステップの検証方法
| Stream | 担当 | 用途 |
|---|---|---|
| impl | impl-agent | 実装 |
| verify | verifier | 検証 |
| review | reviewer | レビュー |
/verify — diff-awareレビュー＋自動修正＋コミット
コード変更完了後、または "verify" "検証" "commit" "push" と発言した時
| 優先度 | 観点 | 例 |
|---|---|---|
| Critical | バグ・ロジックエラー | off-by-one、None参照 |
| Critical | セキュリティ | インジェクション、ハードコード秘密鍵 |
| Critical | データ整合性 | 金額単位ミス、符号反転 |
| High | エラー処理 | bare except、握りつぶし |
| Medium | 命名・DRY | コピペロジック |
| Low | 可読性 | ネスト深度4+ |
1. git diff HEAD で差分取得 → 0行なら即終了
2. 変更ファイル全Read + 包括レビュー
3. Plan Modeで修正計画策定
4. Critical/High を自動修正
5. 再verify（修正の検証）
6. 結果を .claude/out/ に書き出し
7. PASS → 自動コミット＆プッシュ
8. デプロイ（確認不要で即実行）
/debug — 根本原因特定＋最小修正
エラー発生、テスト失敗、スタックトレース貼り付け時
| 手法 | 適用場面 |
|---|---|
| 再現優先 | すべてのバグ |
| 二分探索 | 回帰バグ（git bisect） |
| 最小再現 | 複雑なバグ |
| 5 Whys | 根本原因不明 |
再現確認 → 情報収集 → 仮説立案 → 検証 → 原因特定 → 最小修正 → pytest検証 → /verify
/review — 改善台帳レビュー
改善台帳（.claude/improvements.jsonl）のopen/applied/skippedを集計し、週次棚卸しを実行。未適用の改善が滞留していないか、同種の改善が繰り返されていないかを確認する。
/learn — パターン検出→スキル自動生成
ツール使用ログ（tool-usage.jsonl）からパターンを検出し、繰り返し作業をスキル化する。
| 種別 | 閾値 |
|---|---|
| シーケンス（同一ツール列） | 3回/7日, 長さ3+ |
| ファイルグループ（共起） | 共起率70%+, 3セッション+ |
| 繰り返しBash | 5回/7日 |
| 失敗→リトライ | 3回/7日 |
/kpi-check — KPI整合性検証
"KPI検証" "ARR check" "NRR check" と発言した時、またはKPI計算の妥当性確認時
| 項目 | 内容 | 判定 |
|---|---|---|
| Formula Match | 計算式が定義と一致 | FAIL if mismatch |
| Benchmark Range | 値がベンチマーク内 | WARN if outside |
| Reconciliation | 照合先との差異 | FAIL if > tolerance |
| Component Sum | 内訳合計 = 親KPI | FAIL if mismatch |
/kpi-check ARR（単体）/ /kpi-check --all（全KPI）/ /kpi-check --tree NRR（分解ツリー）/ /kpi-check --drift（定義ドリフト検出）
/schema-check — スキーマ整合性検証
.claude/docs/schema/ 配下のドキュメント間の整合性を検証。specification.md（マスター）を基準に、bus-matrix / ER図 / カラム定義 / セマンティックモデル / DAXメジャーの相互参照をチェック。
| 項目 | 判定 |
|---|---|
| テーブル名一致（specification ↔ bus-matrix ↔ ER図） | FAIL if mismatch |
| カラム名一致（specification ↔ column-definitions） | FAIL if mismatch |
| DAXメジャー参照（→ specificationのカラム参照） | WARN if undefined |
data-quality-checks — データ品質検証
| # | カテゴリ | 内容 |
|---|---|---|
| 1 | スキーマ検証 | 型・Nullable・ユニーク制約 |
| 2 | 値検証 | 範囲チェック・パターンチェック |
| 3 | 異常値検出 | 3σ外れ値・IQR法・急激な変化 |
| 4 | 欠損値分析 | 欠損率・時系列推移・条件付き欠損 |
| 5 | Schema Drift | 設定ファイル変更時の既存キー完全性 |
| 6 | Column Mapping | データソースとUI間のカラム名一貫性 |
fabric-semantic-api — Fabricセマンティックモデル操作
TMDL読み書き、DAXメジャー追加/更新、データセット同期をPython APIで実行。
| 操作 | 内容 |
|---|---|
| メジャー追加 | TMDL形式でDAXメジャーを定義しclient.update_tmdl() |
| メジャー更新 | 既存TMDLを取得→式を置換→更新 |
| 一括更新 | 複数メジャーのTMDLを結合して一括適用 |
| DAX検証 | 括弧バランス・関数名・カラム参照の構文チェック |
chart-patterns — 27件fixから抽出したパターン集
| # | パターン | NG | OK |
|---|---|---|---|
| 1 | Hidden tab内チャート | new Chart() のみ | タブ表示時に chart.resize() |
| 2 | CSSテーブル競合 | グローバル td | scope class で隔離 |
| 3 | 数値フォーマット | :,.1f → JSでNaN | :.1f（カンマなし） |
| 4 | ChartBuilder順序 | set_stacked() → set_scales() | scales内にstacked統合 |
| 5 | Waterfall形式 | stacked: true | floating bars [[start, end]] |
| 6 | PPTXキャプチャ | responsive有効 | responsive: false 設定後 |
deploy-rules — Cloudflare Pagesデプロイ標準
| # | ルール | 理由 |
|---|---|---|
| 1 | --branch=main 必須 | 未指定だとpreview URLのみ |
| 2 | 一時ディレクトリにコピーしてからデプロイ | index.html混入防止 |
| 3 | 許可不要で即デプロイ | ユーザー設定 |
pre-deploy-validation — Playwright自動UI検証
generate.py実行後に自動起動。Playwrightで KPIカード・チャート・テーブルの表示確認、コンソールエラー検出、クロスフィルタリング動作検証を実行。手動ブラウザ確認（5-10分）を自動化（1-2分）。
chart-waterfall — floating bars形式（stacked bar禁止）
| NG (絶対禁止) | OK (正解) |
|---|---|
stacked: true の棒グラフ→バーが地面から積み上がるだけ | [[start, end], ...] 形式のfloating bars→中間バーが正しく「浮く」 |
| 色 | 意味 | 使用場面 |
|---|---|---|
| #1a365d 紺 | 基準値 | Budget, Landing |
| #22c55e 緑 | プラス（EBITDA増） | Revenue増、コスト減 |
| #ef4444 赤 | マイナス（EBITDA減） | Revenue減、コスト増 |
f-string内でバックスラッシュ不可。色は事前に変数定義してから参照。
fabric-direct-lake — 17件fixから抽出した確定仕様
Direct Lake モード設定、TMDL記述、OneLake操作の確定仕様。TMDLにdboスキーマ不可、全columnにsourceColumn必須、SQL Endpointは読み取り専用等、過去17件の失敗から抽出した鉄則。
fabric-patterns — Fabric FP&Aデータ基盤パターン
| Layer | 目的 | 形式 | 更新 |
|---|---|---|---|
| Bronze | 生データ保管 | Parquet/CSV/JSON | Append-only |
| Silver | クレンジング・標準化 | Delta Table (ACID) | Merge/Upsert |
| Gold | BI/ML向け集計済み | Delta / Warehouse | Daily/Hourly |
データサイズ > 1TB → Lakehouse / 複雑なSQL（Window, CTE）→ Warehouse / Python/Spark → Lakehouse / Power BI直結 → Warehouse or Direct Lake
Direct Lake→Import Fallback / 双方向フィルタ乱用 / タイムインテリジェンス不整合 / Delta Schema Evolution失敗 / Capacity枯渇 / カーディナリティ爆発 / RLS漏れ / Pipeline依存ミス / Small Files Problem / カラム型の事前確認不足
fabric-onelake-write — CLI完結書き込み
| 方法 | 可否 | 理由 |
|---|---|---|
| SQL Endpoint DML | ❌ | 設計上読み取り専用 |
| deltalake SDK | ✅ 推奨 | MERGE/DELETE/UPDATE全対応、1秒台完了 |
| OneLake REST API | ✅ | ファイルアップロード可能 |
Azure CLI認証 → bearer_token + use_fabric_endpoint: true でdeltalake SDKから直接DELETE/MERGE/UPDATE。Spark起動(5-10分)不要、SDK完結で1秒台。
delta-table-ops — Delta Table書き込み・監視・最適化
| パターン | コマンド |
|---|---|
| 新規作成 | df.write.format("delta").mode("overwrite").saveAsTable() |
| 差分更新 (MERGE) | DeltaTable.forName().merge().whenMatchedUpdateAll().whenNotMatchedInsertAll() |
| 追記 (Append) | df.write.format("delta").mode("append") |
大量の小さいParquetファイルが蓄積するとクエリ性能劣化。OPTIMIZE でファイル結合、VACUUM で古いバージョン削除。V-Order/Z-Orderで読み取り最適化。
dax-patterns — DAXメジャー設計パターン
| 概念 | 説明 |
|---|---|
| Row Context | 計算列・イテレータで発生。現在行参照。RELATED()必要 |
| Filter Context | メジャーに適用。スライサー/CALCULATEで変更 |
| Context Transition | CALCULATE内のRow→Filter遷移。パフォーマンス注意 |
Time Intelligence (YTD/YoY/Rolling) / Iterator vs Aggregator / CALCULATE深掘り / SaaS KPI (MRR/ARR/NRR/GRR) / 財務パターン（累計・差異・構成比）
bottom-up-validation — ボトムアップ構築→トップダウン検算
財務諸表はボトムアップで構築し、トップダウンで検算する。明細→小計→中計→合計を積み上げ、DBの合計値と突合。許容誤差1.0M。
Revenue - COGS = Gross Profit
Gross Profit - OpEx(G&A + S&M + R&D) = Operating Profit
Operating Profit + Depreciation + Amortization = EBITDA
トップダウンの数字をそのまま表示（検算なし）/ 中区分名のハードコード（DBから取得すべき）/ 0.0ダミー行の表示
financial-modeling — Python財務モデル（P/L, B/S, C/F）
pandas/numpyで3表連結財務モデルを構築。Excelモデルのコード化＋自動化パイプライン対応。
| 財務諸表 | 構造 | 連結ポイント |
|---|---|---|
| P/L (損益計算書) | Revenue → Gross Profit → Operating Profit → EBITDA | Net Income → C/F, Retained Earnings → B/S |
| B/S (貸借対照表) | Assets = Liabilities + Equity | Cash → C/F, Working Capital → C/F |
| C/F (キャッシュフロー) | Operating + Investing + Financing = Net Change | Ending Cash → B/S Cash |
revenue_growth / gross_margin / opex_ratio / tax_rate / ar_days / ap_days / capex_ratio / depreciation_years を @dataclass Assumptions で型安全に管理
reconciliation-patterns — 勘定照合パターン
| 深度 | 種別 | 内容 |
|---|---|---|
| 1 | Balance Reconciliation | 残高一致（Source A = Source B ± 調整項目） |
| 2 | Transaction Reconciliation | 明細突合 |
| 3 | Three-Way Reconciliation | 三点突合（注文書・納品書・請求書） |
| 4 | Waterfall Reconciliation | 変動分析（Budget → Actual の差異分解） |
| 5 | Continuous Reconciliation | リアルタイム照合 |
Timing Difference（一時差異: 将来解消） / Permanent Difference（恒久差異: 解消しない）
clean-code — 可読性・SOLID原則・命名規約
Readability: コードは書く時間より読む時間の方が長い
KISS: 最もシンプルな解決策
DRY: 知識の重複を避ける（コードの重複≠知識の重複）
| 原則 | 要約 |
|---|---|
| S - Single Responsibility | クラスの変更理由は1つだけ |
| O - Open/Closed | 拡張に開き、修正に閉じる |
| L - Liskov Substitution | サブタイプは親と置換可能 |
| I - Interface Segregation | 小さな複数のインターフェース |
| D - Dependency Inversion | 具象ではなく抽象に依存 |
共通化したら元の重複コードを必ず削除。行数が減少しなければリファクタリング未完了。
data-quality-framework — 6次元DQ + 異常検知 + リネージ
| Dimension | 定義 | FP&A例 |
|---|---|---|
| Accuracy | 実態との一致 | ARR = GL売上（繰延調整後） |
| Completeness | 欠損なし | 全顧客の契約終了日存在 |
| Consistency | データソース間一致 | Salesforce MRR = BIツール MRR |
| Timeliness | 鮮度 | 前日実績が翌朝9時までに反映 |
| Validity | ルール準拠 | MRR > 0, 日付 ≤ 今日 |
| Uniqueness | 重複なし | 顧客ID重複ゼロ |
GLリコンが自動で±0.5%以内。データ品質問題で経営判断が遅れない。
requirements-based-testing — 要件駆動テスト設計
| 概念 | 問い | 手法 |
|---|---|---|
| Verification | "正しく作っているか?" | Unit / Integration Test |
| Validation | "正しいものを作っているか?" | Acceptance Test |
要件追跡性マトリクス / Contract Testing（API境界の契約テスト）/ BDD: Given-When-Then / Property-Based Testing（ランダム入力で不変条件を検証）
ユニットテスト100%カバレッジ → でも要件を満たしていない / 全テストグリーン → でもユーザーが使えない
Hooks — 4つの機械的検査
S9で解説したhooksの実装。「お願い」では漏れる検査を、イベント駆動で100%実行する。
ツール呼び出し
Edit / Bash / Read...
security.py
PreToolUse
危険コマンド検知
実行
ツール処理
tool_logger.py
PostToolUse
全操作をJSONL記録
| Hook | タイミング | 役割 |
|---|---|---|
| security.py | PreToolUse | rm -rf / force push / --no-verify 等の危険操作をブロック |
| tool_logger.py | PostToolUse | 全ツール呼び出しを .claude/logs/tool-usage.jsonl に記録 |
| quality.py | PostToolUse | コード品質チェック（Edit後の構文検証等） |
| session_start.py | SessionStart | ブランチ状態・最新verify結果・教訓の自動ロード |
5 Agents — 役割分担
Anthropicの two-agent pattern を拡張。メインはOpus、サブエージェントはSonnet/Haikuでトークンコスト最適化。
impl-agent
チケットに基づく機能実装。コード+ユニットテスト。最もトークンを消費するためSonnet。
reviewer
設計・依存関係・破綻点のレビュー。実装提案は控える。
tester
テスト作成と実行。カバレッジ確認。軽量タスクのためHaiku。
debugger
エラー根本原因分析。スタックトレース解析→修正提案。
verifier
テスト・lint・型チェック・数値整合の実行と合否判定。
7 Projects — モノレポ内の独立ダッシュボード群
autonomous-fpa
全社FP&A統合ダッシュボード。Finance / Funnel / ABM / Marketing の全モジュール統合。
abm
ABM専用ダッシュボード。Leaflet地図+企業スコアリング。
budget-fy27
FY27予算策定。B/S・P/L・C/F三表連結モデル。
hr-dashboard
人事ダッシュボード。ヘッドカウント・退職率。
data-portal
データカタログ＆ポータル。スキーマ管理。
CLAUDE.md — 常設原則の実物
S6で「何を書くか・何を書かないか」を設計すると述べた。実際のCLAUDE.mdは以下の構造で、約40行に収まっている。
| セクション | 内容 | 例 |
|---|---|---|
| 言語 | 出力言語の固定 | 日本語出力。変数名・関数名は英語 |
| ワークフロー | 実行フロー定義 | Plan → Implement → Verify（エラー時Debug） |
| スキル一覧 | 24スキルの分類 | Workflow / Chart / Fabric / Finance / Quality |
| コマンド | テスト・Lint・検証 | uv run pytest -x / uv run ruff check --fix |
| 制約 | 環境固有の注意 | Bash: > /dev/null 2>&1（> nul 禁止） |
| 参照テーブル | ドキュメントへのポインタ | KPI定義 → skills/domain/kpi-definitions.md |
永続記憶 — Auto Memory
セッションを超えて蓄積されるファイルベースの記憶システム。MEMORY.md（インデックス）+ 個別の記憶ファイルで構成。
ユーザー記憶
役割・好み・スキルレベル。応答のパーソナライズに使用。
フィードバック記憶
過去の修正指示。同じミスを繰り返さないためのガードレール。
プロジェクト記憶
進行中の作業・決定事項。文脈の引き継ぎ。
参照記憶
外部システムへのポインタ。Fabric WS / BQテーブル等。
教訓 — 失敗から学ぶ自動フィードバック
session_start hookが毎セッション冒頭で直近の教訓をロードする。過去の失敗をAIが繰り返さないための仕組み。
自省改善サイクル — Claude が自ら賢くなる仕組み
Claude Code は使い捨てのツールではない。ロギング → 分析 → 改善提案 → 適用 → 検証のサイクルを設計すれば、使うほど賢く、便利になる。
自己修復ループの全体像
ロギング（自動）— tool_logger hook
毎回のツール使用が .claude/logs/tool-usage.jsonl に自動記録される。どのファイルを何回読んだか、同じコマンドを何度打ったか、すべてデータとして蓄積。
パターン分析 — /learn
蓄積ログを分析し、繰り返しパターンを検出する。「このファイル3つは常に同時に開かれている」「このBashコマンドは毎日5回実行されている」→ スキル化・自動化の候補として提案。
改善台帳レビュー — /review
改善台帳（improvements.jsonl）に蓄積された提案を週次で棚卸し。未適用の改善が滞留していないか、同種の改善が繰り返されていないか（= 根本原因が未解決）を確認。
教訓化 — lessons.md
失敗から得た教訓を .claude/docs/lessons.md に記録。session_start hook が毎セッション冒頭でロードし、同じ失敗を二度と繰り返さない。
スキル自動生成 — 改善の恒久化
繰り返し検出されたパターンは新しいスキルとして .claude/skills/ に永続化。次回以降、AIが自動で参照する知識に変わる。
週次セルフレビューの実践例
毎週月曜（または任意のタイミング）に以下を Claude Code に指示するだけで、環境が自己改善する。
このサイクルで何が変わるか
Week 1
初期状態。CLAUDE.md + 数個の基本スキル。AIは汎用的に動く。
Week 4
ログ蓄積 → /learn で5つの新スキル生成。頻出パターンが自動化。作業時間が体感で2割減。
Week 8
lessons.md に10+の教訓。同じミスの再発がゼロに。/review で改善の消化率が可視化され、環境がプロジェクトに最適化。
Week 12+
環境全体が「あなた専用の開発アシスタント」に成長。新メンバーが同じ環境で即座に同品質の作業を開始できる。
tool_logger.py hook を設置してログを貯める。1〜2週間後に /learn を実行するだけで、最初の改善提案が得られる。完璧な設計は不要 — 使いながら育てるのがこのサイクルの本質。
まとめ
S13. 環境セットアップ — Claude Code を始める
インストールから最初のコミットまで。スタータープロンプト付き
実務での意味：環境構築に時間をかけず、すぐにハーネス設計の実践に入れる。
今日から：このページの手順に沿ってセットアップし、最初の
/plan → /verify サイクルを回す。
環境セットアップガイド
Claude Code を使い始める前に、開発環境を整える必要がある。すでに環境が整っている場合はスキップして、下のスタータープロンプトへ進む。
前提確認
対応OS: Ubuntu / macOS / WSL2（Windows）。ターミナルが使えることを確認する。
wsl --install を実行。再起動後、Ubuntu が使える。Git のインストール
sudo apt update && sudo apt install -y git git config --global user.name "Your Name" git config --global user.email "you@example.com"
xcode-select --install # Git 含む git config --global user.name "Your Name" git config --global user.email "you@example.com"
Python + uv
uv は Python のバージョン管理とパッケージ管理を兼ねる高速ツール。
curl -LsSf https://astral.sh/uv/install.sh | sh source ~/.bashrc # macOS の場合は ~/.zshrc # Python 3.11 を導入 uv python install 3.11
Claude Code
# Node.js（Claude Code の前提） curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs # Claude Code インストール npm install -g @anthropic-ai/claude-code # 認証（ブラウザが開く） claude # → ブラウザで Anthropic アカウントにログイン # → 認証完了後、ターミナルに戻る # 確認 claude auth status
# Node.js（Homebrew 経由） brew install node # Claude Code インストール npm install -g @anthropic-ai/claude-code # 認証（ブラウザが開く） claude # → ブラウザで Anthropic アカウントにログイン # 確認 claude auth status
作業ディレクトリを作成して Claude Code を起動
mkdir ~/my-project && cd ~/my-project claude # ← ここで下のスタータープロンプトを貼り付け
Claude Code 5レイヤー構成 一発セットアッププロンプト
以下のプロンプトをClaude Codeにそのまま貼り付けると、このガイドで解説した5レイヤー構成のモノレポが自動生成される。プロジェクト名や用途は自分の業務に合わせて書き換えること。
あなたは Claude Code 環境のアーキテクトです。以下の仕様に従って、初心者でも運用しやすい、実際に動作する最小完全体のモノレポを一括生成してください。
重要:
- これは提案ではなく**実際のファイル生成依頼**です。
- すべてのファイルは実際に意味のある内容で作成してください。プレースホルダーは禁止です。
- 曖昧な箇所は、**安全で単純で保守しやすい方**を選んでください。
- 初回セットアップでは、過剰機能より**確実に動くこと**を優先してください。
- 自動 push / 自動 deploy は行わないでください。ローカル検証と初回コミットまでで止めてください。
==================================================
0. 実行モード
==================================================
最初に環境診断を行ってください。
いきなりファイル生成や編集を始めず、まず以下の Preflight を実行し、
不足があれば質問してください。
==================================================
0-1. Preflight（環境診断）
==================================================
まず以下を確認してください。すべて Bash で実行し、結果を表示してください。
- OS 種別（uname -s）
- git --version
- git config --global user.name
- git config --global user.email
- uv --version
- python3 --version
- 現在の作業ディレクトリ（pwd）
- 作業ディレクトリが空か（ls -la）
不足がある場合:
- Git identity 未設定 → ユーザーに名前とメールアドレスを聞く
- uv 未導入 → 「uv のインストールが必要です。curl -LsSf https://astral.sh/uv/install.sh | sh を実行してよいですか？」と確認
- Python 3.11+ 未導入 → 「uv python install 3.11 を実行してよいですか？」と確認
- 作業ディレクトリが空でない → 「既存ファイルがあります。続行してよいですか？」と確認
すべて確認できたら、セクション1以降に進んでください。
==================================================
1. 基本情報（★書き換え）
==================================================
- プロジェクト名: my-project
- 用途: [あなたの業務内容を書く。例: SaaSダッシュボード開発 / データ分析 / Webアプリ / 社内業務自動化]
- 主言語: Python 3.11+
- パッケージマネージャ: uv
- OS 前提: macOS / Linux
- Git ブランチ: main
- 出力言語: 日本語
- 命名規則: 変数名・関数名・ファイル名は英語
- 最初のサブプロジェクト名: app
==================================================
2. 目標
==================================================
以下を一括で完了してください。
1. 実際に使えるモノレポを生成
2. Claude Code の 5 レイヤー構造を作成
3. 最小限の Python サンプル実装とテストを含める
4. pytest / ruff が通る状態にする
5. git init と初回コミットまで行う
6. 最後に、生成したファイル一覧と各レイヤーの役割を要約する
==================================================
3. 生成するディレクトリ構造
==================================================
以下の構造を生成してください。
```text
my-project/
├── .claude/
│ ├── CLAUDE.md
│ ├── settings.json
│ ├── docs/
│ │ ├── workflow.md
│ │ ├── patterns.md
│ │ └── lessons.md
│ ├── skills/
│ │ ├── plan/SKILL.md
│ │ ├── verify/SKILL.md
│ │ ├── debug/SKILL.md
│ │ └── deploy-rules/SKILL.md
│ ├── hooks/
│ │ ├── security.py
│ │ └── tool_logger.py
│ ├── agents/
│ │ ├── impl-agent.md
│ │ ├── reviewer.md
│ │ └── verifier.md
│ ├── out/
│ │ └── .gitkeep
│ └── logs/
│ └── .gitkeep
├── projects/
│ ├── CLAUDE.md
│ └── app/
│ ├── README.md
│ ├── src/
│ │ ├── __init__.py
│ │ └── main.py
│ └── tests/
│ └── test_main.py
├── tests/
│ └── smoke/
│ └── test_repo_smoke.py
├── scripts/
│ └── verify.sh
├── .editorconfig
├── .gitignore
├── .python-version
├── README.md
└── pyproject.toml
```
ルール:
- 初回版は Python 中心でよい
- TypeScript や複雑なフロントエンド構成は入れない
- ただし将来拡張しやすいように、docs と rules はモノレポ前提で書く
==================================================
4. 5レイヤーの責務
==================================================
このリポジトリは以下の 5 レイヤーで構成してください。
- CLAUDE.md — 常に効く原則だけを書く
- skills/ — 必要なときだけ参照する手順を書く
- hooks/ — 実行タイミングで機械的に差し込むチェックを書く
- docs/ — 人間が読む運用ルール・規約・教訓を書く
- agents/ — 役割分担を定義する
禁止:
- スキルの詳細手順を CLAUDE.md に書かない
- hook でやるべきことを自然言語ルールだけに頼らない
- reviewer に実装させない
- verifier に設計変更をさせない
==================================================
5. CLAUDE.md の要件
==================================================
.claude/CLAUDE.md は6セクションのみ、40行以内で作成してください。
余計な文章は禁止です。
セクションは以下のみ:
- 言語
- ワークフロー
- スキル一覧
- コマンド
- 制約
- 参照
要件:
- スキルの中身は書かない
- 「どのスキルが存在するか」だけを書く
- 日本語で書く
- コマンドは表で簡潔に書く
projects/CLAUDE.md は、projects 配下共通のローカルルールを書くこと。
内容は以下に限定:
- project 配下の役割
- README 必須
- src/tests 分離
- 大きな変更は plan を先に出すこと
==================================================
6. docs/ の要件
==================================================
workflow.md:
- 基本フロー: Plan → Implement → Verify
- エラー時: Debug → Fix → Verify
- 小修正と複数ファイル変更の違い
- verify 前に必ずやること
patterns.md:
- Python コーディング規約
- 命名規則
- テスト規約
- やってはいけない例
lessons.md:
- 空ではなく、以下の見出しだけ置いて初期化:
- Date
- Context
- Lesson
- Action
==================================================
7. Skills の要件
==================================================
各 skill は以下の frontmatter 形式で作成してください。
```yaml
---
name: skill-name
description: 1行説明。Use when [トリガー条件] or when the user says "[キーワード]".
user-invocable: true
context: fork
allowed-tools: [Read, Edit, Write, Bash, Grep, Glob]
---
```
plan:
- 入力: 問題 / 対象 / 制約 / 完了条件
- 3点リスクチェック: 符号(Sign) / NULL・空値 / 境界条件
- タスク分割
- 出力: .claude/out/YYYYMMDD-plan.md
verify:
- git diff HEAD で差分取得
- 差分がなければ終了
- pytest / ruff 実行
- Critical / High / Medium / Low 観点でレビュー
- 出力: .claude/out/YYYYMMDD-verify.md
- commit は行ってよいが push はしない
debug:
- 再現優先 / 二分探索 / 最小再現 / 5 Whys
- 根本原因を 1 つに絞る
- 修正後はテストして verify
deploy-rules:
- デプロイコマンド例
- デプロイ前チェックリスト
- 未設定環境では build / artifact 確認までで止める
- 初回版では自動 deploy しない
==================================================
8. Hooks の要件
==================================================
初回版では hook は 2 本だけ作ってください。
security.py:
- PreToolUse 用
- Bash コマンドを検査
- 以下を検出したら警告を出す:
- rm -rf
- git push --force / git push -f
- --no-verify
- sudo rm
- block ではなく warn にする
- 壊れずに動く Python コードにする
tool_logger.py:
- PostToolUse 用
- 操作ログを .claude/logs/tool-usage.jsonl に追記
- 項目: timestamp / tool_name / file_path
- 壊れずに動く Python コードにする
==================================================
9. settings.json の要件
==================================================
以下をベースに、実際に動く形で生成してください。
```json
{
"permissions": {
"allow": [
"Read",
"Write",
"Edit",
"Glob",
"Grep",
"Bash(uv run pytest*)",
"Bash(uv run ruff*)",
"Bash(git status*)",
"Bash(git diff*)",
"Bash(git log*)",
"Bash(git add*)",
"Bash(git commit*)"
],
"deny": [
"Bash(rm -rf*)",
"Bash(git push --force*)",
"Bash(git push -f*)"
]
},
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "python .claude/hooks/security.py" }
]
}
],
"PostToolUse": [
{
"matcher": "*",
"hooks": [
{ "type": "command", "command": "python .claude/hooks/tool_logger.py" }
]
}
]
}
}
```
==================================================
10. Agents の要件
==================================================
.claude/agents/ に以下の 3 体を作成してください。
形式:
```yaml
---
name: agent-name
model: sonnet
tools: [適切なツール群]
---
```
impl-agent:
- model: sonnet
- 実装担当
- レビューしない
reviewer:
- model: sonnet
- 設計・依存関係・破綻点レビュー担当
- 実装しない
verifier:
- model: haiku
- テスト / lint 実行と合否判定
- 設計変更しない
==================================================
11. ルート設定ファイルの要件
==================================================
pyproject.toml:
- project metadata
- requires-python = ">=3.11"
- pytest 設定
- ruff 設定
- 開発依存
.gitignore:
- .venv/ / __pycache__/ / .pytest_cache/ / .ruff_cache/
- .DS_Store
- .claude/logs/*.jsonl
- .claude/out/*.md
.editorconfig:
- 一般的設定を入れる
.python-version:
- 3.11
==================================================
12. サンプル実装の要件
==================================================
projects/app/ には、用途が未具体化でも実際に動く最小サンプルを置いてください。
src/main.py:
- 例: 数値リストから件数、合計、平均を返す関数
tests/test_main.py:
- 正常系 / 空配列 / 境界条件
README.md:
- 役割 / 実行方法 / テスト方法 / 拡張方針
==================================================
13. scripts/verify.sh の要件
==================================================
以下を順に実行するシェルスクリプトを作成:
1. uv run ruff check .
2. uv run pytest -q
失敗時は非ゼロ終了。実行権限を付与すること。
==================================================
14. 実行指示
==================================================
以下の順序で実行してください。
1. Preflight で環境診断（セクション0-1）
2. 不足があればユーザーに確認
3. 全ファイル生成
4. uv 環境構成
5. テスト・Lint 実行
6. エラーがあれば修正→再実行
7. git init → git add -A → git commit -m "feat: initialize monorepo with Claude Code 5-layer architecture"
push はしないでください。
==================================================
15. 最後に出力する内容
==================================================
最後に以下を出力してください。
- Preflight で確認した環境情報と解決状況
- 生成した主要ファイル一覧
- 各レイヤーの役割（CLAUDE.md / skills / hooks / docs / agents）
- 実行した検証コマンドと結果
- 初回コミット SHA
- 次にやるべき 5 項目
==================================================
16. 開始
==================================================
上記仕様に従って、実際にファイルを生成し、検証し、初回コミットまで完了してください。
不足情報があっても止まらず、既定値で埋めて構築してください。
/plan で計画、実装、/verify で検証→コミットのサイクルを回す。