Working with an AI assistant

An AI assistant knows little about x4js. Left to itself, it writes code inspired by other frameworks, with methods that do not exist. x4js provides what is needed to avoid that.

Three files shipped with the package

They are installed with x4js, in node_modules/x4js/, so they always match the version you use.

File	Content
aiguide.md	The rules for writing idiomatic x4js code, and the mistakes to avoid.
aicontext.md	The compact API reference: classes, properties, exact signatures.
aicli.md	The x4js command line and the keys of x4.config.json.

Give them to your assistant before asking it to write code.

Saying it once

Rather than repeating it in every session, write it in the instruction file your assistant reads at startup, at the root of your project. Most read AGENTS.md; Claude Code reads CLAUDE.md.

This project uses x4js. Before writing or reviewing code, read:

- node_modules/x4js/aiguide.md (how to write idiomatic x4js code)
- node_modules/x4js/aicontext.md (exact API)
- node_modules/x4js/aicli.md (command line and build)

Do not invent x4js APIs.

The plugin for Claude Code

With Claude Code, a plugin does this job by itself. It contains a skill that triggers as soon as the request is about x4js, and reads the three files in your project.

claude plugin marketplace add rlibre/x4
claude plugin install x4js@rlibre

llms.txt

For an assistant that reads the web site rather than your project, x4js.org publishes an llms.txt file: a summary of the framework, the essential instructions and the links to the three files.

When the assistant gets it wrong

Before fixing, find out why. There are three possibilities:

1. the documentation was insufficient;
2. the API was ambiguous;
3. the assistant made a mistake although it had the information.

In the third case, fix the generated code. In the first two, it is the documentation or the API that is worth improving: report it on the GitHub repository.