Update instructions to agents on formatting (#1794)

Author: justin808

.gitignore

@@ -60,3 +60,6 @@ yalc.lock
 
 # Generated by ROR FS-based Registry
 generated
+
+# Claude Code local settings
+.claude/settings.local.json

CLAUDE.md

@@ -9,6 +9,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 1. **ALWAYS run `bundle exec rubocop` and fix ALL violations**
 2. **ALWAYS ensure files end with a newline character**
 3. **NEVER push without running full lint check first**
+4. **ALWAYS let Prettier handle ALL formatting - never manually format**
 
 These requirements are non-negotiable. CI will fail if not followed.
 
@@ -39,6 +40,31 @@ Git hooks will automatically run linting on **all changed files (staged + unstag
 - **Type checking**: `yarn run type-check`
 - **⚠️ MANDATORY BEFORE GIT PUSH**: `bundle exec rubocop` and fix ALL violations + ensure trailing newlines
 
+## ⚠️ FORMATTING RULES
+
+**Prettier is the SOLE authority for formatting. NEVER manually format code.**
+
+### Standard Workflow
+1. Make code changes
+2. Run `rake autofix` or `yarn start format`
+3. Commit changes
+
+### Merge Conflict Resolution Workflow
+**CRITICAL**: When resolving merge conflicts, follow this exact sequence:
+
+1. **Resolve logical conflicts only** - don't worry about formatting
+2. **Add resolved files**: `git add .` (or specific files)
+3. **Auto-fix everything**: `rake autofix`
+4. **Add any formatting changes**: `git add .`
+5. **Continue rebase/merge**: `git rebase --continue` or `git commit`
+
+**❌ NEVER manually format during conflict resolution** - this causes formatting wars between tools.
+
+### Debugging Formatting Issues
+- Check current formatting: `yarn start format.listDifferent`
+- Fix all formatting: `rake autofix`
+- If CI fails on formatting, always run automated fixes, never manual fixes
+
 ### Development Setup Commands
 
 - **Initial setup**: `bundle && yarn && rake shakapacker_examples:gen_all && rake node_package && rake`

docs/contributor-info/coding-agents-guide.md

@@ -350,7 +350,20 @@ git checkout HEAD~1 -- Gemfile package.json  # Rollback versions
 - Database warnings during `rails js:export` are usually non-fatal
 - Test builds don't require database connectivity
 
-### 6. Communication with Users
+### 6. Formatting Requirements
+
+**⚠️ CRITICAL**: Always use Prettier for formatting - never manually format code.
+
+**Merge conflict resolution workflow:**
+1. Resolve logical conflicts only (ignore formatting)
+2. `git add .` (or specific files)
+3. `rake autofix` (fixes all formatting + linting)
+4. `git add .` (if autofix made changes)
+5. Continue rebase: `git rebase --continue`
+
+**Never manually format during conflict resolution** - this causes formatting wars.
+
+### 7. Communication with Users
 
 When reporting status to users:
 
@@ -361,7 +374,7 @@ echo "⚠️  Note: Some TypeScript errors may be unrelated to react_on_rails"
 echo "🔗 Next steps: Test your application with 'bin/dev'"
 ```
 
-### 7. Documentation Updates
+### 8. Documentation Updates
 
 After successful upgrades, suggest:
 

docs/contributor-info/linters.md

@@ -27,6 +27,37 @@ npm run lint -- --fix
 
 Autofixing is a **HUGE** time saver!
 
+## Prettier
+
+[Prettier](https://prettier.io/) handles code formatting for JavaScript, TypeScript, CSS, and Markdown files.
+
+**⚠️ CRITICAL**: Prettier is the SOLE authority for formatting. Never manually format code.
+
+### Basic Usage
+
+```bash
+# Check formatting
+yarn start format.listDifferent
+
+# Fix formatting (includes all linters)
+rake autofix
+
+# Or format only
+yarn start format
+```
+
+### Merge Conflict Resolution
+
+When resolving merge conflicts, **NEVER manually format**. Follow this sequence:
+
+1. Resolve logical conflicts only
+2. `git add .` (or specific files)
+3. `rake autofix` (fixes all formatting + linting)
+4. `git add .` (if autofix made changes)
+5. Continue with `git rebase --continue` or `git commit`
+
+**Why this matters**: Manual formatting during conflict resolution creates "formatting wars" between tools and leads to back-and-forth formatting changes in PRs.
+
 ## ESLint
 
 See the [ESLint](https://eslint.org/) website for more information.