Claude Code reads AGENTS.md only when telemetry is on [fixed]

Why Your AGENTS.md Was Being Ignored (And What You Can Do About It)

If you’ve ever created an AGENTS.md file in your project root—carefully crafting instructions for how Claude Code should behave, only to watch it completely ignore your directives—you’re not imagining things. There was a genuine, well-documented reason: Claude Code historically required telemetry to be enabled before it would read the file. For privacy-conscious developers, this created a frustrating catch-22.

This issue has since been addressed, but understanding the underlying mechanism matters if you want to get the most out of Claude Code and similar AI-assisted development tools.

What AGENTS.md Actually Does

Before diving into the telemetry dependency, let’s clarify what AGENTS.md is and why it exists. This file lives in your project root and acts as a persistent instruction set for Claude Code. Think of it as a project-specific personality and guidelines document.

A typical AGENTS.md might look like this:

# Project Agent Instructions

## Code Style
- Use TypeScript strict mode
- Prefer functional components in React
- Maximum line length: 100 characters

## Testing Requirements
- All new functions require unit tests
- Use Vitest for testing
- Minimum 80% coverage for core modules

## Commit Convention
- Follow Conventional Commits spec
- Squash related changes into single commits

## Don't Do These Things
- Don't add console.log statements
- Don't use `any` type in TypeScript
- Don't skip error handling

When Claude Code reads this file, it internalizes these constraints and applies them across your entire session. The tool becomes aware that your project uses TypeScript, has specific testing requirements, and follows particular conventions—without you repeating yourself every session.

The practical impact is significant. In a mid-sized codebase, developers report spending less time correcting AI-generated code to match project standards, and more time shipping features.

The Telemetry Dependency Problem

Here’s what was happening: earlier versions of Claude Code only read AGENTS.md when telemetry was enabled. The reasoning was tied to how Anthropic implemented the feature—the file parsing was bundled with the telemetry pipeline.

For developers who disabled telemetry (a perfectly reasonable privacy choice, especially in corporate environments or for proprietary projects), Claude Code simply wouldn’t pick up their AGENTS.md instructions. The file existed, it was correctly formatted, but the tool behaved as if it weren’t there.

This created three real problems:

1. Inconsistent behavior across different installation configurations
2. Privacy trade-offs where developers had to choose between project configuration and data privacy
3. Debugging confusion since there was no clear error message—just silent ignorance of the file

The fix addresses all three, but understanding the original design helps you reason about how Claude Code processes project context in general.

How the Fix Works

The update separates AGENTS.md parsing from telemetry entirely. Claude Code now reads the file as part of its standard initialization sequence, regardless of telemetry settings. This means:

# This now works whether telemetry is on or off
claude --no-telemetry  # AGENTS.md is still read

You can verify this yourself by creating a test project:

mkdir /tmp/agents-test && cd /tmp/agents-test
cat > AGENTS.md << 'EOF'
# Test Configuration
- You are helping with a Python project
- Use type hints for all function parameters
EOF

# Run with telemetry disabled
CLAUDE_TELEMETRY=off claude --print "What language is this project using?"

Previously, Claude would answer generically. After the fix, it correctly identifies the project context from AGENTS.md.

Why This Matters for Your API Integrations

The AGENTS.md mechanism in Claude Code mirrors a broader pattern you’ll encounter when building with AI APIs directly—whether you’re using Claude through the API, GPT models, or Gemini. Context injection is how you teach AI systems about your specific requirements.

When you’re working with the Anthropic API directly, you don’t have an AGENTS.md file. Instead, you pass project context through the system prompt:

import anthropic

client = anthropic.Anthropic()

system_prompt = """You are working on a legacy Python 2.7 codebase.
- Do not suggest Python 3 features
- Avoid f-strings (use .format() instead)
- Maintain existing code style even if suboptimal
"""

message = client.messages.create(
    model="claude-opus-4",
    max_tokens=1024,
    system=system_prompt,
    messages=[
        {"role": "user", "content": "Refactor this function to be more efficient"}
    ]
)

The tradeoff here is explicit control versus convenience. With AGENTS.md, the configuration lives in your repository and travels with your code. With direct API calls, you manage context programmatically—which offers more flexibility but requires more discipline.

For teams running multiple AI models, managing these context files becomes a real operational concern. Tools that aggregate API access across providers can help standardize how you manage these configurations. AI Prime Tech offers unified API access that lets you apply consistent context management patterns whether you’re using Claude, GPT-6, or Gemini 3.

Practical Configuration Patterns

Getting the most out of AGENTS.md requires understanding what belongs in it and what doesn’t.

What Belongs in AGENTS.md

• Project-specific conventions that differ from defaults (test framework, coding style, directory structure)
• Non-negotiable constraints (compliance requirements, security policies)
• Context that would otherwise require repetition (this is a monorepo, these are the package boundaries)
• CI/CD context (how tests are run, what the deployment pipeline expects)

What Doesn’t Belong

• Instructions for the AI’s personality or tone (keep those in a personal .claude config)
• Sensitive credentials or secrets (use environment variables and proper secret management)
• Outdated information (stale AGENTS.md files cause more confusion than having none)

A Realistic Example

Here’s an AGENTS.md from a practical production project:

# Backend API Agent Configuration

## Project Context
This is a Node.js/Express API with PostgreSQL. We use Prisma as the ORM.

## Code Standards
- All endpoints return consistent error shapes: `{ error: string, code: string }`
- Use async/await, never .then() chains
- No `console.log` in server code—use the configured logger

## Security Requirements
- Never disable authentication checks in code
- All database queries must use parameterized queries (Prisma handles this)
- Validate all external input with express-validator

## Testing Strategy
- Integration tests for all routes (supertest + test database)
- Unit tests for business logic only
- Mock external services (payment gateway, email)

## Common Pitfalls
- Don't suggest Redis caching without discussing it first
- Avoid N+1 queries (always use include() or explicit joins)

Version Control Considerations

One thing to be intentional about: AGENTS.md should live in version control and be reviewed like any other project file. When a developer changes the testing framework from Jest to Vitest, updating AGENTS.md is part of that change. This ensures:

1. Onboarding works: New developers get correct context immediately
2. Consistency across machines: The same instructions apply to everyone
3. Audit trail: Changes to AI behavior are tracked alongside code changes

The Broader Pattern

The telemetry-AGENTS.md issue illustrates a pattern that appears repeatedly in AI-assisted development: the tension between convenience and privacy, between default behaviors and explicit configuration.

As AI tools become more sophisticated, they’ll read more files, infer more context, and make more assumptions. The developers who understand exactly what’s being read, when, and why will get better results than those who treat these tools as black boxes.

This applies whether you’re using Claude Code, building custom integrations with the Claude API, or working with any of the major model providers. The ability to precisely control an AI system’s context—through files, system prompts, or API parameters—is becoming a core developer skill.

Practical Takeaways

1. Verify your setup: Run claude --info to confirm telemetry and AGENTS.md reading are working as expected in your environment.

2. Audit existing AGENTS.md files: If you have projects where configuration was inconsistent, now is a good time to review and clean up those files.

3. Treat AGENTS.md as code: Review it in pull requests, update it when project conventions change, and remove it if it becomes stale.

4. Consider the API parallel: If you’re building custom AI integrations, apply the same discipline you’d use for AGENTS.md—make context explicit, version it, and review changes.

5. Monitor for new capabilities: Claude Code and similar tools are actively developed. Keep track of what configuration files they support, because the set of files these tools read by default is likely to grow.