Developing with AI
When you build features with an AI coding tool (Claude Code, Codex, Cursor, GitHub Copilot and others), the usual problem is not that it cannot write code. It is that it does not know your project's rules: how tables are named, how permission codes are written, where the tenant condition goes, which checks to run when it is done. The code looks fine, and then needs rework everywhere once you merge it.
Since version 1.7.0, Qiwu writes these rules down in files that AI tools read directly, shipped with the repository. It is an enterprise admin foundation that AI coding tools understand: you describe the feature, the AI follows the template's conventions, and when it gets something wrong a check stops it and tells it how to fix it.
This page is an introduction. The full rules and details are in the repository's Developing with AI (Chinese).
Why it works well with AI
- One set of rules, read by every tool: the conventions live in
AGENTS.mdat the repository root, and every tool's entry file points to it. You never end up with one version for Cursor and another for Claude Code that slowly drift apart. - Strict conventions, checked automatically: layering, naming, tenant conditions, data scope, action logs and i18n all have one way to write them, and most are checked by
pnpm verify. When the AI gets one wrong it is stopped right away, not in review or after release. - Generator first: standard CRUD, tree and master-detail pages are generated by the code generator, front end, back end and tests included. The AI only writes the business logic on top, so it writes less and gets less wrong.
- Errors that say how to fix them: a failed check names the file, the reason and the fix, so the AI can fix it and run the check again.
- Project map: a generated list of the modules, tables, endpoints, permission codes and more that already exist, so the AI knows what to reuse without reading the whole repository.
Files in the repository
| File | Read by | Contents |
|---|---|---|
AGENTS.md | Codex and other tools that support the AGENTS.md convention | The rules: layout and layering, naming, API, i18n, multi-tenancy and data scope, security defaults, the CRUD kit, migrations and seeds, tests and the definition of done, commands, and how to fix common check failures |
CLAUDE.md | Claude Code | A single line, @AGENTS.md, which imports the rules above |
.cursor/rules/qiwu.mdc | Cursor | A short always-on rule: read AGENTS.md first, follow the recipes, run pnpm verify before finishing |
.github/copilot-instructions.md | GitHub Copilot | The same short instructions |
.claude/skills/qiwu-*/ | Claude Code | Ten skills, one per task recipe, picked automatically for the task at hand |
docs/ai/recipes/ | People and every AI tool | Ten task recipes, see below |
docs/ai/project-map.md | People and every AI tool | The project map, generated by pnpm ai:map |
The entry files hold no rules of their own. To change a convention, change only AGENTS.md (or your project rules file below), and every tool keeps reading the same text. See the repository's which tool reads which file (Chinese).
Adding your project's own rules
AGENTS.md belongs to the template and changes with new template releases, so avoid editing it. Conventions specific to your project, such as business terms, how domains are divided, your team's coding habits and things that are not allowed, go into docs/project-rules.md.
- The template does not ship this file; you create it, so it never conflicts when you upgrade the template;
- the start of
AGENTS.mdtells the AI to check whether this file exists and, if it does, to read it first; where the two disagree, your file wins.
For example:
# Project rules
- Our domains are `crm` (customer relations) and `erp` (inventory and sales); new tables go only into these two.
- A customer is always called customer, never client.
- Store amounts in cents (integers); convert to currency units only in the UI.See the repository's adding your own rules (Chinese).
Ten task recipes
docs/ai/recipes/ covers the ten things you do most often when building features. Each recipe follows the same outline: when to use it → steps (files and commands) → done checks → common mistakes. Steps the generator can do always start with the generator. You can follow a recipe yourself or ask the AI to follow it:
| Recipe | When to use it |
|---|---|
| New business module | CRUD pages for a new table (single table, tree, master-detail), generator first |
| Tables and migrations | Create or change a table: migration names, the tenant column, soft delete, unique keys |
| Permissions and menus | New permission codes, menus, menu groups, action log verbs; granting them to roles |
| Dicts and system parameters | New dicts or parameters, written by seeds, read on the server and in the web app |
| Data scope | Filter a table by department or creator; hand-written SQL on data-scoped tables |
| Hand-written SQL and tenants | Raw SQL on tenant tables, scans across tenants |
| Queue jobs and scheduled jobs | Hand slow work to a background queue, or add a scheduled job |
| MCP tools | Let agents call your module through MCP |
| i18n strings | Chinese and English strings for the UI, validation, fields, menus and server messages |
| API tests | End-to-end tests for an endpoint: success, 403, 400, 404 and the cross-tenant 404 |
For the list with links to each recipe, see the repository's task recipes (Chinese). In Claude Code, the ten qiwu-* skills under .claude/skills/ pick the matching recipe from your description; with other tools, just tell it to follow a recipe in docs/ai/recipes/.
Project map
pnpm ai:map parses the source code statically (no database needed) and writes docs/ai/project-map.md, which lists:
- domains, modules and feature switches;
- tables;
- every API route and the permission it requires;
- permission codes, menu route names, dict codes and system parameters;
- queues, scheduled job handlers and MCP tools.
Reading this one file, the AI knows what already exists: which dict to reuse, how to name a new permission code.
Run pnpm ai:map after changing modules, tables, endpoints, permissions, menus, dicts, parameters, jobs or MCP tools. pnpm verify checks that the map matches the source and fails with a hint to regenerate it when it is stale. Regenerate it after merging a new template release too; if the file conflicts, do not resolve it by hand, just regenerate it. See the repository's upgrade guide (Chinese).
Errors that say how to fix them
When the architecture checks, the i18n check, the originality check or the license check fail, the error ends with two extra lines:
fix:what to change;see:a link to the doc that explains the rule.
A stale project map tells you to run pnpm ai:map. The AI (or you) applies the fix: and runs the check again, without guessing the rule. Lint and type checks print their tools' usual errors. The "common errors" table at the end of AGENTS.md also lists the usual failures and their fixes; see the repository's development rules (Chinese).
Do not let the AI "fix" a failure by turning the check off or adding ignore comments.
Getting started
- Open your project's repository root in your AI coding tool. The tool finds its entry file by itself; nothing else to set up.
- (Optional) Create
docs/project-rules.mdwith your project's rules. - Describe the task in plain words, for example "add a customer management page for the
crm_customertable". If the task matches one of the ten recipes, ask it to follow that recipe. - Have it run the checks before it finishes:
pnpm ai:map # after changing modules, tables, endpoints, permissions, menus, dicts, parameters, jobs or MCP tools
pnpm verify # the definition of done; must passIf it changed an endpoint, also run that endpoint's server test, for example pnpm --filter @qiwu/server test crm-customer.e2e (needs the test database, see Getting started).
You run pnpm dev yourself in a terminal; do not let the AI start a long-running dev server. The full local gate, pnpm ci:local, takes a while; you decide when to run it before merging.
A person still has to check the work
Rules, recipes and checks make the AI make fewer mistakes, but they do not replace you. Read AI-written code line by line as you would a colleague's change, and make sure the business logic, permissions and data scope are right. Run the tests and try it in the admin console before you merge and release.
How this differs from MCP agent access
This page is about development: AI helps you write code. MCP agent access is a runtime feature: a deployed system lets agents call the console's tools as a particular user. The two do not depend on each other.