Rename AGENTS.md to CLAUDE.md

[HardlyDifficult]

Summary

• Remove CLAUDE.md symlink that pointed to AGENTS.md
• Rename AGENTS.md to CLAUDE.md as the real file

Cursor picks up both files but Claude only recognizes CLAUDE.md. Consolidating to just CLAUDE.md.

Test plan

• Verify CLAUDE.md is a real file (not symlink)
• Verify AGENTS.md is removed

---

Note

Low Risk
Docs-only file move/rename; no runtime code, build, or dependency changes.

Overview
Consolidates the repo’s contributor/agent instructions by removing AGENTS.md and creating a full CLAUDE.md containing the same guidance (replacing the prior CLAUDE.md pointer).

^{Written by Cursor Bugbot for commit 14b6cb1. This will update automatically on new commits. Configure here.}

[claude]

Claude finished @HardlyDifficult's task —— View job

---

Reviewing PR: Rename AGENTS.md to CLAUDE.md

Todo List:

• Examine the new CLAUDE.md file contents
• Check for references to AGENTS.md in other files that may need updating
• Analyze the consolidation approach and tooling benefits
• Provide comprehensive review feedback

---

Review Feedback

✅ Overall Assessment: APPROVED

This is a well-executed documentation consolidation change that addresses a practical tooling issue.

📋 Code Quality & Best Practices

• Excellent: The file rename preserves all content integrity (232 lines moved exactly)
• Good approach: Converting from symlink to real file eliminates potential confusion
• Clean execution: Atomic change that removes ambiguity between AGENTS.md and CLAUDE.md

🐛 Issues Found

1. Minor: Reference in .github/instructions/*.instructions.md:3 still points to AGENTS.md and needs updating
2. Inconsistency: The "Related Repos" table (lines 221-226) still references AGENTS.md for other repositories - this is actually correct since those repos still use AGENTS.md

🚀 Performance Considerations

• Positive impact: Eliminates symlink resolution overhead
• Tool compatibility: Resolves the Cursor vs Claude recognition issue mentioned in the PR description

🔒 Security Concerns

• None identified: This is a documentation-only change with no security implications
• Low risk: No runtime code, build processes, or dependencies affected

📊 Test Coverage

• Not applicable: Documentation changes don't require test coverage
• Verification: The test plan correctly identifies the key verification points:
  • ✅ CLAUDE.md is now a real file (not symlink)
  • ✅ AGENTS.md is removed

🔧 Recommended Actions

Required Fix:

Update .github/instructions/*.instructions.md line 3 to reference CLAUDE.md instead of AGENTS.md:

- **Read `AGENTS.md`** — it is the source of truth for this repository.
+ **Read `CLAUDE.md`** — it is the source of truth for this repository.

Notes:

• The external repository references in the "Related Repos" table should remain as AGENTS.md since those repositories haven't been renamed yet
• The reference to canton/AGENTS.md on line 8 is correct as it points to a different repository

✨ Benefits of This Change

1. Tool Compatibility: Resolves IDE/AI tool confusion between symlink and actual file
2. Simplicity: Eliminates the symlink indirection
3. Consistency: Aligns with the fact that Claude tooling expects CLAUDE.md specifically

This is a straightforward, low-risk improvement that enhances developer experience.

---