neo4j-getting-started-skill

Neo4j はじめてガイドスキル

以下の8つのステージを順番に実行し、ユーザーまたはエージェントがゼロから動作する Neo4j アプリケーションを構築できるようにガイドします。

各ステージの開始時：対応する ${CLAUDE_SKILL_DIR}/references/<stage-name>.md ファイルを読み、その指示に従ってください。現在実行中のステージだけを読み込んでください。一度にすべて読み込まないでください。

「ユーザー」とは、人間の開発者と自律型コーディングエージェントの両方を指します。

---

使用する場面

• Neo4j の新規プロジェクトをゼロから始める場合（ローカル／Docker／Aura）
• 初期設定全般：ゼロ → DB → モデル → 読み込み → アプリ
• デモや開発用の合成データを生成する場合

使用しない場面

• 既存プロジェクトでの Cypher 作成 → neo4j-cypher-skill
• ドライバーのアップグレード／Cypher の移行 → neo4j-migration-skill
• 既存 DB の管理（バックアップ、復元、インポート）→ neo4j-cli-tools-skill

---

プロジェクト構成

生成したすべてのコード、データ、スクリプト、クエリ、ノートブックは、作業ディレクトリに書き込んでください。これにより、ユーザーはセッション終了後も内容を確認し、再利用して再実行できます。出力を会話内のテキストとしてのみ生成してはいけません。必ずファイルに書き込んでください。

ファイルは以下の構成に整理します。ファイルを書き込む前にサブディレクトリを作成してください。

.env                    ← DB credentials (gitignored, loaded by python-dotenv)
aura.env                ← Aura API credentials (gitignored, never overwrite)
progress.md             ← stage-by-stage progress (this skill writes it)
requirements.txt        ← Python dependencies

schema/
  schema.json           ← graph model definition
  schema.cypher         ← DDL: constraints + indexes
  reset.cypher          ← wipe all data (keep schema)

data/
  generate.py           ← synthetic data generator  (DATA_SOURCE=synthetic)
  import.py             ← CSV/file importer          (DATA_SOURCE=csv or relational)
  *.csv                 ← any provided or generated data files

queries/
  queries.cypher        ← validated Cypher query library

scripts/
  provision_aura.py     ← Aura provisioning script (generated during provision stage)

notebook.ipynb          ← app artifact (root — standard jupyter convention)
app.py                  ← app artifact (root — streamlit run app.py)
main.py                 ← app artifact (root — uvicorn main:app)
graphrag_app.py         ← app artifact (root)

ルートレベルのファイル（.env、requirements.txt、アプリのコード）は、ツールがその場所を想定しているため、ルートに置きます。それ以外は適切なサブフォルダーに配置します。

---

進捗の追跡

このスキルは、再開できるように作業ディレクトリ内の progress.md を管理します。

起動時：

1. progress.md が存在するか確認します。
2. 存在する場合、最初の未完了ステージを見つけます。

   grep -B1 "^status: pending" progress.md | grep "^###" | head -1
   

3. そのステージから再開します。コンテキストブロック（見出しの下にある key=value の行）を読み取り、DOMAIN、USE_CASE、NEO4J_URI などを復元してください。すでに記録されている情報をユーザーに再度尋ねてはいけません。
4. 完了済みの各ステージについて、続行する前に files= 行に記載されたすべてのファイルを読みます。これらのファイルを正として扱い、記憶から内容を再構成してはいけません。
   • schema/schema.json → model、load、query、build の各ステージの前に再読します
   • queries/queries.cypher → build ステージの前に再読します
   • data/generate.py → import または reset の前に再読します
5. progress.md が存在しない場合は、0-prerequisites から開始します。

ステージ完了時 — progress.md を更新（または作成）します。

• そのステージの ### セクションがすでにある場合は、status: pending を status: done に更新し、新しい key=value 行を追加します。
• セクションがない場合は、以下の形式に従って追加します。

形式：

# Neo4j Getting-Started — Progress


### 0-prerequisites
status: done

### 1-context
status: done
DOMAIN=social
USE_CASE=friend recommendations
EXPERIENCE=beginner
DB_TARGET=aura-free
DATA_SOURCE=synthetic
APP_TYPE=notebook
EXEC_METHOD=query-api

### 2-provision
status: done
NEO4J_URI=neo4j+s://abc123.databases.neo4j.io

### 3-model
status: done
labels=Person,Post
relationships=FOLLOWS,POSTED
constraints=2

### 4-load
status: done
nodes=200 Person, 50 Post
relationships=1400 FOLLOWS, 300 POSTED

### 5-explore
status: pending

### 6-query
status: pending

### 7-build
status: pending

---

実行プロトコル

各ステージで、次の手順を実行します。

1. ステージを告知します："## Stage: <name> — <purpose>"
2. ${CLAUDE_SKILL_DIR}/references/<name>.md を読みます
3. そのファイルの指示を実行します
4. ステージの完了条件を確認します
5. status: done とステージ固有のコンテキストを使って progress.md を更新します
6. 次のステージに進みます（HITL：先に承認を得るため一時停止します）

ステージが失敗した場合は、ステージの参照ファイルにあるエラー対応の指示に従って復旧します。以下のスキップ条件で明示的に許可されている場合を除き、ステージを飛ばしてはいけません。

---

ステージ

ステージは、以下に示す番号順に実行します。スキップ条件が適用される場合を除き、各ステージは直前のステージが正常に完了していることを前提とします。各ステージに入るとき、リンク先の参照ファイルを読んでください。

0-prerequisites → 1-context → 2-provision → 3-model → 4-load → 5-explore → 6-query → 7-build

複数のステージで使用する共通機能：

• Cypher の実行：${CLAUDE_SKILL_DIR}/references/capabilities/execute-cypher.md（3つのオプション。EXEC_METHOD は context で選択）
• Cypher 作成ルール：${CLAUDE_SKILL_DIR}/references/capabilities/cypher-authoring.md（または neo4j-cypher-authoring-skill に委ねます）
• MCP の設定：${CLAUDE_SKILL_DIR}/references/capabilities/mcp-config.md（prerequisites と build で使用）
• クエリの検証：${CLAUDE_SKILL_DIR}/scripts/validate_queries.py — 1回の呼び出しですべてのクエリを一括検証します（query で使用）

0 — prerequisites

目的：何よりも先に、必要な CLI ツールを確認してインストールします。
参照：${CLAUDE_SKILL_DIR}/references/0-prerequisites.md
完了条件：neo4j-mcp バイナリにアクセスでき、.gitignore に .env のエントリがあること。
必ず実施してください。

---

1 — context

目的：ドメイン、ユースケース、経験、インフラストラクチャの対象、データソース、出力形式を収集します。Cypher の実行に使用する EXEC_METHOD を判定します。
参照：${CLAUDE_SKILL_DIR}/references/1-context.md
完了条件：DOMAIN、USE_CASE、EXPERIENCE、DB_TARGET、DATA_SOURCE、APP_TYPE、EXEC_METHOD が判明していること。
スキップ条件：すべての変数が会話のコンテキストですでに提供されている場合。

---

2 — provision

目的：稼働中の Neo4j データベースを用意し、認証情報を .env に保存します。
参照：${CLAUDE_SKILL_DIR}/references/2-provision.md
完了条件：.env に NEO4J_URI/USERNAME/PASSWORD/DATABASE が記載され、接続が確認されていること。
スキップ条件：DB_TARGET=existing → ユーザーの認証情報から .env を作成し、3-model に進みます。

---

3 — model

目的：ユースケースに適したグラフデータモデルを設計または特定します。
参照：${CLAUDE_SKILL_DIR}/references/3-model.md
完了条件：schema.json と schema.cypher が作成されていること。
スキップ条件：DATA_SOURCE=demo → デモスキーマを使用し、4-load に進みます。
HITL チェックポイント（HITL モードのみ — 自律モードでは完全にスキップしてください）：モデル案を提示し、承認を待ちます。

---

4 — load

目的：スキーマ制約を適用してから、データ（デモ、合成データ、CSV、またはドキュメント）をインポートします。
依存関係：3-model（インポートの前に制約を作成する必要があります）。
完了条件：ノード数が 50 以上で、import/ スクリプトと reset.cypher が作成されていること。

---

5 — explore

目的：グラフへの視覚的な入り口を提供します。「腑に落ちる」瞬間を生み出します。
参照：${CLAUDE_SKILL_DIR}/references/5-explore.md
完了条件：ブラウザーの URL をユーザーに表示するか、ノートブックに可視化セルを追加していること。
必須条件 — 必ず実施してください。

---

6 — query

目的：ユースケース向けの Cypher クエリライブラリを生成し、検証します。
参照：${CLAUDE_SKILL_DIR}/references/6-query.md
完了条件：queries.cypher に 5 件以上のクエリと 2 件以上のトラバーサルが含まれ、3 件以上のクエリが結果を返すこと。

---

7 — build

目的：実行可能なアプリケーション、ダッシュボード、ノートブック、またはエージェントとの連携を生成します。
参照：${CLAUDE_SKILL_DIR}/references/7-build.md
完了条件：成果物が存在し、構文チェックに合格し、ユースケースに沿った空でない結果を返すこと。

---

成功条件（7 項目すべて必須）

条件	ステージ	条件の詳細
db_running	provision	driver.verify_connectivity() が成功する
model_valid	model	ノードラベルが 2 件以上、リレーションシップタイプが 1 件以上、DB 内の制約が 1 件以上
data_present	load	MATCH (n) RETURN count(n) が 50 以上
queries_work	query	クエリが 5 件以上、トラバーサルが 2 件以上、1 件以上の結果を返すクエリが 3 件以上
graph_visible	explore	ブラウザーの URL またはノートブックの可視化をユーザーに提供する
app_generated	build	成果物が存在し、構文チェックに合格し、空でない結果を返す
integration_ready	build	要求された場合、MCP 設定またはエージェントフレームワークのコードが存在する

---

ファストパス

状況	アクション
DB_TARGET=existing	provision をスキップし、ユーザーの認証情報から .env を作成して model に進む
DATA_SOURCE=demo	カスタムモデリングをスキップし、デモスキーマを使用して load に進む
DB_TARGET=existing + データが存在する	provision、model、load をスキップし、スキーマを調査して explore に進む

---

HITL モードと自律モード

HITL（対話型）：モデルの確認のため、model の後に一時停止します。データの確認のため、load の後に一時停止します。

自律モード（CI のように、コンテキストをすべて事前に提供）：どの段階でも承認のために一時停止しません。すべての判断を自動承認し、8 つすべてのステージを直ちに進めます。ブラウザーの URL を標準出力に表示します。DB の起動から 15 分以内を目標とします。

自律モードの判定方法 — ステージ 1 の開始時に確認します：

次のいずれかに該当する場合は自律モードです：

• 最初のプロンプトに次のすべてが含まれている：DOMAIN、USE_CASE、EXPERIENCE、DB_TARGET、DATA_SOURCE、APP_TYPE（または「Domain: X, use-case: Y, ...」のような同等の表現）
• セッションが --auto-approve などの非対話型フラグを指定して開始された
• すべてのコンテキスト変数がすでに progress.md に記録されている（自律実行を再開する場合）

HITL モードの場合：ユーザーが必要なコンテキストをすべて事前に提示せず、新しい会話を開始しています。

自律モードでは：すべてのステージの参照ファイルにある HITL チェックポイントをすべて自動的にスキップします。 承認を求めてはいけません。「これでよさそうですか？」などと尋ねてはいけません。一時停止してはいけません。直ちに次のステップに進みます。

---

最終サマリー（すべてのゲート通過後に提出）

ステップ 1 — README.md を作成します。以下のテンプレートを使用して、作業ディレクトリに作成します。 progress.md と実際に生成されたファイルを参照し、すべての <placeholder> を埋めてください。 これは必須の成果物です。省略してはいけません。

重要 — ポータブルなコマンド：README.md 内の再実行コマンドには、すべて python3 を使用してください（/opt/homebrew/bin/python3.14 や /usr/local/bin/python3 などの絶対パスは使用しないでください）。README は、異なる Python 環境を使う他のユーザーと共有します。

# <DOMAIN> Graph — <USE_CASE>

A synthetic <DOMAIN> graph built with Neo4j, covering <USE_CASE>.
Generated by the neo4j-getting-started-skill on <date>.

## What's in the graph

| Label | Count | Description |
|-------|-------|-------------|
| <Label> | <N> | <one line> |

**Relationships:** <TYPE1>, <TYPE2>, ...  
**Constraints:** <N> uniqueness constraints applied

## Explore visually

Open in Neo4j Browser:
<browser_url>

Use `NEO4J_PASSWORD` from `.env` to connect, then run:
```cypher
// Starter query — shows the full graph sample
MATCH (n)-[r]->(m) RETURN n, r, m LIMIT 50

ファイル

ファイル	用途	再実行
schema/schema.json	グラフモデル	—
schema/schema.cypher	制約とインデックス	source .env && cypher-shell -a $NEO4J_URI -u $NEO4J_USERNAME -p $NEO4J_PASSWORD --file schema/schema.cypher
schema/reset.cypher	スキーマを保持してデータを消去	source .env && cypher-shell -a $NEO4J_URI -u $NEO4J_USERNAME -p $NEO4J_PASSWORD --file schema/reset.cypher
data/generate.py	合成データを再生成	source .venv/bin/activate && python3 data/generate.py
data/import.py	CSV を Neo4j に再インポート	source .venv/bin/activate && python3 data/import.py
queries/queries.cypher	クエリライブラリ	Neo4j Browser に貼り付け
<artifact>	<アプリの種類>	<実行コマンド>
requirements.txt	Python の依存関係	source .venv/bin/activate && pip install -r requirements.txt

（DATA_SOURCE=csv の場合は data/generate.py の行を省略します。DATA_SOURCE=synthetic の場合は data/import.py の行を省略します。）

アプリの実行

python3 -m venv .venv     # skip if .venv already exists
source .venv/bin/activate
pip install -r requirements.txt
<run command>

<FastAPI の場合のみ — このセクションを含めます：> インタラクティブな API ドキュメントは http://localhost:8000/docs で開きます。

< MCP 統合の場合 — APP_TYPE に mcp が含まれている場合、このセクションを含めます：>

MCP 統合

グラフを Claude から直接クエリするには：

Claude Code — mcp-claude-code.json を .claude/settings.json にコピーします：

cp mcp-claude-code.json .claude/settings.json

その後、Claude Code を再読み込みします（/reload または再起動）。「Neo4j データベースにはどのノードラベルがありますか？」と尋ねます。

Claude Desktop — mcp-claude-desktop.json を ~/Library/Application Support/Claude/claude_desktop_config.json にマージしてから、Claude Desktop を再起動します。

利用可能な MCP ツール：get-schema、read-cypher、write-cypher。

リセットと再読み込み

source .env
cypher-shell -a $NEO4J_URI -u $NEO4J_USERNAME -p $NEO4J_PASSWORD --file schema/reset.cypher
source .venv/bin/activate
python3 data/generate.py   # or skip if using your own CSVs
python3 data/import.py

サンプルクエリ

// <use-case-specific query 1 — fill in from queries/queries.cypher>
<query>

// <use-case-specific query 2>
<query>

（Cypher のコメントには -- ではなく // を使用します。）

次のステップ

• GraphAcademy で Neo4j の知識を深めましょう
• data/*.csv を編集してデータセットを変更し、data/import.py を再実行します
• モデルを拡張するには、schema/schema.json に新しいノードラベルやリレーションシップタイプを追加します

**Step 2 — print this to the conversation:**

✓ Neo4j Getting-Started — 完了

データベース： <NEO4J_URI> ブラウザー： https://browser.neo4j.io/?connectURL=

── 生成されたファイル（これらのファイルは保持してください） ─────────────────────── schema/schema.json グラフモデルの定義 schema/schema.cypher 制約／インデックスを再適用： cypher-shell ... --file schema/schema.cypher schema/reset.cypher スキーマを保持してデータを消去： cypher-shell ... --file schema/reset.cypher data/generate.py 合成データを再生成： source .venv/bin/activate && python3 data/generate.py data/*.csv ソースデータファイル — 編集してデータセットを変更 data/import.py CSV から再インポート： source .venv/bin/activate && python3 data/import.py queries/queries.cypher クエリライブラリ — Neo4j Browser に貼り付けるか、cypher-shell で実行 requirements.txt 依存関係をインストール： source .venv/bin/activate && pip install -r requirements.txt

── ゲート ─────────────────────────────────────────────────────── db_running ✓ model_valid ✓ data_present ✓ queries_work ✓ graph_visible ✓ app_generated ✓ integration_ready ✓/–

── 次のステップ ──────────────────────────────────────────────────

• 確認： Browser の URL を開く → MATCH (n)-[r]->(m) RETURN n,r,m LIMIT 50 を実行
• 反復： data/*.csv を編集 → source .venv/bin/activate && python3 data/import.py（先にリセット）
• 学習： https://graphacademy.neo4j.com

Omit lines that don't apply (e.g. omit `data/import.py` when `DATA_SOURCE=synthetic`,
omit `data/generate.py` when `DATA_SOURCE=csv`).

---

## Checklist

- [ ] Prerequisites met (Docker/Python/Java; Aura API key if cloud)
- [ ] DB reachable — `RETURN 1` in cypher-shell
- [ ] Constraints + indexes ONLINE before data load
- [ ] Data loaded — `MATCH (n) RETURN count(n)` > 0
- [ ] queries.cypher: all queries return expected results
- [ ] App/notebook runs end-to-end
- [ ] `.env` gitignored; credentials not hardcoded