What is CLAUDE.md?
Quick definition
A markdown file documenting Claude AI agent capabilities, configuration, and integration patterns for developers implementing MCP protocols and agentic workflows.
CLAUDE.md is a documentation standard used by developers and AI system architects to formalize Claude AI agent specifications, capabilities, and integration requirements. Similar to README.md in open-source projects, CLAUDE.md serves as the authoritative reference for how Claude AI instances or agents should behave, what tools they can access, and how they integrate with MCP servers and client systems. This file typically includes agent identity, version information, supported MCP protocols, tool definitions, and behavioral constraints.
In the context of agentic workflows and multi-agent systems, CLAUDE.md functions as a machine-readable and human-readable contract between agents and their orchestrators. It documents the agent's context window size, tool-call patterns, rate-limiting requirements, and any prompt-injection protections or security measures implemented. Developers use CLAUDE.md to enable consistent agent deployment across headless-agent implementations, autonomous-coding scenarios, and human-in-the-loop systems where agents need to understand their own capabilities and limitations.
The format follows markdown conventions but may include embedded YAML frontmatter, JSON schema definitions for tool calls, and structured metadata compatible with JSON-LD for semantic web integration. CLAUDE.md enables rapid agent discovery, capability introspection, and configuration management in distributed agent-orchestration environments, making it essential documentation for MCP-compliant systems.
Example
How it shows up in practice
```markdown
# CLAUDE.md
## Agent Identity
Name: CodeAnalyzer v2.1
MCP Protocol: 1.0.1
## Capabilities
- Tool: code-review (max 8000 tokens)
- Tool: test-generation (rate-limit: 10/min)
- Supported Languages: Python, JavaScript, Go
## Context Window
Effective: 200K tokens
Reserved: 50K tokens
```Frequently asked questions
What is the difference between CLAUDE.md and AGENTS.md?
CLAUDE.md specifically documents Claude AI agent specifications and Claude-specific capabilities, while AGENTS.md is a broader framework for documenting any AI agent type with generic agent patterns and multi-agent orchestration details.
Is CLAUDE.md required for MCP server integration?
While not strictly required, CLAUDE.md is strongly recommended as a best practice for documenting agent-to-server contracts, capability exposure, and integration requirements in MCP environments.
Can CLAUDE.md include security credentials or API keys?
No. CLAUDE.md should never contain API keys, bearer tokens, or authentication secrets. Use environment variables or secure vault systems referenced via configuration files instead.
How does CLAUDE.md relate to tool-call definitions?
CLAUDE.md documents the schema and constraints for all tool calls an agent can invoke, including parameter validation, return types, rate limits, and error handling patterns expected by MCP clients and servers.