技術系 Reddit 議論を収集し、AI で翻訳・要約して、テーマ別に読めるニュースサイト風サービスを構築するモノレポです。
このプロジェクトは、海外の技術系 Reddit 議論を対象に、 以下の流れを一気通貫で実現することを目的とします。
- Reddit から議論を収集する
- 生データを保存する
- AI で日本語翻訳・要約する
- テーマ別に記事として閲覧可能にする
- 管理画面から収集・再要約を運用できるようにする
対象テーマ:
- ソフトウェアエンジニアリング
- ローカル LLM
- 画像生成 AI
- AMD ROCm
- テーマ一覧表示
- テーマ別記事一覧表示
- 記事詳細表示
- 元スレタイトル
- 元 URL
- 日本語翻訳
- 日本語要約
- 主要論点
- 議論傾向ラベル
- Reddit 収集
- AI 要約
- 管理者向け収集実行
- 管理者向け再要約実行
- 基本的なジョブ履歴確認
- 一般ユーザー向けアカウント機能
- レコメンド
- ベクトル検索
- 課金
- 高度なランキング
- 複雑なソーシャル機能
詳細は docs/product/mvp-scope.md を参照してください。
- フロントエンド
- Next.js
- React
- Redux Toolkit
- バックエンド
- Go
- ワーカー
- Go
- API
- gRPC を主軸
- REST は管理者用・補助用途に限定
- スキーマ
- Protocol Buffers
- DB
- MySQL（MVP）
- インフラ
- AWS ECS
- RDS
- S3
- CloudFront
- WAF
- CI/CD
- GitHub Actions
- 監視
- CloudWatch
- Sentry
- AI
- OpenAI 互換 API
.
├── AGENTS.md
├── README.md
├── apps/
│ ├── web/
│ ├── api/
│ └── worker/
├── packages/
│ ├── proto/
│ ├── schemas/
│ └── openapi/
├── infra/
│ ├── compose/
│ ├── docker/
│ └── terraform/
├── docs/
│ ├── adr/
│ ├── architecture/
│ ├── development/
│ ├── operations/
│ └── product/
└── .ai/
├── prompts/
├── evals/
└── skills/
役割:
apps/web- 公開 UI / 管理 UI
apps/api- Go gRPC サーバー
- 一部 REST エンドポイント
apps/worker- 収集 / 要約 / 再試行ジョブ
packages/proto- Protocol Buffers 定義
packages/schemas- AI 出力や補助スキーマ
infra/compose- ローカル Docker 開発環境
infra/terraform- AWS IaC
docs/- 設計・運用・スコープ文書
.ai/- AI エージェント向け資産
補足:
- 上記は想定構成であり、現時点で未作成のディレクトリも含む
packages/openapiは将来 REST 補助用途や公開仕様が必要になった場合の候補として確保している
- モノレポで Web / API / Worker / IaC / docs / AI 資産を一元管理する
- gRPC を主軸とし、内部契約は
.protoを正本として扱う - REST は管理者用・補助用途に限定する
- 生データ、正規化データ、AI 生成データを分離して保存する
- AI プロバイダは抽象化層の背後に置く
trace_idを API / Worker / LLM 呼び出しの相関キーにする- AGENTS.md は短い入口資料に留め、詳細は docs/ と
.ai/に分離する
詳細は以下を参照してください。
docs/architecture/overview.mddocs/architecture/api.mddocs/architecture/data-model.mddocs/architecture/observability.mddocs/development/coding-rules-common.mddocs/development/coding-rules-frontend.mddocs/development/coding-rules-backend.mddocs/development/code-review-checklist.mddocs/adr/architecture-decisions.md
このリポジトリでは、AGENTS.md は短い入口資料として保ち、
詳細な設計・運用・AI ワークフローは docs/ と .ai/ に分離しています。
AGENTS.md- AI エージェント向けの入口資料
docs/product/mvp-scope.md- MVP の範囲
docs/architecture/overview.md- 全体構成
docs/operations/local-development.md- ローカル開発手順
docs/architecture/overview.mddocs/architecture/api.mddocs/architecture/data-model.mddocs/architecture/observability.md
docs/development/coding-rules-common.mddocs/development/coding-rules-frontend.mddocs/development/coding-rules-backend.mddocs/development/code-review-checklist.md
docs/plans/- 進行中プランと完了済みプランの入口
- 完了済みは
docs/plans/Complete/
docs/adr/architecture-decisions.md
.ai/prompts/README.md.ai/evals/README.md.ai/skills/proto-schema-review/SKILL.md.ai/skills/prompt-regression-check/SKILL.md.ai/skills/reddit-ingestion-debug/SKILL.md.ai/skills/cloudwatch-log-search/SKILL.md
AGENTS.mddocs/product/mvp-scope.mddocs/architecture/overview.mddocs/development/coding-rules-common.mddocs/operations/local-development.md
標準導線は Docker Compose です。
cp infra/compose/.env.example infra/compose/.env
make compose-config
docker compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.override.yml --env-file infra/compose/.env up -d --build mysql
make migrate
make seed
docker compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.override.yml --env-file infra/compose/.env up -d web api worker確認先:
http://127.0.0.1:3000http://127.0.0.1:8080/healthz
補足:
- Web は
CONTENT_API_BASE_URLを server-side env として読み、Compose 内ではhttp://api:8080に接続する - MySQL volume が残っていると
.envの初期化値を変えても再初期化されない - 詳細手順は
docs/operations/local-development.mdとinfra/compose/README.mdを参照する
docs/development/coding-rules-common.mddocs/development/coding-rules-frontend.mddocs/plans/docs/development/code-review-checklist.md
docs/development/coding-rules-common.mddocs/development/coding-rules-backend.mddocs/development/code-review-checklist.md
docs/architecture/api.mddocs/adr/architecture-decisions.md.ai/skills/proto-schema-review/SKILL.md
.ai/prompts/README.md.ai/prompts/.ai/skills/prompt-regression-check/SKILL.md.ai/evals/README.md
docs/architecture/data-model.md.ai/skills/reddit-ingestion-debug/SKILL.md.ai/skills/cloudwatch-log-search/SKILL.md
フロントエンド先行フェーズでは、
apps/web を App Router 前提で実装しつつ、
API 通信をモックで置き換えて UI を先に進めてもよいです。
補足:
- API 全モックの初期実装プランは
docs/plans/を参照する - 完了したプランの記録は
docs/plans/Complete/を参照する - モック方式は
apps/web側で閉じ、本番依存コードへ漏らさない
基本的な流れ:
cp infra/compose/.env.example infra/compose/.env
make migrate
make seed
make up
make test-goローカル開発の詳細は docs/operations/local-development.md を参照してください。
- 実装前に短い作業計画を提示し、承認を得てから着手する
- 可能な限りテストファーストで進める
- 実装後は必ずセルフレビューを行う
- MVP 範囲を勝手に広げない
- proto / prompt / schema を変更した場合は関連文書と評価資産も更新する
詳細は AGENTS.md を参照してください。
コーディングルールの詳細は以下を参照してください。
docs/development/coding-rules-common.mddocs/development/coding-rules-frontend.mddocs/development/coding-rules-backend.mddocs/development/code-review-checklist.md
このリポジトリでは、人間と AI エージェントの両方が 同じ文書体系で開発できることを重視します。
方針:
AGENTS.md- 入口
docs/- 詳細設計と運用文書
.ai/prompts/- プロンプト資産
.ai/evals/- 回帰評価資産
.ai/skills/- 反復作業の標準手順
この構成により、 短い入口資料・詳細設計・再利用可能な作業手順を分離し、 AI エージェントと人間の両方が同じ文書体系で開発できる状態を目指します。
- 主処理は gRPC を優先する
.protoを契約の正本とする- proto 変更時は生成コード、実装、テスト、文書を合わせて更新する
- 互換性を意識し、破壊的変更は慎重に扱う
詳細は以下を参照してください。
docs/architecture/api.md.ai/skills/proto-schema-review/SKILL.md
- プロンプト資産は
.ai/prompts/に配置する - 評価資産は
.ai/evals/に配置する - プロンプト変更時は
prompt_versionと評価資産を更新する - 出力 shape を変える場合は schema と UI の影響を確認する
詳細は以下を参照してください。
.ai/prompts/README.md.ai/evals/README.md.ai/skills/prompt-regression-check/SKILL.md
- topic clustering
- source adapter の追加
- 複数 LLM provider 対応
- CockroachDB 検証
- ベクトル検索
- 管理画面強化
- article view 最適化