Entries for September 8, 2025

This post will age like sour milk, because Anthropic will eventually adopt the company-agnostic AGENTS.md standard.

For those that do not know, AGENTS.md is like robots.txt, but for providing plain text context to any AI agent working in your codebase.

It’s very stupid really. It’s not even worthy of being called a “standard”. The only rule is the name of the file.

Anthropic champions CLAUDE.md, named after their own agent Claude. Insisting on that stupid convention is like Google forcing websites to use googlebot.txt instead of robots.txt, or Microsoft clippy.txt.

Anyway, since this post will become irrelevant very soon, here are some AI-generated instructions on how to migrate your CLAUDE.md files to AGENTS.md.

Why Migrate?

Open Standard: AGENTS.md is an open standard that works with multiple AI systems
Interoperability: Maintains backward compatibility through symlinks
Future-Proof: Not tied to a specific AI platform or tool
Consistency: Standardizes agent instructions across the codebase

Actual Migration Commands Used

Step 1: Rename Files

The following commands were used to rename existing CLAUDE.md files to AGENTS.md:

# Find all CLAUDE.md files and rename them to AGENTS.md
find . -name "CLAUDE.md" -type f -exec sh -c 'mv "$1" "${1%CLAUDE.md}AGENTS.md"' _ {} \;

Step 2: Update Content

Replace Claude-specific references with agent-agnostic language:

# Update file headers in all AGENTS.md files
find . -name "AGENTS.md" -type f -exec sed -i '' 's/This file provides guidance to Claude Code (claude.ai\/code)/This file provides guidance to AI agents/g' {} \;

Step 3: Update .gitignore

Add these lines to .gitignore to ignore symlinked CLAUDE.md files:

# Add to .gitignore
cat >> .gitignore << 'EOF'

# CLAUDE.md files (automatically generated from AGENTS.md via symlinks)
CLAUDE.md
**/CLAUDE.md
EOF

Step 4: Create Symlink Setup Script

Create utils/setup-claude-symlinks.sh with the following content:

#!/bin/bash

# Script to create CLAUDE.md symlinks to AGENTS.md files
# This allows CLAUDE.md files to exist locally without being committed to git

set -e

echo "Setting up CLAUDE.md symlinks..."

# Change to repository root
cd "$(git rev-parse --show-toplevel)"

# Find all AGENTS.md files and create corresponding CLAUDE.md symlinks
git ls-files | grep "AGENTS\.md$" | while read -r file; do
    dir=$(dirname "$file")
    claude_file="${file/AGENTS.md/CLAUDE.md}"
    
    # Remove existing CLAUDE.md file/link if it exists
    if [ -e "$claude_file" ] || [ -L "$claude_file" ]; then
        rm "$claude_file"
        echo "Removed existing $claude_file"
    fi
    
    # Create symlink
    if [ "$dir" = "." ]; then
        ln -s "AGENTS.md" "CLAUDE.md"
        echo "Created symlink: CLAUDE.md -> AGENTS.md"
    else
        ln -s "AGENTS.md" "$claude_file"
        echo "Created symlink: $claude_file -> AGENTS.md"
    fi
done

echo ""
echo "✓ CLAUDE.md symlinks setup complete!"
echo "  - CLAUDE.md files are ignored by git"
echo "  - They will automatically stay in sync with AGENTS.md files"
echo "  - Run this script again if you add new AGENTS.md files"

Step 5: Run Symlink Setup

Make the script executable and run it:

chmod +x utils/setup-claude-symlinks.sh
./utils/setup-claude-symlinks.sh

Top-Level AGENTS.md Note

Add this note to the main AGENTS.md file:

**Note**: This project uses the open AGENTS.md standard. These files are symlinked to CLAUDE.md files in the same directory for interoperability with Claude Code. Any agent instructions or memory features should be saved to AGENTS.md files instead of CLAUDE.md files.

Directory Structure After Migration

project/
├── AGENTS.md          # Primary agent instructions
├── CLAUDE.md          # Symlink to AGENTS.md (git ignored)
├── utils/
│   └── setup-claude-symlinks.sh  # Symlink setup script
├── backend/
│   ├── AGENTS.md      # Backend-specific instructions
│   └── CLAUDE.md      # Symlink to AGENTS.md (git ignored)
└── apps/
    ├── AGENTS.md      # Frontend-specific instructions
    ├── CLAUDE.md      # Symlink to AGENTS.md (git ignored)
    └── web/
        ├── AGENTS.md  # App-specific instructions
        └── CLAUDE.md  # Symlink to AGENTS.md (git ignored)

Content Update Examples

Before Migration

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

After Migration

# AGENTS.md

This file provides guidance to AI agents when working with code in this repository.

Verification Commands

Verify the migration worked correctly:

# Check all AGENTS.md files exist
find . -name "AGENTS.md" -type f

# Verify symlinks are created
find . -name "CLAUDE.md" -type l

# Check symlinks point to correct files
find . -name "CLAUDE.md" -type l -exec ls -la {} \;

# Verify content is agent-agnostic
grep -r "Claude Code (claude.ai/code)" . --include="*.md" | grep AGENTS.md

Maintenance

Adding New AGENTS.md Files

When you add new AGENTS.md files, run the symlink setup script:

./utils/setup-claude-symlinks.sh

Checking Symlink Status

# List all symlinks
find . -name "CLAUDE.md" -type l -exec ls -la {} \;

# Check for broken symlinks
find . -name "CLAUDE.md" -type l ! -exec test -e {} \; -print

Benefits of This Approach

Backward Compatibility: Existing tools expecting CLAUDE.md files continue to work
Git Clean: CLAUDE.md files are not tracked in version control
Automatic Sync: Symlinks ensure CLAUDE.md always matches AGENTS.md
Easy Maintenance: Single script handles all symlink creation/updates
Open Standard: Future-proof with the open AGENTS.md standard

Troubleshooting

Broken Symlinks

# Remove all CLAUDE.md symlinks and recreate
find . -name "CLAUDE.md" -type l -delete
./utils/setup-claude-symlinks.sh

Permission Issues

# Make sure script is executable
chmod +x utils/setup-claude-symlinks.sh

This migration preserves all existing functionality while adopting the open AGENTS.md standard for better interoperability.

CLAUDE.md to AGENTS.md Migration Guide