Skip to content

docs(agents): make AGENTS.md the single source of agent guidelines - #6535

Open
Enizri wants to merge 3 commits into
simstudioai:stagingfrom
Enizri:docs/sync-claude-md-with-agents
Open

docs(agents): make AGENTS.md the single source of agent guidelines#6535
Enizri wants to merge 3 commits into
simstudioai:stagingfrom
Enizri:docs/sync-claude-md-with-agents

Conversation

@Enizri

@Enizri Enizri commented Aug 11, 2026 •
edited
Loading

Copy link
Copy Markdown

Summary

  • AGENTS.md and CLAUDE.md previously held the same guidelines content, and AGENTS.md had drifted behind
  • Duplicate sources force agents to load redundant context (token waste) and make conflicting edits more likely (hallucination / stale guidance)
  • Collapse to one source of truth: AGENTS.md owns the guidelines; CLAUDE.md is a short pointer to it
  • Update sim-components rule pointers from CLAUDE.md → AGENTS.md so tooling tracks the canonical file

Why

One canonical guidelines file is easier to keep in sync, cheaper for agents to read, and reduces the chance of following outdated duplicated instructions.

Test plan

  • Confirm CLAUDE.md only points at AGENTS.md
  • Confirm .claude/rules/sim-components.md and .cursor/rules/sim-components.mdc reference AGENTS.md
  • Spot-check that agent tooling still resolves guidelines via AGENTS.md

@Enizri
Enizri requested a review from a team as a code owner August 11, 2026 07:17
@greptile-apps

greptile-apps Bot commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

Too many files changed for review (691 files, 100 file limit).

@vercel

vercel Bot commented Aug 11, 2026

Copy link
Copy Markdown

@Enizri is attempting to deploy a commit to the Sim Team on Vercel.

A member of the Team first needs to authorize it.

@cursor

cursor Bot commented Aug 11, 2026 •
edited
Loading

Copy link
Copy Markdown

PR Summary

Low Risk
Documentation and rule-pointer updates only; no application runtime or API behavior changes.

Overview
Consolidates duplicated agent guidelines so AGENTS.md holds the full Sim development guide and CLAUDE.md is only a pointer to it, cutting redundant context for agents and avoiding drift between two copies.

AGENTS.md gains the content that lived in CLAUDE.md (and fixes that had fallen behind), including type-checking/@typescript/native, @sim/emcn import paths, React Query staleTime as exported constants, URL state via nuqs, list/menu ordering rules, block registration in registry-maps.ts, and links to .claude/rules for performance and URL state.

Rule file pointers in .claude/rules/sim-components.md and .cursor/rules/sim-components.mdc now cite AGENTS.md > Components instead of CLAUDE.md.

Reviewed by Cursor Bugbot for commit 5b7559d. Bugbot is set up for automated code reviews on this repo. Configure here.

@Enizri
Enizri changed the base branch from main to staging August 11, 2026 07:19
@claude
chore: retrigger review bots
5b7559d 
The Greptile and Cursor Bugbot runs on this PR happened while the base
branch was still main, so both reviewed the full staging-vs-main drift
(691 files) instead of this change. Greptile skipped on the file limit
and Bugbot's findings were about unrelated code. Empty commit to re-run
both against the actual 4-file diff now that the base is staging.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017mcwsfh2YtUU4bS9b9sFif
@Enizri

Enizri commented Aug 11, 2026

Copy link
Copy Markdown
Author

@waleedlatif1 I think that PR worth your attention (:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Enizri @claude