btrc-hub/AGENTS.md

AGENTS.md

Project overview

BTRC Hub / タグ広場 is a split Rails API and React frontend repository.

• Backend: Rails API under backend/.
• Frontend: React + TypeScript + Vite under frontend/.
• Docs: lightweight command notes under docs/.
• There is no README or Makefile at the repository root as of this inspection.

Stack

• Backend: Ruby 3.2.2 from backend/.ruby-version, Rails ~> 8.0.2.
• Backend dependencies include mysql2, sqlite3, rspec-rails, factory_bot_rails, rack-cors, jwt, discard, gollum, whenever, aws-sdk-s3, brakeman, and rubocop-rails-omakase.
• Frontend: React ^19.1.0, TypeScript ~5.8.3, Vite ^6.3.5.
• Frontend data/UI dependencies include Axios, TanStack Query, Tailwind CSS, Framer Motion, Radix UI components, lucide-react, MDX/Markdown tooling, and Zustand.

Main directories

• backend/app/controllers: Rails API controllers.
• backend/app/models: Active Record models.
• backend/app/representations: API response representation classes.
• backend/app/services: domain services such as version recording, wiki commit, YouTube sync, and similarity calculation.
• backend/config/routes.rb: API routes.
• backend/db/migrate: migrations.
• backend/db/schema.rb: current schema snapshot.
• backend/lib/tasks: custom Rake tasks.
• backend/spec: RSpec tests.
• backend/test: Rails minitest files that still exist in the tree.
• frontend/src/App.tsx: frontend route definitions and initial user setup.
• frontend/src/pages: page-level React components.
• frontend/src/components: shared and feature components.
• frontend/src/lib: API client helpers, query keys, prefetchers, and domain helpers.
• frontend/src/stores: Zustand stores.
• docs/commands.md: command notes.

Commands

Only list commands that are backed by files inspected in this repository.

Backend

The following binstubs exist under backend/bin:

cd backend
bin/setup
bin/dev
bin/rails
bin/rake
bin/rubocop
bin/brakeman
bin/kamal
bin/thrust

Common Rails/Rake usage through existing binstubs:

cd backend
bin/rails db:prepare
bin/rails db:migrate
bin/rails routes
bin/rails server
bin/rake
bin/rubocop
bin/brakeman

RSpec is present in Gemfile and .rspec exists:

cd backend
bundle exec rspec

Frontend

The following npm scripts exist in frontend/package.json:

cd frontend
npm run dev
npm run build
npm run lint
npm run preview

npm run build runs tsc -b && vite build, then postbuild runs node scripts/generate-sitemap.js.

Do not write or report npm test as a repository command unless a test script is added to frontend/package.json.

Coding style

• Prefer precise, minimal changes.
• Do not flatter or over-explain.
• Explain risks directly.
• Prefer single quotes for strings unless interpolation or escaping makes double quotes better.
• Ruby: never put a space before method-call parentheses.
• Ruby: do not use %w or %i.
• TypeScript and Python: use GNU-style spacing before parentheses where syntactically valid.
• Do not add production dependencies without explicit approval.

Backend rules

• Inspect existing routes, controllers, models, services, and specs before editing backend behavior.
• For API behavior changes, add or update request specs under backend/spec/requests.
• Prefer RSpec for new backend tests; existing minitest files under backend/test do not make minitest the default for new coverage.
• Do not weaken authentication, BAN user checks, or IP BAN checks.
• Preserve the X-Transfer-Code user identification flow unless the task explicitly changes authentication.
• Be careful with version tables, version_no, optimistic concurrency, wiki revisions, and restore/diff behavior.
• Be careful with tag names, tag normalization, implications, similarities, and discard behavior.
• Keep migration files and backend/db/schema.rb consistent when changing schema.

Frontend rules

• Use frontend/src/lib/api.ts for API calls so headers and camelCase conversion stay consistent.
• Add or reuse TanStack Query keys through frontend/src/lib/queryKeys.ts; avoid ad hoc query key arrays.
• Encode URL path-segment values with encodeURIComponent.
• React hooks must be called unconditionally.
• Keep page-level code under frontend/src/pages and shared UI/feature code under frontend/src/components unless existing patterns point elsewhere.
• Match existing Tailwind, component, and import alias conventions.

Codex workflow

• First inspect existing patterns; do not invent new architecture when a local convention exists.
• Keep changes scoped to the requested issue.
• Do not scan or summarize dependency/generated/runtime directories such as node_modules, dist, tmp, log, and storage unless explicitly needed.
• Before touching wiki, tag, versioning, BAN, IP BAN, or authentication behavior, inspect the related request specs and service objects.
• If frontend code changes, run the existing frontend verification commands that apply: npm run build and npm run lint.
• If backend code changes, run the relevant RSpec command; for broad backend changes, run bundle exec rspec.
• If a verification command cannot be run or fails, report the exact command and failure.

Completion criteria

A task is complete only when:

• implementation is complete,
• relevant verification commands pass, or failures are clearly explained,
• unrelated files are not changed,
• migrations and schema are consistent when schema changes are made,
• user-facing behavior is documented when needed.