CLAUDE.md#

このファイルは、Claude Code (claude.ai/code) がこのリポジトリで作業する際のガイドラインを提供します。

プロジェクト概要#

LinkatはBlueskyアカウントを使用してリンク集を整理・共有できるWebアプリケーションです。ATProtocol/Blueskyエコシステムと深く統合されており、データはローカルとユーザーのPersonal Data Server (PDS)の両方に保存されます。

開発コマンド#

# ビルド
pnpm build            # プロダクションビルド

# テスト
pnpm test             # ユニットテスト実行
pnpm test -- app/models/board.spec.ts  # 特定のテストファイル実行

# コード品質
pnpm lint             # ESLintとPrettierチェック
pnpm format           # ESLint修正とPrettierフォーマット
pnpm typecheck        # TypeScript型チェック
pnpm all              # typecheck、format、testを全て実行

アーキテクチャ#

技術スタック#

• フレームワーク: React Router v7 (旧Remix)
• 言語: TypeScript
• データベース: PostgreSQL (Prisma経由)
• 認証: ATProtocol OAuth 2.0
• 状態管理: Jotai (トースト通知などのクライアント状態)
• スタイリング: Tailwind CSS
• テスト: Vitest (ユニット)、Playwright (E2E)

主要ディレクトリ#

• app/routes/: ページコンポーネントとAPIルート
• app/server/: サーバーサイドロジックとサービス
• app/features/: 機能別コンポーネント
• app/models/: データ検証用Zodスキーマ
• prisma/: データベーススキーマとマイグレーション

データフロー#

1. ユーザーデータは楽観的にローカルのPostgreSQLに保存
2. 変更はATProtoレコードとしてユーザーのBluesky PDSに同期
3. JetstreamがPDSの更新を監視してローカルDBに同期
4. ボードデータはblue.linkat.boardレキシコンスキーマに従う

ATProto統合#

• レコードはblue.linkat.boardコレクションに保存
• OAuthクライアント認証情報はDBに保存
• bsky.socialとセルフホストPDSインスタンスの両方をサポート
• Bluesky firehoseからのリアルタイム更新にJetstreamを使用

開発ガイドライン#

テスト#

• モデルとサービスのユニットテストはVitestで記述
• テストではPrismaモッククライアントを使用（自動設定済み）
• E2EテストはPlaywrightで複数ブラウザをサポート
• テストファイルはソースファイルと同じ場所に*.spec.tsとして配置

データベース変更#

# prisma/schema.prismaを変更した後
pnpm prisma migrate dev --name 変更内容の説明
pnpm prisma generate

環境変数#

必要な変数は.env.exampleに定義されています。主なもの：

• DATABASE_URL: PostgreSQL接続文字列
• PRIVATE_JETSTREAM_URL: JetstreamサービスURL
• ORIGIN: アプリケーションURL (開発環境: http://linkat.localhost:3000)

エラーハンドリング#

• 一貫したエラーハンドリングにはtryCatchユーティリティを使用
• サービスは見つからない場合nullを返す
• バリデーションエラーはZodスキーマで処理