Setup Guide

購入後のセットアップガイド

本ガイドの展開方法と利用開始手順を解説します。
購入ありがとうございます。以下の手順で、すぐにご利用いただけます。

1. 利用方法の選択

本ガイドは静的HTMLサイト + mdファイル群で構成されています。以下の3つの方法で利用できます。

方法対象者メリット必要なもの
A. IIS / Webサーバー配信 社内チームで共有する場合 全機能が完全に動作。ZIPダウンロード、検索、全て対応 Windows Server + IIS（または Apache/Nginx）
B. 直接ファイル閲覧 個人で素早く使いたい場合 セットアップ不要。ZIPを展開してindex.htmlを開くだけ ブラウザのみ
C. VS Code Live Server 開発者が個人で使う場合 ローカルWebサーバーで全機能が動作 VS Code + Live Server拡張
推奨： チームで利用する場合は方法A（IIS配信）を推奨します。 個人利用なら方法C（VS Code Live Server）が最も手軽です。

2. 方法A: IIS（Internet Information Services）で配信

社内のWebサーバーでホストし、チーム全員がブラウザからアクセスできるようにする方法です。

Step 1: ZIPを展開

  1. 購入時にダウンロードしたZIPファイルを、サーバー上の任意のフォルダに展開します
    例: C:\inetpub\wwwroot\ai-agent-guide\
  2. 展開後、フォルダ内に index.html が存在することを確認します

Step 2: IISサイトの作成

  1. IISマネージャーを開く（Windows検索で「IIS」と入力）
  2. 左ペインの「サイト」を右クリック → 「Webサイトの追加」
  3. 設定を入力:
    項目設定値（例）
    サイト名AI-Agent-Guide
    物理パスC:\inetpub\wwwroot\ai-agent-guide
    バインドhttp / ポート 8080（または任意）
    ホスト名空欄（社内のみ）
  4. 「OK」をクリックしてサイトを作成

Step 3: 動作確認

  1. ブラウザで http://localhost:8080/ にアクセス
  2. トップページが表示されることを確認
  3. ヘッダーの検索バーで「プロンプト」と入力し、検索が動作することを確認
  4. プロンプト集ページでZIPダウンロードが動作することを確認
web.config について： 本ガイドには web.config が同梱されています。 .md ファイルと .json ファイルのMIMEタイプが設定済みのため、追加設定は不要です。

Step 4: チームへの共有

  1. サーバーのIPアドレスまたはホスト名を確認
    例: http://192.168.1.100:8080/
  2. チームメンバーにURLを共有
  3. ブックマークを推奨する旨を伝達
セキュリティ注意： 本ガイドは社内ネットワーク内での配信を想定しています。 インターネットに公開しないでください（利用規約で転売・再配布は禁止されています）。 必要に応じてWindows認証やIP制限を設定してください。

3. 方法B: 直接ファイル閲覧（最もシンプル）

セットアップ不要。ZIPを展開して index.html をダブルクリックするだけです。

  1. ZIPファイルを任意のフォルダに展開
  2. index.html をダブルクリックしてブラウザで開く
  3. HTMLページの閲覧、mdファイルの参照はそのまま利用可能
制限事項（file://プロトコルの制約）：
  • ZIPダウンロード機能は初回に「フォルダ選択」ダイアログが表示されます。ルートフォルダを選択してください
  • 全文検索は正常に動作します（search-data.jsに埋め込み済み）
  • 仕様書サンプルのダウンロードリンクは直接クリックで開けます
すべての機能を制約なく使いたい場合は、方法AまたはCを推奨します。

4. 方法C: VS Code Live Server（開発者向け推奨）

VS Codeの拡張機能で手軽にローカルWebサーバーを起動する方法です。

  1. VS Codeで拡張機能「Live Server」（ritwickdey.LiveServer）をインストール
  2. 展開したフォルダをVS Codeで開く（File → Open Folder）
  3. index.html を開いた状態で、右下の「Go Live」ボタンをクリック
  4. ブラウザが自動で開き、http://127.0.0.1:5500/ でサイトが表示される
  5. 全機能（検索、ZIPダウンロード、仕様書サンプル）が動作することを確認
VS Code Live Serverのメリット： IISのセットアップが不要で、5秒で起動。 mdファイルの編集結果もリアルタイムで反映されるため、テンプレートのカスタマイズ時にも便利。

5. mdファイルの使い方

本ガイドの核心はmdファイル群です。AIツールに読ませることで、高品質なコードを生成させます。

基本的な使い方

  1. プロンプト集ページから、言語×FW×DBを選択してZIPダウンロード
  2. ZIPを展開し、プロジェクトの rules/ ディレクトリに配置
  3. project_info.md をプロジェクト固有の情報に書き換え
  4. coding_rules.md をチームの規約に合わせてカスタマイズ
  5. AIツールでセッションを開始し、「rules/ 配下のファイルを読んでください」と指示

ツール別の読ませ方

ツール読ませ方
GitHub Copilot @workspace で自動参照。または #file:rules/project_info.md で個別指定
Claude Code プロジェクトディレクトリで claude を起動すれば自動認識。CLAUDE.md に参照指示を書くとより効果的
Amazon Q VS Codeで開いたワークスペース内のファイルを参照。Chatで rules/project_info.md を参照して と指示

6. フォルダ構成

ai-agent-guide/ ├── index.html ← トップページ（ここを開く） ├── 02_overview.html ← Agent開発 概論 ├── 05_newdev.html ← 新規開発ガイド ├── 07_maintenance.html ← 保守開発ガイド ├── 06_languages.html ← 言語別ガイド ├── 03_ai_tools.html ← AIツール別ガイド ├── 08_operations.html ← 運用保守ガイド ├── 09_extra.html ← 番外編（事務テンプレート） ├── 04_prompts.html ← プロンプト集 + ZIPダウンロード ├── 01_handson.html ← ハンズオン（事務/開発2トラック） ├── glossary.html ← 用語集 ├── search.html ← 全文検索 ├── terms.html ← 利用規約 ├── setup_guide.html ← このページ ├── style.css ← スタイルシート ├── web.config ← IIS設定（MIMEタイプ定義済み） ├── search-data.js ← 検索インデックス ├── md_templates/ ← mdファイル群（本体） │ ├── common/ ← 共通テンプレート（21事務+運用+ルール） │ ├── java/ ← Java（5FW × 3DB） │ ├── csharp/ ← C#.NET（2FW × 3DB） │ ├── vbnet/ ← VB.NET（2FW × 3DB） │ ├── aspnet/ ← ASP.NET Core（2FW × 3DB） │ ├── typescript/ ← TypeScript（React × 3DB） │ ├── migration/ ← マイグレーション（17シナリオ） │ └── tools/ ← AIツール別ガイド（3ツール+共通） ├── docsSamples/ ← 仕様書作成サンプル └── handson_samples/ ← ハンズオン素材

7. プロジェクトへの適用手順

購入後、実際のプロジェクトに適用するまでの推奨手順です。

  1. ハンズオンで体験 — まず01_handson.htmlで事務トラックまたは開発トラックを15分体験
  2. AIツールを選定 — 03_ai_tools.htmlのツール比較を参照し、プロジェクトに最適なツールを決定
  3. テンプレートをダウンロード — 04_prompts.htmlで言語×FW×DBを選択しZIPダウンロード
  4. project_info.md を書き換え — プロジェクト名、技術スタック、チーム構成を記入
  5. coding_rules.md を調整 — 既存の社内規約と整合させる
  6. AIツールの設定ファイルを作成 — CLAUDE.md / copilot-instructions.md / .amazonq のテンプレートを活用
  7. 小さなタスクから始める — バグ修正やテスト追加など、リスクの低いタスクでAIの動作を確認
  8. 徐々に範囲を広げる — 新機能実装、設計レビュー、マイグレーション分析へ展開

8. よくある質問

Q: IISがない場合はどうすれば？

方法C（VS Code Live Server）を推奨します。VS Codeをインストールし、Live Server拡張を追加するだけで、5秒でローカルWebサーバーが起動します。Apache、Nginx、Pythonのhttp.serverでも代用可能です。

Q: 社内のファイルサーバーに置いて共有できる？

HTMLファイルの閲覧は可能ですが、ZIPダウンロード機能に制約が出る場合があります（file://プロトコルの制限）。IISまたはWebサーバー経由の配信を推奨します。

Q: mdファイルは何のエディタで開ける？

テキストエディタなら何でもOKです。VS Code（Markdown Preview機能付き）、メモ帳、サクラエディタなど。VS Codeが最も見やすくておすすめです。

Q: テンプレートを自社用にカスタマイズしてもいい？

はい、自由にカスタマイズしてください。利用規約では個人利用・社内教育での利用を許可しています。ただし、カスタマイズ版の転売・再配布は禁止です。

Q: 更新版はどうやって受け取る？

コンテンツは継続的に更新しています。最新版は本サイト (aidev-guide.pages.dev) で無料で閲覧できます。テンプレート集の更新は有料プラン購入者に提供します。詳しくは 利用規約 をご確認ください。

Q: チーム内の複数人で使えますか？

はい、購入者が所属する1つの組織内であれば、チーム全員で利用可能です。グループ会社・関連会社への共有は別途購入が必要です。

9. ハンズオン実習用の開発環境構築

本教材の「09. ハンズオン」章を実際に手を動かして進めるために必要な開発環境を、 OS別・難易度別にまとめます。 初心者が躓きやすいポイントにも先回りで触れます。

このセクションのクイックナビ：

9.1 所要時間と難易度

トラック 所要時間 前提知識 対象者
事務タスク（ブラウザ + 議事録整形） 5分 不要 プログラミング未経験OK
開発タスク（5 言語対応 — Java / C# / VB.NET / Python / TypeScript から選択） 初心者 60分 / 経験者 10分 選んだ言語の基礎 開発者（環境構築込みで1時間の余裕があると◎）

🆕 9.1.5 5 言語対応 — あなたの現場の言語を選ぶ

2026-04 から 5 言語対応になりました。 開発トラックのハンズオンは、Java / C# / VB.NET / Python / TypeScript の 5 言語で同じ課題を用意しています。現場で使っている言語を選んでください。
言語 ディレクトリ 必要な環境 推奨エディタ 想定読者
☕ Java handson_samples/dev_track/src/main/java/com/example/todo/ Java 17 + Maven VS Code / IntelliJ IDEA Spring Boot 系開発者
💠 C# handson_samples/dev_track/csharp_track/src/TodoApi/ .NET 8 SDK Visual Studio 2022 / VS Code + C# Dev Kit ASP.NET Core 系開発者
🟦 VB.NET handson_samples/dev_track/vb_track/src/TodoApi/ .NET 8 SDK Visual Studio 2022 (VB サポート有効化) VB.NET / 古い VB 移行中の方
🐍 Python handson_samples/dev_track/python_track/src/todo_api/ Python 3.11+ + Flask VS Code + Python 拡張 / PyCharm Flask / FastAPI 系開発者
🔷 TypeScript handson_samples/dev_track/typescript_track/src/ Node.js 20+ + TypeScript 5.x + Express VS Code / WebStorm Node.js / Express / NestJS 系開発者
💡 どの言語を選べばよいか迷う場合:
  • 現場で最も使っている言語を選んでください (筆者の推奨)
  • どの言語も 同じ課題 (Todo API に「完了」機能を追加) を扱います
  • 言語を跨いで比較したい場合は、2 つの言語で同じ課題を解くのもアリです

言語別の環境構築要約

☕ Java
1. Eclipse Temurin (Java 17) をインストール
2. Maven または Gradle
3. VS Code + Extension Pack for Java
詳細: §9.2 (Windows) / §9.3 (macOS) に従う
💠 C# (.NET)
1. .NET 8 SDK をインストール (dotnet --version)
2. Visual Studio 2022 Community (無料) または VS Code
3. VS Code の場合 C# Dev Kit 拡張をインストール
確認: dotnet new console が動けば OK
🟦 VB.NET
1. .NET 8 SDK をインストール (C# と同じ)
2. Visual Studio 2022 Community、インストール時に VB サポート有効化
3. dotnet new console -lang VB で動作確認
注意: VS Code の VB サポートは限定的、VS 2022 を推奨
🐍 Python
1. Python 3.11 以降を公式からインストール
2. 仮想環境作成: python -m venv .venv
3. Flask インストール: pip install flask
4. VS Code + Python 拡張または PyCharm
🔷 TypeScript
1. Node.js 20 LTS (公式) をインストール
2. npm init -y && npm install express
3. npm install -D typescript @types/node @types/express
4. npx tsc --init で tsconfig.json 生成
✨ 全言語共通
どの言語も Git が必要です。
どの言語も お好みの AI 開発ツール (Copilot / Claude Code / Cursor / Amazon Q / Gemini) のいずれかがあれば OK。
§9.5 で各 AI ツールの導入を扱います。

9.2 Windows 環境のセットアップ (Java 中心、他言語にも応用可)

必須ツール

  • Java 17 以上 — Eclipse Temurin (LTS推奨)
  • VS Code — 公式サイトからインストーラ取得
  • Git for Windows — 公式からインストール
  • PowerShell — Windows標準（バージョン5.1以上でOK）

VS Code 拡張機能

  • Extension Pack for Java（Microsoft製・必須）
  • GitHub Copilot（Copilotトラック用）
  • Claude Code（Claude Codeトラック用）
  • AWS Toolkit（Amazon Qトラック用）
  • Markdown Preview Enhanced（mdテンプレート閲覧用）
Windows 初心者が躓くポイント：
  • Java のインストール後、java -version が通らない → 環境変数 JAVA_HOME と PATH の再設定が必要
  • VS Code で日本語が文字化けする → ファイル > 基本設定 > 設定 で files.encoding: utf8 を設定
  • PowerShell スクリプトが実行できない → 管理者 PowerShell で Set-ExecutionPolicy RemoteSigned

9.3 macOS 環境のセットアップ

必須ツール（Homebrew 経由が最速）

# Homebrew が未インストールなら先に
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 必須ツール一式
brew install temurin         # Java 17 (Eclipse Temurin)
brew install --cask visual-studio-code
brew install git             # 標準の Git より新しいバージョンが入る

# VS Code の CLI を PATH に追加（VS Codeの「シェルコマンド: code コマンドをPATHにインストール」実行）

VS Code 拡張機能

Windowsと同じ（上記 9.2 参照）

macOS 初心者が躓くポイント：
  • Apple Silicon (M1/M2/M3) と Intel Mac で Homebrew のパスが違う → M系は /opt/homebrew、Intelは /usr/local
  • Java が複数バージョン入ると切替が必要 → jenv か SDKMAN を使うと楽
  • 「開発元が未確認」警告 → システム環境設定 > セキュリティとプライバシー で許可

9.4 Maven か Gradle か

本教材のハンズオンは Maven を前提にしています。理由：

  • Spring Boot の start.spring.io デフォルトが Maven
  • XML 設定なので初心者に読みやすい
  • 多くの企業案件で Maven が標準

Gradle を使いたい場合は、同じハンズオンを Gradle で再現することも可能です。 md_templates/java/ 配下に Gradle テンプレートも用意しています。

9.5 AI 開発ツールの導入

3 つの AI 開発ツールごとに、前提条件と導入コストが異なります。 自社環境に合わせて選択してください。

ツール 前提条件 月額 初期設定の難易度
GitHub Copilot GitHub アカウント $10/月 (Individual) ★☆☆ 非常に簡単
Claude Code Anthropic アカウント + 従量課金 or Pro/Team プラン $20/月〜 (Pro) ★★☆ CLI操作の慣れが必要
Amazon Q Developer AWS アカウント + Builder ID 無料〜$19/月 (Pro) ★★★ AWS コンソール操作が必要
初心者への推奨順序：
  1. GitHub Copilot から始める（最もシンプル、VS Code 内で完結）
  2. Copilot に慣れたら Claude Code を追加（CLI 操作を学ぶ良い機会）
  3. 業務でセキュリティスキャンが必要になったら Amazon Q を検討

9.5.1 Claude Code の導入手順（ハンズオンで最初に触るツール）

ハンズオンでは Claude Code を中心に扱います。 以下は 2026-04 時点の公式情報をもとにした導入フローの概略です。 実際のインストール手順やコマンドは公式ドキュメントで最新版を確認してください。

Step 1: Node.js 18 以上の準備

Claude Code CLI は npm パッケージとして配布されます。先に Node.js 18 以上を導入してください。 Windows は Node.js 公式 の LTS インストーラ、 macOS は brew install node、 Linux は各ディストリビューションのパッケージマネージャまたは nvm を使います。 

node -v
# → v18.x.x 以上が表示されればOK
npm -v
# → 9.x.x 以上が表示されればOK

Step 2: Claude Code CLI のインストール

# グローバルインストール
npm install -g @anthropic-ai/claude-code

# バージョン確認
claude --version

Windows の PowerShell でパーミッションエラーが出る場合は、 管理者権限の PowerShell で Set-ExecutionPolicy RemoteSigned を実行してから再試行してください。 最新の正式な手順は Claude Code 公式ドキュメント で確認してください（URL や手順は公式の更新に追随する前提で、本書は概略のみ案内しています）。

Step 3: API キーまたはサブスクリプションの準備

Claude Code は以下の 2 通りで認証できます。ハンズオンはどちらでも動作します。

  • Claude Pro / Team / Max プラン — claude.ai のアカウントで claude login からブラウザ認証。月額固定で使える。
  • Anthropic API キー（従量課金） — Anthropic Console でキーを発行し、環境変数 ANTHROPIC_API_KEY にセット。小規模利用なら月数ドル程度。
API キーの取り扱い注意：
  • API キーを Git にコミットしない（.env と .gitignore を徹底）
  • 共有 PC では環境変数ではなく、CLI 側の安全なキーストア機構を優先
  • 検証用キーと本番キーは分ける

Step 4: プロジェクト直下に CLAUDE.md を置く

Claude Code はプロジェクトルートの CLAUDE.md を自動で読み込み、 その内容をシステム指示として扱います。ハンズオンでは最低限、次の観点を書いておくと効果的です。 

# プロジェクト名
Todo API（ハンズオン用 / Java 17 + Spring Boot 3.x）

## 技術スタック
- 言語: Java 17
- FW: Spring Boot 3.x
- ビルド: Maven
- DB: H2 (in-memory)

## コーディング規約
- クラスは com.example.todo パッケージ配下
- コントローラ戻り値は ResponseEntity を基本とする
- テストは JUnit 5 + MockMvc
- コメント・変数名は日本語可、メソッド名は英語

## 禁止事項
- 既存のメソッドシグネチャは無断で変更しない
- 外部ライブラリの追加は事前に許可を取る

CLAUDE.md の詳細な設計指針は 05. AI 開発ツール別ガイド の Claude Code セクションを参照してください。

Step 5: VS Code 拡張との連携（任意）

VS Code 上で Claude Code を使う場合、Claude Code 拡張をマーケットプレイスから導入するとチャットパネルが使えるようになります。 CLI とチャットパネルは同じ CLAUDE.md を読むため、設定は共通です。

9.6 環境構築完了チェックリスト

以下がすべて通れば、ハンズオンを始める準備ができています：

# ターミナル/PowerShell で以下を実行し、各バージョンが表示されればOK
java -version
# → openjdk version "17.x.x" など

mvn -version
# → Apache Maven 3.x.x

git --version
# → git version 2.x.x

code --version
# → 1.x.x

これらが全部通れば OK です。通らない項目があったら、本節 9.2 または 9.3 に戻って インストール作業を確認してください。

9.7 トラブルシューティング FAQ

Q: Copilot がサジェストを出してくれない

A: VS Code 左下の Copilot アイコンを確認してください。緑なら有効、グレーなら無効です。 Ctrl+Shift+P → 「Copilot: Sign In」でサインインし直すと解消することが多いです。

Q: Claude Code の CLI が起動しない

A: npm install が必要です。npm install -g @anthropic-ai/claude-code を実行してください。 Node.js 18 以上が前提です。

Q: Amazon Q で「Sign in failed」が出る

A: AWS Builder ID が必要です。AWS Profile からアカウントを作成してから、VS Code の AWS Toolkit で再ログインしてください。

Q: Maven のダウンロードが遅い

A: 日本国内のミラーサイトを使うと速くなります。 ~/.m2/settings.xml に以下を追加してください： 

<mirrors>
  <mirror>
    <id>jboss-public</id>
    <mirrorOf>central</mirrorOf>
    <url>https://repository.jboss.org/nexus/content/groups/public/</url>
  </mirror>
</mirrors>

Q: 会社のプロキシがあって外部接続できない

A: 環境変数 HTTP_PROXY と HTTPS_PROXY を設定してください。 Maven / npm / Git / VS Code それぞれに個別のプロキシ設定が必要になる場合があります。 主要ツールのプロキシ設定箇所は以下の通りです：

  • Maven: ~/.m2/settings.xml の <proxies> セクション
  • npm: npm config set proxy http://proxy.example.com:8080
  • Git: git config --global http.proxy http://proxy.example.com:8080
  • VS Code: 設定 → http.proxy に URL を指定
  • Claude Code CLI: 環境変数 HTTPS_PROXY を尊重する

SSL 証明書エラーが発生する場合は、社内 CA 証明書の取り込みが必要です。 具体的な手順は社内のネットワーク担当に問い合わせてください。