Overview
Every AI coding tool reads project-specific instructions from config files. This reference covers all major tools so you can configure your project once and support multiple workflows.Quick Reference
| Tool | Config File | Global Location | Nested Support |
|---|---|---|---|
| Claude Code | CLAUDE.md | ~/.claude/CLAUDE.md | Yes |
| Gemini CLI | GEMINI.md | ~/.gemini/GEMINI.md | Yes |
| OpenCode | AGENTS.md | ~/.opencode/AGENTS.md | Yes |
| Cursor | .cursorrules | ~/.cursor/rules/ | Yes |
| GitHub Copilot | copilot-instructions.md | N/A | No |
| Windsurf | .windsurfrules | ~/.codeium/windsurf/ | Yes |
| Aider | CONVENTIONS.md | ~/.aider.conf.yml | No |
| OpenAI Codex | AGENTS.md | N/A | Yes |
Detailed Configuration
- Claude Code
- Gemini CLI
- OpenCode
- Cursor
- GitHub Copilot
- Windsurf
- Aider
- OpenAI Codex
Project file: Example content:
CLAUDE.md in project rootGlobal file: ~/.claude/CLAUDE.mdNested support: Yes - place CLAUDE.md in subdirectories for module-specific contextproject/
├── CLAUDE.md # Project-wide instructions
├── src/
│ ├── CLAUDE.md # src-specific context
│ └── api/
│ └── CLAUDE.md # API module context
└── .claude/
└── settings.json # Tool configuration
# Project: My App
## Tech Stack
- TypeScript, React, Node.js
- PostgreSQL with Prisma ORM
## Conventions
- Use functional components with hooks
- Prefer named exports
- Tests in `__tests__/` directories
## Commands
- `npm run dev` - Start development
- `npm test` - Run tests
Project file: Example content:
GEMINI.md in project rootGlobal file: ~/.gemini/GEMINI.mdNested support: Yes - place GEMINI.md in subdirectoriesproject/
├── GEMINI.md # Project-wide instructions
├── src/
│ └── GEMINI.md # src-specific context
└── .gemini/
└── settings.json # Tool configuration
# Project: My App
## Tech Stack
- TypeScript, React, Node.js
- PostgreSQL with Drizzle ORM
## Conventions
- Use functional components
- Prefer named exports
- Co-locate tests with source files
## Sandbox
- Use `npm run dev` for development
- Database runs in Docker
Project file: Example content:
AGENTS.md in project rootGlobal file: ~/.opencode/AGENTS.mdNested support: Yes - each directory can have its own AGENTS.mdproject/
├── AGENTS.md # Project-wide instructions
├── src/
│ └── AGENTS.md # src-specific context
└── .opencode/
└── config.json # Tool settings
# Project Instructions
## Overview
This is a Next.js e-commerce application.
## Architecture
- `/app` - Next.js App Router pages
- `/lib` - Shared utilities
- `/components` - React components
## Rules
- Use TypeScript strict mode
- All API routes must validate input with Zod
- Use server actions for mutations
Project file: Example content:
.cursorrules in project rootGlobal rules: Settings → General → Rules for AINested support: Yes - .cursor/rules/*.md for additional rulesproject/
├── .cursorrules # Main project rules
└── .cursor/
└── rules/
├── typescript.md # TypeScript-specific
└── testing.md # Testing conventions
You are an expert TypeScript developer.
## Code Style
- Use functional programming patterns
- Prefer immutability
- Use early returns
## Project Structure
- Components in `/src/components`
- Hooks in `/src/hooks`
- Types in `/src/types`
## Testing
- Use Vitest for unit tests
- Use Playwright for E2E
- Minimum 80% coverage
Project file: Example content:
.github/copilot-instructions.mdGlobal config: Not supported (VS Code settings only)Nested support: Noproject/
└── .github/
└── copilot-instructions.md
## Project Context
This is a Python FastAPI backend service.
## Coding Standards
- Use type hints for all functions
- Follow PEP 8 style guide
- Use pydantic for data validation
## Preferences
- Prefer async/await for I/O operations
- Use dependency injection pattern
- Write docstrings for public functions
Project file: Example content:
.windsurfrules in project rootGlobal file: ~/.codeium/windsurf/memories/global_rules.mdNested support: Yes - .windsurf/rules/ directoryproject/
├── .windsurfrules # Project rules
└── .windsurf/
└── rules/
└── backend.md # Backend-specific
# Windsurf Rules
## Language
- Primary: TypeScript
- Runtime: Bun
## Style
- Use Biome for formatting
- Prefer const over let
- Use template literals
## Architecture
- Hexagonal architecture
- Domain-driven design
Project file: Example CONVENTIONS.md:Example .aider.conf.yml:
CONVENTIONS.md in project rootGlobal config: ~/.aider.conf.ymlNested support: Noproject/
├── CONVENTIONS.md # Project conventions
├── .aider.conf.yml # Aider config
└── .aiderignore # Files to ignore
# Code Conventions
## Formatting
- 2 space indentation
- Single quotes for strings
- Trailing commas
## Naming
- camelCase for variables
- PascalCase for components
- SCREAMING_SNAKE for constants
model: claude-3-5-sonnet-20241022
edit-format: diff
auto-commits: true
read:
- CONVENTIONS.md
Project file: Example content:
AGENTS.md in project rootGlobal config: Not supportedNested support: Yesproject/
├── AGENTS.md # Project instructions
└── src/
└── AGENTS.md # Module context
# Codex Instructions
## Project
React Native mobile app with Expo
## Guidelines
- Use Expo SDK features when available
- Handle offline state gracefully
- Support iOS and Android equally
## Commands
- `npx expo start` - Development
- `npx expo build` - Production build
Universal Template
Use this template that works across most tools:# Project: [Name]
## Overview
[1-2 sentence description]
## Tech Stack
- [Language/Framework]
- [Database]
- [Key libraries]
## Project Structure
- `/src` - Source code
- `/tests` - Test files
- `/docs` - Documentation
## Conventions
- [Coding style rules]
- [Naming conventions]
- [File organization]
## Commands
- `[dev command]` - Start development
- `[test command]` - Run tests
- `[build command]` - Build for production
## Important Notes
- [Critical warnings]
- [Non-obvious behaviors]
- [Security considerations]
Multi-Tool Setup
Support multiple AI tools in one project:project/
├── CLAUDE.md # Claude Code
├── GEMINI.md # Gemini CLI
├── AGENTS.md # OpenCode / Codex
├── .cursorrules # Cursor
├── .windsurfrules # Windsurf
├── .github/
│ └── copilot-instructions.md
└── CONVENTIONS.md # Aider
DRY approach: Create one source file and symlink others:
# Create main instructions
echo "# Project Instructions..." > CLAUDE.md
# Symlink for other tools
ln -s CLAUDE.md GEMINI.md
ln -s CLAUDE.md AGENTS.md
ln -s CLAUDE.md .cursorrules
ln -s CLAUDE.md .windsurfrules
Best Practices
- Keep instructions under 2000 words (fits in context)
- Update when tech stack changes
- Include “why” not just “what”
- List common commands developers need
- Note non-obvious project quirks
Avoid:
- Duplicating documentation that’s elsewhere
- Including secrets or credentials
- Over-specifying obvious conventions
- Contradicting tool defaults without reason
Related
Context Optimization
Effective context feeding strategies
Slop Constraints
Control output quality