novel-jp/learn-setup

/learn-setup — セットアップと初体験（00-01）

Claude Code + ProjSight の環境構築と最初の操作体験を 対話的に ガイドします。 各ステップの完了を確認してから次に進んでください。

所要時間: 20〜45 分（環境によって変動） 前提: Claude Code がインストール済みであること

---

Step 1: 環境確認

「Claude Code は正常に動作していますか？このメッセージが見えていれば OK です。」

ProjSight MCP Server の接続確認:

1. list_orgs() を実行

Org（組織） とは、あなたが所属する会社やチームの単位です。ProjSight ではプロジェクトは Org の中に作られます。

2. 結果を確認:
   • Org が表示された場合 → 「接続確認 OK です。以下の Org が見えています:」と一覧表示。学習用 Org を特定する（Org が複数ある場合は、Org 名に「学習」「learn」等を含むものを優先。判断できない場合は受講者に「どの Org を学習用に使いますか？」と確認する）
   • エラーまたは空の場合 → 「MCP 接続の設定が必要です。メンターに確認してください。claude mcp auth コマンドで認証を設定できます。」

学習用プロジェクトがまだ存在しない場合（メンターが不在でセルフサービスで始めたい場合）:

「学習用プロジェクトがまだない場合は、自分で作成することもできます:
create_project(orgId, name: 'ProjSight 学習', description: 'ProjSight 学習カリキュラム用プロジェクト')
作成後、次のステップに進みましょう。」

---

Step 2: プロジェクト確認

直前の会話で get_project_context の結果が表示済みの場合は再取得せず、「先ほど確認したプロジェクトの情報を読み解いてみましょう。」と切り替える。

未取得の場合のみ:

1. list_projects() で学習用プロジェクトを特定
2. get_project_context(projectId) でプロジェクト状態を取得

エージェントへの注意: get_project_context の返却値は生 JSON をそのまま見せず、重要フィールドのみ抜粋して自然言語で説明 すること。具体的には counts（タスク数・成果物数）と alerts の有無を伝えれば十分。

いずれの場合も、以下を説明:

「これがあなたの学習プロジェクトです。
プロジェクト ID は `<projectId>` です。この ID は後のステップで使いますので覚えておいてください。

学習プロジェクトは独立したプロジェクトとして作成されており、本番プロジェクトのデータには一切影響しません。自由に操作して構いません。

表示されている情報のうち、まず覚えるのは 2 つだけです:
- **タスク**: 作業の単位。演習ごとにタスクが作られます
- **成果物**: タスクをグループ化したもの。紐づくタスクの進捗率が自動計算される点が特徴です

他にも DR・リスク・Issue・質問といった項目がありますが、これらは後の演習で 1 つずつ学びます。
今は気にしなくて大丈夫です。」

プロジェクトが見つからない場合:

• 「学習用プロジェクトが見つかりません。メンターに学習プロジェクトへの招待を依頼するか、Step 1 の案内に従って自分で作成してください。」

---

Step 2.5: Web UI ログイン確認

「ProjSight は『AI が入力 / Web が出力』のツールです。
CLI（Claude Code）から操作した結果を Web UI で確認できます。
ここで先に Web UI にログインしておきましょう。

👉 https://projsight.com にアクセスしてログインしてください。
   - メンターから招待メールが届いている場合 → メール内のリンクからログインできます
   - 招待メールが見当たらない場合 → メンターに ProjSight への招待を依頼してください
   - 初回ログイン時はパスワード設定が必要です。画面の案内に従って設定してください

ログインできたら教えてください。
（Web UI の確認は後のステップでも使います。今ログインしておくとスムーズです）」

受講者がログインできたら次に進む。Web UI が使えない場合は「CLI のみで学習を進めることもできます。後のステップで Web UI の代わりに list_tasks で確認します」と案内して次へ。

---

Step 3: GitHub リポジトリの確認

学習用リポジトリ learn-projsight が Web ガイドのセットアップで作成済みか確認する。

1. 現在のディレクトリを確認し、3 パターンで分岐:

   A) learn-projsight リポジトリ内にいる場合 → 「リポジトリ確認 OK です。」と伝えて次へ進む

   B) 別のリポジトリ（例: ProjSight 本体リポ）にいる場合 → 以下を案内:

   「現在は [リポ名] で作業しています。学習用には別リポジトリ learn-projsight を使うことを推奨しますが、
   このリポジトリでも学習を進められます。今回はこのまま続けましょう。
   
   ⚠️ このリポジトリの CLAUDE.md には本番プロジェクトの projectId が設定されています。
   CLAUDE.md は変更しません。学習の操作では学習プロジェクトの ID（`<Step 2 で確認した projectId>`）を明示的に指定して進めます。
   これにより本番プロジェクトに学習タスクが作成されることはありません。
   
   （本格的な学習を始める際は、learn-projsight リポジトリを作成することをお勧めします）」
   

   エージェントへの注意（パターン B）: Step 4 以降のすべての MCP 呼び出しで、CLAUDE.md の projectId ではなく Step 2 で確認した学習プロジェクトの projectId を明示的に使用すること。受講者にも「学習プロジェクト ID を指定しています」と都度伝える。

   → スキップ理由を明示して次へ進む

   C) リポジトリ外、または learn-projsight が未作成の場合 → 作成をガイド:

「learn-projsight リポジトリを作成しましょう。」

まず gh CLI が使えるか確認する。gh --version を実行し:

• 成功した場合 → そのまま以下を実行:

gh repo create learn-projsight --private --clone
cd learn-projsight
git checkout -b main 2>/dev/null || true

• gh が見つからない場合 → 以下を案内:

「GitHub CLI（gh）がインストールされていません。以下のいずれかで対応してください:

**方法 1: gh CLI をインストールする（推奨）**
brew install gh && gh auth login
インストール後、もう一度このステップを進めます。

**方法 2: GitHub Web UI から手動作成する**
1. https://github.com/new にアクセス
2. リポジトリ名: learn-projsight、Private を選択して作成
3. 作成後、ターミナルで以下を実行:
   git clone https://github.com/[あなたのユーザー名]/learn-projsight.git
   cd learn-projsight

どちらの方法で進めますか？」

CLAUDE.md が未設定の場合は、学習プロジェクト ID を使用して作成する:

## ProjSight

- **プロジェクトID**: `<学習プロジェクトの ID>`

ProjSight MCP ツールを呼び出す際は、上記の projectId を使用すること。

git add . && git commit -m "docs: CLAUDE.md with ProjSight project ID" && git push -u origin main

---

Step 4: 成果物の確認と最初のタスク作成

まず、タスクの紐づけ先となる 成果物（deliverable） を確認する。

1. list_deliverables(projectId) で成果物一覧を取得
2. 「セットアップ」に該当する成果物があればそれを使う
3. なければ upsert_deliverable(projectId, title: "00 セットアップ", description: "環境構築と初回体験の記録") で作成

「ProjSight では、タスクは必ず『成果物（deliverable）』に紐づけます。
成果物はタスクをグループ化したもので、紐づくタスクの進捗率が自動計算されます。

学習用の成果物『00 セットアップ』を用意しました。
ここに最初のタスクを作っていきます。」

エージェント内部参照（以下は受講者には表示しないでください）: 各セクションの演習タスクは、以下の成果物に紐づけてください。 演習を始める際に対応する成果物がなければ upsert_deliverable で作成します。

| セクション | 成果物タイトル | | ------------------- | ------------------------------ | | 00 セットアップ | 00 セットアップ | | 01 Prompt Craft | 01 Prompt Craft | | 02 Context Eng. | 02 Context Engineering | | 03 Intent Eng. | 03 Intent Engineering | | 04 Spec Eng. | 04 Specification Engineering | | 05 AI Collab | 05 AI Collaboration | | 06 Git Workflow | 06 Git Workflow | | 07 模擬プロジェクト | 07 模擬プロジェクト |

次に、受講者に最初のタスクを作ってもらう。テーマを選択させる:

「ProjSight での最初の操作として、タスクを 1 つ作ってみましょう。
以下からテーマを選んでください:

A) 自己紹介 — 名前・チーム・学習目標を記録する
B) 開発環境の記録 — 使用ツール・エディタ・言語バージョンなどを記録する
C) チームの課題メモ — 今チームで感じている課題を 1 つ記録する

どれでも構いません。自由に選んでください。」

受講者がテーマを選んだら、テーマに応じた質問をする:

• A) 自己紹介の場合:

  「以下の情報を教えてください:
  1. あなたの名前
  2. 所属チーム（または活動領域）
  3. この学習で身につけたいこと」
  

• B) 開発環境の記録の場合:

  「以下の情報を教えてください:
  1. メインのエディタ / IDE
  2. よく使うプログラミング言語
  3. 開発環境で工夫していること」
  

• C) チームの課題メモの場合:

  「以下の情報を教えてください:
  1. どんな課題か（一言で）
  2. なぜ課題だと感じるか
  3. 理想の状態」
  

受講者の回答を受けて:

1. 作成内容を 実行前に 受講者に見せる:

「以下の内容でタスクを作成します:

- タイトル: [テーマに応じたタイトル]
- 紐づけ先: 00 セットアップ
- 説明: [構造化した内容のプレビュー]

💡 説明は「背景・対応内容・完了条件」の構造で書いています。
この構造は AI がタスクを実行する際に参照するためのものです。
ProjSight が AI ネイティブである理由の一つ — AI が読みやすい形式で記録することで、後から AI に作業を依頼する際にそのまま使えます。

作成してよいですか？」

2. 受講者の承認を得てから upsert_task(projectId, title, deliverableId, description) を実行
   • title: テーマに応じたタイトル（例: 自己紹介: [名前]、開発環境: [エディタ名]、課題メモ: [課題の一言]）
   • deliverableId: Step 4 冒頭で確認/作成した成果物の ID
   • description: 受講者が入力した内容を Markdown で構造化

テーマ A の場合の description 例:

## 背景

学習カリキュラムの最初のステップとして、自己紹介タスクを作成する。

## 自己紹介

- **名前**: [名前]
- **チーム（活動領域）**: [チーム名]
- **学習目標**: [目標]

## 完了条件

- [ ] 自己紹介が ProjSight に記録されている
- [ ] start_work / complete_work を体験した

3. 作成されたタスクを受講者に見せる: 「タスクが作成されました！タスク番号は #XX です。成果物『00 セットアップ』に紐づいています。」

---

Step 5: ProjSight ワークフロー体験

「次に、ProjSight のワークフローを体験しましょう。
ProjSight では、タスクを開始するときに start_work、完了するときに complete_work を実行します。

まず start_work を実行します。実行してよいですか？」

エージェントへの注意: このステップでは MCP ツールの start_work / complete_work を 直接 使用すること。/start-task スキルは使わない。/start-task は DR・Issue・Risk との紐づけや設計ドキュメントの影響確認まで自動で行う本番用のスキルであり、この演習の趣旨（基本操作の体験）には過剰。

5a: start_work

受講者の承認を得てから:

1. start_work(taskId) を実行
2. 返却されるコンテキストの読み方を説明:

「start_work を実行すると、以下の情報が自動的に返ってきます:

- プロジェクトの状態（タスク数、リスク数、アラート）
- 関連する成果物の進捗
- アクティブなフェーズ情報

これは **Context Engineering** という仕組みの一例です。
AI が作業に必要な情報を、呼び出すだけで自動的に受け取れるようになっています。
これは Section 02（/learn-ce-analyze）で詳しく学ぶ概念です。今は『start_work するだけで必要な情報が揃う仕組み』とだけ覚えてください。」

5b: Web UI で確認

start_work と complete_work の間に、受講者自身に状態を確認してもらう。

「ここで、今の状態を自分の目で確認してみましょう。

先ほどログインした Web UI をもう一度開いてください。
👉 https://projsight.com で自分のプロジェクトを開いてみてください。
タスク #XX が「進行中」になっているはずです。

確認できたら教えてください。
（Web UI が使えない場合は、list_tasks を実行して確認することもできます）」

受講者が確認できたら、または list_tasks での確認を希望した場合は list_tasks(projectId) を実行して結果を見せる。

5c: complete_work

「状態が確認できましたね。では、タスクを完了しましょう。
complete_work を実行してよいですか？」

受講者の承認を得てから complete_work(taskId) で完了:

「タスクを完了しました！
complete_work を実行すると:
- タスクの status が completed に変わる
- 完了日時が記録される
- 進捗率が 100% に自動更新される
- 成果物の進捗率が自動計算される

この start → 作業 → complete のサイクルが ProjSight の基本です。

もう一度 Web UI を見てみましょう。完了したタスクはデフォルトでは非表示になります。
『完了タスク (1) 非表示中』というボタンが表示されているはずです。
クリックすると、完了したタスクと成果物の進捗率の変化を確認できます。」

---

Step 6: 完了メッセージ

「🎉 セットアップ完了！

今回学んだこと:
- ProjSight への接続と基本操作
- 成果物（deliverable）とタスクの関係
- タスクの作成（upsert_task）と成果物への紐づけ
- ワークフロー（start_work → 作業 → complete_work）
- Context Engineering の考え方に触れた（AI に自動的にコンテキストを渡す仕組み — 後の演習で深掘り）
- 『AI が入力 / Web が出力』— CLI で操作し、Web UI で確認するサイクル

次は /learn-pc-compare で Prompt Craft の演習を始めましょう。
「曖昧な指示」と「構造化された指示」で AI の出力がどう変わるかを体感します。」

---

エラー時のリカバリー

| エラー | 対応 | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | MCP 接続失敗 | 「claude mcp auth を実行して認証を設定してください。認証 URL が分からない場合は、メンターに ProjSight の MCP 認証情報を確認してください。」 | | gh CLI 未インストール | 「GitHub CLI がインストールされていません。brew install gh && gh auth login でインストール・認証するか、GitHub Web UI（https://github.com/new）からリポジトリを手動作成してください。」 | | プロジェクトが見つからない | 「メンターに学習プロジェクトへの招待を依頼するか、create_project で自分で作成してください」 | | 権限エラー | 「プロジェクトへのアクセス権限がありません。メンターに確認してください」 | | 成果物が見つからない | list_deliverables で適切な成果物を検索。なければ「セットアップ」で作成 | | Web UI にログインできない | 「メンターからの招待メールを確認してください。見当たらない場合はメンターに再送を依頼してください。」 |