Claude Code の精度90%では、私が満足できなかった理由

はじめに

私はふだん、MSP 監視チームのマネジメントをしながら、チームの戦略立案や数字の分析を Claude Code で回しています。

施策の検討メモ、KPI や障害対応の数字の分析、四半期の振り返り、上申資料の下書き。Claude Code の作業ディレクトリの下に用途ごとのフォルダを切って、プロジェクトごとに Markdown を置いて管理しているのですが、使えば使うほど、そこに文脈がどんどん溜まっていきます。

Claude が書いてくれる分析や資料の下書きは、体感で90点くらいには仕上がります。客観的に測った数字ではなく、あくまで私の肌感覚ですが。90点なら上等——のはずなのに、私はこの状態に満足できていませんでした。下書きを全部、頭から疑って読み直していたからです。

なぜ疑って読むのか。残りの1割に、毎回ヒヤッとさせられていたからです。マネジメントの文書って、数字を根拠に何かを判断したり、上に報告したりするためのものなんですよね。数字や事実が1割でも怪しいと、判断材料として使えない。ここが、ブログのような読み物との大きな違いだと思います。

で、あるとき気づいたんです。Claude が賢くないんじゃなくて、私のフォルダのほうが Claude に意地悪な状態になっていたことに。

今日はその1割を潰すために入れた「セマンティックレイヤー」の話です。先に結論の骨だけ言っておくと、Claude Code の Skills が「やり方」を教える仕組みだとしたら、セマンティックレイヤーは「事実」を教える仕組みです。この2つは似て非なるもので、ここを分けると誤読は仕組みで潰せます。本文の後半で、辞書あり・なしの出力を実際に比べた実験結果もそのまま載せます。

ざっくり言うと

• 長く使うフォルダには、独自の呼び名・略語・記号がどんどん溜まる。なのに、その意味は書いた本人の頭の中＝「脳内辞書」にしかない。これが Claude の誤読の温床になる
• Skills は「やり方」を教える仕組み、セマンティックレイヤーは「事実」を教える仕組み。動詞と名詞くらい役割が違う
• 戦略や分析の文書は数字が根拠。AI の答えが9割正しくても、残り1割を疑って全部確認し直しているうちは、判断材料に使えない。セマンティックレイヤーはその1割に効く
• 作ったのは Markdown ファイル2つと、CLAUDE.md への数行だけ。辞書あり・なしで同じ依頼を比べたら、数字の出典と役割の書き分けに一目瞭然の差が出た（本文に実験結果を掲載）

特に2つ目の「動詞と名詞」の整理は、私の中でかなりスッキリしたポイントだったので、ぜひ持ち帰ってほしいです。

きっかけ：言葉の定義が、脳内にしかなかった

長く使っているフォルダって、使えば使うほど独自の言葉が増えていくんですよね。

たとえば、こんな言葉たちです。

• プロジェクトを縮めた呼び名
• 「P1＝最優先で着手、P2＝今期中に対応」のような、施策の優先度を表す略記
• 「2026Q1」＝暦の1〜3月ではなく年度の第1四半期（4〜6月）、という期間の表記
• 「売上」のような当たり前の言葉ですら、税込か税抜かで数字が変わる、という数字の前提

どれも私の中では当たり前なのに、ファイルのどこにも意味が書いていません。

つまり、フォルダには言葉だけが溜まっていて、その意味を引ける辞書は私の頭の中にしかなかったんです。これを「脳内辞書」と呼ぶことにします。

人間のチームに新人が入ったら、先輩が脳内辞書の中身を口頭で教えられます。でも Claude Code は、新しいセッションを立ち上げるたびに「初日の新人」がやってくるのと同じです。過去ファイルを読んで推測はしてくれますが、当たることもあれば、外すこともある。

一番怖いのが、「誰がやったか」の取り違えです。

私のメモには、自分が設計・開発しているツールと、別のチームが進めているプロジェクトが並んで書いてあります。人間が読めば文脈で分かりますが、メモの書き方が曖昧なら、Claude が別チームの成果まで「私がやった」寄りのトーンで書いてしまってもおかしくありません。実際、後述の実験では、辞書がないと関与がじわっと膨らむ出力になりました。

誰の成果かを取り違えた資料がそのまま上に上がったら事故です。報告の信頼にも、チームの評価にも関わります。レビューで拾い続けるのにも限界があります。

最初は「Skills でなんとかするもの」だと思っていた

Claude Code のカスタマイズというと、まず Skills が浮かびますよね。私も最初はそう考えました。

実際、資料の型を整えるスキルや、複数視点（顧客・現場・数字）でレビューさせるスキルは既に作っていて、これはこれでかなり効いています。

でも「脳内辞書の問題」を Skills に押し込もうとすると、どうも気持ち悪い。

レビュー用スキルの中に「プロジェクトAは自分がやった、プロジェクトBは別チーム」って書くのは、明らかに置き場所が違うんですよね。レビューの観点とフォルダの事実が混ざって、スキルがどんどん汚れていく未来が見えました。

Skills の良さは「タスクの種類で発動して、個人用に作ればどのフォルダでも使い回せる」ことです。そこにフォルダ固有の事実を混ぜたら、その良さを自分で殺すことになる。ここで一度立ち止まれたのは、よかったなと思います。

セマンティックレイヤーという考え方を借りてきた

そこで借りてきたのが、BI の世界の「セマンティックレイヤー」という考え方です。

データウェアハウスの上に「用語と指標の正しい定義」を一枚かぶせて、誰がどこから集計しても同じ意味で数字が出る状態を作る層のことです。たとえば同じ「売上」でも、営業は受注ベース、経理は入金ベースで数字を出してきて会議で食い違う——ああいう「言葉の定義のズレ」を仕組みで防ぐためのものですね。

実はこの考え方、Agentic AI（自律的に動く AI エージェント）の文脈で、いま業界の定石になりつつあります。AI エージェント時代のデータ基盤に求められる要件を語るとき、「セマンティックレイヤー」はもう外せない柱の1つとして挙げられるようになってきました。

理屈はこうです。

• 自然言語で聞かれるたびに生成 AI が SQL を推測する方式（Text-to-SQL）は、精度がかなり上がった今でも「もっともらしい間違い」のリスクが残る
• まったく同じ構成のエージェントに同じ質問をしても、売上や粗利の計算ロジックがズレて違う答えを返してしまうことがある
• だから推測させるのではなく、定義済みのロジックを一元管理した層が答えを作る。そうすれば誰が・どのエージェントが聞いても、常に同じ答えが返る

——という設計です。

厳密にはレイヤーが少し違っていて、BI のセマンティックレイヤーが本丸にしているのは「売上＝何を足したものか」みたいな計算ロジックの定義です。私がやりたかったのは「この言葉は何を指すか」「このプロジェクトは誰がやったのか」という用語と役割の定義なので、どちらかというと用語カタログ寄り。それでも、狙いはまったく同じなんですよね。推測させるんじゃなくて、定義を参照させる。

Claude がセッションのたびに過去ファイルから「誰がやったか」や期間を「推測」するのが Text-to-SQL 側で、辞書に書かれた定義を「参照」するのがセマンティックレイヤー側。推測はもっともらしく外れるけど、参照なら外しにくい。BI の世界が先に通った道に、ちゃっかり乗らせてもらったわけです。

これを Claude Code のフォルダでやるとどうなるか。用途ごとに切っているフォルダのうち、まずは誤読がいちばん痛い戦略・分析用のフォルダに _semantics/ というサブフォルダを作りました。作ったものは、拍子抜けするほどシンプルです。

• _semantics/用語・エンティティ辞書.md — プロジェクト名・略語・記号・登場人物の定義集。目玉は「プロジェクトごとに、私の役割は何で、文章でどう書くべきか」を1つの表にしたもの
• _semantics/メトリクス・日付定義.md — 数字と日付のルール集。「アラート件数はどのツールのどの画面の値を正とするか」「数字には計測日を必ず添える」「2026Q1＝年度の第1四半期」といった決めごとを書いておく
• CLAUDE.md への数行 — 「資料の下書き・数字の引用・分析をする前に _semantics/ の該当ファイルを読むこと」

一番効いている「プロジェクト×役割の表」は、こんな雰囲気です（中身はダミーに置き換えています）。

たったこれだけです。でも、この「基盤B」の行があるかないかで、Claude の書き方は実際に変わります。後ほど実験でお見せします。

特別な機能は何も使っていません。ただの Markdown と、それを読むタイミングのルールだけ。しかも辞書づくり自体を Claude にやらせたので、私が手を動かしたのは正味30分くらいです。「このフォルダで定義なしに使われている言葉を洗い出して、必要なことを私にヒアリングして」と頼んだら、grep で怪しい言葉を集めてきて、あとは選択式の質問に答えるだけで叩き台ができました。これは素直に楽でした。

やってみて分かったんですが、セマンティックレイヤーづくりって、要するに脳内辞書を外に書き出す作業なんですよね。難しいのは技術ではなく、「自分の頭の中にしかない定義はどれか」に気づくことの方でした。

動詞の Skills、名詞のセマンティックレイヤー

ここが今日いちばん伝えたいところです。

そして実際の動き方は、こうです。

Skill が動くとき、辞書が材料になる。

たとえば資料レビューのスキルが「この文章は、誰がやったかを正しく書けているか」をチェックするとき。「どうチェックするか」という手順はスキルが知っていて、「このプロジェクトは誰が主体か」という事実は辞書が知っている。やり方はスキル、事実は辞書——という分担がきれいに決まりました。

この整理ができてから、「これはどっちに書くべき？」で迷うことがなくなったのが、地味に嬉しいです。

辞書のあり・なしで、実際に比べてみた

正直に言うと、導入してまだ日が浅いので、「劇的に変わりました」と体験談だけで語るのはフェアじゃないなと思いました。なので、誰でも再現できる形で実験してみます。

ダミーのサンプルフォルダを用意しました。中身はメモ4本だけです。

• ツールA の開発メモ — 「設計も実装もここまで一人で回している」と明記
• 基盤B の連携メモ — 「方針決定には深く関わっている。手は動かしていない」とだけ書かれた曖昧な状態
• 横断WG のメモ — 全体方針は自分が作成、各部の運営はリーダーに移管済み
• 2026Q1 の KPI メモ — 一次対応時間 12.5 分、アラート件数 8,420 件など。出典の記載なし

ここに前述の _semantics/（役割辞書とメトリクス定義）を置いた場合と置かない場合で、まったく同じ依頼をしました。「上長向けの 2026Q1 振り返り報告ドラフトを300字程度で」です。出力をそのまま載せます（太字は筆者による強調で、あり・なしで差が出た箇所です）。

🔴 辞書なし

2026Q1（4〜6月）の主な取り組みを報告します。ツールAでは、トリアージ判断フロー（HITL）と通知優先度ロジックの設計・実装を私自身が担当し、α版を5名へ配布してフィードバック収集を開始しました。基盤Bでは、アーキテクチャ方針レビューに参画し、ストリーミングによるデータ結合方針の決定とスキーマ設計（結合キー）への助言を行いました。横断WG（運用設計標準化）では、全体方針ドラフトを私が作成して立ち上げを主導し、各部リーダーへの運営移管と標準テンプレートの2部署適用開始まで進めました。KPIは一次対応時間が平均18.2分→12.5分、エスカレーション率が9.1%→6.8%に改善（アラート件数8,420件）。

🟢 辞書あり

2026Q1（2026年4月〜6月）振り返り報告。ツールAは、トリアージ判断フローと通知優先度ロジックを自ら設計・実装し、α版を5名へ配布してフィードバック収集を開始しました。基盤Bは、データ結合をストリーミング方式とするなどの技術方針を決定しました（実装は基盤グループが担当）。横断WG（運用設計標準化）は、全体の方向性を定義し、標準テンプレートの適用が2部署で開始されています。KPIは、一次対応時間が平均12.5分（2026Q1・監視ダッシュボード月次レポート、前期18.2分）、アラート件数8,420件（2026Q1・集計ツールZ）、エスカレーション率6.8%（2026Q1・集計ツールZ、前期9.1%）と改善傾向です。

太字の箇所を観点ごとに抜き出して並べると、差は3つです。

① 数字の出どころ —— 一番大きな差

• 🔴 なし：「平均18.2分→12.5分、エスカレーション率が9.1%→6.8%に改善」…数字が全部裸のまま
• 🟢 あり：「平均12.5分（2026Q1・監視ダッシュボード月次レポート、前期18.2分）」…全数字に（期間・計測ソース）付き

上長に「この12.5分、どこの値？」と聞かれて詰まるのが前者です。

② 役割の距離感 —— メモが曖昧だった基盤B・横断WGで差

• 🔴 なし：「方針の決定と…助言を行いました」「運営移管…まで進めました」…私の関与がじわっと膨らんでいる
• 🟢 あり：「技術方針を決定しました（実装は基盤グループが担当）」「方向性を定義し」…辞書の書き分けの線をきっちり守った

ちなみに、メモに役割が明記されていたツールAはどちらも正しく書けています。差が出るのは、メモが曖昧なところなんですよね。

③ 期間 —— 実は差がつかなかった（正直に）

• 🔴 なし：「2026Q1（4〜6月）」…正解。メモの日付から推測が当たった
• 🟢 あり：「2026Q1（2026年4月〜6月）」…定義を参照して確定

推測でも当たることはあります。ただ、これは当たっただけ。辞書は「当てる必要」そのものをなくします。

3点目のように「なしでも合っていた」を隠さず書くのが、この実験のフェアなところだと思っています。そして、当たったかどうかを毎回確かめる作業——それが次に話す「確認コスト」です。

もう1つ正直に書いておくと、「CLAUDE.md に読めと書けば必ず読む」わけではありません。Claude が指示を読み飛ばすことは普通にあります。それでも、推測の土台に「参照できる正解」があるかないかで、出力はこの実験くらい変わります。

ポイントは、「指摘して直させる」より手前で「そもそも間違いにくくなる」ことです。レビューが楽になるというより、レビューで見るものの種類が変わる感覚に近いです。

これがなぜ大事か。データ活用の世界に、私がぐうの音も出なかった考え方があります。

精度が9割あっても、残りの1割が外れうると分かっている限り、出てきたものを「そのまま信じて出す」ことはできない。作業はぐっと楽になる。それでも、最後は自分の目で確かめ直すことになる。

まさにこれでした。Claude の下書きが体感90点でも、「誰がやったか」や数字がたまに外れると分かっている限り、私は全部の行を疑ってレビューするしかない。判断や報告の根拠にする数字なら、なおさらです。90点と100点の差は10点ではなく、「疑いながら読む」か「信じて読めるか」の差なんですよね。タイトルで「90%では満足できなかった」と書いたのは、まさにこの状態のことでした。

脳内辞書にしかなかった部分だけでも「外れにくい」状態にすると、レビューはやっと「内容の良し悪し」に集中できるようになります。

あと、ちょっとびっくりしたのは、辞書が自分にも効いたこと。半年前に自分が作った呼び名やルールって、自分でも忘れてるんですよね。脳内辞書は思った以上に揮発します。書き出した辞書は Claude のためのものであると同時に、未来の自分のためのリファレンスでもありました。

思ったこと

もう1つ。この問題は「モデルが賢くなれば解決する」類のものではない、と思っています。

LLM はどんどん賢くなりますが、どれだけ賢くなっても、私の脳内辞書の中身までは学習してくれません。「2026Q1 が年度の第1四半期」かどうかは、賢さの問題ではなく情報の問題だからです。だからこそ、モデル側に期待するのではなく、フォルダ側に定義を置く。

そして、戦略や分析を AI に任せる範囲が広がるほど、「確実な定義」と「出どころの確かな数字」の価値はむしろ上がっていくと思っています。AI がコモディティ化していくほど、差がつくのはこちら側——自分のデータと文脈の整備——なんだろうな、と。

数字に誤りが1つでもあれば、その資料の価値は限りなくゼロに近づきます。「神は細部に宿る」ではないですが、定義や出どころといった細部を突き詰めておくこと。それが、AI エージェントとの協働をより高い生産性に変えていくと、私は信じています。

「それ、全部 CLAUDE.md に書けばいいのでは？」という声もありそうです。

私は分けてよかったと思っています。CLAUDE.md は毎セッション無条件に読み込まれるので、何でも書くと肥大化して、毎回のコンテキストを無駄に食います。辞書は「該当する作業のときだけ読む」参照資料にしておく。常駐させるのはルールの数行だけ。この構造のほうが、コンテキストのコスパが良いです。

それと、Skills が悪者という話では全くないです。文体やレビューの観点みたいな「やり方」は、今もスキルが主役です。脳内辞書の中身だけを外の辞書ファイルに逃がしたことで、むしろスキルが本来の仕事に集中できるようになった、という感覚です。

これからどうするか

運用ルールは1つだけにしました。

新しい言葉や役割の変更が出たら、その日のうちに辞書に追記する。

業務メモと同じで、辞書も鮮度が命だと思っています。後からまとめて書くのは、たぶん無理です。

それと、辞書はメンテを止めると逆に嘘をつき始めます。更新が止まった定義を Claude が信じて参照したら、誤読より厄介です。なので「辞書と実態が食い違ったら、どちらを正とするか」だけは先に決めておきました。私の場合は、別に置いてある事実集約ファイルが常に上位、と決めています。優先順位が1行あるだけで、矛盾に気づいたとき迷わず直せます。

あとは、実名と伏字の変換表（社外向けの資料を作るときの置換ルール）も同じ _semantics/ に足せる設計にしてあるので、必要になったら追加する予定です。

まとめ

• 長く使うフォルダには独自の呼び名・略語・記号が溜まるが、その意味は「脳内辞書」にしかなく、Claude の誤読の温床になる
• Skills は動詞（やり方）、セマンティックレイヤーは名詞（事実・定義）。混ぜるとスキルが汚れる
• 「推測させる」のではなく「定義を参照させる」。データ基盤の世界で定石になりつつある設計を、フォルダに小さく適用する
• 実体は Markdown ファイル2つ＋CLAUDE.md 数行。「タスクの前に読む」ルールを足すだけ
• 辞書あり・なしで同じ依頼を比べると、数字の出典の有無と役割の書き分けに明確な差が出た（本文に実験結果）
• 精度が9割あっても、残り1割の確認コストが消えなければ楽にならない。脳内辞書を外に書き出して「外れにくい」状態にし、レビューを内容の良し悪しに集中させる

Claude Code で日々のドキュメント仕事を回している方 — 戦略メモや分析レポートが育ってきて、セッションをまたぐたびに微妙な誤読に出会っている方 — は、まず「定義が自分の脳内にしかない言葉」を10個書き出すところから試してみてほしいです。たぶん10個、すぐ出てきます。