Skip to content

Conversation

@sebacc92
Copy link
Contributor

@sebacc92 sebacc92 commented Dec 8, 2025

docs: enhance LLM instructions (qwik-concepts.md) for AI editors

What is it?

  • Docs / tests / types / typos

Description

This PR significantly improves the qwik-concepts.md file (used as context for LLMs/AI Agents like Cursor, Antigravity, and Copilot).

Motivation:
Current LLMs often "hallucinate" React patterns (like useEffect or useState) when writing Qwik code. This update provides a stricter "System Prompt" style to force the correct mental model.

Changes:

  1. Added "Critical Anti-Patterns": Explicitly forbidding useEffect, useState, and nested Stores.
  2. Added React-to-Qwik Translation Table: A side-by-side guide for the AI to translate concepts (e.g., useEffect -> useTask$).
  3. Refined Task Usage: Clarified that useVisibleTask$ should be avoided in favor of useTask$ or useOnDocument to preserve Resumability.
  4. Syntax Rules: Added explicit rules for class vs className and sync$ events.

This incorporates feedback from previous discussions (PR #7729) to make the instructions robust for autonomous agents.

Checklist

  • My code follows the developer guidelines of this project
  • I performed a self-review of my own code
  • I added a changeset with pnpm change (Skipped as this is a docs-only change for starters)
  • I made corresponding changes to the Qwik docs
  • I added new tests to cover the fix / functionality

… and environment variable sections, and fix a typo.
@sebacc92 sebacc92 requested a review from a team as a code owner December 8, 2025 09:16
@changeset-bot
Copy link

changeset-bot bot commented Dec 8, 2025

⚠️ No Changeset found

Latest commit: e2ab04c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Copy link
Member

@wmertens wmertens left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@wmertens
Copy link
Member

wmertens commented Dec 8, 2025

@sebacc92 please run prettier on the file to fix the lint error. I think the other error is transient

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants