#302

AGENTS.md

@@ -12,16 +12,21 @@ BTRC Hub / タグ広場 is a split Rails API and React frontend repository.
 ## 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`.
+- 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.
+- 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/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.
@@ -89,7 +94,8 @@ npm run test:run
 npm run preview
 ```
 
-`npm run build` runs `tsc -b && vite build`, then `postbuild` runs `node scripts/generate-sitemap.js`.
+`npm run build` runs `tsc -b && vite build`, then `postbuild` runs
+`node scripts/generate-sitemap.js`.
 
 `npm run test` runs Vitest in watch mode. Use `npm run test:run` for a non-watch frontend test run.
 
@@ -102,36 +108,59 @@ npm run preview
 - 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.
+- Never write Ruby, TypeScript, or TSX lines longer than 99 characters.
+- Aim to keep Ruby, TypeScript, and TSX lines within 79 characters where practical.
+- TypeScript and TSX use 4-space logical indentation.
+- In TypeScript and TSX only, replace every leading run of 8 spaces with a tab.
+- Tabs are only for leading indentation, never for spaces after non-space text.
 - Do not add production dependencies without explicit approval.
 
 ## Backend rules
 
-- Inspect existing routes, controllers, models, services, and specs before editing backend behavior.
+- 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.
+- 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.
+- 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.
+- 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.
+- 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.
 
 ### Frontend TSX style
 
-- Preserve the local TSX formatting style. Do not normalize TSX to common Prettier-style React formatting unless explicitly asked.
+- Preserve the local TSX formatting style.
+- Do not normalize TSX to common Prettier-style React formatting unless
+  explicitly asked.
 - Prefer `const` arrow functions for TypeScript/TSX component and helper declarations.
-- Put two blank lines before and after top-level `const` function declarations, unless imports, exports, or file boundaries make that awkward.
-- In TSX, indent nested tag attributes with one tab relative to the tag line. With the project tab width, this visually appears as 4 spaces.
-- Keep a tag's closing marker on the same line as the final prop when the tag spans multiple lines. Do not put `/>` or `>` on its own line unless the existing surrounding code does so.
-- Keep JSX closing parentheses in the existing compact style, for example `</div>)` rather than moving `)` onto a separate line.
+- Put two blank lines before and after top-level `const` function
+  declarations, unless imports, exports, or file boundaries make that awkward.
+- In TSX, indent with 4-space logical indentation.
+- A leading tab is exactly equivalent to 8 leading spaces.
+- Keep a tag's closing marker on the same line as the final prop when the tag
+  spans multiple lines.
+- Do not put `/>` or `>` on its own line unless the existing surrounding code
+  does so.
+- Keep JSX closing parentheses in the existing compact style, for example
+  `</div>)` rather than moving `)` onto a separate line.
+- Do not add braces around `if`, `else`, or `for` bodies when the body is a
+  single physical line.
+- Always add braces around `if`, `else`, or `for` bodies when the body spans
+  two or more physical lines, even if it is one statement.
 
 Preferred:
 
@@ -164,10 +193,14 @@ function PostFormTagsArea ({ tags, setTags }: Props) {
 
 - 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`, `npm run lint`, and `npm run test:run`.
-- If backend code changes, run the relevant RSpec command; for broad backend changes, run `bundle exec rspec`.
+- 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`, `npm run lint`, and `npm run test:run`.
+- 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