Your Codebase Is the Best Example Library
The most accurate example of your project's patterns: is your project's existing code. Instead of describing a pattern in prose or writing a code example in the rules file: point the AI to an existing file that demonstrates the pattern. The AI reads the file, extracts the pattern, and applies it to new code. The result: new code that matches existing code perfectly — because the AI copied the pattern from a real implementation, not from a simplified example in the rules file.
When to reference files: when a pattern is complex (the file shows the complete pattern with all the nuances that a short example would miss), when a pattern is used in many places (new instances should match existing instances exactly), and when the pattern evolves (the file is updated as the pattern changes — the rule stays current automatically). File references: tie the rules to the living codebase instead of to a static snapshot.
The format: 'For new API routes: follow the pattern in src/routes/users.ts.' The AI: reads users.ts, understands the structure (imports, validation, handler, response format, error handling), and generates new routes that match. The reference: is a pointer. The actual pattern: lives in the codebase, maintained alongside the code itself.
Step 1: Types of File References
Pattern references: point to a file that demonstrates the correct implementation pattern. 'New API routes: follow the pattern in src/routes/users.ts (imports, Zod validation, handler structure, response format).' 'New React components: follow the pattern in src/components/UserProfile.tsx (component structure, props typing, data fetching, loading states).' 'New database models: follow the pattern in src/db/schema/users.ts (table definition, relations, type exports).' Each reference: a concrete example the AI can study and replicate.
Configuration references: point to configuration files that define project settings. 'TypeScript configuration: see tsconfig.json for compiler options — strict mode enabled, paths configured for @ aliases.' 'ESLint configuration: see eslint.config.js for enabled rules and custom settings.' 'Tailwind configuration: see tailwind.config.ts for custom colors, spacing, and typography tokens.' These references: help the AI understand what is configured, avoiding suggestions that conflict with the project's settings.
Anti-pattern references: point to files that demonstrate what NOT to do, if the codebase has legacy code. 'The pattern in src/legacy/old-auth.ts is DEPRECATED. Do not follow it for new auth code. Follow src/auth/session.ts instead.' This: explicitly warns the AI about legacy patterns it might encounter when reading the codebase. Without this warning: the AI might copy the legacy pattern because it is in the codebase. AI rule: 'Anti-pattern references prevent the AI from learning from legacy code that should not be replicated.'
Your codebase has 20 API routes. Some follow the current pattern. Some were written before the pattern was established. Referencing 'follow src/routes/users.ts': only works if users.ts is the canonical example. If users.ts has technical debt: the AI copies the debt. Choose the reference file carefully: it should be the best, most current implementation of the pattern. If no file is ideal: clean one up first, then reference it.
Step 2: Writing Effective File References
Be specific about what to copy: 'Follow src/routes/users.ts' is vague — copy the entire file? Just the structure? Just the error handling? Better: 'Follow the structure of src/routes/users.ts: import grouping, Zod schema definition, handler function with try-catch and Result pattern, and Response.json return format.' The specific callout: tells the AI which aspects of the file to replicate. The AI: focuses on those aspects rather than copying unrelated details.
Use relative paths from the project root: 'See src/routes/users.ts' not 'See the users file' (ambiguous — which users file?) or '../routes/users.ts' (relative to what?). Consistent root-relative paths: unambiguous for both the AI and developers reading the rules. AI rule: 'Always use root-relative paths (src/routes/users.ts, not ./routes/users.ts or the users file). Root-relative: unambiguous regardless of where the developer or AI is working.'
Keep references current: if you reference src/routes/users.ts and then rename the file to src/routes/user-routes.ts: the reference breaks. The AI: cannot find the file and falls back to generic patterns. Prevention: include file references in the quarterly audit checklist. For each referenced file: verify it still exists at the specified path. If renamed or moved: update the reference. AI rule: 'File references are like hyperlinks — they break when the target moves. Audit referenced files quarterly. Broken references: are worse than no references (the AI fails silently).'
The rule says: 'Follow the pattern in src/routes/users.ts.' The file was renamed to src/routes/user-routes.ts last week. The AI: cannot find src/routes/users.ts. Does it error? No — it silently falls back to generic patterns. The developer: does not know the reference is broken. The code: generated with generic patterns instead of project-specific ones. Quarterly audit: verify every referenced file still exists. One broken reference: undermines an entire pattern.
Step 3: Tool-Specific File Reference Features
Claude Code: reads files in the project context. References in CLAUDE.md like 'See src/routes/users.ts for the API pattern': Claude Code can read this file when generating code. For explicit reference: use the @file syntax in conversation or reference the file in the rules with a description of what pattern it demonstrates.
Cursor: the @file syntax in chat references specific files. In .cursorrules: describe the file and what to learn from it. In Cursor Chat: @src/routes/users.ts gives the AI direct access to the file content. Combine: rules describe what to learn from the file, and @file in chat provides the content. AI rule: 'In Cursor: rules describe the pattern, @file in chat provides the content. The rules: tell the AI what to look for. The @file reference: gives the AI the content to look at.'
Copilot: GitHub Copilot reads open files and recently viewed files for context. Copilot instructions can reference patterns by description: 'New routes follow the pattern established in our users route with Zod validation and structured responses.' Copilot uses its codebase understanding to find and follow the referenced pattern. For explicit context: open the reference file before prompting in Copilot Chat. AI rule: 'Each AI tool handles file references differently. Rules describe the pattern. The tool-specific mechanism provides the file content. Combine both for the strongest reference.'
An inline code example in the rules file: is a snapshot. It does not update when the pattern evolves. A file reference (src/routes/users.ts): points to the living code. When the pattern is updated in users.ts: the AI automatically uses the updated pattern. No rules file edit needed. This is the key advantage: file references are dynamic (they reflect the current codebase). Inline examples are static (they reflect the codebase at the time they were written).
File References in Rules Summary
Summary of referencing specific files in AI rules.
- Power: existing code is the best example. File references use your actual codebase as the pattern library
- Pattern references: 'Follow src/routes/users.ts for new API routes' — the AI replicates the structure
- Config references: point to tsconfig, ESLint, Tailwind config. AI avoids conflicting suggestions
- Anti-pattern references: 'src/legacy/old-auth.ts is DEPRECATED. Follow src/auth/session.ts instead'
- Specificity: name which aspects to copy (imports, validation, error handling, response format)
- Paths: root-relative always (src/routes/users.ts). Never ambiguous relative paths
- Maintenance: audit referenced files quarterly. Broken references cause silent fallback to generic patterns
- Tool-specific: Claude Code reads project files, Cursor uses @file, Copilot uses open files for context