McGarrah Technical Blog

AI Coding Agent Context Files: A Reference Guide

By · 13 min read

Every AI coding assistant has its own way of reading project-level instructions. If you only use one tool, you learn its convention and move on. But if you work across multiple agents — or your team does — knowing exactly what each tool expects becomes essential.

This is a factual reference for the context and rules files used by every major AI coding assistant as of mid-2026. For strategies on managing these across tools, see the companion article Managing Context and Rules Across Multiple AI Coding Assistants.

Quick Reference Table

Agent Context Location Format Auto-Loaded Exclusions
Amazon Q .amazonq/rules/*.md Markdown Yes .amazonq/rules/ scoping
Claude Code CLAUDE.md, .claude/ Markdown Yes .claude/settings.json
GitHub Copilot .github/copilot-instructions.md Markdown Yes .github/copilot-instructions.md
Cursor .cursor/rules/*.mdc MDC (Markdown+frontmatter) Configurable .cursorignore
Windsurf .windsurf/rules/*.md Markdown Configurable .windsurfignore
Gemini Code Assist .gemini/styleguide.md Markdown Yes .aiexclude
Cline .clinerules, .cline/rules/*.md Markdown Yes .clineignore
Aider .aider.conf.yml YAML Yes .aiderignore
Kiro specs/, steering hooks Markdown specs Yes Spec-scoped

Amazon Q Developer

Amazon Q reads project rules from a .amazonq/rules/ directory at the repository root. Every .md file in that directory (and subdirectories) is automatically loaded into context for every chat and inline request.

File Structure

.amazonq/
└── rules/
    ├── coding-standards.md
    ├── project-context.md
    ├── git-credentials-context.md
    └── memory-bank/
        ├── guidelines.md
        ├── product.md
        ├── structure.md
        └── tech.md

Key Behaviors

Exclusions

Amazon Q does not have a dedicated ignore file. It respects .gitignore for file discovery. You can scope what the agent sees by structuring your rules to tell it what to avoid.

Example Rule File

# Project Context

## Overview
This is a Jekyll blog hosted on GitHub Pages.

## Coding Standards
- Wrap JavaScript in IIFEs with strict mode
- Use const/let, never var
- Include YAML front matter in all content files

## Build Commands
- `bundle exec jekyll serve` for development
- `bundle exec jekyll build` for production

Documentation

Claude Code (Anthropic)

Claude Code uses a CLAUDE.md file at the project root as its primary context mechanism. It also supports a .claude/ directory for settings and additional configuration.

File Structure

project-root/
├── CLAUDE.md              # Project-level instructions (committed)
├── .claude/
│   ├── settings.json      # Project settings (committed)
│   └── settings.local.json # Personal settings (gitignored)
└── ...

Key Behaviors

Exclusions

Claude Code respects .gitignore by default. Additional exclusions can be configured in .claude/settings.json:

{
  "permissions": {
    "deny": ["Bash(rm:*)", "Bash(sudo:*)"]
  }
}

Example CLAUDE.md

# CLAUDE.md

## Project Context
Jekyll blog with GitHub Pages hosting. Ruby 3.0+, Node.js 16+.

## Conventions
- YYYY-MM-DD format for post filenames
- All JavaScript in IIFEs with strict mode
- Front matter required on all content files

## Commands
- `bundle exec jekyll serve` — local dev
- `bundle exec jekyll build` — production build
- `npm audit` — security check

## Do Not
- Modify _site/ directory directly
- Remove existing test cases
- Use var in JavaScript

Documentation

GitHub Copilot

GitHub Copilot reads repository-level custom instructions from a single file at .github/copilot-instructions.md. This applies to Copilot Chat in VS Code, Visual Studio, JetBrains IDEs, and GitHub.com.

File Structure

.github/
└── copilot-instructions.md

Key Behaviors

Exclusions

Copilot respects a content exclusion policy configured at the organization or enterprise level in GitHub settings. There is no repository-level ignore file for Copilot specifically. It does respect .gitignore for file indexing.

Example File

# Copilot Instructions

## Language and Framework
This is a Ruby/Jekyll project. Prefer Ruby 3.0+ idioms.

## Code Style
- Use `const` and `let` in JavaScript, never `var`
- Wrap all JS in IIFEs with `'use strict'`
- Follow existing SCSS variable naming in `_sass/`

## Project Structure
- Blog posts go in `_posts/` with YYYY-MM-DD-title.md naming
- Custom plugins in `_plugins/` must set `safe true`
- Assets organized under `assets/` by type

## Testing
- Run `bundle exec jekyll build` to validate changes
- Check for broken links before committing

Documentation

Cursor

Cursor uses a .cursor/rules/ directory with files in MDC format (Markdown with YAML frontmatter). The legacy .cursorrules file at the project root is still supported but deprecated.

File Structure

.cursor/
└── rules/
    ├── general.mdc
    ├── python-style.mdc
    └── testing.mdc

Legacy (deprecated):

.cursorrules          # Single file, plain text/markdown

Key Behaviors

MDC Frontmatter Example

---
description: Python coding standards for this project
globs: "**/*.py"
alwaysApply: false
---

# Python Standards

- Use type hints on all function signatures
- Prefer pathlib over os.path
- Use virtual environments (.venv)

Exclusions

Cursor uses .cursorignore at the project root, with .gitignore syntax:

# .cursorignore
node_modules/
.env
*.secret
vendor/

There is also .cursorindexingignore which only affects Cursor’s codebase indexing but still allows the agent to read files if explicitly referenced.

Documentation

Windsurf (Codeium)

Windsurf uses a .windsurf/rules/ directory structure similar to Cursor, plus a legacy .windsurfrules file.

File Structure

.windsurf/
└── rules/
    ├── general.md
    └── python.md

Legacy:

.windsurfrules        # Single file at project root

Key Behaviors

Exclusions

Windsurf uses .windsurfignore with .gitignore syntax. It also respects .gitignore.

Documentation

Gemini Code Assist (Google)

Gemini Code Assist reads a style guide from .gemini/styleguide.md and supports a GEMINI.md file at the project root. It uses .aiexclude for file exclusions.

File Structure

.gemini/
└── styleguide.md

Or:

GEMINI.md             # Project root alternative

Key Behaviors

Exclusions

Gemini uses .aiexclude at the repository root with .gitignore-style syntax. This is a Gemini-specific mechanism that prevents the AI from reading or indexing matched files:

# .aiexclude
*.env
secrets/
*.pem
*.key
vendor/

This is separate from .gitignore — a file can be tracked in git but excluded from AI context.

Example Style Guide

# Style Guide

## General
- Follow Google's style guides for each language
- Use descriptive variable names
- Keep functions under 30 lines

## Jekyll Specific
- Front matter required on all posts
- Use excerpt separators for custom previews
- Organize assets by type under assets/

Documentation

Cline

Cline (formerly Claude Dev) is an open-source VS Code extension that supports both a .clinerules file and a .cline/rules/ directory.

File Structure

.cline/
└── rules/
    ├── general.md
    └── testing.md

Or:

.clinerules           # Single file at project root

Key Behaviors

Exclusions

Cline uses .clineignore with .gitignore syntax. It also respects .gitignore.

Documentation

Aider

Aider is an open-source CLI tool for AI pair programming. It uses YAML configuration files and a conventions system.

File Structure

project-root/
├── .aider.conf.yml    # Project-level configuration
└── .aiderignore       # File exclusions

User-level:

~/.aider.conf.yml      # Global configuration

Key Behaviors

Configuration Example

# .aider.conf.yml
model: claude-sonnet-4-20250514
auto-commits: true
read:
  - CONVENTIONS.md
  - docs/ARCHITECTURE.md

Exclusions

Aider uses .aiderignore with .gitignore syntax:

# .aiderignore
*.min.js
vendor/
_site/
node_modules/

Documentation

Amazon Kiro

Kiro is Amazon’s successor to Amazon Q Developer as an IDE. It takes a fundamentally different approach — spec-driven development rather than rules files.

File Structure

specs/
├── feature-name/
│   ├── requirements.md    # User stories and acceptance criteria
│   ├── design.md          # Technical design (auto-generated)
│   └── tasks.md           # Implementation tasks (auto-generated)

Steering hooks:

.kiro/
└── steering/
    ├── on-save.md         # Triggered on file save
    ├── on-commit.md       # Triggered on git commit
    └── custom-hook.md     # Custom automation triggers

Key Behaviors

How It Differs

Kiro’s approach is less about “here are my coding standards” and more about “here is what I want built.” The specs system replaces the rules-file pattern with a structured planning workflow. Steering hooks are the closest equivalent to rules files in other tools — they inject instructions at specific points in the development cycle.

Documentation

Comparison: Key Differences

Context Loading

Feature Amazon Q Claude Code Copilot Cursor Gemini
Multi-file rules ✅ Directory ❌ Single file ❌ Single file ✅ Directory ❌ Single file
Hierarchical (parent dirs) ❌ ✅ ❌ ❌ ❌
Conditional loading (globs) ❌ ❌ ❌ ✅ ❌
User-level global rules ✅ ~/.aws/amazonq/prompts/ ✅ ~/CLAUDE.md ✅ Org-level ✅ Settings ❌
Frontmatter/metadata ❌ ❌ ❌ ✅ Required Optional

Exclusion Mechanisms

Agent Exclusion File Syntax AI-Specific
Amazon Q .gitignore gitignore No (reuses git)
Claude Code .gitignore + settings gitignore + JSON Partial
GitHub Copilot Org-level policy Admin UI Yes
Cursor .cursorignore gitignore Yes
Windsurf .windsurfignore gitignore Yes
Gemini .aiexclude gitignore Yes
Cline .clineignore gitignore Yes
Aider .aiderignore gitignore Yes

Format Summary

Most agents use plain Markdown. The outliers:

What’s Missing from This Landscape

A few things stand out after surveying all of these:

When your team uses multiple AI tools — and increasingly, teams do — context file management becomes infrastructure. It’s a standardization problem that no vendor has solved yet, and until someone does, the strategies in the companion article are the best available workaround.

The companion article Managing Context and Rules Across Multiple AI Coding Assistants covers strategies for dealing with this fragmentation.

Revision History

Tags: ai, amazon-q, claude-code, github-copilot, cursor, windsurf, gemini, cline, aider, kiro, productivity, tooling
Categories: technical, development
About the Author: Michael McGarrah is a Cloud Architect with 25+ years in enterprise infrastructure, machine learning, and system administration. He holds an M.S. in Computer Science (AI/ML) from Georgia Tech and a B.S. in Computer Science from NC State University, and is currently pursuing an Executive MBA at UNC Wilmington. LinkedIn · Substack · GitHub · ORCID · Google Scholar · Resume