Digitaltableteur

 _____   _______
|  __ \ |__   __|
| |  | |   | |
| |  | |   | |
| |__| |   | |
|_____/    |_|

Digitaltableteur

「完璧さよりも反復を重視しましょう。今日リリースし、明日学び、いつまでも磨き続けます。」

Digitaltableteur は、Next.js 16（本番環境）と Vite（レガシー）のアプリケーションを備えた、ハイブリッドなモノレポのポートフォリオ Web サイトです。React 19 と TypeScript 6.x で構築されており、包括的なデザインシステム、多言語サポート（EN/FI/SV）、AI 搭載のチャットインターフェースに加え、Sentry によるオブザーバビリティ、Linear による課題管理、MCP（Model Context Protocol）統合などのエンタープライズ級のツールを提供します。

🚀 特徴

コアアーキテクチャ

• ハイブリッドモノレポ：Next.js 16 App Router（本番環境）と Vite 6.4（レガシー）を並行して移行中
• AI ドキュメントシステム：AI アシスタントに最適化された階層型 CLAUDE.md/AGENTS.md 構造
• デザインシステム：CSS Modules、デザイントークン、Storybook、ビジュアルリグレッションテストを備えた 50 以上のコンポーネント
• 型安全性：包括的なインターフェースと JSDoc ドキュメントを備えた TypeScript 6.x の厳格モード

ユーザー体験

• 多言語サポート：英語、フィンランド語、スウェーデン語に対応した完全な i18n（翻訳カバー率 100%）
• AI チャットインターフェース：ガイド付きメールワークフロー、動的なコンポーネント挿入、Markdown レンダリングを備えた OpenAI 搭載のチャット
• レスポンシブデザイン：モバイルファーストの段階的な機能強化（backdrop-filter、gap、:has() セレクター）
• プログレッシブウェブアプリ：サービスワーカーによるキャッシュ、オフラインサポート、ネイティブ共有 API との統合
• アクセシビリティ：axe-core テスト、セマンティック HTML、ARIA 属性、キーボード操作に対応した WCAG AA 準拠

コンテンツとメディア

• ブログプラットフォーム：MDX、シンタックスハイライト、読了時間の推定機能を備えた Sanity CMS 統合
• 安全な CV ダウンロード：API 検証とレート制限によるパスワード保護
• 画像最適化：Next.js Image コンポーネント、遅延読み込み、レスポンシブな srcset 生成
• お問い合わせ統合：ガイド付きの複数ステップワークフロー、検証、アクセシビリティに対応した EmailJS

開発者体験

• Storybook 10：WIP バッジシステムとビジュアルリグレッションテストを備えたコンポーネント開発
• テスト：Vitest + Testing Library（カバレッジ目標 >80%）、アクセシビリティテスト、Playwright による E2E テスト
• MCP 統合：AI 支援開発のための GitHub、Figma、Context7、TypeScript LSP、Sentry
• Linear の自動化：プログラムによる課題の作成・更新、ラベル管理、状態ワークフロー
• Sentry オブザーバビリティ：エラー追跡、パフォーマンス監視、リリースの健全性、MCP クエリインターフェース

パフォーマンスと SEO

• コード分割：React.lazy()（Vite）と next/dynamic（Next.js）による動的インポート
• バンドル最適化：ツリーシェイキング、圧縮、コンテンツハッシュによる積極的なキャッシュ無効化
• SEO：generateMetadata() による動的メタデータ、sitemap.xml、robots.txt、構造化データ
• アナリティクス：プライバシー制御を備えた Google Analytics 4 統合

🏁 はじめに

前提条件

• Node.js 18+（LTS 推奨）
• npm 9+ または互換性のあるパッケージマネージャー

インストール

# Clone repository
git clone https://github.com/PetriLahdelma/digitaltableteur.git
cd digitaltableteur

# Install dependencies
npm install

# Copy environment template
cp .env.example .env.local

環境設定

開発に必要です：

# Analytics
VITE_GA_ID=G-XXXXXXXXXX                      # Google Analytics 4

# Email Services
VITE_EMAILJS_SERVICE_ID=service_xxx
VITE_EMAILJS_TEMPLATE_ID=template_xxx
VITE_EMAILJS_PUBLIC_KEY=xxx

# MCP Servers (optional for enhanced AI features)
FIGMA_TOKEN=figd_xxx                         # Figma design access
GITHUB_MCP_PAT=github_pat_xxx               # GitHub operations
CONTEXT7_API_KEY=xxx                         # Context7 documentation access

# Linear Issue Management (optional)
LINEAR_API_KEY=lin_api_xxx
LINEAR_TEAM_ID=xxx
LINEAR_PROJECT_ID=xxx

# Akaunting Accounting (optional, self-hosted)
[email protected]
AKAUNTING_API_PASSWORD=xxx
AKAUNTING_COMPANY_ID=1

本番環境のみ：

CV_PASSWORD=xxx                              # Secure resume download
OPENAI_API_KEY=sk-xxx                        # AI chat functionality
SENTRY_DSN=https://[email protected]/xxx
SENTRY_AUTH_TOKEN=xxx                        # Source map upload

説明付きの完全な一覧については .env.example を参照してください。

⚒️ 開発

開発サーバー

# Next.js dev server (production app)
npm run dev                    # http://localhost:3001

# Storybook component development
npm run storybook              # http://localhost:6010

コード品質とテスト

# Type checking
npm run typecheck              # TypeScript validation across project

# Linting
npm run lint                   # ESLint + Stylelint
npm run lint:fix               # Auto-fix linting issues

# Testing
npm test                       # Run all tests (Vitest)
npm run test:watch             # Watch mode
npm run test:coverage          # Coverage report (>80% target)
npm run test:a11y              # Accessibility tests (axe-core)
npm run test:visual            # Visual regression (Playwright + Storybook)

# Pre-commit validation (run before PR)
npm run typecheck && npm run lint && npm test && npm run build

MCP と自動化

# GitHub MCP Server
npm run github:mcp:test        # Test connectivity and authentication

# Figma MCP Server
npm run figma:mcp:test         # Test connectivity and authentication

# Context7 MCP Server
npm run context7:mcp           # Launch locally (respects CONTEXT7_API_KEY)
npm run context7:mcp -- --remote-check  # Test remote endpoint

# TypeScript LSP Status
npm run ts:mcp:status          # Validate TypeScript language server
npm run ts:mcp:status:stub     # Generate stub status

# Linear Issue Management
npx tsx scripts/linear/create-issue.ts              # Interactive issue creation
npx tsx scripts/linear/update-issue.ts --issue DIG-16 --state "Done"
npx tsx scripts/linear/check-issue.ts DIG-16        # Display issue details

# Sentry Observability
node scripts/sentry-mcp.js issues digitaltableteur 10 --unresolved
npm run generate-sentry-summary                      # Generate dashboard data

🏗 ビルドとデプロイ

ビルドコマンド

# Next.js production build
npm run build                  # Output: .next/

# Storybook static build
npm run build-storybook        # Output: storybook-static/

デプロイ

# Vite to GitHub Pages
npm run deploy                 # Build + gh-pages deployment

# Vite + Storybook visual diffs
npm run deploy-with-storybook  # Deploy with visual regression report

# Manual cache busting
npm run cache-bust             # Add version metadata + .nojekyll

# Vercel (production - automatic on push to main)
vercel --prod

ハイブリッドデプロイ戦略：

• Vite アプリ：GitHub Pages（https://digitaltableteur.com）
• Next.js アプリ：Vercel（https://nextjs-app.vercel.app）
• サーバーレス関数：Vercel（/api/* ルート）
• ルーティング：Vercel のリライトで特定のパスを Next.js に転送します（vercel.json を参照）

ビルドの最適化

Vite ビルド：

• コンテンツハッシュを付与した、ツリーシェイキング済みの JavaScript バンドル
• ベンダープレフィックスと論理プロパティを適用した、ミニファイ済み CSS
• 圧縮済みの画像とフォント
• オフラインキャッシュ用のサービスワーカー（Workbox）
• ファイル名のハッシュ化による積極的なキャッシュ無効化

Next.js ビルド：

• SEO 向けのサーバーサイドレンダリング（SSR）
• ブログ投稿の静的生成
• Next.js Image コンポーネントによる画像の最適化
• Vercel サーバーレス関数としての API ルート
• ルートごとの自動コード分割

🤖 AI ドキュメントシステム

階層構造

このプロジェクトでは、AI アシスタント向けに最適化された階層型 CLAUDE.md/AGENTS.md システムを使用しています。

Root Documentation (Universal Rules)
├── CLAUDE.md (380 lines)          # Comprehensive authority for Claude Code
├── AGENTS.md (150 lines)          # Quick reference for generic agents
└── .github/copilot-instructions.md  # GitHub Copilot specific

Subdirectory Documentation (Specific Context)
├── app/CLAUDE.md + AGENTS.md      # Next.js App Router patterns
├── shared/components/CLAUDE.md + AGENTS.md  # Component library rules
├── api-legacy-vercel-functions/AGENTS.md    # Serverless patterns
├── docs/AGENTS.md                 # Documentation navigation
└── scripts/AGENTS.md              # Automation patterns

Claude Code Configuration
├── .claude/settings.json          # Hooks (auto-format, safety checks)
└── .claude/commands/              # Custom slash commands
    ├── review.md                  # Comprehensive code review
    ├── fix-issue.md               # GitHub issue workflow
    ├── create-component.md        # Component generation
    └── create-linear-issue.md     # Issue creation

主な機能

CLAUDE.md（Claude Code の権限ファイル）

• ファイルあたり 200～400 行
• 不変のシステムルールとして扱われます
• 階層的に読み込まれます（CWD から上位へ移動し、サブディレクトリも検出します）
• ファイルの例を含む包括的なパターン

AGENTS.md（汎用 AI クイックリファレンス）

• ファイルあたり 100～200 行
• 検索コマンドを使った JIT（Just-In-Time）インデックス作成
• 重複を最小限に抑え、効率を最大化
• コピーしてすぐに使えるコマンド

Claude Code の機能強化

• フック：自動フォーマット（Prettier）、危険なコマンドのブロック
• カスタムコマンド：/review、/fix-issue、/create-component、/create-linear-issue
• トークン効率：一枚岩のドキュメントと比べて、クエリごとに 60～80% 削減

使用方法

Claude Code（自動）：

/review                         # Comprehensive code review
/fix-issue 123                  # Analyze and fix GitHub issue
/create-component Button        # Generate component (5 files)
/create-linear-issue Implement X  # Create Linear issue

汎用 AI エージェント（手動で参照）：

cat AGENTS.md                           # Root rules
cat app/AGENTS.md                       # Next.js patterns
cat shared/components/AGENTS.md         # Component rules

ドキュメント：

• 移行ガイド
• システム概要
• ビジュアルツリー

🎨 デザインアセットの管理

Figma デザインの取得

生のデザインデータが必要な場合は、Figma ファイルを JSON としてダウンロードできます。 個人用アクセストークンを使って FIGMA_TOKEN 環境変数を設定し、次を実行してください。

npm run fetch-figma

API を使用して Figma からデザイントークンとアセットを同期します。 ファイルはプロジェクトのルートに figma.json として保存されます。

SEO とコンテンツの生成

npm run generate:sitemap    # Generate XML sitemap
npm run generate:llms       # Create LLM-friendly content index
npm run generate:alt-text   # Generate accessibility descriptions (requires OPENAI_API_KEY)

generate:alt-text はローカル画像のバイトデータを OpenAI Vision API にストリーミングし、実際のアートワークを説明できるようにします。実行前に .env.local に OPENAI_API_KEY（必要に応じて OPENAI_ALT_MODEL）を追加するか、--force を付けて実行すると、すべての <img> の alt 属性が再生成されます。

Sanity でのブログ公開

クイック公開ワークフロー：

# Publish single article from Sanity
npm run sanity:publish-single <article-slug>

# Publish all articles
npm run sanity:publish

• 自動公開ワークフローの全容については、docs/SANITY_PUBLISHING_AUTOMATION.md を参照してください。
• 移行ワークフロー全体については、docs/SANITY_MIGRATION.md を参照してください（React → Sanity は sanity:parse-posts / sanity:convert / sanity:upload 経由、Sanity → MDX は sanity:sync-from-remote 経由、リダイレクトの生成、クリーンアップ用ヘルパー）。

🏗 アーキテクチャ

ハイブリッドモノレポ構造

digitaltableteur/
├── app/                       # Next.js 16 App Router (production)
│   ├── layout.tsx             # Root layout with providers
│   ├── page.tsx               # Home page (server component)
│   ├── about/page.tsx         # Route pages
│   ├── blog/[slug]/page.tsx   # Dynamic routes
│   └── api/*/route.ts         # API routes (Vercel functions)
│
├── src/                       # Vite app (legacy, being phased out)
│   ├── App.tsx                # React Router configuration
│   ├── pages/                 # Route components (to be migrated)
│   └── components/            # Component library
│
├── shared/                    # Symlinked shared code
│   ├── components/            # Design system (from src/components)
│   ├── hooks/                 # Custom React hooks
│   ├── styles/                # Design tokens & global styles
│   └── locales/               # i18n translation files
│
├── api-legacy-vercel-functions/  # Serverless functions
│   ├── cors.js                # CORS middleware
│   ├── openai-chat.js         # AI chat endpoint
│   ├── save-contact.js        # Contact form handler
│   └── download-cv.js         # Secure CV download
│
├── scripts/                   # Automation & tooling
│   ├── linear/                # Issue management
│   ├── sentry-mcp.js          # Observability queries
│   └── generate-*.js          # Code generation
│
├── docs/                      # Documentation
│   ├── LLM_COMPONENT_GENERATION_RULES.md (12,000+ words)
│   ├── NEXTJS_MIGRATION_PLAN.md
│   ├── LINEAR_AUTOMATION.md
│   └── *_MCP_SETUP.md         # MCP integration guides
│
└── .claude/                   # Claude Code configuration
    ├── settings.json          # Hooks (auto-format, safety)
    └── commands/              # Custom slash commands

技術スタック

フロントエンド

• React 19：並行機能、Suspense、自動バッチ処理
• TypeScript 6.x：厳格モード、デコレーター、インポート属性
• Next.js 16.2.x：App Router、サーバーコンポーネント、ストリーミング SSR
• Vite 6.4：超高速 HMR、最適化された本番ビルド
• React Router 7：遅延読み込みによるクライアント側ルーティング（Vite アプリ）

スタイリングとデザイン

• CSS Modules：一貫した命名規則によるスコープ付きスタイリング
• デザイントークン：src/styles/variables.css の CSS カスタムプロパティ
• プログレッシブエンハンスメント：最新機能向けの @supports クエリ
• 論理プロパティ：margin-inline、padding-block（RTL 対応）
• レスポンシブデザイン：ブレークポイントシステムによるモバイルファースト設計

状態とデータ

• React Hooks：useState、useEffect、useContext、カスタムフック
• i18next：React バインディングによる国際化
• EmailJS：問い合わせフォームからのメール配信
• OpenAI API：関数呼び出し機能を備えた GPT-4 チャット

バックエンドサービス

• Vercel Serverless：CORS ミドルウェアを備えた Node.js 関数
• GitHub Pages：カスタムドメインによる静的サイトホスティング
• Sanity CMS：ヘッドレスブログコンテンツ管理
• Sentry：エラー追跡とパフォーマンス監視

開発者ツール

• Storybook 10：コンポーネントの開発とドキュメント作成
• Vitest：jsdom 環境での単体テスト
• Testing Library：ユーザー中心のテストユーティリティ
• Playwright：Storybook 経由のビジュアルリグレッションテスト
• ESLint + Stylelint：コード品質の維持
• Prettier：一貫したコードフォーマット

AI と自動化

• MCP（Model Context Protocol）：GitHub、Figma、Context7、TypeScript LSP
• Linear API：プログラムによる課題管理
• Sentry REST API：可観測性クエリとダッシュボード
• Claude Code：AI ペアプログラミング向けのカスタムコマンドとフック

📱 コンポーネントの機能

ネイティブ共有機能との統合

SocialShare コンポーネントは、Web Share API を使用したプログレッシブエンハンスメントを実装しています。

ネイティブ共有のサポート

• モバイルデバイスで Web Share API が利用可能かどうかを検出します
• デバイスのネイティブ共有シートを使ったシームレスな共有を提供します
• 利用できない場合は、クリップボードへのコピーに適切にフォールバックします

レスポンシブデザイン

• モバイルデバイスではコンパクトに表示できるアイコンのみのモード
• デスクトップ環境ではボタンのテキスト全体を表示
• 他のソーシャルメディアアイコンとの適切な配置

プログレッシブエンハンスメント

• navigator.share が利用可能かどうかを機能検出します
• クリップボードへのコピー機能に自動的にフォールバックします
• 再試行の仕組みを備え、共有に失敗した場合のエラーを処理します

アクセシビリティ

• ネイティブ共有とコピーの両方の操作に ARIA ラベルを設定します
• キーボードナビゲーションをサポートします
• 適切な role 属性により、スクリーンリーダーで利用しやすくします

ブラウザーのサポート

• 最新のモバイルブラウザー：ネイティブ共有機能
• デスクトップブラウザー：クリップボードへのコピーにフォールバック
• レガシーブラウザー：標準のクリップボードコピー動作

この実装は、適切なエラー処理を備えた Web Share API のベストプラクティスに従っており、あらゆる種類のデバイスで一貫したユーザー体験を提供します。

⚙️ テストと品質

テストスタック

npm test                         # Run all tests
npm run test:watch               # Watch mode
npm run test:coverage            # Generate coverage reports
npm run test:a11y                # Accessibility testing
npm run test:visual              # Visual regression tests
npm run test:visual:update       # Update visual baselines

テストスイートのカバレッジ：

• 単体テスト：コンポーネントの動作、props、状態管理（カバレッジ要件は 80% 超）
• 統合テスト：チャットのワークフロー、メールフォーム、ナビゲーションパターン
• アクセシビリティテスト：すべてのページと Storybook のストーリーで axe-core を使用
• ビジュアルリグレッション：Storybook test-runner 経由の Playwright スクリーンショット
• 翻訳カバレッジ：EN/FI/SV にすべての i18n キーが存在することを確認

テストライブラリ：

• Vitest + jsdom：React をサポートする高速な単体テスト
• Testing Library：ユーザー中心のコンポーネントテスト
• axe-core：自動アクセシビリティ監査
• Playwright：ビジュアルリグレッションと E2E 機能

コード品質

npm run lint                     # ESLint + Stylelint
npm run lint:fix                 # Auto-fix linting issues
npm run format                   # Prettier formatting
npm run typecheck                # TypeScript validation

品質基準：

• ESLint：TypeScript 厳格モード、React のベストプラクティス、a11y ルール
• Stylelint：CSS Modules の標準、論理プロパティの使用を徹底
• Prettier：2 スペースのインデント、シングルクォート、末尾のカンマ
• TypeScript：暗黙の any を禁止、厳格な null チェック、未使用変数を禁止

可観測性

Sentry との統合：

npm run sentry:issues            # Query unresolved issues
npm run sentry:releases          # List recent releases
npm run generate:sentry-summary  # Generate JSON summary

MCP のテスト：

npm run github:mcp:test          # Test GitHub MCP connectivity
npm run figma:mcp:test           # Test Figma MCP connectivity
npm run ts:mcp:status            # Validate TypeScript LSP

コンポーネント開発

Storybook：

npm run storybook                # Launch Storybook dev server
npm run build-storybook          # Build static Storybook
npm run storybook:deploy         # Deploy to GitHub Pages

WIP バッジシステム：

• すべてのストーリーに、デフォルトでローカライズされた「作業中」バッジが表示されます
• 次の条件を満たした後、parameters: { wip: { disabled: true } } でバッジを削除します：
  • ✅ アクセシビリティテスト（axe-core の違反数 = 0）
  • ✅ ビジュアルリグレッション（予期しない差分なし）
  • ✅ 翻訳の網羅性（EN/FI/SV のすべてのキー）

🌐 国際化

このサイトは、翻訳が完全に網羅された3つの言語に対応しています：

• 英語（EN）：すべてのコンテンツを網羅した主要言語
• フィンランド語（FI）：ネイティブ言語に対応
• スウェーデン語（SV）：地域言語に対応

構成：

• 翻訳ファイル：nextjs-app/shared/locales/{en,fi,sv}/translation.json
• 保守しやすい名前空間構成
• テストにより翻訳の網羅率100％を必須化

使用方法：

• ユーザーに表示するテキストは、必ずuseTranslation()フックでラップしてください
• "navigation.home"のようなネストされたオブジェクト表記を使用して整理してください
• マージする前に、3つのロケールファイルをすべて同時に更新してください

🔐 セキュリティとパフォーマンス

セキュリティ対策：

• パスワード保護されたコンテンツ配信
• .env.local（Git による追跡対象外）を使用した環境ベースの設定
• 厳密なオリジン検証を備えた CORS 対応 API エンドポイント
• ユーザー入力のサニタイズと XSS 対策
• バージョン管理システムにシークレットを保存しないでください（.gitignoreを参照）

パフォーマンスの最適化：

• 動的インポートと React.lazy() によるコード分割
• 画像の最適化と遅延読み込み
• サービスワーカーによるキャッシュ戦略（Vite アプリ）
• バンドル分析とツリーシェイキング
• Brotli/Gzip による圧縮アセットの配信
• キャッシュ無効化のための積極的なファイル名ハッシュ化

🚀 ビルドとデプロイ

本番ビルド

Next.js アプリ：

npm run build                    # Build Next.js app (production)
npm run start                    # Start Next.js production server

Vite アプリ（レガシー）：

npm run build                    # Vite production build
npm run preview                  # Preview Vite production build
npm run cache-bust               # Manual cache busting

デプロイ戦略

ハイブリッドデプロイ：

• Vercel：Next.js アプリとサーバーレス API 関数をホスト

  • mainブランチから自動デプロイ
  • 環境変数は Vercel のダッシュボードで管理
  • 認証、API ルート、Webhook 用のエッジ関数

• GitHub Pages：レガシー Vite アプリと Storybook をホスト

  • npm run deployによる手動デプロイ
  • カスタムドメイン：digitaltableteur.com
  • ハッシュ化されたファイル名による積極的なキャッシュ無効化

デプロイコマンド：

npm run deploy                   # Deploy Vite app to GitHub Pages
npm run deploy-with-storybook    # Deploy with visual diff report
npm run storybook:deploy         # Deploy Storybook standalone
npm run generate:sitemap         # Generate sitemap.xml

キャッシュ戦略

Vite ビルド：

• JS/CSS アセットのファイル名を自動でハッシュ化
• 手動のキャッシュ無効化スクリプトでバージョン情報を追加
• .nojekyllファイルにより GitHub Pages の Jekyll 処理を防止

Next.js ビルド：

• アセットのハッシュ化と最適化を標準搭載
• Cache-Controlヘッダーはnext.config.tsで設定
• Vercel CDN がキャッシュの無効化を処理

環境変数

本番環境（Vercel）：

• すべてのシークレットを Vercel プロジェクトの設定に保存
• プレビュー環境と本番環境を分離
• クライアント側の変数にはNEXT*PUBLIC*プレフィックスを自動で付与

本番環境（GitHub Pages）：

• 公開環境変数を GitHub Secrets に保存
• デプロイワークフローでビルド時に変数を注入
• サーバー側のシークレットなし（静的ホスティングのみ）

🚀 CI/CD パイプライン

GitHub Actions：

• 自動テスト：すべての PR で ESLint、Stylelint、Vitest を実行
• プレビューデプロイ：プルリクエストごとにステージング環境を自動作成
• 本番デプロイ：ビルドとキャッシュ無効化を自動実行

ブランチ保護：

• コード品質に関するステータスチェックを必須化
• mainブランチでは1件の承認が必須
• マージ時にコミットをスカッシュ
• マージ後にブランチを削除

🤝 コントリビューション

開発ガイドライン

• TypeScript：新しいコンポーネントや関数には、すべて厳密な型付けを使用してください
• CSS Modules：デザイントークンを使用する既存のパターンに従ってください（インラインスタイルは使用しないでください）
• 国際化：ユーザー向けのすべてのテキストに翻訳を追加してください（EN/FI/SV）
• コンポーネントの作成：まず docs/LLM_COMPONENT_GENERATION_RULES.md を必ず読んでください
• Storybook：すべてのコンポーネントに .stories.tsx を含めてください
• テスト：テストカバレッジを80％超に保ち、アクセシビリティテストを含めてください
• ドキュメント：CLAUDE.md、AGENTS.md、README.md、copilot-instructions.mdを同時に更新してください

ワークフロー

1. リポジトリをフォークします
2. ブランチを作成：docs/BRANCH_NAMING.md の命名規則に従います

   git checkout -b DT-XXX-feat-description
   

3. 開発：上記の規約に従って変更を加えます
4. 品質チェック：

   npm run typecheck && npm run lint && npm test && npm run build
   

5. コミット：Conventional Commits形式を使用します

   git commit -m "feat: add amazing feature"
   

6. プッシュ：ブランチにプッシュします

   git push origin DT-XXX-feat-description
   

7. プルリクエスト：詳細な説明を添えてPRを作成します
8. レビュー：フィードバックに対応し、CIがパスすることを確認します
9. マージ：マージ時にコミットをスカッシュし、その後ブランチを削除します

コミット前チェックリスト

PRを作成する前に、以下を確認してください。

• ✅ すべてのテストがパスする（npm test）
• ✅ TypeScriptエラーがない（npm run typecheck）
• ✅ lintの問題がない（npm run lint）
• ✅ 本番ビルドが成功する（npm run build）
• ✅ 翻訳がすべて揃っている（EN/FI/SV）
• ✅ 新しいコンポーネントにStorybookストーリーが追加されている
• ✅ UIを変更した場合、ビジュアルベースラインが更新されている（npm run test:visual:update）
• ✅ ドキュメントが更新されている（README、CLAUDE.md、AGENTS.md）

📁 フォルダーの概要

• src/ – アプリケーションのソースコード
• public/ – 静的アセットとHTMLテンプレート
• .storybook/ – Storybookの設定ファイル
• dist/ – コンパイル済みの本番ビルド（npm run build の実行後に生成）
• node_modules/ – npmでインストールされたプロジェクトの依存関係

📚 詳細情報

プロジェクトのドキュメント

AIドキュメントシステム：

• 移行ガイド - CLAUDE.md/AGENTS.mdの階層に関する完全ガイド
• システム概要 - 統計情報とファイルの概要
• ビジュアルツリー - ドキュメント構造を示すASCII図
• ルートのCLAUDE.md - Claude Code向けの包括的な規範
• ルートのAGENTS.md - 汎用AIエージェント向けクイックリファレンス

重要なリファレンス：

• コンポーネント生成ルール - コンポーネント作成に関する12,000語超の規範
• 批判的思考と計画 - 計画のワークフロー
• Next.js移行計画 - ViteからNext.jsへの移行戦略
• Linearの自動化 - CLIスクリプト、AIを活用した課題の受付、MCP統合
• LinearとVS Codeの統合 - 拡張機能のセットアップ、ハイブリッドワークフロー、キーボードショートカット
• GitHub MCPのセットアップ - GitHub MCP サーバーの設定
• Figma MCPのセットアップ - Figma MCP サーバーの設定

セットアップとガイド：

• Storybookのデプロイ - ビジュアルリグレッションのセットアップ
• ブランチの命名 - ブランチの命名規則
• Sanityの移行 - ブログの移行ワークフロー

技術ドキュメント

フロントエンド：

• React 19 - UI フレームワーク
• Next.js 16 - App Router を備えた React フレームワーク
• Vite - ビルドツールおよび開発サーバー
• TypeScript - 型安全性
• React Router - クライアントサイドルーティング（Vite アプリ）

スタイリングとデザイン：

• CSS Modules - スコープ化された CSS
• Storybook - コンポーネント開発
• Figma - デザインファイルとトークン

国際化：

• i18next - i18n フレームワーク
• react-i18next - React バインディング

テストと品質：

• Vitest - 単体テスト
• Testing Library - コンポーネントテスト
• Playwright - ビジュアルリグレッション
• axe-core - アクセシビリティテスト

バックエンドとデプロイ：

• Vercel - Next.js ホスティングとサーバーレス
• GitHub Pages - 静的サイトホスティング
• Sanity - ヘッドレス CMS
• Sentry - エラートラッキング

自動化と AI：

• Linear API - 課題管理
• MCP - Model Context Protocol
• Claude Code - AI ペアプログラミング

✉️ メール送信のチャットワークフロー

チャットインターフェースには、自然な言い回しをきっかけに始まる、ガイド付きの複数ステップのメール作成ワークフローが含まれています。起動方法は 2 種類あります。

1. 一般的な意図（例：「メールを送って」「メールの送信を手伝って」／FI／SV の表現）→ アシスタントがローカライズされた chatEmailSendPhrase を挿入し、メール作成を促します。
2. 単純なキーワード（単独の「email」／「sähköposti」／「epost」）→ アシスタントがローカライズされた chatEmailSimplePhrase を挿入し、[email protected] を表示してから、作成を始めるか尋ねます。

どちらも同じ reducer 駆動のフローに合流します。異なるのは最初の言い回しだけです。単純なキーワードによる方法では、アンカー付き正規表現を使うため、「I like email workflows」のような文中での偶発的な言及は無視されます。

起動と検出

messageProcessor.ts は、多言語の正規表現マッチに基づいて、2 つの保留フラグ（pendingEmailWorkflowGeneral または pendingEmailWorkflowSimple）のいずれかを設定します。ChatWidget は次のアシスタントターンでフラグを 1 つだけ消費し、フレーズキー（chatEmailSendPhrase または chatEmailSimplePhrase）を挿入して、ワークフロー UI をインラインでマウントした後、フラグをリセットします。

ステートマシンの概要

Reducer ファイル：src/components/ChatWidget/emailWorkflow/reducer.ts 型定義：src/components/ChatWidget/emailWorkflow/types.ts

状態（簡略版）：

• idle – ワークフローがアクティブではない状態
• compose – 最初の自由形式の意図の入力（件名／目的）
• fields – 構造化された項目を順番に収集する状態（名前、メールアドレス、電話番号（任意）、メッセージ本文）
• review – ユーザーが集約された下書きを確認し、任意の項目を編集できる状態
• sending – 非同期送信の進行中（aria-busy が適用されます）
• success – 確認と概要を表示する状態
• error – 再試行および編集のオプションがあるエラー状態

遷移は決定論的に検証されます。編集すると、データを保持したまま fields に戻ります。キャンセルすると、問題なく idle にリセットされます。

コンポーネント

• ComposePrompt – 最初の意図／件名を入力
• FieldPrompt – 現在の必須項目の入力欄を、検証のヒントとともに表示
• ReviewSummary – 送信前に収集したすべての項目を要約
• SendStatus – 送信中、成功、またはエラーのフィードバックを表示

すべてのコンポーネントは src/components/ChatWidget/emailWorkflow/ にあり、.stories.tsx と .test.tsx によるカバレッジを備えた標準的なパターンに従っています。スタイリングには既存のデザイントークンと CSS Modules を使用し、アクセシブルなラベルと説明には i18n キーを使用しています。

検証とサービスの抽象化

• contactValidation.ts – 共通のフィールドバリデーター（名前、メールアドレスの形式、メッセージの長さ、任意の電話番号）
• contactEmailService.ts – EmailJS の送信ラッパー。型付きエラー（EmailServiceError）をスローし、詳細な再試行メッセージを可能にします

環境変数

開発用 .env に次の項目を追加します（Vite 用のプレフィックスが必要です）。

VITE_EMAILJS_SERVICE_ID=<your_service_id>
VITE_EMAILJS_TEMPLATE_ID=<your_template_id>
VITE_EMAILJS_PUBLIC_KEY=<***REMOVED***>

これらはワークフローと従来の問い合わせフォームで使用されます。変数が不足している場合、送信アクションは安全に無効化されます（エラー状態がユーザーに表示されます）。

国際化

ユーザーに表示されるワークフローのテキストには、すべて emailWorkflow.* キーのプレフィックスが使われます（例：emailWorkflow.compose.heading、emailWorkflow.fields.name.label、emailWorkflow.status.success.title）。マージ前に、3つのロケールファイル（en、fi、sv）すべてを更新してください。更新しないと、翻訳カバレッジテストが失敗します。

アクセシビリティ

• 各プロンプトではセマンティックなフォームコントロールを使用し、htmlFor でラベルを関連付けます
• 送信中の状態では、ローカライズされた進行状況テキストとともに role="status" と aria-busy="true" を適用します
• エラー状態では、明確なフォーカス順序で再試行アクションを提示し、キーボードトラップが発生しないようにします
• スクリーンリーダーで内容を明確に把握できるよう、レビューリストには構造化マークアップ（定義リストまたはグループ化した段落）を使用します

テスト要件

• レデューサーの単体テスト：編集とキャンセルを含む、すべての主要な遷移（compose -> fields -> review -> sending -> success/error）
• 統合テスト：一般的なフロー（emailWorkflow.integration.test.tsx）と簡単なキーワードフロー（emailWorkflow.simpleTrigger.test.tsx）
• i18n カバレッジ：すべてのロケールに emailWorkflow.* キーが存在すること
• ビジュアルリグレッション：各状態の Storybook スナップショット（レイアウトを変更した場合は、意図的に更新します）
• アクセシビリティテスト：ワークフローのストーリーとページに axe の違反がないこと

拡張ガイドライン

フィールドの追加や任意の添付ファイルに対応するには、次の手順に従います。

1. EmailDraft 型とバリデーターに新しいフィールドを追加します
2. レデューサーにフィールドステップのロジックを追加します（進行順序が重要です）
3. emailWorkflow.fields.<fieldName>.* の下に新しい文字列をローカライズします
4. ReviewSummary の表示処理とテストを更新します
5. ビジュアルベースラインと翻訳カバレッジを更新します

既にローカライズされているコンテンツを壊さないよう、既存のフィールドの意味を変更するよりも、機能を追加する変更を優先してください。

メンテナンス

アーキテクチャまたはトリガーの動作を変更する場合は、必ずこの README、.github/copilot-instructions.md、CLAUDE.md、docs/donny-chat.md を同時に更新してください。

🛡️ 可観測性の自動化

自動スクリプトは、実行時の API 呼び出しなしに UI コンポーネント（サマリーカードなど）や Storybook ダッシュボードで使用される、軽量な JSON アーティファクトを生成します。

• Sentry サマリー：public/observability/sentry-summary.json（scripts/generate-sentry-summary.mjs または scripts/sentry-mcp.js コマンドで生成）
• TypeScript MCP ステータス：public/observability/ts-mcp-status.json（scripts/ts-mcp-automation.mjs で生成）

コマンド

npm run ts:mcp:status       # Perform LSP handshake and write status JSON
npm run ts:mcp:status:stub  # Force stub status JSON (no handshake)

Sentry サマリースクリプトは、プロジェクトとフィルターのオプション（未解決の本番環境の問題）を指定して実行します。認証情報がない場合はスタブモードを利用できます。UI ではバッジによってスタブデータを識別します。

統合に関する注意事項

• SentrySummaryCard は Sentry の JSON を読み込み、ローカライズされた読み込み中、エラー、空の状態を表示します
• 今後の可観測性コンポーネントも、同じ疎結合のパターン（ビルド時またはオンデマンドでの JSON 生成と、純粋なレンダリング）に従ってください
• 翻訳キー（observability.sentry.*、今後の observability.ts.*）を各ロケール間で同期してください

メンテナンス要件

可観測性のスキーマが変更される場合（フィールドの追加、プロパティ名の変更など）は、README、.github/copilot-instructions.md、CLAUDE.md を同時に更新してください。新しい状態（スタブの検出、追加メタデータの表示など）をカバーするテストを追加または調整する必要があります。

🤖 MCP ツール

Donny のサーバーレスチャットハンドラーは、mcp.json で宣言されたすべての MCP サーバーを自動的に読み込みます。ローカルの TypeScript 言語サーバーと Sentry ヘルパーに加えて、このリポジトリにはホスト型の Context7 MCP サーバーが含まれるようになりました。これにより、アシスタントのプロンプトから会話を離れることなく、最新のフレームワークやライブラリのドキュメントを取得できます。

• mcp.json の "context7" エントリーは https://mcp.context7.com/mcp を参照し、Context7-API-Key ヘッダーを送信します（値は CONTEXT7_API_KEY から解決されます）。匿名または低頻度での利用の場合は、環境変数を設定しないでください。
• ローカルでのデバッグ用に、便利なランナーを利用できます。
  npm run context7:mcp -- [optional flags]
  • ホスト型 Context7 MCP エンドポイントに ping を送るには、--remote-check を追加します。ヘルパーは CONTEXT7_API_KEY を使って Context7-API-Key ヘッダーを自動的に追加します。
• より高いレート制限とプライベートライブラリへのアクセスを利用するには、.env.local またはシェルのプロファイルに CONTEXT7_API_KEY を設定します（シークレットは Vercel のプロジェクト環境変数に保存されています）。--api-key を手動で渡さない限り、スクリプトがキーを自動的に追加します。
• Context7 を支える REST API は https://context7.com/api/v1 にあります。ダッシュボード以外でアカウントのステータスを確認したり、キーを管理したりする場合は、このベース URL を使用してください。

api/donny-tools.ts は各ツールを <server>.<toolName> として命名するため、接続時に Context7 の機能は context7.* 名前空間の下に表示されます。これにより、後続のプロンプトで明示的に指定でき、必要に応じて設定ブロックを削除するだけでサーバーを簡単に無効化できます。

GitHub MCP サーバー

公式 GitHub MCP サーバーは、AI ツールに GitHub プラットフォームの機能への直接アクセスを提供します。

• mcp.json の "github" エントリーは https://api.githubcopilot.com/mcp/ を参照し、Authorization: Bearer ヘッダーを送信します（値は GITHUB_MCP_PAT から解決されます）。
• セットアップが必要です：GitHub Settingsで GitHub Personal Access Token を作成し、環境変数 GITHUB_MCP_PAT を設定してください。
• 利用可能なツールセット：リポジトリ操作、イシュー管理、プルリクエスト、GitHub Actions、コードセキュリティなど
• 設定をテストするには、npm run github:mcp:test を実行します。
• 詳細なセットアップガイド：docs/GITHUB_MCP_SETUP.md

主な機能：

• リポジトリの閲覧とファイル操作
• イシューとプルリクエストの管理
• GitHub Actions のワークフロー監視
• コードセキュリティ分析と Dependabot アラート
• チームでの共同作業と組織の管理

接続時に GitHub の機能は github.* 名前空間の下に表示され、一貫した明示的なツール命名パターンを維持します。

Figma MCP サーバー

figma-developer-mcpは、デザインからコードへのワークフローで、AI ツールに Figma のデザインプラットフォームへの直接アクセスを提供します。

• mcp.json の "figma-developer-mcp" エントリーは、http://localhost:3333/sse で SSE サーバーとして実行されます。
• セットアップが必要です：Figma Settingsで Figma Personal Access Token を作成し、環境変数 FIGMA_TOKEN を設定してください。
• サーバーの管理：MCP の機能を使用する前に、npx figma-developer-mcp で起動してください。
• 設定をテストするには、npm run figma:mcp:test を実行します。
• 詳細なセットアップガイド：docs/FIGMA_MCP_SETUP.md

主な機能：

• デザインファイルの分析とコンポーネントの抽出
• アセットのダウンロードとデザイントークンの抽出
• デザインシステムのドキュメント化と一貫性の確認
• デザインからコードへの生成と実装ガイダンス
• 共同デザインワークフローとの統合

接続時に Figma の機能は figma.* 名前空間の下に表示されるため、AI アシスタントはデザインファイルを操作し、Figma のデザインから実装コードを直接生成できます。

関連ドキュメント

• ブランチ命名ガイドライン