Tool Configurations as Context

The previous page established documentation as explicit project context. This page examines a specialized category of documentation: configuration files that directly shape agent behavior. These files CLAUDE.md, AGENTS.md, .cursorrules, and similar formats function as the "request model" for agent interactions. They define what agents should do, how they should do it, and what they should avoid.

The configuration file landscape

Different AI coding tools read different configuration files, but they serve the same purpose: providing persistent instructions that apply across all conversations.

The AGENTS.md format has emerged as an open standard, governed by the Agentic AI Foundation under the Linux Foundation. CLAUDE.md remains specific to Claude Code but follows similar principles. Understanding both patterns enables effective multi-tool workflows.

Configuration files as the request model

Configuration files function differently than documentation. Documentation informs; configuration files instruct. The distinction matters for understanding their role in the context hierarchy.

Always-loaded context

Unlike documentation that loads selectively, configuration files load automatically at session start. This makes them the foundation of agent behavior the "ground truth" that persists across every interaction.

Claude Code loads configuration files in a specific hierarchy:

This hierarchy enables layered configuration. An organization can enforce security requirements while teams customize workflows and individuals adjust preferences.

The token cost of permanence

Because configuration files load with every conversation, their size matters. Research on effective CLAUDE.md files finds they average 485-535 words. Frontier models reliably follow 150-200 instructions; beyond this threshold, instruction-following degrades uniformly.

The practical implication: configuration files should contain only universally applicable guidance. Instructions relevant to specific tasks belong in documentation loaded selectively, not in always-loaded configuration.

Structuring effective configuration files

Configuration file effectiveness depends on what they contain and how they structure it.

The WHAT-WHY-HOW framework

Effective configuration addresses three questions:

WHAT: The technical foundation

• Technology stack and versions
• Build, test, and deployment commands
• Project structure overview

WHY: The contextual purpose

• Project goals and constraints
• Team conventions and their rationale
• Quality standards and their justification

HOW: The operational workflow

• Command sequences for common tasks
• Verification steps before committing
• Error recovery procedures

This framework ensures agents understand not just what to do, but why enabling better judgment when encountering situations not explicitly covered.

Practical structure example

# Project Overview
TypeScript 5.3, React 18, Tailwind CSS 4. Monorepo using pnpm workspaces.

# Commands
- `pnpm build` - Build all packages
- `pnpm test` - Run test suite
- `pnpm lint` - Check code style

# Code Conventions
- Use functional components with hooks
- Prefer named exports over default exports
- See src/components/Button.tsx for component pattern

# Workflow
1. Run tests before committing
2. Run linter after code changes
3. Create feature branches from main

# Boundaries
- NEVER commit .env files or secrets
- ASK before adding new dependencies
- DO NOT modify vendor directories

This example demonstrates conciseness. It provides essential guidance without exhaustive explanation. Each instruction applies to most sessions, justifying its position in always-loaded context.

Reference application anchoring

Configuration files benefit from pointing to concrete examples rather than abstract descriptions.

The pointer principle applied

Rather than describing patterns, configuration files should reference implementations:

Abstract (problematic):

Use the repository pattern for data access with proper error handling and logging.

Concrete (improved):

For data access patterns, see src/repositories/UserRepository.ts.
For error handling conventions, see src/utils/errors.ts:15-45.

Pointers provide several advantages:

• Agents can read the actual implementation when needed
• References stay current with the code they point to (unlike embedded snippets that drift)
• Less token consumption when agents do not need the referenced content
• Clear navigation for agents exploring the codebase

The reference application pattern

Large projects benefit from designating reference implementations canonical examples that demonstrate all conventions in context.

# Reference Implementations
- Complete feature: src/features/auth/ (authentication flow)
- Component pattern: src/components/DataTable/ (complex component)
- API endpoint: src/api/users.ts (REST patterns)
- Test suite: src/features/auth/__tests__/ (testing conventions)

When implementing new features, follow patterns established in reference implementations.

This approach scales better than enumerating every convention. Agents can examine reference implementations when encountering novel situations.

The MCP extension pattern

Configuration files define static context information that does not change during a session. The Model Context Protocol (MCP) enables dynamic context: information retrieved from external sources at runtime.

How MCP extends agent capabilities

MCP servers provide three primitives to agents:

This architecture enables agents to access information beyond what fits in configuration files or documentation live database state, real-time API responses, or current system metrics.

MCP in the context hierarchy

MCP complements rather than replaces configuration files:

Configuration files → Define what agents should do
Documentation → Provide reference information
MCP servers → Supply live, dynamic context

A practical example: a configuration file specifies "query the development database for test data" while an MCP server provides the actual connection and query execution. The configuration defines intent; MCP enables capability.

Security considerations

MCP servers expose powerful capabilities. Configuration files should specify security boundaries:

# MCP Permissions
- Database MCP: Development databases only
- Filesystem MCP: Project directory only, read-only access
- GitHub MCP: Repository access requires explicit approval

NEVER use MCP servers with production credentials without human review.

The principle of minimal privilege applies. Grant only the access agents need for legitimate tasks.

Building and maintaining configuration

Configuration file development follows an iterative process distinct from documentation writing.

Configuration and the context hierarchy

Configuration files occupy a unique position in the context engineering hierarchy. They represent the most authoritative layer of project context explicit, persistent, and always present.

Strong configuration reduces burden on every other layer. Agents require shorter prompts when foundational guidance persists automatically. Conversations stay focused when common questions have configuration-level answers. Documentation can address specialized topics when basics load through configuration.

The next page examines conversation context the dynamic layer where context builds, degrades, and requires active management across multiple interactions.