AGENTS.md
This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
Custom Instructions
Communication
- Primary Language: 日本語でのやりとりを基本とする (Use Japanese as the primary communication language)
External Content Management
- MCP Server Changes: MCPサーバーで外部コンテンツに変更を加える時は、必ず事前に確認をとること (Always seek confirmation before making changes to external content via MCP servers)
Git Commit Guidelines
- Commit Granularity: gitコミットは適切な粒度にわけて簡潔なコミットメッセージにより行うこと (Make git commits with appropriate granularity and concise commit messages)
Pull Requests（ベースブランチ）
- 既定のマージ先: 通常の開発用 PR は
devをベースにする（mainは本番相当のため、ここへ向けない）。ユーザーが別ブランチを明示したときのみ従う。 gh pr create: ベース未指定だとリポジトリ既定（多くの場合main）になりやすいので、必ず--base devを付ける（または GitHub 上でベースをdevに変更する）。
Communication Style
- Ask Questions: 指示が曖昧だったり、不明点・懸念点があれば遠慮なく質問・確認すること (Don't hesitate to ask questions or seek clarification when instructions are ambiguous or when there are unclear points or concerns)
Project Overview
YouTube Study Space is a 24/7 automated online study room livestreamed on YouTube. Users can join and leave virtual study sessions through YouTube live chat commands. The system supports both general seats and member-exclusive seats, tracks work time, and provides moderation and automation features.
Development Commands
Go Backend (system/)
# Run the main bot locally
go run main.go
# Run all tests with randomization
go test -shuffle=on -v ./...
# Run tests for a specific package
go test ./core/youtubebot/...
# Generate repository mocks
mockgen -source ./core/repository/interface.go -destination ./core/repository/mocks/interface.go -package mock_repository
# Update dependencies
go mod tidy
# Regenerate typed i18n wrappers
go generate ./...
Frontend (youtube-monitor/)
# Install dependencies
pnpm install
# Development server
pnpm dev
# Production build
pnpm build
# Production server
pnpm start
# Run tests
pnpm test
# Linting and formatting (using Biome)
pnpm format
pnpm lint
pnpm lint:fix
pnpm format:fix
# Storybook for component development
pnpm storybook
pnpm build-storybook
AWS Infrastructure (aws-cdk/)
# Install dependencies
pnpm install
# Preview infrastructure changes
pnpm cdk:diff
# Deploy infrastructure
pnpm cdk:deploy
# Build CDK code
pnpm build
# Run CDK tests
pnpm test
Documentation Site (docs-site/)
# Install dependencies
pnpm install
# Local development server
pnpm start
# Build static site
pnpm build
# Formatting and linting
pnpm format
pnpm lint
youtube-monitor/,aws-cdk/, anddocs-site/usepnpm(packageManager: pnpm@10.4.0).- Do not use
npmoryarnfor these directories unless explicitly required.
Architecture
High-Level Structure
system/- Go backend, scheduled jobs, and AWS Lambda entrypointsyoutube-monitor/- Next.js frontend for the study room interfaceaws-cdk/- AWS infrastructure as codedocs-site/- Docusaurus documentation site with i18n supportfirebase/- Firestore configuration
Core Architecture Patterns
Event-Driven Serverless:
- Every 1 minute:
youtube_organize_database+check_live_stream_status - Every 15 minutes:
update_work_name_trend - Daily at 00:00 JST: EventBridge Scheduler starts
start_daily_batch, which launches the Step Functions and Fargate daily batch flow
Multi-Database Strategy:
- Firestore: Real-time user sessions, room state, chat history, configuration
- DynamoDB: Configuration and secret lookup for Lambda-side operations
- BigQuery: Historical analytics and archival processing
- Cloud Storage: Transfer source for BigQuery import jobs
Command Processing Flow:
- YouTube Live Chat API retrieves messages
- Commands are parsed and validated
workspaceappprocesses seat, break, user, and moderation behavior- Firestore transactions persist state changes
- Replies and notifications are posted to YouTube Live Chat and Discord when needed
Key Components
Backend (system/core/):
workspaceapp/- Main application layer for command handling, presenters, validation, and batch jobsyoutubebot/- YouTube Live Chat API integrationrepository/- Firestore data access layerguardians/- Live stream monitoring and guard logicmoderatorbot/- Moderation and Discord notification integrationsmybigquery/- BigQuery transfer logici18n/- Locales and typed translation wrappers
Backend Entrypoints (system/):
main.go- Local live chat bot runnercmd/batch/- Daily batch executable for Fargateaws-lambda/- Lambda handlers such asyoutube_organize_database,check_live_stream_status,start_daily_batch,set_desired_max_seats, andupdate_work_name_trend
Frontend Architecture:
- Next.js with TypeScript
- Redux Toolkit for state management
- Emotion for CSS-in-JS styling
- SWR for data fetching
- Framer Motion for animations
- next-i18next for localization
Data Models
Core Entities
- SeatDoc: Seat information such as user ID, entry time, and work content
- UserDoc: User profiles and accumulated activity
- ConstantsConfigDoc: Runtime constants such as seat counts and polling settings
- CredentialsConfigDoc: Authentication and configuration references
State Management
- Firestore transactions ensure atomicity for seat assignment and updates
- User sessions persist across reconnections
- Frontend consumes real-time data via Firebase and SWR-based flows
Testing Strategy
Go Backend
- Standard Go testing with
testify - Mock generation using
go.uber.org/mock - Package-level tests around command parsing, repository behavior, and workspace flows
Frontend
- Jest with React Testing Library
- ts-jest for TypeScript support
- jsdom environment for DOM testing
- Component development and verification with Storybook
Infrastructure
- CDK unit tests for schedule and infrastructure invariants
- GitHub Actions CI/CD pipeline
Code Guidelines
Important Conventions
- Preserve
NOTEcomments: These contain important implementation details and should not be removed - Add review comments: Use
[NOTE FOR REVIEW]prefix for temporary explanatory comments - Error handling: Include contextual information in error messages
- Transaction safety: Use Firestore transactions for data consistency
Command System
Representative chat commands:
!in- General seat entry/in- Member seat entry!out- Exit seat!break/!rest/!chill- Start break!resume- End break!my- Show personal stats or update personal settings!rank- Display rankings!more/!okawari- Extend work time- Moderation:
!kick,!block
Internationalization
- Support for English, Japanese, and Korean locale files
- Message templates live under
system/core/i18n/ - Typed wrappers are generated from locale metadata with
go generate ./... - Frontend uses
next-i18next
Development Environment
Required Setup
- Go 1.25.0+ for backend development
- Node.js 18+ and
pnpmfor frontend and TypeScript-based subprojects - Google Cloud credentials for Firestore, Cloud Storage, and BigQuery access
- AWS credentials for Lambda, Step Functions, Scheduler, and CDK operations
- YouTube Data API credentials
Local Development
system/main.goruns the live chat bot locally- Install frontend dependencies with
pnpm installinyoutube-monitor/ - Start the frontend dev server with
pnpm devinyoutube-monitor/ - Start the frontend production server with
pnpm startinyoutube-monitor/on port18080 - Storybook runs on port
6006 - Use
.envfiles for local configuration
Deployment
- AWS Lambda functions are containerized with
system/Dockerfile.lambda - Daily batch jobs run on ECS Fargate via
system/Dockerfile.fargate - Daily orchestration is driven by EventBridge Scheduler and Step Functions
- Infrastructure changes are managed through
aws-cdk/
External Integrations
Google Services
- YouTube Data API v3: Live chat message retrieval and posting
- Firestore: Primary real-time datastore
- BigQuery: Analytics and history transfer target
- Cloud Storage: Export and transfer staging
AWS Services
- Lambda: Scheduled and on-demand compute
- EventBridge / EventBridge Scheduler: Periodic execution and daily scheduling
- Step Functions: Daily batch orchestration
- ECS Fargate: Daily batch runtime
- DynamoDB: Configuration storage for Lambda functions
- API Gateway: Authenticated REST API
Third-Party
- Discord: Notification webhooks for moderation and failures
- OpenAI API: Work name trend generation