Workspace Agent

The @workspace agent gives Copilot project-wide understanding. It can search across files, understand architecture, and answer questions about your entire codebase.

What is @workspace?

Unlike regular chat that sees only open files, @workspace can:

• Search across all project files
• Understand file relationships
• Identify patterns and conventions
• Answer architectural questions
• Find implementations and references

Regular Chat:
├── Sees: Current file
├── Sees: Open tabs
└── Limited project context

@workspace Agent:
├── Sees: Entire project structure
├── Sees: All source files
├── Sees: Configuration files
├── Sees: Dependencies
└── Understands: File relationships

Using @workspace

Basic Syntax

Prefix your question with @workspace:

@workspace How is user authentication implemented?

@workspace Where are API routes defined?

@workspace What testing framework does this project use?

Understanding Architecture

@workspace Describe the overall architecture of this project

Copilot: This is a Next.js 14 application using:

**Architecture Pattern**: Layered architecture

**Layers**:
- `/app` - Next.js App Router pages and API routes
- `/components` - React UI components (atomic design)
- `/lib` - Business logic and utilities
- `/services` - External service integrations
- `/prisma` - Database schema and migrations

**Key Technologies**:
- Framework: Next.js 14 with App Router
- Database: PostgreSQL via Prisma
- Auth: NextAuth.js with OAuth providers
- State: React Query for server state
- Styling: Tailwind CSS + shadcn/ui

**Data Flow**:
Client → Next.js API Routes → Services → Prisma → PostgreSQL

Finding Implementations

@workspace Where is the payment processing logic?

Copilot: Payment processing is implemented in:

1. **`/lib/stripe.ts`** - Stripe client initialization
2. **`/services/payment.service.ts`** - Payment business logic:
   - `createPaymentIntent()`
   - `processRefund()`
   - `createSubscription()`
3. **`/app/api/payments/route.ts`** - API endpoints
4. **`/components/checkout/PaymentForm.tsx`** - UI component

The flow: PaymentForm → API route → PaymentService → Stripe

Discovering Patterns

@workspace What patterns are used for error handling?

Copilot: This project uses these error handling patterns:

1. **Custom Error Classes** (`/lib/errors.ts`):
```typescript
class AppError extends Error {
  constructor(message: string, public statusCode: number) {}
}
class NotFoundError extends AppError { ... }
class ValidationError extends AppError { ... }

2. API Error Handler (/lib/api-handler.ts):

   • Wraps API routes with try/catch
   • Maps errors to HTTP responses

3. React Error Boundaries (/components/ErrorBoundary.tsx):

   • Catches render errors
   • Shows fallback UI

4. Form Validation (Zod schemas in /lib/validations/)

## Common Questions

### Code Location

@workspace Where is the user model defined?

@workspace Which files handle email sending?

@workspace Where are environment variables used?

### Dependencies

@workspace What package is used for date formatting?

@workspace Are there any unused dependencies?

@workspace What version of React is installed?

### Conventions

@workspace What naming conventions are used for components?

@workspace How are API responses structured?

@workspace What's the file organization pattern?

### Testing

@workspace How are tests organized?

@workspace What testing utilities are available?

@workspace Show me an example test for a service

## Advanced Queries

### Relationship Mapping

@workspace How do the auth modules relate to each other?

Copilot: ┌─────────────────────────────────────────────────────────┐ │ Authentication Flow │ ├─────────────────────────────────────────────────────────┤ │ │ │ middleware.ts ──────▶ lib/auth.ts ◀────── auth.config.ts │ │ │ │ │ │ ▼ │ │ │ app/api/auth/ │ │ │ └── [...nextauth]/ │ │ │ └── route.ts │ │ │ │ │ │ ▼ ▼ │ │ components/ services/auth.service.ts │ │ └── auth/ │ │ │ ├── LoginForm.tsx ▼ │ │ ├── SignupForm.tsx prisma/schema.prisma │ │ └── AuthProvider.tsx (User, Session) │ │ │ └─────────────────────────────────────────────────────────┘

### Impact Analysis

@workspace What would be affected if I changed the User model?

Copilot: Changing the User model would affect:

Direct Dependencies (need updates):

• /prisma/schema.prisma - Model definition
• /types/user.ts - TypeScript types
• /lib/validations/user.ts - Zod schemas

Services (may need updates):

• /services/user.service.ts - User CRUD operations
• /services/auth.service.ts - User creation/lookup

API Routes:

• /app/api/users/route.ts
• /app/api/users/[id]/route.ts
• /app/api/auth/[...nextauth]/route.ts

Components (may need prop updates):

• /components/user/UserProfile.tsx
• /components/user/UserSettings.tsx
• /components/admin/UserTable.tsx

Tests:

• /tests/services/user.service.test.ts
• /tests/api/users.test.ts

### Code Search

@workspace Find all usages of the validateEmail function

@workspace Where is 'STRIPE_SECRET_KEY' referenced?

@workspace List all files that import from '@/lib/utils'

### Comparison

@workspace Compare the old and new authentication implementations

@workspace What's different between UserService and AdminService?

## Workspace Indexing

### How Indexing Works

Copilot builds an index of your project:

First query: May take longer (building index) Subsequent queries: Faster (using cached index)

Index includes: ├── File structure ├── Function/class definitions ├── Import relationships ├── Symbol references └── Comment/documentation

### Index Limitations

Not everything is indexed:

✓ Indexed:

• Source code files
• Configuration files
• README and docs
• Package manifests

✗ Not indexed (typically):

• node_modules/
• Build outputs (dist/, .next/)
• Binary files
• Very large files

### Refreshing Index

If workspace seems outdated:

1. Close and reopen VS Code
2. Or run: "Developer: Reload Window"
3. Make a new @workspace query

## Combining with Other Features

### With File References

@workspace Looking at #file:src/services/payment.ts, what other services interact with payments?

### With Code Selection

Select code, then: @workspace Where else is this pattern used in the project?

### With Slash Commands

@workspace /explain the authentication flow

@workspace /doc the API endpoints

## Best Practices

### Be Specific

❌ "How does this work?" ✅ "@workspace How does user session management work?"

❌ "Where is the code?" ✅ "@workspace Where is the order processing logic implemented?"

### Ask Targeted Questions

Good questions for @workspace:

• "Where is X implemented?"
• "What uses X?"
• "How does X relate to Y?"
• "What would be affected by changing X?"
• "What patterns are used for X?"

Not ideal for @workspace:

• "Write a new feature" (use chat)
• "Fix this bug" (use inline chat)
• "Explain this single function" (use /explain)

### Break Down Complex Queries

Instead of: "@workspace Explain everything about authentication"

Try:

1. "@workspace How is user login implemented?"
2. "@workspace How are sessions managed?"
3. "@workspace How does OAuth integration work?"
4. "@workspace What middleware handles auth?"

## Troubleshooting

### "I couldn't find information about that"

Possible causes:

1. Code is in excluded directory
2. Query too vague
3. Index needs refreshing

Solutions:

• Be more specific
• Try different phrasing
• Reload window
• Check .gitignore patterns

### Slow Responses

If @workspace is slow:

1. Large codebase - normal for first query
2. Complex query - break into parts
3. Network issues - check connection

### Incomplete Results

If results seem incomplete:

1. Ask follow-up questions
2. Reference specific files
3. Use different search terms

## Summary

- **@workspace prefix**: Enables project-wide understanding
- **Architecture queries**: Understand overall structure
- **Finding code**: Locate implementations and usages
- **Pattern discovery**: Learn project conventions
- **Impact analysis**: Understand change effects
- **Best practices**: Be specific, ask targeted questions

## Next Steps

You've mastered understanding your codebase. Now let's explore Copilot Edits for making multi-file changes across your project.