AIコーディングツールの「知識管理」を設計したら、チームが安定した
📊この記事の図解版があります。内容を視覚的にまとめたページで、全体像をサッと把握できます
図解を見るはじめに
前回の記事では、AIコーディングツールに「取扱説明書」を書くことで開発がどう変わるかを紹介した。ルールファイルの書き方、コンテキストウィンドウの制約、そしてAI出力の検証方法。この3つを押さえるだけで、AIとの協働は格段にスムーズになる。
しかし、運用を続けてみると新しい壁にぶつかった。
スキル（AIに特定の業務を任せるためのプロンプトセット）が増えるにつれて、ドメイン知識があちこちに散らばってしまったのだ。ルールを書いたその「次」が必要だった。
この記事では、知識の散らばりを構造で解決する3つのアプローチを紹介する。
- ドメイン知識を1箇所に集約する
- 「最初に何を読むか」を明示する
- スキルの命名規則で「探す時間」をゼロにする
問題: ドメイン知識が「散らばる」
コピペ増殖のパターン
ある訪問看護プロジェクトで、AIに業務を任せるスキルが11個まで増えた。シフト作成、経営会議、ケアプラン評価、訪問記録の整理――それぞれ異なるタスクを処理するスキルだ。
問題は、ほぼすべてのスキルが同じデータベース定義を必要としていたこと。接続情報、テーブル構成、よく使うクエリパターン。これらをスキルごとにコピペして埋め込んでいた。
当然、データベースのテーブル構成が変わったときに修正漏れが起きる。11個中3個のスキルが古い定義のまま残り、AIが誤った情報をもとに出力を生成した。
これはコピペした人の注意力の問題ではなく、「同じ情報が複数箇所に存在する」という構造の問題だ。
SSOT（Single Source of Truth）という考え方
ソフトウェア開発には**SSOT（Single Source of Truth = 信頼できる唯一の情報源）**という原則がある。ある情報について「正しい版はこの1箇所だけ」と決め、他の場所からはそこを参照する。
プログラミングでいう DRY（Don’t Repeat Yourself = 同じことを繰り返すな）原則と根っこは同じだ。コードでもドキュメントでも、同じ内容のコピペは更新漏れの温床になる。
この考え方をAIのスキル管理に適用したのが、次の3つの対策だ。
対策1: ドメイン知識を1箇所に集約する
「知識の入口ファイル」を作る
11個のスキルに散らばっていたデータベース定義を、1つのファイルにまとめた。実際に作成したファイルの構成はこうなっている。
# ドメイン知識 — 入口ガイド
## 1. SSOT宣言
Supabaseが正（SSOT）です。ファイルとDBで齟齬がある場合はDBを優先する。
## 2. 接続方法
Session Pooler 経由で接続。IPv4環境ではこちらを使用。
## 3. 主要テーブルと用途
| テーブル | 主要カラム | 用途 |
|---|---|---|
| clients | id, name, care_issues, goals | 利用者情報 |
| visits | id, client_id, scheduled_date, status | 訪問予定・実績 |
| staff | id, name, is_active | スタッフ情報 |
## 4. よく使うクエリパターン
（利用者検索、月次集計、バイタル取得など）
## 5. 権限
（ANON_KEY と SERVICE_ROLE_KEY の使い分け）
## 6. 詳細リファレンスへのリンク
（さらに詳しく知りたい場合の参照先）ポイントは、このファイル自体が「入口」であることだ。すべての詳細を書き込むのではなく、概要と参照先リンクを整理している。
各スキルはこのファイルを参照するだけでよい。「DB定義を知りたければ、このファイルを見て」と1行書くだけだ。
効果と注意点
修正が1箇所で済む。 テーブル構成が変わっても、入口ファイルを更新すれば全スキルに反映される。新しいスキルを作るときも、参照先を指定するだけなので立ち上がりが速い。
注意点は肥大化させないこと。入口ファイルが500行を超えたら、セクションごとに別ファイルへ切り出し、入口はリンク集として維持する。「入口は常に薄く保つ」のが長続きの秘訣だ。
対策2: 「最初に何を読むか」を明示する
優先度付き参照テーブル
知識を1箇所に集めても、AIには「どこから読むか」の判断基準がない。人間なら経験で優先順位をつけられるが、AIはそうはいかない。
そこで、スキルの冒頭に優先度付きの参照テーブルを置くようにした。
## 参照コンテキスト（最初に読むもの）
| 優先度 | ファイル | 用途 |
|--------|---------|------|
| 1 | philosophy/core/事業戦略基盤.md | 会社の価値観・意思決定基準 |
| 2 | philosophy/core/GPS思考フレームワーク.md | フレームワークの定義 |
| 3 | projects/{PROJECT}/overview.md | プロジェクトの背景・現状 |「優先度1」は必ず読む。「優先度2」は判断に迷ったら読む。「優先度3」はプロジェクト固有の文脈が必要なとき。この序列を明示するだけで、AIの初動が安定する。
汎用化のポイント
これは Claude Code 固有のテクニックではない。どんなAIツールでも、プロンプトの冒頭に「最初に読むべき3つのファイル」を書くだけで同じ効果が得られる。
このタスクを始める前に、以下のファイルを順に読んでください:
1. docs/architecture.md（全体設計）
2. docs/api-spec.md（API仕様）
3. src/types/index.ts（型定義）人間の新人に「まずこの3つのドキュメントを読んで」と伝えるのと同じだ。読む順番を指定することで、AIは前提知識を積み上げた状態でタスクに着手できる。
対策3: スキルの命名規則で「探す時間」をゼロにする
expert-{領域}-{機能} パターン
スキルが増えると、「どのスキルを使えばいいか」の判断コストが上がる。11個のスキルの中から適切なものを選ぶのは、名前が曖昧だと人間にもAIにも難しい。
以前は gps-design という名前だったスキルを、expert-gps-design にリネームした。同様に、領域ごとの命名規則を統一した。
命名パターン:
├── expert-{機能} → expert-gps-design, expert-review-cycle
├── expert-{project}-{機能} → expert-yulier-mgmt-meeting
└── {project}-{機能} → yulier-shift, zxy-agenda名前を見ただけで「これはExpert（専門家）スキルで、GPS設計を担当する」とわかる。プロジェクト固有のスキルには、プロジェクト名がプレフィックスとして入る。
命名規則は「AIへの検索インデックス」
一貫した命名規則があると、AIはスキル名を見るだけで用途を判断できる。
たとえば「経営会議の準備をしてほしい」という指示を受けたとき、AIは expert-yulier-mgmt-meeting という名前から「YULIERプロジェクトの経営会議用Expertスキル」だと即座にマッチングできる。
これが meeting-prep や weekly-mtg のような曖昧な名前だと、AIはスキルの中身を読んで判断する必要がある。スキルが5個なら問題ないが、20個、30個と増えたときに選定の精度が落ちる。
名前は「AIへの検索インデックス」だ。 機能を正確に表現する名前をつけることが、スキルの増加に耐える設計につながる。
まとめ: 知識設計の3原則
AIコーディングツールのスキルが増えてきたら、以下の3つを意識すると出力品質が安定する。
1. 散らさない（SSOT）
同じ情報をコピペで増やさない。「正しい版はここだけ」と決めて、他はすべてそこを参照する。入口ファイルを1つ作るだけで、修正コストが劇的に下がる。
2. 読む順番を決める（優先度付き参照）
AIに「まずこのファイルを読んで、次にこれ」と優先順位をつける。人間の新人に「最初にこの3つのドキュメントを読んで」と伝えるのと同じ。読む順番を指示するだけで、AIの初動の安定感が変わる。
3. 名前で語らせる（命名規則）
スキルや設定ファイルの名前は「AIへの検索インデックス」。expert-{領域}-{機能} のように、名前だけで役割がわかる命名規則を統一すると、スキル選定の精度が上がる。
今日からできる3つのこと
- 入口ファイルを1つ作る — プロジェクトで最も参照されるドメイン知識（DB定義、API仕様など）を1ファイルにまとめる
- 参照リストを3行だけ書く — AIに渡すプロンプトに「最初に読むファイル3つ」を追加する
- 既存の設定ファイルの名前を見直す — 名前だけで用途がわかるか？ わからなければリネームする
ルールを「書く」のが入門なら、知識を「設計する」のが次のステップだ。整理された知識構造は、スキルが増えても壊れない土台になる。
コラム: コンテキストはリポジトリに溜まる
この記事で紹介した3つの対策（SSOT、優先度付き参照、命名規則）は、すべてリポジトリに知識を蓄積するという思想に基づいている。ルールファイル、仕様書、スキル定義——これらはすべてリポジトリの中にある。AIツール（CursorやClaude Codeなど）の中には蓄積されない。
つまり、ツールを乗り換えても知識は持ち運べる。今日のツールが来年も存在する保証はないが、リポジトリに蓄積された知識は残り続ける。知識の蓄積先をリポジトリに集約する設計こそが、ツールの変化に振り回されない最善の戦略だ。
付録: 自分のリポジトリで試すプロンプト
「今日からできる3つのこと」を、もう少し具体的に。以下のプロンプトをClaude Codeにそのまま貼れば、リポジトリの現状分析から改善提案までを一気通貫で実行できる。
対策1用: 入口ファイルを作る
散らばっているドメイン知識を見つけ出し、入口ファイルの叩き台を生成するプロンプト。
このリポジトリのスキルやプロンプト定義ファイル（.claude/、.cursor/rules/、
docs/、プロジェクト固有の設定など）を探索して、以下を分析してください。
1. 複数のファイルに重複して書かれているドメイン知識（DB定義、API仕様、
ビジネスルールなど）を特定する
2. 重複が多い知識トップ3を、それぞれ「どのファイルに書かれているか」
「差異があるか」の一覧にまとめる
3. 最も重複の多い知識について、SSOT（信頼できる唯一の情報源）となる
入口ファイルのドラフトを作成する
入口ファイルは以下の構成で:
- SSOT宣言（何が正か）
- 概要（テーブル一覧やエンドポイント一覧など）
- 詳細リファレンスへのリンク
ファイルの作成前に、ドラフト内容を見せてください。対策2用: 優先度付き参照リストを追加する
プロジェクトの重要ファイルを自動で特定し、スキルに貼れる参照テーブルを提案するプロンプト。
このリポジトリの構造を分析して、AIがタスクを始める前に読むべき
「優先度付き参照リスト」を提案してください。
分析の観点:
1. 最も多くのファイルから参照・インポートされているファイルはどれか
2. プロジェクトの意思決定基準が書かれているファイルはどれか
3. ドメインモデル（型定義、DB定義）の中心となるファイルはどれか
出力形式:
| 優先度 | ファイル | 用途 | 理由 |
|--------|---------|------|------|
| 1 | ... | ... | （被参照数が最多、など） |
| 2 | ... | ... | ... |
| 3 | ... | ... | ... |
テーブルは最大5行まで。多すぎる参照リストは読まれないので、
本当に重要なものだけに絞ってください。対策3用: 命名規則の棚卸し
既存のスキルや設定ファイルの命名を監査し、改善案を出すプロンプト。
このリポジトリにあるスキル定義や設定ファイルの命名を監査してください。
対象:
- .claude/skills/ 配下のディレクトリ名
- .cursor/rules/ 配下のファイル名
- その他、AIが参照する設定ファイル
分析してほしいこと:
1. 現在の命名パターンを分類する（例: {project}-{機能}、{機能}-{対象} など）
2. 命名規則が統一されていない箇所を指摘する
3. 名前だけで用途が推測できないものをリストアップする
出力形式:
| 現在の名前 | 推測される用途 | 問題点 | 改善案 |
|-----------|-------------|--------|-------|
| ... | ... | パターン不統一 | ... |
実際のリネームは行わず、提案のみ出力してください。いずれのプロンプトも「分析結果を見せてから実行」の構成にしている。AIに渡す前に、自分の目で確認するステップを挟むのがポイントだ。