開発の基本ルール
AIにツールを作ってもらうとき、知っておくと安心なお約束ごと。
Webサービスの全体像
Webサービス（ホームページやアプリ）は、大きく3つの部分に分かれています。それぞれ別の役割があり、別のサービスを使います。
Webサービスの3層構造 — フロントエンド・バックエンド・データベースが連携してサービスを構成する
| 部分 | やさしく言うと | おすすめサービス |
|---|
フロントエンド
画面まわり | ユーザーが見る・触る部分。ボタンや入力欄など。 | Vercel / Cloudflare Pages / Netlify |
バックエンド
裏側の処理 | データを処理したり、他のサービスと連携する「裏方」。 | Cloud Run / AWS Lambda / Railway |
データベース
データの保存 | ユーザー情報や投稿データなどを保存しておく場所。 | Supabase / Firebase / PlanetScale |
初心者向けおすすめ構成
Vercel（フロント）+ Supabase（バックエンド+DB）で始めるのが最も簡単。どちらも無料枠が充実しており、Gitにpushするだけで自動デプロイされます。認証・データベース・APIが一体で揃います。
環境変数を使う
APIキーやパスワードなどの秘密情報（シークレット）をコードに直接書いてはいけません。代わりに.envファイルに保存し、コードからは環境変数として読み込みます。
悪い例（ハードコーディング）
// APIキーをコードに直接書く → 絶対NG
const API_KEY = "sk-abc123xxxxx";
fetch(`https://api.openai.com/v1/chat`, {
headers: { 'Authorization': `Bearer ${API_KEY}` }
});
良い例（環境変数）
# .envファイル（.gitignoreに追加すること）
OPENAI_API_KEY=sk-abc123xxxxx
# コードから読み込む
import dotenv from 'dotenv';
dotenv.config();
const API_KEY = process.env.OPENAI_API_KEY;
事故事例
GitHubにAPIキーを含むコードをpushし、数時間で不正利用され100万円以上の請求が来た事例が多数報告されています。.envは必ず.gitignoreに追加してください。
マジックナンバーを使わない
コードの中に「意味のわからない数字や文字列」が突然出てくることをマジックナンバーと呼びます。後から読んだ人（＝未来の自分含む）が意味を理解できません。
悪い例
if (users.length > 50) { // 50って何？
showError();
}
const tax = price * 0.1; // 0.1って何？
良い例
const MAX_USERS_PER_PAGE = 50;
const TAX_RATE = 0.1;
if (users.length > MAX_USERS_PER_PAGE) {
showError();
}
const tax = price * TAX_RATE;
ハードコーディングしない
URLやファイルパス、設定値などをコードの中に直接書き込むことをハードコーディングと言います。環境（開発/本番）が変わると動かなくなります。
悪い例
// 開発環境のURLが埋め込まれている
fetch("http://localhost:3000/api/users");
// 特定のパスに依存
const logFile = "C:/Users/tanaka/logs/app.log";
良い例
# .envで環境ごとに切り替え
API_BASE_URL=http://localhost:3000 # 開発時
API_BASE_URL=https://api.myapp.com # 本番時
// コードは環境に依存しない
fetch(`${process.env.API_BASE_URL}/api/users`);
その他の基本ルール
| ルール | やること | やらないこと |
|---|
同じことを繰り返さない
（DRYの原則） | 同じ処理は1箇所にまとめる | 同じコードをあちこちにコピペする |
| 名前の付け方を統一 | ルールを決めて揃える | ファイルごとに名前の付け方がバラバラ |
| エラーに備える | 「もし失敗したら」の処理を入れる | エラーを無視して動かし続ける |
| Gitで管理する | 変更履歴を記録する | 「ファイル名_最終版_v2_本当の最終.html」 |
| 秘密情報を除外する | .envなどをGitに含めないよう設定 | パスワード入りファイルをそのままGitに入れる |
フォルダ構成の基本
プロジェクトが大きくなっても迷わないように、最初からフォルダを整理しておきます。
my-app/
├── .env # 環境変数（Gitに含めない）
├── .gitignore # Git除外設定
├── package.json # 依存パッケージ管理
├── src/ # ソースコード
│ ├── index.js # エントリーポイント
│ ├── config.js # 設定値を集約
│ ├── api/ # API関連
│ └── utils/ # 共通ユーティリティ
├── public/ # 静的ファイル（HTML/CSS/画像）
└── tests/ # テストコード
Claude Codeとの関係
Claude Codeに「環境変数を使ってリファクタリングして」「マジックナンバーを定数に置き換えて」と指示すれば、既存コードを自動的にベストプラクティスに沿って修正してくれます。CLAUDE.mdに「環境変数を使うこと」と書いておけば、最初からそのルールに従ってコードを生成します。
Gemini APIをアプリに組み込む
作ったアプリにGoogleのAI（Gemini）を組み込んで、もっと賢くする方法。
Gemini 2.0 Flash は実質無料
無料枠: 1分15リクエスト。1回のAPIコール ≈ 0.1円以下。1日100回使っても約10円。
APIキーの取得
02
「Create API Key」をクリック
GCPプロジェクトの選択画面で既存を選ぶか新規作成。
03
キーをコピーして安全に保管
.envファイルに保存し、.gitignoreに追加。GitHubに上げないこと。
JavaScript
// Gemini API 呼び出し
const response = await fetch(
`https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=${apiKey}`,
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
contents: [{ parts: [{ text: 'プロンプト' }] }],
generationConfig: { temperature: 0.2 }
})
}
);
const data = await response.json();
const text = data.candidates[0].content.parts[0].text;
Python
# pip install google-generativeai
import google.generativeai as genai
genai.configure(api_key="YOUR_API_KEY")
model = genai.GenerativeModel("gemini-2.0-flash")
response = model.generate_content("プロンプト")
print(response.text)
Playwright — ブラウザ自動操作
ブラウザの操作を自動化。「毎日この画面を開いてこのボタンを押す」をプログラムにできる。
Microsoftが開発したブラウザ自動操作ツール。人間がブラウザで行う操作（クリック、入力、ページ移動など）を、プログラムで自動化できます。
スクレイピング
ログイン必須のサイトからデータ取得。定期的なデータ収集の自動化。
業務自動化
勤怠システムへの自動打刻。Webフォームへの自動入力。管理画面の定型操作。
インストール
# Python版
pip install playwright
playwright install
使用例
# ログインしてデータ取得
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(headless=True)
page = browser.new_page()
page.goto("https://example.com/login")
page.fill("#email", "user@example.com")
page.fill("#password", "password")
page.click("button[type=submit]")
page.wait_for_url("**/dashboard")
print("ログイン成功")
browser.close()
pywinauto — デスクトップアプリ自動操作
Excelや業務ソフトなど、Windowsアプリの操作を自動化する。
Playwright との使い分け
Playwright = Webブラウザの自動化（Chrome等）
pywinauto = Windowsデスクトップアプリの自動化（Excel等）
pip install pywinauto
使用例: メモ帳を操作
from pywinauto.application import Application
app = Application(backend="uia").start("notepad.exe")
dlg = app.window(title_re=".*メモ帳.*")
dlg.Edit.type_keys("自動入力テスト", with_spaces=True)
freee会計 API連携
クラウド会計ソフト「freee」と自分のアプリをつなげて、会計データを自動で取得・登録する。
freee APIってなに？
freee会計にはAPI（外部連携の窓口）が用意されていて、プログラムから会計データを読み書きできます。たとえば「試算表を自動で取得する」「売上データを自動で仕訳登録する」といったことが可能になります。
freee APIでできること
- 試算表（BS/PL）の自動取得
- 仕訳・取引の自動登録
- 取引先マスタの取得・管理
- 請求書・見積書の作成
- 経費精算の管理
- 勘定科目・部門の取得
活用シーン
- 月次の試算表を自動で取得→レポート化
- kintoneの売上データ→freeeに仕訳登録
- 請求書の自動作成・送付
- 経費精算の自動チェック
- 複数顧問先のデータ一括取得
認証の仕組み（OAuth2.0）
freee APIを使うには、まず「このアプリがfreeeのデータにアクセスしていいですよ」という許可を取る必要があります。この仕組みをOAuth2.0（オーオース）と呼びます。
身近な例でいうと
「Googleでログイン」ボタンを押すと、Googleの画面が開いて「このアプリにアクセスを許可しますか？」と聞かれますよね。あれと同じ仕組みです。freeeの画面で許可すると、アプリがfreeeのデータを読み書きできるようになります。
freee OAuth2.0 認証フロー — freee Developers Community公式ドキュメントより
認証フローの流れ
01
アプリを登録する
freee開発者ページでアプリを作成し、Client IDとClient Secretを取得します。これがアプリの「身分証明書」です。
02
ユーザーに許可してもらう
アプリからfreeeの認可画面にリダイレクト。ユーザーがfreeeにログインし、アクセスする事業所を選んで「許可する」をクリックすると、認可コードが発行されます（有効期限10分）。
03
アクセストークンを取得
認可コードを使って、アクセストークン（APIの入場券）を取得します。有効期限は6時間。同時にリフレッシュトークンも発行されます。
04
APIを呼び出す
アクセストークンをリクエストヘッダーに付けて、freee APIにアクセスします。
トークンの管理（重要）
| トークン | 役割 | 有効期限 | 注意点 |
|---|
| アクセストークン | APIの入場券 | 6時間 | 期限切れたらリフレッシュで更新 |
| リフレッシュトークン | 入場券の更新チケット | 90日 | 1回使うと無効になり、新しいものが発行される（使い捨て） |
| 認可コード | 初回の許可証 | 10分 | すぐにトークンに交換する |
リフレッシュトークンは使い捨て！
freeeのリフレッシュトークンは1回使うと無効になります。新しく発行されたトークンを毎回保存しないと、再認証が必要になります。これはfreee特有の仕様で、よくハマるポイントです。
主要なAPI一覧
| API | できること | エンドポイント |
|---|
| 事業所一覧 | アクセス可能な事業所を取得 | GET /api/1/companies |
| 試算表（BS） | 貸借対照表を取得 | GET /api/1/reports/trial_bs |
| 試算表（PL） | 損益計算書を取得 | GET /api/1/reports/trial_pl |
| 取引の作成 | 仕訳を登録する | POST /api/1/deals |
| 取引先一覧 | 取引先マスタを取得 | GET /api/1/partners |
| 勘定科目一覧 | 勘定科目マスタを取得 | GET /api/1/account_items |
| 請求書 | 請求書を作成・取得 | GET/POST /api/1/invoices |
| 経費精算 | 経費申請を管理 | GET/POST /api/1/expense_applications |
実装例: 試算表を取得する
Claude Codeに「freeeから試算表を取得するスクリプトを作って」と指示すれば、以下のようなコードを自動で書いてくれます。
# Python で freee API を叩く例
import requests, os
from dotenv import load_dotenv
load_dotenv()
access_token = os.getenv("FREEE_ACCESS_TOKEN")
company_id = os.getenv("FREEE_COMPANY_ID")
# 試算表（PL: 損益計算書）を取得
response = requests.get(
f"https://api.freee.co.jp/api/1/reports/trial_pl",
headers={"Authorization": f"Bearer {access_token}"},
params={"company_id": company_id, "fiscal_year": 2025}
)
data = response.json()
# 各科目の残高を表示
for item in data["trial_pl"]["balances"]:
if not item.get("total_line"): # 合計行は除外
name = item.get("account_item_name", "")
balance = item.get("closing_balance", 0)
print(f"{name}: {balance:,.0f}円")
// JavaScript で freee API を叩く例
const response = await fetch(
`https://api.freee.co.jp/api/1/reports/trial_bs?company_id=${companyId}&fiscal_year=2025`,
{ headers: { 'Authorization': `Bearer ${accessToken}` } }
);
const data = await response.json();
// 個別科目のみ取得（合計行を除外）
const accounts = data.trial_bs.balances
.filter(b => !b.total_line)
.map(b => ({
name: b.account_item_name,
balance: b.closing_balance
}));
実装時の注意点
合計行の二重カウントに注意
試算表APIのレスポンスにはtotal_line: trueの合計行が含まれています。これを含めて集計すると金額が二重にカウントされます。必ずtotal_lineがfalseの行だけを使いましょう。
トークンは.envに保存
アクセストークンやClient Secretは絶対にコードに直接書かないこと。.envファイルに保存し、.gitignoreに追加してください。
リフレッシュトークンの保存は毎回
freeeのリフレッシュトークンは使い捨てです。トークンを更新したら、新しいリフレッシュトークンを必ず保存してください。保存し忘れると再認証が必要になります。
Claude Codeへの指示例
You
freee会計APIと連携して、指定した事業所の今期の損益計算書を取得するPythonスクリプトを作って。
- OAuth2のアクセストークンは.envから読み込む
- 合計行(total_line)は除外して個別科目だけ表示
- 科目名と金額をCSVで出力
テスト自動化
AIが作ったものが正しく動くか、自動でチェックする仕組み。
Claude Codeにテストを渡すと、自分でテストを実行 → 結果を見て修正するので精度が格段に上がります。
// Playwright E2Eテスト例
import { test, expect } from '@playwright/test';
test('ログインしてダッシュボードが表示', async ({ page }) => {
await page.goto('http://localhost:3000/login');
await page.fill('#email', 'test@example.com');
await page.fill('#password', 'password');
await page.click('button[type="submit"]');
await expect(page).toHaveURL(/dashboard/);
await expect(page.locator('h1')).toContainText('ダッシュボード');
});
プロンプトのコツ: 「テストを書いて」だけでなく「テストを実行して全部通ることを確認して」まで伝える。実行結果を見て自動的にコードを修正してくれます。
ホスティング
作ったものをインターネットに公開する方法。
ホスティングとは
ローカル（自分のPC）で動いているアプリをインターネット上に公開して、誰でもアクセスできるようにするサービスです。
無料で使えるサービス
| サービス | 種類 | 無料枠 | 強み | 注意点 |
|---|
| GitHub Pages | 静的サイト | 完全無料 | GitHubリポジトリから直接公開。最も手軽 | 静的ファイルのみ（HTML/CSS/JS） |
| Cloudflare Pages | 静的+Functions | 帯域無制限 | 世界最大級のCDN。高速。Workers連携 | 学習コストがやや高い |
| Vercel | フルスタック | 個人利用無料 | Next.js最適化。プレビュー自動デプロイ | 商用利用はPro必須（$20/月） |
| Netlify | フルスタック | 100GB/月 | フォーム・認証を組み込み提供 | 日本からのアクセスがやや遅い |
| Firebase Hosting | 静的+Functions | 10GB/月 | Google認証・DB・Storageと統合 | Google Cloud依存 |
| Render | フルスタック | 750時間/月 | Docker対応。DBも無料枠あり | 無料プランは15分でスリープ |
自前サーバー / VPS / レンタルサーバー
クラウドサービスを使わず、自分でサーバーを管理する選択肢もあります。自由度が高い反面、セキュリティやメンテナンスは全て自己責任です。
| 種類 | 代表サービス | 料金目安 | 特徴 | 向いている用途 |
|---|
レンタルサーバー
（共有） | Xserver / ロリポップ / さくら | 月500〜1,500円 | 管理画面で操作。PHPやWordPressがすぐ動く。SSH不要で初心者向き | WordPress / コーポレートサイト / LP |
VPS
（仮想専用） | ConoHa VPS / さくらVPS / Linode | 月500〜3,000円 | root権限あり。OS・ミドルウェアを自由に構築。Docker動作可 | 独自アプリ / Node.js / Python API |
| クラウドVM | GCE / AWS EC2 / Azure VM | 月$5〜（従量課金） | スケール自由。他クラウドサービスとの連携が容易。企業利用の標準 | 大規模アプリ / 機械学習 / エンタープライズ |
自前サーバーの注意点
OS・セキュリティアップデート、SSL証明書管理、ファイアウォール設定、バックアップすべて自己管理。Vercel等のマネージドサービスならこれらが不要なので、個人開発や小規模案件なら最初はマネージドサービスを推奨します。
有料・サーバーレスサービス
| サービス | 料金目安 | 強み | 向いている用途 |
|---|
| GCP Cloud Run | 従量課金（月$0〜） | コンテナをサーバーレス実行。スケール自動 | API・バックエンド・バッチ処理 |
| AWS Lambda | 従量課金（月100万回無料） | 関数単位で実行。AWSエコシステム全連携 | イベント駆動・マイクロサービス |
| Railway | $5/月〜 | Heroku代替。DB込みでワンクリックデプロイ | 個人開発・プロトタイプ |
| Fly.io | $0〜（無料枠あり） | エッジ分散。Docker対応。日本リージョンあり | 低レイテンシ重視のAPI |
全体の棲み分け
静的サイト / LP
GitHub Pages
Cloudflare Pages
→
Webアプリ
Vercel / Netlify
Firebase
→
自前サーバー
VPS / レンタル鯖
自由度◎ 管理△
→
クラウドインフラ
AWS / GCP / Azure
何でもできる
選び方の目安
静的サイト・LP → GitHub Pages / Cloudflare Pages（無料で十分）
WordPress・コーポレート → Xserver等のレンタルサーバー（月1,000円程度で安定）
Next.js / React → Vercel（開発体験が最高）
独自アプリ・自由に構築 → VPS（ConoHa / さくら）
API・バックエンド → Cloud Run / Railway（サーバー管理不要）
大規模・エンタープライズ → AWS / GCP（全サービス連携）
Claude Codeでデプロイする
# Claude Codeへの指示例
"このReactアプリをVercelにデプロイして"
"Cloud RunにDockerでデプロイするスクリプトを書いて"
"GitHub Actionsで自動デプロイのCI/CDを設定して"
認証・ログイン機能
「ログインして使う」機能を追加する方法。
認証の選択肢
ログイン機能をゼロから作るのはセキュリティリスクが非常に高いため、認証専用のサービスを使うのが鉄則です。
| サービス | 無料枠 | 強み | 最適な用途 |
|---|
| Firebase Auth | 無制限（ほぼ） | Google/Apple/メール/電話認証。最も実績豊富 | モバイル・Webアプリ全般 |
| Supabase Auth | 50,000 MAU | PostgreSQL + RLS統合。オープンソース | フルスタックアプリ |
| Clerk | 10,000 MAU | React統合が最強。UIコンポーネント付き | Next.js / Reactアプリ |
| Auth0 | 25,000 MAU | エンタープライズ向け。SAML/OIDC対応 | 大規模・B2Bアプリ |
Firebase Authの実装例
// Firebase Auth: Googleログイン（最短実装）
import { initializeApp } from 'firebase/app';
import { getAuth, signInWithPopup, GoogleAuthProvider } from 'firebase/auth';
const app = initializeApp({ /* Firebase設定 */ });
const auth = getAuth(app);
// Googleログインボタンのクリックハンドラ
async function login() {
const result = await signInWithPopup(auth, new GoogleAuthProvider());
console.log(result.user.displayName); // ログインユーザー名
}
Supabase Authの実装例
// Supabase Auth: メール+パスワード
import { createClient } from '@supabase/supabase-js';
const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
// サインアップ
const { data, error } = await supabase.auth.signUp({
email: 'user@example.com',
password: 'secure-password'
});
// ログイン
const { data } = await supabase.auth.signInWithPassword({
email: 'user@example.com',
password: 'secure-password'
});
Claude Codeで認証を実装
「Firebase Authでgoogleログインを実装して」「Supabaseでメール認証つきのログインページを作って」のように指示すれば、設定ファイルからUIまで一気に生成してくれます。
API接続
他のサービスとデータをやりとりする仕組み。
APIってなに？
API（Application Programming Interface）とは、ソフトウェア同士が情報をやりとりする窓口です。レストランに例えると、お客さん（自分のアプリ）がウェイター（API）を通じて厨房（外部サービス）に注文を出し、料理（データ）を受け取る仕組みです。
身近なAPIの例
- 天気アプリ → 気象庁APIで天気を取得
- Googleマップ埋め込み → Maps API
- ChatGPTをアプリに組み込む → OpenAI API
- 決済機能 → Stripe API
APIがないとどうなる？
- 全機能を自分でゼロから作る必要がある
- AI機能 → 自前でLLMを訓練（数億円）
- 決済 → PCI DSS準拠を自前で（数千万円）
- 地図 → 地図データを自前で収集（不可能）
REST APIの基本
最も一般的なAPIの形式です。HTTPリクエスト（WebブラウザがWebサイトを表示する仕組みと同じ）を使ってデータをやりとりします。
| メソッド | 用途 | たとえると |
|---|
GET | データを取得 | メニューを見せて |
POST | データを新規作成 | この料理を注文して |
PUT | データを更新 | 注文を変更して |
DELETE | データを削除 | 注文をキャンセルして |
APIキーの管理
APIを使うには多くの場合APIキー（認証情報）が必要です。これは「会員証」のようなもので、誰がAPIを利用しているかを特定し、不正利用を防ぎます。
重要: APIキーの取り扱い
APIキーをコードに直接書いてGitHubにプッシュすると、悪意ある第三者に利用され高額請求される事故が頻発しています。必ず.envファイルに保存し、.gitignoreに追加してください。
# .envファイル（Gitに含めない）
OPENAI_API_KEY=sk-xxxxxxxxxxxxx
GEMINI_API_KEY=AIzaXXXXXXXXXXXXXX
# Pythonでの読み込み
from dotenv import load_dotenv
import os
load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")
実際にAPIを叩いてみる
# curlで天気APIを叩く例
curl "https://api.open-meteo.com/v1/forecast?latitude=35.68&longitude=139.77¤t_weather=true"
# レスポンス（JSON形式）
{
"current_weather": {
"temperature": 18.5,
"windspeed": 12.3,
"weathercode": 0
}
}
JavaScriptからAPIを呼ぶ
// fetch APIでデータ取得（ブラウザ / Node.js共通）
const res = await fetch('https://api.example.com/users', {
headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const data = await res.json();
console.log(data);
// POSTでデータ送信
const res2 = await fetch('https://api.example.com/users', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name: '田中太郎', email: 'tanaka@example.com' })
});
Claude Codeとの関係
Claude Code自体が内部でAnthropicのAPIを使って動いています。「このAPIを叩いてデータを取得して」と指示すれば、コードを書いてAPIを呼び出す処理を自動生成してくれます。エラーハンドリングやリトライ処理まで含めて生成可能です。
クラウド連携（GCP / AWS）
GoogleやAmazonのクラウドサービスと組み合わせて、本格的なシステムを作る。
GCPとAWSの使い分け
GCP（Google Cloud）
- Cloud Run → コンテナをサーバーレス実行
- Cloud Functions → 関数単位で実行
- Cloud Storage → ファイル保存
- Firestore → NoSQLデータベース
- BigQuery → 大規模データ分析
Firebase経由で使うと学習コストが低い
AWS（Amazon Web Services）
- Lambda → 関数単位で実行
- EC2 → 仮想サーバー
- S3 → ファイル保存
- DynamoDB → NoSQLデータベース
- RDS → リレーショナルDB
シェア世界1位。情報量が圧倒的
Cloud Runでバックエンドを公開する例
01
Dockerfileを作成
Claude Codeに「このPythonアプリ用のDockerfileを作って」と指示。
02
ビルド＆プッシュ
gcloud builds submit --tag gcr.io/PROJECT_ID/my-app
03
デプロイ
gcloud run deploy my-app --image gcr.io/PROJECT_ID/my-app --region asia-northeast1 --allow-unauthenticated
AWS Lambdaで関数を公開する例
# Python Lambda関数
def lambda_handler(event, context):
name = event.get('name', 'World')
return {
'statusCode': 200,
'body': f'Hello, {name}!'
}
よくあるアーキテクチャパターン
フロントエンド
Vercel / Cloudflare
→
API / バックエンド
Cloud Run / Lambda
→
データベース
Supabase / Firestore
Claude Codeでクラウド連携
「Cloud RunにデプロイするDockerfileとcloudbuild.yamlを作って」「AWS LambdaでAPIゲートウェイ経由のエンドポイントを作って」のように指示すれば、設定ファイルからデプロイスクリプトまで自動生成します。
