[PR #528] [CLOSED] fix: replace CLAUDE.md symlink with real file #648

New issue

Closed

opened 2026-05-06 13:09:18 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 13:09:18 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/528
Author: @NathanDrake2406
Created: 3/13/2026
Status: ❌ Closed

Base: main ← Head: fix/claude-md-symlink

📝 Commits (6)

7136adc fix: replace CLAUDE.md symlink with real file
067042c refactor: rewrite agents.md and re-symlink CLAUDE.md
c2af1b6 fix: correct CLAUDE.md symlink casing to match AGENTS.md
33b3768 fix: address review feedback on AGENTS.md
a960746 docs: add debugging tips, Context7 refs, and fixture guidance
0768bd7 docs: complete AGENTS.md with missing structure, gotchas, and test mappings

📊 Changes

2 files changed (+122 additions, -332 deletions)

View changed files

📝 AGENTS.md (+121 -331)
📝 CLAUDE.md (+1 -1)

📄 Description

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:

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

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/cloudflare/vinext/pull/528 **Author:** [@NathanDrake2406](https://github.com/NathanDrake2406) **Created:** 3/13/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/claude-md-symlink` --- ### 📝 Commits (6) - [`7136adc`](https://github.com/cloudflare/vinext/commit/7136adcc75fceb13c698e7fead839d193e0d8b07) fix: replace CLAUDE.md symlink with real file - [`067042c`](https://github.com/cloudflare/vinext/commit/067042c8c0647ce14ae778a5f064258c840333fa) refactor: rewrite agents.md and re-symlink CLAUDE.md - [`c2af1b6`](https://github.com/cloudflare/vinext/commit/c2af1b6fe228d8680bcb7101676125df55117002) fix: correct CLAUDE.md symlink casing to match AGENTS.md - [`33b3768`](https://github.com/cloudflare/vinext/commit/33b37687f6c97d9b91f86262137b8e15ed4b2969) fix: address review feedback on AGENTS.md - [`a960746`](https://github.com/cloudflare/vinext/commit/a960746832badb34186407e5f8f104e61189b2dd) docs: add debugging tips, Context7 refs, and fixture guidance - [`0768bd7`](https://github.com/cloudflare/vinext/commit/0768bd73440e0b77df05c8109c88c6e796279d9e) docs: complete AGENTS.md with missing structure, gotchas, and test mappings ### 📊 Changes **2 files changed** (+122 additions, -332 deletions) <details> <summary>View changed files</summary> 📝 `AGENTS.md` (+121 -331) 📝 `CLAUDE.md` (+1 -1) </details> ### 📄 Description 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 --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>