Project rules are short plain-text facts about a project that every agent working through QA Vault reads before it touches a test case. A QA Engineer writes each fact once. Every session after that, for every agent and every person on the team, starts with it already in context.

It is one of the simplest features in QA Vault and one of the most useful.

What it solves

Every project has facts that shape every test, and that no agent can guess. Four of them, as rules, on the fictional ACME product we use for demos:

  1. ACME has three roles: Owner, Editor and Viewer. A Viewer can open a project but cannot edit it or invite anyone.
  2. Staging is reset every night at 02:00 UTC. Never rely on data created the day before.
  3. Card numbers from the payment sandbox must never appear in a test case title.
  4. “Member” and “seat” are different things here: a seat is paid, a member may not have one.

Without them, an agent writes test cases for a product with one kind of user, reuses yesterday’s data and leaks a sandbox card into a title. With them missing from the tool, the only fix is a person: pasting the same background into every session, then re-reading every result to check the agent did not forget it. That is exactly the kind of work that burns a QA Engineer’s attention on repetition instead of judgement.

Roles and permissions are the clearest case. A product with an Owner, an Editor and a Viewer needs its scenarios checked for each of them. Written once as a rule, that matrix reaches every agent that authors, maintains or automates a case, so the permission scenarios stop depending on someone remembering to mention them.

How a rule reaches the agent

Diagram: a rule is written once, read by every agent session first, and shapes every case the agent writes.

  • Written once. On the project’s Rules page, or by telling the agent “remember: this project has three roles”, which it saves with create_project_rule. Each rule is one fact, up to 1,000 characters, up to 50 per project, so the list stays short enough to read.
  • Read first. get_project_rules, one of the QA Vault MCP tools, hands the whole list to the agent. MCP cannot force the order an agent calls tools in, so QA Vault asks for it twice: the tool describes itself as the mandatory first step, and the server’s own instructions tell every connected client to read the rules before substantive work. The skills in the QA Vault harness, an open-source plugin for Claude Code and Codex CLI you install in one command, make it their first step.
  • Kept current. Rules are edited and deleted on the same page, and a change reaches the next session immediately. Nothing lives in a chat history that disappears when the session ends.

Rules are context, not enforcement. The agent works with the project’s facts in front of it; a QA Engineer still reviews what it produces. What changes is that the review no longer starts with “did it know about the roles?”

Project lessons work the same way for incidents that already happened: each lesson records a failure and the class of mistake to watch for, and agents read them alongside the rules.

What it frees up

The facts a project depends on move out of one person’s head and into the one place every agent reads. Nobody re-explains the project at the start of a session, nobody re-checks whether the agent was told, and a new teammate or a new agent starts from the same ground as everyone else. The QA Engineer’s attention goes back to what only a person can do: deciding what matters and approving what the agent wrote.

Where to start

  1. Write down the facts you repeat. Roles and permissions first, then environments, data constraints and vocabulary.
  2. Keep each rule to one fact. Short, atomic rules are easier to read, update and trust.
  3. Install the QA Vault harness so every skill reads the rules before it creates, maintains or automates a case.