Config Files Reference

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

Project file: CLAUDE.md in project rootGlobal file: ~/.claude/CLAUDE.mdNested support: Yes - place CLAUDE.md in subdirectories for module-specific context

project/
├── CLAUDE.md              # Project-wide instructions
├── src/
│   ├── CLAUDE.md          # src-specific context
│   └── api/
│       └── CLAUDE.md      # API module context
└── .claude/
    └── settings.json      # Tool configuration

Example content:

# 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: GEMINI.md in project rootGlobal file: ~/.gemini/GEMINI.mdNested support: Yes - place GEMINI.md in subdirectories

project/
├── GEMINI.md              # Project-wide instructions
├── src/
│   └── GEMINI.md          # src-specific context
└── .gemini/
    └── settings.json      # Tool configuration

Example content:

# 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: AGENTS.md in project rootGlobal file: ~/.opencode/AGENTS.mdNested support: Yes - each directory can have its own AGENTS.md

project/
├── AGENTS.md              # Project-wide instructions
├── src/
│   └── AGENTS.md          # src-specific context
└── .opencode/
    └── config.json        # Tool settings

Example content:

# 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: .cursorrules in project rootGlobal rules: Settings → General → Rules for AINested support: Yes - .cursor/rules/*.md for additional rules

project/
├── .cursorrules           # Main project rules
└── .cursor/
    └── rules/
        ├── typescript.md  # TypeScript-specific
        └── testing.md     # Testing conventions

Example content:

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: .github/copilot-instructions.mdGlobal config: Not supported (VS Code settings only)Nested support: No

project/
└── .github/
    └── copilot-instructions.md

Example content:

## 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: .windsurfrules in project rootGlobal file: ~/.codeium/windsurf/memories/global_rules.mdNested support: Yes - .windsurf/rules/ directory

project/
├── .windsurfrules         # Project rules
└── .windsurf/
    └── rules/
        └── backend.md     # Backend-specific

Example content:

# 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: CONVENTIONS.md in project rootGlobal config: ~/.aider.conf.ymlNested support: No

project/
├── CONVENTIONS.md         # Project conventions
├── .aider.conf.yml        # Aider config
└── .aiderignore           # Files to ignore

Example CONVENTIONS.md:

# Code Conventions

## Formatting
- 2 space indentation
- Single quotes for strings
- Trailing commas

## Naming
- camelCase for variables
- PascalCase for components
- SCREAMING_SNAKE for constants

Example .aider.conf.yml:

model: claude-3-5-sonnet-20241022
edit-format: diff
auto-commits: true
read:
  - CONVENTIONS.md

Project file: AGENTS.md in project rootGlobal config: Not supportedNested support: Yes

project/
├── AGENTS.md              # Project instructions
└── src/
    └── AGENTS.md          # Module context

Example content:

# 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

Context Optimization

Effective context feeding strategies

Slop Constraints

Control output quality

Get Started

Core Concepts

Configuration

Building Agents

Production

Resources

API

Overview

Quick Reference

Detailed Configuration

Universal Template

Multi-Tool Setup

Best Practices

Context Optimization

Slop Constraints

Get Started

Core Concepts

Configuration

Building Agents

Production

Resources

API

​Overview

​Quick Reference

​Detailed Configuration

​Universal Template

​Multi-Tool Setup

​Best Practices

​Related

Context Optimization

Slop Constraints

Overview

Quick Reference

Detailed Configuration

Universal Template

Multi-Tool Setup

Best Practices

Related