# Multi-File and Codebase-Aware Prompting
When you're working on real projects, code doesn't live in isolation. Features span multiple files, components interact with services, and changes in one place ripple through your entire codebase. Yet many developers still prompt AI assistants as if each file exists in a vacuum. This is where multi-file and codebase-aware prompting becomes your superpower.
In this lesson, you'll learn how to leverage your AI assistant's understanding of your entire project structure to generate better, more contextually appropriate code. We'll move beyond single-file examples to tackle real-world scenarios where multiple files need to work together harmoniously.
## Why Context Matters More Than You Think
Here's a scenario you've probably experienced: You ask your AI assistant to create a new API endpoint. It generates perfectly valid Express.js code, but it doesn't match your existing authentication middleware, uses a different error handling pattern, and imports utilities that don't exist in your project.
The code works in isolation, but it's wrong for your codebase.
This happens because the AI didn't understand the context of your project. Multi-file prompting solves this by:
- **Maintaining consistency** across your codebase's patterns and conventions
- **Reusing existing utilities** instead of recreating them
- **Respecting architectural decisions** already embedded in your project
- **Generating code that integrates** rather than requiring extensive modification
## Understanding What Your AI Can "See"
Before diving into techniques, you need to understand what context your AI assistant actually has access to. Different tools work differently:
**GitHub Copilot**: Primarily sees the current file and limited context from recently opened files
**Cursor/Windsurf**: Can index your entire codebase and reference multiple files explicitly
**Claude with Projects**: Maintains conversation context plus any files you've explicitly added to the project knowledge
**ChatGPT with file uploads**: Only knows about files you've uploaded in the current conversation
The key insight: Your AI doesn't automatically know everything about your project. You need to deliberately provide or reference the right context.
## Technique 1: Explicit File Referencing
The most straightforward approach is explicitly telling your AI which files to consider. This works across all AI tools and gives you precise control over context.
### Basic Pattern
```
I need to add a new user profile endpoint to our API.
Relevant files:
- src/routes/users.js (existing user routes)
- src/middleware/auth.js (authentication patterns)
- src/services/userService.js (database interactions)
- src/utils/validators.js (validation helpers)
Create a new GET /api/users/:id/profile endpoint that:
1. Uses the same auth middleware as other user routes
2. Calls userService methods for data access
3. Validates the ID parameter using our existing validators
4. Returns responses in the same format as other endpoints
```
This prompt gives the AI a roadmap of which files contain the patterns and utilities it should follow. Even if the AI can't read all these files directly, you've set expectations for consistency.
### Advanced: Including Code Snippets
For maximum clarity, include relevant snippets from those files:
```
I need to add a new user profile endpoint. Here's our existing pattern:
// src/routes/users.js (existing pattern)
router.get('/list',
authMiddleware.requireAuth,
asyncHandler(async (req, res) => {
const users = await userService.findAll(req.user.organizationId);
res.json({ success: true, data: users });
})
);
// src/utils/validators.js (our validation style)
const validateId = (id) => {
if (!mongoose.Types.ObjectId.isValid(id)) {
throw new ValidationError('Invalid ID format');
}
return id;
};
Create a GET /api/users/:id/profile endpoint following these exact patterns.
```
Now the AI has concrete examples to match, not just file names to reference. This is particularly useful when working with tools that can't directly access your codebase.
## Technique 2: Architecture-First Prompting
Instead of jumping straight to code, start by describing the architectural relationships between files. This helps the AI understand the bigger picture.
```
Our application structure:
- Controllers (src/controllers/) handle HTTP requests/responses
- Services (src/services/) contain business logic and database operations
- Models (src/models/) define Mongoose schemas
- Middleware (src/middleware/) handles cross-cutting concerns
- Utils (src/utils/) contain shared helper functions
I need to add functionality to archive old posts. This should:
1. Add an archivePost() method to PostService
2. Add an archive() controller in PostController
3. Expose a PUT /api/posts/:id/archive route
4. Use the existing requireAuth and requireOwnership middleware
Generate the code for each layer, ensuring they integrate properly.
```
This approach is powerful because it forces the AI to think about separation of concerns and how different parts of your application communicate. You'll get better structured code that fits your architectural patterns.
For more on planning architectural approaches with AI, see [ai-architecture](/lessons/ai-architecture).
## Technique 3: Dependency Chain Prompting
When creating new features that depend on multiple existing files, explicitly map out the dependency chain:
```
I need to implement a password reset flow. Here's the dependency chain:
1. User Model (src/models/User.js) - needs two new fields:
- resetPasswordToken (String)
- resetPasswordExpires (Date)
2. Email Service (src/services/emailService.js) - needs new method:
- sendPasswordResetEmail(user, resetToken)
- Should use existing sendEmail() helper and our email templates
3. Auth Controller (src/controllers/authController.js) - needs two endpoints:
- POST /auth/forgot-password (generates token, sends email)
- POST /auth/reset-password (validates token, updates password)
- Should use existing hashPassword() from utils/crypto.js
4. Routes (src/routes/auth.js) - wire up the new endpoints
Generate each piece in order, showing how they connect.
```
By mapping dependencies explicitly, you help the AI understand the order of operations and ensure each piece properly references the others. This is especially valuable when following patterns like [breaking-down-projects](/lessons/breaking-down-projects).
## Technique 4: Pattern Extraction and Replication
Sometimes the best way to ensure consistency is to show the AI an existing pattern and ask it to replicate it for a new use case.
```
Here's how we implemented the Comment feature:
// src/models/Comment.js
const commentSchema = new Schema({
content: { type: String, required: true },
author: { type: Schema.Types.ObjectId, ref: 'User', required: true },
post: { type: Schema.Types.ObjectId, ref: 'Post', required: true },
createdAt: { type: Date, default: Date.now },
updatedAt: { type: Date, default: Date.now }
});
// src/services/commentService.js
class CommentService {
async create(data, userId) {
const comment = new Comment({ ...data, author: userId });
await comment.save();
return comment.populate('author', 'username avatar');
}
async findByPost(postId) {
return Comment.find({ post: postId })
.populate('author', 'username avatar')
.sort({ createdAt: -1 });
}
}
// src/controllers/commentController.js
exports.create = asyncHandler(async (req, res) => {
const comment = await commentService.create(req.body, req.user.id);
res.status(201).json({ success: true, data: comment });
});
Now implement a Like feature following this EXACT same pattern:
- Model with similar schema structure
- Service with create() and findByPost() methods
- Controller with consistent response format
- Track user who created the like and which post it's on
```
Pattern replication ensures consistency and makes code reviews easier because reviewers recognize familiar structures. This ties directly into [code-gen-best-practices](/lessons/code-gen-best-practices).
## Technique 5: Cross-File Impact Analysis
Before making changes, prompt your AI to analyze the impact across your codebase:
```
I want to add a "status" field to our User model (active, suspended, deleted).
Before generating code, analyze the impact:
1. Which files import or use the User model?
2. Which queries might need to filter by status?
3. Which API endpoints should respect user status?
4. Are there any middleware or utilities that need updates?
5. What existing tests need modification?
Provide the analysis first, then generate necessary changes for each affected file.
```
This "think before coding" approach helps catch ripple effects early. The AI will often identify files and dependencies you hadn't considered. This technique works well alongside [chain-of-thought](/lessons/chain-of-thought) prompting.
## Technique 6: Convention Documentation
If you're using a codebase-aware tool like Cursor, create a conventions document that lives in your repo:
```markdown
# Codebase Conventions
## File Organization
- One class/component per file
- Filename matches the main export (UserService.js exports UserService)
- Index files only for barrel exports
## Naming Patterns
- Services: `*Service.js` (UserService, EmailService)
- Controllers: `*Controller.js` (AuthController, PostController)
- Models: Singular PascalCase (User.js, Post.js)
- Utils: camelCase describing function (validateEmail.js)
## Error Handling
```javascript
// Always use custom error classes
throw new ValidationError('Descriptive message');
throw new NotFoundError('Resource not found');
throw new UnauthorizedError('Insufficient permissions');
// Controllers use asyncHandler wrapper
exports.myMethod = asyncHandler(async (req, res) => {
// errors automatically caught and formatted
});
```
## Database Patterns
- All database operations in Service layer
- Controllers never import Models directly
- Use transactions for multi-model operations
## Testing
- Unit tests: `*.test.js` alongside source file
- Integration tests: `/tests/integration/`
- Use factory functions for test data
```
Then reference it in prompts:
```
Following our conventions in .ai/conventions.md, create a new ProductService
with CRUD operations.
```
This creates a single source of truth for your coding standards. Tools like Cursor can automatically reference this file, making every prompt convention-aware.
## Technique 7: Type System Leverage
If you're using TypeScript or JSDoc, leverage your type definitions as context:
```
Here are our existing types:
// src/types/api.ts
export interface ApiResponse {
success: boolean;
data?: T;
error?: {
message: string;
code: string;
details?: Record;
};
}
export interface PaginatedResponse extends ApiResponse {
pagination: {
page: number;
pageSize: number;
totalItems: number;
totalPages: number;
};
}
// src/types/user.ts
export interface User {
id: string;
email: string;
username: string;
role: 'admin' | 'user' | 'moderator';
createdAt: Date;
}
Create a new endpoint GET /api/users that returns a PaginatedResponse.
Ensure the implementation matches these type signatures exactly.
```
Types serve as contracts that the AI can verify against, reducing type errors and ensuring consistency. This is especially powerful when combined with [quality-control](/lessons/quality-control) practices.
## Practical Workflow: Adding a New Feature
Let's walk through adding a complete feature using multi-file prompting:
### Step 1: Context Gathering Prompt
```
I want to add a "bookmark" feature where users can save posts for later.
First, help me understand the context:
1. What existing models does this relate to? (User, Post)
2. What similar features already exist that I should follow?
3. Where should the code live based on our current structure?
4. What middleware or utilities can I reuse?
```
### Step 2: Architecture Planning Prompt
```
Based on our codebase structure, design the bookmark feature:
- Model: Should this be a separate Bookmark model or a field on User?
- Routes: What endpoints do we need?
- Services: What business logic methods?
- Frontend: Which components need updating?
Provide the high-level design before any code.
```
### Step 3: Implementation Prompts (In Order)
```
1. Create the Bookmark model following our User and Post model patterns
(include timestamps, references, and indexes)
2. Add bookmark methods to UserService:
- addBookmark(userId, postId)
- removeBookmark(userId, postId)
- getBookmarks(userId, options) // with pagination
3. Create bookmark controller endpoints matching our existing controller patterns:
- POST /api/bookmarks
- DELETE /api/bookmarks/:postId
- GET /api/bookmarks
4. Wire up routes in src/routes/bookmarks.js using our standard middleware stack
5. Add a bookmarked status check to the existing GET /api/posts endpoint
(when user is authenticated, include isBookmarked boolean)
```
Notice how each prompt builds on the previous ones and references existing patterns. This is [iterating-output](/lessons/iterating-output) in practice.
## Common Pitfalls and How to Avoid Them
### Pitfall 1: Context Overload
**Problem**: Pasting your entire codebase into a prompt.
**Solution**: Be selective. Include only files directly relevant to the task. For large codebases, reference file paths and include small snippets of key patterns.
### Pitfall 2: Assuming the AI Knows Your Conventions
**Problem**: "Add a new service" without explaining what a service is in your codebase.
**Solution**: Always provide at least one example of the pattern you want followed. Don't assume the AI knows your team's specific conventions.
### Pitfall 3: Ignoring Integration Points
**Problem**: Generating code that works standalone but breaks integration.
**Solution**: Explicitly mention integration requirements: "This must work with our existing auth flow," "This needs to emit events our logging system can capture," etc.
### Pitfall 4: Not Verifying Cross-File Imports
**Problem**: AI generates imports that don't match your actual file structure.
**Solution**: After generation, explicitly ask: "Verify that all imports in this code match actual file paths in our project structure."
For more on common issues, see [top-mistakes](/lessons/top-mistakes).
## Advanced: Refactoring Across Multiple Files
Multi-file prompting shines when refactoring:
```
We're changing our error handling approach. Currently we use:
if (!user) {
return res.status(404).json({ error: 'User not found' });
}
New standard (using custom errors):
if (!user) {
throw new NotFoundError('User not found');
}
Files that need updating:
- src/controllers/userController.js
- src/controllers/postController.js
- src/controllers/authController.js
For each file:
1. Show me the current error handling locations
2. Generate the refactored version
3. Highlight what changed
Start with userController.js
```
This systematic approach ensures consistency across your refactor. Learn more about this in [review-refactor](/lessons/review-refactor).
## Testing Your Multi-File Changes
Always prompt for tests that verify integration:
```
Now create integration tests for the bookmark feature that verify:
1. POST /api/bookmarks creates a bookmark AND it appears in GET /api/bookmarks
2. Bookmarking the same post twice returns appropriate error
3. DELETE removes the bookmark AND it no longer appears in the list
4. GET /api/posts includes isBookmarked=true for bookmarked posts
5. Deleting a post also deletes associated bookmarks
Use our existing test patterns from tests/integration/posts.test.js
```
Integration tests catch the issues that unit tests miss—when files don't play nicely together. More on this in [testing-strategies](/lessons/testing-strategies).
## Working with Large Codebases
For large projects (50+ files), use a layered approach:
**Layer 1: Project Map**
```
Provide a high-level overview of our codebase structure:
- What are the main modules/domains?
- How do they communicate?
- Where would a "notification system" fit?
```
**Layer 2: Domain Context**
```
Focusing on the user management domain:
- List all files in src/domains/users/
- What patterns do they follow?
- What shared utilities do they use?
```
**Layer 3: Specific Implementation**
```
Now implement the specific feature using those patterns...
```
This prevents overwhelming the AI while still providing necessary context. It's also useful when [scaling-vibe-coding](/lessons/scaling-vibe-coding) to larger teams.
## Version Control Integration
When making multi-file changes, prompt for atomic commits:
```
We just implemented the bookmark feature across 6 files.
Generate git commit messages for this change as 3 separate commits:
1. Database layer (model and migrations)
2. Business logic (service methods)
3. API layer (routes and controllers)
For each commit, list which files it includes and write a clear commit message.
```
This creates reviewable, revertable chunks instead of one massive commit. More on this in [version-control-ai](/lessons/version-control-ai).
## Putting It All Together
Multi-file and codebase-aware prompting is about giving your AI assistant the context it needs to generate code that fits your project like a puzzle piece, not a square peg.
The key principles:
1. **Be explicit about context**: Don't assume the AI knows which files matter
2. **Show patterns**: Provide examples of the style and structure you want
3. **Think architecturally**: Help the AI understand how pieces connect
4. **Verify integration**: Always consider how new code affects existing code
5. **Iterate systematically**: Build complex features file by file, layer by layer
As you practice these techniques, you'll develop an intuition for how much context is enough, which files to reference, and how to guide the AI toward generating code that feels native to your codebase.
The result? Less time refactoring AI-generated code to match your patterns, and more time building features that matter.
## Next Steps
Now that you understand multi-file prompting, explore:
- [agentic-optimization](/lessons/agentic-optimization) - Let AI assistants autonomously handle multi-file changes
- [managing-tech-debt](/lessons/managing-tech-debt) - Use these techniques to refactor legacy code
- [working-with-generated](/lessons/working-with-generated) - Best practices for reviewing and integrating multi-file changes
- [hallucination-detection](/lessons/hallucination-detection) - Catch when AI invents files or imports that don't exist
The more you practice context-aware prompting, the more your AI assistant becomes a true collaborator who understands not just how to code, but how to code for *your* project.