japan-localize-builder

name	japan-localize-builder
description	海外で成功しているWebアプリを発見→超詳細に分析→日本向けにローカライズ→ACP（Claude Code）セッションで実装するフルスタック自動化スキル。「日本向けにローカライズして」「海外アプリを日本で作りたい」「海外プロダクトを日本版にして」「ローカライズ開発」「Japan localize」「日本市場向けに」などと言われたら使う。

Japan Localize Builder

海外で成功しているプロダクトを発見→超詳細に分析→日本向け要件定義→ACP（Claude Code）セッションで開発するワークフロー。

絶対ルール

1. 既存プロダクトのリソースに触らない — 他のプロダクトのClerkアプリ、Convexプロジェクト、Vercelプロジェクト、GitHub リポジトリ等を一切変更・流用しない。必ず新規作成する。
2. Clerkは毎回新規アプリ作成 — 既存のAPIキーを使い回さない。
3. Convexも毎回新規プロジェクト — npx convex dev で新規作成。既存プロジェクトに接続しない。
4. 実装はメインエージェントの直接実装を優先する — ACPが利用可能でも、ユーザーが明示した場合はこのセッションで直接実装を進める。
5. デザイン検討はGemini Skill（Gemini CLI実行フロー）を優先する — 可能な場合はGemini Skillでデザイン案を生成し、不可ならメインセッションで継続する。
6. 実装開始後の進捗ログはDiscordの「開発中」カテゴリに記録する — カテゴリ/チャンネルがなければ新規作成し、主要マイルストーンごとに投稿する。
7. any 型の使用を絶対に禁止する — unknown、具体的な型、ジェネリクスを使うこと。
8. gitコミットメッセージは必ず日本語で書くこと。

前提条件チェック（ワークフロー開始前に必ず実行）

ワークフロー開始前に、以下の全ツール・アカウントが揃っているかチェックし、不足があればユーザーに確認すること。

1. CLIツール（自動チェック）

以下のコマンドを実行して全ツールの存在を一括確認する:

echo "=== 前提条件チェック ===" && \
echo -n "Node.js: " && (node -v 2>/dev/null || echo "❌ 未インストール → https://nodejs.org/") && \
echo -n "npm: " && (npm -v 2>/dev/null || echo "❌ 未インストール") && \
echo -n "git: " && (git --version 2>/dev/null || echo "❌ 未インストール") && \
echo -n "GitHub CLI (gh): " && (gh --version 2>/dev/null | head -1 || echo "❌ 未インストール → brew install gh") && \
echo -n "Vercel CLI: " && (npx vercel --version 2>/dev/null || echo "❌ 未インストール → npm i -g vercel") && \
echo "=== チェック完了 ==="

必須ツール一覧:

ツール	最低バージョン	用途	インストール方法
Node.js	18+	開発ランタイム	brew install node or https://nodejs.org/
npm	9+	パッケージ管理	Node.jsに同梱
git	2.x	バージョン管理	brew install git
GitHub CLI (gh)	2.x	リポジトリ作成・管理	brew install gh → gh auth login
Vercel CLI	latest	デプロイ	npm i -g vercel → vercel login

2. アカウント・サービス（ユーザーに確認）

ユーザーに以下を確認すること（未取得のものがあれば案内する）:

サービス	用途	登録URL
GitHub	ソースコード管理	https://github.com
Vercel	フロントエンドデプロイ	https://vercel.com
Convex	バックエンド/DB	https://www.convex.dev
Clerk	認証 (Phase 8で使用)	https://clerk.com

3. 不足ツールの自動インストール（ユーザー許可後）

チェックで不足が見つかった場合、ユーザーに以下を提示して許可を得てからインストール:

# 不足ツールのインストール例（必要なもののみ実行）
brew install node           # Node.js
brew install gh && gh auth login   # GitHub CLI
npm i -g vercel && vercel login    # Vercel CLI

全ツールが揃うまでワークフローを開始しない。

---

Workflow Checklist

━━━ ステージ0: 前提条件 ━━━
- [ ] 前提条件チェック: CLI・アカウント確認（不足があればインストール）

━━━ ステージ1: リサーチ & 分析（順次） ━━━
- [ ] Phase 0: 開発済みプロダクト確認
- [ ] Phase 1: ディープリサーチ（5件以上発見、Webアプリのみ）
- [ ] Phase 1.5: 候補アプリの実地調査（WebFetchで調査）
- [ ] Phase 2: 日本市場機会分析（スコアリング）

━━━ ステージ2: ドキュメント作成 ━━━
- [ ] Phase 3-A: ローカライズ戦略ドキュメント作成
- [ ] Phase 3-B: 超詳細要件定義書作成

━━━ ステージ3: 開発（ACP: Claude Codeセッション） ━━━
- [ ] Phase 4: プロジェクト作成→コード実装→完了

━━━ ステージ4: 品質保証 ━━━
- [ ] Phase 5: テスト（ビルド・起動・機能テスト）
- [ ] Phase 5.5: コード品質チェック（Biome & 型安全）
- [ ] Phase 5.7: SEO対策実装
- [ ] Phase 6: セキュリティ調査

━━━ ステージ5: デプロイ & 公開 ━━━
- [ ] Phase 7: GitHub リポジトリ作成 & プッシュ
- [ ] Phase 7.3: Convex セットアップ（自動・質問なし）
- [ ] Phase 7.5: Vercelデプロイ

━━━ ステージ5.5: 品質改善ループ ━━━
- [ ] Phase 7.8: 品質改善ループ（最低3周、実運用レベルまで）

━━━ ステージ6: Clerk認証（最終ステップ） ━━━
- [ ] Phase 8: Clerk認証セットアップ

━━━ ステージ7: 完了 ━━━
- [ ] Phase 9: built-products.md 更新 & レポート出力

---

Phase 0: 初期化 & 重複チェック

まず現在の日時を取得:

date '+%Y年%m月%d日 %H:%M %Z'

references/built-products.md を読み込み、同じプロダクトは作らない。機能・趣旨が異なるなら別物としてOK。

---

Phase 1: ディープリサーチ

references/research-sources.md を読み込んでリサーチソースを確認。

1. 以下の指定サイトのみでリサーチ（WebSearch、WebFetchを活用）。一般Web検索は禁止:
   • acquire.com /buyers/ — カテゴリ・収益でフィルタ
   • Product Hunt — 今週/今月のトレンド
   • Indie Hackers — 収益実証済みプロダクト
   • Hacker News Show HN — 新興ツール
   • TechCrunch — スタートアップニュース
   • Crunchbase — スタートアップDB
2. 各発見物を記録: 名前、URL、カテゴリ、概要、収益/トラクション、日本での面白さ
3. 最低5件発見すること
4. 必ずWebアプリであること（Chrome拡張、モバイル専用アプリはNG）。ブラウザで完結するWebアプリのみ選定対象。

Phase 1.5: 候補アプリの実地調査（必須）

トップ候補3つに対して、WebFetchでアクセスして調査:

1. サイトにアクセス — LP/トップページの内容を取得
2. 主要機能の把握 — 機能一覧、UI構成、料金体系を調査
3. UI/UXの詳細メモ — 以下を記録:
   • レイアウト構成（サイドバー？タブ？）
   • カラーパレット（メインカラー、アクセントカラー）
   • 特徴的なUIパターン
4. 感想・評価 — 何が良い？何が微妙？日本向けに変えるべき点は？

この調査結果を output/<project-name>/research-notes.md に記録。

---

Phase 2: 日本市場機会分析

references/japan-localization.md を読み込んでローカライズフレームワークを確認。

各候補を以下でスコアリング（各1-5点）:

• JP競合の有無 — WebSearchで日本語検索
• 文化的フィット — 日本ユーザーに刺さるか
• 市場規模 — 十分な市場があるか
• ローカライズ難易度 — 低いほど高スコア
• 独自優位性 — JP版を作る意味があるか

合計スコアでランキング。トップ1つを選定。

---

Phase 3-A: ローカライズ戦略ドキュメント

output/<project-name>/localization-strategy.md に書き出す:

1. 元プロダクト完全分析

• 全機能リスト（UI構成の記述含む）
• ビジネスモデル詳細（料金体系、課金フロー、フリーミアム構成）
• ユーザージャーニー（登録→オンボーディング→コア体験→課金→リテンション）
• 成功要因（なぜバズったか、何が刺さったか）

2. 日本市場ギャップ分析

• 日本の類似サービス一覧と各サービスの弱点
• 日本ユーザーの未充足ニーズ
• 文化的に変更が必要な点
• 日本ユーザーが求める追加機能

3. ローカライズ方針

• UI/UX変更点（レイアウト、情報密度、色彩、フォント）
• コピーライティング方針（トーン、敬語レベル、キャッチコピー案3つ以上）
• 決済手段優先順位（クレカ、コンビニ払い、PayPay、LINE Pay）
• 日本独自機能（LINE連携、日本語検索最適化等）
• 法的対応（特商法表記、プライバシーポリシー、インボイス制度）

4. Go-to-Market戦略

• ローンチ前（ティザー、SNS、Note記事）
• ローンチ（PR TIMES、Twitter/X拡散）
• 成長（SEO、コンテンツマーケ、コミュニティ）
• KPI（DAU/MAU、CVR、チャーン率の具体的目標値）

---

Phase 3-B: 超詳細要件定義書

output/<project-name>/requirements.md に書き出す。これが開発の設計図。

1. プロダクト概要

• プロダクト名（日本向け）、一言コンセプト
• ターゲットペルソナ3つ以上
• 独自の価値提案

2. 機能要件（全機能） 各機能に: 機能名、ユーザーストーリー、受け入れ条件、優先度（P0/P1/P2）、UI概要

3. 画面一覧（元アプリを完全再現） 各画面に: 画面名、目的、含まれる要素、ユーザーアクション、画面遷移先 ログイン/サインアップ、ダッシュボード、設定、プロフィール等すべての画面を網羅

4. データモデル（Convexスキーマ）

• エンティティ一覧、各フィールド（Convex型）、リレーション
• convex/schema.ts のコード例を含める

5. Convex関数設計

• Queries、Mutations、Actions一覧
• 認証方式（Convex Auth / Clerk連携）

6. 技術スタック

• フロントエンド: Next.js 15 + TypeScript + Tailwind CSS
• UIコンポーネント: shadcn/ui（必須）
• チャート: shadcn/ui Charts
• バックエンド/DB: Convex（必須）
• 認証: Clerk

7. 非機能要件

• パフォーマンス、SEO、アクセシビリティ、レスポンシブ

8. 日本語ローカライズ仕様

• フォント: Noto Sans JP / BIZ UDPGothic
• 日付: YYYY年MM月DD日、通貨: ¥（小数点なし）
• 主要UI文言の日本語訳一覧

9. 必須ページ（全プロダクト共通）

パス	ページ名	内容
/about	サービスについて	ミッション、主な特徴、運営者情報（<YOUR_NAME>, <YOUR_ADDRESS>）
/help	ヘルプセンター	よくある質問、お問い合わせ先
/terms	利用規約	サービス内容、アカウント、料金と返金、禁止事項等
/privacy	プライバシーポリシー	収集する情報、利用目的、第三者サービス等
/legal	特定商取引法に基づく表記	販売業者、運営責任者、所在地等
/status	サービスステータス	各システムの稼働状況

共通情報（各自設定）:

• 運営者: <YOUR_NAME>
• 所在地: <YOUR_ADDRESS>
• メール: <YOUR_EMAIL>
• フッターに全ページへのリンクを配置

---

Phase 4: ACP（Claude Code）による開発

requirements.mdに基づいて、ACPハーネスでClaude Codeセッションを起動して実装する。

0. ACPセッション起動（必須）

• sessions_spawn を使い、runtime: "acp" でセッションを作成する。
• agentId は明示指定する（環境に acp.defaultAgent がある場合を除く）。
• Discordでは thread: true, mode: "session" をデフォルトにする。
• 以後の実装・修正はそのACPセッションに対して指示して進める。

1. プロジェクト初期化

PROJECT_DIR=~/<project-name>
mkdir -p $PROJECT_DIR && cd $PROJECT_DIR
npx create-next-app@latest . --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm

2. 依存パッケージインストール

npx shadcn@latest init
npx shadcn@latest add button card dialog input label select table tabs sonner badge separator sheet avatar dropdown-menu popover calendar command tooltip progress textarea switch chart
npm install convex @clerk/nextjs

3. Convex Provider の実装（Clerkキー未設定でもビルド可能にする）

src/components/providers/convex-client-provider.tsx は以下のように実装すること:

• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY が未設定またはプレースホルダの場合、ClerkProviderをスキップして子要素をそのまま返す
• クライアントサイドでのみClerkProviderをマウントする（useState + useEffect でマウント制御）
• これにより、Clerkのセットアップが完了していなくてもビルド＆静的ページが正常に動作する

// パターン:
const [mounted, setMounted] = useState(false);
useEffect(() => { setMounted(true); }, []);

if (!mounted || !isValidClerkKey(clerkPubKey)) {
  return <>{children}</>;
}

// ClerkProvider + ConvexProviderWithClerk でラップ

4. ダッシュボードのSSR対応

• src/app/dashboard/layout.tsx はServer Componentにして export const dynamic = "force-dynamic" を設定
• サイドバー等のClient Componentは別ファイル src/components/dashboard-shell.tsx に分離
• UserButton (Clerk) は dynamic(() => import("@clerk/nextjs").then(...), { ssr: false }) で読み込む

5. コード実装（ACPセッションで実装） ACPセッションへ以下を順に実装指示:

1. Convexスキーマ (convex/schema.ts)
2. Convex関数 (convex/ 内のqueries/mutations/actions)
3. convex/convex.config.ts — import { defineApp } from "convex/server"; const app = defineApp(); export default app;
4. レイアウト (src/app/layout.tsx) — Noto Sans JP、Provider
5. 全ページ実装 (src/app/ 配下)
6. コンポーネント (src/components/ 配下)
7. 必須ページ6つ (about/help/terms/privacy/legal/status)
8. SEO設定 (metadata, sitemap, robots)

6. 実装ルール

• shadcn/uiコンポーネントを最大活用
• any 型は絶対使わない
• Server Componentsを最大活用（"use client" は最小限）
• 元アプリのUI/UXを可能な限り完全再現
• 全テキスト日本語

---

Phase 5: テスト

1. ビルドテスト

cd ~/<project-name>
npm run build

2. 起動テスト

npm run dev

3. 機能テスト

• WebFetchで各ページにアクセスして表示確認
• TypeScriptエラーがゼロであること
• コンソールエラーがないこと

4. 修正ループ

• 問題発見 → 直接修正 → 再テスト → 全パスまで繰り返し

---

Phase 5.5: コード品質チェック

1. Biomeセットアップ & 実行

npx @biomejs/biome init
npx @biomejs/biome check --write .

2. any型の完全排除

grep -rn ': any' --include='*.ts' --include='*.tsx' src/
grep -rn 'as any' --include='*.ts' --include='*.tsx' src/

any が1つでもあれば直接修正。全ファイルで any ゼロになるまで繰り返す。

3. TypeScript strict チェック

• tsconfig.json の strict: true を確認
• npm run build でエラーゼロ

---

Phase 5.7: SEO対策実装

1. メタデータ（Next.js Metadata API）

• app/layout.tsx にグローバルメタデータ設定
• 各ページに個別metadata
• OGP設定 (locale: ja_JP)

2. 構造化データ（JSON-LD）

• トップページに Organization または WebApplication スキーマ

3. 技術的SEO

• app/sitemap.ts — 動的サイトマップ
• app/robots.ts — robots.txt
• next.config.ts でセキュリティヘッダー
• next/image でWebP自動変換
• セマンティックHTML

4. 日本語SEO

• <html lang="ja">
• ページタイトルに主要キーワード
• description は自然な日本語

---

Phase 6: セキュリティ調査

1. 依存パッケージ脆弱性

npm audit

2. 環境変数漏洩チェック

• .env が .gitignore に含まれているか
• ハードコードされたシークレットがないか

3. 認証・認可の確認

• 未認証ユーザーのアクセス制限
• API/Convex関数の認証チェック

4. 入力バリデーション

• XSS対策
• dangerouslySetInnerHTML の不正使用チェック

---

Phase 7: GitHub リポジトリ作成 & プッシュ

cd ~/<project-name>
gh repo create <project-name> --public --source=. --remote=origin
git add -A
git commit -m "初回リリース: <プロダクト名日本語>"
git push -u origin main

---

Phase 7.3: Convex セットアップ（自動・質問なし）

ユーザーに一切質問せず、自動で完了させること。

1. チームslugの自動取得 既存のConvexプロジェクトの .env.local から CONVEX_DEPLOYMENT の team: コメントを読み取ってチームslugを取得する:

# 既存プロジェクトからチームslugを検索
find ~/ -maxdepth 3 -name ".env.local" -exec grep -l "CONVEX_DEPLOYMENT" {} \; 2>/dev/null | head -1 | xargs grep "team:" | head -1

コメント部分から team: <slug> を抽出する。

2. Convexプロジェクト作成 & デプロイ

cd ~/<project-name>
npx convex dev --once --configure=new --team <team-slug> --project <project-name>

このコマンドで:

• 新規Convexプロジェクトが作成される
• .env.local に NEXT_PUBLIC_CONVEX_URL と CONVEX_DEPLOYMENT が自動書き込みされる
• スキーマと全Convex関数がデプロイされる

3. デプロイ確認

npx convex dev --once

エラーが出ないことを確認。

重要: このフェーズでユーザーに質問は一切しない。自動取得・自動実行する。

---

Phase 7.5: Vercelデプロイ

npx vercel --yes
npx vercel --prod

• 環境変数設定（Convex URL）
• デプロイ完了後、本番URLで表示確認
• 注意: この時点ではClerkの認証はまだ設定されていない。認証が必要なページ以外が正常に表示されることを確認する。

---

Phase 7.8: 品質改善ループ（最大20周）

┌─────────────────────────────────────────┐
│  改善ループ（1周 = 以下の全ステップ）     │
│                                         │
│  1. 本番URLをWebFetchで全画面確認       │
│  2. 問題リスト作成                       │
│  3. ACPのClaude Codeセッションで修正     │
│  4. git commit & push                   │
│  5. 問題が残っていれば → 1に戻る         │
│                                         │
│  問題ゼロになったら → Phase 8へ          │
└─────────────────────────────────────────┘

各周で確認する観点:

周回1: 基本動作 & UI品質

• 全ページアクセス可、リンク正常、レイアウト崩れなし
• Noto Sans JP統一、必須ページ6つ存在、フッターリンク

周回2: 機能 & UX品質

• ランディングページ→料金→必須ページ全フロー
• ローディング状態、エラー表示、レスポンシブ

周回3+: 本番品質 & セルフ改善

• OGP、サイトマップ、robots.txt、読み込み速度
• UX改善、デザイン改善、コピーライティング改善

終了条件: 自分が実際にユーザーとして使いたいと思えるレベル（認証フロー以外）

---

Phase 8: Clerk認証セットアップ

Clerk認証のセットアップを行う。Clerkダッシュボードでのアプリ作成、APIキー取得が必要。

1. Clerkアプリ作成 Clerkダッシュボード (https://dashboard.clerk.com) で新しいアプリを作成し、APIキーを取得する。

2. 環境変数の設定

# .env.local を更新
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=<actual-key>
CLERK_SECRET_KEY=<actual-key>

3. Convex環境変数にClerk Issuer URLを設定

4. Vercel環境変数の更新

npx vercel env rm NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY production -y
npx vercel env add NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY production <<< "<actual-key>"
npx vercel env rm CLERK_SECRET_KEY production -y
npx vercel env add CLERK_SECRET_KEY production <<< "<actual-key>"

5. 再デプロイ

npx vercel --prod --force

6. サインインページの動作確認 WebFetchで /sign-in ページにアクセスし、Clerkのサインインフォームが表示されることを確認。

---

Phase 9: 完了処理

1. references/built-products.md にプロダクト情報を追記
2. レポート出力:

# 海外トレンド → 日本ローカライズ レポート

## リサーチ結果
| # | Name | Category | Revenue | JP Competition | Score |
|---|------|----------|---------|----------------|-------|

## 選定プロダクト詳細分析
### [Product Name]
- **参考元アプリ**: [元アプリ名](URL)
- **概要**: ...
- **なぜ日本で成功できるか**: ...

## 開発成果物
- **プロジェクトパス**: ~/<name>
- **GitHub**: https://github.com/<user>/<repo>
- **Vercel本番URL**: https://<name>.vercel.app
- **Clerk認証**: セットアップ済み（Phase 8参照）