Claude Code の Skills アーキテクチャで GIS プロダクト開発を加速する
はじめに
AI コーディングアシスタントを使ったプロダクト開発で、こんな経験はありませんか？
- 「このプロジェクトでは PostGIS を使っている」と毎回説明する
- 前回のセッションで解決した問題を、次のセッションで同じ AI が再び間違える
- コードベースが育つにつれて、AI が読むべきファイルを見つけるまでの探索時間が増える
これらはすべて コンテキスト問題 です。AI エージェントはセッションを跨いで記憶を持たず、毎回ゼロからプロジェクトを理解する必要があります（いわゆる「コールドスタート」）。
この記事では、GIS ベースの不動産分析サービス（Python + React + PostGIS、50万行以上）の開発で、Claude Code の Skills アーキテクチャを活用してコンテキスト問題を体系的に解決した実践記録を紹介します。
コンテキスト問題の構造
コールドスタートコスト
AI エージェントが新しいセッションでタスクに着手するまでに消費するトークンを「コールドスタートコスト」と呼びます。
プロジェクトが小さいうちは B→F が数秒で完了しますが、コードベースが成長するにつれて D（探索）のコストが爆発的に増加します。50万行規模では、何の指針もなく探索すると 100K トークン以上を消費することがあります。
3つの非効率パターン
| パターン | 原因 | 結果 |
|---|---|---|
| 広域探索 | AI が関連ファイルの場所を知らない | Glob/Grep を 10回以上繰り返す |
| 情報不足による誤判断 | プロジェクト固有の制約を知らない | 破壊的変更・既存パターン無視 |
| 繰り返し学習 | 前回の失敗が次回に伝わらない | 同じ過ちを複数セッションで反復 |
Skills アーキテクチャ
設計原則
Claude Code には CLAUDE.md（プロジェクト指示書）と .claude/skills/（スキルファイル）の仕組みがあります。この階層構造を利用して、ルーティング型のコンテキスト供給を設計します。
核心思想：AI は全ファイルを読む必要はない。タスク種別に応じて「読むべきファイル」だけを正確に供給する。
L0: 入口（CLAUDE.md）
プロジェクトルートの CLAUDE.md は AI が最初に読むファイルです。ここに配置するのは：
- 約束事（コーディング規約、禁止事項）
- タスクルーティング表（タスク種別 → 必読ファイルのマッピング）
- 変更してはいけないもの（コア競争力のアルゴリズム等）
ルーティング表の例：
| タスク種別 | 必読 | 按需読 |
|---|---|---|
| データ導入 | skills/data-import-checklist.md | DATA.md |
| フロント修正 | frontend/CLAUDE.md | skills/react-best-practices.md |
| DB マイグレーション | skills/production-db-migration.md | scripts/migration/ |
| 分析 API 修正 | src/api/routes/analysis_v2.py | ARCHITECTURE.md |
これにより、AI はタスクに無関係なファイルを読まずに済みます。
L2: Skills（操作手順）
Skills は再利用可能なワークフローを定義するファイルです。知識の参考文献（docs）とは明確に区別します。
| 特徴 | Skill（.claude/skills/） |
Doc（.claude/docs/） |
|---|---|---|
| 内容 | チェックリスト、操作手順 | 知識、アーキテクチャ解説 |
| 使い方 | ステップを順に実行 | 必要時に参照 |
| 更新頻度 | 操作変更時 | 知識更新時 |
Skill の構造テンプレート
実戦で収束した Skill ファイルの構造:
# タスク名
> **目的**：一文で説明
> **引用**：被誰引用 / 引用誰
## チェックリスト
### 事前確認
- [ ] 条件A を満たしているか
- [ ] 条件B を確認したか
### 実行手順
1. ステップ1
2. ステップ2（**人間確認必要**）
3. ステップ3
### 事後検証
- [ ] 結果A を確認
- [ ] 結果B を検証実践：GIS プロダクトでの適用
データ導入の Skill 群（5ファイル連携）
GIS プロダクトでは、異なるデータソース（OpenStreetMap、国土数値情報、e-Stat 等）から空間データを取り込む作業が頻発します。各データソースの API 仕様、座標系、フィールド名が異なるため、手順を標準化する必要がありました。
5つの Skill ファイルを連携させる設計：
| ファイル | 役割 | 行数 |
|---|---|---|
| checklist | 導入前・中・後の確認項目 | ~300 |
| execution | バッチ処理・トランザクション制約 | ~430 |
| methods | データソース別コマンド一覧 | ~530 |
| architecture | 基底クラスと拡張パターン | ~330 |
| pitfalls | 過去の失敗と対策 | ~210 |
合計 ~1,800 行ですが、ルーティング表によって AI は checklist から入り、必要に応じて他のファイルへジャンプします。全部読む必要はありません。
効果測定
Skills 導入前後で、データ導入タスクのコンテキスト消費量を比較:
| 指標 | 導入前 | 導入後 | 改善 |
|---|---|---|---|
| 探索トークン（Glob/Grep） | ~30K | ~5K | -83% |
| 誤操作（ロールバック回数） | 平均 1.2回/タスク | 0.1回/タスク | -92% |
| コールドスタート→実作業 | ~3分 | ~30秒 | -83% |
ドキュメント健全性の維持
膨張問題
Skills を運用すると、2つの膨張リスクが発生します：
- CLAUDE.md の肥大化：便利なので何でも書き足してしまう
- Skill 間の重複：似たトピックの Skill で同じ情報を二重記述
対策ルール
| ルール | 閾値 | アクション |
|---|---|---|
| 単一ファイル行数 | > 500行で評価 | 拆分 or 構造索引を追加 |
| CLAUDE.md 行数 | ≤ 450行 | 超過した情報を skill/docs へ移動 |
| 重複検出 | 同一情報が2箇所以上 | 権威ソースを1つに統一 |
| 持続更新型ファイル | 作成時 | 文書ヘッダー（目的・構造・更新ルール）必須 |
使用駆動の最適化
静的なルール（上記）だけでは構造的問題を見つけられません。実タスクを通じてフィードバックを蓄積する仕組みを併用します。
タスク後のシグナル記録（実際に「遠回りした」と感じた時のみ）：
| シグナル | 意味 | 対策 |
|---|---|---|
| 遠回り | ルーティング表が指すファイルに必要な情報がなかった | ルーティング修正 |
| 往復参照 | 2ファイル以上を行き来して初めて理解できた | マージ or サマリー追加 |
| 無用な読込 | ルーティング表の「必読」だが実際は不要だった | 必読→按需に降格 |
36 Skills の分類体系
最終的に収束した Skill の分類：
| カテゴリ | 件数 | 例 |
|---|---|---|
| データ導入 | 8 | チェックリスト、OSM 専用手順 |
| DB・マイグレーション | 2 | 本番 DB 手順、開発 DB ワークフロー |
| 分析・最適化 | 6 | メッシュ最適化、Tile 完備性検査 |
| フロントエンド | 4 | UI ガイドライン、バンドル監査 |
| デプロイ・運用 | 3 | 本番デプロイ、インフラ監査 |
| コンテンツ・法務 | 3 | 日本語文案チェック、法的文書審査 |
| ドキュメント管理 | 4 | CHANGELOG ワークフロー、文書精簡 |
| テスト・検証 | 2 | ブラウザ検証、API テスト方法論 |
| マーケティング | 4 | ブログ執筆、リリースツイート |
命名規則：{動詞/名詞}-{対象}-{形式}.md（例: data-import-checklist.md, deploy-to-production.md）
GIS プロダクト特有の考慮点
GIS ドメインでは、以下の理由から Skills の効果が特に大きいです：
1. データソースの多様性
一般的な Web アプリケーションは 1-2 種類のデータストアを扱いますが、GIS プロダクトは 10 種類以上のデータソースを統合します。各データソースの API 仕様・座標系・ライセンス条件をすべて AI が「知っている」状態にするには、構造化されたドキュメントが不可欠です。
2. 空間計算の非直感性
ST_Contains と ST_Intersects の使い分け、SRID の変換、球面距離と平面距離の違いなど、空間計算には直感に反するトラップが多数あります。これらを Skill の「踏坑経験」セクションに蓄積することで、AI が同じ過ちを繰り返すのを防止します。
3. パフォーマンスの臨界点
空間インデックスの有無で 100 倍以上のクエリ速度差が出るため、「この関数を使うときは必ず GIST インデックスを確認」といった制約を Skill に明記することが、本番障害の予防になります。
まとめ
Claude Code の Skills アーキテクチャは、以下の問題を構造的に解決します：
- コールドスタートコスト：タスクルーティング表で「読むべきファイル」を即座に特定
- 知識の揮発：セッションを跨ぐ経験を Skill ファイルに永続化
- プロジェクト固有の制約：コーディング規約・禁止事項を強制力のあるドキュメントとして配置
50万行規模の GIS プロダクトでの実測では、コンテキスト探索コスト 83% 削減、操作ミス 92% 削減を実現しました。
ポイントは「全部書く」ことではなく、ルーティングで必要最小限のコンテキストを正確に供給する ことです。AI は賢いので、正しいファイルさえ渡せば、あとは自分で理解して作業を進めてくれます。
この記事は、筆者が個人開発の GIS スタートアップで Claude Code を日常的に利用する中で体系化した手法に基づいています。Claude Code は Anthropic が提供する CLI ベースの AI コーディングアシスタントです。
