Refactor AGENTS.md files to reference existing documentation

Copilot · hi-ogawa · Copilot · commit 1098fcb56e81 · 2025-09-07T07:46:00.000Z
Co-authored-by: hi-ogawa &lt;4232207+hi-ogawa@users.noreply.github.com&gt;
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,131 +1,56 @@
 # AI Agent Development Guide
 
-This document provides guidance for AI agents working with the vite-plugin-react monorepo.
+This document provides AI-agent-specific guidance for working with the vite-plugin-react monorepo. For comprehensive documentation, see:
 
-## Repository Structure
+- **[README.md](README.md)** - Repository overview and package links
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Setup, testing, debugging, and contribution guidelines
 
-This is a monorepo containing multiple Vite React plugins:
+## Quick Reference for AI Agents
 
-```
-packages/
-├── plugin-react/        # Main React plugin with Babel transformation
-├── plugin-react-swc/    # React plugin with SWC transformation
-├── plugin-react-oxc/    # Deprecated React plugin (merged with plugin-react)
-├── plugin-rsc/          # React Server Components plugin
-└── common/              # Shared utilities
-```
+### Repository Navigation
 
-## Development Workflow
+This monorepo contains multiple packages (see [README.md](README.md#packages) for details):
 
-### Prerequisites
+- `packages/plugin-react/` - Main React plugin with Babel
+- `packages/plugin-react-swc/` - SWC-based React plugin
+- `packages/plugin-rsc/` - React Server Components ([AI guidance](packages/plugin-rsc/AGENTS.md))
+- `packages/plugin-react-oxc/` - Deprecated (merged with plugin-react)
 
-- Node.js ^20.19.0 || >=22.12.0
-- pnpm (package manager) - version 10.15.0
-
-### Setup
+### Essential Setup Commands
 
 ```bash
-# Install dependencies
-pnpm install
-
-# Build all packages
-pnpm build
-
-# Start development mode (watch builds)
-pnpm dev
+pnpm install && pnpm build   # Initial setup (see CONTRIBUTING.md for details)
+pnpm dev                     # Watch mode development
+pnpm test                    # Run all tests
 ```
 
-### Key Commands
-
-```bash
-# Linting
-pnpm lint                # ESLint across all packages
-pnpm format              # Prettier formatting
-
-# Type checking
-pnpm typecheck           # TypeScript checking
-
-# Testing
-pnpm test                # Run all tests
-pnpm test-unit           # Unit tests only
-pnpm test-serve          # Development server tests
-pnpm test-build          # Build tests
-```
-
-## Important Files
-
-- `package.json` - Monorepo configuration and scripts
-- `pnpm-workspace.yaml` - Workspace configuration
-- `eslint.config.js` - ESLint configuration
-- `playground/` - Test applications for each plugin
-
-## Plugin-Specific Notes
-
-### @vitejs/plugin-react
-
-- Located in `packages/plugin-react/`
-- Uses Babel for transformation
-- Primary React plugin for Vite
-
-### @vitejs/plugin-react-swc
-
-- Located in `packages/plugin-react-swc/`
-- Uses SWC for faster transformation
-- Alternative to Babel-based plugin
-
-### @vitejs/plugin-rsc
-
-- Located in `packages/plugin-rsc/`
-- Experimental React Server Components support
-- See [packages/plugin-rsc/AGENTS.md](packages/plugin-rsc/AGENTS.md) for detailed guidance
-
-## Testing Guidelines
-
-Each package has its own test suite. The playground directory contains integration tests that verify plugin functionality in realistic scenarios.
-
-### Running Package-Specific Tests
-
-```bash
-# Test specific package
-pnpm --filter ./packages/plugin-react test
-pnpm --filter ./packages/plugin-rsc test-e2e
-```
-
-## Code Quality
-
-- Code is automatically formatted with Prettier on commit
-- ESLint enforces code quality and consistency
-- TypeScript provides type safety
-- All packages require tests for new features
+### AI-Specific Workflow Tips
 
-## Contributing
+1. **Start with existing documentation** - Always read package-specific READMEs before making changes
+2. **Use playground tests** - Each package has `playground/` examples for testing changes
+3. **Focus on minimal changes** - Prefer surgical edits over large refactors
+4. **Test early and often** - Run `pnpm test` after each logical change
+5. **Follow existing patterns** - Study similar implementations in the codebase first
 
-1. Follow the existing code style and patterns
-2. Add tests for new functionality
-3. Update documentation as needed
-4. Ensure all linting and tests pass
-5. Keep changes focused and atomic
+### Common Development Tasks
 
-## Common Tasks for AI Agents
+#### Making Changes to Plugin Logic
 
-### Adding a New Feature
+1. Read the package README and existing code patterns
+2. Use `pnpm dev` for watch mode during development
+3. Test changes with relevant playground examples
+4. Run tests: `pnpm test-serve` and `pnpm test-build`
 
-1. Identify the appropriate package
-2. Read existing code patterns
-3. Add implementation with proper TypeScript types
-4. Add comprehensive tests
-5. Update relevant documentation
+#### Debugging Build Issues
 
-### Debugging Issues
+1. Check individual package builds with `pnpm --filter ./packages/<name> build`
+2. Use playground tests to isolate problems
+3. See [CONTRIBUTING.md debugging section](CONTRIBUTING.md#debugging) for detailed guidance
 
-1. Check playground tests for reproduction cases
-2. Use `pnpm dev` for live development
-3. Run specific test suites to isolate problems
-4. Review build outputs and error messages
+#### Adding Tests
 
-### Performance Optimization
+1. Follow patterns in existing `__tests__` directories
+2. Use playground integration tests for feature verification
+3. See [CONTRIBUTING.md testing section](CONTRIBUTING.md#running-tests) for comprehensive testing guide
 
-1. Profile with `vite-plugin-inspect`
-2. Analyze bundle sizes in playground builds
-3. Test with various React application patterns
-4. Ensure backward compatibility
+For detailed development setup, testing procedures, and contribution guidelines, refer to [CONTRIBUTING.md](CONTRIBUTING.md).
diff --git a/packages/plugin-rsc/AGENTS.md b/packages/plugin-rsc/AGENTS.md
@@ -1,180 +1,54 @@
 # AI Agent Guide for @vitejs/plugin-rsc
 
-This document provides specific guidance for AI agents working with the React Server Components (RSC) plugin.
+This document provides AI-agent-specific guidance for the React Server Components (RSC) plugin. For comprehensive documentation, see:
 
-## Overview
+- **[README.md](README.md)** - Plugin overview, concepts, and examples
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Development setup and testing guidelines
 
-The `@vitejs/plugin-rsc` provides React Server Components support for Vite. It's built on the Vite environment API and enables:
+## Quick Reference for AI Agents
 
-- Framework-agnostic RSC bundler features
-- HMR support for both client and server components
-- CSS code-splitting and injection
-- Runtime-agnostic builds (works with various deployment targets)
+### Key Plugin Concepts
 
-## Key Concepts
+The RSC plugin creates three environments (see [README.md Basic Concepts](README.md#basic-concepts) for diagrams):
 
-### Environments
+- **rsc** - Server component rendering
+- **ssr** - Server-side rendering
+- **client** - Browser hydration
 
-The plugin creates three distinct environments:
-
-1. **rsc** - React server components rendering
-2. **ssr** - Server-side rendering environment
-3. **client** - Browser environment for hydration
-
-### Architecture
-
-```
-RSC Component → RSC Stream → SSR/Client Consumption → DOM/HTML
-```
-
-See [Basic Concepts](README.md#basic-concepts) in the README for detailed flow diagrams.
-
-## Development Workflow
-
-### Setup
+### Essential Commands
 
 ```bash
-# Build the plugin
-pnpm -C packages/plugin-rsc dev
-
-# Type checking
-pnpm -C packages/plugin-rsc tsc-dev
+pnpm -C packages/plugin-rsc dev       # Watch mode development
+pnpm -C packages/plugin-rsc test-e2e  # Run e2e tests
+pnpm -C packages/plugin-rsc test-e2e basic  # Test specific example
 ```
 
-### Testing
+### AI-Specific Development Tips
 
-```bash
-# Run all e2e tests
-pnpm -C packages/plugin-rsc test-e2e
-
-# Run with UI (interactive filtering)
-pnpm -C packages/plugin-rsc test-e2e --ui
+#### Making RSC Changes
 
-# Run specific test file
-pnpm -C packages/plugin-rsc test-e2e basic
+1. **Start with `examples/starter/`** - Best learning resource for understanding RSC flows
+2. **Use `examples/basic/` for testing** - Comprehensive test suite with routing
+3. **Test across all environments** - Verify rsc, ssr, and client functionality
+4. **Check virtual modules** - Important for RSC manifest and reference handling
 
-# Run with grep filter
-pnpm -C packages/plugin-rsc test-e2e -g "hmr"
-```
+#### Testing Patterns
 
-### Examples
+- **examples/basic** - Add test cases to `src/routes/`, update routing, add tests to `e2e/basic.test.ts`
+- **setupInlineFixture** - For isolated edge cases (see `e2e/ssr-thenable.test.ts` pattern)
 
-- `examples/starter/` - **Start here** - Comprehensive learning resource
-- `examples/basic/` - Advanced features and main e2e test suite
-- `examples/ssg/` - Static site generation example
-- `examples/react-router/` - React Router integration
-
-## Important Files
-
-### Core Plugin Files
+#### Important File Locations
 
 - `src/plugin.ts` - Main plugin implementation
 - `src/environment/` - Environment-specific logic
-- `src/types/` - TypeScript definitions
-- `types/` - External type definitions
-
-### Runtime APIs
-
-- `rsc/` - Server component runtime
-- `ssr/` - SSR runtime
-- `browser/` - Client runtime
-- `vendor/` - Vendored react-server-dom
-
-### Configuration
-
-- `vite.config.ts` - Development configuration
-- `tsdown.config.ts` - Build configuration
-- `playwright.config.ts` - E2E test configuration
+- `rsc/`, `ssr/`, `browser/` - Runtime APIs
+- `examples/` - Test applications and learning resources
 
-## Testing Patterns
-
-### Test Fixture Patterns
-
-1. **examples/basic** - Comprehensive test suite
-   - Add test cases to `src/routes/`
-   - Update routing in `src/routes/root.tsx`
-   - Add tests to `e2e/basic.test.ts`
-
-2. **setupInlineFixture** - Isolated edge case testing
-   - Best for specific scenarios
-   - See `e2e/ssr-thenable.test.ts` for pattern
-   - Dependencies managed in `examples/e2e/package.json`
-
-### Adding Tests
-
-```bash
-# Create new test project (automatically runnable)
-pnpm -C packages/plugin-rsc/examples/e2e/temp/my-test dev
-```
-
-## Common Development Tasks
-
-### Adding New RSC Features
-
-1. Understand the React Server Components specification
-2. Check existing implementation in `src/environment/`
-3. Add runtime support in appropriate environment
-4. Update type definitions
-5. Add comprehensive tests
-6. Update documentation
-
-### Debugging Issues
+### Debugging RSC Issues
 
 1. Use `examples/starter` for basic reproduction
-2. Check environment-specific builds in `.vite/`
-3. Examine RSC streams and manifests
-4. Test across all three environments
-5. Verify HMR behavior
-
-### Performance Optimization
-
-1. Analyze bundle outputs with metadata plugins
-2. Check CSS code-splitting effectiveness
-3. Monitor RSC payload sizes
-4. Test streaming performance
-
-## Key Plugin APIs
-
-### Virtual Modules
-
-- `virtual:vite-rsc/assets-manifest`
-- `virtual:vite-rsc/client-references`
-- `virtual:vite-rsc/server-references`
-- `virtual:vite-rsc/encryption-key`
-
-### Environment Helper API
-
-- `import.meta.viteRsc.loadCss()` - CSS loading
-- `?vite-rsc-css-export=<name>` - CSS exports
-
-### Runtime Modules
-
-- `@vitejs/plugin-rsc/rsc` - Server component rendering
-- `@vitejs/plugin-rsc/ssr` - SSR utilities
-- `@vitejs/plugin-rsc/browser` - Client-side RSC
-
-## Best Practices
-
-1. **Use setupInlineFixture for new tests** - More maintainable and faster
-2. **Follow existing patterns** - Check `examples/basic` for comprehensive examples
-3. **Test across environments** - Ensure functionality works in rsc, ssr, and client
-4. **Maintain backward compatibility** - RSC ecosystem is evolving rapidly
-5. **Document breaking changes** - Update CHANGELOG.md appropriately
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Module resolution errors** - Check `optimizeDeps.include` configuration
-2. **CSS not loading** - Verify `loadCss()` usage and environment setup
-3. **HMR not working** - Check component boundaries and environment isolation
-4. **Build failures** - Verify environment-specific configurations
-
-### Debugging Tools
-
-- Vite's built-in inspect plugin
-- Browser DevTools for client environment
-- Server logs for rsc/ssr environments
-- Playwright test inspector for e2e tests
+2. Check environment builds in `.vite/` directory
+3. Examine RSC streams and client/server manifests
+4. Verify HMR behavior across environments
 
-For more detailed contributing guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+For detailed setup, testing procedures, and architectural deep-dives, refer to the comprehensive documentation in [README.md](README.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
