> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents-squads.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Config Files Reference

> Project instruction files across AI coding tools

## 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

<Tabs>
  <Tab title="Claude Code">
    **Project file**: `CLAUDE.md` in project root

    **Global file**: `~/.claude/CLAUDE.md`

    **Nested 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**:

    ```markdown theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Gemini CLI">
    **Project file**: `GEMINI.md` in project root

    **Global file**: `~/.gemini/GEMINI.md`

    **Nested 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**:

    ```markdown theme={null}
    # 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
    ```
  </Tab>

  <Tab title="OpenCode">
    **Project file**: `AGENTS.md` in project root

    **Global file**: `~/.opencode/AGENTS.md`

    **Nested 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**:

    ```markdown theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Cursor">
    **Project file**: `.cursorrules` in project root

    **Global rules**: Settings → General → Rules for AI

    **Nested 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**:

    ```markdown theme={null}
    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
    ```
  </Tab>

  <Tab title="GitHub Copilot">
    **Project file**: `.github/copilot-instructions.md`

    **Global config**: Not supported (VS Code settings only)

    **Nested support**: No

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

    **Example content**:

    ```markdown theme={null}
    ## 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
    ```
  </Tab>

  <Tab title="Windsurf">
    **Project file**: `.windsurfrules` in project root

    **Global file**: `~/.codeium/windsurf/memories/global_rules.md`

    **Nested support**: Yes - `.windsurf/rules/` directory

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

    **Example content**:

    ```markdown theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Aider">
    **Project file**: `CONVENTIONS.md` in project root

    **Global config**: `~/.aider.conf.yml`

    **Nested support**: No

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

    **Example CONVENTIONS.md**:

    ```markdown theme={null}
    # 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**:

    ```yaml theme={null}
    model: claude-3-5-sonnet-20241022
    edit-format: diff
    auto-commits: true
    read:
      - CONVENTIONS.md
    ```
  </Tab>

  <Tab title="OpenAI Codex">
    **Project file**: `AGENTS.md` in project root

    **Global config**: Not supported

    **Nested support**: Yes

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

    **Example content**:

    ```markdown theme={null}
    # 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
    ```
  </Tab>
</Tabs>

## Universal Template

Use this template that works across most tools:

```markdown theme={null}
# 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
```

<Tip>
  **DRY approach**: Create one source file and symlink others:

  ```bash theme={null}
  # 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
  ```
</Tip>

## Best Practices

<Check>
  * 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
</Check>

<Warning>
  **Avoid:**

  * Duplicating documentation that's elsewhere
  * Including secrets or credentials
  * Over-specifying obvious conventions
  * Contradicting tool defaults without reason
</Warning>

## Related

<CardGroup cols={2}>
  <Card title="Context Optimization" icon="brain" href="/guides/context-optimization">
    Effective context feeding strategies
  </Card>

  <Card title="Slop Constraints" icon="filter" href="/concepts/slop">
    Control output quality
  </Card>
</CardGroup>