fix: replace CLAUDE.md symlink with real file

[NathanDrake2406]

Just found out that my Claude Code hasn't been loading instructions at all cuz Claude Code doesn't load symlinks lol. Maybe that's why the code was so buggy.

While at it, rewrote agents.md using the claude-md-improver skill — it was bloated and outdated.

---

What changed

1. CLAUDE.md symlink fix

CLAUDE.md was a symlink → AGENTS.md. Claude Code doesn't follow symlinks, so project-level instructions were never loaded. Re-created as a proper symlink to agents.md (lowercase, the real file).

2. agents.md rewrite (393 → 135 lines)

Used the claude-md-improver skill to audit, score, and iteratively improve the file across 6 iterations.

Quality scores across iterations

Iteration	Score	Grade	Key change
Original	52/100	C	Bloated, outdated architecture, unnecessary sections
Rewrite v1	88/100	B+	Stripped to essentials, updated ALS architecture
+ context abstractions + test mapping	93/100	A	Added three context types gotcha, test file table
+ serverExternalPackages + Context7	95/100	A	Non-obvious patterns, Context7 library IDs
+ debugging + Next.js test search + git workflow	98/100	A+	Restored genuinely useful over-trimmed items
De-duped RSC/SSR section, --admin ban, merged ecosystem/config	100/100	A+	Zero repeated info, zero filler

Final score breakdown

Criterion	Score	Notes
Commands/workflows	20/20	Commands, test mapping, full PR workflow
Architecture clarity	20/20	Unified ALS with module graph caveat in one paragraph, three context types
Non-obvious patterns	15/15	Virtual modules, thenable params, ISR, debugging, ecosystem + config compat
Conciseness	15/15	135 lines, no repeated info, zero filler
Currency	15/15	Accurate post-#450, reflects current codebase
Actionability	15/15	Context7 IDs, gh search code, copy-paste PR flow

What was removed (and why)

Section	Lines	Why removed
"Adding a New Example" walkthrough	~40	Step-by-step hand-holding agents don't need
"Smoke Tests" details	~15	Belongs in contributor guide, not agent context
"Porting Strategy"	~10	Edge case, not daily context
"Research Tools" verbose explanation	~30	Replaced with concise Context7 section with library IDs
"CI for External Contributors"	~25	Irrelevant to agents writing code
Examples table + URLs	~12	Agents can read the examples/ directory

What was added/updated

Addition	Why
Unified Request Context (ALS) section	Old doc described 5-6 nested ALS scopes; #450 unified them into one
RSC/SSR module graph caveat	Folded into ALS section — separate heading was redundant
Three Context Abstractions	Agents hit RequestContext from 3 files and get confused
Test file mapping table	Compact version of "which test to run" — saves guessing
entries/ annotated as code generators	Not runtime code — agents modify the emitted strings, not the module itself
Ecosystem & Config Compat	Merged serverExternalPackages + library compat into one section
Context7 section	Library IDs + instruction to always query before guessing Next.js behavior
Next.js test suite search	gh search code command in Code Style
Git workflow	Full PR flow for contributors without global rules
Fixed dev-server.ts description	Was "Pages Router SSR handler" — actually handles both Pages + App Router
Removed cloudflare/worker-entry.ts reference	File doesn't exist

Skill used

claude-md-improver (from claude-plugins-official/claude-md-management) — ran 6 iterations:

1. Discovery + initial quality assessment → 52/100
2. Full rewrite targeting identified issues → 88/100
3. Targeted additions (context abstractions, test mapping) → 93/100
4. Non-obvious patterns (serverExternalPackages, Context7) → 95/100
5. Restored over-trimmed items (debugging, git workflow, Next.js test search) → 98/100
6. De-duplicated (merged RSC/SSR into ALS, combined ecosystem/config, removed triple --admin mention) → 100/100

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/vinext@528

commit: ca38ce8

[james-elicx]

Claude should be following symlinks. If it's not, that's a bug in Claude that they need to fix - I'd prefer not to duplicate the file in the repo...

[NathanDrake2406]

Claude should be following symlinks. If it's not, that's a bug in Claude that they need to fix - I'd prefer not to duplicate the file in the repo...

Hmm I just took a look at the agents.md, it's pretty bloated and kind of stale. I'll amend this PR and make an update to the file