AI 連携 — Claude Code から PieceLOD を使う

PieceLOD 上の設計データ（概念・構成・機能・データモデル・ER・ユースケース・用語集と、それらを結ぶ線）は、すべて HTTP API (/api/v1/*) 経由で AI コーディングアシスタントから読み書きできます。このページの設定をコピペするだけで、Claude Code などの AI が PieceLOD に接続できるようになります。

2つの使い方

PieceLOD 単体で使う

下のブロックを CLAUDE.md にコピペし、AI に PieceLOD のプロジェクト URL を渡すだけで始められます。AI が既存コードを解析して設計マップを起こす・設計を読んで実装するといった作業がすぐに可能です。

PieceDev と組み合わせて使う

PieceDev のタスクを進めている AI が、対象プロジェクトの現状設計を PieceLOD から取得し、実装後の構造変更を PieceLOD へ書き戻せます。PieceDev 側の接続設定に加えて、下のブロックも CLAUDE.md に併記してください。

CLAUDE.md にコピペする設定

以下のブロックをそのまま CLAUDE.md に追加してください。AI に PieceLOD の URL を渡すと、この設定に従って自動的に接続します。

## PieceLOD 接続（Device Auth 方式）

PieceLOD URL（https://lod.piecedev.com/projects/...）を渡された場合、以下のフローで接続する:

1. URL から projectId を抽出
2. 認証開始（Bearer 不要）:
   curl -s -X POST https://lod.piecedev.com/api/device-auth/start \
     -H 'Content-Type: application/json; charset=utf-8' \
     --data-binary @- <<'JSON'
   {"projectId":"<projectId>"}
   JSON
   → deviceCode, userCode が返る
3. ユーザーに userCode（6桁）を伝え、https://lod.piecedev.com/device で入力してもらう
4. 重要: すぐにポーリングしない。「認証が完了したら教えてください」と伝えて返答を待つ
5. ユーザーの返答後、3秒間隔で poll:
   curl -s -X POST https://lod.piecedev.com/api/device-auth/poll \
     -H 'Content-Type: application/json; charset=utf-8' \
     --data-binary @- <<'JSON'
   {"deviceCode":"<deviceCode>"}
   JSON
   → status: "approved" で apiKey が返る
6. 以降の操作はすべて Authorization: Bearer <apiKey> を付けた https://lod.piecedev.com/api/v1/* で行う。
   DB への直接続（psql / SQL 直叩き）は禁止。API が唯一の正規経路。
7. 最初に必ず以下を読む。以降の操作方法（シナリオ・API 仕様）はすべて自己記述されている:
   curl -s -H "Authorization: Bearer <apiKey>" https://lod.piecedev.com/api/v1/help/guide
   curl -s -H "Authorization: Bearer <apiKey>" https://lod.piecedev.com/api/v1/help/task-flow
   - GET https://lod.piecedev.com/api/v1/help/scenario/<key> : シナリオ別の作業手順
   - GET https://lod.piecedev.com/api/v1/help/api/<name>     : 各 API の仕様
8. JSON Body を送る時は必ず上記の形式（--data-binary @- + シングルクォート heredoc +
   Content-Type: application/json; charset=utf-8）を使う。-d 'インライン JSON' は
   Windows の CP932 シェルで文字化けするため禁止。

コピペ後の注意

  • CLAUDE.md の置き場所に注意してください。開発プロジェクトのソースツリー直下に置くのが一番確実です。ユーザーホームディレクトリ（~/.claude/CLAUDE.md）や、プロジェクトの一つ上のディレクトリに置く運用もあります（違いは AI に聞くと詳しく教えてくれます）。
  • コピペした後、VSCode を再起動するか、Claude Code のチャットタブを新しく開かないと設定が認識されません。

接続の流れ

  1. 1

    AI にプロジェクト URL を渡す

    「これを進めたい」程度のメッセージと一緒に、PieceLOD のプロジェクト URL を AI に渡します。AI が Device Auth を開始し、6桁の認証コードを表示します。

  2. 2

    ブラウザで承認する

    AI が案内する /device ページを開き、6桁コードを入力して承認します。認可はプロジェクト単位で、発行された API キーはそのプロジェクトにしかアクセスできません。

  3. 3

    AI に「認証した」と伝える

    AI が API キーを取得し、利用ガイド (GET /api/v1/help/guide) と作業インデックス (GET /api/v1/help/task-flow) を読み込んで作業を開始します。

AI は何を参照して動くのか

接続後の操作方法は、すべて PieceLOD 自身の help API が AI に直接教えます。人間がこのページで API 仕様を覚える必要はありません。

  • GET /api/v1/help/guide — 概念モデル・レイヤー体系・線種マトリクス・モデリング規約・完全性チェックリストを含む利用ガイド全文
  • GET /api/v1/help/task-flow — シナリオ（設計理解 / コード反映 / 一括投入 / 細粒度編集など）と API 一覧のインデックス
  • GET /api/v1/help/scenario/{key} ・ GET /api/v1/help/api/{name} — 個別の手順・仕様の詳細

読み書きの実体は /api/v1/projects/{projectId} 配下の REST API（summary / layers / pieces / relations / bulk PUT など）です。いずれも Bearer 認可付きで、API キーの確認・取り消しはプロジェクト設定からいつでも行えます。