Skip to content

[Chore][nextjs] Slimmer LLM guidance docs#426

Draft
art-alexeyenko wants to merge 5 commits intodevfrom
poc/better-llm-context
Draft

[Chore][nextjs] Slimmer LLM guidance docs#426
art-alexeyenko wants to merge 5 commits intodevfrom
poc/better-llm-context

Conversation

@art-alexeyenko
Copy link
Copy Markdown
Collaborator

Slim down skills, AGENTS.md and other LLM files in samples to limit the amount of context loaded and limit token use.

  • Load skills, other info only when needed
  • Apply layering approach to main AGENTS.md in templates

Rough impact:

**Default stack (S0: `CLAUDE.md` + `AGENTS.md`)** — This is the main “always-on” doc cost if both are loaded.

- **nextjs:** ~18.0 KB → ~8.2 KB (**~54% smaller**; ~4500 → ~2050 approximate tokens).
- **nextjs-app-router:** ~20.5 KB → ~9.2 KB (**~55% smaller**; ~5100 → ~2300 approximate tokens).

Roughly **half the size of a short technical article** removed from the default stack, or on the order of **8–10 typewritten pages** fewer text at ~2 KB/page (very approximate).

**Skills index (S1)** — `Skills.md` alone.

- **nextjs:** ~5.3 KB → ~3.7 KB (**~30% smaller**).
- **nextjs-app-router:** ~5.2 KB → ~3.7 KB (**~29% smaller**).

**Scaffold-style load** — Compare historical worst case (two scaffold-related skills + **monolithic** `AGENTS.md`) to the intended layered path (same skills + `AGENTS-router-specifics.md` + `AGENTS-workflows-and-boundaries.md` only).

- **nextjs:** ~19.3 KB → ~9.3 KB (**~52% smaller** than monolith + skills).
- **nextjs-app-router:** ~21.8 KB → ~10.8 KB (**~50% smaller**).

If the agent still attaches **slim** `AGENTS.md` plus both skills (~9.7 KB / ~10.8 KB), that is still well below the old monolith + skills totals.

**Full corpus (S3)** — All `.md` under `.agents/`, plus root `AGENTS.md`, `Skills.md`, `CLAUDE.md`, and `.cursor/rules/*.mdc`.

- **nextjs:** ~46.3 KB → ~48.9 KB (**~6% larger**) — expected: same text, more file overhead and README / layer preambles.
- **nextjs-app-router:** ~48.8 KB → ~51.8 KB (**~6% larger**).

@illiakovalenko
Copy link
Copy Markdown
Collaborator

@art-alexeyenko What’s the current status of this PR? Could you please revisit it?

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants