Project Rito - 開発ガイドライン

プロジェクト概要

Ritoは、Bluesky（AT Protocol）のエコシステムに向けたブックマークおよびフィード管理システムです。モノレポ構成を採用しており、フロントエンド、バックエンド、Chrome拡張機能、およびカスタムレキシコンの定義を含みます。

技術スタック

• 共通: TypeScript, pnpm (Workspace)
• Frontend: Next.js (App Router), Martine, Vitest, Prisma
• Backend: Hono, Vitest
• Protocol: AT Protocol (Lexicons)

ディレクトリ構造と役割

• /backend: APIサーバー、データベーススキーマ、およびバックエンドロジック。
• /frontend: Next.js アプリケーション。XRPCの実装やUIコンポーネント。
• /lexicons: uk.skyblur.* などのカスタムレキシコン定義。

開発ルールと規約

1. パッケージ管理

• 必ず pnpm を使用してください。
• 依存関係の追加は、それぞれのディレクトリ（frontend や backend）で行ってください。

2. コマンド実行ルール

• ターミナルでコマンド（pnpm, git, wrangler など）を実行する際は、常に RTK.md の指示に従い、rtk をプレフィックスとして付与してください（例：rtk pnpm install）。
• 実行ディレクトリ: ルート直下で直接 pnpm test 等を実行せず、対象ディレクトリ（backend/ または frontend/）で実行してください。
• 型チェック:
  • backend: rtk pnpm run typecheck (tsc --noEmit) を使用してください。
  • frontend: rtk pnpm run build (Next.js Turbopack 型検証) を使用してください。
• 既知のコマンド制限（ESLintスキップ）:
  • frontend の pnpm lint は、TypeScript 7.0 と typescript-eslint 8.x の非互換によりエラー停止するため、上流ライブラリの対応までワークフロー内で実行をスキップしてください（型チェック・静的検査は Next.js ビルドで代替）。
• 共通コード同期（DRY）:
  • shared/logic/ が共有モジュールの単一情報源（Single Source of Truth）です。frontend / backend への同期は pnpm run sync:shared、検証は pnpm run verify:shared（またはテスト内）で行ってください。

3. AT Protocol / Lexicon

• uk.skyblur.* 名前空間 of レキシコンを尊重してください。
• レキシコンの変更は lexicons/ ディレクトリで行い、必要に応じて型定義を再生成してください。

4. テスト方針

• vitest を使用しています。
• 新機能やバグ修正の際は、必ず __tests__ ディレクトリに対応するテストを追加または更新してください。
• コマンド: pnpm test

5. 命名規則・スタイル

• 変数・関数名: camelCase
• クラス・コンポーネント名: PascalCase
• ファイル名: 基本的に内容に応じた camelCase または PascalCase (Reactコンポーネント)
• 思考プロセスは英語で行いますが、ユーザーへの応答やドキュメント（特に指定がない場合）は日本語で行います。

6. コミットログ

すべて日本語で記載する

• feat : 新機能
• fix : バグ修正
• lib : ライブラリの更新

特定のワークフロー

• OAuth: HandleOauthClientNode.ts など、BlueskyのOAuthフローの実装に注意を払ってください。

AIワークフロー自己改善サブエージェント

このプロジェクトでは、AIエージェントの作業そのものを観測し、改善対象として扱います。単発の実装だけでなく、作業プロセスを継続的に改善してください。

通常の開発タスクを開始するときは、必ずワークフロー自己改善専任のサブエージェントを起動してください。サブエージェントが利用できない実行環境では、その理由をユーザーに明示し、主担当が同等の観測・Issue化・改善レビューを代替してください。

サブエージェントの責務

• 主担当の実装方針とは独立して、作業プロセスの無駄、失敗、手戻り、検証不足、コスト増を観測してください。
• 主担当が実装を進めている間に、改善 Issue 候補、追加で必要な検証、次回以降の Skill 改善案をまとめてください。
• 完了前に、実装結果だけでなく「今回のワークフローが改善可能か」をレビューし、主担当へ短い報告を返してください。
• 報告には「観測」「Issue候補」「改善提案」「今回保存すべき ICM 内容」を含めてください。

1. 観測（Tracer）

• 作業開始前に ICM で関連する過去コンテキストを recall してください。
• サブエージェントは、実行時間、失敗したコマンド、再試行、テスト結果、ビルド結果、調査に時間がかかった箇所など、改善に使える事実を観測してください。
• 外部サービスや専用 Tracer が利用できる場合は、API呼び出し回数、サブエージェント数、コスト、待ち時間などを記録・可視化できる形にしてください。

2. Issue化

• サブエージェントが、繰り返し発生する失敗、手戻り、曖昧な仕様、検証不足、コスト増、作業時間の肥大化を発見した場合は、改善 Issue として扱ってください。
• Issue には「観測された事実」「影響」「再発条件」「改善案」「完了条件」を含めてください。
• GitHub Issue を作成しない場合でも、ICM に保存できる粒度で記録してください。

3. 調査・計画

• 改善に着手する前に、既存のルール、テスト、CI、デプロイ、スキル定義への影響を確認してください。
• 変更範囲を小さく保ち、既存の運用やユーザーの明示的な制約を壊さない計画にしてください。
• 実装計画には、検証方法とロールバックしやすい境界を含めてください。

4. 実装

• ワークフロー改善は、必要に応じて SKILL.md、テスト、スクリプト、CI、ドキュメント、プロンプト運用に反映してください。
• Claude Code、Codex など特定の実行環境に依存しすぎず、他のエージェントへ移植しやすい記述にしてください。
• 既存の開発ルール（RTK、ICM、テスト方針、UI維持、Lexicon生成ルール）を優先してください。

5. 検証

• 改善後は、対象ワークフローが実際に短く、確実に、再現しやすくなったかを確認してください。
• コード変更を伴う場合は、影響範囲に応じたテスト、型チェック、ビルドを実行してください。Next.js のビルドは必ず権限付きで実行してください。
• 主担当は、サブエージェントの報告を踏まえて、改善内容、検証結果、次回以降の注意点を ICM に保存してください。

7. UI/スタイルの変更制限

• 既存のUIコンポーネントを修正する際、明示的な指示がない限り、見た目やレイアウトに関する属性（radius, size, color, mt, variant 等）や CSS/スタイリングを変更してはなりません。
• 機能修正やロジック変更の際も、周囲 of 既存スタイルを厳格に維持してください。

優先事項

1. 既存UIの維持: 指示がない限り、ボタンの形状や余白などの視覚的要素を一切変更しないこと。
2. 型の安全性: TypeScriptの型定義を厳格に守り、any の使用を避けてください。
3. パフォーマンス: 特にフィードの取得や画像プロキシの処理において、効率的な実装を心がけてください。
4. セキュリティ: OAuthのクレデンシャルやセッション情報の扱いに細心の注意を払ってください。