solid-rules: the markdown file that keeps AI from writing React in Solid
Aiden Bai turns SolidJS's sharpest footguns into AGENTS.md guardrails, revealing a new kind of infrastructure: documentation written for code-generating agents, not humans.
AGENTS.md for SolidJS
- solid-rules treats documentation as part of the execution path, because an agent needs framework constraints before it can write the first token.
- The repo works because it targets the exact SolidJS habits that LLMs flatten into React-shaped defaults.
- Its real power is translation, turning human intent into constraints that preserve reactivity, list semantics, and prop behavior.
- The project sits in a wider agent-rules ecosystem, but its value is the framework-specific content layer, not distribution or enforcement.
The markdown file that teaches an AI to stop thinking in React
At first glance, solid-rules is almost insultingly small. That is why it matters. It does not ship runtime code, and it does not add a new abstraction. It hands an agent a compact set of rules that says, in effect, stop treating Solid like React.
Aiden Bai describes it plainly in the repo itself as AGENTS.md for SolidJS. That line captures the whole premise: the file is not there to teach humans the framework from scratch, it is there to keep machine-generated code from drifting into familiar but wrong habits.
Why SolidJS is an easy framework for AI to get wrong
Solid looks close enough to React to trigger pattern matching. That is the trap. A component is a setup function, not a render loop. Signals need to be read in reactive contexts. Props are proxies, so destructuring can break reactivity. Even list rendering splits on identity versus position, which is exactly the sort of detail a model can flatten away.
That is why the repo is so compact. It is not trying to cover every Solid edge case. It focuses on the mistakes that are both common and expensive: reading a value too early, destructuring a proxy, choosing the wrong control-flow primitive, or using a memo where a simple derivation would do.
What AGENTS.md changes in practice
| Default AI instinct | Solid-rules instruction | Bug avoided |
|---|---|---|
| Destructure props because it feels idiomatic. | Read props through the proxy and keep access reactive. | Keeps updates live instead of freezing values. |
| Read a signal once in setup. | Read signals inside JSX, effects, or memos. | Prevents stale snapshots from leaking into the UI. |
| Render lists with a generic loop instinct. | Choose <For> for identity and <Index> for position. | Avoids wrong DOM reuse and needless churn. |
| Use one mental model for derived values. | Use cheap derivations for simple transforms and memos for expensive work. | Keeps reactivity lean instead of over-memoized. |
| Copy React event patterns by default. | Use Solid-native event handling and batching when it matters. | Avoids mismatched semantics and extra recomputation. |
The most useful thing here is not one rule. It is the cumulative effect. solid-rules keeps an agent from making code look right to a React-trained eye while still being wrong for Solid's runtime.
solid-rules is a translation layer, not a framework doc
That is the real insight. The repo sits between prompt and output like a compiler pass for intent. It does not invent a new syntax. It narrows the space of plausible mistakes so the model can land on the idiomatic path faster.
That also explains why the project feels bigger than the repository itself. A human can read Solid docs and still forget the details when drafting code fast. An agent needs those details stated in the exact place where it plans the next token. AGENTS.md becomes part of the workflow, not just the reference shelf.
Where it fits in the agent-rules ecosystem
Other projects solve different layers of the same problem. Tools like ai-rulesmith and rulesync help compose or sync rules files. Directories like cursor.directory help people find them. Policy engines like Agent RuleZ focus on enforcement. solid-rules lives in the content layer: expert guidance for one framework, written so an agent can absorb it before the first line of code appears.
That is why this repo is small but suggestive. It points to a future where framework correctness is partly decided by the quality of the instructions sitting next to the source tree. For subtle systems like Solid, those instructions are no longer optional decoration.
The bigger shift is not that AI needs more documentation. It is that documentation is becoming infrastructure. In a codebase with fine-grained reactivity, a good rules file is not commentary. It is a guardrail on correctness.