mirror of
https://github.com/RooVetGit/Roo-Code.git
synced 2026-09-05 08:10:14 +00:00
refactor: clean up AGENTS.md files to only include non-obvious patterns
- Reduced main AGENTS.md from 65 to 21 lines - Reduced .roo/rules-code/AGENTS.md from 39 to 11 lines - Reduced .roo/rules-debug/AGENTS.md from 40 to 13 lines - Reduced .roo/rules-ask/AGENTS.md from 39 to 8 lines - Reduced .roo/rules-architect/AGENTS.md from 42 to 10 lines Removed all obvious information like standard commands, framework defaults, and common patterns. Files now only contain truly non-obvious, project-specific gotchas discovered by reading the actual code.
This commit is contained in:
Hannes Rudolph
parent
2581fcc8bf
commit
8db9d2f7d7
5 changed files with 40 additions and 203 deletions
|
|
@ -1,42 +1,10 @@
|
|||
# Architect Mode Rules
|
||||
|
||||
## Design Principles
|
||||
## Non-Obvious Architecture Constraints
|
||||
|
||||
- **VSCode Extension Architecture**: Work within VSCode's webview + extension host model
|
||||
- **Monorepo Organization**: Maintain clear separation between packages
|
||||
- **Provider Pattern**: New AI providers must follow existing interface patterns
|
||||
- **State Management**: React hooks for UI, VSCode context for extension state
|
||||
|
||||
## Package Structure Requirements
|
||||
|
||||
- New packages go in `packages/` directory
|
||||
- Must include proper TypeScript configuration extending base
|
||||
- Shared types belong in `packages/types/src/`
|
||||
- Follow existing naming conventions (e.g., @roo-code/package-name)
|
||||
|
||||
## API Design
|
||||
|
||||
- All providers implement Provider interface from packages/types
|
||||
- IPC messages must be strongly typed
|
||||
- Backwards compatibility required for existing provider contracts
|
||||
- Error handling must include proper error types and recovery
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- Large JSON operations must use streaming (see safeWriteJson)
|
||||
- Webview content should lazy-load heavy components
|
||||
- Code indexing happens asynchronously in background
|
||||
- Terminal operations should not block UI
|
||||
|
||||
## Evals Database & Migrations
|
||||
|
||||
- Evals database schemas in `packages/evals/src/db/`
|
||||
- Migrations required for schema changes
|
||||
- Use proper transaction handling for data consistency
|
||||
|
||||
## Security Patterns
|
||||
|
||||
- Never expose sensitive data in webview
|
||||
- API keys stored in VSCode SecretStorage
|
||||
- File operations must validate paths
|
||||
- Command execution requires user approval
|
||||
- Providers MUST be stateless - hidden caching layer assumes this
|
||||
- Webview and extension communicate through specific IPC channel patterns only
|
||||
- React hooks required because external state libraries break webview isolation
|
||||
- Large JSON operations must use `safeWriteJson()` for streaming (prevents memory issues)
|
||||
- TypeScript `noUncheckedIndexedAccess: true` - array/object access may return undefined
|
||||
- Import paths in packages/ require `.js` extensions despite TypeScript source
|
||||
|
|
|
|||
|
|
@ -1,39 +1,8 @@
|
|||
# Ask Mode Rules
|
||||
|
||||
## Documentation Sources
|
||||
## Non-Obvious Documentation Context
|
||||
|
||||
- Main documentation: README.md, CONTRIBUTING.md, CHANGELOG.md
|
||||
- API docs: Check provider implementations in `src/api/providers/`
|
||||
- UI patterns: Reference `webview-ui/src/components/` for React components
|
||||
- Types: Refer to `packages/types/src/` for TypeScript interfaces
|
||||
|
||||
## Code Examples
|
||||
|
||||
- Provider examples: Each provider in `src/api/providers/` shows implementation patterns
|
||||
- Test examples: `src/__tests__/` and `webview-ui/src/**/*.test.tsx`
|
||||
- IPC patterns: `packages/ipc/src/` for communication examples
|
||||
- Custom modes: Check `.roo/rules-*/` directories for mode-specific patterns
|
||||
|
||||
## Architecture Explanations
|
||||
|
||||
- **Monorepo Structure**:
|
||||
- `src/` - VSCode extension backend
|
||||
- `webview-ui/` - React frontend
|
||||
- `packages/` - Shared libraries
|
||||
- `apps/` - Additional applications
|
||||
- **Webview Architecture**: VSCode extension hosts React app via webview API
|
||||
- **Provider Pattern**: All AI providers implement common interface for consistency
|
||||
- **IPC Communication**: Typed messages between extension and webview
|
||||
|
||||
## Command References
|
||||
|
||||
- Build commands: See `package.json` scripts section
|
||||
- Test commands: Must run from workspace directory with package.json
|
||||
- Development: F5 launches extension in new VSCode window
|
||||
- VSIX packaging: `pnpm vsix` creates installable package
|
||||
|
||||
## Localization
|
||||
|
||||
- i18n files in `locales/` directory
|
||||
- Extension uses vscode.l10n API for translations
|
||||
- Webview uses i18next for React component translations
|
||||
- `src/` contains VSCode extension code, NOT generic source (counterintuitive naming)
|
||||
- Two separate i18n systems: root `locales/` for extension, `webview-ui/src/i18n/` for UI
|
||||
- Provider examples in `src/api/providers/` are canonical reference (docs may be outdated)
|
||||
- Webview runs in VSCode context with restrictions (no localStorage, limited browser APIs)
|
||||
|
|
|
|||
|
|
@ -1,39 +1,10 @@
|
|||
# Code Mode Rules
|
||||
|
||||
## JSON File Operations
|
||||
## Critical Non-Obvious Patterns
|
||||
|
||||
- **MANDATORY**: Use `safeWriteJson()` from `src/utils/safeWriteJson.ts` for ALL JSON writes
|
||||
- Never use `JSON.stringify` with direct file writes - always use `safeWriteJson`
|
||||
- `safeWriteJson` handles directory creation, atomic writes, and locking automatically
|
||||
|
||||
## Provider Implementation
|
||||
|
||||
- All new providers MUST implement the Provider interface from `packages/types/src/`
|
||||
- Provider implementations go in `src/api/providers/`
|
||||
- Each provider needs proper error handling and retry mechanisms
|
||||
|
||||
## UI Component Guidelines
|
||||
|
||||
- Use Tailwind CSS classes exclusively - no inline styles
|
||||
- **MANDATORY**: Use `safeWriteJson()` from `src/utils/safeWriteJson.ts` for ALL JSON writes (prevents corruption via atomic writes with locking)
|
||||
- Tests MUST run from workspace directory: `cd src && npx vitest run` (NOT from root)
|
||||
- VSCode CSS variables must be added to `webview-ui/src/index.css` before use
|
||||
- React components use functional components with hooks
|
||||
- State management via React hooks, not external state libraries
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
- All new features require test coverage
|
||||
- Tests use vitest framework (vi, describe, test, it are global)
|
||||
- Run tests from workspace directory: `cd src && npx vitest run`
|
||||
- Never run tests from project root
|
||||
|
||||
## IPC Communication
|
||||
|
||||
- Use packages/ipc for webview ↔ extension communication
|
||||
- Messages must be typed using interfaces from packages/types
|
||||
- Handle all async operations with proper error boundaries
|
||||
|
||||
## File Restrictions
|
||||
|
||||
- Code mode can edit all file types
|
||||
- Always verify file exists before operations
|
||||
- Use proper file locking for concurrent access safety
|
||||
- State management via React hooks only (external state libraries break webview isolation)
|
||||
- Providers MUST be stateless (hidden caching layer assumes this)
|
||||
- Import paths in packages/ require `.js` extensions despite TypeScript source
|
||||
|
|
|
|||
|
|
@ -1,40 +1,13 @@
|
|||
# Debug Mode Rules
|
||||
|
||||
## Debugging Entry Points
|
||||
## Non-Obvious Debug Access
|
||||
|
||||
- VSCode Debug Console shows extension logs via `outputChannel`
|
||||
- Webview DevTools accessible via Command Palette → "Developer: Open Webview Developer Tools"
|
||||
- Extension host debugging: Press F5 to launch new VSCode window with extension loaded
|
||||
- Webview DevTools: Command Palette → "Developer: Open Webview Developer Tools" (NOT F12)
|
||||
- Extension logs: VSCode Output panel → "Roo Code" channel
|
||||
- Extension Host output channel shows different logs than Debug Console
|
||||
|
||||
## Common Debug Patterns
|
||||
## Critical Debug Patterns
|
||||
|
||||
- Provider issues: Check `src/api/providers/__tests__/` for test patterns
|
||||
- IPC communication: Review `packages/ipc/src/` for message flow
|
||||
- Webview state issues: Check React DevTools in webview developer tools
|
||||
- Extension activation: Review `src/extension.ts` and `src/activate/`
|
||||
|
||||
## Log Locations
|
||||
|
||||
- Extension logs: VSCode Output panel → "Roo Code"
|
||||
- Terminal command logs: Check TerminalRegistry in `src/integrations/terminal/`
|
||||
- MCP server logs: Check McpServerManager output
|
||||
- Cloud service logs: Check CloudService initialization in extension.ts
|
||||
|
||||
## Testing Debug Workflow
|
||||
|
||||
1. Add console.log or debugger statements
|
||||
2. Run tests with: `cd src && npx vitest run --reporter=verbose`
|
||||
3. For UI tests: `cd webview-ui && npx vitest run --reporter=verbose`
|
||||
4. Use VSCode's built-in debugger for stepping through code
|
||||
|
||||
## Performance Debugging
|
||||
|
||||
- Memory issues: Check for proper cleanup in `deactivate()` function
|
||||
- Slow operations: Profile with Chrome DevTools for webview
|
||||
- Extension performance: Use VSCode's Extension Host profiler
|
||||
|
||||
## Error Handling
|
||||
|
||||
- All async operations should have try-catch blocks
|
||||
- Errors should be logged to outputChannel
|
||||
- Critical errors should provide user-friendly messages via vscode.window.showErrorMessage
|
||||
- IPC messages fail silently without try/catch in `packages/ipc/src/`
|
||||
- Tests MUST run from workspace directory: `cd src && npx vitest run`
|
||||
- Webview runs in restricted context (no localStorage, limited browser APIs)
|
||||
|
|
|
|||
72
AGENTS.md
72
AGENTS.md
|
|
@ -2,64 +2,20 @@
|
|||
|
||||
This file provides guidance to agents when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
## Critical Non-Obvious Patterns
|
||||
|
||||
Roo Code - AI-powered autonomous coding agent VSCode extension with React webview UI, supporting multiple AI providers and custom modes.
|
||||
- **JSON Writes**: MUST use `safeWriteJson()` from `src/utils/safeWriteJson.ts` for ALL JSON writes (atomic writes with locking, handles streaming)
|
||||
- **Test Execution**: Tests MUST run from workspace directory: `cd src && npx vitest run` or `cd webview-ui && npx vitest run` (NOT from root)
|
||||
- **Import Extensions**: Use `.js` extensions in packages/ imports despite TypeScript source files
|
||||
- **Bootstrap**: `pnpm install` auto-bootstraps via `scripts/bootstrap.mjs` if pnpm not found
|
||||
- **Webview DevTools**: Access via Command Palette → "Developer: Open Webview Developer Tools" (not F12)
|
||||
- **VSCode CSS Variables**: Must be added to `webview-ui/src/index.css` before use in components
|
||||
- **React Hooks Required**: External state libraries break webview isolation - use React hooks only
|
||||
- **noUncheckedIndexedAccess**: TypeScript strict mode with this enabled - array/object access may return undefined
|
||||
|
||||
## Build/Test/Lint Commands
|
||||
## Architecture Gotchas
|
||||
|
||||
```bash
|
||||
# Install dependencies (from root)
|
||||
pnpm install
|
||||
|
||||
# Build entire project
|
||||
pnpm build
|
||||
|
||||
# Run tests (CRITICAL: run from workspace directory containing package.json)
|
||||
cd src && npx vitest run tests/user.test.ts # Backend tests
|
||||
cd webview-ui && npx vitest run src/components/Button.test.tsx # UI tests
|
||||
|
||||
# Lint/format
|
||||
pnpm lint
|
||||
pnpm format
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
- **Formatting**: Tabs (4 width), 120 char lines, no semicolons, bracket same line
|
||||
- **Imports**: ESM modules, use `.js` extensions in packages/
|
||||
- **Types**: TypeScript strict mode, `noUncheckedIndexedAccess: true`
|
||||
- **Naming**: camelCase functions/variables, PascalCase components/classes
|
||||
- **UI**: Tailwind CSS classes only (no inline styles), VSCode CSS vars via webview-ui/src/index.css
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
src/ # VSCode extension backend (TypeScript)
|
||||
├── extension.ts # Entry point, registers providers & commands
|
||||
├── api/providers/ # AI provider implementations
|
||||
├── core/webview/ # Webview provider & IPC
|
||||
└── utils/ # Utilities (MUST use safeWriteJson for JSON writes)
|
||||
|
||||
webview-ui/ # React frontend
|
||||
├── src/components/ # React components with Tailwind CSS
|
||||
└── src/hooks/ # Custom React hooks
|
||||
|
||||
packages/ # Shared packages
|
||||
├── types/ # Shared TypeScript types
|
||||
├── ipc/ # IPC communication layer
|
||||
└── evals/ # Evaluation framework
|
||||
```
|
||||
|
||||
## Critical Patterns
|
||||
|
||||
- **JSON Writes**: ALWAYS use `safeWriteJson()` from src/utils/safeWriteJson.ts (atomic writes with locking)
|
||||
- **Testing**: Run vitest from workspace directory containing package.json, NOT from project root
|
||||
- **Providers**: Implement Provider interface from packages/types/src/
|
||||
- **Webview**: VSCode webview architecture with IPC messaging between extension and UI
|
||||
|
||||
## Development
|
||||
|
||||
- **Debug**: Press F5 in VSCode to launch extension host
|
||||
- **Hot Reload**: Webview changes appear immediately, core changes auto-reload in dev mode
|
||||
- **VSIX**: `pnpm vsix` to build, `pnpm install:vsix` to install locally
|
||||
- `src/` contains VSCode extension backend (not generic source)
|
||||
- `webview-ui/` is React frontend in VSCode webview (restricted APIs, no localStorage)
|
||||
- IPC messages between extension/webview must use typed interfaces from `packages/types`
|
||||
- Provider implementations must be stateless (hidden caching layer assumes this)
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue